/src/wrappers/gtk/library/gtk_tree_store.e

  1indexing
  2	description: "GtkTreeStore -- A tree-like data structure that can be used with the GtkTreeView."
  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
 22class GTK_TREE_STORE
 23	-- The GtkTreeStore object is a list model for use with a
 24	-- GtkTreeView widget. It implements the GtkTreeModel interface,
 25	-- and consequentialy, can use all of the methods available
 26	-- there. It also implements the GtkTreeSortable interface so it
 27	-- can be sorted by the view. Finally, it also implements the tree
 28	-- drag and drop interfaces.
 29	
 30inherit
 31	GTK_TREE_MODEL 
 32	GTK_TREE_SORTABLE 
 33	GTK_TREE_DRAG_SOURCE
 34	GTK_TREE_DRAG_DEST
 35
 36insert
 37	GTK_STORE_SETTERS
 38	GTK_TREE_STORE_EXTERNALS
 39
 40creation make, from_external_pointer
 41
 42feature {} -- Creation
 43
 44	make (some_columns: ARRAY[INTEGER]) is
 45			-- Creates a new tree store. `some_columns' is an array of integers; each
 46			-- integer is the G_TYPE of an actual column. Note that only types
 47			-- derived from standard GObject fundamental types are supported.
 48		require gtk_initialized: gtk.is_initialized
 49		do
 50			from_external_pointer (gtk_tree_store_newv (some_columns.count, some_columns.to_external))
 51		end
 52	
 53feature -- Generic setter
 54	set_value (an_iterator: GTK_TREE_ITER; a_column: INTEGER; a_value: G_VALUE) is
 55			-- Sets the data in the cell specified by `an_iterator' and
 56			-- `a_column'. The type of `a_value' must be convertible to the type of
 57			-- the column.
 58		
 59			-- `an_iterator': A valid GtkTreeIter for the row being modified
 60			-- `a_column' : column number to modify
 61			-- `a_value' : new value for the cell
 62		require
 63			valid_iterator: an_iterator/=Void
 64			valid_value: a_value /= Void -- and then Eiffelize "The type of
 65			-- `a_value' must be convertible to the type of the column."
 66		do
 67			gtk_tree_store_set_value (handle, an_iterator.handle, a_column, a_value.handle)
 68		end
 69
 70	is_last_iterator_valid: BOOLEAN
 71			-- Is the last iterator passed as an argument still valid?
 72
 73	remove (an_iterator: GTK_TREE_ITER) is
 74			-- Removes the given row from the list store. After being removed,
 75			-- `an_iterator' is set to be the next valid row, or invalidated if it
 76			-- pointed to the last row in the list store; in this case
 77			-- `is_last_iterator_valid' will be False
 78		require
 79			valid_iterator: an_iterator/=Void
 80		do
 81			is_last_iterator_valid := gtk_tree_store_remove (handle,an_iterator.handle).to_boolean
 82		end
 83
 84	put (an_iterator, a_parent: GTK_TREE_ITER; a_position: INTEGER) is
 85			-- Creates a new row at position. If `a_parent' is non-NULL, 
 86			-- then the row will be made a child of parent. Otherwise,
 87			-- the row will be created at the toplevel. If `a_position' is
 88			-- larger than the number of rows at that level, then the
 89			-- new row will be inserted to the end of the list. `iter' will
 90			-- be changed to point to this new row. The row will be empty
 91			-- after this function is called. To fill in values, you need
 92			-- to call some of the set_* methods.
 93		require
 94			valid_iterator: an_iterator/=Void
 95		local
 96			parent_pointer: POINTER
 97		do
 98			if a_parent /= Void then parent_pointer := a_parent.handle end
 99			gtk_tree_store_insert (handle, an_iterator.handle, a_parent.handle, a_position)
100		end
101
102	put_before, insert_before  (an_iterator, a_parent, a_sibling: GTK_TREE_ITER) is
103			-- Inserts a new row before `a_sibling'. If `a_sibling' is Void,
104			-- then the row will be appended to `a_parent''s children. If
105			-- `a_parent' and `a_sibling' are Void, then the row will be
106			-- appended to the toplevel. If both `a_sibling' and `a_parent'
107			-- are set, then `a_parent' must be the parent of `a_sibling'.
108			-- When `a_sibling' is set, `a_parent' is optional.
109			--
110			-- `an_iterator' will be changed to point to this new row.
111			-- The row will be empty after this function is called.
112			-- To fill in values, you need to call some of the set_* methods.
113		require
114			valid_iterator: an_iterator /= Void
115		local
116			parent_pointer, sibling_pointer: POINTER
117		do
118			if a_parent /= Void then parent_pointer := a_parent.handle end
119			if a_sibling /= Void then sibling_pointer := a_sibling.handle end
120			gtk_tree_store_insert_before (handle, an_iterator.handle,
121										 parent_pointer, sibling_pointer)
122		end
123
124	put_after, insert_after (an_iterator, a_parent, a_sibling: GTK_TREE_ITER) is
125			-- Inserts a new row after `a_sibling'. If `a_sibling' is Void,
126			-- then the row will be prepended to `a_parent''s children.
127			-- If `a_parent' and `a_sibling' are Void, then the row will
128			-- be prepended to the toplevel. If both `a_sibling' and
129			-- `a_parent' are set, then `a_parent' must be the parent of
130			-- `a_sibling'. When `a_sibling' is set, `a_parent' is optional.
131			--
132			-- `an_iterator' will be changed to point to this new row.
133			-- The row will be empty after this function is called.
134			-- To fill in values, you need to call some of the set_* methods.
135		require
136			valid_iterator: an_iterator /= Void
137		local
138			parent_pointer, sibling_pointer: POINTER
139		do
140			if a_parent /= Void then parent_pointer := a_parent.handle end
141			if a_sibling /= Void then sibling_pointer := a_sibling.handle end
142			gtk_tree_store_insert_after (handle, an_iterator.handle,
143										 parent_pointer, sibling_pointer)
144		end
145
146	insert_with_values (an_iterator, a_parent: GTK_TREE_ITER;
147							  a_position: INTEGER;
148							  some_columns: ARRAY[INTEGER];
149							  some_values: ARRAY[G_VALUE]) is
150			-- Creates a new row at `a_position'. `an_iterator' will be
151			-- changed to point to this new row. If `a_position' is larger
152			-- than the number of rows on the list, then the new row will
153			-- be appended to the list. The row will be filled with the
154			-- values given to this function.
155
156			-- Calling store.insert_with_values (iter, parent, position,
157			-- cols, vals) has the same effect as calling
158
159			-- store.put (iter, parent, position)
160			-- store.set (iter, cols, vals);
161
162			-- with the difference that the former will only emit a
163			-- row_inserted signal, while the latter will emit
164			-- row_inserted, row_changed and if the tree store is sorted,
165			-- rows_reordered.  Since emitting the rows_reordered signal
166			-- repeatedly can affect the performance of the program,
167			-- insert_with_values should generally be preferred when
168			-- inserting rows in a sorted tree store.
169
170			-- `some_columns' contains the column numbers; each column
171			-- will be set with the corresponding value in `some_values'.
172		require columns_n_equals_values_n: some_columns.count = some_values.count
173		do
174			not_yet_implemented
175			-- TODO: some_values.to_external is an array of pointers to the Eiffel wrappers!!!
176			gtk_tree_store_insert_with_valuesv (handle, an_iterator.handle,
177															a_parent.handle,
178															a_position,
179															-- gint *columns an array of column numbers
180															some_columns.to_external,
181															-- GValue *values an array of GValues
182															some_values.to_external,
183															-- gint n_values the length of the
184															-- columns and values arrays
185															some_values.count
186														  )
187		end
188
189	add_first, prepend (an_iterator, a_parent: GTK_TREE_ITER) is
190			-- Prepends a new row to tree store. If `a_parent' is non-Void,
191			-- then it will prepend the new row before the first child of
192			-- `a_parent', otherwise it will prepend a row to the top
193			-- level. `an_iterator' will be changed to point to this new
194			-- row. The row will be empty after this function is called.
195			-- To fill in values, you need to call some set_* method.
196		require valid_iterator: an_iterator /= Void
197		local
198			parent_pointer: POINTER
199		do
200			if a_parent /= Void then parent_pointer := a_parent.handle end
201			gtk_tree_store_prepend (handle, an_iterator.handle, parent_pointer)
202		end
203
204	add_last, append (an_iterator, a_parent: GTK_TREE_ITER) is
205			-- Appends a new row to tree store. If `a_parent' is non-Void,
206			-- then it will append the new row after the last child of
207			-- `a_parent', otherwise it will append a row to the top level.
208			-- `an_iterator' will be changed to point to this new row. The row will
209			-- be empty after this function is called. To fill in values,
210			-- you need to call some `set_*' feature
211		require iterator_not_void: an_iterator /= Void
212		local
213			parent_pointer: POINTER
214		do
215			if a_parent /= Void then parent_pointer := a_parent.handle end
216			gtk_tree_store_append  (handle, an_iterator.handle, parent_pointer)
217		end
218
219	is_ancestor(an_iterator, a_descendant: GTK_TREE_ITER): BOOLEAN is
220			-- Returns True if `an_iterator' is an ancestor of `a_descendant'.
221			-- That is, `an_iterator' is the parent (or grandparent or
222			-- great-grandparent or ...) of `a_descendant).
223		require
224			valid_iterators: an_iterator /= Void and a_descendant /= Void
225		do
226			Result := gtk_tree_store_is_ancestor(handle, an_iterator.handle,
227								 a_descendant.handle).to_boolean
228		end
229
230	iter_depth(an_iterator: GTK_TREE_ITER): INTEGER is
231			-- Returns the depth of `an_iterator'. This will be 0 for
232			-- anything on the root level, 1 for anything down a level, etc.
233		require
234			valid_iterators: an_iterator /= Void
235		do
236			Result := gtk_tree_store_iter_depth(handle, an_iterator.handle)
237		end
238
239	clear is
240			-- Removes all rows from the tree store.
241		do
242			gtk_tree_store_clear (handle)
243		end
244
245	is_iterator_valid (an_iterator: GTK_TREE_ITER): BOOLEAN is
246			-- Is `an_iterator' valid for Current GtkTreeStore?
247			--
248			-- Warning: this query is slow. Only use it for debugging
249			-- and/or testing purposes.
250		require
251			valid_iterator: an_iterator/=Void
252		do
253			Result:=(gtk_tree_store_iter_is_valid(handle,an_iterator.handle)).to_boolean
254		end
255
256	reorder (a_parent: GTK_TREE_ITER; a_new_order: ARRAY[INTEGER]) is
257			-- Reorders the children of `a_parent' to follow the order
258			-- indicated by `a_new_order'. Note that this function only
259			-- works with unsorted stores.
260			-- `a_new_order' is the array of integers
261			-- mapping the new position of each child to its old position
262			-- before the re-ordering, i.e. a_new_order.item(newpos) =
263			-- oldpos.
264		require
265			unsorted_store: not is_sorted
266			valid_order: a_new_order /= Void
267		do
268			gtk_tree_store_reorder (handle, a_parent.handle, a_new_order.to_external)
269		end
270
271	swap (a, b: GTK_TREE_ITER) is
272			-- Swaps `a' and `b' in the same level of tree store.
273			-- Note that this function only works with unsorted stores.
274		require
275			unsorted_store: not is_sorted
276			valid_iterators: a /= Void and b /= Void
277		do
278			gtk_tree_store_swap (handle, a.handle, b.handle)
279		end
280
281	move_before (an_iterator, a_position: GTK_TREE_ITER) is
282			-- Moves `an_iterator' in tree store to the position before
283			-- `a_position'. `an_iterator' and `a_position' should be in
284			-- the same level. Note that this function only works with
285			-- unsorted stores.
286		require
287			unsorted_store: not is_sorted
288			valid_iterator: an_iterator/=Void
289			valid_position: a_position/=Void
290		do
291			gtk_tree_store_move_before (handle,an_iterator.handle, a_position.handle)
292		end
293
294	move_last  (an_iterator: GTK_TREE_ITER) is
295			-- Moves `an_iterator' in store to the end of the level. Note that this
296			-- function only works with unsorted stores.
297		require
298			unsorted_store: not is_sorted
299			valid_iterator: an_iterator /= Void
300		do
301			gtk_tree_store_move_before (handle, an_iterator.handle, default_pointer)
302		end
303
304	move_after  (an_iterator, a_position: GTK_TREE_ITER) is
305			-- Moves `an_iterator' in store to the position after
306			-- `a_position'. Note that this function only works with unsorted stores. 
307		require
308			unsorted_store: not is_sorted
309			valid_iterator: an_iterator/=Void
310			valid_position: a_position/=Void
311		do
312			gtk_tree_store_move_after (handle, an_iterator.handle, a_position.handle)
313		end
314
315	move_first  (an_iterator: GTK_TREE_ITER) is
316			-- Moves item pointed to by `an_iterator' to the start of the
317			-- level. Note that this function only works with unsorted stores.
318		require
319			unsorted_store: not is_sorted
320			valid_iterator: an_iterator/=Void
321		do
322			gtk_tree_store_move_after (handle, an_iterator.handle, default_pointer)
323		end
324feature -- struct size
325	struct_size: INTEGER is
326		external "C inline use <gtk/gtk.h>"
327		alias "sizeof(GtkTreeStore)"
328		end
329
330-- TODO:
331-- --             GtkTreeStore;
332-- -- GtkTreeStore* gtk_tree_store_newv           (gint n_columns,
333
334-- -- void        gtk_tree_store_set              (GtkTreeStore *tree_store,
335-- --                                              GtkTreeIter *iter,
336-- --                                              ...);
337-- -- void        gtk_tree_store_set_valist       (GtkTreeStore *tree_store,
338-- --                                              GtkTreeIter *iter,
339-- --                                              va_list var_args);
340end