/src/wrappers/gtk/library/gtk_tree_iter.e

  1indexing
  2	description: "The GtkTreeIter is the primary structure for accessing a structure. Models are expected to put a unique integer in the stamp member, and put model-specific data in the three user_data members."
  3	copyright: "[
  4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20				]"
 21	date: "$Date:$"
 22	revision: "$Revision:$"
 23
 24class GTK_TREE_ITER
 25
 26inherit
 27	C_STRUCT redefine allocate end
 28
 29insert
 30	GTK
 31	GTK_TREE_ITER_EXTERNALS rename set_stamp as set_stamp_internal end
 32	GTK_TREE_MODEL_EXTERNALS
 33	GLIB_MEMORY_ALLOCATION
 34
 35creation
 36	make,
 37	make_from_model, from_model,
 38	from_external_pointer,
 39	copy_from_pointer,
 40	as_children_of
 41
 42feature -- Creation
 43
 44	make is
 45		require
 46			gtk_initialized: gtk.is_initialized
 47		do
 48			allocate
 49		end
 50	
 51	make_from_model, from_model (a_model: GTK_TREE_MODEL) is
 52		require
 53			gtk_initialized: gtk.is_initialized
 54			valid_model: a_model/=Void
 55		do
 56			allocate
 57			tree_model := a_model
 58		ensure
 59			handle.is_not_null
 60			attached_to_model
 61		end
 62
 63	copy_from_pointer (a_ptr: POINTER) is
 64		require
 65			a_ptr.is_not_null
 66		do
 67			handle := gtk_tree_iter_copy (a_ptr)
 68		end
 69
 70	as_children_of (a_parent: GTK_TREE_ITER) is
 71			-- Create an iterator pointing to the first child of
 72			-- `a_parent'.
 73		require
 74			parent_not_void: a_parent /= Void
 75			parent_has_children: a_parent.has_children
 76		do
 77			allocate
 78			tree_model := a_parent.tree_model
 79			is_valid := (gtk_tree_model_iter_children
 80							 (tree_model.handle, handle,
 81							  a_parent.handle).to_boolean)
 82		end
 83
 84feature
 85	is_valid: BOOLEAN
 86			-- Is last action made on Current successful, making it valid?
 87
 88	start, first is
 89			-- Moves Current to the first iterator in the tree (the one
 90			-- at the path "0"). `is_valid' will be set to False if the
 91			-- tree is empty.
 92		require
 93			attached_to_model
 94		do
 95			is_valid:=(gtk_tree_model_get_iter_first (tree_model.handle, handle)).to_boolean
 96		end
 97
 98	next is
 99			-- Points Current to the node following it at the current
100			-- level. If there is no next position `is_valid' will be
101			-- False and Current is set to be invalid.
102		require
103			attached_to_model
104		do
105			is_valid:=(gtk_tree_model_iter_next (tree_model.handle,handle)).to_boolean
106		end
107
108	to_children_of (a_parent: GTK_TREE_ITER) is
109			-- Sets Current iterator to point to the first child of
110			-- `tree_model'. If parent has no children `is_valid' will be
111			-- False. Current will remain a valid node after this
112			-- function has been called. If `a_parent' is Void returns
113			-- the first node, equivalent to `first'
114		require
115			attached_to_model
116		do
117			if a_parent=Void then
118				is_valid:=(gtk_tree_model_iter_children (tree_model.handle, handle, default_pointer)).to_boolean
119			else
120				is_valid:=(gtk_tree_model_iter_children (tree_model.handle, handle, a_parent.handle)).to_boolean
121			end
122		end
123
124	has_children, has_child: BOOLEAN is
125			-- Does Current iterator have children?
126		require
127			attached_to_model
128		do
129			Result := (gtk_tree_model_iter_has_child (tree_model.handle,
130						  handle)).to_boolean
131		end
132
133	n_children, children_count: INTEGER is
134			-- Number of children that Current iter has. As a special case, if iter
135			-- is NULL, then the number of toplevel nodes is returned. (Note:
136			-- `n_children' feature name comes from C Api. `children_count' is
137			-- another name of the same feature that follow Eiffel naming style)
138		require
139			attached_to_model
140		do
141			Result := gtk_tree_model_iter_n_children (tree_model.handle, handle)
142		end
143
144	toplevel_nodes_count: INTEGER is
145			-- Number of toplevel nodes of `tree_model'
146		require
147			attached_to_model
148		do
149			Result := gtk_tree_model_iter_n_children (tree_model.handle,default_pointer)
150		end
151
152	to_nth_child_of (a_parent: like Current; an_index: INTEGER) is
153			-- Sets Current to be the child of `a_parent', using `an_index'. The
154			-- first index is 0. If n is too big, or parent has no children, iter
155			-- is set to an invalid iterator and `is_valid' will be
156			-- False. `a_parent' will remain a valid node after this function has
157			-- been called. As a special case, if `a_parent' is Void, then the nth
158			-- root node is set. `is_valid' is True, if `a_parent' has an nth
159			-- child.
160
161			-- Note: Is `to_nth_child' a better name than `to_nth_child_of'?
162		require
163			valid_index: an_index >= 0
164			attached_to_model
165		local
166			parent_ptr: POINTER
167		do
168			if a_parent/=Void then parent_ptr := a_parent.handle end
169			is_valid := (gtk_tree_model_iter_nth_child  (tree_model.handle,handle,
170							 parent_ptr, an_index)).to_boolean
171		end
172
173	to_parent (a_child: like Current) is
174			-- Sets Current to be the parent of `a_child'. If child is at the
175			-- toplevel it doesn't have a parent, then iter is set to an invalid
176			-- iterator and `is_valid' will be False. `a_child' will remain a valid
177			-- node after this function has been called.
178		require
179			valid_child: a_child /= Void
180			attached_to_model
181		do
182			is_valid := (gtk_tree_model_iter_parent (tree_model.handle,handle,
183							 a_child.handle)).to_boolean
184		end
185
186	to_string: STRING is
187			-- a representation of the iter. This string is a ':' separated list of
188			-- numbers. For example, "4:10:0:3" would be an acceptable return value
189			-- for this string.
190		require
191			attached_to_model
192		do
193			create Result.from_external (gtk_tree_model_get_string_from_iter (tree_model.handle,handle))
194			-- Note: gtk_tree_model_get_string_from_iter returns a newly-allocated
195			-- string that Must be freed with g_free. As far as I know this means
196			-- that Result shall be created without copying the string and letting
197			-- the Garbage Collector free it.
198		end
199
200	attached_to_model: BOOLEAN is
201		do
202			Result := tree_model /= Void
203		end
204
205feature {CALLBACK}
206
207	attach_to (a_model: like tree_model) is
208		require
209			not attached_to_model
210			a_model /= Void
211		do
212			tree_model := a_model
213		ensure
214			attached_to_model
215			tree_model = a_model
216		end
217
218feature  -- struct size
219	struct_size: INTEGER is
220		external "C inline use <gtk/gtk.h>"
221		alias "sizeof(GtkTreeIter)"
222		end
223
224feature {}
225
226	allocate is
227			-- There is no malloc-like function in GTK to allocate iterators.
228			-- Therefore, we allocate iterators using gtk_tree_iter_copy()
229		require
230			handle.is_null
231		do
232			handle := gtk_tree_iter_copy (dummy_iter)
233			if handle.is_null then
234				raise_exception (No_more_memory)
235			end
236		end
237
238	dummy_iter: POINTER is
239		once
240			Result := calloc (1, struct_size)
241			if Result.is_null then
242				raise_exception (No_more_memory)
243			end
244		end
245
246feature
247	dispose is
248		do
249			if handle.is_not_null then gtk_tree_iter_free (handle) end
250			handle:= default_pointer
251		end
252
253feature
254	stamp: INTEGER is
255			-- A unique stamp to catch invalid iterators
256		do
257			Result := get_stamp (handle)
258		end
259
260	set_stamp (a_stamp: INTEGER) is
261		do
262			set_stamp_internal (handle, a_stamp)
263		end
264
265	-- TODO: (if ever necessary) user_data[|2|3]
266	-- gpointer user_data; 	Model specific data
267	-- gpointer user_data2; 	Model specific data
268	-- gpointer user_data3; 	Model specific data 
269
270	tree_model: GTK_TREE_MODEL
271			-- Reference to the tree model.
272
273			-- Note: It could have been just a POINTER but in this case
274			-- we would not be sure that the model is still alive when
275			-- the iterator tries to access it.
276end