/src/wrappers/gtk/library/gtk_combo_box.e

  1indexing
  2	description: "GtkComboBox -- A widget used to choose from a list of items."
  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_COMBO_BOX
 23	-- A GtkComboBox is a widget that allows the user to choose from a
 24	-- list of valid choices. The GtkComboBox displays the selected
 25	-- choice. When activated, the GtkComboBox displays a popup which
 26	-- allows the user to make a new choice. The style in which the
 27	-- selected value is displayed, and the style of the popup is
 28	-- determined by the current theme. It may be similar to a
 29	-- GtkOptionMenu, or similar to a Windows-style combo box.
 30
 31	-- Unlike its predecessors GtkCombo and GtkOptionMenu, the
 32	-- GtkComboBox uses the model-view pattern; the list of valid
 33	-- choices is specified in the form of a tree model, and the
 34	-- display of the choices can be adapted to the data in the model
 35	-- by using cell renderers, as you would in a tree view. This is
 36	-- possible since GtkComboBox implements the GtkCellLayout
 37	-- interface. The tree model holding the valid choices is not
 38	-- restricted to a flat list, it can be a real tree, and the popup
 39	-- will reflect the tree structure.
 40
 41	-- In addition to the model-view API, GtkComboBox offers a simple
 42	-- API which is suitable for text-only combo boxes, and hides the
 43	-- complexity of managing the data in a model. It consists of the
 44	-- functions `with_text', `append_text', `insert_text',
 45	-- `prepend_text', `remove_text' and `active_text'.
 46
 47inherit
 48	GTK_BIN
 49	GTK_CELL_EDITABLE
 50	GTK_CELL_LAYOUT 
 51		undefine 
 52			store_eiffel_wrapper
 53		end
 54
 55	-- GtkComboBox also implements AtkImplementorIface interface.
 56
 57insert 
 58	GTK_COMBO_BOX_EXTERNALS
 59
 60creation make, with_text_only, from_external_pointer
 61
 62feature {} -- Creation
 63
 64	make is
 65			-- Creates a new empty GtkComboBox.
 66		do
 67			from_external_pointer (gtk_combo_box_new)
 68			is_text_only:=False
 69		ensure no_text_only: not is_text_only
 70		end
 71
 72	with_model (a_model: GTK_TREE_MODEL) is
 73			-- Creates a new GtkComboBox with `a_model'.
 74		do
 75			from_external_pointer (gtk_combo_box_new_with_model (handle))
 76			is_text_only:=False
 77		ensure no_text_only: not is_text_only
 78		end
 79
 80feature -- Model-related features
 81	wrap_width: INTEGER is
 82			-- the wrap width which is used to determine the number of
 83			-- columns for the popup menu. If the wrap width is larger
 84			-- than 1, the combo box is in table mode.
 85		require no_simple_api: not is_text_only
 86		do
 87			Result:=gtk_combo_box_get_wrap_width (handle)
 88		end
 89
 90	set_wrap_width (a_width: INTEGER) is
 91			-- Sets the wrap width of combo_box to be `a_width'. The wrap
 92			-- width is basically the preferred number of columns when
 93			-- you want the popup to be layed out in a table.
 94		require no_simple_api: not is_text_only
 95		do
 96			gtk_combo_box_set_wrap_width    (handle, a_width)
 97		end
 98
 99	row_span_column: INTEGER is
100			-- the column with row span information for combo_box.
101		require no_simple_api: not is_text_only
102		do
103			Result := gtk_combo_box_get_row_span_column (handle)
104		end
105
106	set_row_span_column (a_row_span: INTEGER) is
107			-- Sets the column with row span information for combo_box to
108			-- be row_span. The row span column contains integers which
109			-- indicate how many rows an item should span.
110		require no_simple_api: not is_text_only
111		do
112			gtk_combo_box_set_row_span_column (handle, a_row_span)
113		end
114
115	column_span_column: INTEGER is
116			-- the column with column span information for combo_box.
117		require no_simple_api: not is_text_only
118		do
119			Result:= gtk_combo_box_get_column_span_column (handle)
120		end
121
122	set_column_span_column (a_column_span: INTEGER) is
123			-- Sets the column with column span information for combo_box
124			-- to be column_span. The column span column contains
125			-- integers which indicate how many columns an item should
126			-- span.
127		require no_simple_api: not is_text_only
128		do
129			gtk_combo_box_set_column_span_column (handle, a_column_span)
130		end
131
132	active_row: INTEGER is
133			-- the index of the currently active item, or -1 if there's
134			-- no active item. If the model is a non-flat treemodel, and
135			-- the active item is not an immediate child of the root of
136			-- the tree, this function returns the result of the C call
137			-- "gtk_tree_path_get_indices (path)[0]", where path is the
138			-- GtkTreePath of the active item.
139		require no_simple_api: not is_text_only
140		do
141			Result := gtk_combo_box_get_active (handle)
142		end
143
144	active_column: INTEGER is
145		obsolete "Renamed this feature to `active_row' which is a better name"
146		do
147			Result := active_row
148		end
149
150	set_active (an_index: INTEGER) is
151			-- Sets the active item of combo_box to be the item at index.
152		require no_simple_api: not is_text_only
153		do
154			gtk_combo_box_set_active (handle,an_index)
155		end
156
157	active_iter: GTK_TREE_ITER is
158			-- An iterator pointing to the current active item, if it
159			-- exists. Otherwise Void
160		require no_simple_api: not is_text_only
161		local gbool: INTEGER
162		do
163			create Result.make -- a newly allocated iterator
164			gbool := gtk_combo_box_get_active_iter (handle, Result.handle)
165			if gbool=0 then Result:=Void end
166		end
167
168	set_active_iter (an_iterator: GTK_TREE_ITER) is
169			-- Sets the current active item to be the one referenced by
170			-- `an_iterator' that must correspond to a path of depth one.
171		require
172			no_simple_api: not is_text_only
173			-- TODO: an_iterator.depth = 1
174		do
175			gtk_combo_box_set_active_iter (handle, an_iterator.handle)
176		end
177	
178
179	model: GTK_TREE_MODEL is
180			-- the GtkTreeModel which is acting as data source for
181			-- combo_box.
182		require no_simple_api: not is_text_only
183		local factory: G_OBJECT_EXPANDED_FACTORY [GTK_TREE_MODEL]
184		do
185			Result := factory.wrapper(gtk_combo_box_get_model (handle))
186		end
187
188	set_model (a_model: GTK_TREE_MODEL) is
189			-- Sets the model used by combo_box to be model. Will unset a
190			-- previously set model (if applicable). If model is NULL,
191			-- then it will unset the model.
192			
193			-- Note that this function does not clear the cell renderers,
194			-- you have to call `cell_layout_clear' yourself if you need
195			-- to set up different cell renderers for the new model.
196		require
197			no_simple_api: not is_text_only
198			model_not_void: a_model /= Void
199		do
200			gtk_combo_box_set_model (handle, a_model.handle)
201		end
202
203	unset_model is
204			-- Unsets the model used by combo box.
205		require no_simple_api: not is_text_only
206		do
207			gtk_combo_box_set_model (handle, default_pointer)
208		end
209
210feature {} -- Simplified, text-only API creation
211	with_text_only is
212			-- Convenience constructor of a new text combo box, which
213			-- will display only strings. If you use this function to
214			-- create a text combo box, you should only manipulate its
215			-- data source with the following convenience functions:
216			-- `append_text', `insert_text', `prepend_text'' and
217			-- `remove_text' as the "simple_api" preconditions state.
218		do
219			from_external_pointer (gtk_combo_box_new_text )
220			is_text_only:=True
221		ensure text_only: is_text_only
222		end
223
224feature -- Simplified, text-only API
225
226	is_text_only: BOOLEAN
227	append_text (a_text: STRING) is
228			-- Appends `a_text' to the list of strings stored in combo box.		
229		require
230			simple_api: is_text_only
231			text_not_void: a_text /= Void
232		do
233			gtk_combo_box_append_text (handle, a_text.to_external)
234		end
235
236	insert_text (a_text: STRING; a_position: INTEGER) is
237			-- Inserts `a_text' at `a_position' in the list of strings
238			-- stored in combo_box.
239		require
240			simple_api: is_text_only
241			text_not_void: a_text /= Void
242		do
243			gtk_combo_box_insert_text (handle, a_position, a_text.to_external)
244		end
245
246	prepend_text (a_text: STRING) is
247			-- Prepends `a_text' to the list of strings stored in combo box.		
248		require
249			simple_api: is_text_only
250			text_not_void: a_text /= Void
251		do
252			gtk_combo_box_prepend_text (handle, a_text.to_external)
253		end
254
255	remove_text (a_position: INTEGER) is
256			-- Removes the string at `a_position' from combo box. 
257		require simple_api: is_text_only
258		do
259			gtk_combo_box_remove_text (handle, a_position)
260		end
261
262	active_text: STRING is
263			-- The currently active string in combo_box or Void if none
264			-- is selected.
265		require simple_api: is_text_only
266		local ptr: POINTER
267		do
268			ptr := gtk_combo_box_get_active_text (handle)
269			-- Returns : a newly allocated string containing the
270			-- currently active text.
271			if ptr.is_not_null then create Result.from_external(ptr) end
272		end
273
274feature -- For accessibility technologies
275	popup is
276			-- Pops up the menu or dropdown list of combo box. This
277			-- function is mostly intended for use by accessibility
278			-- technologies; applications should have little use for it.
279		do
280			gtk_combo_box_popup (handle)
281		end
282
283	popdown is
284			-- Hides the menu or dropdown list of combo_box.  This
285			-- function is mostly intended for use by accessibility
286			-- technologies; applications should have little use for it.
287		do
288			gtk_combo_box_popdown (handle)
289		end
290
291	-- TODO: popup_accessible_object: ATK_OBJECT is AtkObject*
292	-- gtk_combo_box_get_popup_accessible (GtkComboBox *combo_box);
293	-- Gets the accessible object corresponding to the combo box's
294	-- popup. This function is mostly intended for use by accessibility
295	-- technologies; applications should have little use for it.
296
297	-- gtk_combo_box_get_row_separator_func ()
298
299	-- GtkTreeViewRowSeparatorFunc gtk_combo_box_get_row_separator_func
300	-- (GtkComboBox *combo_box);
301
302	-- Returns the current row separator function.
303
304	-- combo_box : 	a GtkComboBox
305	-- Returns : 	the current row separator function.
306
307	-- Since 2.6
308	-- gtk_combo_box_set_row_separator_func ()
309
310	-- void gtk_combo_box_set_row_separator_func
311	-- (GtkComboBox *combo_box,
312	-- GtkTreeViewRowSeparatorFunc func,
313	-- gpointer data,
314	-- GtkDestroyNotify destroy);
315
316	-- Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is NULL, no separators are drawn. This is the default value.
317
318	-- combo_box : 	a GtkComboBox
319	-- func : 	a GtkTreeViewRowSeparatorFunc
320	-- data : 	user data to pass to func, or NULL
321	-- destroy : 	destroy notifier for data, or NULL
322
323	-- Since 2.6
324	-- gtk_combo_box_set_add_tearoffs ()
325
326	-- void gtk_combo_box_set_add_tearoffs (GtkComboBox *combo_box,
327	-- gboolean add_tearoffs);
328
329	-- Sets whether the popup menu should have a tearoff menu item.
330
331	-- combo_box : 	a GtkComboBox
332	-- add_tearoffs : 	TRUE to add tearoff menu items
333
334	-- Since 2.6
335	-- gtk_combo_box_get_add_tearoffs ()
336
337	-- gboolean gtk_combo_box_get_add_tearoffs (GtkComboBox *combo_box);
338
339	-- Gets the current value of the :add-tearoffs property.
340
341	-- combo_box : 	a GtkComboBox
342	-- Returns : 	the current value of the :add-tearoffs property.
343	-- gtk_combo_box_set_focus_on_click ()
344
345	-- void gtk_combo_box_set_focus_on_click
346	-- (GtkComboBox *combo,
347	-- gboolean focus_on_click);
348
349	-- Sets whether the combo box will grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don't want the keyboard focus removed from the main area of the application.
350
351	-- combo : 	a GtkComboBox
352	-- focus_on_click : 	whether the combo box grabs focus when clicked with the mouse
353
354	-- Since 2.6
355	-- gtk_combo_box_get_focus_on_click ()
356
357	-- gboolean gtk_combo_box_get_focus_on_click
358	-- (GtkComboBox *combo);
359
360	-- Returns whether the combo box grabs focus when it is clicked with the mouse. See gtk_combo_box_set_focus_on_click().
361
362	-- combo : 	a GtkComboBox
363	-- Returns : 	TRUE if the combo box grabs focus when it is clicked with the mouse.
364
365	-- Since 2.6
366feature -- Properties
367
368	-- "active" gint : Read / Write
369	-- "add-tearoffs" gboolean : Read / Write
370	-- "column-span-column" gint : Read / Write
371	-- "focus-on-click" gboolean : Read / Write
372	-- "has-frame" gboolean : Read / Write
373	-- "model" GtkTreeModel : Read / Write
374	-- "row-span-column" gint : Read / Write
375	-- "wrap-width" gint : Read / Write
376
377	-- Style Properties
378
379	-- "appears-as-list" gboolean : Read
380
381	-- Property Details
382	-- The "active" property
383
384	-- "active" gint : Read / Write
385
386	-- The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value gtk_tree_path_get_indices (path)[0], where path is the GtkTreePath of the active item.
387
388	-- Allowed values: >= -1
389
390	-- Default value: -1
391
392	-- Since 2.4
393	-- The "add-tearoffs" property
394
395	-- "add-tearoffs" gboolean : Read / Write
396
397	-- The add-tearoffs property controls whether generated menus have tearoff menu items.
398
399	-- Note that this only affects menu style combo boxes.
400
401	-- Default value: FALSE
402
403	-- Since 2.6
404	-- The "column-span-column" property
405
406	-- "column-span-column" gint : Read / Write
407
408	-- If this is set to a non-negative value, it must be the index of a column of type G_TYPE_INT in the model.
409
410	-- The values of that column are used to determine how many columns a value in the list will span.
411
412	-- Allowed values: >= -1
413
414	-- Default value: -1
415
416	-- Since 2.4
417	-- The "focus-on-click" property
418
419	-- "focus-on-click" gboolean : Read / Write
420
421	-- Whether the combo box grabs focus when it is clicked with the mouse.
422
423	-- Default value: TRUE
424	-- The "has-frame" property
425
426	-- "has-frame" gboolean : Read / Write
427
428	-- The has-frame property controls whether a frame is drawn around the entry.
429
430	-- Default value: TRUE
431
432	-- Since 2.6
433	-- The "model" property
434
435	-- "model" GtkTreeModel : Read / Write
436
437	-- The model from which the combo box takes the values shown in the list.
438
439	-- Since 2.4
440	-- The "row-span-column" property
441
442	-- "row-span-column" gint : Read / Write
443
444	-- If this is set to a non-negative value, it must be the index of a column of type G_TYPE_INT in the model.
445
446	-- The values of that column are used to determine how many rows a value in the list will span. Therefore, the values in the model column pointed to by this property must be greater than zero and not larger than wrap-width.
447
448	-- Allowed values: >= -1
449
450	-- Default value: -1
451
452	-- Since 2.4
453	-- The "wrap-width" property
454
455	-- "wrap-width" gint : Read / Write
456
457	-- If wrap-width is set to a positive value, the list will be displayed in multiple columns, the number of columns is determined by wrap-width.
458
459	-- Allowed values: >= 0
460
461	-- Default value: 0
462
463	-- Since 2.4
464	-- Style Property Details
465	-- The "appears-as-list" style property
466
467	-- "appears-as-list" gboolean : Read
468
469	-- Whether dropdowns should look like lists rather than menus.
470
471	-- Default value: FALSE
472
473feature -- The "changed" signal
474	changed_signal_name: STRING is "changed"
475
476	enable_on_changed is
477			-- Connects "changed" signal to `on_changed' feature.
478		do
479			connect (Current, changed_signal_name, $on_changed)
480		end
481
482	on_changed is
483			-- Built-in changed signal handler; empty by design; redefine it.
484
485			-- The `changed' signal is emitted when the active item is changed.
486			-- The can be due to the user selecting a different item from the list,
487			-- or due to a call to gtk_combo_box_set_active_iter(). It will also be
488			-- emitted while typing into a GtkComboBoxEntry, as well as when
489			-- selecting an item from the GtkComboBoxEntry's list.
490		do
491		end
492
493	connect_agent_to_changed_signal (a_procedure: PROCEDURE [ANY, TUPLE[GTK_COMBO_BOX]]) is
494			-- widget : 	the object which received the signal
495			-- user_data : 	user data set when the signal handler was connected.
496		require
497			valid_procedure: a_procedure /= Void
498		local
499			changed_callback: CHANGED_CALLBACK[like Current]
500		do
501			create changed_callback.make
502			changed_callback.connect (Current, a_procedure)
503		end
504
505feature -- size
506	struct_size: INTEGER is
507		external "C inline use <gtk/gtk.h>"
508		alias "sizeof(GtkComboBox)"
509		end
510
511end