Interface
GioListModel
Description
interface Gio.ListModel : GObject.Object
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
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.
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
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
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,
you can also iterate over items: starting from 0, repeatedly call
g_list_model_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 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.
Over time, it has established itself as good practice for listmodel
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:
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);
Prerequisite
In order to implement ListModel, your type must inherit fromGObject
.
Signals
Gio.ListModel::items-changed
This signal is emitted whenever items were added to or removed
from list
. At position
, removed
items were removed and added
items were added in their place.
since: 2.44
Interface structure
struct GioListModelInterface {
GTypeInterface g_iface;
GType (* get_item_type) (
GListModel* list
);
guint (* get_n_items) (
GListModel* list
);
GObject* (* get_item) (
GListModel* list,
guint position
);
}
The virtual function table for GListModel
.
Interface members
g_iface |
|
Parent |
|
get_item_type |
|
No description available. | |
get_n_items |
|
No description available. | |
get_item |
|
No description available. |
Virtual methods
Gio.ListModel.get_item
Get the item at position
. If position
is greater than the number of
items in list
, NULL
is returned.
since: 2.44