gtk.TreeViewColumn
Prev | The gtk Class Reference | Next

## gtk.TreeViewColumn

gtk.TreeViewColumn — a visible column in a `gtk.TreeView` widget

## Synopsis

    class gtk.TreeViewColumn(gtk.Object):
        gtk.TreeViewColumn(title=None, cell_renderer=None, ...)
        def pack_start(cell, expand=True)
        def pack_end(cell, expand=True)
        def clear()
        def get_cell_renderers()
        def add_attribute(cell_renderer, attribute, column)
        def set_attributes(cell_renderer, ...)
        def set_cell_data_func(cell_renderer, func, func_data=None)
        def clear_attributes(cell_renderer)
        def set_spacing(spacing)
        def get_spacing()
        def set_visible(visible)
        def get_visible()
        def set_resizable(resizable)
        def get_resizable()
        def set_sizing(type)
        def get_sizing()
        def get_width()
        def get_fixed_width()
        def set_fixed_width(fixed_width)
        def set_min_width(min_width)
        def get_min_width()
        def set_max_width(max_width)
        def get_max_width()
        def clicked()
        def set_title(title)
        def get_title()
        def set_expand(expand)
        def get_expand()
        def set_clickable(active)
        def get_clickable()
        def set_widget(widget)
        def get_widget()
        def set_alignment(xalign)
        def get_alignment()
        def set_reorderable(reorderable)
        def get_reorderable()
        def set_sort_column_id(sort_column_id)
        def get_sort_column_id()
        def set_sort_indicator(setting)
        def get_sort_indicator()
        def set_sort_order(order)
        def get_sort_order()
        def cell_set_cell_data(tree_model, iter, is_expander, is_expanded)
        def cell_get_size(cell_area=(0,0,0,0))
        def cell_is_visible()
        def focus_cell(cell)
        def cell_get_position(cell_renderer)
        def queue_resize()
        def get_tree_view()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.TreeViewColumn

## Implemented Interfaces

`gtk.TreeViewColumn` implements `gtk.Buildable`

## gtk.TreeViewColumn Properties

gtk.Object Properties

"alignment" | Read-Write | The alignment of the column header text or widget
"clickable" | Read-Write | If `True`, the header can be clicked
"expand" | Read-Write | If `True`, the column can expand to take extra available space. Available in GTK+ 2.4 and above
"fixed-width" | Read-Write | The current fixed width of the column
"max-width" | Read-Write | The maximum allowed width of the column
"min-width" | Read-Write | The minimum allowed width of the column
"reorderable" | Read-Write | If `True`, the column can be reordered around the headers
"resizable" | Read-Write | If `True`, the user can resize the column
"sizing" | Read-Write | The resize mode of the column: `gtk.TREE_VIEW_COLUMN_GROW_ONLY`, `gtk.TREE_VIEW_COLUMN_AUTOSIZE` or `gtk.TREE_VIEW_COLUMN_FIXED`
"sort-indicator" | Read-Write | If `True`, how a sort indicator
"sort-order" | Read-Write | The sort direction the sort indicator should indicate: `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`
"spacing" | Read-Write | Space which is inserted between cells
"title" | Read-Write | The title to appear in the column header
"visible" | Read-Write | If `True`, display the column
"widget" | Read-Write | The widget to put in the column header button instead of the column title
"width" | Read | The current width of the column

## gtk.TreeViewColumn Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

"clicked" | `def callback(`treeviewcolumn`, `user_param1`, `...`)`

## Description

The `gtk.TreeViewColumn` object is a visible column in a `gtk.TreeView` widget. A `gtk.TreeViewColumn` manages the display of the header and the cells using a `gtk.CellRenderer`.

In PyGTK 2.4 `gtk.TreeViewColumn` implementes the `gtk.CellLayout` interface.

## Constructor

        gtk.TreeViewColumn(title=None, cell_renderer=None, ...)

`title` : | the header title string
`cell_renderer` : | a `gtk.CellRenderer`
`...` : | zero or more `attribute=column` pairs
Returns : | A newly created `gtk.TreeViewColumn`.

Creates a new `gtk.TreeViewColumn` with the header string specified by `title` and using the `gtk.CellRenderer` specified by `cell_renderer`. Zero or more `attribute=column` pairs may be added to specify from which tree model column to retrieve the attribute value. For example:

      column = gtk.TreeViewColumn('Column Title', cell_renderer, text=0, foreground=1)

will retrieve the 'text' attribute values for the cell renderer from column 0 in the treemodel and the 'foreground' attribute values from column 1. See the `add_attribute`() method for more detail.

## Methods

### gtk.TreeViewColumn.pack_start

        def pack_start(cell, expand=True)

`cell` : | a `gtk.CellRenderer`.
`expand` : | if `True` `cell` is to be given the extra space allocated to the cell box.

The `pack_start`() method packs the `gtk.CellRenderer` specified by `cell` into the beginning column. If `expand` is `True`, then the `cell` is allocated a share of all available space that the column is allocated. Note `expand` defaults to `True` in PyGTK 2.4.

### gtk.TreeViewColumn.pack_end

        def pack_end(cell, expand=True)

`cell` : | a `gtk.CellRenderer`.
`expand` : | if `True` `cell` is to be given the extra space allocated to the cell box.

The `pack_end`() method packs the `gtk.CellRenderer` specified by `cell` into the column. If `expand` is `True`, then the `cell` is allocated a share of all available space that the column is allocated. Note `expand` defaults to `True` in PyGTK 2.4.

### gtk.TreeViewColumn.clear

        def clear()

The `clear`() method unsets all the mappings on all renderers on the column.

### gtk.TreeViewColumn.get_cell_renderers

        def get_cell_renderers()

Returns : | a list of `gtk.CellRenderer` objects

The `get_cell_renderers`() method returns a list containing all the cell renderers in the column, in no particular order.

### gtk.TreeViewColumn.add_attribute

        def add_attribute(cell_renderer, attribute, column)

`cell_renderer` : | the `gtk.CellRenderer` to set attributes on
`attribute` : | an attribute on the renderer
`column` : | the column position on the model to get the attribute from.

The `add_attribute`() method adds an attribute mapping to the list in the tree column. The `column` is the column of the tree 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 `gtk.CellRendererText` get its values from column 2.

### gtk.TreeViewColumn.set_attributes

        def set_attributes(cell_renderer, ...)

`cell_renderer` : | the `gtk.CellRenderer` we're setting the attributes of
`...` : | zero or more `attribute=column` pairs

The `set_attributes`() method sets the attribute locations of the `gtk.CellRenderer` specified by `cell_renderer` using the `attribute=column` pairs (e.g. text=0, foreground=1). See the `add_attribute`() method for more detail. All existing cell attributes are removed, and replaced with the new attributes.

### gtk.TreeViewColumn.set_cell_data_func

        def set_cell_data_func(cell_renderer, func, func_data=None)

`cell_renderer` : | a `gtk.CellRenderer`
`func` : | the function or method to use.
`func_data` : | the user data to pass when calling `func`.

The `set_cell_data_func`() method sets the data function (or method) to use for the column `gtk.CellRenderer` specified by `cell_renderer`. This function (or method) is used instead of the standard attribute mappings for setting the column values, and should set the attributes of the cell renderer as appropriate. `func` may be `None` to remove the current data function. The signature of `func` is:

        def celldatafunction(column, cell, model, iter, user_data)

        def celldatamethod(self, column, cell, model, iter, user_data)

where `column` is the `gtk.TreeViewColumn` in the treeview, `cell` is the `gtk.CellRenderer` for `column`, `model` is the `gtk.TreeModel` for the treeview and `iter` is the `gtk.TreeIter` pointing at the row.

### gtk.TreeViewColumn.clear_attributes

        def clear_attributes(cell_renderer)

`cell_renderer` : | a `gtk.CellRenderer` to clear the attribute mapping on.

The `clear_attributes`() method clears all existing attributes previously set with the `set_attributes`() method.

### gtk.TreeViewColumn.set_spacing

        def set_spacing(spacing)

`spacing` : | the distance between cell renderers in pixels.

The `set_spacing`() method sets the spacing field of the treeview column, which is the number of pixels to place between cell renderers packed into it.

### gtk.TreeViewColumn.get_spacing

        def get_spacing()

Returns : | the spacing of the treeview column.

The `get_spacing`() method returns the spacing of the treeview column.

### gtk.TreeViewColumn.set_visible

        def set_visible(visible)

`visible` : | if `True` the treeview column is visible.

The `set_visible`() method sets the "visible" property to the value of `visible`. If `visible` is `True` the treeview column is visible

### gtk.TreeViewColumn.get_visible

        def get_visible()

Returns : | `True` if the column is visible

The `get_visible`() method returns the value of the "visible" property. If "visible" is `True` the treeview column is visible.

### gtk.TreeViewColumn.set_resizable

        def set_resizable(resizable)

`resizable` : | if `True`, the column can be resized

The `set_resizable`() method sets the "resizable" property to the value of `resizable`. If `resizable` is `True` the user can explicitly resize the column by grabbing the outer edge of the column button. If `resizable` is `True` and the sizing mode of the column is `gtk.TREE_VIEW_COLUMN_AUTOSIZE`, the sizing mode is changed to `gtk.TREE_VIEW_COLUMN_GROW_ONLY`.

### gtk.TreeViewColumn.get_resizable

        def get_resizable()

Returns : | `True`, if the treeview column can be resized.

The `get_resizable`() method returns the value of the "resizable" property. If "resizable" is `True`, the treeview column can be resized by the user.

### gtk.TreeViewColumn.set_sizing

        def set_sizing(type)

`type` : | The treeview column sizing: `gtk.TREE_VIEW_COLUMN_GROW_ONLY`, `gtk.TREE_VIEW_COLUMN_AUTOSIZE` or `gtk.TREE_VIEW_COLUMN_FIXED`.

The `set_sizing`() method sets the "sizing" property to the value of `type`. The value of type must be one of the GTK TreeViewColumn Sizing Constants.

### gtk.TreeViewColumn.get_sizing

        def get_sizing()

Returns : | the treeview column sizing type.

The `get_sizing`() method returns the value of the "sizing" property that contains the current type of the treeview column sizing mode. See the `set_sizing`() method for more detail.

### gtk.TreeViewColumn.get_width

        def get_width()

Returns : | the current width of the treeview column.

The `get_width`() method returns the value of the "width" property that contains the current size of the treeview column in pixels.

### gtk.TreeViewColumn.get_fixed_width

        def get_fixed_width()

Returns : | the fixed width of the treeview column

The `get_fixed_width`() method returns the value of the "fixed-width" property that contains the fixed width of the treeview column i.e. the width of the treeview column only if the sizing type is `gtk.TREE_VIEW_COLUMN_FIXED`.

### gtk.TreeViewColumn.set_fixed_width

        def set_fixed_width(fixed_width)

`fixed_width` : | the size to set the treeview column to. Must be greater than 0.

The `set_fixed_width`() method sets the "fixed-width" property to the value of `fixed_width`. The value of `fixed_width` is the size of the column in pixels. This is meaningful only if the sizing type is `gtk.TREE_VIEW_COLUMN_FIXED`. The size of the column is clamped to the min and max width for the column. Please note that the min and max width of the column doesn't actually affect the "fixed_width" property of the widget, just the actual size when displayed.

### gtk.TreeViewColumn.set_min_width

        def set_min_width(min_width)

`min_width` : | the minimum width of the treeview column in pixels, or -1.

The `set_min_width`() method sets the "min-width" property to the value of `min_width`. The value of `min_width` is the minimum width of the treeview column. If `min_width` is -1, then the minimum width is unset.

### gtk.TreeViewColumn.get_min_width

        def get_min_width()

Returns : | the minimum width of the treeview column.

The `get_min_width`() method returns the value of the "min-width" property that contains the minimum width in pixels of the treeview column, or -1 if no minimum width is set.

### gtk.TreeViewColumn.set_max_width

        def set_max_width(max_width)

`max_width` : | the maximum width of the column in pixels, or -1.

The `set_max_width`() method sets the "max-width" property to the value of `max_width`. The value of `max_width` becomes the maximum width of the treeview 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.

### gtk.TreeViewColumn.get_max_width

        def get_max_width()

Returns : | the maximum width of the treeview column.

The `get_max_width`() method returns the value of the "max-width" property that contains the maximum width in pixels of the treeview column, or -1 if no maximum width is set.

### gtk.TreeViewColumn.clicked

        def clicked()

The `clicked`() method emits the "clicked" signal on the treeview column. The treeview column must be clickable.

### gtk.TreeViewColumn.set_title

        def set_title(title)

`title` : | the title string of the treeview column.

The `set_title`() method sets the "title" property to the value of `title`. The "title" property contains the string that is used to set the treeview column title. If a custom widget has been set (see the `set_widget`() method), this value is ignored.

### gtk.TreeViewColumn.get_title

        def get_title()

Returns : | the title of the column.

The `get_title`() method returns the value of the "title" property that contains the treeview column title.

### gtk.TreeViewColumn.set_expand

        def set_expand(expand)

`expand` : | if `True` the column expands to take extra space if available.

### Note

This method is available in PyGTK 2.4 and above.

The `set_expand`() method sets the "expand" property to the value of `expand`. If expand is `True` the column expands to take available extra space. This space is shared equally among all columns that have their "expand" property 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`.

### gtk.TreeViewColumn.get_expand

        def get_expand()

Returns : | `True`, if the column expands

### Note

This method is available in PyGTK 2.4 and above.

The `get_expand`() method returns the value of the "expand" property. If "expand is `True` if the column expands to take any available space.

### gtk.TreeViewColumn.set_clickable

        def set_clickable(active)

`active` : | if `True` the treeview column header can be clicked

The `set_clickable`() method sets the "clickable" property to the value of `active`. If `active` is `True` the header can take keyboard focus, and be clicked.

### gtk.TreeViewColumn.get_clickable

        def get_clickable()

Returns : | `True` if the user can click the column header.

The `get_clickable`() method returns the value of the "clickable" property. If "clickable" is `True` the user can click on the header for the treeview column.

### gtk.TreeViewColumn.set_widget

        def set_widget(widget)

`widget` : | a child `gtk.Widget`.

The `set_widget`() method sets the widget in the header to be `widget`.

### gtk.TreeViewColumn.get_widget

        def get_widget()

Returns : | the `gtk.Widget` in the column header, or `None`

The `get_widget`() method returns the `gtk.Widget` in the button on the column header. If a custom widget has not been set using the `set_widget`() method `None` is returned.

### gtk.TreeViewColumn.set_alignment

        def set_alignment(xalign)

`xalign` : | the horizontal alignment, in the range 0.0 to 1.0 inclusive.

The `set_alignment`() method sets the "alignment" property to the value of `xalign`. `xalign` specifies the alignment of the title or custom widget inside the column header. The alignment value specifies the fraction of free space to the left of the widget.

### gtk.TreeViewColumn.get_alignment

        def get_alignment()

Returns : | the current alignment of the treeview column.

The `get_alignment`() method returns the value of the "alignment" property that contains the current horizontal alignment of the treeview column. See the `set_alignment`() method for more detail.

### gtk.TreeViewColumn.set_reorderable

        def set_reorderable(reorderable)

`reorderable` : | if `True`, the column can be reordered.

The `set_reorderable`() method sets the "reorderable" property to the value of `reorderable`. If `reorderable` is `True`, the column can be reordered by the end user dragging the header.

### gtk.TreeViewColumn.get_reorderable

        def get_reorderable()

Returns : | `True` if the treeview column can be reordered by the user.

The `get_reorderable`() method returns the value of the "reorderable" property. If "reorderable" is `True` the treeview column can be reordered by the user.

### gtk.TreeViewColumn.set_sort_column_id

        def set_sort_column_id(sort_column_id)

`sort_column_id` : | the logical column ID of the model to sort on or -1.

The `set_sort_column_id`() method is a convenience method that sets the column's sort column ID to the value specified by `sort_column_id` (an integer value). The treeview model sorts on the `sort_column_id` when this treeview column is selected for sorting. This method also makes the treeview column header clickable. If `sort_column_id` is -1 sorting using the treeview column is disabled.

This method sets up a number of callbacks that manage the sorting of the tree model when the column header is clicked. These callbacks provide toggling of the sort order, enabling the sort indicator and so on.

### gtk.TreeViewColumn.get_sort_column_id

        def get_sort_column_id()

Returns : | the current column ID for this column, or -1 if this column can't be used for sorting.

The `get_sort_column_id`() method returns the logical column ID that the model sorts on when this column is selected for sorting. See the `set_sort_column_id`() method.

### gtk.TreeViewColumn.set_sort_indicator

        def set_sort_indicator(setting)

`setting` : | if `True` display an indicator that the column is sorted

The `set_sort_indicator`() method sets the "sort-indicator" property to the value of `setting`. If `setting` is `True` an arrow is displayed in the header button when the column is sorted. Call the `set_sort_order`() to change the direction of the arrow.

### Note

If the `set_sort_column_id`() convenience method has been called the visibility of the sort indicator will be managed automatically. See the `set_sort_order`() method for more information.

### gtk.TreeViewColumn.get_sort_indicator

        def get_sort_indicator()

Returns : | `True` if the sort indicator arrow is displayed

The `get_sort_indicator`() method returns the value of the "sort-indicator" property. If "sort-indicator" is `True` an arrow is displayed in the header button when the column is sorted.

### gtk.TreeViewColumn.set_sort_order

        def set_sort_order(order)

`order` : | the sort order that the sort indicator should indicate

The `set_sort_order`() method set the "sort-order" property to the value of order. The value of order must be either: `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`. This method changes the appearance of the sort indicator.

### Note

This method does not actually sort the model. Use the `set_sort_column_id`() method if you want automatic sorting support. This method is primarily for custom sorting behavior, and should be used in conjunction with the `set_sort_column_id`() method to do that. For custom models, the mechanism will vary.

The sort indicator changes direction to indicate normal sort or reverse sort. Of course, you must have the sort indicator enabled to see anything when calling this method; see the `set_sort_indicator`() method.

### gtk.TreeViewColumn.get_sort_order

        def get_sort_order()

Returns : | the sort order the sort indicator is indicating

The `get_sort_order`() method returns the value of the "sort-order" property that indicates in which direction the treeview column is sorted. See the `set_sort_order`() method for more detail.

### gtk.TreeViewColumn.cell_set_cell_data

        def cell_set_cell_data(tree_model, iter, is_expander, is_expanded)

`tree_model` : | the `gtk.TreeModel` to get the cell renderer's attributes from.
`iter` : | the `gtk.TreeIter` to get the cell renderer's attributes from.
`is_expander` : | if `True`, the row has children
`is_expanded` : | if `True`, the row has visible children

The `cell_set_cell_data`() method sets the cell renderer attributes based on the specified `tree_model` and `iter`. That is, for every attribute mapping in the treeview column, it will get a value from the set column in the `iter`, and use that value to set the attribute on the cell renderer. If `is_expander` is `True` the tree model row has children that may or may not be displayed. If `is_expanded` is `True` the tree model row has children that are displayed.

### gtk.TreeViewColumn.cell_get_size

        def cell_get_size(cell_area=(0,0,0,0))

`cell_area` : | an optional 4-tuple or 4-list or `gtk.gdk.Rectangle` specifying the area allocated for a cell in the column
Returns : | a tuple containing five values: a `gtk.gdk.Rectangle` holding the area a cell in the column will be allocated; the x offset of the cell; the y offset of the cell; the cell width; and, the cell height

The `cell_get_size`() method returns a tuple containing:

- a `gtk.gdk.Rectangle` holding the area a cell in the treeview column will be allocated.
- the x offset of the cell relative to `cell_area`.
- the y offset of the cell relative to `cell_area`.
- the width of the cell.
- the height of the cell.

This method is used primarily by the `gtk.TreeView`.

### gtk.TreeViewColumn.cell_is_visible

        def cell_is_visible()

Returns : | `True`, if any of the cells packed into the treeview column are currently visible

The `cell_is_visible`() method returns `True` if any of the cells packed into the treeview column are visible. For this to be meaningful, you must first initialize the cells with the `cell_set_cell_data`() method.

### gtk.TreeViewColumn.focus_cell

        def focus_cell(cell)

`cell` : | a `gtk.CellRenderer`

### Note

This method is available in PyGTK 2.2 and above.

The `focus_cell`() method sets the current keyboard focus to be at `cell`, if the column contains 2 or more editable and activatable cells.

### gtk.TreeViewColumn.cell_get_position

        def cell_get_position(cell_renderer)

`cell_renderer` : | a `gtk.CellRenderer`
Returns : | a 2-tuple containing the horizontal position and size of a cell or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `cell_get_position`() method returns the horizontal position and size of the cell specified by `cell_renderer`. If the cell is not found in the column, `None` is returned.

### gtk.TreeViewColumn.queue_resize

        def queue_resize()

### Note

This method is available in PyGTK 2.8 and above.

The `queue_resize`() method flags the column, and the cell renderers added to this column, to have their sizes renegotiated.

### gtk.TreeViewColumn.get_tree_view

        def get_tree_view()

Returns : | The tree view wherein column has been inserted if any, `None`otherwise.

### Note

This method is available in PyGTK 2.12 and above.

The `get_tree_view`() method returns the `gtk.TreeView` wherein tree_column has been inserted. If column is currently not inserted in any tree view, `None` is returned.

## Signals

### The "clicked" gtk.TreeViewColumn Signal

        def callback(treeviewcolumn, user_param1, ...)

`treeviewcolumn` : | the treeviewcolumn that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "clicked" signal is emitted when the user clicks on the `treeviewcolumn` header button.

Prev | Up | Next
gtk.TreeView | Home | gtk.UIManager