AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

listview: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-28 13:09:48 -05:00 committed by Emmanuele Bassi
parent 5189d3b485
commit 5568025f1d
2 changed files with 71 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
gtk/gtklistview.c
View File

@ -41,29 +41,28 @@
#define GTK_LIST_VIEW_EXTRA_ITEMS 2 #define GTK_LIST_VIEW_EXTRA_ITEMS 2
/** /**
* SECTION:gtklistview * GtkListView:
* @title: GtkListView
* @short_description: A widget for displaying lists
* @see_also: #GtkSelectionModel, #GtkColumnView, #GtkGridView
* *
* GtkListView is a widget to present a view into a large dynamic list of items. * `GtkListView` presents a large dynamic list of items.
* *
* GtkListView uses its factory to generate one row widget for each visible item * `GtkListView` uses its factory to generate one row widget for each visible
* and shows them in a linear display, either vertically or horizontally. The * item and shows them in a linear display, either vertically or horizontally.
* #GtkListView:show-separators property offers a simple way to display separators
* between the rows.
* *
* GtkListView allows the user to select items according to the selection * The [property@Gtk.ListView:show-separators] property offers a simple way to
* display separators between the rows.
*
* `GtkListView` allows the user to select items according to the selection
* characteristics of the model. For models that allow multiple selected items, * characteristics of the model. For models that allow multiple selected items,
* it is possible to turn on _rubberband selection_, using * it is possible to turn on _rubberband selection_, using
* #GtkListView:enable-rubberband. * [property@Gtk.ListView:enable-rubberband].
* *
* If you need multiple columns with headers, see #GtkColumnView. * If you need multiple columns with headers, see [class@Gtk.ColumnView].
* *
* To learn more about the list widget framework, see the [overview](#ListWidget). * To learn more about the list widget framework, see the
* [overview](section-list-widget.html).
* *
* An example of using GtkListView: * An example of using `GtkListView`:
* |[ * ```c
* static void * static void
* setup_listitem_cb (GtkListItemFactory *factory, * setup_listitem_cb (GtkListItemFactory *factory,
* GtkListItem *list_item) * GtkListItem *list_item)
@ -112,11 +111,11 @@
* g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL); * g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL);
* *
* gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); * gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list);
* ]| * ```
* *
* # CSS nodes * # CSS nodes
* *
* |[<!-- language="plain" --> * ```
* listview[.separators][.rich-list][.navigation-sidebar][.data-table] * listview[.separators][.rich-list][.navigation-sidebar][.data-table]
* ├── row * ├── row
* │ * │
@ -124,11 +123,10 @@
* │ * │
* ┊ * ┊
* ╰── [rubberband] * ╰── [rubberband]
* ```
* ]|
* *
* GtkListView uses a single CSS node named listview. It may carry the * `GtkListView` uses a single CSS node named listview. It may carry the
* .separators style class, when #GtkListView:show-separators property * .separators style class, when `GtkListView`:show-separators property
* is set. Each child widget uses a single CSS node named row. For * is set. Each child widget uses a single CSS node named row. For
* rubberband selection, a node with name rubberband is used. * rubberband selection, a node with name rubberband is used.
* *
@ -138,8 +136,8 @@
* *
* # Accessibility * # Accessibility
* *
* GtkListView uses the #GTK_ACCESSIBLE_ROLE_LIST role, and the list * `GtkListView` uses the %GTK_ACCESSIBLE_ROLE_LIST role, and the list
* items use the #GTK_ACCESSIBLE_ROLE_LIST_ITEM role. * items use the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role.
*/ */
typedef struct _ListRow ListRow; typedef struct _ListRow ListRow;
@ -810,9 +808,9 @@ gtk_list_view_class_init (GtkListViewClass *klass)
gobject_class->set_property = gtk_list_view_set_property; gobject_class->set_property = gtk_list_view_set_property;
/** /**
* GtkListView:factory: * GtkListView:factory: (attributes org.gtk.Property.get=gtk_list_view_get_factory org.gtk.Property.set=gtk_list_view_set_factory)
* *
* Factory for populating list items * Factory for populating list items.
*/ */
properties[PROP_FACTORY] = properties[PROP_FACTORY] =
g_param_spec_object ("factory", g_param_spec_object ("factory",
@ -822,9 +820,9 @@ gtk_list_view_class_init (GtkListViewClass *klass)
G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS); G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
/** /**
* GtkListView:model: * GtkListView:model: (attributes org.gtk.Property.get=gtk_list_view_get_model org.gtk.Property.set=gtk_list_view_set_model)
* *
* Model for the items displayed * Model for the items displayed.
*/ */
properties[PROP_MODEL] = properties[PROP_MODEL] =
g_param_spec_object ("model", g_param_spec_object ("model",
@ -834,9 +832,9 @@ gtk_list_view_class_init (GtkListViewClass *klass)
G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS); G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
/** /**
* GtkListView:show-separators: * GtkListView:show-separators: (attributes org.gtk.Property.get=gtk_list_view_get_show_separators org.gtk.Property.set=gtk_list_view_set_show_separators)
* *
* Show separators between rows * Show separators between rows.
*/ */
properties[PROP_SHOW_SEPARATORS] = properties[PROP_SHOW_SEPARATORS] =
g_param_spec_boolean ("show-separators", g_param_spec_boolean ("show-separators",
@ -846,9 +844,9 @@ gtk_list_view_class_init (GtkListViewClass *klass)
G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkListView:single-click-activate: * GtkListView:single-click-activate: (attributes org.gtk.Property.get=gtk_list_view_get_single_click_activate org.gtk.Property.set=gtk_list_view_set_single_click_activate)
* *
* Activate rows on single click and select them on hover * Activate rows on single click and select them on hover.
*/ */
properties[PROP_SINGLE_CLICK_ACTIVATE] = properties[PROP_SINGLE_CLICK_ACTIVATE] =
g_param_spec_boolean ("single-click-activate", g_param_spec_boolean ("single-click-activate",
@ -858,9 +856,9 @@ gtk_list_view_class_init (GtkListViewClass *klass)
G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
/** /**
* GtkListView:enable-rubberband: * GtkListView:enable-rubberband: (attributes org.gtk.Property.get=gtk_list_view_get_enable_rubberband org.gtk.Property.set=gtk_list_view_set_enable_rubberband)
* *
* Allow rubberband selection * Allow rubberband selection.
*/ */
properties[PROP_ENABLE_RUBBERBAND] = properties[PROP_ENABLE_RUBBERBAND] =
g_param_spec_boolean ("enable-rubberband", g_param_spec_boolean ("enable-rubberband",
@ -873,14 +871,15 @@ gtk_list_view_class_init (GtkListViewClass *klass)
/** /**
* GtkListView::activate: * GtkListView::activate:
* @self: The #GtkListView * @self: The `GtkListView`
* @position: position of item to activate * @position: position of item to activate
* *
* The ::activate signal is emitted when a row has been activated by the user, * Emitted when a row has been activated by the user,
* usually via activating the GtkListView|list.activate-item action. * usually via activating the GtkListView|list.activate-item action.
* *
* This allows for a convenient way to handle activation in a listview. * This allows for a convenient way to handle activation in a listview.
* See gtk_list_item_set_activatable() for details on how to use this signal. * See [method@Gtk.ListItem.set_activatable] for details on how to use
* this signal.
*/ */
signals[ACTIVATE] = signals[ACTIVATE] =
g_signal_new (I_("activate"), g_signal_new (I_("activate"),
@ -899,8 +898,8 @@ gtk_list_view_class_init (GtkListViewClass *klass)
* GtkListView|list.activate-item: * GtkListView|list.activate-item:
* @position: position of item to activate * @position: position of item to activate
* *
* Activates the item given in @position by emitting the GtkListView::activate * Activates the item given in @position by emitting the
* signal. * [signal@Gtk.ListView::activate] signal.
*/ */
gtk_widget_class_install_action (widget_class, gtk_widget_class_install_action (widget_class,
"list.activate-item", "list.activate-item",
@ -928,18 +927,18 @@ gtk_list_view_init (GtkListView *self)
* @model: (allow-none) (transfer full): the model to use, or %NULL * @model: (allow-none) (transfer full): the model to use, or %NULL
* @factory: (allow-none) (transfer full): The factory to populate items with, or %NULL * @factory: (allow-none) (transfer full): The factory to populate items with, or %NULL
* *
* Creates a new #GtkListView that uses the given @factory for * Creates a new `GtkListView` that uses the given @factory for
* mapping items to widgets. * mapping items to widgets.
* *
* The function takes ownership of the * The function takes ownership of the
* arguments, so you can write code like * arguments, so you can write code like
* ``` * ```c
* list_view = gtk_list_view_new (create_model (), * list_view = gtk_list_view_new (create_model (),
* gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); * gtk_builder_list_item_factory_new_from_resource ("/resource.ui"));
* ``` * ```
* *
* Returns: a new #GtkListView using the given @model and @factory * Returns: a new `GtkListView` using the given @model and @factory
**/ */
GtkWidget * GtkWidget *
gtk_list_view_new (GtkSelectionModel *model, gtk_list_view_new (GtkSelectionModel *model,
GtkListItemFactory *factory) GtkListItemFactory *factory)
@ -962,13 +961,13 @@ gtk_list_view_new (GtkSelectionModel *model,
} }
/** /**
* gtk_list_view_get_model: * gtk_list_view_get_model: (attributes org.gtk.Method.get_property=model)
* @self: a #GtkListView * @self: a `GtkListView`
* *
* Gets the model that's currently used to read the items displayed. * Gets the model that's currently used to read the items displayed.
* *
* Returns: (nullable) (transfer none): The model in use * Returns: (nullable) (transfer none): The model in use
**/ */
GtkSelectionModel * GtkSelectionModel *
gtk_list_view_get_model (GtkListView *self) gtk_list_view_get_model (GtkListView *self)
{ {
@ -978,12 +977,14 @@ gtk_list_view_get_model (GtkListView *self)
} }
/** /**
* gtk_list_view_set_model: * gtk_list_view_set_model: (attributes org.gtk.Method.set_property=model)
* @self: a #GtkListView * @self: a `GtkListView`
* @model: (allow-none) (transfer none): the model to use or %NULL for none * @model: (allow-none) (transfer none): the model to use or %NULL for none
* *
* Sets the #GtkSelectionModel to use. * Sets the model to use.
**/ *
* This must be a [iface@Gtk.SelectionModel] to use.
*/
void void
gtk_list_view_set_model (GtkListView *self, gtk_list_view_set_model (GtkListView *self,
GtkSelectionModel *model) GtkSelectionModel *model)
@ -1002,13 +1003,13 @@ gtk_list_view_set_model (GtkListView *self,
} }
/** /**
* gtk_list_view_get_factory: * gtk_list_view_get_factory: (attributes org.gtk.Method.get_property=factory)
* @self: a #GtkListView * @self: a `GtkListView`
* *
* Gets the factory that's currently used to populate list items. * Gets the factory that's currently used to populate list items.
* *
* Returns: (nullable) (transfer none): The factory in use * Returns: (nullable) (transfer none): The factory in use
**/ */
GtkListItemFactory * GtkListItemFactory *
gtk_list_view_get_factory (GtkListView *self) gtk_list_view_get_factory (GtkListView *self)
{ {
@ -1018,12 +1019,12 @@ gtk_list_view_get_factory (GtkListView *self)
} }
/** /**
* gtk_list_view_set_factory: * gtk_list_view_set_factory: (attributes org.gtk.Method.set_property=factory)
* @self: a #GtkListView * @self: a `GtkListView`
* @factory: (allow-none) (transfer none): the factory to use or %NULL for none * @factory: (allow-none) (transfer none): the factory to use or %NULL for none
* *
* Sets the #GtkListItemFactory to use for populating list items. * Sets the `GtkListItemFactory` to use for populating list items.
**/ */
void void
gtk_list_view_set_factory (GtkListView *self, gtk_list_view_set_factory (GtkListView *self,
GtkListItemFactory *factory) GtkListItemFactory *factory)
@ -1040,8 +1041,8 @@ gtk_list_view_set_factory (GtkListView *self,
} }
/** /**
* gtk_list_view_set_show_separators: * gtk_list_view_set_show_separators: (attributes org.gtk.Method.set_property=show-separators)
* @self: a #GtkListView * @self: a `GtkListView`
* @show_separators: %TRUE to show separators * @show_separators: %TRUE to show separators
* *
* Sets whether the list box should show separators * Sets whether the list box should show separators
@ -1067,8 +1068,8 @@ gtk_list_view_set_show_separators (GtkListView *self,
} }
/** /**
* gtk_list_view_get_show_separators: * gtk_list_view_get_show_separators: (attributes org.gtk.Method.get_property=show-separators)
* @self: a #GtkListView * @self: a `GtkListView`
* *
* Returns whether the list box should show separators * Returns whether the list box should show separators
* between rows. * between rows.
@ -1084,8 +1085,8 @@ gtk_list_view_get_show_separators (GtkListView *self)
} }
/** /**
* gtk_list_view_set_single_click_activate: * gtk_list_view_set_single_click_activate: (attributes org.gtk.Method.set_property=single-click-activate)
* @self: a #GtkListView * @self: a `GtkListView`
* @single_click_activate: %TRUE to activate items on single click * @single_click_activate: %TRUE to activate items on single click
* *
* Sets whether rows should be activated on single click and * Sets whether rows should be activated on single click and
@ -1106,8 +1107,8 @@ gtk_list_view_set_single_click_activate (GtkListView *self,
} }
/** /**
* gtk_list_view_get_single_click_activate: * gtk_list_view_get_single_click_activate: (attributes org.gtk.Method.set_property=single-click-activate)
* @self: a #GtkListView * @self: a `GtkListView`
* *
* Returns whether rows will be activated on single click and * Returns whether rows will be activated on single click and
* selected on hover. * selected on hover.
@ -1123,8 +1124,8 @@ gtk_list_view_get_single_click_activate (GtkListView *self)
} }
/** /**
* gtk_list_view_set_enable_rubberband: * gtk_list_view_set_enable_rubberband: (attributes org.gtk.Method.set_property=enable-rubberband)
* @self: a #GtkListView * @self: a `GtkListView`
* @enable_rubberband: %TRUE to enable rubberband selection * @enable_rubberband: %TRUE to enable rubberband selection
* *
* Sets whether selections can be changed by dragging with the mouse. * Sets whether selections can be changed by dragging with the mouse.
@ -1144,8 +1145,8 @@ gtk_list_view_set_enable_rubberband (GtkListView *self,
} }
/** /**
* gtk_list_view_get_enable_rubberband: * gtk_list_view_get_enable_rubberband: (attributes org.gtk.Method.get_property=enable-rubberband)
* @self: a #GtkListView * @self: a `GtkListView`
* *
* Returns whether rows can be selected by dragging with the mouse. * Returns whether rows can be selected by dragging with the mouse.
* *

5
gtk/gtklistview.h
View File

@ -35,11 +35,6 @@ G_BEGIN_DECLS
#define GTK_IS_LIST_VIEW_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_LIST_VIEW)) #define GTK_IS_LIST_VIEW_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_LIST_VIEW))
#define GTK_LIST_VIEW_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_LIST_VIEW, GtkListViewClass)) #define GTK_LIST_VIEW_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_LIST_VIEW, GtkListViewClass))
/**
* GtkListView:
*
* GtkListView is the simple list implementation for GTK's list widgets.
*/
typedef struct _GtkListView GtkListView; typedef struct _GtkListView GtkListView;
typedef struct _GtkListViewClass GtkListViewClass; typedef struct _GtkListViewClass GtkListViewClass;