## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2006-2011, AdaCore                   --

5.     --                                                                   --

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

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

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

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

10.     --                                                                   --

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

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

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

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

15.     --                                                                   --

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

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

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

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

20.     --                                                                   --

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

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

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

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

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

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

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  Actions are organised into groups. An action group is essentially a map

31.     --  from names to Gtk_Action objects.

32.     --

33.     --  All actions that would make sense to use in a particular context should be

34.     --  in a single group. Multiple action groups may be used for a particular user

35.     --  interface. In fact, it is expected that most nontrivial applications will

36.     --  make use of multiple groups. For example, in an application that can edit

37.     --  multiple documents, one group holding global actions (e.g. quit, about,

38.     --  new), and one group per document holding actions that act on that document

39.     --  (eg. save, cut/copy/paste, etc). Each window's menus would be constructed

40.     --  from a combination of two action groups.

41.     --

42.     --  Accelerators are handled by the GTK+ accelerator map. All actions are

43.     --  assigned an accelerator path (which normally has the form

44.     --  "<Actions>/group-name/action-name") and a shortcut is associated with this

45.     --  accelerator path. All menu items and tool items take on this accelerator

46.     --  path. The GTK+ accelerator map code makes sure that the correct shortcut is

47.     --  displayed next to the menu item.

48.     --  </description>

49.     --  <c_version>2.8.17</c_version>

50.     --  <group>Action-based menus</group>

52.     with Glib.ObjectTo API docTo specTo body;

53.     with Glib.PropertiesTo API docTo specTo body;

54.     with Gtk.ActionTo API docTo specTo body;

55.     with Interfaces.C.Strings;

56.     with System;

58.     package Gtk.Action_GroupTo API docTo specTo body is

60.        type Gtk_Action_Group_Record is new Glib.Object.GObject_RecordTo API docTo specTo body with

61.          null record;

62.        type Gtk_Action_Group is access all Gtk_Action_Group_RecordTo API docTo spec'Class;

64.        procedure Gtk_NewTo API docTo body (Group : out Gtk_Action_GroupTo API docTo spec; Name : String);

65.        procedure InitializeTo API docTo body

66.          (Group : access Gtk_Action_Group_RecordTo API docTo spec'Class; Name : String);

67.        --  Creates a new Gtk_Action_Group object. The name of the action group

68.        --  is used when associating keybindings with the actions.

70.        function Get_TypeTo API docTo body return GTypeTo API docTo spec;

71.        --  Return the internal value associated with a Gtk_Action_Group.

73.        function Get_ActionTo API docTo body

74.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

75.           Action_Name  : String) return Gtk.Action.Gtk_ActionTo API docTo spec;

76.        --  Looks up an action in the action group by name, or null if no such

77.        --  action exists.

79.        function Get_NameTo API docTo body

80.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec) return String;

81.        --  Gets the name of the action group.

83.        procedure Set_SensitiveTo API docTo body

84.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec; Sensitive : Boolean);

85.        function Get_SensitiveTo API docTo body

86.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec) return Boolean;

87.        --  Returns True if the group is sensitive.  The constituent actions

88.        --  can only be logically sensitive (see Gtk.Action.Is_Sensitive) if

89.        --  they are sensitive (see Gtk.Action.Get_Sensitive) and their group

90.        --  is sensitive.

92.        procedure Set_VisibleTo API docTo body

93.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec; Visible : Boolean);

94.        function Get_VisibleTo API docTo body

95.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec) return Boolean;

96.        --  Returns True if the group is visible.  The constituent actions

97.        --  can only be logically visible (see Gtk.Action.Is_Visible) if

98.        --  they are visible (see Gtk.Action.Get_Visible) and their group

99.        --  is visible.

101.        function List_ActionsTo API docTo body

102.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec)

103.          return Glib.Object.Object_Simple_List.GlistTo API docTo specTo body;

104.        --  Lists the actions in the action group. The returned list must be freed

105.        --  by the user.

107.        procedure Set_Translation_DomainTo API docTo body

108.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

109.           Domain       : String);

110.        --  Sets the translation domain and uses dgettext() for translating the

111.        --  Label and Tooltip of Gtk_Action_Entry's added by Add_Actions.

113.        ---------------------------------

114.        -- Adding and removing actions --

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

117.        type Action_EntryTo API docTo body        is private;

118.        type Radio_Action_EntryTo API docTo body  is private;

119.        type Toggle_Action_EntryTo API docTo body is private;

120.        --  An opaque structure describing an action entry

122.        type Action_Entry_Array is array (Natural range <>) of Action_EntryTo API docTo specTo body;

123.        type Radio_Action_Entry_Array

124.          is array (Natural range <>) of Radio_Action_EntryTo API docTo specTo body;

125.        type Toggle_Action_Entry_Array

126.          is array (Natural range <>) of Toggle_Action_EntryTo API docTo specTo body;

128.        type Action_Callback is access procedure

129.          (Action : System.Address; User_Data : System.Address);

130.        pragma Convention (C, Action_CallbackTo API docTo spec);

131.        --  Profile of callbacks when an action is activated. You must convert

132.        --  Action to a Gtk_Action through:

133.        --      Act : constant Gtk_Action := Convert (Action);

135.        type Radio_Action_Callback is access procedure

136.          (Group     : access Gtk.Action.Gtk_Action_RecordTo API docTo specTo body'Class;

137.           Current   : access Gtk.Action.Gtk_Action_RecordTo API docTo specTo body'Class;

138.           User_Data : System.Address);

139.        --   Called when an element of the Gtk_Radio_Action group is selected

141.        function CreateTo API docTo body

142.          (Name        : String;

143.           Label       : String := "";

144.           Stock_Id    : String := "";

145.           Accelerator : String := "";

146.           Tooltip     : String := "";

147.           Callback    : Action_CallbackTo API docTo spec := null) return Action_EntryTo API docTo specTo body;

148.        --  Create a new Action_Entry. The returned value must be freed by the

149.        --  caller.

151.        function CreateTo API docTo body

152.          (Name        : String;

153.           Label       : String := "";

154.           Stock_Id    : String := "";

155.           Accelerator : String := "";

156.           Tooltip     : String := "";

157.           Callback    : Action_CallbackTo API docTo spec := null;

158.           Is_Active   : Boolean := True) return Toggle_Action_EntryTo API docTo specTo body;

159.        --  Create a new Action_Entry. The returned value must be freed by the

160.        --  caller. Is_Active is the initial state of the button.

162.        function CreateTo API docTo body

163.          (Name        : String;

164.           Label       : String;

165.           Stock_Id    : String := "";

166.           Accelerator : String := "";

167.           Tooltip     : String := "";

168.           Value       : Glib.GintTo API docTo spec) return Radio_Action_EntryTo API docTo specTo body;

169.        --  Create a new Radio_Action_Entry. Value is the value set on the radio

170.        --  action (see Gtk.Radio_Action.Get_Current_Value)

172.        procedure FreeTo API docTo body (ActionTo API docTo body  : in out Action_EntryTo API docTo specTo body);

173.        procedure FreeTo API docTo body (Actions : in out Action_Entry_ArrayTo API docTo spec);

174.        procedure FreeTo API docTo body (ActionTo API docTo body  : in out Radio_Action_EntryTo API docTo specTo body);

175.        procedure FreeTo API docTo body (Actions : in out Radio_Action_Entry_ArrayTo API docTo spec);

176.        procedure FreeTo API docTo body (ActionTo API docTo body  : in out Toggle_Action_EntryTo API docTo specTo body);

177.        procedure FreeTo API docTo body (Actions : in out Toggle_Action_Entry_ArrayTo API docTo spec);

178.        --  Free Action and Actions

180.        procedure Add_ActionTo API docTo body

181.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

182.           Action       : access Gtk.Action.Gtk_Action_RecordTo API docTo specTo body'Class);

183.        --  Adds an action object to the action group. Note that this function

184.        --  does not set up the accel path of the action, which can lead to problems

185.        --  if a user tries to modify the accelerator of a menuitem associated with

186.        --  the action. Therefore you must either set the accel path yourself with

187.        --  Gtk.Action.Set_Accel_Path, or use Add_Action_With_Accel.

189.        procedure Remove_ActionTo API docTo body

190.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

191.           Action       : access Gtk.Action.Gtk_Action_RecordTo API docTo specTo body'Class);

192.        --  Removes an action object from the action group.

194.        procedure Add_Action_With_AccelTo API docTo body

195.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

196.           Action       : access Gtk.Action.Gtk_Action_RecordTo API docTo specTo body'Class;

197.           Accelerator  : String := "");

198.        --  Adds an action object to the action group and sets up the accelerator.

199.        --  If Accelerator is unspecified, attempts to use the accelerator

200.        --  associated with the stock_id of the action.

201.        --  Accel paths are set to <Actions>/group-name/action-name.

203.        procedure Add_ActionsTo API docTo body

204.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

205.           Entries      : Action_Entry_ArrayTo API docTo spec;

206.           User_Data    : System.Address := System.Null_Address;

207.           Destroy      : Glib.G_Destroy_Notify_AddressTo API docTo spec := null);

208.        --  This is a convenience function to create a number of actions and add

209.        --  them to the action group.

210.        --  Destroy is called when User_Data is no longer needed.

211.        --

212.        --  The "activate" signals of the actions are connected to the callbacks in

213.        --  Entries, and their accel paths are set to

214.        --  <Actions>/group-name/action-name.

216.        procedure Add_Radio_ActionsTo API docTo body

217.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

218.           Entries      : Radio_Action_Entry_ArrayTo API docTo spec;

219.           Value        : Glib.GintTo API docTo spec;

220.           On_Change    : Radio_Action_CallbackTo API docTo spec;

221.           User_Data    : System.Address := System.Null_Address;

222.           Destroy      : Glib.G_Destroy_Notify_AddressTo API docTo spec := null);

223.        --  This is a convenience routine to create a group of radio actions and

224.        --  add them to the action group.

225.        --

226.        --  The "changed" signal of the first radio action is connected to the

227.        --  On_Change callback and the accel paths of the actions are set to

228.        --    <Actions>/group-name/action-name

229.        --

230.        --  Value is the value of the action to activate initially, or -1 if no

231.        --  action should be activated.

232.        --  Destroy is called when User_Data is no longer necessary.

234.        procedure Add_Toggle_ActionsTo API docTo body

235.          (Action_Group : access Gtk_Action_Group_RecordTo API docTo spec;

236.           Entries      : Toggle_Action_Entry_ArrayTo API docTo spec;

237.           User_Data    : System.Address := System.Null_Address;

238.           Destroy      : Glib.G_Destroy_Notify_AddressTo API docTo spec := null);

239.        --  This is a convenience function to create a number of toggle actions and

240.        --  add them to the action group.

241.        --  The "activate" signals of the actions are connected to the callbacks and

242.        --  their accel paths are set to <Actions>/group-name/action-name.

243.        --  Destroy is called when User_Data is no longer necessary.

245.        ----------------

246.        -- Properties --

247.        ----------------

249.        --  <properties>

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

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

252.        --

253.        --  Name:  Name_Property

254.        --  Type:  String

255.        --  Descr: A name for the action group.

256.        --

257.        --  Name:  Sensitive_Property

258.        --  Type:  Boolean

259.        --  Descr: Whether the action group is enabled.

260.        --

261.        --  Name:  Visible_Property

262.        --  Type:  Boolean

263.        --  Descr: Whether the action group is visible.

264.        --

265.        --  </properties>

267.        Name_Property      : constant Glib.Properties.Property_StringTo API docTo spec;

268.        Sensitive_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

269.        Visible_Property   : constant Glib.Properties.Property_BooleanTo API docTo spec;

271.        -------------

272.        -- Signals --

273.        -------------

275.        --  <signals>

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

277.        --

278.        --  - "connect_proxy"

279.        --    procedure Handler

280.        --       (Group  : access Gtk_Action_Group_Record'Class;

281.        --        Action : access Gtk_Action_Record'Class;

282.        --        Proxy  : access Gtk_Widget_Record'Class);

283.        --    The connect_proxy signal is emitted after connecting a proxy to an

284.        --    action in the group. Note that the proxy may have been connected to a

285.        --    different action before.

286.        --    This is intended for simple customizations for which a custom action

287.        --    class would be too clumsy, e.g. showing tooltips for menuitems in the

288.        --    statusbar.

289.        --    Gtk_UI_Manager proxies the signal and provides global notification

290.        --    just before any action is connected to a proxy, which is probably more

291.        --    convenient to use.

292.        --

293.        --  - "disconnect_proxy"

294.        --    procedure Handler

295.        --       (Group  : access Gtk_Action_Group_Record'Class;

296.        --        Action : access Gtk_Action_Record'Class;

297.        --        Proxy  : access Gtk_Widget_Record'Class);

298.        --    The disconnect_proxy signal is emitted after disconnecting a proxy

299.        --    from an action in the group.

300.        --    Gtk_UI_Manager proxies the signal and provides global notification

301.        --    just before any action is connected to a proxy, which is probably more

302.        --    convenient to use.

303.        --

304.        --  - "post_activate"

305.        --    procedure Handler

306.        --       (Group  : access Gtk_Action_Group_Record'Class;

307.        --        Action : access Gtk_Action_Record'Class);

308.        --    The post_activate signal is emitted just after the action in the

309.        --    action_group is activated

310.        --    This is intended for Gtk_UI_Manager to proxy the signal and provide

311.        --    global notification just after any action is activated.

312.        --

313.        --  - "pre_activate"

314.        --    procedure Handler

315.        --       (Group  : access Gtk_Action_Group_Record'Class;

316.        --        Action : access Gtk_Action_Record'Class);

317.        --    The post_activate signal is emitted just before the action in the

318.        --    action_group is activated

319.        --    This is intended for Gtk_UI_Manager to proxy the signal and provide

320.        --    global notification just after any action is activated.

321.        --  </signals>

323.        Signal_Connect_Proxy    : constant Glib.Signal_NameTo API docTo spec := "connect_proxy";

324.        Signal_Disconnect_Proxy : constant Glib.Signal_NameTo API docTo spec := "disconnect_proxy";

325.        Signal_Post_Activate    : constant Glib.Signal_NameTo API docTo spec := "post_activate";

326.        Signal_Pre_Activate     : constant Glib.Signal_NameTo API docTo spec := "pre_activate";

328.     private

329.        Name_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

330.          Glib.Properties.BuildTo API docTo specTo body ("name");

331.        Sensitive_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

332.          Glib.Properties.BuildTo API docTo specTo body ("sensitive");

333.        Visible_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

334.          Glib.Properties.BuildTo API docTo specTo body ("visible");

336.        type Action_EntryTo API docTo spec is record

337.           Name         : Interfaces.C.Strings.chars_ptr;

338.           Stock_Id     : Interfaces.C.Strings.chars_ptr;

339.           Label        : Interfaces.C.Strings.chars_ptr;

340.           Accelerator  : Interfaces.C.Strings.chars_ptr;

341.           Tooltip      : Interfaces.C.Strings.chars_ptr;

342.           Callback     : Action_CallbackTo API docTo spec;

343.        end record;

344.        pragma Convention (C, Action_EntryTo API docTo specTo body);

346.        type Radio_Action_EntryTo API docTo spec is record

347.           Name         : Interfaces.C.Strings.chars_ptr;

348.           Stock_Id     : Interfaces.C.Strings.chars_ptr;

349.           Label        : Interfaces.C.Strings.chars_ptr;

350.           Accelerator  : Interfaces.C.Strings.chars_ptr;

351.           Tooltip      : Interfaces.C.Strings.chars_ptr;

352.           Value        : Glib.GintTo API docTo spec;

353.        end record;

354.        pragma Convention (C, Radio_Action_EntryTo API docTo specTo body);

356.        type Toggle_Action_EntryTo API docTo spec is record

357.           Name         : Interfaces.C.Strings.chars_ptr;

358.           Stock_Id     : Interfaces.C.Strings.chars_ptr;

359.           Label        : Interfaces.C.Strings.chars_ptr;

360.           Accelerator  : Interfaces.C.Strings.chars_ptr;

361.           Tooltip      : Interfaces.C.Strings.chars_ptr;

362.           Callback     : Action_CallbackTo API docTo spec;

363.           Is_Active    : Glib.GbooleanTo API docTo spec;

364.        end record;

365.        pragma Convention (C, Toggle_Action_EntryTo API docTo specTo body);

367.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_action_group_get_type");

368.     end Gtk.Action_GroupTo API docTo specTo body;

370.     --  Binding is through *_full

371.     --  No binding: gtk_action_group_add_actions

372.     --  No binding: gtk_action_group_add_radio_actions

373.     --  No binding: gtk_action_group_add_toggle_actions

375.     --  Binding might be needed later

376.     --  No binding: gtk_action_group_set_translate_func

377.     --  No binding: gtk_action_group_translate_string