/src/wrappers/gtk/library/gtk_list_store.e

  1indexing
  2	description: "GtkListStore -- A list-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_LIST_STORE
 23	-- The GtkListStore 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
 30	-- The GtkListStore can accept most GObject types as a column type,
 31	-- though it can't accept all custom types. Internally, it will
 32	-- keep a copy of data passed in (such as a string or a boxed
 33	-- pointer). Columns that accept GObjects are handled a little
 34	-- differently. The GtkListStore will keep a reference to the
 35	-- object instead of copying the value. As a result, if the object
 36	-- is modified, it is up to the application writer to call
 37	-- gtk_tree_model_row_changed to emit the "row_changed"
 38	-- signal. This most commonly affects lists with GdkPixbufs stored.
 39
 40	-- Example 5. Creating a simple list store. TODO: Eiffelize this example
 41
 42	-- enum { COLUMN_STRING, COLUMN_INT, COLUMN_BOOLEAN, N_COLUMNS };
 43
 44	-- {
 45	--   GtkListStore *list_store;
 46	--   GtkTreePath *path;
 47	--   GtkTreeIter iter;
 48	--   gint i;
 49			
 50	-- list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING,
 51	--                                    G_TYPE_INT, G_TYPE_BOOLEAN);
 52			
 53	--   for (i = 0; i < 10; i++) {
 54	--       gchar *some_data;
 55			
 56	--       some_data = get_some_data (i);
 57			
 58	--       /* Add a new row to the model */
 59	--       gtk_list_store_append (list_store, &iter);
 60	--       gtk_list_store_set (list_store, &iter,
 61	--                           COLUMN_STRING, some_data,
 62	--                           COLUMN_INT, i,
 63	--                           COLUMN_BOOLEAN,  FALSE,
 64	--                           -1);
 65			
 66	--       /* As the store will keep a copy of the string internally, we
 67	--        * free some_data.
 68	--        */
 69	--       g_free (some_data);
 70	--     }
 71			
 72	--   /* Modify a particular row */
 73	--   path = gtk_tree_path_new_from_string ("4");
 74	--   gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
 75	--                            &iter,
 76	--                            path);
 77	--   gtk_tree_path_free (path);
 78	--   gtk_list_store_set (list_store, &iter,
 79	--                       COLUMN_BOOLEAN, TRUE,
 80	--                       -1);
 81	-- }
 82	
 83	-- Performance Considerations: Internally, the GtkListStore was
 84	-- implemented with a linked list with a tail pointer prior to GTK+
 85	-- 2.6. As a result, it was fast at data insertion and deletion,
 86	-- and not fast at random data access. The GtkListStore sets the
 87	-- GTK_TREE_MODEL_ITERS_PERSIST flag, which means that GtkTreeIters
 88	-- can be cached while the row exists. Thus, if access to a
 89	-- particular row is needed often and your code is expected to run
 90	-- on older versions of GTK+, it is worth keeping the iter around.
 91
 92	--	Note: GTK_LIST_STORE has some features that are deliberately similar to COLLECTION's
 93
 94inherit
 95	GTK_TREE_MODEL
 96	GTK_TREE_SORTABLE
 97	GTK_TREE_DRAG_SOURCE
 98	GTK_TREE_DRAG_DEST
 99
100insert
101	GTK_STORE_SETTERS
102	GTK_LIST_STORE_EXTERNALS
103
104creation make, from_external_pointer
105
106feature {} -- Creation
107
108	make (some_columns: ARRAY[INTEGER]) is
109			-- Creates a new list store. `some_columns' is a list of integers; each
110			-- integer is the G_TYPE of an actual column. Note that only types
111			-- derived from standard GObject fundamental types are supported.
112			
113			-- As an example, make (<<g_type_int, g_type_string, gdk_type_pixbuf>>)
114			-- will create a new GtkListStore with three columns, of type int,
115			-- string and GdkPixbuf respectively.
116			
117			-- TODO: make this more eiffelish
118			
119			-- Note: ARRAY seems to be the more general class that fits the
120			-- task. Feel free to change it. Paolo 2006-02-22
121		require gtk_initialized: gtk.is_initialized
122		do
123			from_external_pointer (gtk_list_store_newv (some_columns.count, some_columns.to_external))
124		end
125
126feature {} -- Unwrapped code
127	
128	-- gtk_list_store_set_column_types ()
129	
130	-- void gtk_list_store_set_column_types (GtkListStore *list_store, gint
131	-- n_columns, GType *types);
132	
133	-- This function is meant primarily for GObjects that inherit from
134	-- GtkListStore, and should only be used when constructing a new
135	-- GtkListStore. It will not function after a row has been added, or a method
136	-- on the GtkTreeModel interface is called.
137
138	-- list_store : 	A GtkListStore
139	-- n_columns : 	Number of columns for the list store
140	-- types : 	An array length n of GTypes
141	
142	-- gtk_list_store_set ()
143
144	-- void gtk_list_store_set (GtkListStore *list_store, GtkTreeIter *iter,
145	-- ...);
146
147	-- Sets the value of one or more cells in the row referenced by iter. The
148	-- variable argument list should contain integer column numbers, each column
149	-- number followed by the value to be set. The list is terminated by a
150	-- -1. For example, to set column 0 with type G_TYPE_STRING to "Foo", you
151	-- would write gtk_list_store_set (store, iter, 0, "Foo", -1).
152
153	-- list_store : 	a GtkListStore
154	-- iter : 	row iterator
155	-- ... : 	pairs of column number and value, terminated with -1
156	
157	-- gtk_list_store_set_valist ()
158	
159	-- void gtk_list_store_set_valist (GtkListStore *list_store, GtkTreeIter
160	-- *iter, va_list var_args);
161
162	-- See gtk_list_store_set(); this version takes a va_list for use by language
163	-- bindings.
164
165	-- list_store : 	A GtkListStore
166	-- iter : 	A valid GtkTreeIter for the row being modified
167	-- var_args : 	va_list of column/value pairs
168
169feature -- Generic setter
170
171	set_value (an_iterator: GTK_TREE_ITER; a_column: INTEGER; a_value: G_VALUE) is
172			-- Sets the data in the cell specified by `an_iterator' and
173			-- `a_column'. The type of `a_value' must be convertible to the type of
174			-- the column.
175		
176			-- `an_iterator': A valid GtkTreeIter for the row being modified
177			-- `a_column' : column number to modify
178			-- `a_value' : new value for the cell
179		require
180			valid_iterator: an_iterator/=Void
181			valid_value: a_value /= Void -- and then Eiffelize "The type of
182			-- `a_value' must be convertible to the type of the column."
183		do
184			gtk_list_store_set_value (handle, an_iterator.handle, a_column, a_value.handle)
185		end
186
187	is_last_iterator_valid: BOOLEAN
188			-- Is the last iterator passed as an argument still valid?
189
190	remove (an_iterator: GTK_TREE_ITER) is
191			-- Removes the given row from the list store. After being removed,
192			-- `an_iterator' is set to be the next valid row, or invalidated if it
193			-- pointed to the last row in the list store; in this case
194			-- `is_last_iterator_valid' will be False
195		require
196			valid_iterator: an_iterator/=Void
197		do
198			is_last_iterator_valid := gtk_list_store_remove (handle,an_iterator.handle).to_boolean
199		end
200
201	put (an_iterator: GTK_TREE_ITER; a_position: INTEGER) is
202			-- Creates a new row at position. iter will be changed to
203			-- point to this new row. If position is larger than the
204			-- number of rows on the list, then the new row will be
205			-- appended to the list. The row will be empty after this
206			-- function is called. To fill in values, you need to call
207			-- `set' or `set_value'.
208		require
209			valid_iterator: an_iterator/=Void
210		do
211			gtk_list_store_insert (handle, an_iterator.handle, a_position)
212		end
213
214	put_before, insert_before  (an_iterator, a_sibling: GTK_TREE_ITER) is
215			-- Inserts a new row before `a_sibling'. `an_iterator' iter will
216			-- be changed to point to this new row. The row will be empty
217			-- after this function is called. To fill in values, you need
218			-- to call gtk_list_store_set() or
219			-- gtk_list_store_set_value().
220		require
221			valid_iterator: an_iterator/=Void
222			valid_sibling: a_sibling/=Void
223		do
224			gtk_list_store_insert_before (handle, an_iterator.handle, a_sibling.handle)
225		end
226
227	add_last (an_iterator: GTK_TREE_ITER) is
228			-- Append the row referred by `an_iterator' to the end of the
229			-- list. `an_iterator' will be changed to point to this new
230			-- row. The row will be empty after this function is
231			-- called. To fill in values, you need to call `set' or
232			-- `set_value'.
233		require
234			valid_iterator: an_iterator/=Void
235		do
236			gtk_list_store_insert_before (handle, an_iterator.handle, default_pointer)
237		end
238
239	put_after, insert_after (an_iterator, a_sibling: GTK_TREE_ITER) is
240			-- Inserts a new row after `a_sibling'. `an_iterator' iter
241			-- will be changed to point to this new row. The row will be
242			-- empty after this function is called. To fill in values,
243			-- you need to call `set' or `set_value'.
244		require
245			valid_iterator: an_iterator/=Void
246			valid_sibling: a_sibling/=Void
247		do
248			gtk_list_store_insert_after (handle, an_iterator.handle, a_sibling.handle)
249		end
250
251	add_first (an_iterator: GTK_TREE_ITER) is
252			-- Prepend the row to the beginning of the list. `an_iterator' iter will
253			-- be changed to point to this new row. The row will be empty
254			-- after this function is called. To fill in values, you need
255			-- to call `set' or `set_value'.
256		require
257			valid_iterator: an_iterator/=Void
258		do
259			gtk_list_store_insert_after (handle, an_iterator.handle, default_pointer)
260		end
261
262	-- Unwrappable: variadic gtk_list_store_insert_with_values ()
263
264	-- void        gtk_list_store_insert_with_values
265	--                                             (GtkListStore *list_store,
266	--                                              GtkTreeIter *iter,
267	--                                              gint position,
268	--                                              ...);
269
270	-- Creates a new row at position. iter will be changed to point to
271	-- this new row. If position is larger than the number of rows on
272	-- the list, then the new row will be appended to the list. The row
273	-- will be filled with the values given to this function.
274
275	-- Calling gtk_list_store_insert_with_values(list_store, iter,
276	-- position...) has the same effect as calling
277	
278	-- gtk_list_store_insert (list_store, iter, position);
279	-- gtk_list_store_set (list_store_iter, ...);
280
281	-- with the difference that the former will only emit a
282	-- row_inserted signal, while the latter will emit row_inserted,
283	-- row_changed and, if the list store is sorted,
284	-- rows_reordered. Since emitting the rows_reordered signal
285	-- repeatedly can affect the performance of the program,
286	-- gtk_list_store_insert_with_values() should generally be
287	-- preferred when inserting rows in a sorted list store.
288
289	-- list_store : 	A GtkListStore
290	-- iter : 	An unset GtkTreeIter to set to the new row
291	-- position : 	position to insert the new row
292	-- ... : 	pairs of column number and value, terminated with -1
293
294	insert_with_values (an_iterator: GTK_TREE_ITER;
295							  a_position: INTEGER;
296							  some_columns: ARRAY[INTEGER];
297							  some_values: ARRAY[G_VALUE]) is
298			-- Creates a new row at `a_position'. `an_iterator' will be changed to
299			-- point to this new row. If position is larger than the number of rows
300			-- on the list, then the new row will be appended to the list. The row
301			-- will be filled with the values given to this function.
302		
303			-- `insert_with_values' has the same effect as calling `put' (known as
304			-- insert in C) and `set_values' with the difference that the former
305			-- will only emit a row_inserted signal, while the latter will emit
306			-- row_inserted, row_changed and, if the list store is sorted,
307			-- rows_reordered. Since emitting the rows_reordered signal repeatedly
308			-- can affect the performance of the program, insert_with_values should
309			-- generally be preferred when inserting rows in a sorted list store.
310
311			-- `some_columns' contains the column numbers; each column
312			-- will be set with the corresponding value in `some_values'
313		require columns_n_equals_values_n: some_columns.count = some_values.count
314		do
315			-- Uses a variant of gtk_list_store_insert_with_values() which takes
316			-- the columns and values as two arrays, instead of varargs. This
317			-- function is mainly intended for language-bindings. (PS Paolo: No, I
318			-- couldn't believe it!)
319			
320			-- list_store : 	A GtkListStore
321			-- iter : 	An unset GtkTreeIter to set to the new row
322			-- position : 	position to insert the new row
323			not_yet_implemented
324			-- TODO: some_values.to_external is an array of pointers to the Eiffel wrappers!!!
325			gtk_list_store_insert_with_valuesv (handle, an_iterator.handle,
326												a_position,
327												-- gint *columns an array of column numbers
328												some_columns.to_external,
329												-- GValue *values an array of
330												-- GValues
331												some_values.to_external,
332												-- gint n_values the length of the
333												-- columns and values arrays
334												some_values.count
335												)
336		end
337
338	prepend (an_iterator: GTK_TREE_ITER) is
339			-- Prepends a new row. `an_iterator' will be changed to
340			-- point to this new row. The row will be empty after this
341			-- function is called. To fill in values, you need to call
342			-- `set_values'
343		
344			-- TODO: C documentation says that `an_iterator` shall be unset. Is it true?
345		require valid_iterator: an_iterator/=Void
346		do
347			gtk_list_store_prepend (handle, an_iterator.handle)
348		end
349
350	append  (an_iterator: GTK_TREE_ITER) is
351			-- Append a new row. `an_iterator' will be changed to point to this new
352			-- row. The row will be empty after this function is called. To fill in
353			-- values, you need to call `set_values'
354		
355			-- TODO: C documentation says that `an_iterator` shall be unset. Is it
356			-- true?
357		require valid_iterator: an_iterator/=Void
358		do
359			gtk_list_store_append  (handle, an_iterator.handle)
360		end
361
362	clear is
363			-- Removes all rows from the list store.
364		do
365			gtk_list_store_clear (handle)
366		end
367
368	is_iterator_valid (an_iterator: GTK_TREE_ITER): BOOLEAN is
369			-- Is `an_iterator' valid for Current GtkListStore?
370			
371			-- Warning: this query is slow. Only use it for debugging
372			-- and/or testing purposes.
373		require valid_iterator: an_iterator/=Void
374		do
375			Result:=(gtk_list_store_iter_is_valid(handle,an_iterator.handle)).to_boolean
376		end
377
378	reorder (a_new_order: ARRAY[INTEGER]) is
379			-- Reorders store to follow the order indicated by
380			-- `a_new_order'. Note that this function only works with
381			-- unsorted stores. `a_new_order' is the array of integers
382			-- mapping the new position of each child to its old position
383			-- before the re-ordering, i.e. a_new_order.item(newpos) =
384			-- oldpos.
385		require
386			unsorted_store: not is_sorted
387			valid_order: a_new_order /= Void
388		do
389			gtk_list_store_reorder (handle, a_new_order.to_external)
390		end
391
392	swap (an_iterator, another: GTK_TREE_ITER) is
393			-- Swaps `an_iterator' and `another' in store. Note that this
394			-- function only works with unsorted stores.
395		require
396			unsorted_store: not is_sorted
397			valid_iterator: an_iterator/=Void
398			valid_another: another/=Void
399		do
400			gtk_list_store_swap (handle, an_iterator.handle, another.handle)
401		end
402
403	move_before (an_iterator, a_position: GTK_TREE_ITER) is
404			-- Moves iter in store to the position before position. Note
405			-- that this function only works with unsorted stores.
406		require
407			unsorted_store: not is_sorted
408			valid_iterator: an_iterator/=Void
409			valid_position: a_position/=Void
410		do
411			gtk_list_store_move_before (handle,an_iterator.handle, a_position.handle)
412		end
413
414	move_last  (an_iterator: GTK_TREE_ITER) is
415			-- Moves iter in store to the end of the list. Note that this
416			-- function only works with unsorted stores.
417		require
418			unsorted_store: not is_sorted
419			valid_iterator: an_iterator/=Void
420		do
421			gtk_list_store_move_before (handle,an_iterator.handle, default_pointer)
422		end
423
424	move_after  (an_iterator, a_position: GTK_TREE_ITER) is
425			-- Moves iter in store to the position after position. Note
426			-- that this function only works with unsorted stores. 
427		require
428			unsorted_store: not is_sorted
429			valid_iterator: an_iterator/=Void
430			valid_position: a_position/=Void
431		do
432			gtk_list_store_move_after  (handle,an_iterator.handle, a_position.handle)
433		end
434
435	move_first  (an_iterator: GTK_TREE_ITER) is
436			-- Moves item pointed to by `an_iterator' to the start of the list.
437			-- Note that this function only works with unsorted stores.
438		require
439			unsorted_store: not is_sorted
440			valid_iterator: an_iterator/=Void
441		do
442			gtk_list_store_move_after (handle, an_iterator.handle, default_pointer)
443		end
444
445end