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-2007 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-----------------------------------------------------------------------
29
30--  <description>
31--  A Gtk_Spin_Button is a single line text editing widget for text that
32--  represents a number. At the right hand side of the text line there are
33--  small up- and down arrow buttons for incrementing or decrementing
34--  (spinning) the number within a given range.
35--  It allows the value to have zero or a number of decimal places and
36--  to be incremented/decremented in configurable steps.
37--  The action of holding down one of the buttons optionally results in an
38--  acceleration of change in the value according to how long it is
39--  depressed.
40--
41--  See Gtk.GEntry for a text editing widget without spin buttons.
42--  </description>
43--  <c_version>2.8.17</c_version>
44--  <group>Numeric/Text Data Entry</group>
45--  <screenshot>gtk-spin_button</screenshot>
46--  <testgtk>create_spin.adb</testgtk>
47
48with Glib.Generic_Properties;
49with Glib.Properties;
50with Gtk.Adjustment;
51with Gtk.GEntry;
52
53package Gtk.Spin_Button is
54
55   type Gtk_Spin_Button_Record is new Gtk.GEntry.Gtk_Entry_Record with private;
56   type Gtk_Spin_Button is access all Gtk_Spin_Button_Record'Class;
57
58   type Gtk_Spin_Button_Update_Policy is
59     (Update_Always,
60      --  Update always, errors are ignored while converting text into a
61      --  numeric value.
62
63      Update_If_Valid
64      --  The spin button's value gets changed if the text input is a numeric
65      --  value that is within the range specified by the adjustment.
66     );
67   --  Determine the update policy of the spin button which affects the
68   --  behaviour when parsing inserted text and syncing its value with the
69   --  values of the adjustment.
70   pragma Convention (C, Gtk_Spin_Button_Update_Policy);
71
72   type Gtk_Spin_Type is
73     (Spin_Step_Forward,
74      Spin_Step_Backward,
75      Spin_Page_Forward,
76      Spin_Page_Backward,
77      Spin_Home,
78      Spin_End,
79      Spin_User_Defined);
80   --  Determine how manual spinning should be done.
81   --  See also the Spin procedure.
82   pragma Convention (C, Gtk_Spin_Type);
83
84   procedure Gtk_New
85     (Spin_Button : out Gtk_Spin_Button;
86      Adjustment  : Gtk.Adjustment.Gtk_Adjustment;
87      Climb_Rate  : Gdouble;
88      The_Digits  : Gint);
89   --  Create a spin button with the given parameters.
90   --  Adjustment contains the range, current value, step value and
91   --  "page" value. The step value is the increment/decrement when pressing
92   --  mouse button 1 on a button; the page value when mouse button 2 is
93   --  pressed. Additionally, mouse button 3 can be used to jump directly to
94   --  the or lower values when used to select one of the buttons.
95   --  Climb_Rate takes a value between 0.0 and 1.0 and indicates the
96   --  amount of acceleration that the Spin Button has.
97   --  The_Digits is the number of digits behind the decimal point to be
98   --  displayed for the value.
99
100   procedure Gtk_New
101     (Spin_Button : out Gtk_Spin_Button;
102      Min         : Gdouble;
103      Max         : Gdouble;
104      Step        : Gdouble);
105   --  Same as above, but with explicit range instead of an adjustment.
106   --  The adjustment associated with Spin_Button is created internally.
107
108   procedure Initialize
109     (Spin_Button : access Gtk_Spin_Button_Record'Class;
110      Adjustment  : Gtk.Adjustment.Gtk_Adjustment;
111      Climb_Rate  : Gdouble;
112      The_Digits  : Gint);
113   --  Internal initialization function.
114   --  See the section "Creating your own widgets" in the documentation.
115
116   procedure Initialize
117     (Spin_Button : access Gtk_Spin_Button_Record'Class;
118      Min         : Gdouble;
119      Max         : Gdouble;
120      Step        : Gdouble);
121   --  Internal initialization function.
122
123   function Get_Type return Gtk.Gtk_Type;
124   --  Return the internal value associated with a Gtk_Spin_Button.
125
126   procedure Set_Adjustment
127     (Spin_Button : access Gtk_Spin_Button_Record;
128      Adjustment  : Gtk.Adjustment.Gtk_Adjustment);
129   function Get_Adjustment
130     (Spin_Button : access Gtk_Spin_Button_Record)
131      return Gtk.Adjustment.Gtk_Adjustment;
132   --  Set or Get the adjustment settings of the spin button.
133
134   procedure Set_Digits
135     (Spin_Button : access Gtk_Spin_Button_Record;
136      The_Digits  : Guint);
137   function Get_Digits
138     (Spin_Button : access Gtk_Spin_Button_Record) return Guint;
139   --  Set or Get number of decimals of the spin button.
140
141   procedure Set_Increments
142     (Spin_Button : access Gtk_Spin_Button_Record;
143      Step        : Gdouble;
144      Page        : Gdouble);
145   procedure Get_Increments
146     (Spin_Button : access Gtk_Spin_Button_Record;
147      Step        : out Gdouble;
148      Page        : out Gdouble);
149   --  Set or Get the increments for a single step and a page move.
150
151   procedure Set_Range
152     (Spin_Button : access Gtk_Spin_Button_Record;
153      Min         : Gdouble;
154      Max         : Gdouble);
155   procedure Get_Range
156     (Spin_Button : access Gtk_Spin_Button_Record;
157      Min         : out Gdouble;
158      Max         : out Gdouble);
159   --  Set or Get range of the spin button.
160
161   procedure Set_Value
162     (Spin_Button : access Gtk_Spin_Button_Record;
163      Value       : Gdouble);
164   function Get_Value
165     (Spin_Button : access Gtk_Spin_Button_Record) return Gdouble;
166   --  Set or Get the current value of the spin button in a double.
167
168   function Get_Value_As_Int
169     (Spin_Button : access Gtk_Spin_Button_Record) return Gint;
170   --  Return the current value of the spin button in an integer.
171
172   procedure Set_Update_Policy
173     (Spin_Button : access Gtk_Spin_Button_Record;
174      Policy      : Gtk_Spin_Button_Update_Policy);
175   function Get_Update_Policy
176     (Spin_Button : access Gtk_Spin_Button_Record)
177      return Gtk_Spin_Button_Update_Policy;
178   --  Set the update policy of the spin button.
179   --  See Gtk_Spin_Button_Update_Policy for the meaning of Policy.
180
181   procedure Set_Numeric
182     (Spin_Button : access Gtk_Spin_Button_Record;
183      Numeric     : Boolean);
184   function Get_Numeric
185     (Spin_Button : access Gtk_Spin_Button_Record) return Boolean;
186   --  If Numeric is True, then only a numeric value can be typed in the
187   --  text entry, otherwise also nonnumeric text.
188
189   procedure Spin
190     (Spin_Button : access Gtk_Spin_Button_Record;
191      Direction   : Gtk_Spin_Type;
192      Step        : Gdouble);
193   --  Set the value of the spin button relative to its current value.
194   --  Depending on Direction, it will be incremented or decremented with
195   --  the step value.
196
197   procedure Set_Wrap
198     (Spin_Button : access Gtk_Spin_Button_Record; Wrap : Boolean);
199   function Get_Wrap
200     (Spin_Button : access Gtk_Spin_Button_Record) return Boolean;
201   --  Set whether the spin button should "wrap around" when exceeding the
202   --  upper and lower limits.
203
204   procedure Set_Snap_To_Ticks
205    (Spin_Button   : access Gtk_Spin_Button_Record;
206     Snap_To_Ticks : Boolean);
207   function Get_Snap_To_Ticks
208    (Spin_Button : access Gtk_Spin_Button_Record) return Boolean;
209   --  Set the spin button to round the value to the nearest step value
210   --  which is set within its adjustment settings.
211
212   procedure Update (Spin_Button : access Gtk_Spin_Button_Record);
213   --  Manually force an update of the spin button.
214
215   ----------------
216   -- Properties --
217   ----------------
218
219   --  <properties>
220   --  The following properties are defined for this widget. See
221   --  Glib.Properties for more information on properties.
222   --
223   --  Name:  Adjustment_Property
224   --  Type:  Object
225   --  Descr: The adjustment that holds the value of the spinbutton
226   --
227   --  Name:  Climb_Rate_Property
228   --  Type:  Double
229   --  Descr: The acceleration rate when you hold down a button
230   --
231   --  Name:  Digits_Property
232   --  Type:  Uint
233   --  Descr: The number of decimal places to display
234   --
235   --  Name:  Numeric_Property
236   --  Type:  Boolean
237   --  Descr: Whether non-numeric characters should be ignored
238   --
239   --  Name:  Snap_To_Ticks_Property
240   --  Type:  Boolean
241   --  Descr: Whether erroneous values are automatically changed to a spin
242   --         button's nearest step increment
243   --
244   --  Name:  Update_Policy_Property
245   --  Type:  Enum
246   --  Descr: Whether the spin button should update always, or only when the
247   --         value is legal
248   --
249   --  Name:  Value_Property
250   --  Type:  Double
251   --  Descr: Reads the current value, or sets a new value
252   --
253   --  Name:  Wrap_Property
254   --  Type:  Boolean
255   --  Descr: Whether a spin button should wrap upon reaching its limits
256   --
257   --  </properties>
258
259   package Spin_Button_Update_Policy_Properties is new
260     Glib.Generic_Properties.Generic_Internal_Discrete_Property
261       (Gtk_Spin_Button_Update_Policy);
262   type Property_Spin_Button_Update_Policy_Type is new
263     Spin_Button_Update_Policy_Properties.Property;
264
265   Adjustment_Property    : constant Glib.Properties.Property_Object;
266   Climb_Rate_Property    : constant Glib.Properties.Property_Double;
267   Digits_Property        : constant Glib.Properties.Property_Uint;
268   Numeric_Property       : constant Glib.Properties.Property_Boolean;
269   Snap_To_Ticks_Property : constant Glib.Properties.Property_Boolean;
270   Update_Policy_Property : constant Property_Spin_Button_Update_Policy_Type;
271   Value_Property         : constant Glib.Properties.Property_Double;
272   Wrap_Property          : constant Glib.Properties.Property_Boolean;
273
274   -------------
275   -- Signals --
276   -------------
277
278   --  <signals>
279   --  The following new signals are defined for this widget:
280   --
281   --  - "change_value"
282   --    procedure Handler
283   --      (Spin : access Gtk_Spin_Button_Record'Class;
284   --       Typ  : Gtk_Scroll_Type);
285   --    You should emit this signal to request a change in the value of the
286   --    spin button. This is mostly useful as a keybinding, and is bound, by
287   --    default, to the arrow keys, PageUp, PageDown, Home and End keys.
288   --
289   --  - "input"
290   --    procedure Handler
291   --       (Spin  : access Gtk_Spin_Button_Record'Class;
292   --        Value : out Gint);
293   --    ???
294   --
295   --  - "output"
296   --    procedure Handler (Spin : access Gtk_Spin_Button_Record'Class);
297   --    ???
298   --
299   --  - "value_changed"
300   --    procedure Handler (Spin : access Gtk_Spin_Button_Record'Class);
301   --    Emitted when the value of the spin button has changed.
302   --
303   --  </signals>
304
305   Signal_Change_Value  : constant Glib.Signal_Name := "change_value";
306   Signal_Input         : constant Glib.Signal_Name := "input";
307   Signal_Output        : constant Glib.Signal_Name := "output";
308   Signal_Value_Changed : constant Glib.Signal_Name := "value_changed";
309
310private
311   type Gtk_Spin_Button_Record is new Gtk.GEntry.Gtk_Entry_Record
312   with null record;
313
314   Adjustment_Property : constant Glib.Properties.Property_Object :=
315     Glib.Properties.Build ("adjustment");
316   Climb_Rate_Property : constant Glib.Properties.Property_Double :=
317     Glib.Properties.Build ("climb-rate");
318   Digits_Property : constant Glib.Properties.Property_Uint :=
319     Glib.Properties.Build ("digits");
320   Numeric_Property : constant Glib.Properties.Property_Boolean :=
321     Glib.Properties.Build ("numeric");
322   Snap_To_Ticks_Property : constant Glib.Properties.Property_Boolean :=
323     Glib.Properties.Build ("snap-to-ticks");
324   Update_Policy_Property : constant Property_Spin_Button_Update_Policy_Type :=
325     Build ("update-policy");
326   Value_Property : constant Glib.Properties.Property_Double :=
327     Glib.Properties.Build ("value");
328   Wrap_Property : constant Glib.Properties.Property_Boolean :=
329     Glib.Properties.Build ("wrap");
330
331   pragma Import (C, Get_Type, "gtk_spin_button_get_type");
332end Gtk.Spin_Button;
333
334--  The following function is for the sake of the C++ binding only:
335--  No binding: gtk_spin_button_configure
336