[gtkmm: 3/5] Add class documentation for DropDown etc

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 865418954a8958b038a3e93ad64300a5a45c5866
Author: Andreas Persson <andreasp56 outlook com>
Date:   Wed Jul 15 20:51:57 2020 +0200

    Add class documentation for DropDown etc
    
    Class documentation for DropDown, ListItem, ListItemFactory,
    SignalListItemFactory and StringList copied from GTK and manually
    converted to Doxygen format.

 gtk/src/dropdown.hg              | 31 ++++++++++++++++++++++++++
 gtk/src/listitem.hg              | 22 +++++++++++++++++++
 gtk/src/listitemfactory.hg       | 47 ++++++++++++++++++++++++++++++++++++++++
 gtk/src/signallistitemfactory.hg | 45 ++++++++++++++++++++++++++++++++++++++
 gtk/src/stringlist.hg            | 28 ++++++++++++++++++++++++
 5 files changed, 173 insertions(+)
---
diff --git a/gtk/src/dropdown.hg b/gtk/src/dropdown.hg
index f87e8865c..595ac2f83 100644
--- a/gtk/src/dropdown.hg
+++ b/gtk/src/dropdown.hg
@@ -23,6 +23,37 @@ _PINCLUDE(gtkmm/private/widget_p.h)
 
 namespace Gtk
 {
+
+/** Choose an item from a list.
+ *
+ * %Gtk::DropDown is a widget that allows the user to choose an item
+ * from a list of options. The %Gtk::DropDown displays the selected
+ * choice.
+ *
+ * The options are given to %Gtk::DropDown in the form of Gio::ListModel,
+ * and how the individual options are represented is determined by
+ * a Gtk::ListItemFactory. The default factory displays simple strings,
+ * and expects to obtain these from the model by evaluating an expression
+ * that has to be provided via set_expression().
+ *
+ * The convenience method set_from_strings() can be used to set up a
+ * model that is populated from an array of strings and an expression
+ * for obtaining those strings.
+ *
+ * %Gtk::DropDown can optionally allow search in the popup, which is
+ * useful if the list of options is long. To enable the search entry,
+ * use set_enable_search().
+ *
+ * @par CSS nodes
+ * %Gtk::DropDown has a single CSS node with name dropdown,
+ * with the button and popover nodes as children.
+ *
+ * @see Gtk::ComboBox
+ *
+ * @ingroup Widgets
+ *
+ * @newin{3,98}
+ */
 class GTKMM_API DropDown : public Widget
 {
   _CLASS_GTKOBJECT(DropDown, GtkDropDown, GTK_DROP_DOWN, Gtk::Widget, GtkWidget, , , GTKMM_API)
diff --git a/gtk/src/listitem.hg b/gtk/src/listitem.hg
index 665e6a86e..e9383d406 100644
--- a/gtk/src/listitem.hg
+++ b/gtk/src/listitem.hg
@@ -21,6 +21,28 @@ _PINCLUDE(glibmm/private/object_p.h)
 
 namespace Gtk
 {
+
+/** %Object used to represent items of a ListModel.
+ *
+ * %Gtk::ListItem is the object that list-handling containers such
+ * as Gtk::ListView use to represent items in a Gio::ListModel. They are
+ * managed by the container and cannot be created by application code.
+ *
+ * %Gtk::ListItems need to be populated by application code. This is done by
+ * calling set_child().
+ *
+ * %Gtk::ListItems exist in 2 stages:
+ *
+ * 1. The unbound stage where the listitem is not currently connected to
+ *    an item in the list. In that case, the property_item() property is
+ *    not set.
+ *
+ * 2. The bound stage where the listitem references an item from the list.
+ *    The property_item() property is set.
+ *
+ * @see Gtk::ListView, Gio::ListModel
+ * @newin{3,98}
+ */
 class GTKMM_API ListItem : public Glib::Object
 {
   _CLASS_GOBJECT(ListItem, GtkListItem, GTK_LIST_ITEM, Glib::Object, GObject, , , GTKMM_API)
diff --git a/gtk/src/listitemfactory.hg b/gtk/src/listitemfactory.hg
index 2125efeeb..d3176c277 100644
--- a/gtk/src/listitemfactory.hg
+++ b/gtk/src/listitemfactory.hg
@@ -23,6 +23,53 @@ _PINCLUDE(glibmm/private/object_p.h)
 
 namespace Gtk
 {
+
+/** Mapping list items to widgets.
+ *
+ * %Gtk::ListItemFactory is one of the core concepts of handling list widgets.
+ * It is the object tasked with creating widgets for items taken from a
+ * Gio::ListModel 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
+ * not skip this step when setting up your first view.
+ *
+ * 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 %Gtk::ListItemFactory 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 Gtk::ListItem 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 Gtk::ListItem
+ * documentation for further details.
+ *
+ * Various implementations of %Gtk::ListItemFactory exist to allow you different
+ * ways to provide those widgets. The most common implementations are
+ * Gtk::BuilderListItemFactory which takes a Gtk::Builder .ui file and then creates
+ * widgets and manages everything automatically from the information in that file
+ * and 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 %Gtk::ListItemFactory 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 %Gtk::ListItemFactory 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::ListView::set_factory().
+ * Reusing factories across different views is allowed, but very uncommon.
+ *
+ * @newin{3,98}
+ */
 class GTKMM_API ListItemFactory : public Glib::Object
 {
   _CLASS_GOBJECT(ListItemFactory, GtkListItemFactory, GTK_LIST_ITEM_FACTORY, Glib::Object, GObject, , , 
GTKMM_API)
diff --git a/gtk/src/signallistitemfactory.hg b/gtk/src/signallistitemfactory.hg
index f6f1ed138..ef25c3380 100644
--- a/gtk/src/signallistitemfactory.hg
+++ b/gtk/src/signallistitemfactory.hg
@@ -22,6 +22,51 @@ _PINCLUDE(gtkmm/private/listitemfactory_p.h)
 
 namespace Gtk
 {
+
+/** A listitem factory providing signals.
+ *
+ * %Gtk::SignalListItemFactory is a Gtk::ListItemFactory that provides signals
+ * that user code can connect to to manage listitems.
+ * Signals are emitted for every listitem in the same order:
+ *
+ *  1. signal_setup() is emitted to set up permanent things
+ *  on the listitem. This usually means constructing the widgets used in the
+ *  row and adding them to the listitem.
+ *
+ *  2. signal_bind() is emitted to bind the item passed via
+ *  Gtk::ListItem::item to the widgets that have been created in step 1 or to
+ *  add item-specific widgets. Signals are connected to listen to changes -
+ *  both to changes in the item to update the widgets or to changes in the
+ *  widgets to update the item. After this signal has been called, the
+ *  listitem may be shown in a list widget.
+ *
+ *  3. signal_unbind() is emitted to undo everything 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
+ *  widget.
+ *
+ *  4. signal_bind() and signal_unbind() may be emitted multiple times
+ *  again to bind the listitem for use with new items. By reusing
+ *  listitems, potentially costly setup can be avoided. However, it
+ *  means code needs to make sure to properly clean up the listitem in
+ *  step 3 so that no information from the previous use leaks into the
+ *  next use.
+ *
+ * 5. signal_teardown() is emitted to allow undoing the effects of
+ * signal_setup(). After this signal 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
+ * Gtk::ListItems passed will not trigger notify signals as the listitem's
+ * notifications are frozen. See Glib::ObjectBase::freeze_notify() for details.
+ *
+ * For tracking changes in other properties in the Gtk::ListItem, the
+ * Gtk::ListItem notify signal is recommended. The signal can be connected
+ * in the signal_setup() signal and removed again during signal_teardown().
+ *
+ * @see Gtk::ListItemFactory
+ * @newin{3,98}
+ */
 class GTKMM_API SignalListItemFactory : public ListItemFactory
 {
   _CLASS_GOBJECT(SignalListItemFactory, GtkSignalListItemFactory, GTK_SIGNAL_LIST_ITEM_FACTORY, 
Gtk::ListItemFactory, GtkListItemFactory, , , GTKMM_API)
diff --git a/gtk/src/stringlist.hg b/gtk/src/stringlist.hg
index 2d0406bd5..385637ddc 100644
--- a/gtk/src/stringlist.hg
+++ b/gtk/src/stringlist.hg
@@ -36,6 +36,34 @@ public:
   _WRAP_PROPERTY("string", Glib::ustring)
 };
 
+/** A list model for strings.
+ *
+ * %Gtk::StringList is a list model that wraps an array of strings.
+ *
+ * The objects in the model have a "string" property.
+ *
+ * @par %Gtk::StringList as Gtk::Buildable
+ * The %Gtk::StringList implementation of the Gtk::Buildable interface
+ * supports adding items directly using the <items> element and
+ * specifying <item> elements for each item. Each <item> element
+ * supports the regular translation attributes “translatable”,
+ * “context” and “comments”.
+ *
+ * @par
+ * Here is a UI definition fragment specifying a %Gtk::StringList
+ * ~~~{.xml}
+ * <object class="GtkStringList">
+ *   <items>
+ *     <item translatable="yes">Factory</item>
+ *     <item translatable="yes">Home</item>
+ *     <item translatable="yes">Subway</item>
+ *   </items>
+ * </object>
+ * ~~~
+ *
+ * @see Gio::ListModel
+ * @newin{3,98}
+ */
 class GTKMM_API StringList : public Glib::Object, public Gio::ListModel, public Buildable
 {
   _CLASS_GOBJECT(StringList, GtkStringList, GTK_STRING_LIST, Glib::Object, GObject, , , GTKMM_API)