/src/wrappers/gtk/library/gtk_list_store.e
Specman e | 445 lines | 160 code | 72 blank | 213 comment | 2 complexity | 75107fa5b3fc7c1743cca2aff3ff8a89 MD5 | raw file
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