nexmon – Blame information for rev 1

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