## 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-2010, 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.     --  This widget represents one of the lines in a menu, on which the user can

32.     --  click to execute an action. The menu items can be bound to a submenu, so

33.     --  that clicking on them will in fact display the submenu on the screen.

34.     --

35.     --  They can also be associated with key shortcuts (called accelerators). See

36.     --  the subprogram Set_Accel_Path, and the subprograms in the package

37.     --  Gtk.Accel_Map.

38.     --

39.     --  Activating the proper options in the theme files will allow the user to

40.     --  interactively modify the shortcuts.

41.     --  </description>

42.     --  <c_version>2.16.6</c_version>

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

45.     with Glib.PropertiesTo API docTo specTo body;

46.     with Gtk.ItemTo API docTo specTo body;

47.     with Gtk.WidgetTo API docTo specTo body;

49.     package Gtk.Menu_ItemTo API docTo specTo body is

51.        type Gtk_Menu_Item_RecordTo API docTo body is new Item.Gtk_Item_RecordTo API docTo specTo body with private;

52.        type Gtk_Menu_Item is access all Gtk_Menu_Item_RecordTo API docTo specTo body'Class;

54.        Null_Submenu : constant Widget.Gtk_WidgetTo API docTo spec;

56.        procedure Gtk_NewTo API docTo body

57.          (Menu_Item : out Gtk_Menu_ItemTo API docTo spec; Label : UTF8_StringTo API docTo spec := "");

58.        procedure InitializeTo API docTo body

59.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class; Label : UTF8_StringTo API docTo spec);

60.        --  Creates or initializes a new menu item containing a simple label.

62.        procedure Gtk_New_With_MnemonicTo API docTo body

63.          (Menu_Item : out Gtk_Menu_ItemTo API docTo spec;

64.           Label     : UTF8_StringTo API docTo spec);

65.        procedure Initialize_With_MnemonicTo API docTo body

66.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body'Class;

67.           Label     : UTF8_StringTo API docTo spec);

68.        --  Creates or initializes a new Gtk_Menu_Item containing a label.

69.        --  The label is created using Gtk.Label.Gtk_New_With_Mnemonic, so

70.        --  underscores in Label indicate the mnemonic for the menu item.

71.        --

72.        --  Warning: with some versions of gtk+, the menu_item will not be properly

73.        --  destroyed when you remove it from its parent menu, if you created it

74.        --  with a non-empty Label. In this case, you first need to destroy the

75.        --  child of the Menu_Item, and then remove it from its parent menu.

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

78.        --  Return the internal value associated with a Gtk_Menu_Item.

80.        procedure Set_SubmenuTo API docTo body

81.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body;

82.           Submenu   : access Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

83.        function Get_SubmenuTo API docTo body

84.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

85.        --  Set or Get the submenu underneath Menu_Item.

87.        procedure Set_LabelTo API docTo body

88.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body;

89.           Label     : String);

90.        function Get_LabelTo API docTo body

91.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body)

92.           return String;

93.        --  Controls the text in Menu_Item's label.

95.        procedure Set_Right_JustifiedTo API docTo body

96.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body;

97.           Justify   : Boolean := True);

98.        function Get_Right_JustifiedTo API docTo body

99.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body) return Boolean;

100.        --  Sets whether the menu item appears justified at the right side of a menu

101.        --  bar. This was traditionally done for "Help" menu items, but is now

102.        --  considered a bad idea. (If the widget layout is reversed for a

103.        --  right-to-left language like Hebrew or Arabic, right-justified-menu-items

104.        --  appear at the left.)

106.        procedure Set_Use_UnderlineTo API docTo body

107.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body;

108.           Setting   : Boolean);

109.        function Get_Use_UnderlineTo API docTo body

110.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body)

111.           return Boolean;

112.        --  If true, an underline in the text indicates the next character should be

113.        --  used for the mnemonic accelerator key.

115.        procedure Set_Accel_PathTo API docTo body

116.          (Menu_Item  : access Gtk_Menu_Item_RecordTo API docTo specTo body;

117.           Accel_Path : UTF8_StringTo API docTo spec);

118.        function Get_Accel_PathTo API docTo body

119.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body)

120.           return String;

121.        --  Set the path that will be used to reference the widget in calls to the

122.        --  subprograms in Gtk.Accel_Map. This means, for instance, that the widget

123.        --  is fully setup for interactive modification of the shortcuts by the

124.        --  user, should he choose to activate this possibility in his themes (see

125.        --  gtk-accel_map.ads for more information).

127.        -----------------

128.        -- Obsolescent --

129.        -----------------

130.        --  All subprograms below are now obsolescent in gtk+. They might be removed

131.        --  from future versions of gtk+ (and therefore GtkAda).

132.        --  To find out whether your code uses any of these, we recommend compiling

133.        --  with the -gnatwj switch

134.        --  <doc_ignore>

136.        procedure Remove_SubmenuTo API docTo body (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body);

137.        pragma Obsolescent; --  Remove_Submenu

138.        --  Remove the menu_item's submenu

139.        --

140.        --  Deprecated: 2.12: Remove_Submenu deprecated and should not be used

141.        --  in newly written code. Use Set_Submenu instead.

143.        procedure Set_Right_Justify

144.          (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body;

145.           Justify   : Boolean) renames Set_Right_JustifiedTo API docTo specTo body;

146.        --  pragma Obsolescent;

147.        --  This procedure is needed by Gate to automate the code generation.

149.        procedure Right_JustifyTo API docTo body (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body);

150.        pragma Obsolescent;

151.        --  Use Set_Right_Justified with Justify = True instead.

153.        --  </doc_ignore>

155.        -------------

156.        -- Signals --

157.        -------------

159.        --  <signals>

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

161.        --

162.        --  - "activate"

163.        --    procedure Handler

164.        --      (Menu_Item : access Gtk_Menu_Item_Record'Class);

165.        --    Emitted when the menu item has been activated, ie the user has clicked

166.        --    on it (or use a key shortcut for this)

167.        --

168.        --  - "activate_item"

169.        --    procedure Handler

170.        --      (Menu_Item : access Gtk_Menu_Item_Record'Class);

171.        --    ???

172.        --

173.        --  - "toggle_size_request"

174.        --    procedure Handler

175.        --      (Menu_Item : access Gtk_Menu_Item_Record'Class;

176.        --       Request   : Gtk_Requisition_Access);

177.        --    Query the menu item to ask for its preferred size (this might not be

178.        --    the one actually allocated for it, depending on screen space)

179.        --

180.        --  - "toggle_size_allocate"

181.        --    procedure Handler

182.        --      (Menu_Item  : access Gtk_Menu_Item_Record'Class;

183.        --       Allocation : Gtk_Allocation_Request);

184.        --    You should emit this signal to allocate a specific size for the item.

185.        --    In practice, you will not need to do this yourself, since gtk+ takes

186.        --    care of it correctly most of the time.

187.        --

188.        --  </signals>

189.        --

190.        --  If you want to get a signal every time the menu item is made visible

191.        --  on screen, for instance because you want to dynamically set its

192.        --  sensitive state, you should connect to the "map" signal of the

193.        --  toplevel menu, as in:

194.        --     Gtkada.Handlers.Widget_Callback.Object_Connect

195.        --        (Get_Toplevel (Item), "map",

196.        --         Slot_Object => Item);

198.        Signal_Activate             : constant Glib.Signal_NameTo API docTo spec :=

199.                                        "activate";

200.        Signal_Activate_Item        : constant Glib.Signal_NameTo API docTo spec :=

201.                                        "activate_item";

202.        Signal_Toggle_Size_Allocate : constant Glib.Signal_NameTo API docTo spec :=

203.                                        "toggle_size_allocate";

204.        Signal_Toggle_Size_Request  : constant Glib.Signal_NameTo API docTo spec :=

205.                                        "toggle_size_request";

207.        procedure Gtk_SelectTo API docTo body (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body);

208.        --  Emits the "select" signal on Menu_Item

210.        procedure DeselectTo API docTo body (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body);

211.        --  Emits the "deselect" signal on Menu_Item

213.        procedure ActivateTo API docTo body (Menu_Item : access Gtk_Menu_Item_RecordTo API docTo specTo body);

214.        --  Emits the "activate" signal on Menu_Item

216.        procedure Toggle_Size_AllocateTo API docTo body

217.          (Menu_Item  : access Gtk_Menu_Item_RecordTo API docTo specTo body;

218.           AllocationTo API docTo body : Gtk.Widget.Gtk_AllocationTo API docTo spec);

219.        --  Emits the "toggle_size_allocate" signal on Menu_Item

221.        procedure Toggle_Size_RequestTo API docTo body

222.          (Menu_Item   : access Gtk_Menu_Item_RecordTo API docTo specTo body;

223.           RequisitionTo API docTo body : out Gtk.Widget.Gtk_RequisitionTo API docTo spec);

224.        --  Emits the "toggle_size_request" signal on Menu_Item

226.        ----------------

227.        -- Properties --

228.        ----------------

230.        --  <properties>

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

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

233.        --

234.        --  Name:  Accel_Path_Property

235.        --  Type:  String

236.        --  Descr: Sets the accelerator path of the menu item

237.        --

238.        --  Name:  Label_Property

239.        --  Type:  String

240.        --  Descr: The text for the child label

241.        --

242.        --  Name:  Right_Justified_Property

243.        --  Type:  Boolean

244.        --  Descr: Sets whether the menu item appears justified at the right

245.        --         side of a menu bar

246.        --

247.        --  Name:  Submenu_Property

248.        --  Type:  Object

249.        --  Descr: The submenu attached to the menu item, or null if it has none

250.        --

251.        --  Name:  Use_Underline_Property

252.        --  Type:  Boolean

253.        --  Descr: If set, an underline in the text indicates the next character

254.        --         should be used for the mnemonic accelerator key

255.        --

256.        --  </properties>

258.        Accel_Path_Property      : constant Glib.Properties.Property_StringTo API docTo spec;

259.        Label_Property           : constant Glib.Properties.Property_StringTo API docTo spec;

260.        Right_Justified_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

261.        Submenu_Property         : constant Glib.Properties.Property_ObjectTo API docTo spec;

262.        Use_Underline_Property   : constant Glib.Properties.Property_BooleanTo API docTo spec;

264.        ----------------------

265.        -- Style Properties --

266.        ----------------------

267.        --  The following properties can be changed through the gtk theme and

268.        --  configuration files, and retrieved through Gtk.Widget.Style_Get_Property

270.        --  <style_properties>

271.        --  Name:  Arrow_Scaling_Property

272.        --  Type:  Float

273.        --  Descr: Amount of space used up by arrow, relative to the menu item's

274.        --         font size

275.        --

276.        --  Name:  Width_Chars_Property

277.        --  Type:  Int

278.        --  Descr: The minimum desired width of the menu item in characters

279.        --

280.        --  </style_properties>

282.        Arrow_Scaling_Property : constant Glib.Properties.Property_FloatTo API docTo spec;

283.        Width_Chars_Property   : constant Glib.Properties.Property_IntTo API docTo spec;

285.     private

286.        type Gtk_Menu_Item_RecordTo API docTo spec is new Item.Gtk_Item_RecordTo API docTo specTo body with null record;

288.        Accel_Path_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

289.          Glib.Properties.BuildTo API docTo specTo body ("accel-path");

290.        Label_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

291.          Glib.Properties.BuildTo API docTo specTo body ("label");

292.        Right_Justified_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

293.          Glib.Properties.BuildTo API docTo specTo body ("right-justified");

294.        Submenu_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

295.          Glib.Properties.BuildTo API docTo specTo body ("submenu");

296.        Use_Underline_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

297.          Glib.Properties.BuildTo API docTo specTo body ("use-underline");

299.        Arrow_Scaling_PropertyTo API docTo spec : constant Glib.Properties.Property_FloatTo API docTo spec :=

300.          Glib.Properties.BuildTo API docTo specTo body ("arrow-scaling");

301.        Width_Chars_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

302.          Glib.Properties.BuildTo API docTo specTo body ("width-chars");

304.        Null_SubmenuTo API docTo spec : constant Widget.Gtk_WidgetTo API docTo spec := null;

306.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_menu_item_get_type");

307.     end Gtk.Menu_ItemTo API docTo specTo body;

309.     --  missing:

310.     --  procedure Toggle_Size_Request

311.     --    (Menu_Item   : access Gtk_Menu_Item_Record;

312.     --     Requisition : int*);

313.     --  Emit the signal "toggle_size_request"

315.     --  procedure Toggle_Size_Allocate

316.     --    (Menu_Item  : access Gtk_Menu_Item_Record;

317.     --     Allocation : Gint);

318.     --  Emit the signal "toggle_size_allocate"