manpagez: man pages & more
html files: gtk3
Home | html | info | man

GtkListBox

GtkListBox — A list container

Functions

gboolean (*GtkListBoxFilterFunc) ()
gint (*GtkListBoxSortFunc) ()
void (*GtkListBoxUpdateHeaderFunc) ()
GtkWidget * gtk_list_box_new ()
void gtk_list_box_prepend ()
void gtk_list_box_insert ()
void gtk_list_box_select_row ()
void gtk_list_box_unselect_row ()
void gtk_list_box_select_all ()
void gtk_list_box_unselect_all ()
GtkListBoxRow * gtk_list_box_get_selected_row ()
void (*GtkListBoxForeachFunc) ()
void gtk_list_box_selected_foreach ()
GList * gtk_list_box_get_selected_rows ()
void gtk_list_box_set_selection_mode ()
GtkSelectionMode gtk_list_box_get_selection_mode ()
void gtk_list_box_set_activate_on_single_click ()
gboolean gtk_list_box_get_activate_on_single_click ()
GtkAdjustment * gtk_list_box_get_adjustment ()
void gtk_list_box_set_adjustment ()
void gtk_list_box_set_placeholder ()
GtkListBoxRow * gtk_list_box_get_row_at_index ()
GtkListBoxRow * gtk_list_box_get_row_at_y ()
void gtk_list_box_invalidate_filter ()
void gtk_list_box_invalidate_headers ()
void gtk_list_box_invalidate_sort ()
void gtk_list_box_set_filter_func ()
void gtk_list_box_set_header_func ()
void gtk_list_box_set_sort_func ()
void gtk_list_box_drag_highlight_row ()
void gtk_list_box_drag_unhighlight_row ()
GtkWidget * gtk_list_box_row_new ()
void gtk_list_box_row_changed ()
gboolean gtk_list_box_row_is_selected ()
GtkWidget * gtk_list_box_row_get_header ()
GType gtk_list_box_row_get_type ()
void gtk_list_box_row_set_header ()
gint gtk_list_box_row_get_index ()
void gtk_list_box_row_set_activatable ()
gboolean gtk_list_box_row_get_activatable ()
void gtk_list_box_row_set_selectable ()
gboolean gtk_list_box_row_get_selectable ()

Properties

Signals

void activate-cursor-row Action
void move-cursor Action
void row-activated Run Last
void row-selected Run Last
void select-all Action
void selected-rows-changed Run First
void toggle-cursor-row Action
void unselect-all Action
void activate Action

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ├── GtkBin
                   ╰── GtkListBoxRow
                ╰── GtkListBox

Implemented Interfaces

GtkListBox implements AtkImplementorIface and GtkBuildable.

GtkListBoxRow implements AtkImplementorIface and GtkBuildable.

Includes

#include <gtk/gtk.h>

Description

A GtkListBox is a vertical container that contains GtkListBoxRow children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Using GtkListBox is often an alternative to GtkTreeView, especially when the list contents has a more complicated layout than what is allowed by a GtkCellRenderer, or when the contents is interactive (i.e. has a button in it).

Although a GtkListBox must have only GtkListBoxRow children you can add any kind of widget to it via gtk_container_add(), and a GtkListBoxRow widget will automatically be inserted between the list and the widget.

GtkListBoxRows can be marked as activatable or selectable. If a row is activatable, “row-activated” will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.

The GtkListBox widget was added in GTK+ 3.10.

Functions

GtkListBoxFilterFunc ()

gboolean
(*GtkListBoxFilterFunc) (GtkListBoxRow *row,
                         gpointer user_data);

Will be called whenever the row changes or is added and lets you control if the row should be visible or not.

Parameters

row

the row that may be filtered

 

user_data

user data.

[closure]

Returns

TRUE if the row should be visible, FALSE otherwise

Since 3.10


GtkListBoxSortFunc ()

gint
(*GtkListBoxSortFunc) (GtkListBoxRow *row1,
                       GtkListBoxRow *row2,
                       gpointer user_data);

Compare two rows to determine which should be first.

Parameters

row1

the first row

 

row2

the second row

 

user_data

user data.

[closure]

Returns

< 0 if row1 should be before row2 , 0 if they are equal and > 0 otherwise

Since 3.10


GtkListBoxUpdateHeaderFunc ()

void
(*GtkListBoxUpdateHeaderFunc) (GtkListBoxRow *row,
                               GtkListBoxRow *before,
                               gpointer user_data);

Whenever row changes or which row is before row changes this is called, which lets you update the header on row . You may remove or set a new one via gtk_list_box_row_set_header() or just change the state of the current header widget.

Parameters

row

the row to update

 

before

the row before row , or NULL if it is first.

[allow-none]

user_data

user data.

[closure]

Since 3.10


gtk_list_box_new ()

GtkWidget *
gtk_list_box_new (void);

Creates a new GtkListBox container.

Returns

a new GtkListBox

Since 3.10


gtk_list_box_prepend ()

void
gtk_list_box_prepend (GtkListBox *box,
                      GtkWidget *child);

Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add().

Parameters

box

a GtkListBox

 

child

the GtkWidget to add

 

Since 3.10


gtk_list_box_insert ()

void
gtk_list_box_insert (GtkListBox *box,
                     GtkWidget *child,
                     gint position);

Insert the child into the box at position . If a sort function is set, the widget will actually be inserted at the calculated position and this function has the same effect of gtk_container_add().

If position is -1, or larger than the total number of items in the box , then the child will be appended to the end.

Parameters

box

a GtkListBox

 

child

the GtkWidget to add

 

position

the position to insert child in

 

Since 3.10


gtk_list_box_select_row ()

void
gtk_list_box_select_row (GtkListBox *box,
                         GtkListBoxRow *row);

Make row the currently selected row.

Parameters

box

a GtkListBox

 

row

The row to select or NULL.

[allow-none]

Since 3.10


gtk_list_box_unselect_row ()

void
gtk_list_box_unselect_row (GtkListBox *box,
                           GtkListBoxRow *row);

Unselects a single row of box , if the selection mode allows it.

Parameters

box

a GtkListBox

 

row

the row to unselected

 

Since 3.14


gtk_list_box_select_all ()

void
gtk_list_box_select_all (GtkListBox *box);

Select all children of box , if the selection mode allows it.

Parameters

box

a GtkListBox

 

Since 3.14


gtk_list_box_unselect_all ()

void
gtk_list_box_unselect_all (GtkListBox *box);

Unselect all children of box , if the selection mode allows it.

Parameters

box

a GtkListBox

 

Since 3.14


gtk_list_box_get_selected_row ()

GtkListBoxRow *
gtk_list_box_get_selected_row (GtkListBox *box);

Gets the selected row.

Note that the box may allow multiple selection, in which case you should use gtk_list_box_selected_foreach() to find all selected rows.

Parameters

box

a GtkListBox

 

Returns

the selected row.

[transfer none]

Since 3.10


GtkListBoxForeachFunc ()

void
(*GtkListBoxForeachFunc) (GtkListBox *box,
                          GtkListBoxRow *row,
                          gpointer user_data);

A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the box .

Parameters

box

a GtkListBox

 

row

a GtkListBoxRow

 

user_data

user data.

[closure]

Since 3.14


gtk_list_box_selected_foreach ()

void
gtk_list_box_selected_foreach (GtkListBox *box,
                               GtkListBoxForeachFunc func,
                               gpointer data);

Calls a function for each selected child.

Note that the selection cannot be modified from within this function.

Parameters

box

a GtkListBox

 

func

the function to call for each selected child.

[scope call]

data

user data to pass to the function

 

Since 3.14


gtk_list_box_get_selected_rows ()

GList *
gtk_list_box_get_selected_rows (GtkListBox *box);

Creates a list of all selected children.

Parameters

box

a GtkListBox

 

Returns

A GList containing the GtkWidget for each selected child. Free with g_list_free() when done.

[element-type GtkListBoxRow][transfer container]

Since 3.14


gtk_list_box_set_selection_mode ()

void
gtk_list_box_set_selection_mode (GtkListBox *box,
                                 GtkSelectionMode mode);

Sets how selection works in the listbox. See GtkSelectionMode for details.

Parameters

box

a GtkListBox

 

mode

The GtkSelectionMode

 

Since 3.10


gtk_list_box_get_selection_mode ()

GtkSelectionMode
gtk_list_box_get_selection_mode (GtkListBox *box);

Gets the selection mode of the listbox.

Parameters

box

a GtkListBox

 

Returns

a GtkSelectionMode

Since 3.10


gtk_list_box_set_activate_on_single_click ()

void
gtk_list_box_set_activate_on_single_click
                               (GtkListBox *box,
                                gboolean single);

If single is TRUE, rows will be activated when you click on them, otherwise you need to double-click.

Parameters

box

a GtkListBox

 

single

a boolean

 

Since 3.10


gtk_list_box_get_activate_on_single_click ()

gboolean
gtk_list_box_get_activate_on_single_click
                               (GtkListBox *box);

Returns whether rows activate on single clicks.

Parameters

box

a GtkListBox

 

Returns

TRUE if rows are activated on single click, FALSE otherwise

Since 3.10


gtk_list_box_get_adjustment ()

GtkAdjustment *
gtk_list_box_get_adjustment (GtkListBox *box);

Gets the adjustment (if any) that the widget uses to for vertical scrolling.

Parameters

box

a GtkListBox

 

Returns

the adjustment.

[transfer none]

Since 3.10


gtk_list_box_set_adjustment ()

void
gtk_list_box_set_adjustment (GtkListBox *box,
                             GtkAdjustment *adjustment);

Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling.

In the normal case when the box is packed inside a GtkScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that.

Parameters

box

a GtkListBox

 

adjustment

the adjustment, or NULL.

[allow-none]

Since 3.10


gtk_list_box_set_placeholder ()

void
gtk_list_box_set_placeholder (GtkListBox *box,
                              GtkWidget *placeholder);

Sets the placeholder widget that is shown in the list when it doesn't display any visible children.

Parameters

box

a GtkListBox

 

placeholder

a GtkWidget or NULL.

[allow-none]

Since 3.10


gtk_list_box_get_row_at_index ()

GtkListBoxRow *
gtk_list_box_get_row_at_index (GtkListBox *box,
                               gint index_);

Gets the n-th child in the list (not counting headers). If _index is negative or larger than the number of items in the list, NULL is returned.

Parameters

box

a GtkListBox

 

index_

the index of the row

 

Returns

the child GtkWidget or NULL.

[transfer none]

Since 3.10


gtk_list_box_get_row_at_y ()

GtkListBoxRow *
gtk_list_box_get_row_at_y (GtkListBox *box,
                           gint y);

Gets the row at the y position.

Parameters

box

a GtkListBox

 

y

position

 

Returns

the row.

[transfer none]

Since 3.10


gtk_list_box_invalidate_filter ()

void
gtk_list_box_invalidate_filter (GtkListBox *box);

Update the filtering for all rows. Call this when result of the filter function on the box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed.

Parameters

box

a GtkListBox

 

Since 3.10


gtk_list_box_invalidate_headers ()

void
gtk_list_box_invalidate_headers (GtkListBox *box);

Update the separators for all rows. Call this when result of the header function on the box is changed due to an external factor.

Parameters

box

a GtkListBox

 

Since 3.10


gtk_list_box_invalidate_sort ()

void
gtk_list_box_invalidate_sort (GtkListBox *box);

Update the sorting for all rows. Call this when result of the sort function on the box is changed due to an external factor.

Parameters

box

a GtkListBox

 

Since 3.10


gtk_list_box_set_filter_func ()

void
gtk_list_box_set_filter_func (GtkListBox *box,
                              GtkListBoxFilterFunc filter_func,
                              gpointer user_data,
                              GDestroyNotify destroy);

By setting a filter function on the box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows.

The filter_func will be called for each row after the call, and it will continue to be called each time a row changes (via gtk_list_box_row_changed()) or when gtk_list_box_invalidate_filter() is called.

Parameters

box

a GtkListBox

 

filter_func

callback that lets you filter which rows to show.

[closure user_data][allow-none]

user_data

user data passed to filter_func

 

destroy

destroy notifier for user_data

 

Since 3.10


gtk_list_box_set_header_func ()

void
gtk_list_box_set_header_func (GtkListBox *box,
                              GtkListBoxUpdateHeaderFunc update_header,
                              gpointer user_data,
                              GDestroyNotify destroy);

By setting a header function on the box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind.

The update_header can look at the current header widget using gtk_list_box_row_get_header() and either update the state of the widget as needed, or set a new one using gtk_list_box_row_set_header(). If no header is needed, set the header to NULL.

Note that you may get many calls update_header to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one.

The update_header function will be called for each row after the call, and it will continue to be called each time a row changes (via gtk_list_box_row_changed()) and when the row before changes (either by gtk_list_box_row_changed() on the previous row, or when the previous row becomes a different row). It is also called for all rows when gtk_list_box_invalidate_headers() is called.

Parameters

box

a GtkListBox

 

update_header

callback that lets you add row headers.

[closure user_data][allow-none]

user_data

user data passed to update_header

 

destroy

destroy notifier for user_data

 

Since 3.10


gtk_list_box_set_sort_func ()

void
gtk_list_box_set_sort_func (GtkListBox *box,
                            GtkListBoxSortFunc sort_func,
                            gpointer user_data,
                            GDestroyNotify destroy);

By setting a sort function on the box one can dynamically reorder the rows of the list, based on the contents of the rows.

The sort_func will be called for each row after the call, and will continue to be called each time a row changes (via gtk_list_box_row_changed()) and when gtk_list_box_invalidate_sort() is called.

Parameters

box

a GtkListBox

 

sort_func

the sort function.

[closure user_data][allow-none]

user_data

user data passed to sort_func

 

destroy

destroy notifier for user_data

 

Since 3.10


gtk_list_box_drag_highlight_row ()

void
gtk_list_box_drag_highlight_row (GtkListBox *box,
                                 GtkListBoxRow *row);

This is a helper function for implementing DnD onto a GtkListBox. The passed in row will be highlighted via gtk_drag_highlight(), and any previously highlighted row will be unhighlighted.

The row will also be unhighlighted when the widget gets a drag leave event.

Parameters

box

a GtkListBox

 

row

a GtkListBoxRow

 

Since 3.10


gtk_list_box_drag_unhighlight_row ()

void
gtk_list_box_drag_unhighlight_row (GtkListBox *box);

If a row has previously been highlighted via gtk_list_box_drag_highlight_row() it will have the highlight removed.

Parameters

box

a GtkListBox

 

Since 3.10


gtk_list_box_row_new ()

GtkWidget *
gtk_list_box_row_new (void);

Creates a new GtkListBoxRow, to be used as a child of a GtkListBox.

Returns

a new GtkListBoxRow

Since 3.10


gtk_list_box_row_changed ()

void
gtk_list_box_row_changed (GtkListBoxRow *row);

Marks row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers.

Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list is mirroring some external data set, and *two* rows changed in the external data set then when you call gtk_list_box_row_changed() on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong.

This generally means that if you don’t fully control the data model you have to duplicate the data that affects the listbox row functions into the row widgets themselves. Another alternative is to call gtk_list_box_invalidate_sort() on any model change, but that is more expensive.

Parameters

row

a GtkListBoxRow

 

Since 3.10


gtk_list_box_row_is_selected ()

gboolean
gtk_list_box_row_is_selected (GtkListBoxRow *row);

Returns whether the child is currently selected in its GtkListBox container.

Parameters

row

a GtkListBoxRow

 

Returns

TRUE if row is selected

Since 3.14


gtk_list_box_row_get_header ()

GtkWidget *
gtk_list_box_row_get_header (GtkListBoxRow *row);

Returns the current header of the row . This can be used in a GtkListBoxUpdateHeaderFunc to see if there is a header set already, and if so to update the state of it.

Parameters

row

a GtkListBoxRow

 

Returns

the current header, or NULL if none.

[transfer none]

Since 3.10


gtk_list_box_row_get_type ()

GType
gtk_list_box_row_get_type (void);

gtk_list_box_row_set_header ()

void
gtk_list_box_row_set_header (GtkListBoxRow *row,
                             GtkWidget *header);

Sets the current header of the row . This is only allowed to be called from a GtkListBoxUpdateHeaderFunc. It will replace any existing header in the row, and be shown in front of the row in the listbox.

Parameters

row

a GtkListBoxRow

 

header

the header, or NULL.

[allow-none]

Since 3.10


gtk_list_box_row_get_index ()

gint
gtk_list_box_row_get_index (GtkListBoxRow *row);

Gets the current index of the row in its GtkListBox container.

Parameters

row

a GtkListBoxRow

 

Returns

the index of the row , or -1 if the row is not in a listbox

Since 3.10


gtk_list_box_row_set_activatable ()

void
gtk_list_box_row_set_activatable (GtkListBoxRow *row,
                                  gboolean activatable);

Set the “activatable” property for this row.

Parameters

row

a GTkListBoxrow

 

activatable

TRUE to mark the row as activatable

 

Since 3.14


gtk_list_box_row_get_activatable ()

gboolean
gtk_list_box_row_get_activatable (GtkListBoxRow *row);

Gets the value of the “activatable” property for this row.

Parameters

row

a GtkListBoxRow

 

Returns

TRUE if the row is activatable

Since 3.14


gtk_list_box_row_set_selectable ()

void
gtk_list_box_row_set_selectable (GtkListBoxRow *row,
                                 gboolean selectable);

Set the “selectable” property for this row.

Parameters

row

a GTkListBoxrow

 

selectable

TRUE to mark the row as selectable

 

Since 3.14


gtk_list_box_row_get_selectable ()

gboolean
gtk_list_box_row_get_selectable (GtkListBoxRow *row);

Gets the value of the “selectable” property for this row.

Parameters

row

a GtkListBoxRow

 

Returns

TRUE if the row is selectable

Since 3.14

Types and Values

struct GtkListBox

struct GtkListBox;

struct GtkListBoxClass

struct GtkListBoxClass {
  GtkContainerClass parent_class;


  void (*row_selected)        (GtkListBox      *box,
                               GtkListBoxRow   *row);
  void (*row_activated)       (GtkListBox      *box,
                               GtkListBoxRow   *row);
  void (*activate_cursor_row) (GtkListBox      *box);
  void (*toggle_cursor_row)   (GtkListBox      *box);
  void (*move_cursor)         (GtkListBox      *box,
                               GtkMovementStep  step,
                               gint             count);
  void (*selected_rows_changed) (GtkListBox    *box);
  void (*select_all)            (GtkListBox    *box);
  void (*unselect_all)          (GtkListBox    *box);
};

Members

GtkContainerClass parent_class;

The parent class.

 

row_selected ()

Class handler for the “row-selected” signal

 

row_activated ()

Class handler for the “row-activated” signal

 

activate_cursor_row ()

Class handler for the “activate-cursor-row” signal

 

toggle_cursor_row ()

Class handler for the “activate-cursor-row” signal

 

move_cursor ()

Class handler for the “move-cursor” signal

 

selected_rows_changed ()

Class handler for the “selected-rows-changed” signal

 

select_all ()

Class handler for the “select-all” signal

 

unselect_all ()

Class handler for the “unselect-all” signal

 

struct GtkListBoxRow

struct GtkListBoxRow;

struct GtkListBoxRowClass

struct GtkListBoxRowClass {
  GtkBinClass parent_class;


  void (* activate) (GtkListBoxRow *row);
};

Members

GtkBinClass parent_class;

The parent class.

 

activate ()

   

Property Details

The “activate-on-single-click” property

  “activate-on-single-click” gboolean

Activate row on a single click.

Flags: Read / Write

Default value: TRUE


The “selection-mode” property

  “selection-mode”           GtkSelectionMode

The selection mode.

Flags: Read / Write

Default value: GTK_SELECTION_SINGLE


The “activatable” property

  “activatable”              gboolean

The property determines whether the “row-activated” signal will be emitted for this row.

Flags: Read / Write

Default value: TRUE

Since 3.14


The “selectable” property

  “selectable”               gboolean

The property determines whether this row can be selected.

Flags: Read / Write

Default value: TRUE

Since 3.14

Signal Details

The “activate-cursor-row” signal

void
user_function (GtkListBox *listbox,
               gpointer    user_data)

Flags: Action


The “move-cursor” signal

void
user_function (GtkListBox     *listbox,
               GtkMovementStep arg1,
               gint            arg2,
               gpointer        user_data)

Flags: Action


The “row-activated” signal

void
user_function (GtkListBox    *box,
               GtkListBoxRow *row,
               gpointer       user_data)

The ::row-activated signal is emitted when a row has been activated by the user.

Parameters

box

the GtkListBox

 

row

the activated row

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 3.10


The “row-selected” signal

void
user_function (GtkListBox    *box,
               GtkListBoxRow *row,
               gpointer       user_data)

The ::row-selected signal is emitted when a new row is selected, or (with a NULL row ) when the selection is cleared.

When the box is using GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the “selected-rows-changed” signal instead.

Parameters

box

the GtkListBox

 

row

the selected row.

[nullable]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 3.10


The “select-all” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::select-all signal is a keybinding signal which gets emitted to select all children of the box, if the selection mode permits it.

The default bindings for this signal is Ctrl-a.

Parameters

box

the GtkListBox on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Action

Since 3.14


The “selected-rows-changed” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::selected-rows-changed signal is emitted when the set of selected rows changes.

Parameters

box

the GtkListBox on wich the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since 3.14


The “toggle-cursor-row” signal

void
user_function (GtkListBox *listbox,
               gpointer    user_data)

Flags: Action


The “unselect-all” signal

void
user_function (GtkListBox *box,
               gpointer    user_data)

The ::unselect-all signal is a keybinding signal which gets emitted to unselect all children of the box, if the selection mode permits it.

The default bindings for this signal is Ctrl-Shift-a.

Parameters

box

the GtkListBox on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Action

Since 3.14


The “activate” signal

void
user_function (GtkListBoxRow *listboxrow,
               gpointer       user_data)

Flags: Action

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.