AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-27 06:00:22 +00:00
Code Issues Projects Releases Wiki Activity

signallistitemfactory: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-27 18:17:57 -05:00 committed by Emmanuele Bassi
parent 68cd66b210
commit dc42dcf962
2 changed files with 54 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
gtk/gtksignallistitemfactory.c
View File

@ -26,50 +26,48 @@
#include "gtklistitem.h" #include "gtklistitem.h"
/** /**
* SECTION:gtksignallistitemfactory * GtkSignalListItemFactory:
* @title: GtkSignalListItemFactory *
* @short_description: A listitem factory providing signals * `GtkSignalListItemFactory` is a `GtkListItemFactory` that emits signals
* @see_also: #GtkListItemFactory * to to manage listitems.
* *
* #GtkSignalListItemFactory is a #GtkListItemFactory that provides signals
* that user code can connect to to manage listitems.
* Signals are emitted for every listitem in the same order: * Signals are emitted for every listitem in the same order:
* *
* 1. #GtkSignalListItemFactory::setup is emitted to set up permanent things * 1. [signal@Gtk.SignalListItemFactory::setup] is emitted to set up permanent
* on the listitem. This usually means constructing the widgets used in the * things on the listitem. This usually means constructing the widgets used in
* row and adding them to the listitem. * the row and adding them to the listitem.
* *
* 2. #GtkSignalListItemFactory::bind is emitted to bind the item passed via * 2. [signal@Gtk.SignalListItemFactory::bind] is emitted to bind the item passed
* #GtkListItem:item to the widgets that have been created in step 1 or to * via [property@Gtk.ListItem:item] to the widgets that have been created in
* add item-specific widgets. Signals are connected to listen to changes - * step 1 or to add item-specific widgets. Signals are connected to listen to
* both to changes in the item to update the widgets or to changes in the * changes - both to changes in the item to update the widgets or to changes
* widgets to update the item. After this signal has been called, the * in the widgets to update the item. After this signal has been called, the
* listitem may be shown in a list widget. * listitem may be shown in a list widget.
* *
* 3. #GtkSignalListItemFactory::unbind is emitted to undo everything done * 3. [signal@Gtk.SignalListItemFactory::unbind] is emitted to undo everything
* in step 2. Usually this means disconnecting signal handlers. Once this * done in step 2. Usually this means disconnecting signal handlers. Once this
* signal has been called, the listitem will no longer be used in a list * signal has been called, the listitem will no longer be used in a list
* widget. * widget.
* *
* 4. #GtkSignalListItemFactory::bind and #GtkSignalListItemFactory::unbind * 4. [signal@Gtk.SignalListItemFactory::bind] and
* may be emitted multiple times again to bind the listitem for use with * [signal@Gtk.SignalListItemFactory::unbind] may be emitted multiple times
* new items. By reusing listitems, potentially costly setup can be * again to bind the listitem for use with new items. By reusing listitems,
* avoided. However, it means code needs to make sure to properly clean * potentially costly setup can be avoided. However, it means code needs to
* up the listitem in step 3 so that no information from the previous * make sure to properly clean up the listitem in step 3 so that no information
* use leaks into the next use. * from the previous use leaks into the next use.
* *
* 5. #GtkSignalListItemFactory::teardown is emitted to allow undoing the * 5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing
* effects of #GtkSignalListItemFactory::setup. After this signal was emitted * the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal
* on a listitem, the listitem will be destroyed and not be used again. * was emitted on a listitem, the listitem will be destroyed and not be used again.
* *
* Note that during the signal emissions, changing properties on the * Note that during the signal emissions, changing properties on the
* #GtkListItems passed will not trigger notify signals as the listitem's * #GtkListItems passed will not trigger notify signals as the listitem's
* notifications are frozen. See g_object_freeze_notify() for details. * notifications are frozen. See g_object_freeze_notify() for details.
* *
* For tracking changes in other properties in the #GtkListItem, the * For tracking changes in other properties in the `GtkListItem`, the
* #GtkListItem::notify signal is recommended. The signal can be connected * ::notify signal is recommended. The signal can be connected in the
* in the #GtkSignalListItemFactory::setup signal and removed again during * [signal@Gtk.SignalListItemFactory::setup] signal and removed again during
* #GtkSignalListItemFactory::teardown. * [signal@Gtk.SignalListItemFactory::teardown].
*/ */
struct _GtkSignalListItemFactory struct _GtkSignalListItemFactory
@ -157,14 +155,15 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
/** /**
* GtkSignalListItemFactory::setup: * GtkSignalListItemFactory::setup:
* @self: The #GtkSignalListItemFactory * @self: The `GtkSignalListItemFactory`
* @listitem: The #GtkListItem to set up * @listitem: The #GtkListItem to set up
* *
* The ::setup signal is emitted when a new listitem has been created and * Emitted when a new listitem has been created and needs to be setup for use.
* needs to be setup for use. It is the first signal emitted for every listitem.
* *
* The #GtkSignalListItemFactory::teardown signal is the opposite of this signal * It is the first signal emitted for every listitem.
* and can be used to undo everything done in this signal. *
* The [signal@Gtk.SignalListItemFactory::teardown] signal is the opposite
* of this signal and can be used to undo everything done in this signal.
*/ */
signals[SETUP] = signals[SETUP] =
g_signal_new (I_("setup"), g_signal_new (I_("setup"),
@ -181,17 +180,18 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
/** /**
* GtkSignalListItemFactory::bind: * GtkSignalListItemFactory::bind:
* @self: The #GtkSignalListItemFactory * @self: The `GtkSignalListItemFactory`
* @listitem: The #GtkListItem to bind * @listitem: The #GtkListItem to bind
* *
* The ::bind signal is emitted when a new #GtkListItem:item has been set * Emitted when a new [property@Gtk.ListItem:item] has been set
* on the @listitem and should be bound for use. * on the @listitem and should be bound for use.
* *
* After this signal was emitted, the listitem might be shown in a #GtkListView * After this signal was emitted, the listitem might be shown in
* or other list widget. * a [class@Gtk.ListView] or other list widget.
* *
* The #GtkSignalListItemFactory::unbind signal is the opposite of this signal * The [signal@Gtk.SignalListItemFactory::unbind] signal is the
* and can be used to undo everything done in this signal. * opposite of this signal and can be used to undo everything done
* in this signal.
*/ */
signals[BIND] = signals[BIND] =
g_signal_new (I_("bind"), g_signal_new (I_("bind"),
@ -208,14 +208,14 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
/** /**
* GtkSignalListItemFactory::unbind: * GtkSignalListItemFactory::unbind:
* @self: The #GtkSignalListItemFactory * @self: The `GtkSignalListItemFactory`
* @listitem: The #GtkListItem to unbind * @listitem: The #GtkListItem to unbind
* *
* The ::unbind signal is emitted when a listitem has been removed from use * Emitted when a listitem has been removed from use in a list widget
* in a list widget and its new #GtkListItem:item is about to be unset. * and its new [property@Gtk.ListItem:item] is about to be unset.
* *
* This signal is the opposite of the #GtkSignalListItemFactory::bind signal * This signal is the opposite of the [signal@Gtk.SignalListItemFactory::bind]
* and should be used to undo everything done in that signal. * signal and should be used to undo everything done in that signal.
*/ */
signals[UNBIND] = signals[UNBIND] =
g_signal_new (I_("unbind"), g_signal_new (I_("unbind"),
@ -232,14 +232,15 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
/** /**
* GtkSignalListItemFactory::teardown: * GtkSignalListItemFactory::teardown:
* @self: The #GtkSignalListItemFactory * @self: The `GtkSignalListItemFactory`
* @listitem: The #GtkListItem to teardown * @listitem: The #GtkListItem to teardown
* *
* The ::teardown signal is emitted when a listitem is about to be destroyed. * Emitted when a listitem is about to be destroyed.
*
* It is the last signal ever emitted for this @listitem. * It is the last signal ever emitted for this @listitem.
* *
* This signal is the opposite of the #GtkSignalListItemFactory::setup signal * This signal is the opposite of the [signal@Gtk.SignalListItemFactory::setup]
* and should be used to undo everything done in that signal. * signal and should be used to undo everything done in that signal.
*/ */
signals[TEARDOWN] = signals[TEARDOWN] =
g_signal_new (I_("teardown"), g_signal_new (I_("teardown"),
@ -263,14 +264,14 @@ gtk_signal_list_item_factory_init (GtkSignalListItemFactory *self)
/** /**
* gtk_signal_list_item_factory_new: * gtk_signal_list_item_factory_new:
* *
* Creates a new #GtkSignalListItemFactory. You need to connect signal * Creates a new `GtkSignalListItemFactory`.
* handlers before you use it.
* *
* Returns: a new #GtkSignalListItemFactory * You need to connect signal handlers before you use it.
*
* Returns: a new `GtkSignalListItemFactory`
**/ **/
GtkListItemFactory * GtkListItemFactory *
gtk_signal_list_item_factory_new (void) gtk_signal_list_item_factory_new (void)
{ {
return g_object_new (GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY, NULL); return g_object_new (GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY, NULL);
} }

5
gtk/gtksignallistitemfactory.h
View File

@ -35,11 +35,6 @@ G_BEGIN_DECLS
#define GTK_IS_SIGNAL_LIST_ITEM_FACTORY_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY)) #define GTK_IS_SIGNAL_LIST_ITEM_FACTORY_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY))
#define GTK_SIGNAL_LIST_ITEM_FACTORY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY, GtkSignalListItemFactoryClass)) #define GTK_SIGNAL_LIST_ITEM_FACTORY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GTK_TYPE_SIGNAL_LIST_ITEM_FACTORY, GtkSignalListItemFactoryClass))
/**
* GtkSignalListItemFactory:
*
* The object for the #GtkSignalListItemFactory.
**/
typedef struct _GtkSignalListItemFactory GtkSignalListItemFactory; typedef struct _GtkSignalListItemFactory GtkSignalListItemFactory;
typedef struct _GtkSignalListItemFactoryClass GtkSignalListItemFactoryClass; typedef struct _GtkSignalListItemFactoryClass GtkSignalListItemFactoryClass;