class Gtk::ColumnView

Overview

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 [property@Gtk.ColumnView:show-row-separators] and [property@Gtk.ColumnView: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 [property@Gtk.ColumnView: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 Gtk::ColumnView#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 Gtk::ColumnViewColumn#sorter=. The initial sort order can be set with 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 Gtk::ColumnView#reorderable and Gtk::ColumnViewColumn#resizable properties.

To learn more about the list widget framework, see the overview.

CSS nodes

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 [property@Gtk.ColumnView: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 [property@Gtk.ColumnView: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: .rich-list, .navigation-sidebar or .data-table.

Accessibility

GtkColumnView uses the %GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title widgets are using the %GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets are using the %GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using the %GTK_ACCESSIBLE_ROLE_GRID_CELL role

Included Modules

Defined in:

auto/gtk-4.0/column_view.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from module Gtk::Scrollable

border : Gtk::Border border, hadjustment : Gtk::Adjustment? hadjustment, hadjustment=(hadjustment : Gtk::Adjustment?) : Nil hadjustment=, hscroll_policy : Gtk::ScrollablePolicy hscroll_policy, hscroll_policy=(policy : Gtk::ScrollablePolicy) : Nil hscroll_policy=, to_unsafe to_unsafe, vadjustment : Gtk::Adjustment? vadjustment, vadjustment=(vadjustment : Gtk::Adjustment?) : Nil vadjustment=, vscroll_policy : Gtk::ScrollablePolicy vscroll_policy, vscroll_policy=(policy : Gtk::ScrollablePolicy) : Nil vscroll_policy=

Instance methods inherited from module Gtk::ConstraintTarget

to_unsafe to_unsafe

Instance methods inherited from module Gtk::Buildable

buildable_id : String? buildable_id, to_unsafe to_unsafe

Instance methods inherited from module Gtk::Accessible

accessible_role : Gtk::AccessibleRole accessible_role, accessible_role=(value : Gtk::AccessibleRole) : Gtk::AccessibleRole accessible_role=, reset_property(property : Gtk::AccessibleProperty) : Nil reset_property, reset_relation(relation : Gtk::AccessibleRelation) : Nil reset_relation, reset_state(state : Gtk::AccessibleState) : Nil reset_state, to_unsafe to_unsafe, update_property(properties : Enumerable(Gtk::AccessibleProperty), values : Enumerable(_)) : Nil update_property, update_relation(relations : Enumerable(Gtk::AccessibleRelation), values : Enumerable(_)) : Nil update_relation, update_state(states : Enumerable(Gtk::AccessibleState), values : Enumerable(_)) : Nil update_state

Instance methods inherited from class Gtk::Widget

action_set_enabled(action_name : String, enabled : Bool) : Nil action_set_enabled, activate : Bool activate, activate_action(name : String, args : _?) : Bool activate_action, activate_default : Nil activate_default, add_controller(controller : Gtk::EventController) : Nil add_controller, add_css_class(css_class : String) : Nil add_css_class, add_mnemonic_label(label : Gtk::Widget) : Nil add_mnemonic_label, add_tick_callback(callback : Gtk::TickCallback) : UInt32 add_tick_callback, allocate(width : Int32, height : Int32, baseline : Int32, transform : Gsk::Transform?) : Nil allocate, allocated_baseline : Int32 allocated_baseline, allocated_height : Int32 allocated_height, allocated_width : Int32 allocated_width, allocation : Gdk::Rectangle allocation, ancestor(widget_type : UInt64) : Gtk::Widget? ancestor, can_focus : Bool can_focus, can_focus=(can_focus : Bool) : Nil can_focus=, can_focus? : Bool can_focus?, can_target : Bool can_target, can_target=(can_target : Bool) : Nil can_target=, can_target? : Bool can_target?, child_focus(direction : Gtk::DirectionType) : Bool child_focus, child_visible : Bool child_visible, child_visible=(child_visible : Bool) : Nil child_visible=, clipboard : Gdk::Clipboard clipboard, compute_bounds(target : Gtk::Widget) : Graphene::Rect compute_bounds, compute_expand(orientation : Gtk::Orientation) : Bool compute_expand, compute_point(target : Gtk::Widget, point : Graphene::Point) : Graphene::Point compute_point, compute_transform(target : Gtk::Widget) : Graphene::Matrix compute_transform, contains(x : Float64, y : Float64) : Bool contains, create_pango_context : Pango::Context create_pango_context, create_pango_layout(text : String?) : Pango::Layout create_pango_layout, css_classes : Enumerable(String) css_classes, css_classes=(classes : Enumerable(String)) : Nil css_classes=, css_name : String css_name, css_name=(value : String) : String css_name=, cursor : Gdk::Cursor? cursor, cursor=(cursor : Gdk::Cursor?) : Nil cursor=, cursor_from_name=(name : String?) : Nil cursor_from_name=, destroy_signal destroy_signal, direction : Gtk::TextDirection direction, direction=(dir : Gtk::TextDirection) : Nil direction=, direction_changed_signal direction_changed_signal, display : Gdk::Display display, drag_check_threshold(start_x : Int32, start_y : Int32, current_x : Int32, current_y : Int32) : Bool drag_check_threshold, error_bell : Nil error_bell, first_child : Gtk::Widget? first_child, focus_child : Gtk::Widget? focus_child, focus_child=(child : Gtk::Widget?) : Nil focus_child=, focus_on_click : Bool focus_on_click, focus_on_click=(focus_on_click : Bool) : Nil focus_on_click=, focus_on_click? : Bool focus_on_click?, focusable : Bool focusable, focusable=(focusable : Bool) : Nil focusable=, focusable? : Bool focusable?, font_map : Pango::FontMap? font_map, font_map=(font_map : Pango::FontMap?) : Nil font_map=, font_options : Cairo::FontOptions? font_options, font_options=(options : Cairo::FontOptions?) : Nil font_options=, frame_clock : Gdk::FrameClock? frame_clock, grab_focus : Bool grab_focus, halign : Gtk::Align halign, halign=(align : Gtk::Align) : Nil halign=, has_css_class(css_class : String) : Bool has_css_class, has_default : Bool has_default, has_default? : Bool has_default?, has_focus : Bool has_focus, has_focus? : Bool has_focus?, has_tooltip : Bool has_tooltip, has_tooltip=(has_tooltip : Bool) : Nil has_tooltip=, has_tooltip? : Bool has_tooltip?, has_visible_focus : Bool has_visible_focus, height : Int32 height, height_request : Int32 height_request, height_request=(value : Int32) : Int32 height_request=, hexpand : Bool hexpand, hexpand=(expand : Bool) : Nil hexpand=, hexpand? : Bool hexpand?, hexpand_set : Bool hexpand_set, hexpand_set=(set : Bool) : Nil hexpand_set=, hexpand_set? : Bool hexpand_set?, hide : Nil hide, hide_signal hide_signal, in_destruction : Bool in_destruction, init_template : Nil init_template, insert_action_group(name : String, group : Gio::ActionGroup?) : Nil insert_action_group, insert_after(parent : Gtk::Widget, previous_sibling : Gtk::Widget?) : Nil insert_after, insert_before(parent : Gtk::Widget, next_sibling : Gtk::Widget?) : Nil insert_before, is_ancestor(ancestor : Gtk::Widget) : Bool is_ancestor, is_drawable : Bool is_drawable, is_focus : Bool is_focus, is_sensitive : Bool is_sensitive, is_visible : Bool is_visible, keynav_failed(direction : Gtk::DirectionType) : Bool keynav_failed, keynav_failed_signal keynav_failed_signal, last_child : Gtk::Widget? last_child, layout_manager : Gtk::LayoutManager? layout_manager, layout_manager=(layout_manager : Gtk::LayoutManager?) : Nil layout_manager=, list_mnemonic_labels : GLib::List list_mnemonic_labels, map : Nil map, map_signal map_signal, mapped : Bool mapped, margin_bottom : Int32 margin_bottom, margin_bottom=(margin : Int32) : Nil margin_bottom=, margin_end : Int32 margin_end, margin_end=(margin : Int32) : Nil margin_end=, margin_start : Int32 margin_start, margin_start=(margin : Int32) : Nil margin_start=, margin_top : Int32 margin_top, margin_top=(margin : Int32) : Nil margin_top=, measure(orientation : Gtk::Orientation, for_size : Int32) : Nil measure, mnemonic_activate(group_cycling : Bool) : Bool mnemonic_activate, mnemonic_activate_signal mnemonic_activate_signal, move_focus_signal move_focus_signal, name : String name, name=(name : String) : Nil name=, native : Gtk::Native? native, next_sibling : Gtk::Widget? next_sibling, observe_children : Gio::ListModel observe_children, observe_controllers : Gio::ListModel observe_controllers, opacity : Float64 opacity, opacity=(opacity : Float64) : Nil opacity=, overflow : Gtk::Overflow overflow, overflow=(overflow : Gtk::Overflow) : Nil overflow=, pango_context : Pango::Context pango_context, parent : Gtk::Widget? parent, parent=(parent : Gtk::Widget) : Nil parent=, pick(x : Float64, y : Float64, flags : Gtk::PickFlags) : Gtk::Widget? pick, preferred_size : Gtk::Requisition preferred_size, prev_sibling : Gtk::Widget? prev_sibling, primary_clipboard : Gdk::Clipboard primary_clipboard, query_tooltip_signal query_tooltip_signal, queue_allocate : Nil queue_allocate, queue_draw : Nil queue_draw, queue_resize : Nil queue_resize, realize : Nil realize, realize_signal realize_signal, realized : Bool realized, receives_default : Bool receives_default, receives_default=(receives_default : Bool) : Nil receives_default=, receives_default? : Bool receives_default?, remove_controller(controller : Gtk::EventController) : Nil remove_controller, remove_css_class(css_class : String) : Nil remove_css_class, remove_mnemonic_label(label : Gtk::Widget) : Nil remove_mnemonic_label, remove_tick_callback(id : UInt32) : Nil remove_tick_callback, request_mode : Gtk::SizeRequestMode request_mode, root : Gtk::Root? root, scale_factor : Int32 scale_factor, sensitive : Bool sensitive, sensitive=(sensitive : Bool) : Nil sensitive=, sensitive? : Bool sensitive?, set_size_request(width : Int32, height : Int32) : Nil set_size_request, set_state_flags(flags : Gtk::StateFlags, clear : Bool) : Nil set_state_flags, settings : Gtk::Settings settings, should_layout : Bool should_layout, show : Nil show, show_signal show_signal, size(orientation : Gtk::Orientation) : Int32 size, size_allocate(allocation : Gdk::Rectangle, baseline : Int32) : Nil size_allocate, size_request : Nil size_request, snapshot_child(child : Gtk::Widget, snapshot : Gtk::Snapshot) : Nil snapshot_child, state_flags : Gtk::StateFlags state_flags, state_flags_changed_signal state_flags_changed_signal, style_context : Gtk::StyleContext style_context, template_child(widget_type : UInt64, name : String) : GObject::Object template_child, tooltip_markup : String? tooltip_markup, tooltip_markup=(value : String) : String
tooltip_markup=(markup : String?) : Nil
tooltip_markup=
, tooltip_text : String? tooltip_text, tooltip_text=(value : String) : String
tooltip_text=(text : String?) : Nil
tooltip_text=
, translate_coordinates(dest_widget : Gtk::Widget, src_x : Float64, src_y : Float64) : Bool translate_coordinates, trigger_tooltip_query : Nil trigger_tooltip_query, unmap : Nil unmap, unmap_signal unmap_signal, unparent : Nil unparent, unrealize : Nil unrealize, unrealize_signal unrealize_signal, unset_state_flags(flags : Gtk::StateFlags) : Nil unset_state_flags, valign : Gtk::Align valign, valign=(align : Gtk::Align) : Nil valign=, vexpand : Bool vexpand, vexpand=(expand : Bool) : Nil vexpand=, vexpand? : Bool vexpand?, vexpand_set : Bool vexpand_set, vexpand_set=(set : Bool) : Nil vexpand_set=, vexpand_set? : Bool vexpand_set?, visible : Bool visible, visible=(visible : Bool) : Nil visible=, visible? : Bool visible?, width : Int32 width, width_request : Int32 width_request, width_request=(value : Int32) : Int32 width_request=

Constructor methods inherited from class Gtk::Widget

new
new(*, accessible_role : Gtk::AccessibleRole? = nil, can_focus : Bool? = nil, can_target : Bool? = nil, css_classes : Enumerable(String)? = nil, css_name : String? = nil, cursor : Gdk::Cursor? = nil, focus_on_click : Bool? = nil, focusable : Bool? = nil, halign : Gtk::Align? = nil, has_default : Bool? = nil, has_focus : Bool? = nil, has_tooltip : Bool? = nil, height_request : Int32? = nil, hexpand : Bool? = nil, hexpand_set : Bool? = nil, layout_manager : Gtk::LayoutManager? = nil, margin_bottom : Int32? = nil, margin_end : Int32? = nil, margin_start : Int32? = nil, margin_top : Int32? = nil, name : String? = nil, opacity : Float64? = nil, overflow : Gtk::Overflow? = nil, parent : Gtk::Widget? = nil, receives_default : Bool? = nil, root : Gtk::Root? = nil, scale_factor : Int32? = nil, sensitive : Bool? = nil, tooltip_markup : String? = nil, tooltip_text : String? = nil, valign : Gtk::Align? = nil, vexpand : Bool? = nil, vexpand_set : Bool? = nil, visible : Bool? = nil, width_request : Int32? = nil)
new

Class methods inherited from class Gtk::Widget

default_direction : Gtk::TextDirection default_direction, default_direction=(dir : Gtk::TextDirection) : Nil default_direction=, g_type : UInt64 g_type

Instance methods inherited from module Gtk::ConstraintTarget

to_unsafe to_unsafe

Instance methods inherited from module Gtk::Buildable

buildable_id : String? buildable_id, to_unsafe to_unsafe

Instance methods inherited from module Gtk::Accessible

accessible_role : Gtk::AccessibleRole accessible_role, accessible_role=(value : Gtk::AccessibleRole) : Gtk::AccessibleRole accessible_role=, reset_property(property : Gtk::AccessibleProperty) : Nil reset_property, reset_relation(relation : Gtk::AccessibleRelation) : Nil reset_relation, reset_state(state : Gtk::AccessibleState) : Nil reset_state, to_unsafe to_unsafe, update_property(properties : Enumerable(Gtk::AccessibleProperty), values : Enumerable(_)) : Nil update_property, update_relation(relations : Enumerable(Gtk::AccessibleRelation), values : Enumerable(_)) : Nil update_relation, update_state(states : Enumerable(Gtk::AccessibleState), values : Enumerable(_)) : Nil update_state

Constructor methods inherited from class GObject::InitiallyUnowned

new new

Class methods inherited from class GObject::InitiallyUnowned

g_type : UInt64 g_type

Instance methods inherited from class GObject::Object

bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void)? data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void)? qdata, ref_count ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void)?) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void)? steal_data, steal_qdata(quark : UInt32) : Pointer(Void)? steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, cast?(obj : GObject::Object) : self? cast?, new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

compat_control(what : UInt64, data : Pointer(Void)?) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new(model : Gtk::SelectionModel?) #

Creates a new GtkColumnView.

You most likely want to call Gtk::ColumnView#append_column to add columns next.


def self.new #

Initialize a new ColumnView.


def self.new(*, accessible_role : Gtk::AccessibleRole? = nil, can_focus : Bool? = nil, can_target : Bool? = nil, columns : Gio::ListModel? = nil, css_classes : Enumerable(String)? = nil, css_name : String? = nil, cursor : Gdk::Cursor? = nil, enable_rubberband : Bool? = nil, focus_on_click : Bool? = nil, focusable : Bool? = nil, hadjustment : Gtk::Adjustment? = nil, halign : Gtk::Align? = nil, has_default : Bool? = nil, has_focus : Bool? = nil, has_tooltip : Bool? = nil, height_request : Int32? = nil, hexpand : Bool? = nil, hexpand_set : Bool? = nil, hscroll_policy : Gtk::ScrollablePolicy? = nil, layout_manager : Gtk::LayoutManager? = nil, margin_bottom : Int32? = nil, margin_end : Int32? = nil, margin_start : Int32? = nil, margin_top : Int32? = nil, model : Gtk::SelectionModel? = nil, name : String? = nil, opacity : Float64? = nil, overflow : Gtk::Overflow? = nil, parent : Gtk::Widget? = nil, receives_default : Bool? = nil, reorderable : Bool? = nil, root : Gtk::Root? = nil, scale_factor : Int32? = nil, sensitive : Bool? = nil, show_column_separators : Bool? = nil, show_row_separators : Bool? = nil, single_click_activate : Bool? = nil, sorter : Gtk::Sorter? = nil, tooltip_markup : String? = nil, tooltip_text : String? = nil, vadjustment : Gtk::Adjustment? = nil, valign : Gtk::Align? = nil, vexpand : Bool? = nil, vexpand_set : Bool? = nil, visible : Bool? = nil, vscroll_policy : Gtk::ScrollablePolicy? = nil, width_request : Int32? = nil) #

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


Instance Method Detail

def activate_signal #

def append_column(column : Gtk::ColumnViewColumn) : Nil #

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


def columns : 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.


def enable_rubberband : Bool #

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


def enable_rubberband=(enable_rubberband : Bool) : Nil #

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


def enable_rubberband? : Bool #

def insert_column(position : UInt32, column : Gtk::ColumnViewColumn) : Nil #

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

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


def model : Gtk::SelectionModel? #

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


def model=(model : Gtk::SelectionModel?) : Nil #

Sets the model to use.

This must be a Gtk#SelectionModel.


def remove_column(column : Gtk::ColumnViewColumn) : Nil #

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


def reorderable : Bool #

Returns whether columns are reorderable.


def reorderable=(reorderable : Bool) : Nil #

Sets whether columns should be reorderable by dragging.


def reorderable? : Bool #

def show_column_separators : Bool #

Returns whether the list should show separators between columns.


def show_column_separators=(show_column_separators : Bool) : Nil #

Sets whether the list should show separators between columns.


def show_column_separators? : Bool #

def show_row_separators : Bool #

Returns whether the list should show separators between rows.


def show_row_separators=(show_row_separators : Bool) : Nil #

Sets whether the list should show separators between rows.


def show_row_separators? : Bool #

def single_click_activate : Bool #

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


def single_click_activate=(single_click_activate : Bool) : Nil #

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


def single_click_activate? : Bool #

def sort_by_column(column : Gtk::ColumnViewColumn?, direction : Gtk::SortType) : Nil #

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 Gtk::ColumnView#sorter is set on a sort model, and Gtk::ColumnViewColumn#sorter= has been called on @column to associate a sorter with the column.

If @column is %NULL, the view will be unsorted.


def sorter : Gtk::Sorter? #

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 Gtk::ColumnViewColumn#sorter= for setting up per-column sorting.

Here is an example:

WARNING ⚠️ The following code is in c ⚠️

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);