## 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.     --  Dialog boxes are a convenient way to prompt the user for a small amount of

32.     --  input, eg. to display a message, ask a question, or anything else that does

33.     --  not require extensive effort on the user's part.

34.     --

35.     --  Gtkada treats a dialog as a window split horizontally. The top section is

36.     --  a Gtk_Vbox, and is where widgets such as a Gtk_Label or a Gtk_Entry should

37.     --  be packed. The second area is known as the action_area. This is generally

38.     --  used for packing buttons into the dialog which may perform functions such

39.     --  as cancel, ok, or apply. The two areas are separated by a Gtk_Hseparator.

40.     --

41.     --  If 'dialog' is a newly created dialog, the two primary areas of the window

42.     --  can be accessed using Get_Vbox and Get_Action_Area as can be seen from the

43.     --  example, below.

44.     --

45.     --  A 'modal' dialog (that is, one which freezes the rest of the application

46.     --  from user input), can be created by calling Set_Modal on the dialog.

47.     --

48.     --  See Gtkada.Dialogs for a higher level dialog interface.

49.     --

50.     --  </description>

51.     --  <screenshot>gtk-dialog</screenshot>

52.     --  <group>Windows</group>

53.     --  <testgtk>create_dialog.adb</testgtk>

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

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

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

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

59.     with Gtk.BoxTo API docTo specTo body;         use Gtk.BoxTo API docTo specTo body;

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

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

62.     with Gtk.WindowTo API docTo specTo body;      use Gtk.WindowTo API docTo specTo body;

64.     package Gtk.DialogTo API docTo specTo body is

66.        type Gtk_Dialog_Record is new Gtk_Window_RecordTo API docTo specTo body with null record;

67.        type Gtk_Dialog is access all Gtk_Dialog_RecordTo API docTo spec'Class;

69.        type Gtk_Dialog_Flags is mod 8;

70.        for Gtk_Dialog_FlagsTo API docTo spec'Size use GintTo API docTo spec'Size;

71.        pragma Convention (C, Gtk_Dialog_FlagsTo API docTo spec);

72.        Modal               : constant Gtk_Dialog_FlagsTo API docTo spec := 2 ** 0;

73.        Destroy_With_Parent : constant Gtk_Dialog_FlagsTo API docTo spec := 2 ** 1;

74.        No_Separator        : constant Gtk_Dialog_FlagsTo API docTo spec := 2 ** 2;

75.        --  Various flags that can be set for the dialog, with the following

76.        --  implications:

77.        --     - Modal : the dialog is modal, see Gtk.Window.Set_Modal

78.        --     - Destroy_With_Parent: The dialog is destroyed if its parent is

79.        --       destroyed. See Gtk.Window.Set_Destroy_With_Parent

80.        --     - No_Separator: No separator bar above the buttons.

82.        type Gtk_Response_Type is new GintTo API docTo spec;

83.        --  Type used for Response_Id's.

84.        --  Positive values are totally user-interpreted.

85.        --  GtkAda will sometimes return Gtk_Response_None if no Response_Id is

86.        --  available.

87.        --

88.        --  Typical usage is:

89.        --    if Gtk.Dialog.Run (Dialog) = Gtk_Response_Accept then

90.        --       blah;

91.        --    end if;

93.        Gtk_Response_None : constant Gtk_Response_TypeTo API docTo spec := -1;

94.        --  GtkAda returns this if a response widget has no Response_Id,

95.        --  or if the dialog gets programmatically hidden or destroyed.

97.        Gtk_Response_Reject : constant Gtk_Response_TypeTo API docTo spec := -2;

98.        Gtk_Response_Accept : constant Gtk_Response_TypeTo API docTo spec := -3;

99.        --  GtkAda won't return these unless you pass them in

100.        --  as the response for an action widget. They are

101.        --  for your convenience.

103.        Gtk_Response_Delete_Event : constant Gtk_Response_TypeTo API docTo spec := -4;

104.        --  If the dialog is deleted through the button in the titlebar

106.        Gtk_Response_OK     : constant Gtk_Response_TypeTo API docTo spec := -5;

107.        Gtk_Response_Cancel : constant Gtk_Response_TypeTo API docTo spec := -6;

108.        Gtk_Response_Close  : constant Gtk_Response_TypeTo API docTo spec := -7;

109.        Gtk_Response_Yes    : constant Gtk_Response_TypeTo API docTo spec := -8;

110.        Gtk_Response_No     : constant Gtk_Response_TypeTo API docTo spec := -9;

111.        Gtk_Response_Apply  : constant Gtk_Response_TypeTo API docTo spec := -10;

112.        Gtk_Response_Help   : constant Gtk_Response_TypeTo API docTo spec := -11;

113.        --  These are returned from dialogs, and you can also use them

114.        --  yourself if you like.

116.        type Response_Type_Array is array (Natural range <>) of Gtk_Response_TypeTo API docTo spec;

118.        ------------------

119.        -- Constructors --

120.        ------------------

122.        procedure Gtk_NewTo API docTo body (Dialog : out Gtk_DialogTo API docTo spec);

123.        procedure InitializeTo API docTo body (Dialog : access Gtk_Dialog_RecordTo API docTo spec'Class);

125.        procedure Gtk_NewTo API docTo body

126.           (Dialog : out Gtk_DialogTo API docTo spec;

127.            Title  : UTF8_StringTo API docTo spec;

128.            Parent : Gtk.Window.Gtk_WindowTo API docTo spec := null;

129.            Flags  : Gtk_Dialog_FlagsTo API docTo spec);

130.        procedure InitializeTo API docTo body

131.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec'Class;

132.            Title  : UTF8_StringTo API docTo spec;

133.            Parent : Gtk.Window.Gtk_WindowTo API docTo spec := null;

134.            Flags  : Gtk_Dialog_FlagsTo API docTo spec);

135.        --  Create a new dialog with a specific title, and specific attributes.

136.        --  Parent is the transient parent for the dialog (ie the one that is used

137.        --  for reference for the flag Destroy_With_Parent, or to compute the

138.        --  initial position of the dialog).

139.        --  Since: gtk+ GtkAda 1.0

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

142.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_dialog_get_type");

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

145.        -- Methods --

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

148.        procedure Add_Action_WidgetTo API docTo body

149.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

150.            Child       : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

151.            Response_Id : Gtk_Response_TypeTo API docTo spec);

152.        --  Adds an activatable widget to the action area of a

153.        --  Gtk.Dialog.Gtk_Dialog, connecting a signal handler that will emit the

154.        --  Gtk.Dialog.Gtk_Dialog::response signal on the dialog when the widget is

155.        --  activated. The widget is appended to the end of the dialog's action

156.        --  area. If you want to add a non-activatable widget, simply pack it into

157.        --  the Action_Area field of the Gtk.Dialog.Gtk_Dialog struct.

158.        --  "child": an activatable widget

159.        --  "response_id": response ID for Child

161.        function Add_ButtonTo API docTo body

162.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

163.            Text        : UTF8_StringTo API docTo spec;

164.            Response_Id : Gtk_Response_TypeTo API docTo spec) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

165.        --  Adds a button with the given text (or a stock button, if Button_Text is

166.        --  a stock ID) and sets things up so that clicking the button will emit the

167.        --  Gtk.Dialog.Gtk_Dialog::response signal with the given Response_Id. The

168.        --  button is appended to the end of the dialog's action area. The button

169.        --  widget is returned, but usually you don't need it.

170.        --  "text": text of button, or stock ID

171.        --  "response_id": response ID for the button

173.        function Get_Action_AreaTo API docTo body

174.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec) return Gtk.Box.Gtk_BoxTo API docTo spec;

175.        --  Returns the action area of Dialog.

176.        --  Since: gtk+ 2.14

178.        function Get_Content_AreaTo API docTo body

179.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec) return Gtk.Box.Gtk_BoxTo API docTo spec;

180.        --  Returns the content area of Dialog.

181.        --  Since: gtk+ 2.14

183.        function Get_Has_SeparatorTo API docTo body

184.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec) return Boolean;

185.        pragma Obsolescent (Get_Has_SeparatorTo API docTo specTo body);

186.        procedure Set_Has_SeparatorTo API docTo body

187.           (Dialog  : access Gtk_Dialog_RecordTo API docTo spec;

188.            Setting : Boolean);

189.        pragma Obsolescent (Set_Has_SeparatorTo API docTo specTo body);

190.        --  Sets whether the dialog has a separator above the buttons.

191.        --  Deprecated since 2.22, This function will be removed in GTK+ 3

192.        --  "setting": True to have a separator

194.        function Get_Response_For_WidgetTo API docTo body

195.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec;

196.            Widget : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class)

197.            return Gtk_Response_TypeTo API docTo spec;

198.        --  Gets the response id of a widget in the action area of a dialog. if

199.        --  Widget doesn't have a response id set.

200.        --  Since: gtk+ 2.8

201.        --  "widget": a widget in the action area of Dialog

203.        function Get_Widget_For_ResponseTo API docTo body

204.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

205.            Response_Id : Gtk_Response_TypeTo API docTo spec) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

206.        --  Gets the widget button that uses the given response ID in the action

207.        --  area of a dialog.

208.        --  Since: gtk+ 2.20

209.        --  "response_id": the response ID used by the Dialog widget

211.        procedure ResponseTo API docTo body

212.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

213.            Response_Id : Gtk_Response_TypeTo API docTo spec);

214.        --  Emits the Gtk.Dialog.Gtk_Dialog::response signal with the given

215.        --  response ID. Used to indicate that the user has responded to the dialog

216.        --  in some way; typically either you or Gtk.Dialog.Run will be monitoring

217.        --  the ::response signal and take appropriate action.

218.        --  "response_id": response ID

220.        function RunTo API docTo body (Dialog : access Gtk_Dialog_RecordTo API docTo spec) return Gtk_Response_TypeTo API docTo spec;

221.        --  Blocks in a recursive main loop until the Dialog either emits the

222.        --  Gtk.Dialog.Gtk_Dialog::response signal, or is destroyed. If the dialog

223.        --  is destroyed during the call to Gtk.Dialog.Run, Gtk.Dialog.Run returns

224.        --  GTK_RESPONSE_NONE. Otherwise, it returns the response ID from the

225.        --  ::response signal emission. Before entering the recursive main loop,

226.        --  Gtk.Dialog.Run calls Gtk.Widget.Show on the dialog for you. Note that

227.        --  you still need to show any children of the dialog yourself. During

228.        --  Gtk.Dialog.Run, the default behavior of

229.        --  Gtk.Widget.Gtk_Widget::delete-event is disabled; if the dialog receives

230.        --  ::delete_event, it will not be destroyed as windows usually are, and

231.        --  Gtk.Dialog.Run will return GTK_RESPONSE_DELETE_EVENT. Also, during

232.        --  Gtk.Dialog.Run the dialog will be modal. You can force Gtk.Dialog.Run to

233.        --  return at any time by calling Gtk.Dialog.Response to emit the ::response

234.        --  signal. Destroying the dialog during Gtk.Dialog.Run is a very bad idea,

235.        --  because your post-run code won't know whether the dialog was destroyed

236.        --  or not. After Gtk.Dialog.Run returns, you are responsible for hiding or

237.        --  destroying the dialog if you wish to do so. Typical usage of this

238.        --  function might be: |[ gint result = gtk_dialog_run (GTK_DIALOG

239.        --  (dialog)); switch (result) { case GTK_RESPONSE_ACCEPT:

240.        --  do_application_specific_something (); break; default:

241.        --  do_nothing_since_dialog_was_cancelled (); break; } gtk_widget_destroy

242.        --  (dialog); ]| Note that even though the recursive main loop gives the

243.        --  effect of a modal dialog (it prevents the user from interacting with

244.        --  other windows in the same window group while the dialog is run),

245.        --  callbacks such as timeouts, IO channel watches, DND drops, etc,

246.        --  <emphasis>will</emphasis> be triggered during a Gtk.Dialog.Run call.

248.        procedure Set_Default_ResponseTo API docTo body

249.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

250.            Response_Id : Gtk_Response_TypeTo API docTo spec);

251.        --  Sets the last widget in the dialog's action area with the given

252.        --  Response_Id as the default widget for the dialog. Pressing "Enter"

253.        --  normally activates the default widget.

254.        --  "response_id": a response ID

256.        procedure Set_Response_SensitiveTo API docTo body

257.           (Dialog      : access Gtk_Dialog_RecordTo API docTo spec;

258.            Response_Id : Gtk_Response_TypeTo API docTo spec;

259.            Setting     : Boolean);

260.        --  Calls <literal>gtk_widget_set_sensitive (widget, Setting)</literal> for

261.        --  each widget in the dialog's action area with the given Response_Id. A

262.        --  convenient way to sensitize/desensitize dialog buttons.

263.        --  "response_id": a response ID

264.        --  "setting": True for sensitive

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

267.        -- GtkAda additions --

268.        ----------------------

270.        procedure Set_Alternative_Button_Order_From_ArrayTo API docTo body

271.          (Dialog    : access Gtk_Dialog_RecordTo API docTo spec;

272.           New_Order : Response_Type_ArrayTo API docTo spec);

273.        --  Sets an alternative button order. If the gtk-alternative-button-order

274.        --  setting is set to %TRUE, the dialog buttons are reordered according to

275.        --  the order of the response ids passed to this function.

276.        --

277.        --  By default, GTK+ dialogs use the button order advocated by the Gnome

278.        --  Human Interface Guidelines with the affirmative button at the far right,

279.        --  and the cancel button left of it. But the builtin GTK+ dialogs and

280.        --  message dialogs' do provide an alternative button order, which is more

281.        --  suitable on some platforms, e.g. Windows.

282.        --

283.        --  Use this function after adding all the buttons to your dialog.

285.        function Gtk_Alternative_Dialog_Button_OrderTo API docTo body

286.          (Screen : Gdk.Gdk_ScreenTo API docTo spec := null)  return Boolean;

287.        --  Returns True if dialogs are expected to use an alternative button order

288.        --  on the given screen (or current screen if null) . See

289.        --  Set_Alternative_Button_Order_From_Array for more details about

290.        --  alternative button order.

291.        --

292.        --  If you need to use this function, you should probably connect to the

293.        --  ::notify:gtk-alternative-button-order signal on the Gtk_Settings object

294.        --  associated to Screen, in order to be notified if the button order

295.        --  setting changes.

296.        --

297.        --  Returns: Whether the alternative button order should be used

299.        ------------

300.        -- Fields --

301.        ------------

303.        function Get_VboxTo API docTo body

304.           (Dialog : access Gtk_Dialog_RecordTo API docTo spec) return Gtk.Box.Gtk_BoxTo API docTo spec;

306.        ----------------

307.        -- Interfaces --

308.        ----------------

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

310.        --

311.        --  - "Buildable"

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

314.          (Gtk.Buildable.Gtk_BuildableTo API docTo spec, Gtk_Dialog_RecordTo API docTo spec, Gtk_DialogTo API docTo spec);

315.        function "+"

316.          (Widget : access Gtk_Dialog_RecordTo API docTo spec'Class)

317.        return Gtk.Buildable.Gtk_BuildableTo API docTo spec

318.        renames Implements_Buildable.To_InterfaceTo API docTo specTo body;

319.        function "-"

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

321.        return Gtk_DialogTo API docTo spec

322.        renames Implements_Buildable.To_ObjectTo API docTo specTo body;

324.        ----------------

325.        -- Properties --

326.        ----------------

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

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

329.        --

330.        --  Name: Has_Separator_Property

331.        --  Type: Boolean

332.        --  Flags: read-write

333.        --  When True, the dialog has a separator bar above its buttons.

335.        Has_Separator_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

337.        -------------

338.        -- Signals --

339.        -------------

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

341.        --

342.        --  "close"

343.        --     procedure Handler (Self : access Gtk_Dialog_Record'Class);

344.        --  The ::close signal is a <link linkend="keybinding-signals">keybinding

345.        --  signal</link> which gets emitted when the user uses a keybinding to

346.        --  close the dialog. The default binding for this signal is the Escape key.

347.        --

348.        --  "response"

349.        --     procedure Handler

350.        --       (Self        : access Gtk_Dialog_Record'Class;

351.        --        Response_Id : Gtk_Response_Type);

352.        --    --  "response_id": the response ID

353.        --  Emitted when an action widget is clicked, the dialog receives a delete

354.        --  event, or the application programmer calls Gtk.Dialog.Response. On a

355.        --  delete event, the response ID is GTK_RESPONSE_DELETE_EVENT. Otherwise,

356.        --  it depends on which action widget was clicked.

358.        Signal_Close : constant Glib.Signal_NameTo API docTo spec := "close";

359.        Signal_Response : constant Glib.Signal_NameTo API docTo spec := "response";

361.     private

362.        Has_Separator_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

363.          Glib.Properties.BuildTo API docTo specTo body ("has-separator");

364.     end Gtk.DialogTo API docTo specTo body;