/src/wrappers/gtk/library/gtk_menu_shell.e

  1indexing
  2	description: "GtkMenuShell -- A base class for menu objects."
  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
 22deferred class GTK_MENU_SHELL
 23	-- A GtkMenuShell is the abstract base class used to derive the
 24	-- GtkMenu and GtkMenuBar subclasses.
 25
 26	-- A GtkMenuShell is a container of GtkMenuItem objects arranged in
 27	-- a list which can be navigated, selected, and activated by the
 28	-- user to perform application functions. A GtkMenuItem can have a
 29	-- submenu associated with it, allowing for nested hierarchical
 30	-- menus.
 31
 32inherit GTK_CONTAINER
 33	-- GtkMenuShell implements AtkImplementorIface Interface
 34
 35feature -- size
 36
 37	struct_size: INTEGER is
 38		external "C inline use <gtk/gtk.h>"
 39		alias "sizeof(GtkMenuShell)"
 40		end
 41
 42feature
 43	-- TODO: check if all those `a_child' shall be GTK_MENU_ITEM
 44	-- instead of GTK_WIDGET
 45
 46	append (a_child: GTK_WIDGET) is
 47			-- Adds a new GtkMenuItem to the end of the menu shell's item
 48			-- list.
 49		require widget_not_void: a_child /= Void
 50		do
 51			gtk_menu_shell_append (handle, a_child.handle)
 52		end
 53
 54	prepend (a_child: GTK_WIDGET) is
 55			-- Adds a new GtkMenuItem to the beginning of the menu
 56			-- shell's item list.
 57		require widget_not_void: a_child /= Void
 58		do
 59			gtk_menu_shell_prepend (handle, a_child.handle)
 60		end
 61	
 62	insert_child (a_child: GTK_WIDGET; a_position: INTEGER) is
 63			-- Adds a new GtkMenuItem to the menu shell's item list at
 64			-- `a_position'. Positions are numbered from 0 to n-1.
 65		require 
 66			widget_not_void: a_child /= Void
 67			valid_position: a_position>=0
 68		do
 69			gtk_menu_shell_insert  (handle, a_child.handle, a_position)
 70		end
 71
 72
 73	deactivate is
 74			-- Deactivates the menu shell. Typically this results in the
 75			-- menu shell being erased from the screen.
 76		do
 77			gtk_menu_shell_deactivate (handle)
 78		end
 79
 80	select_item (a_menu_item: GTK_WIDGET) is
 81			-- Selects `a_menu_item' (a GtkMenuItem) from the menu shell.
 82		require item_not_void: a_menu_item /= Void
 83		do
 84			gtk_menu_shell_select_item (handle, a_menu_item.handle)
 85		end
 86
 87	select_first (search_sensitive: BOOLEAN) is
 88			-- Select the first visible or selectable child of the menu
 89			-- shell; don't select tearoff items unless the only item is
 90			-- a tearoff item.
 91
 92			-- `search_sensitive': if TRUE, search for the first
 93			-- selectable menu item, otherwise select nothing if the
 94			-- first item isn't sensitive. This should be FALSE if the
 95			-- menu is being popped up initially.
 96		do
 97			gtk_menu_shell_select_first (handle, search_sensitive.to_integer);
 98		end
 99
100	deselect is
101			-- Deselects the currently selected item from the menu shell,
102			-- if any.
103		do
104			gtk_menu_shell_deselect (handle)
105		end
106
107	activate_item (a_menu_item: GTK_WIDGET; force_deactivate: BOOLEAN) is
108			-- Activates `a_menu_item' within the menu shell. If
109			-- `force_deactivate' is True, force the deactivation of the
110			-- menu shell after the menu item is activated.
111		require item_not_void: a_menu_item /= Void
112		do
113			gtk_menu_shell_activate_item (handle, a_menu_item.handle, force_deactivate.to_integer)
114		end
115
116	cancel is
117			-- Cancels the selection within the menu shell.
118		do
119			gtk_menu_shell_cancel (handle)
120		end
121
122
123	set_take_focus is
124			-- Makes the menu shell to take the keyboard focus so that it
125			-- will receive all keyboard events which is needed to enable
126			-- keyboard navigation in menus.
127		
128			-- The state of a menu or menu bar is automatically
129			-- propagated to submenus whenever a submenu is popped up, so
130			-- you don't have to worry about recursively setting it for
131			-- your entire menu hierarchy. Only when programmatically
132			-- picking a submenu and popping it up manually, the
133			-- take_focus property of the submenu needs to be set
134			-- explicitely.
135
136			-- See also GDK_KEYBOARD.grab
137		do
138			gtk_menu_shell_set_take_focus (handle,1)
139		end
140	
141	unset_take_focus is
142			-- This is useful only for special applications like virtual
143			-- keyboard implementations which should not take keyboard
144			-- focus.
145
146			-- The take_focus state of a menu or menu bar is
147			-- automatically propagated to submenus whenever a submenu is
148			-- popped up, so you don't have to worry about recursively
149			-- setting it for your entire menu hierarchy. Only when
150			-- programmatically picking a submenu and popping it up
151			-- manually, the take_focus property of the submenu needs to
152			-- be set explicitely.
153
154			-- Note that this setting has side-effects:
155
156			-- If the focus is in some other app, it keeps the focus and
157			-- keynav in the menu doesn't work. Consequently, keynav on
158			-- the menu will only work if the focus is on some toplevel
159			-- owned by the onscreen keyboard.
160
161			-- To avoid confusing the user, menus with take_focus set to
162			-- FALSE should not display mnemonics or accelerators, since
163			-- it cannot be guaranteed that they will work.
164
165			-- See also GDK_KEYBOARD.grab
166		do
167			gtk_menu_shell_set_take_focus (handle,0)
168		end
169	
170	is_focus_taken: BOOLEAN is
171			-- Will the menu shell will take the keyboard focus on popup.
172		do
173			Result:=(gtk_menu_shell_get_take_focus(handle).to_boolean)
174		end
175
176feature -- TODO: Properties
177--    "take-focus"           gboolean              : Read / Write
178
179-- Property Details
180
181--   The "take-focus" property
182
183--    "take-focus"           gboolean              : Read / Write
184
185--    A boolean that determines whether the menu and its submenus grab the
186--    keyboard focus. See gtk_menu_shell_set_take_focus() and
187--    gtk_menu_shell_get_take_focus().
188
189--    Default value: TRUE
190
191--    Since 2.8
192
193feature -- TODO: Signals
194
195
196--  "activate-current"
197--              void        user_function      (GtkMenuShell *menushell,
198--                                              gboolean      force_hide,
199--                                              gpointer      user_data)       : Run last / Action
200--  "cancel"    void        user_function      (GtkMenuShell *menushell,
201--                                              gpointer      user_data)      : Run last / Action
202--  "cycle-focus"
203--              void        user_function      (GtkMenuShell     *menushell,
204--                                              GtkDirectionType *arg1,
205--                                              gpointer          user_data)      : Run last / Action
206--  "deactivate"
207--              void        user_function      (GtkMenuShell *menushell,
208--                                              gpointer      user_data)      : Run first
209--  "move-current"
210--              void        user_function      (GtkMenuShell        *menushell,
211--                                              GtkMenuDirectionType direction,
212--                                              gpointer             user_data)      : Run last / Action
213--  "selection-done"
214--              void        user_function      (GtkMenuShell *menushell,
215--                                              gpointer      user_data)      : Run first
216-- Signal Details
217
218--   The "activate-current" signal
219
220--  void        user_function                  (GtkMenuShell *menushell,
221--                                              gboolean      force_hide,
222--                                              gpointer      user_data)       : Run last / Action
223
224--    An action signal that activates the current menu item within the menu
225--    shell.
226
227--    menushell :  the object which received the signal.
228--    force_hide : if TRUE, hide the menu after activating the menu item.
229--    user_data :  user data set when the signal handler was connected.
230
231--    -----------------------------------------------------------------------
232
233--   The "cancel" signal
234
235--  void        user_function                  (GtkMenuShell *menushell,
236--                                              gpointer      user_data)      : Run last / Action
237
238--    An action signal which cancels the selection within the menu shell.
239--    Causes the GtkMenuShell::selection-done signal to be emitted.
240
241--    menushell : the object which received the signal.
242--    user_data : user data set when the signal handler was connected.
243
244--    -----------------------------------------------------------------------
245
246--   The "cycle-focus" signal
247
248--  void        user_function                  (GtkMenuShell     *menushell,
249--                                              GtkDirectionType *arg1,
250--                                              gpointer          user_data)      : Run last / Action
251
252--    menushell : the object which received the signal.
253--    arg1 :
254--    user_data : user data set when the signal handler was connected.
255
256--    -----------------------------------------------------------------------
257
258--   The "deactivate" signal
259
260--  void        user_function                  (GtkMenuShell *menushell,
261--                                              gpointer      user_data)      : Run first
262
263--    This signal is emitted when a menu shell is deactivated.
264
265--    menushell : the object which received the signal.
266--    user_data : user data set when the signal handler was connected.
267
268--    -----------------------------------------------------------------------
269
270--   The "move-current" signal
271
272--  void        user_function                  (GtkMenuShell        *menushell,
273--                                              GtkMenuDirectionType direction,
274--                                              gpointer             user_data)      : Run last / Action
275
276--    An action signal which moves the current menu item in the direction
277--    specified by direction.
278
279--    menushell : the object which received the signal.
280--    direction : the direction to move.
281--    user_data : user data set when the signal handler was connected.
282
283--    -----------------------------------------------------------------------
284
285--   The "selection-done" signal
286
287--  void        user_function                  (GtkMenuShell *menushell,
288--                                              gpointer      user_data)      : Run first
289
290--    This signal is emitted when a selection has been completed within a
291--    menu shell.
292
293--    menushell : the object which received the signal.
294--    user_data : user data set when the signal handler was connected.
295
296feature {} -- External calls
297	--   GtkMenuShell
298
299	--  typedef struct _GtkMenuShell GtkMenuShell;
300	
301	-- The GtkMenuShell-struct struct contains the following
302	-- fields. (These fields should be considered read-only. They
303	-- should never be set by an application.)
304	
305	-- GList *children; The list of GtkMenuItem objects contained by
306	-- this GtkMenuShell.
307
308	get_children (a_menu_shell: POINTER): POINTER is
309		external "C struct GtkMenuShell get children use <gtk/gtk.h>"
310		end
311	
312	gtk_menu_shell_append (a_menu_shell: POINTER; a_child: POINTER) is
313		external "C use <gtk/gtk.h>"
314		end
315	
316	gtk_menu_shell_prepend (a_menu_shell: POINTER; a_child: POINTER) is
317		external "C use <gtk/gtk.h>"
318		end
319
320	gtk_menu_shell_insert (a_menu_shell: POINTER; a_child: POINTER; a_position: INTEGER) is
321		external "C use <gtk/gtk.h>"
322		end
323
324	gtk_menu_shell_deactivate (a_menu_shell: POINTER) is
325		external "C use <gtk/gtk.h>"
326		end
327
328	gtk_menu_shell_select_item (a_menu_shell: POINTER; a_menu_item: POINTER) is
329		external "C use <gtk/gtk.h>"
330		end
331
332	gtk_menu_shell_select_first (a_menu_shell: POINTER; search_sensitive: INTEGER) is
333		external "C use <gtk/gtk.h>"
334		end
335
336	gtk_menu_shell_deselect (a_menu_shell: POINTER) is
337		external "C use <gtk/gtk.h>"
338		end
339
340	gtk_menu_shell_activate_item (a_menu_shell: POINTER; a_menu_item: POINTER; force_deactivate: INTEGER) is
341		external "C use <gtk/gtk.h>"
342		end
343
344	gtk_menu_shell_cancel (a_menu_shell: POINTER) is
345		external "C use <gtk/gtk.h>"
346		end
347
348	gtk_menu_shell_set_take_focus (a_menu_shell: POINTER; take_focus: INTEGER) is
349		external "C use <gtk/gtk.h>"
350		end
351
352	gtk_menu_shell_get_take_focus (a_menu_shell: POINTER): INTEGER is
353		external "C use <gtk/gtk.h>"
354		end
355end