luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-23 10:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GListModel SECTION

Browse Source 
Move it to the struct docs.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-10-23 14:40:20 +01:00
parent b45c554da5
commit c834b843b9
1 changed files with 25 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
gio/glistmodel.c
View File

@ -31,74 +31,72 @@
G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
/**
* SECTION:glistmodel
* @title: GListModel
* @short_description: An interface describing a dynamic list of objects
* @include: gio/gio.h
* @see_also: #GListStore
* GListModel:
*
* #GListModel is an interface that represents a mutable list of
* #GObjects. Its main intention is as a model for various widgets in
* user interfaces, such as list views, but it can also be used as a
* `GListModel` is an interface that represents a mutable list of
* [class@GObject.Object]. Its main intention is as a model for various widgets
* in user interfaces, such as list views, but it can also be used as a
* convenient method of returning lists of data, with support for
* updates.
*
* Each object in the list may also report changes in itself via some
* mechanism (normally the #GObject::notify signal). Taken together
* with the #GListModel::items-changed signal, this provides for a list
* that can change its membership, and in which the members can change
* their individual properties.
* mechanism (normally the [signal@GObject.Object::notify] signal). Taken
* together with the [signal@Gio.ListModel::items-changed] signal, this provides
* for a list that can change its membership, and in which the members can
* change their individual properties.
*
* A good example would be the list of visible wireless network access
* points, where each access point can report dynamic properties such as
* signal strength.
*
* It is important to note that the #GListModel itself does not report
* It is important to note that the `GListModel` itself does not report
* changes to the individual items. It only reports changes to the list
* membership. If you want to observe changes to the objects themselves
* then you need to connect signals to the objects that you are
* interested in.
*
* All items in a #GListModel are of (or derived from) the same type.
* g_list_model_get_item_type() returns that type. The type may be an
* All items in a `GListModel` are of (or derived from) the same type.
* [method@Gio.ListModel.get_item_type] returns that type. The type may be an
* interface, in which case all objects in the list must implement it.
*
* The semantics are close to that of an array:
* g_list_model_get_n_items() returns the number of items in the list and
* g_list_model_get_item() returns an item at a (0-based) position. In
* order to allow implementations to calculate the list length lazily,
* [method@Gio.ListModel.get_n_items] returns the number of items in the list
* and [method@Gio.ListModel.get_item] returns an item at a (0-based) position.
* In order to allow implementations to calculate the list length lazily,
* you can also iterate over items: starting from 0, repeatedly call
* g_list_model_get_item() until it returns %NULL.
* [method@Gio.ListModel.get_item] until it returns `NULL`.
*
* An implementation may create objects lazily, but must take care to
* return the same object for a given position until all references to
* it are gone.
*
* On the other side, a consumer is expected only to hold references on
* objects that are currently "user visible", in order to facilitate the
* objects that are currently ‘user visible’, in order to facilitate the
* maximum level of laziness in the implementation of the list and to
* reduce the required number of signal connections at a given time.
*
* This interface is intended only to be used from a single thread. The
* thread in which it is appropriate to use it depends on the particular
* implementation, but typically it will be from the thread that owns
* the [thread-default main context][g-main-context-push-thread-default]
* in effect at the time that the model was created.
* the thread-default main context (see
* [method@GLib.MainContext.push_thread_default]) in effect at the time that the
* model was created.
*
* Over time, it has established itself as good practice for listmodel
* Over time, it has established itself as good practice for list model
* implementations to provide properties `item-type` and `n-items` to
* ease working with them. While it is not required, it is recommended
* that implementations provide these two properties. They should return
* the values of g_list_model_get_item_type() and g_list_model_get_n_items()
* respectively and be defined as such:
* |[<!-- language="C" -->
* the values of [method@Gio.ListModel.get_item_type] and
* [method@Gio.ListModel.get_n_items] respectively and be defined as such:
*
* ```c
* properties[PROP_ITEM_TYPE] =
* g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT,
* G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
* properties[PROP_N_ITEMS] =
* g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0,
* G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
* ]|
* ```
*/
/**
@ -131,13 +129,6 @@ G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
* Since: 2.44
*/
/**
* GListModel:
*
* #GListModel is an opaque data structure and can only be accessed
* using the following functions.
**/
static guint g_list_model_changed_signal;
static void