## 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-2011, 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 package implements a general button widget. This button can be

32.     --  clicked on by the user to start any action. This button does not have

33.     --  multiple states, it can just be temporarily pressed while the mouse is on

34.     --  it, but does not keep its pressed state.

35.     --

36.     --  The gtk+ sources provide the following drawing that explains the role of

37.     --  the various spacings that can be set for a button:

38.     --

39.     --  </description>

40.     --  <screenshot>gtk-button</screenshot>

41.     --  <group>Buttons and Toggles</group>

42.     --  <testgtk>create_buttons.adb</testgtk>

44.     pragma Warnings (Off, "*is already use-visible*");

45.     with Gdk.WindowTo API docTo specTo body;      use Gdk.WindowTo API docTo specTo body;

46.     with GlibTo API docTo specTo body;            use GlibTo API docTo specTo body;

47.     with Glib.PropertiesTo API docTo specTo body; use Glib.PropertiesTo API docTo specTo body;

48.     with Glib.TypesTo API docTo specTo body;      use Glib.TypesTo API docTo specTo body;

49.     with Gtk.ActionTo API docTo specTo body;      use Gtk.ActionTo API docTo specTo body;

50.     with Gtk.ActivatableTo API docTo specTo body; use Gtk.ActivatableTo API docTo specTo body;

51.     with Gtk.BinTo API docTo specTo body;         use Gtk.BinTo API docTo specTo body;

52.     with Gtk.BuildableTo API docTo specTo body;   use Gtk.BuildableTo API docTo specTo body;

53.     with Gtk.EnumsTo API docTo specTo body;       use Gtk.EnumsTo API docTo specTo body;

54.     with Gtk.WidgetTo API docTo specTo body;      use Gtk.WidgetTo API docTo specTo body;

56.     package Gtk.ButtonTo API docTo specTo body is

58.        type Gtk_Button_Record is new Gtk_Bin_RecordTo API docTo spec with null record;

59.        type Gtk_Button is access all Gtk_Button_RecordTo API docTo spec'Class;

61.        ------------------

62.        -- Constructors --

63.        ------------------

65.        procedure Gtk_New_From_StockTo API docTo body

66.           (Button   : out Gtk_ButtonTo API docTo spec;

67.            Stock_Id : UTF8_StringTo API docTo spec);

68.        procedure Initialize_From_StockTo API docTo body

69.           (Button   : access Gtk_Button_RecordTo API docTo spec'Class;

70.            Stock_Id : UTF8_StringTo API docTo spec);

71.        --  Creates a new Gtk.Button.Gtk_Button containing the image and text from

72.        --  a stock item. Some stock ids have preprocessor macros like GTK_STOCK_OK

73.        --  and GTK_STOCK_APPLY. If Stock_Id is unknown, then it will be treated as

74.        --  a mnemonic label (as for Gtk.Button.Gtk_New_With_Mnemonic).

75.        --  "stock_id": the name of the stock item

77.        procedure Gtk_NewTo API docTo body (Button : out Gtk_ButtonTo API docTo spec; Label : UTF8_StringTo API docTo spec := "");

78.        procedure InitializeTo API docTo body

79.           (Button : access Gtk_Button_RecordTo API docTo spec'Class;

80.            Label  : UTF8_StringTo API docTo spec := "");

82.        procedure Gtk_New_With_MnemonicTo API docTo body

83.           (Button : out Gtk_ButtonTo API docTo spec;

84.            Label  : UTF8_StringTo API docTo spec);

85.        procedure Initialize_With_MnemonicTo API docTo body

86.           (Button : access Gtk_Button_RecordTo API docTo spec'Class;

87.            Label  : UTF8_StringTo API docTo spec);

88.        --  Creates a new Gtk.Button.Gtk_Button containing a label. If characters

89.        --  in Label are preceded by an underscore, they are underlined. If you need

90.        --  a literal underscore character in a label, use '__' (two underscores).

91.        --  The first underlined character represents a keyboard accelerator called

92.        --  a mnemonic. Pressing Alt and that key activates the button.

93.        --  "label": The text of the button, with an underscore in front of the

94.        --  mnemonic character

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

97.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_button_get_type");

99.        -------------

100.        -- Methods --

101.        -------------

103.        procedure ClickedTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec);

105.        procedure EnterTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec);

107.        procedure Get_AlignmentTo API docTo body

108.           (Button : access Gtk_Button_RecordTo API docTo spec;

109.            Xalign : out GfloatTo API docTo spec;

110.            Yalign : out GfloatTo API docTo spec);

111.        procedure Set_AlignmentTo API docTo body

112.           (Button : access Gtk_Button_RecordTo API docTo spec;

113.            Xalign : GfloatTo API docTo spec;

114.            Yalign : GfloatTo API docTo spec);

115.        --  Sets the alignment of the child. This property has no effect unless the

116.        --  child is a Gtk.Misc.Gtk_Misc or a GtkAligment.

117.        --  Since: gtk+ 2.4

118.        --  "xalign": the horizontal position of the child, 0.0 is left aligned,

119.        --  1.0 is right aligned

120.        --  "yalign": the vertical position of the child, 0.0 is top aligned, 1.0

121.        --  is bottom aligned

123.        function Get_Event_WindowTo API docTo body

124.           (Button : access Gtk_Button_RecordTo API docTo spec) return Gdk.Window.Gdk_WindowTo API docTo spec;

125.        --  Returns the button's event window if it is realized, null otherwise.

126.        --  This function should be rarely needed.

127.        --  Since: gtk+ 2.22

129.        function Get_Focus_On_ClickTo API docTo body

130.           (Button : access Gtk_Button_RecordTo API docTo spec) return Boolean;

131.        procedure Set_Focus_On_ClickTo API docTo body

132.           (Button         : access Gtk_Button_RecordTo API docTo spec;

133.            Focus_On_Click : Boolean);

134.        --  Sets whether the button will grab focus when it is clicked with the

135.        --  mouse. Making mouse clicks not grab focus is useful in places like

136.        --  toolbars where you don't want the keyboard focus removed from the main

137.        --  area of the application.

138.        --  Since: gtk+ 2.4

139.        --  "focus_on_click": whether the button grabs focus when clicked with the

140.        --  mouse

142.        function Get_ImageTo API docTo body

143.           (Button : access Gtk_Button_RecordTo API docTo spec) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

144.        procedure Set_ImageTo API docTo body

145.           (Button : access Gtk_Button_RecordTo API docTo spec;

146.            Image  : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

147.        --  Set the image of Button to the given widget. Note that it depends on

148.        --  the Gtk.Settings.Gtk_Settings:gtk-button-images setting whether the

149.        --  image will be displayed or not, you don't have to call Gtk.Widget.Show

150.        --  on Image yourself.

151.        --  Since: gtk+ 2.6

152.        --  "image": a widget to set as the image for the button

154.        function Get_Image_PositionTo API docTo body

155.           (Button : access Gtk_Button_RecordTo API docTo spec) return Gtk.Enums.Gtk_Position_TypeTo API docTo spec;

156.        procedure Set_Image_PositionTo API docTo body

157.           (Button   : access Gtk_Button_RecordTo API docTo spec;

158.            PositionTo API docTo body : Gtk.Enums.Gtk_Position_TypeTo API docTo spec);

159.        --  Sets the position of the image relative to the text inside the button.

160.        --  Since: gtk+ 2.10

161.        --  "position": the position

163.        function Get_LabelTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec) return UTF8_StringTo API docTo spec;

164.        procedure Set_LabelTo API docTo body

165.           (Button : access Gtk_Button_RecordTo API docTo spec;

166.            Label  : UTF8_StringTo API docTo spec);

167.        --  Sets the text of the label of the button to Str. This text is also used

168.        --  to select the stock item if Gtk.Button.Set_Use_Stock is used. This will

169.        --  also clear any previously set labels.

170.        --  "label": a string

172.        function Get_ReliefTo API docTo body

173.           (Button : access Gtk_Button_RecordTo API docTo spec) return Gtk.Enums.Gtk_Relief_StyleTo API docTo spec;

174.        procedure Set_ReliefTo API docTo body

175.           (Button   : access Gtk_Button_RecordTo API docTo spec;

176.            NewstyleTo API docTo body : Gtk.Enums.Gtk_Relief_StyleTo API docTo spec);

178.        function Get_Use_StockTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec) return Boolean;

179.        procedure Set_Use_StockTo API docTo body

180.           (Button    : access Gtk_Button_RecordTo API docTo spec;

181.            Use_Stock : Boolean);

182.        --  If True, the label set on the button is used as a stock id to select

183.        --  the stock item for the button.

184.        --  "use_stock": True if the button should use a stock item

186.        function Get_Use_UnderlineTo API docTo body

187.           (Button : access Gtk_Button_RecordTo API docTo spec) return Boolean;

188.        procedure Set_Use_UnderlineTo API docTo body

189.           (Button        : access Gtk_Button_RecordTo API docTo spec;

190.            Use_Underline : Boolean);

191.        --  If true, an underline in the text of the button label indicates the

192.        --  next character should be used for the mnemonic accelerator key.

193.        --  "use_underline": True if underlines in the text indicate mnemonics

195.        procedure LeaveTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec);

197.        procedure PressedTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec);

199.        procedure ReleasedTo API docTo body (Button : access Gtk_Button_RecordTo API docTo spec);

201.        ---------------------

202.        -- Interfaces_Impl --

203.        ---------------------

205.        procedure Do_Set_Related_ActionTo API docTo body

206.           (Self   : access Gtk_Button_RecordTo API docTo spec;

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

209.        function Get_Related_ActionTo API docTo body

210.           (Self : access Gtk_Button_RecordTo API docTo spec) return Gtk.Action.Gtk_ActionTo API docTo spec;

211.        procedure Set_Related_ActionTo API docTo body

212.           (Self   : access Gtk_Button_RecordTo API docTo spec;

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

215.        function Get_Use_Action_AppearanceTo API docTo body

216.           (Self : access Gtk_Button_RecordTo API docTo spec) return Boolean;

217.        procedure Set_Use_Action_AppearanceTo API docTo body

218.           (Self           : access Gtk_Button_RecordTo API docTo spec;

219.            Use_Appearance : Boolean);

221.        procedure Sync_Action_PropertiesTo API docTo body

222.           (Self   : access Gtk_Button_RecordTo API docTo spec;

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

225.        ----------------

226.        -- Interfaces --

227.        ----------------

228.        --  This class implements several interfaces. See Glib.Types

229.        --

230.        --  - "Activatable"

231.        --

232.        --  - "Buildable"

234.        package Implements_Activatable is new Glib.Types.ImplementsTo API docTo specTo body

235.          (Gtk.Activatable.Gtk_ActivatableTo API docTo spec, Gtk_Button_RecordTo API docTo spec, Gtk_ButtonTo API docTo spec);

236.        function "+"

237.          (Widget : access Gtk_Button_RecordTo API docTo spec'Class)

238.        return Gtk.Activatable.Gtk_ActivatableTo API docTo spec

239.        renames Implements_Activatable.To_InterfaceTo API docTo specTo body;

240.        function "-"

241.          (Interf : Gtk.Activatable.Gtk_ActivatableTo API docTo spec)

242.        return Gtk_ButtonTo API docTo spec

243.        renames Implements_Activatable.To_ObjectTo API docTo specTo body;

245.        package Implements_Buildable is new Glib.Types.ImplementsTo API docTo specTo body

246.          (Gtk.Buildable.Gtk_BuildableTo API docTo spec, Gtk_Button_RecordTo API docTo spec, Gtk_ButtonTo API docTo spec);

247.        function "+"

248.          (Widget : access Gtk_Button_RecordTo API docTo spec'Class)

249.        return Gtk.Buildable.Gtk_BuildableTo API docTo spec

250.        renames Implements_Buildable.To_InterfaceTo API docTo specTo body;

251.        function "-"

252.          (Interf : Gtk.Buildable.Gtk_BuildableTo API docTo spec)

253.        return Gtk_ButtonTo API docTo spec

254.        renames Implements_Buildable.To_ObjectTo API docTo specTo body;

256.        ----------------

257.        -- Properties --

258.        ----------------

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

260.        --  Glib.Properties for more information on properties)

261.        --

262.        --  Name: Focus_On_Click_Property

263.        --  Type: Boolean

264.        --  Flags: read-write

265.        --

266.        --  Name: Image_Property

267.        --  Type: Gtk.Widget.Gtk_Widget

268.        --  Flags: read-write

269.        --

270.        --  Name: Image_Position_Property

271.        --  Type: Gtk.Enums.Gtk_Position_Type

272.        --  Flags: read-write

273.        --  The position of the image relative to the text inside the button.

274.        --

275.        --  Name: Label_Property

276.        --  Type: UTF8_String

277.        --  Flags: read-write

278.        --

279.        --  Name: Relief_Property

280.        --  Type: Gtk.Enums.Gtk_Relief_Style

281.        --  Flags: read-write

282.        --

283.        --  Name: Use_Stock_Property

284.        --  Type: Boolean

285.        --  Flags: read-write

286.        --

287.        --  Name: Use_Underline_Property

288.        --  Type: Boolean

289.        --  Flags: read-write

290.        --

291.        --  Name: Xalign_Property

292.        --  Type: Gfloat

293.        --  Flags: read-write

294.        --  If the child of the button is a Gtk.Misc.Gtk_Misc or

295.        --  Gtk.Alignment.Gtk_Alignment, this property can be used to control it's

296.        --  horizontal alignment. 0.0 is left aligned, 1.0 is right aligned.

297.        --

298.        --  Name: Yalign_Property

299.        --  Type: Gfloat

300.        --  Flags: read-write

301.        --  If the child of the button is a Gtk.Misc.Gtk_Misc or

302.        --  Gtk.Alignment.Gtk_Alignment, this property can be used to control it's

303.        --  vertical alignment. 0.0 is top aligned, 1.0 is bottom aligned.

305.        Focus_On_Click_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

306.        Image_Property : constant Glib.Properties.Property_ObjectTo API docTo spec;

307.        Image_Position_Property : constant Gtk.Enums.Property_Gtk_Position_TypeTo API docTo spec;

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

309.        Relief_Property : constant Gtk.Enums.Property_Gtk_Relief_StyleTo API docTo spec;

310.        Use_Stock_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

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

312.        Xalign_Property : constant Glib.Properties.Property_FloatTo API docTo spec;

313.        Yalign_Property : constant Glib.Properties.Property_FloatTo API docTo spec;

315.        -------------

316.        -- Signals --

317.        -------------

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

319.        --

320.        --  "activate"

321.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

322.        --  The ::activate signal on GtkButton is an action signal and emitting it

323.        --  causes the button to animate press then release. Applications should

324.        --  never connect to this signal, but use the Gtk.Button.Gtk_Button::clicked

325.        --  signal.

326.        --

327.        --  "clicked"

328.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

329.        --  Emitted when the button has been activated (pressed and released).

330.        --

331.        --  "enter"

332.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

333.        --  Emitted when the pointer enters the button.

334.        --

335.        --  "leave"

336.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

337.        --  Emitted when the pointer leaves the button.

338.        --

339.        --  "pressed"

340.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

341.        --  Emitted when the button is pressed.

342.        --

343.        --  "released"

344.        --     procedure Handler (Self : access Gtk_Button_Record'Class);

345.        --  Emitted when the button is released.

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

348.        Signal_Clicked : constant Glib.Signal_NameTo API docTo spec := "clicked";

349.        Signal_Enter : constant Glib.Signal_NameTo API docTo spec := "enter";

350.        Signal_Leave : constant Glib.Signal_NameTo API docTo spec := "leave";

351.        Signal_Pressed : constant Glib.Signal_NameTo API docTo spec := "pressed";

352.        Signal_Released : constant Glib.Signal_NameTo API docTo spec := "released";

354.     private

355.        Focus_On_Click_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

356.          Glib.Properties.BuildTo API docTo specTo body ("focus-on-click");

357.        Image_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

358.          Glib.Properties.BuildTo API docTo specTo body ("image");

359.        Image_Position_PropertyTo API docTo spec : constant Gtk.Enums.Property_Gtk_Position_TypeTo API docTo spec :=

360.          Gtk.Enums.BuildTo API docTo specTo body ("image-position");

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

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

363.        Relief_PropertyTo API docTo spec : constant Gtk.Enums.Property_Gtk_Relief_StyleTo API docTo spec :=

364.          Gtk.Enums.BuildTo API docTo specTo body ("relief");

365.        Use_Stock_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

366.          Glib.Properties.BuildTo API docTo specTo body ("use-stock");

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

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

369.        Xalign_PropertyTo API docTo spec : constant Glib.Properties.Property_FloatTo API docTo spec :=

370.          Glib.Properties.BuildTo API docTo specTo body ("xalign");

371.        Yalign_PropertyTo API docTo spec : constant Glib.Properties.Property_FloatTo API docTo spec :=

372.          Glib.Properties.BuildTo API docTo specTo body ("yalign");

373.     end Gtk.ButtonTo API docTo specTo body;