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

GtkListBox

GtkListBox — A list container

Properties

Signals

void activate-cursor-row Action
void move-cursor Action
void row-activated Run Last
void row-selected Run Last
void toggle-cursor-row 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.

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 *list_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

list_box

a GtkListBox.

 

child

the GtkWidget to add

 

Since 3.10


gtk_list_box_insert ()

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

Insert the child into the list_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 list_box , then the child will be appended to the end.

Parameters

list_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 *list_box,
                         GtkListBoxRow *row);

Make row the currently selected row.

Parameters

list_box

a GtkListBox

 

row

The row to select or NULL.

[allow-none]

Since 3.10


gtk_list_box_get_selected_row ()

GtkListBoxRow *
gtk_list_box_get_selected_row (GtkListBox *list_box);

Gets the selected row.

Parameters

list_box

a GtkListBox

 

Returns

the selected GtkWidget.

[transfer none]

Since 3.10


gtk_list_box_set_selection_mode ()

void
gtk_list_box_set_selection_mode (GtkListBox *list_box,
                                 GtkSelectionMode mode);

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

Note: GtkListBox does not support GTK_SELECTION_MULTIPLE .

Parameters

list_box

a GtkListBox

 

mode

The GtkSelectionMode

 

Since 3.10


gtk_list_box_get_selection_mode ()

GtkSelectionMode
gtk_list_box_get_selection_mode (GtkListBox *list_box);

Gets the selection mode of the listbox.

Parameters

list_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 *list_box,
                                gboolean single);

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

Parameters

list_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 *list_box);

Returns whether rows activate on single clicks.

Parameters

list_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 *list_box);

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

Parameters

list_box

a GtkListBox

 

Returns

the adjustment.

[transfer none]

Since 3.10


gtk_list_box_set_adjustment ()

void
gtk_list_box_set_adjustment (GtkListBox *list_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 list_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

list_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 *list_box,
                              GtkWidget *placeholder);

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

Parameters

list_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 *list_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

list_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 *list_box,
                           gint y);

Gets the row at the y position.

Parameters

list_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 *list_box);

Update the filtering for all rows. Call this when result of the filter function on the list_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

list_box

a GtkListBox

 

Since 3.10


gtk_list_box_invalidate_headers ()

void
gtk_list_box_invalidate_headers (GtkListBox *list_box);

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

Parameters

list_box

a GtkListBox

 

Since 3.10


gtk_list_box_invalidate_sort ()

void
gtk_list_box_invalidate_sort (GtkListBox *list_box);

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

Parameters

list_box

a GtkListBox

 

Since 3.10


gtk_list_box_set_filter_func ()

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

By setting a filter function on the list_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

list_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 *list_box,
                              GtkListBoxUpdateHeaderFunc update_header,
                              gpointer user_data,
                              GDestroyNotify destroy);

By setting a header function on the list_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 exisiting header widh 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

list_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 *list_box,
                            GtkListBoxSortFunc sort_func,
                            gpointer user_data,
                            GDestroyNotify destroy);

By setting a sort function on the list_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

list_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 *list_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

list_box

An GtkListBox.

 

row

a GtkListBoxRow

 

Since 3.10


gtk_list_box_drag_unhighlight_row ()

void
gtk_list_box_drag_unhighlight_row (GtkListBox *list_box);

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

Parameters

list_box

An 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_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

Types and Values

struct GtkListBox

struct GtkListBox;

struct GtkListBoxClass

struct GtkListBoxClass {
  GtkContainerClass parent_class;


  void (*row_selected)        (GtkListBox      *list_box,
                               GtkListBoxRow   *row);
  void (*row_activated)       (GtkListBox      *list_box,
                               GtkListBoxRow   *row);
  void (*activate_cursor_row) (GtkListBox      *list_box);
  void (*toggle_cursor_row)   (GtkListBox      *list_box);
  void (*move_cursor)         (GtkListBox      *list_box,
                               GtkMovementStep  step,
                               gint             count);
};

Members

GtkContainerClass parent_class;

The parent class.

 

row_selected ()

Signal emitted when a new row is selected.

 

row_activated ()

Signal emitted when a row has been activated by the user.

 

activate_cursor_row ()

   

toggle_cursor_row ()

   

move_cursor ()

   

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

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    *list_box,
               GtkListBoxRow *row,
               gpointer       user_data)

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

Parameters

list_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    *list_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.

Parameters

list_box

the GtkListBox

 

row

the selected row

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 3.10


The “toggle-cursor-row” signal

void
user_function (GtkListBox *listbox,
               gpointer    user_data)

Flags: Action


The “activate” signal

void
user_function (GtkListBoxRow *listboxrow,
               gpointer       user_data)

Flags: Action

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