/*

 * Copyright 2015 Lars Uebernickel

 * Copyright 2015 Ryan Lortie

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Lesser General Public

 * License as published by the Free Software Foundation; either

 * version 2.1 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General

 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.

 *

 * Authors:

 *     Lars Uebernickel <lars@uebernic.de>

 *     Ryan Lortie <desrt@desrt.ca>

 */

#include "config.h"

#include "glistmodel.h"

#include "glibintl.h"

G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)

/**

 * SECTION:glistmodel

 * @title: GListModel

 * @short_description: An interface describing a dynamic list of objects

 * @include: gio/gio.h

 * @see_also: #GListStore

 *

 * #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 faciliate 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.

 */

/**

 * GListModelInterface:

 * @g_iface: parent #GTypeInterface

 * @get_item_type: the virtual function pointer for g_list_model_get_item_type()

 * @get_n_items: the virtual function pointer for g_list_model_get_n_items()

 * @get_item: the virtual function pointer for g_list_model_get_item()

 *

 * The virtual function table for #GListModel.

 *

 * Since: 2.44

 */

/**

 * GListModelInterface::get_item:

 * @list: a #GListModel

 * @position: the position of the item to fetch

 *

 * Get the item at @position. If @position is greater than the number of

 * items in @list, %NULL is returned.

 *

 * %NULL is never returned for an index that is smaller than the length

 * of the list.  See g_list_model_get_n_items().

 *

 * Returns: (type GObject) (transfer full) (nullable): the object at @position.

 *

 * Since: 2.44

 */

/**

 * GListModel:

 *

 * #GListModel is an opaque data structure and can only be accessed

 * using the following functions.

 **/

static guint g_list_model_changed_signal;

static void

g_list_model_default_init (GListModelInterface *iface)

{

  /**

   * GListModel::items-changed:

   * @list: the #GListModel that changed

   * @position: the position at which @list changed

   * @removed: the number of items removed

   * @added: the number of items added

   *

   * This signal is emitted whenever items were added or removed to

   * @list. At @position, @removed items were removed and @added items

   * were added in their place.

   *

   * Since: 2.44

   */

  g_list_model_changed_signal = g_signal_new (I_("items-changed"),

                                              G_TYPE_LIST_MODEL,

                                              G_SIGNAL_RUN_LAST,

                                              0,

                                              NULL, NULL,

                                              g_cclosure_marshal_generic,

                                              G_TYPE_NONE,

                                              3, G_TYPE_UINT, G_TYPE_UINT, G_TYPE_UINT);

}

/**

 * g_list_model_get_item_type:

 * @list: a #GListModel

 *

 * Gets the type of the items in @list. All items returned from

 * g_list_model_get_type() are of that type or a subtype, or are an

 * implementation of that interface.

 *

 * The item type of a #GListModel can not change during the life of the

 * model.

 *

 * Returns: the #GType of the items contained in @list.

 *

 * Since: 2.44

 */

GType

g_list_model_get_item_type (GListModel *list)

{

  g_return_val_if_fail (G_IS_LIST_MODEL (list), G_TYPE_NONE);

  return G_LIST_MODEL_GET_IFACE (list)->get_item_type (list);

}

/**

 * g_list_model_get_n_items:

 * @list: a #GListModel

 *

 * Gets the number of items in @list.

 *

 * Depending on the model implementation, calling this function may be

 * less efficient than iterating the list with increasing values for

 * @position until g_list_model_get_item() returns %NULL.

 *

 * Returns: the number of items in @list.

 *

 * Since: 2.44

 */

guint

g_list_model_get_n_items (GListModel *list)

{

  g_return_val_if_fail (G_IS_LIST_MODEL (list), 0);

  return G_LIST_MODEL_GET_IFACE (list)->get_n_items (list);

}

/**

 * g_list_model_get_item: (skip)

 * @list: a #GListModel

 * @position: the position of the item to fetch

 *

 * Get the item at @position. If @position is greater than the number of

 * items in @list, %NULL is returned.

 *

 * %NULL is never returned for an index that is smaller than the length

 * of the list.  See g_list_model_get_n_items().

 *

 * Returns: (transfer full) (nullable): the item at @position.

 *

 * Since: 2.44

 */

gpointer

g_list_model_get_item (GListModel *list,

                       guint       position)

{

  g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);

  return G_LIST_MODEL_GET_IFACE (list)->get_item (list, position);

}

/**

 * g_list_model_get_object: (rename-to g_list_model_get_item)

 * @list: a #GListModel

 * @position: the position of the item to fetch

 *

 * Get the item at @position. If @position is greater than the number of

 * items in @list, %NULL is returned.

 *

 * %NULL is never returned for an index that is smaller than the length

 * of the list.  See g_list_model_get_n_items().

 *

 * Returns: (transfer full) (nullable): the object at @position.

 *

 * Since: 2.44

 */

GObject *

g_list_model_get_object (GListModel *list,

                         guint       position)

{

  gpointer item;

  g_return_val_if_fail (G_IS_LIST_MODEL (list), NULL);

  item = g_list_model_get_item (list, position);

  return G_OBJECT (item);

}

/**

 * g_list_model_items_changed:

 * @list: a #GListModel

 * @position: the position at which @list changed

 * @removed: the number of items removed

 * @added: the number of items added

 *

 * Emits the #GListModel::items-changed signal on @list.

 *

 * This function should only be called by classes implementing

 * #GListModel. It has to be called after the internal representation

 * of @list has been updated, because handlers connected to this signal

 * might query the new state of the list.

 *

 * Implementations must only make changes to the model (as visible to

 * its consumer) in places that will not cause problems for that

 * consumer.  For models that are driven directly by a write API (such

 * as #GListStore), changes can be reported in response to uses of that

 * API.  For models that represent remote data, changes should only be

 * made from a fresh mainloop dispatch.  It is particularly not

 * permitted to make changes in response to a call to the #GListModel

 * consumer API.

 *

 * Stated another way: in general, it is assumed that code making a

 * series of accesses to the model via the API, without returning to the

 * mainloop, and without calling other code, will continue to view the

 * same contents of the model.

 *

 * Since: 2.44

 */

void

g_list_model_items_changed (GListModel *list,

                            guint       position,

                            guint       removed,

                            guint       added)

{

  g_return_if_fail (G_IS_LIST_MODEL (list));

  g_signal_emit (list, g_list_model_changed_signal, 0, position, removed, added);

}