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

listitemfactory: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-27 18:18:12 -05:00 committed by Emmanuele Bassi
parent dc42dcf962
commit 8e887fbbf4
1 changed files with 27 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
gtk/gtklistitemfactory.c
View File

@ -24,14 +24,16 @@
#include "gtklistitemprivate.h" #include "gtklistitemprivate.h"
/** /**
* SECTION:gtklistitemfactory * GtkListItemFactory:
* @Title: GtkListItemFactory
* @Short_description: Mapping list items to widgets
* *
* #GtkListItemFactory is one of the core concepts of handling list widgets. * A `GtkListItemFactory` creates widgets for the items taken from a `GListModel`.
* It is the object tasked with creating widgets for items taken from a *
* #GListModel when the views need them and updating them as the items * This is one of the core concepts of handling list widgets such
* displayed by the view change. * as [class@Gtk.ListView] or [class@Gtk.GridView].
*
* The `GtkListItemFactory` is tasked with creating widgets for items
* taken from the model when the views need them and updating them as
* the items displayed by the view change.
* *
* A view is usually only able to display anything after both a factory * A view is usually only able to display anything after both a factory
* and a model have been set on the view. So it is important that you do * and a model have been set on the view. So it is important that you do
@ -39,36 +41,39 @@
* *
* Because views do not display the whole list at once but only a few * Because views do not display the whole list at once but only a few
* items, they only need to maintain a few widgets at a time. They will * items, they only need to maintain a few widgets at a time. They will
* instruct the #GtkListItemFactory to create these widgets and bind them * instruct the `GtkListItemFactory` to create these widgets and bind them
* to the items that are currently displayed. * to the items that are currently displayed.
*
* As the list model changes or the user scrolls to the list, the items will * As the list model changes or the user scrolls to the list, the items will
* change and the view will instruct the factory to bind the widgets to those * change and the view will instruct the factory to bind the widgets to those
* new items. * new items.
* *
* The actual widgets used for displaying those widgets is provided by you. * The actual widgets used for displaying those widgets is provided by you.
* *
* When the factory needs widgets created, it will create a #GtkListItem and * When the factory needs widgets created, it will create a `GtkListItem`
* hand it to your code to set up a widget for. This list item will provide * and hand it to your code to set up a widget for. This list item will provide
* various properties with information about what item to display and provide * various properties with information about what item to display and provide
* you with some opportunities to configure its behavior. See the #GtkListItem * you with some opportunities to configure its behavior. See the
* documentation for further details. * [class@Gtk.ListItem] documentation for further details.
* *
* Various implementations of #GtkListItemFactory exist to allow you different * Various implementations of `GtkListItemFactory` exist to allow you different
* ways to provide those widgets. The most common implementations are * ways to provide those widgets. The most common implementations are
* #GtkBuilderListItemFactory which takes a #GtkBuilder .ui file and then creates * [class@Gtk.BuilderListItemFactory] which takes a `GtkBuilder` .ui file
* widgets and manages everything automatically from the information in that file * and then creates widgets and manages everything automatically from the
* and #GtkSignalListItemFactory which allows you to connect to signals with your * information in that file and [class@Gtk.SignalListItemFactory] which allows
* own code and retain full control over how the widgets are setup and managed. * you to connect to signals with your own code and retain full control over
* how the widgets are setup and managed.
* *
* A #GtkListItemFactory is supposed to be final - that means its behavior should * A `GtkListItemFactory` is supposed to be final - that means its behavior should
* not change and the first widget created from it should behave the same way as * not change and the first widget created from it should behave the same way as
* the last widget created from it. * the last widget created from it.
* If you intend to do changes to the behavior, it is recommended that you create * If you intend to do changes to the behavior, it is recommended that you create
* a new #GtkListItemFactory which will allow the views to recreate its widgets. * a new `GtkListItemFactory` which will allow the views to recreate its widgets.
* *
* Once you have chosen your factory and created it, you need to set it on the * Once you have chosen your factory and created it, you need to set it
* view widget you want to use it with, such as via gtk_list_view_set_factory(). * on the view widget you want to use it with, such as via
* Reusing factories across different views is allowed, but very uncommon. * [method@Gtk.ListView.set_factory]. Reusing factories across different
* views is allowed, but very uncommon.
*/ */
G_DEFINE_TYPE (GtkListItemFactory, gtk_list_item_factory, G_TYPE_OBJECT) G_DEFINE_TYPE (GtkListItemFactory, gtk_list_item_factory, G_TYPE_OBJECT)
@ -163,4 +168,3 @@ gtk_list_item_factory_update (GtkListItemFactory *self,
g_object_thaw_notify (G_OBJECT (list_item)); g_object_thaw_notify (G_OBJECT (list_item));
} }