GtkGridView

GtkGridView — A widget for displaying lists in a grid

Properties

gboolean enable-rubberband Read / Write
GtkListItemFactory * factory Read / Write
guint max-columns Read / Write
guint min-columns Read / Write
GListModel * model Read / Write
gboolean single-click-activate Read / Write

Signals

void activate Run Last

Actions

  list.activate-item u

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkListBase
                ╰── GtkGridView

Implemented Interfaces

GtkGridView implements AtkImplementorIface, GtkBuildable, GtkConstraintTarget, GtkOrientable and GtkScrollable.

Includes

#include <gtk/gtk.h>

Description

GtkGridView is a widget to present a view into a large dynamic grid of items.

GtkGridView uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view determines if the grid reflows vertically or horizontally.

GtkGridView allows the user to select items according to the selection characteristics of the model. If the provided model is not a GtkSelectionModel, GtkGridView will wrap it in a GtkSingleSelection. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using “enable-rubberband”.

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

CSS nodes

1
2
3
4
5
6
7
gridview
├── child

├── child


╰── [rubberband]

GtkGridView uses a single CSS node with name gridview. Each child uses a single CSS node with name child. For rubberband selection, a subnode with name rubberband is used.

Functions

gtk_grid_view_new ()

GtkWidget *
gtk_grid_view_new (void);

Creates a new empty GtkGridView.

You most likely want to call gtk_grid_view_set_factory() to set up a way to map its items to widgets and gtk_grid_view_set_model() to set a model to provide items next.

Returns

a new GtkGridView


gtk_grid_view_set_model ()

void
gtk_grid_view_set_model (GtkGridView *self,
                         GListModel *model);

Sets the GListModel to use for

Parameters

self

a GtkGridView

 

model

the model to use or NULL for none.

[allow-none][transfer none]

gtk_grid_view_get_model ()

GListModel *
gtk_grid_view_get_model (GtkGridView *self);

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

Parameters

self

a GtkGridView

 

Returns

The model in use.

[nullable][transfer none]


gtk_grid_view_set_max_columns ()

void
gtk_grid_view_set_max_columns (GtkGridView *self,
                               guint max_columns);

Sets the maximum number of columns to use. This number must be at least 1.

If max_columns is smaller than the minimum set via gtk_grid_view_set_min_columns(), that value is used instead.

Parameters

self

a GtkGridView

 

max_columns

The maximum number of columns

 

gtk_grid_view_get_max_columns ()

guint
gtk_grid_view_get_max_columns (GtkGridView *self);

Gets the maximum number of columns that the grid will use.

Parameters

self

a GtkGridView

 

Returns

The maximum number of columns


gtk_grid_view_set_min_columns ()

void
gtk_grid_view_set_min_columns (GtkGridView *self,
                               guint min_columns);

Sets the minimum number of columns to use. This number must be at least 1.

If min_columns is smaller than the minimum set via gtk_grid_view_set_max_columns(), that value is ignored.

Parameters

self

a GtkGridView

 

min_columns

The minimum number of columns

 

gtk_grid_view_get_min_columns ()

guint
gtk_grid_view_get_min_columns (GtkGridView *self);

Gets the minimum number of columns that the grid will use.

Parameters

self

a GtkGridView

 

Returns

The minimum number of columns


gtk_grid_view_set_single_click_activate ()

void
gtk_grid_view_set_single_click_activate
                               (GtkGridView *self,
                                gboolean single_click_activate);

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

Parameters

self

a GtkGridView

 

single_click_activate

TRUE to activate items on single click

 

gtk_grid_view_get_single_click_activate ()

gboolean
gtk_grid_view_get_single_click_activate
                               (GtkGridView *self);

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

Parameters

self

a GtkListView

 

Returns

TRUE if items are activated on single click


gtk_grid_view_set_enable_rubberband ()

void
gtk_grid_view_set_enable_rubberband (GtkGridView *self,
                                     gboolean enable_rubberband);

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

Parameters

self

a GtkGridView

 

enable_rubberband

TRUE to enable rubberband selection

 

gtk_grid_view_get_enable_rubberband ()

gboolean
gtk_grid_view_get_enable_rubberband (GtkGridView *self);

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

Parameters

self

a GtkGridView

 

Returns

TRUE if rubberband selection is enabled

Types and Values

GtkGridView

typedef struct _GtkGridView GtkGridView;

GtkGridView is a list widget implementation that arranges its items in a grid.

Property Details

The “enable-rubberband” property

  “enable-rubberband”        gboolean

Allow rubberband selection

Owner: GtkGridView

Flags: Read / Write

Default value: FALSE


The “factory” property

  “factory”                  GtkListItemFactory *

Factory for populating list items

Owner: GtkGridView

Flags: Read / Write


The “max-columns” property

  “max-columns”              guint

Maximum number of columns per row

If this number is smaller than GtkGridView:min-columns, that value is used instead.

Owner: GtkGridView

Flags: Read / Write

Allowed values: >= 1

Default value: 7


The “min-columns” property

  “min-columns”              guint

Minimum number of columns per row

Owner: GtkGridView

Flags: Read / Write

Allowed values: >= 1

Default value: 1


The “model” property

  “model”                    GListModel *

Model for the items displayed

Owner: GtkGridView

Flags: Read / Write


The “single-click-activate” property

  “single-click-activate”    gboolean

Activate rows on single click and select them on hover

Owner: GtkGridView

Flags: Read / Write

Default value: FALSE

Signal Details

The “activate” signal

void
user_function (GtkGridView *self,
               guint        position,
               gpointer     user_data)

The ::activate signal is emitted when a cell has been activated by the user, usually via activating the GtkGridView|list.activate-item action.

This allows for a convenient way to handle activation in a gridview. See GtkListItem:activatable for details on how to use this signal.

Parameters

self

The GtkGridView

 

position

position of item to activate

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Action Details

The “list.activate-item” action

Activates the item given in position by emitting the GtkGridView::activate signal.

Parameter type: u

Parameters

position

position of item to activate

 

See Also

GListModel, GtkListView, GtkColumnView