From 8e887fbbf4fe4f9ee6c889c4f2018a6cadc2a09b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 27 Feb 2021 18:18:12 -0500 Subject: [PATCH] listitemfactory: Convert docs --- gtk/gtklistitemfactory.c | 50 ++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/gtk/gtklistitemfactory.c b/gtk/gtklistitemfactory.c index da854ade85..82fa3402db 100644 --- a/gtk/gtklistitemfactory.c +++ b/gtk/gtklistitemfactory.c @@ -24,14 +24,16 @@ #include "gtklistitemprivate.h" /** - * SECTION:gtklistitemfactory - * @Title: GtkListItemFactory - * @Short_description: Mapping list items to widgets + * GtkListItemFactory: * - * #GtkListItemFactory is one of the core concepts of handling list widgets. - * 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 - * displayed by the view change. + * A `GtkListItemFactory` creates widgets for the items taken from a `GListModel`. + * + * This is one of the core concepts of handling list widgets such + * 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 * 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 * 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. + * * 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 * new items. * * The actual widgets used for displaying those widgets is provided by you. * - * When the factory needs widgets created, it will create a #GtkListItem and - * hand it to your code to set up a widget for. This list item will provide + * When the factory needs widgets created, it will create a `GtkListItem` + * 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 - * you with some opportunities to configure its behavior. See the #GtkListItem - * documentation for further details. + * you with some opportunities to configure its behavior. See the + * [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 - * #GtkBuilderListItemFactory which takes a #GtkBuilder .ui file and then creates - * widgets and manages everything automatically from the information in that file - * and #GtkSignalListItemFactory which allows you to connect to signals with your - * own code and retain full control over how the widgets are setup and managed. + * [class@Gtk.BuilderListItemFactory] which takes a `GtkBuilder` .ui file + * and then creates widgets and manages everything automatically from the + * information in that file and [class@Gtk.SignalListItemFactory] which allows + * 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 * the last widget created from it. * 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 - * view widget you want to use it with, such as via gtk_list_view_set_factory(). - * Reusing factories across different views is allowed, but very uncommon. + * Once you have chosen your factory and created it, you need to set it + * on the view widget you want to use it with, such as via + * [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) @@ -163,4 +168,3 @@ gtk_list_item_factory_update (GtkListItemFactory *self, g_object_thaw_notify (G_OBJECT (list_item)); } -