:right-sidebar: True

ColumnView
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: ColumnView(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Scrollable`



``GtkColumnView`` presents a large dynamic list of items using multiple columns
with headers.

``GtkColumnView`` uses the factories of its columns to generate a cell widget for
each column, for each visible item and displays them together as the row for
this item.

The :obj:`~gi.repository.Gtk.ColumnView.props.show_row_separators` and
:obj:`~gi.repository.Gtk.ColumnView.props.show_column_separators` properties offer a simple way
to display separators between the rows or columns.

``GtkColumnView`` allows the user to select items according to the selection
characteristics of the model. For models that allow multiple selected items,
it is possible to turn on *rubberband selection*, using
:obj:`~gi.repository.Gtk.ColumnView.props.enable_rubberband`.

The column view supports sorting that can be customized by the user by
clicking on column headers. To set this up, the ``GtkSorter`` returned by
:obj:`~gi.repository.Gtk.ColumnView.get_sorter` must be attached to a sort model for the
data that the view is showing, and the columns must have sorters attached to
them by calling :obj:`~gi.repository.Gtk.ColumnViewColumn.set_sorter`. The initial sort
order can be set with :obj:`~gi.repository.Gtk.ColumnView.sort_by_column`.

The column view also supports interactive resizing and reordering of
columns, via Drag-and-Drop of the column headers. This can be enabled or
disabled with the :obj:`~gi.repository.Gtk.ColumnView.props.reorderable` and
:obj:`~gi.repository.Gtk.ColumnViewColumn.props.resizable` properties.

To learn more about the list widget framework, see the
`overview <section-list-widget.html>`_.

CSS nodes
---------


.. code-block::
   :dedent:

   columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table]
   ├── header
   │   ├── <column header>
   ┊   ┊
   │   ╰── <column header>
   │
   ├── listview
   │
   ┊
   ╰── [rubberband]


``GtkColumnView`` uses a single CSS node named columnview. It may carry the
.column-separators style class, when :obj:`~gi.repository.Gtk.ColumnView.props.show_column_separators`
property is set. Header widgets appear below a node with name header.
The rows are contained in a ``GtkListView`` widget, so there is a listview
node with the same structure as for a standalone ``GtkListView`` widget.
If :obj:`~gi.repository.Gtk.ColumnView.props.show_row_separators` is set, it will be passed
on to the list view, causing its CSS node to carry the .separators style class.
For rubberband selection, a node with name rubberband is used.

The main columnview node may also carry style classes to select
the style of `list presentation <section-list-widget.html#list-styles>`_:
.rich-list, .navigation-sidebar or .data-table.

Accessibility
-------------

``GtkColumnView`` uses the :const:`~gi.repository.Gtk.AccessibleRole.TREE_GRID` role, header title
widgets are using the :const:`~gi.repository.Gtk.AccessibleRole.COLUMN_HEADER` role. The row widgets
are using the :const:`~gi.repository.Gtk.AccessibleRole.ROW` role, and individual cells are using
the :const:`~gi.repository.Gtk.AccessibleRole.GRID_CELL` role



Constructors
------------

.. rst-class:: interim-class

.. class:: ColumnView
   :no-index:


   .. classmethod:: new(model: ~gi.repository.Gtk.SelectionModel | None = None) -> ~gi.repository.Gtk.Widget

      Creates a new ``GtkColumnView``.

      You most likely want to call :obj:`~gi.repository.Gtk.ColumnView.append_column`
      to add columns next.







      :param model: the list model to use









Methods
-------

.. rst-class:: interim-class

.. class:: ColumnView
   :no-index:


   .. method:: append_column(column: ~gi.repository.Gtk.ColumnViewColumn) -> None

      Appends the ``column`` to the end of the columns in ``self``.







      :param column: a ``GtkColumnViewColumn`` that hasn't been added to a
         ``GtkColumnView`` yet





   .. method:: get_columns() -> ~gi.repository.Gio.ListModel

      Gets the list of columns in this column view.

      This list is constant over the lifetime of ``self`` and can be used to
      monitor changes to the columns of ``self`` by connecting to the
      ::items-changed signal.










   .. method:: get_enable_rubberband() -> bool

      Returns whether rows can be selected by dragging with the mouse.










   .. method:: get_header_factory() -> ~gi.repository.Gtk.ListItemFactory | None

      Gets the factory that's currently used to populate section headers.



      .. versionadded:: 4.12








   .. method:: get_model() -> ~gi.repository.Gtk.SelectionModel | None

      Gets the model that's currently used to read the items displayed.










   .. method:: get_reorderable() -> bool

      Returns whether columns are reorderable.










   .. method:: get_row_factory() -> ~gi.repository.Gtk.ListItemFactory | None

      Gets the factory set via :obj:`~gi.repository.Gtk.ColumnView.set_row_factory`.



      .. versionadded:: 4.12








   .. method:: get_show_column_separators() -> bool

      Returns whether the list should show separators
      between columns.










   .. method:: get_show_row_separators() -> bool

      Returns whether the list should show separators
      between rows.










   .. method:: get_single_click_activate() -> bool

      Returns whether rows will be activated on single click and
      selected on hover.










   .. method:: get_sorter() -> ~gi.repository.Gtk.Sorter | None

      Returns a special sorter that reflects the users sorting
      choices in the column view.

      To allow users to customizable sorting by clicking on column
      headers, this sorter needs to be set on the sort model underneath
      the model that is displayed by the view.

      See :obj:`~gi.repository.Gtk.ColumnViewColumn.set_sorter` for setting up
      per-column sorting.

      Here is an example:

      .. code-block::
         :dedent:

         gtk_column_view_column_set_sorter (column, sorter);
         gtk_column_view_append_column (view, column);
         sorter = g_object_ref (gtk_column_view_get_sorter (view)));
         model = gtk_sort_list_model_new (store, sorter);
         selection = gtk_no_selection_new (model);
         gtk_column_view_set_model (view, selection);











   .. method:: get_tab_behavior() -> ~gi.repository.Gtk.ListTabBehavior

      Gets the behavior set for the :kbd:`Tab` key.



      .. versionadded:: 4.12








   .. method:: insert_column(position: int, column: ~gi.repository.Gtk.ColumnViewColumn) -> None

      Inserts a column at the given position in the columns of ``self``.

      If ``column`` is already a column of ``self``, it will be repositioned.







      :param position: the position to insert ``column`` at


      :param column: the ``GtkColumnViewColumn`` to insert





   .. method:: remove_column(column: ~gi.repository.Gtk.ColumnViewColumn) -> None

      Removes the ``column`` from the list of columns of ``self``.







      :param column: a ``GtkColumnViewColumn`` that's part of ``self``





   .. method:: scroll_to(pos: int, column: ~gi.repository.Gtk.ColumnViewColumn | None, flags: ~gi.repository.Gtk.ListScrollFlags, scroll: ~gi.repository.Gtk.ScrollInfo | None = None) -> None

      Scroll to the row at the given position - or cell if a column is
      given - and performs the actions specified in ``flags``.

      This function works no matter if the listview is shown or focused.
      If it isn't, then the changes will take effect once that happens.



      .. versionadded:: 4.12





      :param pos: position of the item


      :param column: The column to scroll to
         or :const:`None` to not scroll columns.


      :param flags: actions to perform


      :param scroll: details of how to perform
         the scroll operation or :const:`None` to scroll into view





   .. method:: set_enable_rubberband(enable_rubberband: bool) -> None

      Sets whether selections can be changed by dragging with the mouse.







      :param enable_rubberband: :const:`True` to enable rubberband selection





   .. method:: set_header_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None

      Sets the ``GtkListItemFactory`` to use for populating the
      :obj:`~gi.repository.Gtk.ListHeader` objects used in section headers.

      If this factory is set to :const:`None`, the list will not show
      section headers.



      .. versionadded:: 4.12





      :param factory: the factory to use





   .. method:: set_model(model: ~gi.repository.Gtk.SelectionModel | None = None) -> None

      Sets the model to use.

      This must be a :obj:`~gi.repository.Gtk.SelectionModel`.







      :param model: the model to use





   .. method:: set_reorderable(reorderable: bool) -> None

      Sets whether columns should be reorderable by dragging.







      :param reorderable: whether columns should be reorderable





   .. method:: set_row_factory(factory: ~gi.repository.Gtk.ListItemFactory | None = None) -> None

      Sets the factory used for configuring rows. The factory must be for configuring
      :obj:`~gi.repository.Gtk.ColumnViewRow` objects.

      If this factory is not set - which is the default - then the defaults will be used.

      This factory is not used to set the widgets displayed in the individual cells. For
      that see :obj:`~gi.repository.GtkColumnViewColumn.set_factory` and :obj:`~gi.repository.Gtk.GtkColumnViewCell`.



      .. versionadded:: 4.12





      :param factory: The row factory





   .. method:: set_show_column_separators(show_column_separators: bool) -> None

      Sets whether the list should show separators
      between columns.







      :param show_column_separators: :const:`True` to show column separators





   .. method:: set_show_row_separators(show_row_separators: bool) -> None

      Sets whether the list should show separators
      between rows.







      :param show_row_separators: :const:`True` to show row separators





   .. method:: set_single_click_activate(single_click_activate: bool) -> None

      Sets whether rows should be activated on single click and
      selected on hover.







      :param single_click_activate: :const:`True` to activate items on single click





   .. method:: set_tab_behavior(tab_behavior: ~gi.repository.Gtk.ListTabBehavior) -> None

      Sets the behavior of the :kbd:`Tab` and :kbd:`Shift`+:kbd:`Tab` keys.



      .. versionadded:: 4.12





      :param tab_behavior: The desired tab behavior





   .. method:: sort_by_column(column: ~gi.repository.Gtk.ColumnViewColumn | None, direction: ~gi.repository.Gtk.SortType) -> None

      Sets the sorting of the view.

      This function should be used to set up the initial sorting.
      At runtime, users can change the sorting of a column view
      by clicking on the list headers.

      This call only has an effect if the sorter returned by
      :obj:`~gi.repository.Gtk.ColumnView.get_sorter` is set on a sort model,
      and :obj:`~gi.repository.Gtk.ColumnViewColumn.set_sorter` has been called
      on ``column`` to associate a sorter with the column.

      If ``column`` is :const:`None`, the view will be unsorted.







      :param column: the ``GtkColumnViewColumn`` to sort by


      :param direction: the direction to sort in









Properties
----------

.. rst-class:: interim-class

.. class:: ColumnView
   :no-index:
   

   .. attribute:: props.columns
      :type: ~gi.repository.Gio.ListModel

      The list of columns.







   .. attribute:: props.enable_rubberband
      :type: bool

      Allow rubberband selection.







   .. attribute:: props.header_factory
      :type: ~gi.repository.Gtk.ListItemFactory

      Factory for creating header widgets.



      .. versionadded:: 4.12





   .. attribute:: props.model
      :type: ~gi.repository.Gtk.SelectionModel

      Model for the items displayed.







   .. attribute:: props.reorderable
      :type: bool

      Whether columns are reorderable.







   .. attribute:: props.row_factory
      :type: ~gi.repository.Gtk.ListItemFactory

      The factory used for configuring rows.



      .. versionadded:: 4.12





   .. attribute:: props.show_column_separators
      :type: bool

      Show separators between columns.







   .. attribute:: props.show_row_separators
      :type: bool

      Show separators between rows.







   .. attribute:: props.single_click_activate
      :type: bool

      Activate rows on single click and select them on hover.







   .. attribute:: props.sorter
      :type: ~gi.repository.Gtk.Sorter

      Sorter with the sorting choices of the user.







   .. attribute:: props.tab_behavior
      :type: ~gi.repository.Gtk.ListTabBehavior

      Behavior of the :kbd:`Tab` key



      .. versionadded:: 4.12









Signals
-------

.. rst-class:: interim-class

.. class:: ColumnView.signals
   :no-index:
   

   .. method:: activate(position: int) -> None

      Emitted when a row has been activated by the user, usually via activating
      the GtkListBase|list.activate-item action.

      This allows for a convenient way to handle activation in a columnview.
      See :obj:`~gi.repository.Gtk.ListItem.set_activatable` for details on how to use this
      signal.







      :param position: position of item to activate