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 private import std.algorithm;
32 
33 
34 /**
35  * #GListModel is an interface that represents a mutable list of
36  * #GObjects. Its main intention is as a model for various widgets in
37  * user interfaces, such as list views, but it can also be used as a
38  * convenient method of returning lists of data, with support for
39  * updates.
40  * 
41  * Each object in the list may also report changes in itself via some
42  * mechanism (normally the #GObject::notify signal).  Taken together
43  * with the #GListModel::items-changed signal, this provides for a list
44  * that can change its membership, and in which the members can change
45  * their individual properties.
46  * 
47  * A good example would be the list of visible wireless network access
48  * points, where each access point can report dynamic properties such as
49  * signal strength.
50  * 
51  * It is important to note that the #GListModel itself does not report
52  * changes to the individual items.  It only reports changes to the list
53  * membership.  If you want to observe changes to the objects themselves
54  * then you need to connect signals to the objects that you are
55  * interested in.
56  * 
57  * All items in a #GListModel are of (or derived from) the same type.
58  * g_list_model_get_item_type() returns that type.  The type may be an
59  * interface, in which case all objects in the list must implement it.
60  * 
61  * The semantics are close to that of an array:
62  * g_list_model_get_n_items() returns the number of items in the list and
63  * g_list_model_get_item() returns an item at a (0-based) position. In
64  * order to allow implementations to calculate the list length lazily,
65  * you can also iterate over items: starting from 0, repeatedly call
66  * g_list_model_get_item() until it returns %NULL.
67  * 
68  * An implementation may create objects lazily, but must take care to
69  * return the same object for a given position until all references to
70  * it are gone.
71  * 
72  * On the other side, a consumer is expected only to hold references on
73  * objects that are currently "user visible", in order to facilitate the
74  * maximum level of laziness in the implementation of the list and to
75  * reduce the required number of signal connections at a given time.
76  * 
77  * This interface is intended only to be used from a single thread.  The
78  * thread in which it is appropriate to use it depends on the particular
79  * implementation, but typically it will be from the thread that owns
80  * the [thread-default main context][g-main-context-push-thread-default]
81  * in effect at the time that the model was created.
82  */
83 public interface ListModelIF{
84 	/** Get the main Gtk struct */
85 	public GListModel* getListModelStruct(bool transferOwnership = false);
86 
87 	/** the main Gtk struct as a void* */
88 	protected void* getStruct();
89 
90 
91 	/** */
92 	public static GType getType()
93 	{
94 		return g_list_model_get_type();
95 	}
96 
97 	/**
98 	 * Get the item at @position. If @position is greater than the number of
99 	 * items in @list, %NULL is returned.
100 	 *
101 	 * %NULL is never returned for an index that is smaller than the length
102 	 * of the list.  See g_list_model_get_n_items().
103 	 *
104 	 * Params:
105 	 *     position = the position of the item to fetch
106 	 *
107 	 * Returns: the item at @position.
108 	 *
109 	 * Since: 2.44
110 	 */
111 	public void* getItem(uint position);
112 
113 	/**
114 	 * Gets the type of the items in @list. All items returned from
115 	 * g_list_model_get_type() are of that type or a subtype, or are an
116 	 * implementation of that interface.
117 	 *
118 	 * The item type of a #GListModel can not change during the life of the
119 	 * model.
120 	 *
121 	 * Returns: the #GType of the items contained in @list.
122 	 *
123 	 * Since: 2.44
124 	 */
125 	public GType getItemType();
126 
127 	/**
128 	 * Gets the number of items in @list.
129 	 *
130 	 * Depending on the model implementation, calling this function may be
131 	 * less efficient than iterating the list with increasing values for
132 	 * @position until g_list_model_get_item() returns %NULL.
133 	 *
134 	 * Returns: the number of items in @list.
135 	 *
136 	 * Since: 2.44
137 	 */
138 	public uint getNItems();
139 
140 	/**
141 	 * Get the item at @position. If @position is greater than the number of
142 	 * items in @list, %NULL is returned.
143 	 *
144 	 * %NULL is never returned for an index that is smaller than the length
145 	 * of the list.  See g_list_model_get_n_items().
146 	 *
147 	 * Params:
148 	 *     position = the position of the item to fetch
149 	 *
150 	 * Returns: the object at @position.
151 	 *
152 	 * Since: 2.44
153 	 */
154 	public ObjectG getObject(uint position);
155 
156 	/**
157 	 * Emits the #GListModel::items-changed signal on @list.
158 	 *
159 	 * This function should only be called by classes implementing
160 	 * #GListModel. It has to be called after the internal representation
161 	 * of @list has been updated, because handlers connected to this signal
162 	 * might query the new state of the list.
163 	 *
164 	 * Implementations must only make changes to the model (as visible to
165 	 * its consumer) in places that will not cause problems for that
166 	 * consumer.  For models that are driven directly by a write API (such
167 	 * as #GListStore), changes can be reported in response to uses of that
168 	 * API.  For models that represent remote data, changes should only be
169 	 * made from a fresh mainloop dispatch.  It is particularly not
170 	 * permitted to make changes in response to a call to the #GListModel
171 	 * consumer API.
172 	 *
173 	 * Stated another way: in general, it is assumed that code making a
174 	 * series of accesses to the model via the API, without returning to the
175 	 * mainloop, and without calling other code, will continue to view the
176 	 * same contents of the model.
177 	 *
178 	 * Params:
179 	 *     position = the position at which @list changed
180 	 *     removed = the number of items removed
181 	 *     added = the number of items added
182 	 *
183 	 * Since: 2.44
184 	 */
185 	public void itemsChanged(uint position, uint removed, uint added);
186 
187 	/**
188 	 * This signal is emitted whenever items were added to or removed
189 	 * from @list. At @position, @removed items were removed and @added
190 	 * items were added in their place.
191 	 *
192 	 * Note: If @removed != @added, the positions of all later items
193 	 * in the model change.
194 	 *
195 	 * Params:
196 	 *     position = the position at which @list changed
197 	 *     removed = the number of items removed
198 	 *     added = the number of items added
199 	 *
200 	 * Since: 2.44
201 	 */
202 	gulong addOnItemsChanged(void delegate(uint, uint, uint, ListModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
203 }