Skip to content

Gtk.TreeViewColumn

class — extends GObject.InitiallyUnowned, Buildable, CellLayout

:::warning Deprecated since 4.10 This API is deprecated. :::

A visible column in a 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 TreeView documentation for specifics about the CSS node structure for treeviews and their headers.

Constructors

new

@classmethod
def new(cls) -> TreeViewColumn

:::warning Deprecated since 4.10 This API is deprecated. :::

Creates a new GtkTreeViewColumn.

new_with_area

@classmethod
def new_with_area(cls, area: CellArea) -> TreeViewColumn

:::warning Deprecated since 4.10 This API is deprecated. :::

Creates a new GtkTreeViewColumn using area to render its cells.

Parameters:

  • area — the GtkCellArea that the newly created column should use to layout cells.

Methods

add_attribute

def add_attribute(self, cell_renderer: CellRenderer, attribute: str, column: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

  • cell_renderer — the GtkCellRenderer to set attributes on
  • attribute — An attribute on the renderer
  • column — The column position on the model to get the attribute from.

cell_get_position

def cell_get_position(self, cell_renderer: CellRenderer) -> tuple[bool, int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

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 False is returned.

Parameters:

  • cell_renderer — a GtkCellRenderer

cell_get_size

def cell_get_size(self) -> tuple[int, int, int, int]

:::warning Deprecated since 4.10 This API is deprecated. :::

Obtains the width and height needed to render the column. This is used primarily by the GtkTreeView.

cell_is_visible

def cell_is_visible(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns 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 TreeViewColumn.cell_set_cell_data

cell_set_cell_data

def cell_set_cell_data(self, tree_model: TreeModel, iter: TreeIter, is_expander: bool, is_expanded: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

  • tree_model — The GtkTreeModel to get the cell renderers attributes from.
  • iter — The GtkTreeIter to get the cell renderer’s attributes from.
  • is_expander — True, if the row has children
  • is_expanded — True, if the row has visible children

clear

def clear(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Unsets all the mappings on all renderers on the tree_column.

clear_attributes

def clear_attributes(self, cell_renderer: CellRenderer) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Clears all existing attributes previously set with gtk_tree_view_column_set_attributes().

Parameters:

  • cell_renderer — a GtkCellRenderer to clear the attribute mapping on.

clicked

def clicked(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Emits the “clicked” signal on the column. This function will only work if tree_column is clickable.

focus_cell

def focus_cell(self, cell: CellRenderer) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the current keyboard focus to be at cell, if the column contains 2 or more editable and activatable cells.

Parameters:

  • cell — A GtkCellRenderer

get_alignment

def get_alignment(self) -> float

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the current x alignment of tree_column. This value can range between 0.0 and 1.0.

get_button

def get_button(self) -> Widget

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the button used in the treeview column header

get_clickable

def get_clickable(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns True if the user can click on the header for the column.

get_expand

def get_expand(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns True if the column expands to fill available space.

get_fixed_width

def get_fixed_width(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use TreeViewColumn.get_width.

get_max_width

def get_max_width(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the maximum width in pixels of the tree_column, or -1 if no maximum width is set.

get_min_width

def get_min_width(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the minimum width in pixels of the tree_column, or -1 if no minimum width is set.

get_reorderable

def get_reorderable(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns True if the tree_column can be reordered by the user.

get_resizable

def get_resizable(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns True if the tree_column can be resized by the end user.

get_sizing

def get_sizing(self) -> TreeViewColumnSizing

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the current type of tree_column.

get_sort_column_id

def get_sort_column_id(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the logical sort_column_id that the model sorts on when this column is selected for sorting.

See TreeViewColumn.set_sort_column_id.

get_sort_indicator

def get_sort_indicator(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the value set by TreeViewColumn.set_sort_indicator.

get_sort_order

def get_sort_order(self) -> SortType

:::warning Deprecated since 4.10 This API is deprecated. :::

Gets the value set by TreeViewColumn.set_sort_order.

get_spacing

def get_spacing(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the spacing of tree_column.

get_title

def get_title(self) -> str

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the title of the widget.

get_tree_view

def get_tree_view(self) -> Widget | None

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the GtkTreeView wherein tree_column has been inserted. If column is currently not inserted in any tree view, None is returned.

get_visible

def get_visible(self) -> bool

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns True if tree_column is visible.

get_widget

def get_widget(self) -> Widget | None

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the GtkWidget in the button on the column header.

If a custom widget has not been set then None is returned.

get_width

def get_width(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the current size of tree_column in pixels.

get_x_offset

def get_x_offset(self) -> int

:::warning Deprecated since 4.10 This API is deprecated. :::

Returns the current X offset of tree_column in pixels.

pack_end

def pack_end(self, cell: CellRenderer, expand: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Adds the cell to end of the column. If expand is False, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is True.

Parameters:

  • cell — The GtkCellRenderer
  • expand — True if cell is to be given extra space allocated to tree_column.

pack_start

def pack_start(self, cell: CellRenderer, expand: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Packs the cell into the beginning of the column. If expand is False, then the cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which expand is True.

Parameters:

  • cell — The GtkCellRenderer
  • expand — True if cell is to be given extra space allocated to tree_column.

queue_resize

def queue_resize(self) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Flags the column, and the cell renderers added to this column, to have their sizes renegotiated.

set_alignment

def set_alignment(self, xalign: float) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

  • xalign — The alignment, which is between [0.0 and 1.0] inclusive.

set_cell_data_func

def set_cell_data_func(self, cell_renderer: CellRenderer, func: TreeCellDataFunc | None = ...) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 None to remove an older one.

Parameters:

  • cell_renderer — A GtkCellRenderer
  • func — The GtkTreeCellDataFunc to use.

set_clickable

def set_clickable(self, clickable: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the header to be active if clickable is True. When the header is active, then it can take keyboard focus, and can be clicked.

Parameters:

  • clickable — True if the header is active.

set_expand

def set_expand(self, expand: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the column to take available extra space. This space is shared equally amongst all columns that have the expand set to True. If no column has this option set, then the last column gets all extra space. By default, every column is created with this False.

Along with “fixed-width”, the “expand” property changes when the column is resized by the user.

Parameters:

  • expand — True if the column should expand to fill available space.

set_fixed_width

def set_fixed_width(self, fixed_width: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 TreeViewColumnSizing.GROW_ONLY or 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.

Parameters:

  • fixed_width — The new fixed width, in pixels, or -1.

set_max_width

def set_max_width(self, max_width: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

  • max_width — The maximum width of the column in pixels, or -1.

set_min_width

def set_min_width(self, min_width: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the minimum width of the tree_column. If min_width is -1, then the minimum width is unset.

Parameters:

  • min_width — The minimum width of the column in pixels, or -1.

set_reorderable

def set_reorderable(self, reorderable: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

If reorderable is True, then the column can be reordered by the end user dragging the header.

Parameters:

  • reorderable — True, if the column can be reordered.

set_resizable

def set_resizable(self, resizable: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

If resizable is True, then the user can explicitly resize the column by grabbing the outer edge of the column button.

If resizable is True and sizing mode of the column is TreeViewColumnSizing.AUTOSIZE, then the sizing mode is changed to TreeViewColumnSizing.GROW_ONLY.

Parameters:

  • resizable — True, if the column can be resized

set_sizing

def set_sizing(self, type: TreeViewColumnSizing | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the growth behavior of tree_column to type.

Parameters:

  • type — The GtkTreeViewColumnSizing.

set_sort_column_id

def set_sort_column_id(self, sort_column_id: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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.

Parameters:

  • sort_column_id — The sort_column_id of the model to sort on.

set_sort_indicator

def set_sort_indicator(self, setting: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Call this function with a setting of True to display an arrow in the header button indicating the column is sorted. Call TreeViewColumn.set_sort_order to change the direction of the arrow.

Parameters:

  • setting — True to display an indicator that the column is sorted

set_sort_order

def set_sort_order(self, order: SortType | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Changes the appearance of the sort indicator.

This does not actually sort the model. Use 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 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 TreeViewColumn.set_sort_indicator.

Parameters:

  • order — sort order that the sort indicator should indicate

set_spacing

def set_spacing(self, spacing: int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the spacing field of tree_column, which is the number of pixels to place between cell renderers packed into it.

Parameters:

  • spacing — distance between cell renderers in pixels.

set_title

def set_title(self, title: str) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the title of the tree_column. If a custom widget has been set, then this value is ignored.

Parameters:

  • title — The title of the tree_column.

set_visible

def set_visible(self, visible: bool) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the visibility of tree_column.

Parameters:

  • visible — True if the tree_column is visible.

set_widget

def set_widget(self, widget: Widget | None = ...) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

Sets the widget in the header to be widget. If widget is None, then the header button is set with a GtkLabel set to the title of tree_column.

Parameters:

  • widget — A child GtkWidget

Properties

alignment

alignment: float  # read/write

cell_area

cell_area: CellArea  # read/write

The GtkCellArea used to layout cell renderers for this column.

If no area is specified when creating the tree view column with TreeViewColumn.new_with_area a horizontally oriented GtkCellAreaBox will be used.

clickable

clickable: bool  # read/write

expand

expand: bool  # read/write

fixed_width

fixed_width: int  # read/write

max_width

max_width: int  # read/write

min_width

min_width: int  # read/write

reorderable

reorderable: bool  # read/write

resizable

resizable: bool  # read/write

sizing

sizing: TreeViewColumnSizing | int  # read/write

sort_column_id

sort_column_id: int  # read/write

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.

sort_indicator

sort_indicator: bool  # read/write

sort_order

sort_order: SortType | int  # read/write

spacing

spacing: int  # read/write

title

title: str  # read/write

visible

visible: bool  # read/write

widget

widget: Widget  # read/write

width

width: int  # read-only

x_offset

x_offset: int  # read-only

Signals

clicked

def on_clicked(self) -> None: ...

Emitted when the column's header has been clicked.