## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --               GtkAda - Ada95 binding for Gtk+/Gnome               --

3.     --                                                                   --

4.     --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   --

5.     --                Copyright (C) 2000-2007 AdaCore                    --

6.     --                                                                   --

7.     -- This library is free software; you can redistribute it and/or     --

8.     -- modify it under the terms of the GNU General Public               --

9.     -- License as published by the Free Software Foundation; either      --

10.     -- version 2 of the License, or (at your option) any later version.  --

11.     --                                                                   --

12.     -- This library is distributed in the hope that it will be useful,   --

13.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

14.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

15.     -- General Public License for more details.                          --

16.     --                                                                   --

17.     -- You should have received a copy of the GNU General Public         --

18.     -- License along with this library; if not, write to the             --

19.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

20.     -- Boston, MA 02111-1307, USA.                                       --

21.     --                                                                   --

22.     -- As a special exception, if other files instantiate generics from  --

23.     -- this unit, or you link this unit with other files to produce an   --

24.     -- executable, this  unit  does not  by itself cause  the resulting  --

25.     -- executable to be covered by the GNU General Public License. This  --

26.     -- exception does not however invalidate any other reasons why the   --

27.     -- executable file  might be covered by the  GNU Public License.     --

28.     -----------------------------------------------------------------------

30.     --  <description>

31.     --

32.     --  This widget is a base class for all menu widgets. It contains a list of

33.     --  items that can be navigated, selected and activated by the user.

34.     --  It can not be instantiated directly.

35.     --

36.     --  A menu is considered "active" when it is displayed on the screen, or, in

37.     --  the case of a menu_bar when one of its menus is active.

38.     --

39.     --  An item is "selected" if it is displayed in a prelight state and its

40.     --  submenu (if any) displayed.

41.     --

42.     --  </description>

43.     --  <c_version>2.8.17</c_version>

44.     --  <group>Menus and Toolbars</group>

46.     with Glib.PropertiesTo API docTo specTo body;

47.     with Gtk.ContainerTo API docTo specTo body;

48.     with Gtk.Menu_ItemTo API docTo specTo body; use Gtk.Menu_ItemTo API docTo specTo body;

50.     package Gtk.Menu_ShellTo API docTo specTo body is

52.        type Gtk_Menu_Shell_RecordTo API docTo body is new

53.          Gtk.Container.Gtk_Container_RecordTo API docTo specTo body with private;

54.        type Gtk_Menu_Shell is access all Gtk_Menu_Shell_RecordTo API docTo specTo body'Class;

56.        function Get_TypeTo API docTo body return Gtk.Gtk_TypeTo API docTo spec;

57.        --  Return the internal value associated with a Gtk_Menu_Shell.

59.        procedure AppendTo API docTo body

60.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

61.           Child      : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class);

62.        --  Add a new item at the end of the menu.

64.        procedure PrependTo API docTo body

65.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

66.           Child      : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class);

67.        --  Add a new item at the beginning of the menu

69.        procedure InsertTo API docTo body

70.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

71.           Child      : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class;

72.           Position   : GintTo API docTo spec);

73.        --  Add a new item at a specific position in the menu.

74.        --  The first item is at position 0. To insert as the last item in the menu,

75.        --  set Position to -1.

77.        procedure Set_Take_FocusTo API docTo body

78.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

79.           Take_Focus : Boolean := True);

80.        function Get_Take_FocusTo API docTo body

81.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body) return Boolean;

82.        --  If Take_Focus is TRUE the menu shell will take the keyboard focus so

83.        --  that it will receive all keyboard events which is needed to enable

84.        --  keyboard navigation in menus.

85.        --

86.        --  Setting Take_Focus to FALSE is useful only for special applications like

87.        --  virtual keyboard implementations which should not take keyboard focus.

88.        --

89.        --  The Take_Focus state of a menu or menu bar is automatically propagated

90.        --  to submenus whenever a submenu is popped up, so you don't have to worry

91.        --  about recursively setting it for your entire menu hierarchy. Only when

92.        --  programmatically picking a submenu and popping it up manually, the

93.        --  Take_Focus property of the submenu needs to be set explicitely.

94.        --

95.        --  Note that setting it to %ALSE has side-effects:

96.        --

97.        --  If the focus is in some other app, it keeps the focus and keynav in

98.        --  the menu doesn't work. Consequently, keynav on the menu will only

99.        --  work if the focus is on some toplevel owned by the onscreen keyboard.

100.        --

101.        --  To avoid confusing the user, menus with Take_Focus set to FALSE

102.        --  should not display mnemonics or accelerators, since it cannot be

103.        --  guaranteed that they will work.

105.        procedure Select_FirstTo API docTo body

106.          (Menu_Shell       : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

107.           Search_Sensitive : Boolean);

108.        --  Select the first visible or selectable child of the menu shell;

109.        --  don't select tearoff items unless the only item is a tearoff

110.        --  item.

111.        --  If Search_Sensitive is True, search for the first selectable menu item,

112.        --  otherwise select nothing if the first item isn't sensitive. This should

113.        --  be False if the menu is being popped up initially.

115.        ----------------------

116.        -- Signals emission --

117.        ----------------------

119.        procedure DeactivateTo API docTo body (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body);

120.        --  Emit the "deactivate" signal.

121.        --  This deselects the selected item, ungrabs the mouse and keyboard, and

122.        --  erase the Menu_Shell from the screen.

124.        procedure Select_ItemTo API docTo body

125.          (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

126.           Item       : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class);

127.        --  Select a new item in the menu, after deselecting the current item.

129.        procedure DeselectTo API docTo body (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body);

130.        --  Deselect the currently selected item.

132.        procedure Activate_ItemTo API docTo body

133.          (Menu_Shell       : access Gtk_Menu_Shell_RecordTo API docTo specTo body;

134.           Item             : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class;

135.           Force_Deactivate : Boolean);

136.        --  Activate the item.

137.        --  If Force_Deactivate is True or the menu_shell sets this property,

138.        --  Menu_Shell and all its parent menus are deactivated and erased from

139.        --  the screen.

141.        procedure CancelTo API docTo body (Menu_Shell : access Gtk_Menu_Shell_RecordTo API docTo specTo body);

142.        --  Cancels the selection within the menu shell.

144.        ----------------

145.        -- Properties --

146.        ----------------

148.        --  <properties>

149.        --  The following properties are defined for this widget. See

150.        --  Glib.Properties for more information on properties.

151.        --

152.        --  Name:  Take_Focus_Property

153.        --  Type:  Boolean

154.        --  Descr: A boolean that determines whether the menu grabs the keyboard

155.        --         focus

156.        --

157.        --  </properties>

159.        Take_Focus_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

161.        -------------

162.        -- Signals --

163.        -------------

165.        --  <signals>

166.        --  The following new signals are defined for this widget:

167.        --

168.        --  - "deactivate"

169.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class);

170.        --    Emitted when the menu is deactivated, ie is erased from the screen.

171.        --

172.        --  - "selection-done"

173.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class);

174.        --    Emitted when an item has been selected. The menu shell might not be

175.        --    activated when the signal is emitted.

176.        --

177.        --  - "move_current"

178.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class;

179.        --                       Direction  : Gtk_Menu_Direction_Type);

180.        --    You should emit this signal to request that another menu item be

181.        --    selected. It is mostly useful when bound to a keybinding.

182.        --    In a menu, this is bound by default to the arrow keys to move the

183.        --    the selection.

184.        --

185.        --  - "cycle_focus"

186.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class;

187.        --                       Direction  : Gtk_Menu_Direction_Type);

188.        --    You should emit this signal to request that another child of

189.        --    Menu_Shell gets the focus. The child is not activated.

190.        --

191.        --  - "activate_current"

192.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class;

193.        --                       Force_Hide : Gboolean);

194.        --    Activates the current menu item within the Menu_Shell.

195.        --    if Force_Hide is True, hide the menu afterwards.

196.        --

197.        --  - "cancel"

198.        --    procedure Handler (Menu_Shell : access Gtk_Menu_Shell_Record'Class);

199.        --    Cancels the selection within the menu_shell. Causes a "selection-done"

200.        --    signal to be emitted.

201.        --

202.        --  </signals>

204.        Signal_Activate_Current : constant Glib.Signal_NameTo API docTo spec := "activate_current";

205.        Signal_Cancel           : constant Glib.Signal_NameTo API docTo spec := "cancel";

206.        Signal_Cycle_Focus      : constant Glib.Signal_NameTo API docTo spec := "cycle_focus";

207.        Signal_Deactivate       : constant Glib.Signal_NameTo API docTo spec := "deactivate";

208.        Signal_Move_Current     : constant Glib.Signal_NameTo API docTo spec := "move_current";

209.        Signal_Selection_Done   : constant Glib.Signal_NameTo API docTo spec := "selection-done";

211.     private

212.        type Gtk_Menu_Shell_RecordTo API docTo spec is new

213.          Gtk.Container.Gtk_Container_RecordTo API docTo specTo body with null record;

215.        Take_Focus_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

216.          Glib.Properties.BuildTo API docTo specTo body ("take-focus");

218.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_menu_shell_get_type");

219.     end Gtk.Menu_ShellTo API docTo specTo body;