Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Spinbox(3)	      User Contributed Perl Documentation	    Spinbox(3)

NAME
       Tk::Spinbox - Create and	manipulate Spinbox widgets

SYNOPSIS
       $spinbox	=  $parent->Spinbox(?options?);

	-activebackground    -highlightthickness -repeatinterval
	-background	     -insertbackground	 -selectbackground
	-borderwidth	     -insertborderwidth	 -selectborderwidth
	-cursor		     -insertontime	 -selectforeground
	-exportselection     -insertwidth	 -takefocus
	-font		     -insertofftime	 -textvariable
	-foreground	     -justify		 -xscrollcommand
	-highlightbackground -relief
	-highlightcolor	     -repeatdelay

WIDGET-SPECIFIC	OPTIONS
       Option:	 -buttonbackground
       Name:	 buttonBackground
       Class:	 Background
	   The background color	to be used for the spin	buttons.

       Option:	 -buttoncursor
       Name:	 buttonCursor
       Class:	 Cursor
	   The cursor to be used when over the spin buttons.  If this is empty
	   (the	default), a default cursor will	be used.

       Option:	 -buttondownrelief
       Name:	 buttonDownRelief
       Class:	 Relief
	   The relief to be used for the upper spin button.

       Option:	 -buttonuprelief
       Name:	 buttonUpRelief
       Class:	 Relief
	   The relief to be used for the lower spin button.

       Option:	 -command
       Name:	 command
       Class:	 Command
	   Specifies a Perl/Tk callback	to invoke whenever a Spinbutton	is
	   invoked.  The callback has these two	arguments appended to any
	   existing callback arguments:	the current value of the widget	and
	   the direction of the	button press (up or down).

       Option:	 -disabledbackground
       Name:	 disabledBackground
       Class:	 DisabledBackground
	   Specifies the background color to use when the Spinbox is disabled.
	   If this option is the empty string, the normal background color is
	   used.

       Option:	 -disabledforeground
       Name:	 disabledForeground
       Class:	 DisabledForeground
	   Specifies the foreground color to use when the Spinbox is disabled.
	   If this option is the empty string, the normal foreground color is
	   used.

       Option:	 -format
       Name:	 format
       Class:	 Format
	   Specifies an	alternate format to use	when setting the string	value
	   when	using the -from	and -to	range.	This must be a format
	   specifier of	the form %<pad>.<pad>f,	as it will format a floating-
	   point number.

       Option:	 -from
       Name:	 from
       Class:	 From
	   A floating-point value corresponding	to the lowest value for	a
	   Spinbox, to be used in conjunction with -to and -increment.	When
	   all are specified correctly,	the Spinbox will use these values to
	   control its contents.  This value must be less than the -to option.
	   If -values is specified, it supercedes this option.

       Option:	 -invalidcommand
       Alias:	 -invcmd
       Name:	 invalidCommand
       Class:	 InvalidCommand
	   Specifies a script to eval when validateCommand returns 0.  Setting
	   it to an empty string disables this feature (the default).  The
	   best	use of this option is to set it	to bell.  See Validation below
	   for more information.

       Option:	 -increment
       Name:	 increment
       Class:	 Increment
	   A floating-point value specifying the increment.  When used with
	   -from and -to, the value in the widget will be adjusted by
	   -increment when a spin button is pressed (up	adds the value,	down
	   subtracts the value).

       Option:	 -readonlybackground
       Name:	 readonlyBackground
       Class:	 ReadonlyBackground
	   Specifies the background color to use when the Spinbox is readonly.
	   If this option is the empty string, the normal background color is
	   used.

       Option:	 -state
       Name:	 state
       Class:	 State
	   Specifies one of three states for the Spinbox:  normal, disabled,
	   or readonly.	 If the	Spinbox	is readonly, then the value may	not be
	   changed using methods and no	insertion cursor will be displayed,
	   even	if the input focus is in the widget; the contents of the
	   widget may still be selected.  If the Spinbox is disabled, the
	   value may not be changed, no	insertion cursor will be displayed,
	   the contents	will not be selectable,	and the	Spinbox	may be
	   displayed in	a different color, depending on	the values of the
	   -disabledforeground and -disabledbackground options.

       Option:	 -to
       Name:	 to
       Class:	 To
	   A floating-point value corresponding	to the highest value for the
	   Spinbox, to be used in conjunction with -from and -increment.  When
	   all are specified correctly,	the Spinbox will use these values to
	   control its contents.  This value must be greater than the -from
	   option.  If -values is specified, it	supercedes this	option.

       Option:	 -validate
       Name:	 validate
       Class:	 Validate
	   Specifies the mode in which validation should operate: none,	focus,
	   focusin, focusout, key, or all.  It defaults	to none.  When you
	   want	validation, you	must explicitly	state which mode you wish to
	   use.	 See Validation	below for more.

       Option:	 -validatecommand
       Alias:	 -vcmd
       Name:	 validateCommand
       Class:	 ValidateCommand
	   Specifies a script to evaluate when you want	to validate the	input
	   in the widget.  Setting it to an empty string disables this feature
	   (the	default).  Validation occurs according to the value of
	   -validate.  This command must return	a valid	boolean	value.	If it
	   returns 0 (or the valid boolean equivalent) then the	value of the
	   widget will not change and the invalidCommand will be evaluated if
	   it is set.  If it returns 1,	then value will	be changed.  See
	   Validation below for	more information.

       Option:	 -values
       Name:	 values
       Class:	 Values
	   Must	be a proper list value.	 If specified, the Spinbox will	use
	   these values	as to control its contents, starting with the first
	   value.  This	option has precedence over the -from and -to range.

       Option:	 -width
       Name:	 width
       Class:	 Width
	   Specifies an	integer	value indicating the desired width of the
	   Spinbox window, in average-size characters of the widget's font.
	   If the value	is less	than or	equal to zero, the widget picks	a size
	   just	large enough to	hold its current text.

       Option:	 -wrap
       Name:	 wrap
       Class:	 Wrap
	   Must	be a proper boolean value.  If on, the Spinbox will wrap
	   around the values of	data in	the widget.

DESCRIPTION
       The Spinbox method creates a new	window (given by the $spinbox
       argument) and makes it into a Spinbox widget.  Additional options,
       described above,	may be specified on the	command	line or	in the option
       database	to configure aspects of	the Spinbox such as its	colors,	font,
       and relief.

       A Spinbox is an extended	Entry widget that allows he user to move, or
       spin, through a fixed set of ascending or descending values such	as
       times or	dates in addition to editing the value as in an	entry.	When
       first created, a	Spinbox's string is empty.  A portion of the Spinbox
       may be selected as described below.  If a Spinbox is exporting its
       selection (see the exportSelection option), then	it will	observe	the
       standard	protocols for handling the selection;  Spinbox selections are
       available as type STRING.  Spinboxes also observe the standard Tk rules
       for dealing with	the input focus.  When a Spinbox has the input focus
       it displays an insertion	cursor to indicate where new characters	will
       be inserted.

       Spinboxes are capable of	displaying strings that	are too	long to	fit
       entirely	within the widget's window.  In	this case, only	a portion of
       the string will be displayed; commands described	below may be used to
       change the view in the window.  Spinboxes use the standard
       -xscrollcommand mechanism for interacting with scrollbars (see the
       description of the -xscrollcommand option for details).	They also
       support scanning, as described below.

VALIDATION
       Validation works	by setting the validateCommand option to a callback
       which will be evaluated according to the	validate option	as follows:

       none
	   Default.  This means	no validation will occur.

       focus
	   validateCommand will	be called when the Spinbox receives or loses
	   focus.

       focusin
	   validateCommand will	be called when the Spinbox receives focus.

       focusout
	   validateCommand will	be called when the Spinbox loses focus.

       key validateCommand will	be called when the Spinbox is edited.

       all validateCommand will	be called for all above	conditions.

	   The validateCommand and invalidCommand callbacks are	invoked	with
	   at least 5 positional arguments, which are appended to any already
	   existing callback arguments:

	   o   1

	       The proposed value of the entry.	 If you	are configuring	the
	       entry widget to have a new textVariable,	this will be the value
	       of that textVariable.

	   o   2

	       The characters to be added (or deleted).	This will be "undef"
	       if validation is	due to focus, explcit call to validate or if
	       change is due to	"-textvariable"	changing.

	   o   3

	       The current value of entry i.e. before the proposed change.

	   o   4

	       The index of character string to	be added/deleted, if any.
	       Otherwise -1.

	   o   5

	       Type of action. 1 == INSERT, 0 == DELETE, -1 if it's a forced
	       validation or textVariable validation.

	   In general, the textVariable	and validateCommand can	be dangerous
	   to mix.  Any	problems have been overcome so that using the
	   validateCommand will	not interfere with the traditional behavior of
	   the Spinbox widget.	Using the textVariable for read-only purposes
	   will	never cause problems.  The danger comes	when you try set the
	   textVariable	to something that the validateCommand would not
	   accept, which causes	validate to become none	(the invalidCommand
	   will	not be triggered).  The	same happens when an error occurs
	   evaluating the validateCommand.

	   Primarily, an error will occur when the validateCommand or
	   invalidCommand encounters an	error in its script while evaluating
	   or validateCommand does not return a	valid boolean value.  The
	   validate option will	also set itself	to none	when you edit the
	   Spinbox widget from within either the validateCommand or the
	   invalidCommand.  Such editions will override	the one	that was being
	   validated.  If you wish to edit the value of	the widget during
	   validation and still	have the validate option set, you should
	   include the command

	    my $val = $spinbox->cget(-validate);
	    $spinbox->configure(-validate => $val);

	   in the validateCommand or invalidCommand (whichever one you were
	   editing the Spinbox widget from).  It is also recommended to	not
	   set an associated textVariable during validation, as	that can cause
	   the Spinbox widget to become	out of sync with the textVariable.

WIDGET METHODS
       The Spinbox command creates a widget object whose name is $widget.
       This command may	be used	to invoke various operations on	the widget.
       It has the following general form:

	$widget->method(?arg arg ...?);

       Many of the methods for Spinboxes take one or more indices as
       arguments.  An index specifies a	particular character in	the Spinbox's
       string, in any of the following ways:

       number
	   Specifies the character as a	numerical index, where 0 corresponds
	   to the first	character in the string.

       anchor
	   Indicates the anchor	point for the selection, which is set with the
	   select from and select adjust methods.

       end Indicates the character just	after the last one in the Spinbox's
	   string.  This is equivalent to specifying a numerical index equal
	   to the length of the	Spinbox's string.

       insert
	   Indicates the character adjacent to and immediately following the
	   insertion cursor.

       sel.first
	   Indicates the first character in the	selection.  It is an error to
	   use this form if the	selection isn't	in the Spinbox window.

       sel.last
	   Indicates the character just	after the last one in the selection.
	   It is an error to use this form if the selection isn't in the
	   Spinbox window.

       @number
	   In this form, number	is treated as an x-coordinate in the Spinbox's
	   window;  the	character spanning that	x-coordinate is	used.  For
	   example, ``@0'' indicates the left-most character in	the window.

       Abbreviations may be used for any of the	forms above, e.g. ``e''	or
       ``sel.f''.  In general, out-of-range indices are	automatically rounded
       to the nearest legal value.

       The following commands are possible for Spinbox widgets:

       $widget->bbox(index);
	   Returns a list of four numbers describing the bounding box of the
	   character given by index.  The first	two elements of	the list give
	   the x and y coordinates of the upper-left corner of the screen area
	   covered by the character (in	pixels relative	to the widget) and the
	   last	two elements give the width and	height of the character, in
	   pixels.  The	bounding box may refer to a region outside the visible
	   area	of the window.

       $widget->cget(option);
	   Returns the current value of	the configuration option given by
	   option.  Option may have any	of the values accepted by the Spinbox
	   command.

       $widget->configure(?option?, ?value, option, value, ...?);
	   Query or modify the configuration options of	the widget.  If	no
	   option is specified,	returns	a list describing all of the available
	   options for $widget (see Tk::configure for information on the
	   format of this list).  If option is specified with no value,	then
	   the command returns a list describing the one named option (this
	   list	will be	identical to the corresponding sublist of the value
	   returned if no option is specified).	 If one	or more	option-value
	   pairs are specified,	then the command modifies the given widget
	   option(s) to	have the given value(s);  in this case the command
	   returns an empty string.  Option may	have any of the	values
	   accepted by the Spinbox command.

       $widget->delete(first, ?last?);
	   Delete one or more elements of the Spinbox.	First is the index of
	   the first character to delete, and last is the index	of the
	   character just after	the last one to	delete.	 If last isn't
	   specified it	defaults to first+1, i.e. a single character is
	   deleted.  This command returns an empty string.

       $widget->get;
	   Returns the Spinbox's string.

       $widget->icursor(index);
	   Arrange for the insertion cursor to be displayed just before	the
	   character given by index.  Returns an empty string.

       $widget->identify(x, y);
	   Returns the name of the window element corresponding	to coordinates
	   x and y in the Spinbox.  Return value is one	of: none, buttondown,
	   buttonup, entry.

       $widget->index(index);
	   Returns the numerical index corresponding to	index.

       $widget->insert(index, string);
	   Insert the characters of string just	before the character indicated
	   by index.  Returns an empty string.

       $widget->invoke(element);
	   Causes the specified	element, either	buttondown or buttonup,	to be
	   invoked, triggering the action associated with it.

       $widget->scan(option, args);
	   This	command	is used	to implement scanning on Spinboxes.  It	has
	   two forms, depending	on option:

	   $widget->scanMark(x);
	       Records x and the current view in the Spinbox window;  used in
	       conjunction with	later scan dragto commands.  Typically this
	       command is associated with a mouse button press in the widget.
	       It returns an empty string.

	   $widget->scanDragto(x);
	       This command computes the difference between its	x argument and
	       the x argument to the last scan mark command for	the widget.
	       It then adjusts the view	left or	right by 10 times the
	       difference in x-coordinates.  This command is typically
	       associated with mouse motion events in the widget, to produce
	       the effect of dragging the Spinbox at high speed	through	the
	       window.	The return value is an empty string.

       $widget->selection(option, arg);
	   This	command	is used	to adjust the selection	within a Spinbox.  It
	   has several forms, depending	on option:

	   $widget->selectionAdjust(index);
	       Locate the end of the selection nearest to the character	given
	       by index, and adjust that end of	the selection to be at index
	       (i.e including but not going beyond index).  The	other end of
	       the selection is	made the anchor	point for future select	to
	       commands.  If the selection isn't currently in the Spinbox,
	       then a new selection is created to include the characters
	       between index and the most recent selection anchor point,
	       inclusive.  Returns an empty string.

	   $widget->selectionClear;
	       Clear the selection if it is currently in this widget.  If the
	       selection isn't in this widget then the command has no effect.
	       Returns an empty	string.

	   $widget->selectionElement(?element?);
	       Sets or gets the	currently selected element.  If	a spinbutton
	       element is specified, it	will be	displayed depressed.

	   $widget->selectionFrom(index);
	       Set the selection anchor	point to just before the character
	       given by	index.	Doesn't	change the selection.  Returns an
	       empty string.

	   $widget->selectionPresent;
	       Returns 1 if there is are characters selected in	the Spinbox, 0
	       if nothing is selected.

	   $widget->selectionRange(start, end);
	       Sets the	selection to include the characters starting with the
	       one indexed by start and	ending with the	one just before	end.
	       If end refers to	the same character as start or an earlier one,
	       then the	Spinbox's selection is cleared.

	   $widget->selectionTo(index);
	       If index	is before the anchor point, set	the selection to the
	       characters from index up	to but not including the anchor	point.
	       If index	is the same as the anchor point, do nothing.  If index
	       is after	the anchor point, set the selection to the characters
	       from the	anchor point up	to but not including index.  The
	       anchor point is determined by the most recent select from or
	       select adjust command in	this widget.  If the selection isn't
	       in this widget then a new selection is created using the	most
	       recent anchor point specified for the widget.  Returns an empty
	       string.

       $widget->set(?string?);
	   If string is	specified, the Spinbox will try	and set	it to this
	   value, otherwise it just returns the	Spinbox's string.  If
	   validation is on, it	will occur when	setting	the string.

       $widget->validate;
	   This	command	is used	to force an evaluation of the validateCommand
	   independent of the conditions specified by the validate option.
	   This	is done	by temporarily setting the validate option to all.  It
	   returns 0 or	1.

       $widget->xview(args);
	   This	command	is used	to query and change the	horizontal position of
	   the text in the widget's window.  It	can take any of	the following
	   forms:

	   $widget->xview;
	       Returns a list containing two elements.	Each element is	a real
	       fraction	between	0 and 1;  together they	describe the
	       horizontal span that is visible in the window.  For example, if
	       the first element is .2 and the second element is .6, 20% of
	       the Spinbox's text is off-screen	to the left, the middle	40% is
	       visible in the window, and 40% of the text is off-screen	to the
	       right.  These are the same values passed	to scrollbars via the
	       -xscrollcommand option.

	   $widget->xview(index);
	       Adjusts the view	in the window so that the character given by
	       index is	displayed at the left edge of the window.

	   $widget->xviewMoveto(fraction);
	       Adjusts the view	in the window so that the character fraction
	       of the way through the text appears at the left edge of the
	       window.	Fraction must be a fraction between 0 and 1.

	   $widget->xviewScroll(number,	what);
	       This command shifts the view in the window left or right
	       according to number and what.  Number must be an	integer.  What
	       must be either units or pages or	an abbreviation	of one of
	       these.  If what is units, the view adjusts left or right	by
	       number average-width characters on the display;	if it is pages
	       then the	view adjusts by	number screenfuls.  If number is
	       negative	then characters	farther	to the left become visible;
	       if it is	positive then characters farther to the	right become
	       visible.

DEFAULT	BINDINGS
       Tk automatically	creates	class bindings for Spinboxes that give them
       the following default behavior.	In the descriptions below, ``word''
       refers to a contiguous group of letters,	digits,	or ``_'' characters,
       or any single character other than these.

       [1] Clicking mouse button 1 positions the insertion cursor just before
	   the character underneath the	mouse cursor, sets the input focus to
	   this	widget,	and clears any selection in the	widget.	 Dragging with
	   mouse button	1 strokes out a	selection between the insertion	cursor
	   and the character under the mouse.

       [2] Double-clicking with	mouse button 1 selects the word	under the
	   mouse and positions the insertion cursor at the beginning of	the
	   word.  Dragging after a double click	will stroke out	a selection
	   consisting of whole words.

       [3] Triple-clicking with	mouse button 1 selects all of the text in the
	   Spinbox and positions the insertion cursor before the first
	   character.

       [4] The ends of the selection can be adjusted by	dragging with mouse
	   button 1 while the Shift key	is down;  this will adjust the end of
	   the selection that was nearest to the mouse cursor when button 1
	   was pressed.	 If the	button is double-clicked before	dragging then
	   the selection will be adjusted in units of whole words.

       [5] Clicking mouse button 1 with	the Control key	down will position the
	   insertion cursor in the Spinbox without affecting the selection.

       [6] If any normal printing characters are typed in a Spinbox, they are
	   inserted at the point of the	insertion cursor.

       [7] The view in the Spinbox can be adjusted by dragging with mouse
	   button 2.  If mouse button 2	is clicked without moving the mouse,
	   the selection is copied into	the Spinbox at the position of the
	   mouse cursor.

       [8] If the mouse	is dragged out of the Spinbox on the left or right
	   sides while button 1	is pressed, the	Spinbox	will automatically
	   scroll to make more text visible (if	there is more text off-screen
	   on the side where the mouse left the	window).

       [9] The Left and	Right keys move	the insertion cursor one character to
	   the left or right;  they also clear any selection in	the Spinbox
	   and set the selection anchor.  If Left or Right is typed with the
	   Shift key down, then	the insertion cursor moves and the selection
	   is extended to include the new character.  Control-Left and
	   Control-Right move the insertion cursor by words, and Control-
	   Shift-Left and Control-Shift-Right move the insertion cursor	by
	   words and also extend the selection.	 Control-b and Control-f
	   behave the same as Left and Right, respectively.  Meta-b and	Meta-f
	   behave the same as Control-Left and Control-Right, respectively.

       [10]
	   The Home key, or Control-a, will move the insertion cursor to the
	   beginning of	the Spinbox and	clear any selection in the Spinbox.
	   Shift-Home moves the	insertion cursor to the	beginning of the
	   Spinbox and also extends the	selection to that point.

       [11]
	   The End key,	or Control-e, will move	the insertion cursor to	the
	   end of the Spinbox and clear	any selection in the Spinbox.  Shift-
	   End moves the cursor	to the end and extends the selection to	that
	   point.

       [12]
	   The Select key and Control-Space set	the selection anchor to	the
	   position of the insertion cursor.  They don't affect	the current
	   selection.  Shift-Select and	Control-Shift-Space adjust the
	   selection to	the current position of	the insertion cursor,
	   selecting from the anchor to	the insertion cursor if	there was not
	   any selection previously.

       [13]
	   Control-/ selects all the text in the Spinbox.

       [14]
	   Control-\ clears any	selection in the Spinbox.

       [15]
	   The F16 key (labelled Copy on many Sun workstations)	or Meta-w
	   copies the selection	in the widget to the clipboard,	if there is a
	   selection.

       [16]
	   The F20 key (labelled Cut on	many Sun workstations) or Control-w
	   copies the selection	in the widget to the clipboard and deletes the
	   selection.  If there	is no selection	in the widget then these keys
	   have	no effect.

       [17]
	   The F18 key (labelled Paste on many Sun workstations) or Control-y
	   inserts the contents	of the clipboard at the	position of the
	   insertion cursor.

       [18]
	   The Delete key deletes the selection, if there is one in the
	   Spinbox.  If	there is no selection, it deletes the character	to the
	   right of the	insertion cursor.

       [19]
	   The BackSpace key and Control-h delete the selection, if there is
	   one in the Spinbox.	If there is no selection, it deletes the
	   character to	the left of the	insertion cursor.

       [20]
	   Control-d deletes the character to the right	of the insertion
	   cursor.

       [21]
	   Meta-d deletes the word to the right	of the insertion cursor.

       [22]
	   Control-k deletes all the characters	to the right of	the insertion
	   cursor.

       [23]
	   Control-t reverses the order	of the two characters to the right of
	   the insertion cursor.

	   If the Spinbox is disabled using the	-state option, then the
	   Spinbox's view can still be adjusted	and text in the	Spinbox	can
	   still be selected, but no insertion cursor will be displayed	and no
	   text	modifications will take	place.

	   The behavior	of Spinboxes can be changed by defining	new bindings
	   for individual widgets or by	redefining the class bindings.

KEYWORDS
       Spinbox,	Entry, widget

perl v5.24.1			  2013-11-15			    Spinbox(3)

NAME | SYNOPSIS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | VALIDATION | WIDGET METHODS | DEFAULT BINDINGS | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::Spinbox&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help