/src/wrappers/gtk/library/gtk_spin_button.e

  1indexing
  2	description: "GtkSpinButton Retrieve an integer or floating-point number from the user."
  3	copyright: "[
  4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20					]"
 21
 22class GTK_SPIN_BUTTON
 23	-- A GtkSpinButton is an ideal way to allow the user to set the value of some
 24	-- attribute. Rather than having to directly type a number into a GtkEntry,
 25	-- GtkSpinButton allows the user to click on one of two arrows to increment
 26	-- or decrement the displayed value. A value can still be typed in, with the
 27	-- bonus that it can be checked to ensure it is in a given range.
 28
 29	-- The main properties of a GtkSpinButton are through a GtkAdjustment. See
 30	-- the GtkAdjustment section for more details about an adjustment's
 31	-- properties.
 32
 33	-- TODO: Example 1. Using a GtkSpinButton to get an integer.
 34	
 35	-- /* Provides a function to retrieve an integer value from a GtkSpinButton
 36	--  * and creates a spin button to model percentage values.
 37	--  */
 38
 39	-- gint grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
 40	--    return gtk_spin_button_get_value_as_int (a_spinner);
 41	-- }
 42
 43	-- void create_integer_spin_button (void) {
 44
 45	--    GtkWidget *window, *spinner;
 46	--    GtkAdjustment *spinner_adj;
 47	
 48	--    spinner_adj = (GtkAdjustment *) gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 5.0);
 49	
 50	--    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 51	--    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
 52	
 53	--    /* creates the spinner, with no decimal places */
 54	--    spinner = gtk_spin_button_new (spinner_adj, 1.0, 0);
 55	--    gtk_container_add (GTK_CONTAINER (window), spinner);
 56	
 57	--    gtk_widget_show_all (window);
 58	--    return;
 59	-- }
 60
 61	-- TODO: Example 2. Using a GtkSpinButton to get a floating point value.
 62
 63	-- /* Provides a function to retrieve a floating point value from a
 64	--  * GtkSpinButton, and creates a high precision spin button.
 65--  */
 66	
 67	-- gfloat grab_int_value (GtkSpinButton *a_spinner, gpointer user_data) {
 68	--    return gtk_spin_button_get_value (a_spinner);
 69	-- }
 70	
 71	-- void create_floating_spin_button (void) {
 72	
 73	--    GtkWidget *window, *spinner;
 74	--    GtkAdjustment *spinner_adj;
 75
 76	--    spinner_adj = (GtkAdjustment *) gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.1);
 77	
 78	--    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 79	--    gtk_container_set_border_width (GTK_CONTAINER (window), 5);
 80	
 81	--    /* creates the spinner, with three decimal places */
 82	--    spinner = gtk_spin_button_new (spinner_adj, 0.001, 3);
 83	--    gtk_container_add (GTK_CONTAINER (window), spinner);
 84	
 85	--    gtk_widget_show_all (window);
 86	--    return;
 87	-- }
 88
 89inherit
 90	GTK_ENTRY rename make as as_entry end
 91		-- GtkSpinButton implements AtkImplementorIface, GtkCellEditable and
 92		-- GtkEditable.
 93insert GTK_SPIN_BUTTON_EXTERNALS
 94	
 95creation make, from_external_pointer
 96
 97feature {} -- Creation
 98	make (an_adjustment: GTK_ADJUSTMENT; a_climb_rate: REAL; some_digits: INTEGER) is
 99			-- Creates a new GtkSpinButton. `an_adjustment' is the GtkAdjustment
100			-- object that this spin button should use. `a_climb_rate' specifies
101			-- how much the spin button changes when an arrow is clicked on.
102			-- `some_digits' are the number of decimal places to display.
103		require
104			gtk_initialized: gtk.is_initialized
105			valid_adjustment: an_adjustment /= Void
106			positive_digits: some_digits >= 0 
107		do
108			handle:=gtk_spin_button_new (an_adjustment.handle,
109												  a_climb_rate, some_digits)
110			store_eiffel_wrapper
111		end
112
113	with_range (a_min,a_max,a_step: REAL) is
114			-- A convenience creation feature that allows creation of a numeric
115			-- GtkSpinButton without manually creating an adjustment. The value is
116			-- initially set to the minimum value and a page increment of 10 * step
117			-- is the default. The precision of the spin button is equivalent to
118			-- the precision of step.
119
120			-- Note that the way in which the precision is derived works best if
121			-- step is a power of ten. If the resulting precision is not suitable
122			-- for your needs, use `set_digits' to correct it.
123
124			-- `a_min' : Minimum allowable value
125
126			-- `a_max' : Maximum allowable value
127		
128			-- `a_step' : Increment added or subtracted by spinning the widget
129		require gtk_initialized: gtk.is_initialized
130		do
131			handle:=gtk_spin_button_new_with_range  (a_min, a_max, a_step)
132			store_eiffel_wrapper
133		end
134
135feature -- Configuration
136	configure  (an_adjustment: GTK_ADJUSTMENT; a_climb_rate: REAL; some_digits: INTEGER) is
137			-- Changes the properties of an existing spin button. `an_adjustment'
138			-- is the GtkAdjustment object that this spin button should
139			-- use. `a_climb_rate' specifies how much the spin button changes when
140			-- an arrow is clicked on.  `some_digits' are the number of decimal
141			-- places to display.
142		require
143			valid_adjustment: an_adjustment /= Void
144			positive_digits: some_digits >= 0 
145		do
146			gtk_spin_button_configure (handle, an_adjustment.handle,
147												a_climb_rate, some_digits)
148		ensure -- TODO
149		end
150
151	set_adjustment (an_adjustment: GTK_ADJUSTMENT) is
152			-- Replaces the GtkAdjustment associated with spin_button to `an_adjustment'.
153		require valid_adjustment: an_adjustment /= Void
154		do
155			gtk_spin_button_set_adjustment (handle, an_adjustment.handle)
156		end
157
158
159	adjustment: GTK_ADJUSTMENT is
160			-- the adjustment associated with a GtkSpinButton
161		do
162			create Result.from_external_pointer (gtk_spin_button_get_adjustment (handle))
163		ensure Result/=Void
164		end
165
166	set_digits (some_digits: INTEGER) is
167			-- Set the precision to be displayed by spin_button. Up to 20 digit precision is allowed.
168			-- TODO: some_digits shall be NATURAL
169		require
170			positive_digits: some_digits >= 0
171			valid_digits: some_digits <=  20
172		do
173			gtk_spin_button_set_digits (handle, some_digits)
174		end
175
176	set_increments (a_step, a_page: REAL) is
177			-- Sets the step and page increments for spin_button. This affects how
178			-- quickly the value changes when the spin button's arrows are
179			-- activated. `a_step' is the increment applied for a button 1
180			-- press. `a_page' is the increment applied for a button 2 press.
181		do
182			gtk_spin_button_set_increments  (handle, a_step, a_page)
183		end
184
185	set_range (a_min, a_max: REAL) is
186			-- Sets the minimum (`a_min') and maximum (`a_max') allowable values for 
187			-- spin_button
188		require valid_value: a_min < a_max
189		do
190			gtk_spin_button_set_range (handle, a_min, a_max)
191		end
192
193	to_integer: INTEGER is
194			-- the value of the spin_button represented as an integer.
195		do
196			Result :=  gtk_spin_button_get_value_as_int (handle)
197		end
198
199	set_value (a_value: REAL) is
200			-- Set the value of spin_button.
201		do
202			gtk_spin_button_set_value (handle, a_value)
203		end
204	
205feature -- update policy
206	
207	set_always_update_policy is
208			-- Sets the update behavior of a spin button: when refreshing your
209			-- GtkSpinButton, the value is always displayed.
210		do
211			gtk_spin_button_set_update_policy (handle, gtk_update_always)
212		end
213	
214	set_if_valid_update_policy is
215			-- When refreshing your GtkSpinButton, the value is only displayed if
216			-- it is valid within the bounds of the spin button's GtkAdjustment.
217		do
218			gtk_spin_button_set_update_policy (handle, gtk_update_if_valid)
219		end
220
221	is_policy_always_update: BOOLEAN is
222			-- Is the value always displayed when refreshing the GtkSpinButton?
223		do
224			Result:=(gtk_spin_button_get_update_policy (handle)=gtk_update_always)
225		end
226	
227	is_policy_valid_update: BOOLEAN is
228			-- Is the value displayed only if it is valid within the bounds of the
229			-- spin button's GtkAdjustment? 
230		do
231			Result:=(gtk_spin_button_get_update_policy (handle)=gtk_update_if_valid)
232		end
233
234
235-- Gets the update behavior of a spin button. See gtk_spin_button_set_update_policy().
236
237-- spin_button : 	a GtkSpinButton
238	-- Returns : 	the current update policy
239	
240
241feature
242	allow_non_numeric is
243			-- Allow the user to type non-numeric text into the spin button.
244		do
245			gtk_spin_button_set_numeric (handle, 0)
246		end
247
248	allow_only_numeric is
249			-- Allow the user to type only numeric text into the spin button.
250		do
251			gtk_spin_button_set_numeric (handle, 1)
252		end
253	
254	are_only_numeric_allowed: BOOLEAN is
255			-- Can only numeric text can be entered?
256		do
257			Result:=(gtk_spin_button_get_numeric (handle)).to_boolean
258		end
259
260feature  -- Spinning
261	spin (a_direction: INTEGER; an_increment: INTEGER) is
262			-- Increment or decrement a spin button's value in a specified direction by a specified amount.
263			-- `a_direction' is a GtkSpinType indicating the direction to spin.
264			-- `an_increment' is the step increment to apply in the specified direction.
265		require is_valid_gtk_spin_type (a_direction)
266		do
267			gtk_spin_button_spin (handle, a_direction, an_increment)
268		end
269
270feature -- Wrapping
271	set_wrap is
272			-- Makes the spin button value wraps around to the opposite limit when
273			-- the upper or lower limit of the range is exceeded.
274		do
275			gtk_spin_button_set_wrap (handle, 1)
276		end
277
278	unset_wrap is
279			-- Unset wrapping. See `set_wrap'
280		do
281			gtk_spin_button_set_wrap (handle, 0)
282		end
283
284	is_wrap_set: BOOLEAN is
285			-- Doed the spin button's value wrap around to the opposite limit when
286			-- the upper or lower limit of the range is exceeded?
287		do
288			Result:=(gtk_spin_button_get_wrap (handle)).to_boolean
289		end
290
291feature -- Snapping
292	set_snap_to_ticks is
293			-- At every update corrects the values to the nearest step increment
294			-- when a spin button is activated after providing an invalid value.
295		do
296			gtk_spin_button_set_snap_to_ticks (handle, 1)
297		end
298
299	unset_snap_to_ticks is
300			-- Unset snap to ticks. See `set_snap_to_ticks'
301		do
302			gtk_spin_button_set_snap_to_ticks (handle, 1)
303		end
304	
305feature
306	update is
307			-- Manually force an update of the spin button.
308		do
309			gtk_spin_button_update (handle)
310		end
311
312	digits: INTEGER is
313			--  the precision of spin_button. See `set_digits'. TODO: shall be NATURAL
314		do
315			Result := gtk_spin_button_get_digits (handle)
316		end
317
318
319	increments: TUPLE[REAL,REAL] is
320			--  the current step and page the increments used by spin_button. See
321			--  `set_increments'.
322		local s,p: REAL
323		do
324			gtk_spin_button_get_increments (handle, $s, $p)
325			-- s,step : 	location to store step increment, or NULL
326			-- p,page : 	location to store page increment, or NULL
327			create Result.make_2 (s,p)
328		end
329
330	range: TUPLE[REAL,REAL] is
331			-- the range (minumun, maximum) allowed for spin_button. See
332			-- `set_range'.
333		local a_min,a_max:REAL
334		do
335			gtk_spin_button_get_range (handle, $a_min, $a_max)
336			-- spin_button : 	a GtkSpinButton
337			-- min : 	location to store minimum allowed value, or NULL
338			-- max : 	location to store maximum allowed value, or NULL
339			create Result.make_2 (a_min, a_max)
340		end
341
342	is_snapped_to_ticks: BOOLEAN is
343		-- Are the values corrected to the nearest step? See `set_snap_to_ticks'.
344		do
345			Result:= gtk_spin_button_get_snap_to_ticks(handle).to_boolean
346		end
347	
348	value: REAL is
349			--  the value in the spin_button.
350		do
351			Result := gtk_spin_button_get_value (handle)
352		end
353	
354feature -- TODO Properties
355-- The "adjustment" property
356
357--   "adjustment"           GtkAdjustment         : Read / Write
358
359-- The adjustment that holds the value of the spinbutton.
360-- The "climb-rate" property
361
362--   "climb-rate"           gdouble               : Read / Write
363
364-- The acceleration rate when you hold down a button.
365
366-- Allowed values: >= 0
367
368-- Default value: 0
369-- The "digits" property
370
371--   "digits"               guint                 : Read / Write
372
373-- The number of decimal places to display.
374
375-- Allowed values: <= 20
376
377-- Default value: 0
378-- The "numeric" property
379
380--   "numeric"              gboolean              : Read / Write
381
382-- Whether non-numeric characters should be ignored.
383
384-- Default value: FALSE
385-- The "snap-to-ticks" property
386
387--   "snap-to-ticks"        gboolean              : Read / Write
388
389-- Whether erroneous values are automatically changed to a spin button's nearest step increment.
390
391-- Default value: FALSE
392-- The "update-policy" property
393
394--   "update-policy"        GtkSpinButtonUpdatePolicy  : Read / Write
395
396-- Whether the spin button should update always, or only when the value is legal.
397
398-- Default value: GTK_UPDATE_ALWAYS
399-- The "value" property
400
401--   "value"                gdouble               : Read / Write
402
403-- Reads the current value, or sets a new value.
404
405-- Default value: 0
406-- The "wrap" property
407
408--   "wrap"                 gboolean              : Read / Write
409
410-- Whether a spin button should wrap upon reaching its limits.
411
412-- Default value: FALSE
413-- Style Property Details
414-- The "shadow-type" style property
415
416--   "shadow-type"          GtkShadowType         : Read
417
418-- the type of border that surrounds the arrows of a spin button.
419
420-- Default value: GTK_SHADOW_IN
421-- Signal Details
422-- The "change-value" signal
423
424-- void        user_function                  (GtkSpinButton *spinbutton,
425--                                             GtkScrollType arg1,
426--                                             gpointer user_data);
427
428-- spinbutton : 	the object which received the signal.
429-- arg1 : 	
430-- user_data : 	user data set when the signal handler was connected.
431-- The "input" signal
432
433-- gint        user_function                  (GtkSpinButton *spinbutton,
434--                                             gpointer arg1,
435--                                             gpointer user_data);
436
437-- spinbutton : 	the object which received the signal.
438-- arg1 : 	
439-- user_data : 	user data set when the signal handler was connected.
440-- Returns : 	
441-- The "output" signal
442
443-- gboolean    user_function                  (GtkSpinButton *spinbutton,
444--                                             gpointer user_data);
445
446-- spinbutton : 	the object which received the signal.
447-- user_data : 	user data set when the signal handler was connected.
448-- Returns : 	
449-- The "value-changed" signal
450
451-- void        user_function                  (GtkSpinButton *spinbutton,
452--                                             gpointer user_data);
453
454-- spinbutton : 	the object which received the signal.
455-- user_data : 	user data set when the signal handler was connected.
456-- See Also
457
458-- GtkEntry 	
459
460-- retrieve text rather than numbers.
461
462
463end