/src/wrappers/gtk/library/gtk_tree_sortable.e

  1indexing
  2	description: "GtkTreeSortable -- The interface for sortable models used by 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					
 22
 23deferred class GTK_TREE_SORTABLE
 24	-- GtkTreeSortable is an interface to be implemented by tree models
 25	-- which support sorting. The GtkTreeView uses the methods provided
 26	-- by this interface to sort the model.
 27inherit
 28	-- TODO: G_INTERFACE 
 29	-- Prerequisites: GtkTreeSortable requires GtkTreeModel and GObject.
 30	GTK_TREE_MODEL
 31
 32		-- Note: GTK_TREE_MODEL already requires G_OBJECT
 33	
 34		-- Known Implementations: GtkTreeSortable is implemented by
 35		-- GtkTreeModelSort, GtkTreeStore and GtkListStore.
 36
 37insert
 38	GTK_SORT_TYPE
 39	GTK_TREE_SORTABLE_EXTERNALS
 40		
 41feature 
 42
 43-- GtkTreeIterCompareFunc ()
 44
 45-- gint        (*GtkTreeIterCompareFunc)       (GtkTreeModel *model,
 46--                                              GtkTreeIter *a,
 47--                                              GtkTreeIter *b,
 48--                                              gpointer user_data);
 49
 50-- A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if a sorts before b, a sorts with b, or a sorts after b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the GtkTreeSortable behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive.
 51
 52-- For example, if model is a product catalogue, then a compare function for the "price" column could be one which returns price_of(a) - price_of(b).
 53-- model : 	The GtkTreeModel the comparison is within
 54-- a : 	A GtkTreeIter in model
 55-- b : 	Another GtkTreeIter in model
 56-- user_data : 	Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func()
 57-- Returns : 	
 58
 59	sort_column_changed is
 60			-- -- Emits a GtkTreeSortable::sort_column_changed signal on Current
 61		do
 62			gtk_tree_sortable_sort_column_changed (handle)
 63		end
 64
 65	is_sort_column_id_not_special: BOOLEAN
 66			-- Is the sort column not one of the special sort column ids
 67			-- (i.e.: gtk_tree_sortable_default_sort_column_id or
 68			-- gtk_tree_sortable_unsorted_sort_column_id)?
 69	
 70	sort_column_id: INTEGER is
 71			-- The current sort column and the order. It returns TRUE
 72			-- unless the sort_column_id is
 73			-- GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or
 74			-- GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
 75		
 76			-- sortable : 	A GtkTreeSortable
 77			-- sort_column_id : 	The sort column id to be filled in
 78			-- order : 	The GtkSortType to be filled in
 79			-- Returns : 	TRUE if the sort column is not one of the special sort column ids.
 80		local an_order: INTEGER
 81		do
 82			is_sort_column_id_not_special := (gtk_tree_sortable_get_sort_column_id (handle,
 83																											$Result,
 84																											$an_order
 85																											)).to_boolean
 86		end
 87
 88	order: INTEGER is
 89			-- Fills in sort_column_id and order with the current sort column and the order. It returns TRUE unless the sort_column_id is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
 90		
 91			-- sortable : 	A GtkTreeSortable
 92			-- sort_column_id : 	The sort column id to be filled in
 93			-- order : 	The GtkSortType to be filled in
 94			-- Returns : 	TRUE if the sort column is not one of the special sort column ids.
 95		local a_column: INTEGER
 96		do
 97			is_sort_column_id_not_special := (gtk_tree_sortable_get_sort_column_id (handle, $a_column,
 98																											$Result)).to_boolean
 99		ensure is_valid_gtk_sort_type (Result)
100		end
101	
102	set_sort_column_id (a_column_id, an_order: INTEGER) is
103			-- Sets the current sort column to be `a_column_id'. The
104			-- sortable will resort itself to reflect this change, after
105			-- emitting a GtkTreeSortable::sort_column_changed signal. If
106			-- sort_column_id is
107			-- GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the default
108			-- sort function will be used, if it is set.
109		
110			-- `an_order' is the sort order of the column
111		require valid_order: is_valid_gtk_sort_type (an_order)
112		do
113			gtk_tree_sortable_set_sort_column_id (handle, a_column_id, an_order)
114		end
115	
116	is_sorted: BOOLEAN is
117			-- Is Current GTK_TREE_SORTABLE sorted?
118		local
119			col, sorted: INTEGER
120		do
121			Result := gtk_tree_sortable_get_sort_column_id (handle,
122				$col,
123				$sorted
124				).to_boolean
125		end
126
127	-- TODO: gtk_tree_sortable_set_sort_func ()
128	
129	-- void        gtk_tree_sortable_set_sort_func (GtkTreeSortable *sortable,
130	--                                              gint sort_column_id,
131	--                                              GtkTreeIterCompareFunc sort_func,
132	--                                              gpointer user_data,
133	--                                              GtkDestroyNotify destroy);
134	
135	-- Sets the comparison function used when sorting to be sort_func. If the current sort column id of sortable is the same as sort_column_id, then the model will sort using this function.
136
137	-- sortable : 	A GtkTreeSortable
138	-- sort_column_id : 	the sort column id to set the function for
139	-- sort_func : 	The comparison function
140	-- user_data : 	User data to pass to sort_func, or NULL
141	-- destroy : 	Destroy notifier of user_data, or NULL
142
143	-- TODO: set_default_sort_func is
144
145	-- void        gtk_tree_sortable_set_default_sort_func
146	--                                             (GtkTreeSortable *sortable,
147	--                                              GtkTreeIterCompareFunc sort_func,
148--                                              gpointer user_data,
149	--                                              GtkDestroyNotify destroy);
150
151	-- Sets the default comparison function used when sorting to be sort_func. If the current sort column id of sortable is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function.
152	
153-- If sort_func is NULL, then there will be no default comparison function. This means that once the model has been sorted, it can't go back to the default state. In this case, when the current sort column id of sortable is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
154	
155-- sortable : 	A GtkTreeSortable
156-- sort_func : 	The comparison function
157-- user_data : 	User data to pass to sort_func, or NULL
158-- destroy : 	Destroy notifier of user_data, or NULL
159-- gtk_tree_sortable_has_default_sort_func ()
160
161-- gboolean    gtk_tree_sortable_has_default_sort_func
162--                                             (GtkTreeSortable *sortable);
163
164-- Returns TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not.
165
166-- sortable : 	A GtkTreeSortable
167-- Returns : 	TRUE, if the model has a default sort function
168-- Signal Details
169-- The "sort-column-changed" signal
170
171-- void        user_function                  (GtkTreeSortable *treesortable,
172--                                             gpointer user_data);
173
174-- treesortable : 	the object which received the signal.
175-- user_data : 	user data set when the signal handler was connected.
176-- See Also
177
178-- GtkTreeModel, GtkTreeView
179end
180