## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                Copyright (C) 2006-2013, 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 represent operations that the user can perform, along with some

31.     --  information on how it should be presented in the interface. Each action

32.     --  provides methods to create icons, menu items and toolbar items representing

33.     --  itself.

34.     --

35.     --  As well as the callback that is called when the action gets activated, the

36.     --  following also gets associated with the action:

37.     --    - a name (not translated, for path lookup)

38.     --    - a label (translated, for display)

39.     --    - an accelerator

40.     --    - whether label indicates a stock id

41.     --    - a tooltip (optional, translated)

42.     --    - a toolbar label (optional, shorter than label)

43.     --

44.     --  The action will also have some state information:

45.     --    - visible (shown/hidden)

46.     --    - sensitive (enabled/disabled)

47.     --

48.     --  Apart from regular actions, there are toggle actions, which can be toggled

49.     --  between two states and radio actions, of which only one in a group can be

50.     --  in the "active" state. Other actions can be implemented as Gtk_Action

51.     --  subclasses.

52.     --

53.     --  Each action can have one or more proxy menu item, toolbar button or other

54.     --  proxy widgets. Proxies mirror the state of the action (text label, tooltip,

55.     --  icon, visible, sensitive, etc), and should change when the action's state

56.     --  changes. When the proxy is activated, it should activate its action.

57.     --  </description>

58.     --  <c_version>2.16.6</c_version>

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

61.     with Glib.G_IconTo API docTo specTo body;

62.     with Glib.ObjectTo API docTo specTo body;

63.     with Glib.PropertiesTo API docTo specTo body;

64.     with Gtk.Accel_GroupTo API docTo specTo body;

65.     with Gtk.EnumsTo API docTo specTo body;

66.     with Gtk.WidgetTo API docTo specTo body;

67.     with System;

69.     package Gtk.ActionTo API docTo specTo body is

71.        type Gtk_Action_RecordTo API docTo body is new Glib.Object.GObject_RecordTo API docTo specTo body with private;

72.        type Gtk_Action is access all Gtk_Action_RecordTo API docTo specTo body'Class;

74.        procedure Gtk_NewTo API docTo body

75.          (Action   : out Gtk_ActionTo API docTo spec;

76.           Name     : String;

77.           Label    : String;

78.           Tooltip  : String := "";

79.           Stock_Id : String := "");

80.        procedure InitializeTo API docTo body

81.          (Action   : access Gtk_Action_RecordTo API docTo specTo body'Class;

82.           Name     : String;

83.           Label    : String;

84.           Tooltip  : String := "";

85.           Stock_Id : String := "");

86.        --  Creates a new Gtk_Action object. To add the action to a Gtk_Action_Group

87.        --  and set the accelerator for the action, call

88.        --  Gtk.Action_Group.Add_Action_With_Accel.

89.        --  Name must be a unique name for the action. Label is the label displayed

90.        --  in menu items and on buttons.

92.        function ConvertTo API docTo body (C_Object : System.Address) return Gtk_ActionTo API docTo spec;

93.        --  Convert a C object to a Gtk_Action. The type of the C object must match,

94.        --  of course.

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

97.        --  Return the internal value associated with a Gtk_Action

99.        procedure ActivateTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body);

100.        --  Emits the "activate" signal on the specified action, if it isn't

101.        --  insensitive. This gets called by the proxy widgets when they get

102.        --  activated.

103.        --  It can also be used to manually activate an action.

105.        procedure Connect_AcceleratorTo API docTo body    (Action : access Gtk_Action_RecordTo API docTo specTo body);

106.        procedure Disconnect_AcceleratorTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body);

107.        --  Installs the accelerator for Action if Action has an accel path and

108.        --  group. See Set_Accel_Path and Set_Accel_Group.

109.        --  Since multiple proxies may independently trigger the installation

110.        --  of the accelerator, the Action counts the number of times this

111.        --  function has been called and doesn't remove the accelerator until

112.        --  Disconnect_Accelerator has been called as many times.

114.        function Create_IconTo API docTo body

115.          (Action    : access Gtk_Action_RecordTo API docTo specTo body;

116.           Icon_Size : Gtk.Enums.Gtk_Icon_SizeTo API docTo spec) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

117.        --  This function is intended for use by action implementations to

118.        --  create icons displayed in the proxy widgets.

119.        --  Returns a widget that displays the icon for this action.

121.        function Get_GIconTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body)

122.           return Glib.G_Icon.G_IconTo API docTo spec;

123.        procedure Set_GIconTo API docTo body

124.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

125.           Icon   : Glib.G_Icon.G_IconTo API docTo spec);

126.        --  Gets/Sets the Action's G_Icon.

128.        function Get_Icon_NameTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

129.        procedure Set_Icon_NameTo API docTo body

130.          (Action    : access Gtk_Action_RecordTo API docTo specTo body;

131.           Icon_Name : String);

132.        --  Gets/Sets the Action's icon name.

134.        function Get_Is_ImportantTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body)

135.           return Boolean;

136.        procedure Set_Is_ImportantTo API docTo body

137.          (Action       : access Gtk_Action_RecordTo API docTo specTo body;

138.           Is_Important : Boolean);

139.        --  Gets/Sets whether or not Action is important.

141.        function Get_LabelTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

142.        procedure Set_LabelTo API docTo body

143.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

144.           Label  : String);

145.        --  Gets/Sets the label text associated with Action.

147.        function Get_Short_LabelTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

148.        procedure Set_Short_LabelTo API docTo body

149.          (Action      : access Gtk_Action_RecordTo API docTo specTo body;

150.           Short_Label : String);

151.        --  Gets/Sets the short label text of Action.

153.        function Get_Stock_IdTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

154.        procedure Set_Stock_IdTo API docTo body

155.          (Action   : access Gtk_Action_RecordTo API docTo specTo body;

156.           Stock_Id : String);

157.        --  Gets/Sets the stock id of Action.

159.        function Get_TooltipTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

160.        procedure Set_TooltipTo API docTo body

161.          (Action  : access Gtk_Action_RecordTo API docTo specTo body;

162.           Tooltip : String);

163.        --  Gets/Sets the tooltip text associated with Action.

165.        function Get_Visible_HorizontalTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body)

166.           return Boolean;

167.        procedure Set_Visible_HorizontalTo API docTo body

168.          (Action             : access Gtk_Action_RecordTo API docTo specTo body;

169.           Visible_Horizontal : Boolean);

170.        --  Gets/Sets whether Action is visible when horizontal.

172.        function Get_Visible_VerticalTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body)

173.           return Boolean;

174.        procedure Set_Visible_VerticalTo API docTo body

175.          (Action           : access Gtk_Action_RecordTo API docTo specTo body;

176.           Visible_Vertical : Boolean);

177.        --  Gets/Sets whether Action is visible when vertical.

179.        function Create_MenuTo API docTo body

180.          (Action : access Gtk_Action_RecordTo API docTo specTo body)

181.           return Gtk.Widget.Gtk_WidgetTo API docTo spec;

182.        --  If Action provides a Gtk_Menu widget as a submenu for the menu

183.        --  item or the toolbar item it creates, this function returns an

184.        --  instance of that menu.

185.        --  Since: 2.12

187.        function Create_Menu_ItemTo API docTo body

188.          (Action : access Gtk_Action_RecordTo API docTo specTo body) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

189.        --  Creates a menu item widget that proxies for the given action.

191.        function Create_Tool_ItemTo API docTo body

192.          (Action : access Gtk_Action_RecordTo API docTo specTo body) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

193.        --  Creates a toolbar item widget that proxies for the given action.

195.        procedure Set_Accel_GroupTo API docTo body

196.          (Action      : access Gtk_Action_RecordTo API docTo specTo body;

197.           Accel_Group : Gtk.Accel_Group.Gtk_Accel_GroupTo API docTo spec := null);

198.        --  Sets the Gtk_Accel_Group in which the accelerator for this action

199.        --  will be installed.

201.        procedure Set_Accel_PathTo API docTo body

202.          (Action : access Gtk_Action_RecordTo API docTo specTo body; Accel_Path : String);

203.        function Get_Accel_PathTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

204.        --  Sets the accel path for this action.  All proxy widgets associated

205.        --  with the action will have this accel path, so that their

206.        --  accelerators are consistent.

208.        function Get_NameTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return String;

209.        --  Returns the name of the action.

211.        procedure Set_SensitiveTo API docTo body

212.          (Action    : access Gtk_Action_RecordTo API docTo specTo body; Sensitive : Boolean);

213.        function Get_SensitiveTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return Boolean;

214.        --  Returns whether the action itself is sensitive. Note that this doesn't

215.        --  necessarily mean effective sensitivity. See Is_Sensitive for that.

217.        function Is_SensitiveTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return Boolean;

218.        --  Returns whether the action is effectively sensitive.

219.        --  Returns True if teh action and its associated action group are both

220.        --  sensitive.

222.        procedure Set_VisibleTo API docTo body

223.          (Action : access Gtk_Action_RecordTo API docTo specTo body; Visible : Boolean);

224.        function Get_VisibleTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return Boolean;

225.        --  Returns whether the action itself is visible. Note that this doesn't

226.        --  necessarily mean effective visibility. See Is_Visible for that.

228.        function Is_VisibleTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body) return Boolean;

229.        --  Returns whether the action is effectively visible.

230.        --  Returns True if the action and its associated action group are both

231.        --  visible.

233.        -------------

234.        -- Proxies --

235.        -------------

237.        function Get_ProxiesTo API docTo body

238.          (Action : access Gtk_Action_RecordTo API docTo specTo body) return Gtk.Widget.Widget_SList.GSlistTo API docTo specTo body;

239.        --  Returns the proxy widgets for an action. The returned list must not be

240.        --  modified

242.        function Gtk_Widget_Get_ActionTo API docTo body

243.          (Widget : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body) return Gtk_ActionTo API docTo spec;

244.        pragma Obsolescent (Gtk_Widget_Get_ActionTo API docTo specTo body);

245.        --  Returns the action that Widget is a proxy for.

246.        --  See also Get_Proxies.

247.        --  Since: 2.10

249.        procedure Connect_ProxyTo API docTo body

250.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

251.           Proxy  : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

252.        pragma Obsolescent (Connect_ProxyTo API docTo specTo body);

253.        procedure Disconnect_ProxyTo API docTo body

254.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

255.           Proxy  : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

256.        pragma Obsolescent (Disconnect_ProxyTo API docTo specTo body);

257.        --  Connects a widget to an action object as a proxy. Synchronises various

258.        --  properties of the action with the widget (such as label text, icon,

259.        --  tooltip, etc), and attaches a callback so that the action gets activated

260.        --  when the proxy widget does.

261.        --  If the widget is already connected to an action, it is disconnected

262.        --  first.

263.        --  Disconnect_Proxy does not destroy the widget.

265.        procedure Block_ActivateTo API docTo body   (Action : access Gtk_Action_RecordTo API docTo specTo body);

266.        procedure Unblock_ActivateTo API docTo body (Action : access Gtk_Action_RecordTo API docTo specTo body);

267.        --  Disable or reenable activation signals from the action.  This is

268.        --  needed when updating the state of your proxy widget could result

269.        --  in calling Activate.  This is a convenience function to avoid

270.        --  recursing in those cases (updating toggle state for instance).

272.        procedure Block_Activate_FromTo API docTo body

273.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

274.           Proxy  : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

275.        pragma Obsolescent (Block_Activate_FromTo API docTo specTo body);

276.        procedure Unblock_Activate_FromTo API docTo body

277.          (Action : access Gtk_Action_RecordTo API docTo specTo body;

278.           Proxy  : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

279.        pragma Obsolescent (Unblock_Activate_FromTo API docTo specTo body);

280.        --  Disables calls to the Activate function by signals on the given proxy

281.        --  widget. This is used to break notification loops for things like check

282.        --  or radio actions.

283.        --  This function is intended for use by action implementations.

285.        ----------------

286.        -- Properties --

287.        ----------------

289.        --  <properties>

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

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

292.        --

293.        --  Name:  Action_Group_Property

294.        --  Type:  Object

295.        --  Descr: The Gtk_Action_Group this Gtk_Action is associated with, or NULL

296.        --        (for internal use).

297.        --

298.        --  Name:  GIcon_Property

299.        --  Type:  Object

300.        --  Descr: The GIcon being displayed

301.        --

302.        --  Name:  Hide_If_Empty_Property

303.        --  Type:  Boolean

304.        --  Descr: When TRUE, empty menu proxies for this action are hidden.

305.        --

306.        --  Name:  Icon_Name_Property

307.        --  Type:  String

308.        --  Descr: The name of the icon from the icon theme

309.        --

310.        --  Name:  Is_Important_Property

311.        --  Type:  Boolean

312.        --  Descr: Whether the action is considered important.

313.        --

314.        --  Name:  Label_Property

315.        --  Type:  String

316.        --  Descr: The label used for menu items and buttons

317.        --

318.        --  Name:  Name_Property

319.        --  Type:  String

320.        --  Descr: A unique name for the action.

321.        --

322.        --  Name:  Sensitive_Property

323.        --  Type:  Boolean

324.        --  Descr: Whether the action is enabled.

325.        --

326.        --  Name:  Short_Label_Property

327.        --  Type:  String

328.        --  Descr: A shorter label that may be used on toolbar buttons.

329.        --

330.        --  Name:  Stock_Id_Property

331.        --  Type:  String

332.        --  Descr: The stock icon displayed in widgets representing

333.        --

334.        --  Name:  Tooltip_Property

335.        --  Type:  String

336.        --  Descr: A tooltip for this action.

337.        --

338.        --  Name:  Visible_Property

339.        --  Type:  Boolean

340.        --  Descr: Whether the action is visible.

341.        --

342.        --  Name:  Visible_Horizontal_Property

343.        --  Type:  Boolean

344.        --  Descr: Whether the toolbar item is visible when the toolbar

345.        --

346.        --  Name:  Visible_Overflown_Property

347.        --  Type:  Boolean

348.        --  Descr: When TRUE, toolitem proxies for this action

349.        --

350.        --  Name:  Visible_Vertical_Property

351.        --  Type:  Boolean

352.        --  Descr: Whether the toolbar item is visible when the toolbar

353.        --

354.        --  </properties>

356.        Action_Group_Property       : constant Glib.Properties.Property_ObjectTo API docTo spec;

357.        GIcon_Property              : constant Glib.Properties.Property_ObjectTo API docTo spec;

358.        Hide_If_Empty_Property      : constant Glib.Properties.Property_BooleanTo API docTo spec;

359.        Icon_Name_Property          : constant Glib.Properties.Property_StringTo API docTo spec;

360.        Is_Important_Property       : constant Glib.Properties.Property_BooleanTo API docTo spec;

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

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

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

364.        Short_Label_Property        : constant Glib.Properties.Property_StringTo API docTo spec;

365.        Stock_Id_Property           : constant Glib.Properties.Property_StringTo API docTo spec;

366.        Tooltip_Property            : constant Glib.Properties.Property_StringTo API docTo spec;

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

368.        Visible_Horizontal_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

369.        Visible_Overflown_Property  : constant Glib.Properties.Property_BooleanTo API docTo spec;

370.        Visible_Vertical_Property   : constant Glib.Properties.Property_BooleanTo API docTo spec;

372.        -------------

373.        -- Signals --

374.        -------------

376.        --  <signals>

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

378.        --

379.        --  - "activate"

380.        --    procedure Handler (Action : access Gtk_Action_Record'Class);

381.        --    The "activate" signal is emitted when the action is activated.

382.        --  </signals>

384.        Signal_Activate : constant Glib.Signal_NameTo API docTo spec := "activate";

386.     private

387.        type Gtk_Action_RecordTo API docTo spec is new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

389.        Action_Group_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

390.          Glib.Properties.BuildTo API docTo specTo body ("action-group");

391.        GIcon_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

392.          Glib.Properties.BuildTo API docTo specTo body ("gicon");

393.        Hide_If_Empty_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

394.          Glib.Properties.BuildTo API docTo specTo body ("hide-if-empty");

395.        Icon_Name_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

396.          Glib.Properties.BuildTo API docTo specTo body ("icon-name");

397.        Is_Important_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

398.          Glib.Properties.BuildTo API docTo specTo body ("is-important");

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

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

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

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

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

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

405.        Short_Label_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

406.          Glib.Properties.BuildTo API docTo specTo body ("short-label");

407.        Stock_Id_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

408.          Glib.Properties.BuildTo API docTo specTo body ("stock-id");

409.        Tooltip_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

410.          Glib.Properties.BuildTo API docTo specTo body ("tooltip");

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

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

413.        Visible_Horizontal_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

414.          Glib.Properties.BuildTo API docTo specTo body ("visible-horizontal");

415.        Visible_Overflown_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

416.          Glib.Properties.BuildTo API docTo specTo body ("visible-overflown");

417.        Visible_Vertical_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

418.          Glib.Properties.BuildTo API docTo specTo body ("visible-vertical");

420.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_action_get_type");

421.     end Gtk.ActionTo API docTo specTo body;

423.     --  No binding: gtk_action_get_accel_closure