/src/wrappers/gtk/library/gtk_tree_selection.e

  1indexing
  2	description: "GtkTreeSelection - The selection object for 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_SELECTION
 23	-- The GtkTreeSelection object is a helper object to manage the
 24	-- selection for a GtkTreeView widget. The GtkTreeSelection object
 25	-- is automatically created when a new GtkTreeView widget is
 26	-- created, and cannot exist independentally of this widget. The
 27	-- primary reason the GtkTreeSelection objects exists is for
 28	-- cleanliness of code and API. That is, there is no conceptual
 29	-- reason all these functions could not be methods on the
 30	-- GtkTreeView widget instead of a separate function.
 31
 32	-- A GTK_TREE_SELECTION object is obtained from a GTK_TREE_VIEW by
 33	-- calling `selection'. It can be manipulated to check the
 34	-- selection status of the tree, as well as select and deselect
 35	-- individual rows. Selection is done completely view side. As a
 36	-- result, multiple views of the same model can have completely
 37	-- different selections. Additionally, you cannot change the
 38	-- selection of a row on the model that is not currently displayed
 39	-- by the view without expanding its parents first.
 40
 41	-- One of the important things to remember when monitoring the
 42	-- selection of a view is that the "changed" signal is mostly a
 43	-- hint. That is, it may only emit one signal when a range of rows
 44	-- is selected. Additionally, it may on occasion emit a "changed"
 45	-- signal when nothing has happened (mostly as a result of
 46	-- programmers calling select_row on an already selected row).
 47
 48inherit
 49	G_OBJECT
 50
 51insert
 52	G_SIGNALS
 53	GTK_TREE_SELECTION_EXTERNALS
 54
 55creation from_external_pointer
 56
 57feature -- selection mode
 58	set_single_mode is
 59			-- Set selection mode to single. Zero or one element may be
 60			-- selected.If the previous type was GTK_SELECTION_MULTIPLE,
 61			-- then the anchor is kept selected, if it was previously
 62			-- selected.
 63		do
 64			gtk_tree_selection_set_mode (handle, gtk_selection_single)
 65		end
 66	
 67	is_mode_single: BOOLEAN is
 68			-- Is selection mode single?
 69		do
 70			Result := (gtk_tree_selection_get_mode (handle) = gtk_selection_single )
 71		end
 72
 73	set_browse_mode is
 74			-- Set selection mode to browse. Exactly one element is
 75			-- selected. In some circumstances, such as initially or
 76			-- during a search operation, it's possible for no element to
 77			-- be selected with GTK_SELECTION_BROWSE. What is really
 78			-- enforced is that the user can't deselect a currently
 79			-- selected element except by selecting another element. If
 80			-- the previous type was GTK_SELECTION_MULTIPLE, then the
 81			-- anchor is kept selected, if it was previously selected.
 82		do
 83			gtk_tree_selection_set_mode (handle, gtk_selection_browse)
 84		end
 85	
 86	is_mode_browse: BOOLEAN is
 87			-- Is selection mode browse?
 88		do
 89			Result := (gtk_tree_selection_get_mode (handle) = gtk_selection_browse )
 90		end
 91	
 92	set_multiple_mode is
 93			-- Set selection mode to multiple. Any number of elements may
 94			-- be selected. Clicks toggle the state of an item. Any
 95			-- number of elements may be selected. The Ctrl key may be
 96			-- used to enlarge the selection, and Shift key to select
 97			-- between the focus and the child pointed to. Some widgets
 98			-- may also allow Click-drag to select a range of
 99			-- elements. If the previous type was GTK_SELECTION_MULTIPLE,
100			-- then the anchor is kept selected, if it was previously
101			-- selected.
102		do
103			gtk_tree_selection_set_mode (handle, gtk_selection_multiple)
104		end
105	
106	is_mode_multiple: BOOLEAN is
107			-- Is selection mode multiple?
108		do
109			Result := (gtk_tree_selection_get_mode (handle) = gtk_selection_multiple)
110		end
111
112		
113	set_select_function (a_function: FUNCTION[ANY,TUPLE[GTK_TREE_SELECTION, GTK_TREE_MODEL, GTK_TREE_PATH, BOOLEAN],BOOLEAN]) is
114			-- Sets the selection function. If set, this function is
115			-- called before any node is selected or unselected, giving
116			-- some control over which nodes are selected. The select
117			-- function should return TRUE if the state of the node may
118			-- be toggled, and FALSE if the state of the node should be
119			-- left unchanged.
120		local select_callback: GTK_TREE_SELECT_FUNCTION
121		do
122			create select_callback.make (Current, a_function)
123		end
124		
125	-- Note: not wrapping gtk_tree_selection_get_user_data, since it is not useful.
126		
127	-- gpointer gtk_tree_selection_get_user_data (GtkTreeSelection
128	-- *selection); Returns the user data for the selection
129	-- function. selection : A GtkTreeSelection.  Returns : The user
130	-- data.
131
132feature -- View	
133	tree_view: GTK_TREE_VIEW is
134			-- the tree view associated with selection.
135		local factory: G_OBJECT_EXPANDED_FACTORY[GTK_TREE_VIEW]
136		do
137			Result :=factory.wrapper (gtk_tree_selection_get_tree_view (handle))
138		ensure result_not_void: Result/=Void
139		end
140
141	is_node_selected: BOOLEAN is
142			-- Is there a selected node?
143		require not_multiple: not is_mode_multiple
144		do
145			Result:=(gtk_tree_selection_get_selected (handle, default_pointer, default_pointer)).to_boolean
146		end
147	
148feature -- selections
149	selected: GTK_TREE_ITER is
150			-- the currently selected node if selection is set to
151			-- `gtk_selection_single' or `gtk_selection_browse'.
152		require not_multiple: not is_mode_multiple
153		local discarded_result: INTEGER
154		do
155			create Result.make
156			discarded_result := gtk_tree_selection_get_selected (handle, default_pointer, Result.handle)
157		end
158	
159	-- TODO: gtk_tree_selection_selected_foreach ()
160
161	-- void        gtk_tree_selection_selected_foreach
162	--                                             (GtkTreeSelection *selection,
163	--                                              GtkTreeSelectionForeachFunc func,
164	--                                              gpointer data);
165
166	-- Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_selection_get_selected_rows() might be more useful.
167
168	-- selection : 	A GtkTreeSelection.
169	-- func : 	The function to call for each selected node.
170	-- data : 	user data to pass to the function.
171
172	selected_rows: G_LIST [GTK_TREE_PATH] is
173			-- A (newly allocated) list of paths of all selected
174			-- rows. TODO: Eiffellize this Additionally, if you are
175			-- planning on modifying the model after calling this
176			-- function, you may want to convert the returned list into a
177			-- list of GtkTreeRowReferences. To do this, you can use
178			-- gtk_tree_row_reference_new().
179		do
180			create {GTK_TREE_PATH_LIST} Result.from_external_pointer
181			(gtk_tree_selection_get_selected_rows(handle,default_pointer))
182			-- To free the return value, use:
183			
184			-- g_list_foreach (list, gtk_tree_path_free, NULL);
185			-- g_list_free (list);
186			
187			-- selection : 	A GtkTreeSelection.
188			-- model : 	A pointer to set to the GtkTreeModel, or NULL.
189			-- Returns : 	A GList containing a GtkTreePath for each selected row.
190		end
191
192	selected_rows_count: INTEGER is
193			-- the number of rows that have been selected in tree.
194		do
195			Result := gtk_tree_selection_count_selected_rows (handle)
196		end
197
198	select_path (a_path: GTK_TREE_PATH) is
199			-- Select the row at `a_path'.
200		require path_not_void: a_path/=Void
201		do
202			gtk_tree_selection_select_path  (handle, a_path.handle)
203		ensure selected: is_path_selected (a_path)
204		end
205
206	unselect_path (a_path: GTK_TREE_PATH) is
207			-- Unselect the row at `a_path'.
208		require path_not_void: a_path/=Void
209		do
210			gtk_tree_selection_unselect_path  (handle, a_path.handle)
211		ensure unselected: not is_path_selected (a_path)
212		end
213
214	is_path_selected (a_path: GTK_TREE_PATH): BOOLEAN is
215			-- Is the row pointed to by `a_path' currently selected?
216			-- False if `a_path' does not point to a valid location.
217		do
218			Result:=(gtk_tree_selection_path_is_selected(handle,a_path.handle)).to_boolean
219		end
220
221	select_iter (an_iter: GTK_TREE_ITER) is
222			-- Selects the specified iterator (`an_iter').
223		require iterator_not_void: an_iter/=Void
224		do
225			gtk_tree_selection_select_iter  (handle, an_iter.handle)
226		ensure selected: is_iter_selected(an_iter)
227		end
228	
229	unselect_iter (an_iter: GTK_TREE_ITER) is
230			-- Unselects the specified iterator (`an_iter').
231		require iterator_not_void: an_iter/=Void
232		do
233			gtk_tree_selection_unselect_iter  (handle, an_iter.handle)		
234		ensure unselected: not is_iter_selected(an_iter)
235		end
236
237	is_iter_selected (an_iter: GTK_TREE_ITER): BOOLEAN is
238			-- Is the row at `an_iter' currently selected?
239		require iterator_not_void: an_iter/=Void
240		do
241			Result:=(gtk_tree_selection_iter_is_selected(handle,an_iter.handle)).to_boolean
242		end
243
244	select_all is
245			-- Selects all the nodes. selection must be set to GTK_SELECTION_MULTIPLE mode.
246		require multiple_mode: is_mode_multiple
247		do
248			gtk_tree_selection_select_all (handle)
249		end
250
251	unselect_all is
252			-- Unselects all the nodes.
253		do
254			gtk_tree_selection_unselect_all (handle)
255		end 
256
257	select_range (a_start,an_end: GTK_TREE_PATH) is
258			-- Selects a range of nodes, determined by `a_start' and
259			-- `an_end' paths inclusive. Selection must be set to
260			-- GTK_SELECTION_MULTIPLE mode.
261
262			-- `a_start' : 	The initial node of the range.
263			-- `an_end' : 	The final node of the range.
264		require
265			multiple_mode: is_mode_multiple
266			valid_start: a_start /= Void
267			valid_end: an_end /= Void
268		do
269			gtk_tree_selection_select_range (handle, a_start.handle, an_end.handle)
270		end
271
272	unselect_range (a_start,an_end: GTK_TREE_PATH) is
273			-- Unselects a range of nodes, determined by `a_start' and
274			-- `an_end' paths inclusive. Selection must be set to
275			-- GTK_SELECTION_MULTIPLE mode.
276
277			-- `a_start' : 	The initial node of the range.
278			-- `an_end' : 	The final node of the range.
279		require
280			multiple_mode: is_mode_multiple
281			valid_start: a_start /= Void
282			valid_end: an_end /= Void
283		do
284			gtk_tree_selection_unselect_range (handle, a_start.handle, an_end.handle)
285		end
286	
287
288feature  -- The "changed" signal
289	changed_signal_name: STRING is "changed"
290
291	on_changed is
292			-- Built-in changed signal handler; empty by design; redefine it.
293		do
294		end
295
296	enable_on_changed is
297			-- Connects "changed" signal to `on_changed' feature.
298		do
299			connect (Current, changed_signal_name, $on_changed)
300		end
301
302	connect_to_changed_signal (a_procedure: PROCEDURE [ANY, TUPLE[GTK_TREE_SELECTION]]) is
303		require
304			valid_procedure: a_procedure /= Void
305		local
306			changed_callback: CHANGED_TREE_SELECTION_CALLBACK
307		do
308			create changed_callback.make
309			changed_callback.connect (Current, a_procedure)
310		end
311
312	-- void        user_function                  (GtkTreeSelection *treeselection,
313	--                                             gpointer user_data);
314
315	-- Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened.
316	-- treeselection : 	the object which received the signal.
317	-- user_data : 	user data set when the signal handler was connected.
318	-- See Also
319
320	-- GtkTreeView, GtkTreeViewColumn, GtkTreeDnd, GtkTreeMode, GtkTreeSortable,
321	-- GtkTreeModelSort, GtkListStore, GtkTreeStore, GtkCellRenderer, GtkCellEditable,
322	-- GtkCellRendererPixbuf, GtkCellRendererText, GtkCellRendererToggle
323	
324	-- TODO: Unwrapped
325	
326	-- GtkTreeSelectionFunc ()
327	
328	-- gboolean    (*GtkTreeSelectionFunc)         (GtkTreeSelection *selection,
329	--                                              GtkTreeModel *model,
330	--                                              GtkTreePath *path,
331	--                                              gboolean path_currently_selected,
332	--                                              gpointer data);
333
334	-- A function used by gtk_tree_selection_set_select_function() to filter whether or not a row may be selected. It is called whenever a row's state might change. A return value of TRUE indicates to selection that it is okay to change the selection.
335	-- selection : 	A GtkTreeSelection
336	-- model : 	A GtkTreeModel being viewed
337	-- path : 	The GtkTreePath of the row in question
338	-- path_currently_selected : 	TRUE, if the path is currently selected
339	-- data : 	user data
340	-- Returns : 	TRUE, if the selection state of the row can be toggled
341	-- GtkTreeSelectionForeachFunc ()
342
343	-- void        (*GtkTreeSelectionForeachFunc)  (GtkTreeModel *model,
344	--                                              GtkTreePath *path,
345	--                                              GtkTreeIter *iter,
346	--                                              gpointer data);
347
348	-- A function used by gtk_tree_selection_selected_foreach() to map all selected rows. It will be called on every selected row in the view.
349	-- model : 	The GtkTreeModel being viewed
350	-- path : 	The GtkTreePath of a selected row
351	-- iter : 	A GtkTreeIter pointing to a selected row
352	-- data : 	user data
353feature -- struct size
354	struct_size: INTEGER is
355		external "C inline use <gtk/gtk.h>"
356		alias "sizeof(GtkTreeSelection)"
357		end
358end