:right-sidebar: True TreeViewColumn =================================================================== .. currentmodule:: gi.repository.Gtk .. deprecated:: 4.10 Use :obj:`~gi.repository.Gtk.ColumnView` and :obj:`~gi.repository.Gtk.ColumnViewColumn` instead of :obj:`~gi.repository.Gtk.TreeView` to show a tabular list .. class:: TreeViewColumn(title='', cell_renderer=None, **attributes) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.CellLayout` A visible column in a :obj:`~gi.repository.Gtk.TreeView` widget The ``GtkTreeViewColumn`` object represents a visible column in a ``GtkTreeView`` widget. It allows to set properties of the column header, and functions as a holding pen for the cell renderers which determine how the data in the column is displayed. Please refer to the `tree widget conceptual overview `_ for an overview of all the objects and data types related to the tree widget and how they work together, and to the :obj:`~gi.repository.Gtk.TreeView` documentation for specifics about the CSS node structure for treeviews and their headers. Constructors ------------ .. rst-class:: interim-class .. class:: TreeViewColumn :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.TreeViewColumn Creates a new ``GtkTreeViewColumn``. .. deprecated:: 4.10 Use GtkColumnView instead .. classmethod:: new_with_area(area: ~gi.repository.Gtk.CellArea) -> ~gi.repository.Gtk.TreeViewColumn Creates a new ``GtkTreeViewColumn`` using ``area`` to render its cells. .. deprecated:: 4.10 Use GtkColumnView instead :param area: the ``GtkCellArea`` that the newly created column should use to layout cells. Methods ------- .. rst-class:: interim-class .. class:: TreeViewColumn :no-index: .. method:: add_attribute(cell_renderer: ~gi.repository.Gtk.CellRenderer, attribute: str, column: int) -> None Adds an attribute mapping to the list in ``tree_column``. The ``column`` is the column of the model to get a value from, and the ``attribute`` is the parameter on ``cell_renderer`` to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a ``GtkCellRendererText`` get its values from column 2. .. deprecated:: 4.10 Use GtkColumnView instead :param cell_renderer: the ``GtkCellRenderer`` to set attributes on :param attribute: An attribute on the renderer :param column: The column position on the model to get the attribute from. .. method:: cell_get_position(cell_renderer: ~gi.repository.Gtk.CellRenderer) -> tuple[bool, int, int] Obtains the horizontal position and size of a cell in a column. If the cell is not found in the column, ``start_pos`` and ``width`` are not changed and :const:`False` is returned. .. deprecated:: 4.10 Use GtkColumnView instead :param cell_renderer: a ``GtkCellRenderer`` .. method:: cell_get_size() -> tuple[int, int, int, int] Obtains the width and height needed to render the column. This is used primarily by the ``GtkTreeView``. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: cell_is_visible() -> bool Returns :const:`True` if any of the cells packed into the ``tree_column`` are visible. For this to be meaningful, you must first initialize the cells with :func:`~gi.repository.Gtk.TreeViewColumn.cell_set_cell_data` .. deprecated:: 4.10 Use GtkColumnView instead .. method:: cell_set_cell_data(tree_model: ~gi.repository.Gtk.TreeModel, iter: ~gi.repository.Gtk.TreeIter, is_expander: bool, is_expanded: bool) -> None Sets the cell renderer based on the ``tree_model`` and ``iter``. That is, for every attribute mapping in ``tree_column``, it will get a value from the set column on the ``iter``, and use that value to set the attribute on the cell renderer. This is used primarily by the ``GtkTreeView``. .. deprecated:: 4.10 Use GtkColumnView instead :param tree_model: The ``GtkTreeModel`` to get the cell renderers attributes from. :param iter: The ``GtkTreeIter`` to get the cell renderer’s attributes from. :param is_expander: :const:`True`, if the row has children :param is_expanded: :const:`True`, if the row has visible children .. method:: clear() -> None Unsets all the mappings on all renderers on the ``tree_column``. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: clear_attributes(cell_renderer: ~gi.repository.Gtk.CellRenderer) -> None Clears all existing attributes previously set with :func:`~gi.repository.Gtk.TreeViewColumn.set_attributes`. .. deprecated:: 4.10 Use GtkColumnView instead :param cell_renderer: a ``GtkCellRenderer`` to clear the attribute mapping on. .. method:: clicked() -> None Emits the “clicked” signal on the column. This function will only work if ``tree_column`` is clickable. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: focus_cell(cell: ~gi.repository.Gtk.CellRenderer) -> None Sets the current keyboard focus to be at ``cell``, if the column contains 2 or more editable and activatable cells. .. deprecated:: 4.10 Use GtkColumnView instead :param cell: A ``GtkCellRenderer`` .. method:: get_alignment() -> float Returns the current x alignment of ``tree_column``. This value can range between 0.0 and 1.0. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_button() -> ~gi.repository.Gtk.Widget Returns the button used in the treeview column header .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_clickable() -> bool Returns :const:`True` if the user can click on the header for the column. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_expand() -> bool Returns :const:`True` if the column expands to fill available space. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_fixed_width() -> int Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use :func:`~gi.repository.Gtk.TreeViewColumn.get_width`. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_max_width() -> int Returns the maximum width in pixels of the ``tree_column``, or -1 if no maximum width is set. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_min_width() -> int Returns the minimum width in pixels of the ``tree_column``, or -1 if no minimum width is set. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_reorderable() -> bool Returns :const:`True` if the ``tree_column`` can be reordered by the user. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_resizable() -> bool Returns :const:`True` if the ``tree_column`` can be resized by the end user. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_sizing() -> ~gi.repository.Gtk.TreeViewColumnSizing Returns the current type of ``tree_column``. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_sort_column_id() -> int Gets the logical ``sort_column_id`` that the model sorts on when this column is selected for sorting. See :obj:`~gi.repository.Gtk.TreeViewColumn.set_sort_column_id`. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_sort_indicator() -> bool Gets the value set by :func:`~gi.repository.Gtk.TreeViewColumn.set_sort_indicator`. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_sort_order() -> ~gi.repository.Gtk.SortType Gets the value set by :func:`~gi.repository.Gtk.TreeViewColumn.set_sort_order`. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_spacing() -> int Returns the spacing of ``tree_column``. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_title() -> str Returns the title of the widget. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_tree_view() -> ~gi.repository.Gtk.Widget | None Returns the ``GtkTreeView`` wherein ``tree_column`` has been inserted. If ``column`` is currently not inserted in any tree view, :const:`None` is returned. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_visible() -> bool Returns :const:`True` if ``tree_column`` is visible. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_widget() -> ~gi.repository.Gtk.Widget | None Returns the ``GtkWidget`` in the button on the column header. If a custom widget has not been set then :const:`None` is returned. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_width() -> int Returns the current size of ``tree_column`` in pixels. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: get_x_offset() -> int Returns the current X offset of ``tree_column`` in pixels. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: pack_end(cell: ~gi.repository.Gtk.CellRenderer, expand: bool) -> None Adds the ``cell`` to end of the column. If ``expand`` is :const:`False`, then the ``cell`` is allocated no more space than it needs. Any unused space is divided evenly between cells for which ``expand`` is :const:`True`. .. deprecated:: 4.10 Use GtkColumnView instead :param cell: The ``GtkCellRenderer`` :param expand: :const:`True` if ``cell`` is to be given extra space allocated to ``tree_column``. .. method:: pack_start(cell: ~gi.repository.Gtk.CellRenderer, expand: bool) -> None Packs the ``cell`` into the beginning of the column. If ``expand`` is :const:`False`, then the ``cell`` is allocated no more space than it needs. Any unused space is divided evenly between cells for which ``expand`` is :const:`True`. .. deprecated:: 4.10 Use GtkColumnView instead :param cell: The ``GtkCellRenderer`` :param expand: :const:`True` if ``cell`` is to be given extra space allocated to ``tree_column``. .. method:: queue_resize() -> None Flags the column, and the cell renderers added to this column, to have their sizes renegotiated. .. deprecated:: 4.10 Use GtkColumnView instead .. method:: set_alignment(xalign: float) -> None Sets the alignment of the title or custom widget inside the column header. The alignment determines its location inside the button -- 0.0 for left, 0.5 for center, 1.0 for right. .. deprecated:: 4.10 Use GtkColumnView instead :param xalign: The alignment, which is between [0.0 and 1.0] inclusive. .. method:: set_attributes(cell_renderer, **attributes) Sets the attributes in the list as the attributes of ``tree_column``. The attributes should be in attribute/column order, as in :func:`~gi.repository.Gtk.TreeViewColumn.add_attribute`. All existing attributes are removed, and replaced with the new attributes. .. deprecated:: 4.10 Use GtkColumnView instead :param cell_renderer: the ``GtkCellRenderer`` we’re setting the attributes of :param attributes: .. method:: set_cell_data_func(cell_renderer, func, func_data=None) Sets the ``GtkTreeCellDataFunc`` to use for the column. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of ``tree_column``'s cell renderer as appropriate. ``func`` may be :const:`None` to remove an older one. .. deprecated:: 4.10 Use GtkColumnView instead :param cell_renderer: A ``GtkCellRenderer`` :param func: The ``GtkTreeCellDataFunc`` to use. :param func_data: The user data for ``func``. .. method:: set_clickable(clickable: bool) -> None Sets the header to be active if ``clickable`` is :const:`True`. When the header is active, then it can take keyboard focus, and can be clicked. .. deprecated:: 4.10 Use GtkColumnView instead :param clickable: :const:`True` if the header is active. .. method:: set_expand(expand: bool) -> None Sets the column to take available extra space. This space is shared equally amongst all columns that have the expand set to :const:`True`. If no column has this option set, then the last column gets all extra space. By default, every column is created with this :const:`False`. Along with “fixed-width”, the “expand” property changes when the column is resized by the user. .. deprecated:: 4.10 Use GtkColumnView instead :param expand: :const:`True` if the column should expand to fill available space. .. method:: set_fixed_width(fixed_width: int) -> None If ``fixed_width`` is not -1, sets the fixed width of ``tree_column``; otherwise unsets it. The effective value of ``fixed_width`` is clamped between the minimum and maximum width of the column; however, the value stored in the “fixed-width” property is not clamped. If the column sizing is :const:`~gi.repository.Gtk.TreeViewColumnSizing.GROW_ONLY` or :const:`~gi.repository.Gtk.TreeViewColumnSizing.AUTOSIZE`, setting a fixed width overrides the automatically calculated width. Note that ``fixed_width`` is only a hint to GTK; the width actually allocated to the column may be greater or less than requested. Along with “expand”, the “fixed-width” property changes when the column is resized by the user. .. deprecated:: 4.10 Use GtkColumnView instead :param fixed_width: The new fixed width, in pixels, or -1. .. method:: set_max_width(max_width: int) -> None Sets the maximum width of the ``tree_column``. If ``max_width`` is -1, then the maximum width is unset. Note, the column can actually be wider than max width if it’s the last column in a view. In this case, the column expands to fill any extra space. .. deprecated:: 4.10 Use GtkColumnView instead :param max_width: The maximum width of the column in pixels, or -1. .. method:: set_min_width(min_width: int) -> None Sets the minimum width of the ``tree_column``. If ``min_width`` is -1, then the minimum width is unset. .. deprecated:: 4.10 Use GtkColumnView instead :param min_width: The minimum width of the column in pixels, or -1. .. method:: set_reorderable(reorderable: bool) -> None If ``reorderable`` is :const:`True`, then the column can be reordered by the end user dragging the header. .. deprecated:: 4.10 Use GtkColumnView instead :param reorderable: :const:`True`, if the column can be reordered. .. method:: set_resizable(resizable: bool) -> None If ``resizable`` is :const:`True`, then the user can explicitly resize the column by grabbing the outer edge of the column button. If resizable is :const:`True` and sizing mode of the column is :const:`~gi.repository.Gtk.TreeViewColumnSizing.AUTOSIZE`, then the sizing mode is changed to :const:`~gi.repository.Gtk.TreeViewColumnSizing.GROW_ONLY`. .. deprecated:: 4.10 Use GtkColumnView instead :param resizable: :const:`True`, if the column can be resized .. method:: set_sizing(type: ~gi.repository.Gtk.TreeViewColumnSizing) -> None Sets the growth behavior of ``tree_column`` to ``type``. .. deprecated:: 4.10 Use GtkColumnView instead :param type: The ``GtkTreeViewColumn``Sizing. .. method:: set_sort_column_id(sort_column_id: int) -> None Sets the logical ``sort_column_id`` that this column sorts on when this column is selected for sorting. Doing so makes the column header clickable. .. deprecated:: 4.10 Use GtkColumnView instead :param sort_column_id: The ``sort_column_id`` of the model to sort on. .. method:: set_sort_indicator(setting: bool) -> None Call this function with a ``setting`` of :const:`True` to display an arrow in the header button indicating the column is sorted. Call :func:`~gi.repository.Gtk.TreeViewColumn.set_sort_order` to change the direction of the arrow. .. deprecated:: 4.10 Use GtkColumnView instead :param setting: :const:`True` to display an indicator that the column is sorted .. method:: set_sort_order(order: ~gi.repository.Gtk.SortType) -> None Changes the appearance of the sort indicator. This does not actually sort the model. Use :func:`~gi.repository.Gtk.TreeViewColumn.set_sort_column_id` if you want automatic sorting support. This function is primarily for custom sorting behavior, and should be used in conjunction with :func:`~gi.repository.Gtk.TreeSortable.set_sort_column_id` to do that. For custom models, the mechanism will vary. The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the sort indicator enabled to see anything when calling this function; see :func:`~gi.repository.Gtk.TreeViewColumn.set_sort_indicator`. .. deprecated:: 4.10 Use GtkColumnView instead :param order: sort order that the sort indicator should indicate .. method:: set_spacing(spacing: int) -> None Sets the spacing field of ``tree_column``, which is the number of pixels to place between cell renderers packed into it. .. deprecated:: 4.10 Use GtkColumnView instead :param spacing: distance between cell renderers in pixels. .. method:: set_title(title: str) -> None Sets the title of the ``tree_column``. If a custom widget has been set, then this value is ignored. .. deprecated:: 4.10 Use GtkColumnView instead :param title: The title of the ``tree_column``. .. method:: set_visible(visible: bool) -> None Sets the visibility of ``tree_column``. .. deprecated:: 4.10 Use GtkColumnView instead :param visible: :const:`True` if the ``tree_column`` is visible. .. method:: set_widget(widget: ~gi.repository.Gtk.Widget | None = None) -> None Sets the widget in the header to be ``widget``. If widget is :const:`None`, then the header button is set with a ``GtkLabel`` set to the title of ``tree_column``. .. deprecated:: 4.10 Use GtkColumnView instead :param widget: A child ``GtkWidget`` Properties ---------- .. rst-class:: interim-class .. class:: TreeViewColumn :no-index: .. attribute:: props.alignment :type: float .. attribute:: props.cell_area :type: ~gi.repository.Gtk.CellArea The ``GtkCellArea`` used to layout cell renderers for this column. If no area is specified when creating the tree view column with :func:`~gi.repository.Gtk.TreeViewColumn.new_with_area` a horizontally oriented ``GtkCellAreaBox`` will be used. .. attribute:: props.clickable :type: bool .. attribute:: props.expand :type: bool .. attribute:: props.fixed_width :type: int .. attribute:: props.max_width :type: int .. attribute:: props.min_width :type: int .. attribute:: props.reorderable :type: bool .. attribute:: props.resizable :type: bool .. attribute:: props.sizing :type: ~gi.repository.Gtk.TreeViewColumnSizing .. attribute:: props.sort_column_id :type: int Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header clickable. Set to -1 to make the column unsortable. .. attribute:: props.sort_indicator :type: bool .. attribute:: props.sort_order :type: ~gi.repository.Gtk.SortType .. attribute:: props.spacing :type: int .. attribute:: props.title :type: str .. attribute:: props.visible :type: bool .. attribute:: props.widget :type: ~gi.repository.Gtk.Widget .. attribute:: props.width :type: int .. attribute:: props.x_offset :type: int Signals ------- .. rst-class:: interim-class .. class:: TreeViewColumn.signals :no-index: .. method:: clicked() -> None Emitted when the column's header has been clicked.