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 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 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 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 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 }
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 g_list_model_get_item_type (GListModel *list)
185 {
186 g_return_val_if_fail (G_IS_LIST_MODEL (list), G_TYPE_NONE);
187
188 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 g_list_model_get_n_items (GListModel *list)
207 {
208 g_return_val_if_fail (G_IS_LIST_MODEL (list), 0);
209
210 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 g_list_model_get_item (GListModel *list,
234 guint position)
235 {
236 g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
237
238 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 g_list_model_get_object (GListModel *list,
265 guint position)
266 {
267 gpointer item;
268
269 g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
270
271 item = g_list_model_get_item (list, position);
272
273 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 g_list_model_items_changed (GListModel *list,
308 guint position,
309 guint removed,
310 guint added)
311 {
312 g_return_if_fail (G_IS_LIST_MODEL (list));
313
314 g_signal_emit (list, g_list_model_changed_signal, 0, position, removed, added);
315 }