Branch data Line data Source code
1 : : /*
2 : : * Copyright 2015 Lars Uebernickel
3 : : * Copyright 2015 Ryan Lortie
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General
18 : : * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 : : *
20 : : * Authors:
21 : : * Lars Uebernickel <lars@uebernic.de>
22 : : * Ryan Lortie <desrt@desrt.ca>
23 : : */
24 : :
25 : : #include "config.h"
26 : :
27 : : #include "glistmodel.h"
28 : : #include "glibintl.h"
29 : : #include "gmarshal-internal.h"
30 : :
31 : 22619 : G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
32 : :
33 : : /**
34 : : * GListModel:
35 : : *
36 : : * `GListModel` is an interface that represents a mutable list of
37 : : * [class@GObject.Object]. Its main intention is as a model for various widgets
38 : : * in user interfaces, such as list views, but it can also be used as a
39 : : * convenient method of returning lists of data, with support for
40 : : * updates.
41 : : *
42 : : * Each object in the list may also report changes in itself via some
43 : : * mechanism (normally the [signal@GObject.Object::notify] signal). Taken
44 : : * together with the [signal@Gio.ListModel::items-changed] signal, this provides
45 : : * for a list that can change its membership, and in which the members can
46 : : * change their individual properties.
47 : : *
48 : : * A good example would be the list of visible wireless network access
49 : : * points, where each access point can report dynamic properties such as
50 : : * signal strength.
51 : : *
52 : : * It is important to note that the `GListModel` itself does not report
53 : : * changes to the individual items. It only reports changes to the list
54 : : * membership. If you want to observe changes to the objects themselves
55 : : * then you need to connect signals to the objects that you are
56 : : * interested in.
57 : : *
58 : : * All items in a `GListModel` are of (or derived from) the same type.
59 : : * [method@Gio.ListModel.get_item_type] returns that type. The type may be an
60 : : * interface, in which case all objects in the list must implement it.
61 : : *
62 : : * The semantics are close to that of an array:
63 : : * [method@Gio.ListModel.get_n_items] returns the number of items in the list
64 : : * and [method@Gio.ListModel.get_item] returns an item at a (0-based) position.
65 : : * In order to allow implementations to calculate the list length lazily,
66 : : * you can also iterate over items: starting from 0, repeatedly call
67 : : * [method@Gio.ListModel.get_item] until it returns `NULL`.
68 : : *
69 : : * An implementation may create objects lazily, but must take care to
70 : : * return the same object for a given position until all references to
71 : : * it are gone.
72 : : *
73 : : * On the other side, a consumer is expected only to hold references on
74 : : * objects that are currently ‘user visible’, in order to facilitate the
75 : : * maximum level of laziness in the implementation of the list and to
76 : : * reduce the required number of signal connections at a given time.
77 : : *
78 : : * This interface is intended only to be used from a single thread. The
79 : : * thread in which it is appropriate to use it depends on the particular
80 : : * implementation, but typically it will be from the thread that owns
81 : : * the thread-default main context (see
82 : : * [method@GLib.MainContext.push_thread_default]) in effect at the time that the
83 : : * model was created.
84 : : *
85 : : * Over time, it has established itself as good practice for list model
86 : : * implementations to provide properties `item-type` and `n-items` to
87 : : * ease working with them. While it is not required, it is recommended
88 : : * that implementations provide these two properties. They should return
89 : : * the values of [method@Gio.ListModel.get_item_type] and
90 : : * [method@Gio.ListModel.get_n_items] respectively and be defined as such:
91 : : *
92 : : * ```c
93 : : * properties[PROP_ITEM_TYPE] =
94 : : * g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT,
95 : : * G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
96 : : * properties[PROP_N_ITEMS] =
97 : : * g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0,
98 : : * G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
99 : : * ```
100 : : */
101 : :
102 : : /**
103 : : * GListModelInterface:
104 : : * @g_iface: parent #GTypeInterface
105 : : * @get_item_type: the virtual function pointer for g_list_model_get_item_type()
106 : : * @get_n_items: the virtual function pointer for g_list_model_get_n_items()
107 : : * @get_item: the virtual function pointer for g_list_model_get_item()
108 : : *
109 : : * The virtual function table for #GListModel.
110 : : *
111 : : * Since: 2.44
112 : : */
113 : :
114 : : /**
115 : : * GListModelInterface::get_item:
116 : : * @list: a #GListModel
117 : : * @position: the position of the item to fetch
118 : : *
119 : : * Get the item at @position. If @position is greater than the number of
120 : : * items in @list, %NULL is returned.
121 : : *
122 : : * %NULL is never returned for an index that is smaller than the length
123 : : * of the list. See g_list_model_get_n_items().
124 : : *
125 : : * The same #GObject instance may not appear more than once in a #GListModel.
126 : : *
127 : : * Returns: (type GObject) (transfer full) (nullable): the object at @position.
128 : : *
129 : : * Since: 2.44
130 : : */
131 : :
132 : : static guint g_list_model_changed_signal;
133 : :
134 : : static void
135 : 3 : g_list_model_default_init (GListModelInterface *iface)
136 : : {
137 : : /**
138 : : * GListModel::items-changed:
139 : : * @list: the #GListModel that changed
140 : : * @position: the position at which @list changed
141 : : * @removed: the number of items removed
142 : : * @added: the number of items added
143 : : *
144 : : * This signal is emitted whenever items were added to or removed
145 : : * from @list. At @position, @removed items were removed and @added
146 : : * items were added in their place.
147 : : *
148 : : * Note: If `removed != added`, the positions of all later items
149 : : * in the model change.
150 : : *
151 : : * Since: 2.44
152 : : */
153 : 3 : g_list_model_changed_signal = g_signal_new (I_("items-changed"),
154 : : G_TYPE_LIST_MODEL,
155 : : G_SIGNAL_RUN_LAST,
156 : : 0,
157 : : NULL, NULL,
158 : : _g_cclosure_marshal_VOID__UINT_UINT_UINT,
159 : : G_TYPE_NONE,
160 : : 3, G_TYPE_UINT, G_TYPE_UINT, G_TYPE_UINT);
161 : 3 : g_signal_set_va_marshaller (g_list_model_changed_signal,
162 : : G_TYPE_FROM_INTERFACE (iface),
163 : : _g_cclosure_marshal_VOID__UINT_UINT_UINTv);
164 : 3 : }
165 : :
166 : : /**
167 : : * g_list_model_get_item_type:
168 : : * @list: a #GListModel
169 : : *
170 : : * Gets the type of the items in @list.
171 : : *
172 : : * All items returned from g_list_model_get_item() are of the type
173 : : * returned by this function, or a subtype, or if the type is an
174 : : * interface, they are an implementation of that interface.
175 : : *
176 : : * The item type of a #GListModel can not change during the life of the
177 : : * model.
178 : : *
179 : : * Returns: the #GType of the items contained in @list.
180 : : *
181 : : * Since: 2.44
182 : : */
183 : : GType
184 : 1 : g_list_model_get_item_type (GListModel *list)
185 : : {
186 : 1 : g_return_val_if_fail (G_IS_LIST_MODEL (list), G_TYPE_NONE);
187 : :
188 : 1 : return G_LIST_MODEL_GET_IFACE (list)->get_item_type (list);
189 : : }
190 : :
191 : : /**
192 : : * g_list_model_get_n_items:
193 : : * @list: a #GListModel
194 : : *
195 : : * Gets the number of items in @list.
196 : : *
197 : : * Depending on the model implementation, calling this function may be
198 : : * less efficient than iterating the list with increasing values for
199 : : * @position until g_list_model_get_item() returns %NULL.
200 : : *
201 : : * Returns: the number of items in @list.
202 : : *
203 : : * Since: 2.44
204 : : */
205 : : guint
206 : 37 : g_list_model_get_n_items (GListModel *list)
207 : : {
208 : 37 : g_return_val_if_fail (G_IS_LIST_MODEL (list), 0);
209 : :
210 : 37 : return G_LIST_MODEL_GET_IFACE (list)->get_n_items (list);
211 : : }
212 : :
213 : : /**
214 : : * g_list_model_get_item: (skip)
215 : : * @list: a #GListModel
216 : : * @position: the position of the item to fetch
217 : : *
218 : : * Get the item at @position.
219 : : *
220 : : * If @position is greater than the number of items in @list, %NULL is
221 : : * returned.
222 : : *
223 : : * %NULL is never returned for an index that is smaller than the length
224 : : * of the list.
225 : : *
226 : : * See also: g_list_model_get_n_items()
227 : : *
228 : : * Returns: (transfer full) (nullable): the item at @position.
229 : : *
230 : : * Since: 2.44
231 : : */
232 : : gpointer
233 : 6156 : g_list_model_get_item (GListModel *list,
234 : : guint position)
235 : : {
236 : 6156 : g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
237 : :
238 : 6156 : return G_LIST_MODEL_GET_IFACE (list)->get_item (list, position);
239 : : }
240 : :
241 : : /**
242 : : * g_list_model_get_object: (rename-to g_list_model_get_item)
243 : : * @list: a #GListModel
244 : : * @position: the position of the item to fetch
245 : : *
246 : : * Get the item at @position.
247 : : *
248 : : * If @position is greater than the number of items in @list, %NULL is
249 : : * returned.
250 : : *
251 : : * %NULL is never returned for an index that is smaller than the length
252 : : * of the list.
253 : : *
254 : : * This function is meant to be used by language bindings in place
255 : : * of g_list_model_get_item().
256 : : *
257 : : * See also: g_list_model_get_n_items()
258 : : *
259 : : * Returns: (transfer full) (nullable): the object at @position.
260 : : *
261 : : * Since: 2.44
262 : : */
263 : : GObject *
264 : 3077 : g_list_model_get_object (GListModel *list,
265 : : guint position)
266 : : {
267 : : gpointer item;
268 : :
269 : 3077 : g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
270 : :
271 : 3077 : item = g_list_model_get_item (list, position);
272 : :
273 : 3077 : return G_OBJECT (item);
274 : : }
275 : :
276 : : /**
277 : : * g_list_model_items_changed:
278 : : * @list: a #GListModel
279 : : * @position: the position at which @list changed
280 : : * @removed: the number of items removed
281 : : * @added: the number of items added
282 : : *
283 : : * Emits the #GListModel::items-changed signal on @list.
284 : : *
285 : : * This function should only be called by classes implementing
286 : : * #GListModel. It has to be called after the internal representation
287 : : * of @list has been updated, because handlers connected to this signal
288 : : * might query the new state of the list.
289 : : *
290 : : * Implementations must only make changes to the model (as visible to
291 : : * its consumer) in places that will not cause problems for that
292 : : * consumer. For models that are driven directly by a write API (such
293 : : * as #GListStore), changes can be reported in response to uses of that
294 : : * API. For models that represent remote data, changes should only be
295 : : * made from a fresh mainloop dispatch. It is particularly not
296 : : * permitted to make changes in response to a call to the #GListModel
297 : : * consumer API.
298 : : *
299 : : * Stated another way: in general, it is assumed that code making a
300 : : * series of accesses to the model via the API, without returning to the
301 : : * mainloop, and without calling other code, will continue to view the
302 : : * same contents of the model.
303 : : *
304 : : * Since: 2.44
305 : : */
306 : : void
307 : 2054 : g_list_model_items_changed (GListModel *list,
308 : : guint position,
309 : : guint removed,
310 : : guint added)
311 : : {
312 : 2054 : g_return_if_fail (G_IS_LIST_MODEL (list));
313 : :
314 : 2054 : g_signal_emit (list, g_list_model_changed_signal, 0, position, removed, added);
315 : : }
|
