gio/glistmodel.c

   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.1 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  * GListModelInterface::get_item:
 100  * @list: a #GListModel
 101  * @position: the position of the item to fetch
 102  *
 103  * Get the item at @position. If @position is greater than the number of
 104  * items in @list, %NULL is returned.
 105  *
 106  * %NULL is never returned for an index that is smaller than the length
 107  * of the list.  See g_list_model_get_n_items().
 108  *
 109  * Returns: (type GObject) (transfer full) (nullable): the object at @position.
 110  *
 111  * Since: 2.44
 112  */
 113
 114 /**
 115  * GListModel:
 116  *
 117  * #GListModel is an opaque data structure and can only be accessed
 118  * using the following functions.
 119  **/
 120
 121 static guint g_list_model_changed_signal;
 122
 123 static void
 124 g_list_model_default_init (GListModelInterface *iface)
 125 {
 126   /**
 127    * GListModel::items-changed:
 128    * @list: the #GListModel that changed
 129    * @position: the position at which @list changed
 130    * @removed: the number of items removed
 131    * @added: the number of items added
 132    *
 133    * This signal is emitted whenever items were added or removed to
 134    * @list. At @position, @removed items were removed and @added items
 135    * were added in their place.
 136    *
 137    * Since: 2.44
 138    */
 139   g_list_model_changed_signal = g_signal_new (I_("items-changed"),
 140                                               G_TYPE_LIST_MODEL,
 141                                               G_SIGNAL_RUN_LAST,
 142                                               0,
 143                                               NULL, NULL,
 144                                               g_cclosure_marshal_generic,
 145                                               G_TYPE_NONE,
 146                                               3, G_TYPE_UINT, G_TYPE_UINT, G_TYPE_UINT);
 147 }
 148
 149 /**
 150  * g_list_model_get_item_type:
 151  * @list: a #GListModel
 152  *
 153  * Gets the type of the items in @list. All items returned from
 154  * g_list_model_get_type() are of that type or a subtype, or are an
 155  * implementation of that interface.
 156  *
 157  * The item type of a #GListModel can not change during the life of the
 158  * model.
 159  *
 160  * Returns: the #GType of the items contained in @list.
 161  *
 162  * Since: 2.44
 163  */
 164 GType
 165 g_list_model_get_item_type (GListModel *list)
 166 {
 167   g_return_val_if_fail (G_IS_LIST_MODEL (list), G_TYPE_NONE);
 168
 169   return G_LIST_MODEL_GET_IFACE (list)->get_item_type (list);
 170 }
 171
 172 /**
 173  * g_list_model_get_n_items:
 174  * @list: a #GListModel
 175  *
 176  * Gets the number of items in @list.
 177  *
 178  * Depending on the model implementation, calling this function may be
 179  * less efficient than iterating the list with increasing values for
 180  * @position until g_list_model_get_item() returns %NULL.
 181  *
 182  * Returns: the number of items in @list.
 183  *
 184  * Since: 2.44
 185  */
 186 guint
 187 g_list_model_get_n_items (GListModel *list)
 188 {
 189   g_return_val_if_fail (G_IS_LIST_MODEL (list), 0);
 190
 191   return G_LIST_MODEL_GET_IFACE (list)->get_n_items (list);
 192 }
 193
 194 /**
 195  * g_list_model_get_item: (skip)
 196  * @list: a #GListModel
 197  * @position: the position of the item to fetch
 198  *
 199  * Get the item at @position. If @position is greater than the number of
 200  * items in @list, %NULL is returned.
 201  *
 202  * %NULL is never returned for an index that is smaller than the length
 203  * of the list.  See g_list_model_get_n_items().
 204  *
 205  * Returns: (transfer full) (nullable): the item at @position.
 206  *
 207  * Since: 2.44
 208  */
 209 gpointer
 210 g_list_model_get_item (GListModel *list,
 211                        guint       position)
 212 {
 213   g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
 214
 215   return G_LIST_MODEL_GET_IFACE (list)->get_item (list, position);
 216 }
 217
 218 /**
 219  * g_list_model_get_object: (rename-to g_list_model_get_item)
 220  * @list: a #GListModel
 221  * @position: the position of the item to fetch
 222  *
 223  * Get the item at @position. If @position is greater than the number of
 224  * items in @list, %NULL is returned.
 225  *
 226  * %NULL is never returned for an index that is smaller than the length
 227  * of the list.  See g_list_model_get_n_items().
 228  *
 229  * Returns: (transfer full) (nullable): the object at @position.
 230  *
 231  * Since: 2.44
 232  */
 233 GObject *
 234 g_list_model_get_object (GListModel *list,
 235                          guint       position)
 236 {
 237   gpointer item;
 238
 239   g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);
 240
 241   item = g_list_model_get_item (list, position);
 242
 243   return G_OBJECT (item);
 244 }
 245
 246 /**
 247  * g_list_model_items_changed:
 248  * @list: a #GListModel
 249  * @position: the position at which @list changed
 250  * @removed: the number of items removed
 251  * @added: the number of items added
 252  *
 253  * Emits the #GListModel::items-changed signal on @list.
 254  *
 255  * This function should only be called by classes implementing
 256  * #GListModel. It has to be called after the internal representation
 257  * of @list has been updated, because handlers connected to this signal
 258  * might query the new state of the list.
 259  *
 260  * Implementations must only make changes to the model (as visible to
 261  * its consumer) in places that will not cause problems for that
 262  * consumer.  For models that are driven directly by a write API (such
 263  * as #GListStore), changes can be reported in response to uses of that
 264  * API.  For models that represent remote data, changes should only be
 265  * made from a fresh mainloop dispatch.  It is particularly not
 266  * permitted to make changes in response to a call to the #GListModel
 267  * consumer API.
 268  *
 269  * Stated another way: in general, it is assumed that code making a
 270  * series of accesses to the model via the API, without returning to the
 271  * mainloop, and without calling other code, will continue to view the
 272  * same contents of the model.
 273  *
 274  * Since: 2.44
 275  */
 276 void
 277 g_list_model_items_changed (GListModel *list,
 278                             guint       position,
 279                             guint       removed,
 280                             guint       added)
 281 {
 282   g_return_if_fail (G_IS_LIST_MODEL (list));
 283
 284   g_signal_emit (list, g_list_model_changed_signal, 0, position, removed, added);
 285 }