1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.ListModelIF;
26 
27 private import gio.c.functions;
28 public  import gio.c.types;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 public  import gtkc.giotypes;
32 private import std.algorithm;
33 
34 
35 /**
36  * #GListModel is an interface that represents a mutable list of
37  * #GObjects. Its main intention is as a model for various widgets in
38  * 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 #GObject::notify signal).  Taken together
44  * with the #GListModel::items-changed signal, this provides for a list
45  * that can change its membership, and in which the members can change
46  * 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  * g_list_model_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  * g_list_model_get_n_items() returns the number of items in the list and
64  * g_list_model_get_item() returns an item at a (0-based) position. In
65  * order to allow implementations to calculate the list length lazily,
66  * you can also iterate over items: starting from 0, repeatedly call
67  * g_list_model_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 faciliate 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][g-main-context-push-thread-default]
82  * in effect at the time that the model was created.
83  */
84 public interface ListModelIF{
85 	/** Get the main Gtk struct */
86 	public GListModel* getListModelStruct(bool transferOwnership = false);
87 
88 	/** the main Gtk struct as a void* */
89 	protected void* getStruct();
90 
91 
92 	/** */
93 	public static GType getType()
94 	{
95 		return g_list_model_get_type();
96 	}
97 
98 	/**
99 	 * Get the item at @position. If @position is greater than the number of
100 	 * items in @list, %NULL is returned.
101 	 *
102 	 * %NULL is never returned for an index that is smaller than the length
103 	 * of the list.  See g_list_model_get_n_items().
104 	 *
105 	 * Params:
106 	 *     position = the position of the item to fetch
107 	 *
108 	 * Returns: the item at @position.
109 	 *
110 	 * Since: 2.44
111 	 */
112 	public ObjectG getItem(uint position);
113 
114 	/**
115 	 * Gets the type of the items in @list. All items returned from
116 	 * g_list_model_get_type() are of that type or a subtype, or are an
117 	 * implementation of that interface.
118 	 *
119 	 * The item type of a #GListModel can not change during the life of the
120 	 * model.
121 	 *
122 	 * Returns: the #GType of the items contained in @list.
123 	 *
124 	 * Since: 2.44
125 	 */
126 	public GType getItemType();
127 
128 	/**
129 	 * Gets the number of items in @list.
130 	 *
131 	 * Depending on the model implementation, calling this function may be
132 	 * less efficient than iterating the list with increasing values for
133 	 * @position until g_list_model_get_item() returns %NULL.
134 	 *
135 	 * Returns: the number of items in @list.
136 	 *
137 	 * Since: 2.44
138 	 */
139 	public uint getNItems();
140 
141 	/**
142 	 * Get the item at @position. If @position is greater than the number of
143 	 * items in @list, %NULL is returned.
144 	 *
145 	 * %NULL is never returned for an index that is smaller than the length
146 	 * of the list.  See g_list_model_get_n_items().
147 	 *
148 	 * Params:
149 	 *     position = the position of the item to fetch
150 	 *
151 	 * Returns: the object at @position.
152 	 *
153 	 * Since: 2.44
154 	 */
155 	public ObjectG getObject(uint position);
156 
157 	/**
158 	 * Emits the #GListModel::items-changed signal on @list.
159 	 *
160 	 * This function should only be called by classes implementing
161 	 * #GListModel. It has to be called after the internal representation
162 	 * of @list has been updated, because handlers connected to this signal
163 	 * might query the new state of the list.
164 	 *
165 	 * Implementations must only make changes to the model (as visible to
166 	 * its consumer) in places that will not cause problems for that
167 	 * consumer.  For models that are driven directly by a write API (such
168 	 * as #GListStore), changes can be reported in response to uses of that
169 	 * API.  For models that represent remote data, changes should only be
170 	 * made from a fresh mainloop dispatch.  It is particularly not
171 	 * permitted to make changes in response to a call to the #GListModel
172 	 * consumer API.
173 	 *
174 	 * Stated another way: in general, it is assumed that code making a
175 	 * series of accesses to the model via the API, without returning to the
176 	 * mainloop, and without calling other code, will continue to view the
177 	 * same contents of the model.
178 	 *
179 	 * Params:
180 	 *     position = the position at which @list changed
181 	 *     removed = the number of items removed
182 	 *     added = the number of items added
183 	 *
184 	 * Since: 2.44
185 	 */
186 	public void itemsChanged(uint position, uint removed, uint added);
187 
188 	/**
189 	 * This signal is emitted whenever items were added or removed to
190 	 * @list. At @position, @removed items were removed and @added items
191 	 * were added in their place.
192 	 *
193 	 * Params:
194 	 *     position = the position at which @list changed
195 	 *     removed = the number of items removed
196 	 *     added = the number of items added
197 	 *
198 	 * Since: 2.44
199 	 */
200 	gulong addOnItemsChanged(void delegate(uint, uint, uint, ListModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
201 }