File: gtk-dialog.ads

package info (click to toggle)
libgtkada2 2.8.1-6lenny3
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,496 kB
  • ctags: 3,886
  • sloc: ada: 103,189; ansic: 45,411; perl: 5,500; sh: 2,812; makefile: 1,169; xml: 19
file content (325 lines) | stat: -rw-r--r-- 13,984 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
-----------------------------------------------------------------------
--               GtkAda - Ada95 binding for Gtk+/Gnome               --
--                                                                   --
--   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   --
--                Copyright (C) 2000-2006 AdaCore                    --
--                                                                   --
-- This library is free software; you can redistribute it and/or     --
-- modify it under the terms of the GNU General Public               --
-- License as published by the Free Software Foundation; either      --
-- version 2 of the License, or (at your option) any later version.  --
--                                                                   --
-- This library is distributed in the hope that it will be useful,   --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --
-- General Public License for more details.                          --
--                                                                   --
-- You should have received a copy of the GNU General Public         --
-- License along with this library; if not, write to the             --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --
-- Boston, MA 02111-1307, USA.                                       --
--                                                                   --
-----------------------------------------------------------------------

--  <description>
--  Dialog boxes are a convenient way to prompt the user for a small amount of
--  input, eg. to display a message, ask a question, or anything else that does
--  not require extensive effort on the user's part.
--
--  Gtkada treats a dialog as a window split horizontally. The top section is a
--  Gtk_Vbox, and is where widgets such as a Gtk_Label or a Gtk_Entry should be
--  packed. The second area is known as the action_area. This is generally used
--  for packing buttons into the dialog which may perform functions such as
--  cancel, ok, or apply. The two areas are separated by a Gtk_Hseparator.
--
--  If 'dialog' is a newly created dialog, the two primary areas of the window
--  can be accessed using Get_Vbox and Get_Action_Area as can be seen from the
--  example, below.
--
--  A 'modal' dialog (that is, one which freezes the rest of the application
--  from user input), can be created by calling Set_Modal on the dialog.
--
--  See Gtkada.Dialogs for a higher level dialog interface.
--  </description>
--  <c_version>2.8.17</c_version>
--  <group>Windows</group>
--  <testgtk>create_dialog.adb</testgtk>
--  <screenshot>gtk-dialog</screenshot>

with Glib.Properties;
with Gtk.Box;
with Gtk.Widget;
with Gtk.Window;

package Gtk.Dialog is

   type Gtk_Dialog_Record is new Gtk.Window.Gtk_Window_Record with private;
   type Gtk_Dialog is access all Gtk_Dialog_Record'Class;

   -----------------------
   -- Enumeration types --
   -----------------------

   type Gtk_Dialog_Flags is mod 3;
   pragma Convention (C, Gtk_Dialog_Flags);
   Modal               : constant Gtk_Dialog_Flags := 0;
   Destroy_With_Parent : constant Gtk_Dialog_Flags := 1;
   No_Separator        : constant Gtk_Dialog_Flags := 2;
   --  Various flags that can be set for the dialog, with the following
   --  implications:
   --     - Modal : the dialog is modal, see Gtk.Window.Set_Modal
   --     - Destroy_With_Parent: The dialog is destroyed if its parent is
   --       destroyed. See Gtk.Window.Set_Destroy_With_Parent
   --     - No_Separator: No separator bar above the buttons.

   type Gtk_Response_Type is new Gint;
   --  Type used for Response_Id's.
   --  Positive values are totally user-interpreted.
   --  GtkAda will sometimes return Gtk_Response_None if no Response_Id is
   --  available.
   --
   --  Typical usage is:
   --    if Gtk.Dialog.Run (Dialog) = Gtk_Response_Accept then
   --       blah;
   --    end if;

   Gtk_Response_None : constant Gtk_Response_Type := -1;
   --  GtkAda returns this if a response widget has no Response_Id,
   --  or if the dialog gets programmatically hidden or destroyed.

   Gtk_Response_Reject : constant Gtk_Response_Type := -2;
   Gtk_Response_Accept : constant Gtk_Response_Type := -3;
   --  GtkAda won't return these unless you pass them in
   --  as the response for an action widget. They are
   --  for your convenience.

   Gtk_Response_Delete_Event : constant Gtk_Response_Type := -4;
   --  If the dialog is deleted through the button in the titlebar

   Gtk_Response_OK     : constant Gtk_Response_Type := -5;
   Gtk_Response_Cancel : constant Gtk_Response_Type := -6;
   Gtk_Response_Close  : constant Gtk_Response_Type := -7;
   Gtk_Response_Yes    : constant Gtk_Response_Type := -8;
   Gtk_Response_No     : constant Gtk_Response_Type := -9;
   Gtk_Response_Apply  : constant Gtk_Response_Type := -10;
   Gtk_Response_Help   : constant Gtk_Response_Type := -11;
   --  These are returned from dialogs, and you can also use them
   --  yourself if you like.

   type Response_Type_Array is array (Natural range <>) of Gtk_Response_Type;

   -----------------
   -- Subprograms --
   -----------------

   procedure Gtk_New (Dialog : out Gtk_Dialog);
   --  Create a new dialog.
   --  Widgets should not be packed into this widget directly, but into the
   --  vbox and action_area, as described above.

   procedure Gtk_New
     (Dialog : out Gtk_Dialog;
      Title  : UTF8_String;
      Parent : Gtk.Window.Gtk_Window;
      Flags  : Gtk_Dialog_Flags);
   --  Create a new dialog with a specific title, and specific attributes.
   --  Parent is the transient parent for the dialog (ie the one that is
   --  used for reference for the flag Destroy_With_Parent, or to compute the
   --  initial position of the dialog).

   procedure Initialize (Dialog : access Gtk_Dialog_Record'Class);
   --  Internal initialization function.
   --  See the section "Creating your own widgets" in the documentation.

   procedure Initialize
     (Dialog : access Gtk_Dialog_Record'Class;
      Title  : UTF8_String;
      Parent : Gtk.Window.Gtk_Window;
      Flags  : Gtk_Dialog_Flags);
   --  Internal initialization function.
   --  See the section "Creating your own widgets" in the documentation.

   function Get_Type return Gtk.Gtk_Type;
   --  Return the internal value associated with a Gtk_Dialog.

   function Get_Action_Area
     (Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box;
   --  Return the action area box associated with a Dialog.

   function Get_Vbox
     (Dialog : access Gtk_Dialog_Record) return Gtk.Box.Gtk_Box;
   --  Return the vertical box associated with a Dialog.

   procedure Add_Action_Widget
     (Dialog      : access Gtk_Dialog_Record;
      Child       : access Gtk.Widget.Gtk_Widget_Record'Class;
      Response_Id : Gtk_Response_Type);
   --  Add an activatable widget to the action area of Dialog.
   --  When the widget is activated (ie emits the "activate" signal), Dialog
   --  will emit the "response" signal with Response_Id.

   function Add_Button
     (Dialog      : access Gtk_Dialog_Record;
      Text        : UTF8_String;
      Response_Id : Gtk_Response_Type) return Gtk.Widget.Gtk_Widget;
   --  Add a button with the given text to the dialog. Note that you can also
   --  pass one of the constants defined in Gtk.Stock for the predefined
   --  buttons.
   --  When the button is clicked, Dialog will emit the "response" signal.
   --  The button widget is returned.

   function Get_Response_For_Widget
     (Dialog : access Gtk_Dialog_Record;
      Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gint;
   --  Gets the response id of a widget in the action area of a dialog, or
   --  Gtk_Response_None if Widget doesn't have a response Id set

   procedure Set_Alternative_Button_Order_From_Array
     (Dialog    : access Gtk_Dialog_Record;
      New_Order : Response_Type_Array);
   --  Sets an alternative button order. If the gtk-alternative-button-order
   --  setting is set to %TRUE, the dialog buttons are reordered according to
   --  the order of the response ids passed to this function.
   --
   --  By default, GTK+ dialogs use the button order advocated by the Gnome
   --  Human Interface Guidelines with the affirmative button at the far right,
   --  and the cancel button left of it. But the builtin GTK+ dialogs and
   --  message dialogs' do provide an alternative button order, which is more
   --  suitable on some platforms, e.g. Windows.
   --
   --  Use this function after adding all the buttons to your dialog.

   function Gtk_Alternative_Dialog_Button_Order
     (Screen : Gdk.Gdk_Screen := null)  return Boolean;
   --  Returns True if dialogs are expected to use an alternative button order
   --  on the given screen (or current screen if null) . See
   --  Set_Alternative_Button_Order_From_Array for more details about
   --  alternative button order.
   --
   --  If you need to use this function, you should probably connect to the
   --  ::notify:gtk-alternative-button-order signal on the Gtk_Settings object
   --  associated to Screen, in order to be notified if the button order
   --  setting changes.
   --
   --  Returns: Whether the alternative button order should be used

   procedure Set_Response_Sensitive
     (Dialog      : access Gtk_Dialog_Record;
      Response_Id : Gtk_Response_Type;
      Setting     : Boolean);
   --  Call Gtk.Widget.Set_Sensitive for all the buttons in the dialog
   --  associated with Response_Id.

   procedure Set_Default_Response
     (Dialog : access Gtk_Dialog_Record; Response_Id : Gtk_Response_Type);
   --  Set the last widget in the dialog's action area with the given
   --  Response_Id as the default widget for Dialog.
   --  Pressing Enter will activate this default widget.

   procedure Set_Has_Separator
     (Dialog : access Gtk_Dialog_Record; Setting : Boolean);
   function Get_Has_Separator (Dialog : access Gtk_Dialog_Record)
      return Boolean;
   --  Set whether the dialog has a separator above the buttons.

   function Run (Dialog : access Gtk_Dialog_Record) return Gtk_Response_Type;
   --  Block in a recursive main loop until Dialog emits the "response"
   --  signal, or is destroyed. If the dialog is destroyed, Gtk_Response_None
   --  is returned. Otherwise, the response_id from the "response" signal is
   --  returned.
   --  Run will call Show on the dialog automatically. However, it is your
   --  responsability to call Show for any child you have inserted in the
   --  dialog.
   --  The dialog is automatically set to modal when this function is
   --  called. You can exit at any time from this function by emitting the
   --  "response" signal directly.
   --  When Run returns, you are responsible for hiding or destroying the
   --  dialog if necessary.

   ----------------
   -- Properties --
   ----------------
   --  The following properties are defined for this widget. See
   --  Glib.Properties for more information on properties.

   --  <properties>
   --  - Name:  Has_Separator_Property
   --    Type:  Boolean
   --    Flags: read-write
   --    Descr: The dialog has a separator bar above its buttons
   --  </properties>

   Has_Separator_Property : constant Glib.Properties.Property_Boolean;

   ----------------------
   -- Style Properties --
   ----------------------
   --  The following properties can be changed through the gtk theme and
   --  configuration files, and retrieved through Gtk.Widget.Style_Get_Property

   --  <style_properties>
   --  Name:  Action_Area_Border_Property
   --  Type:  Int
   --  Descr: Width of border around the button area at the bottom of the
   --         dialog
   --
   --  Name:  Button_Spacing_Property
   --  Type:  Int
   --  Descr: Spacing between buttons
   --
   --  Name:  Content_Area_Border_Property
   --  Type:  Int
   --  Descr: Width of border around the main dialog area
   --  </style_properties>

   Action_Area_Border_Property  : constant Glib.Properties.Property_Int;
   Button_Spacing_Property      : constant Glib.Properties.Property_Int;
   Content_Area_Border_Property : constant Glib.Properties.Property_Int;

   -------------
   -- Signals --
   -------------

   --  <signals>
   --  The following new signals are defined for this widget:
   --
   --  - "response"
   --    procedure Handler
   --      (Dialog      : access Gtk_Dialog_Record'Class;
   --       Response_Id : Gint);
   --    Emitted when an action widget is clicked, the dialog receives a delete
   --    event, or the application programmer calls Response. On delete event,
   --    the response ID is GTK_RESPONSE_NONE. Otherwise, it depends on which
   --    action widget was clicked.
   --
   --  - "close"
   --    procedure Handler (Dialog : access Gtk_Dialog_Record'Class);
   --    Emit this signal to force a closing of the dialog.
   --  </signals>

   Signal_Close    : constant String := "close";
   Signal_Response : constant String := "response";

   procedure Response
     (Dialog      : access Gtk_Dialog_Record;
      Response_Id : Gtk_Response_Type);
   --  Emit the "response" signal

private
   type Gtk_Dialog_Record is new Gtk.Window.Gtk_Window_Record with null record;

   Has_Separator_Property : constant Glib.Properties.Property_Boolean :=
     Glib.Properties.Build ("has_separator");

   Action_Area_Border_Property : constant Glib.Properties.Property_Int :=
     Glib.Properties.Build ("action-area-border");
   Button_Spacing_Property : constant Glib.Properties.Property_Int :=
     Glib.Properties.Build ("button-spacing");
   Content_Area_Border_Property : constant Glib.Properties.Property_Int :=
     Glib.Properties.Build ("content-area-border");

   pragma Import (C, Get_Type, "gtk_dialog_get_type");
end Gtk.Dialog;

--  No binding: gtk_dialog_set_alternative_button_order
--  No binding: gtk_dialog_new_with_buttons