<section ID="chapter.widgets.numberentry">
  <TITLE>Numberentry widget</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A numberentry is a widget that displays a one-line text string and allows that string to be edited. The string can contains only integer values between a defined range. Small arrows allow the user to modify the value of the integer with the mouse. A portion of the entry may be selected as described below. If an entry is exporting its selection (see the <<exportselection>> option), then it will observe the standard X11 protocols for handling the selection. When an entry has the input focus it displays an insertion cursor to indicate where new characters will be inserted.
</P>
<P>
Number entries 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. Entries use the standard <<lrscrollbar>> mechanism. They also support scanning, as described below. 
</P>
<P>
<EM>Indices</EM>
</P>
<P>
Many of the widget methods for entry take one or more indices as arguments. An index specifies a particular character of the entry, in any of the following ways: 
<LIST>

<ITEM> integer : Specifies the character as a numerical index, where 0 corresponds to the first character in the string. 

<ITEM> <<anchor>> : Indicates the anchor point for the selection, which is set with the select from and select adjust widget commands. 

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

<ITEM> <<insert>> :  Indicates the character adjacent to and immediately following the insertion cursor.  

<ITEM> <<'sel.first'>> : Indicates the first character in the selection. It is an error to use this form if the selection isn't in the entry window. 

<ITEM> <<'self.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 entry window. 

<ITEM> <<'@'#X>> : In this form, <<X>> is treated as an x-coordinate in the entry's window; the character spanning that x-coordinate is used. For example, <<'@'#0>> indicates the left-most character in the window. 

</LIST>
<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>
<ITEM> <<1:I>> : Specifies a positive integer value to display inside the widget. This parameter can be only used with the <<set()>> and <<get()>> methods.

<ITEM> <<init:I>> : Specifies a positive integer value to display inside the widget. This parameter can be used at creation time only.

<ITEM> <<return:V>> : When the window is closed, <<V>> is bound to the contents of the number entry. <<V>> must be a free variable.

&param_background;
&param_borderwidth;
&param_cursor;
&param_exportselection;
&param_font;
&param_foreground;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;
&param_insertbackground;
&param_insertborderwidth;
&param_insertofftime;
&param_insertontime;
&param_insertwidth;
&param_justify;
&param_relief;
&param_selectbackground;
&param_selectborderwidth;
&param_selectforeground;
&param_takefocus;

<ITEM> <<show:VS>> : If this option is specified, then the true contents of the entry are not displayed in the window. Instead, each character in the entry's value will be displayed as the first character in the value of this option, such as <<*>>. This is useful, for example, if the entry is to be used to enter a password. If characters in the entry are selected and copied elsewhere, the information copied will be what is displayed, not the true contents of the entry. <<VS>> must be a virtual string.

<ITEM> <<state:A>> : Specifies one of two states for the button: <<normal>> or <<disabled>>. If the entry is disabled then the value may not be changed using widget commands and no insertion cursor will be displayed, even if the input focus is in the widget. <<A>> must be one of these two atoms : <<normal>> or <<disabled>>.

<ITEM> <<width:I>> : Specifies an integer value indicating the desired width of the entry 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. <<I>> must be a valid index.

<ITEM> <<action:C>> : Specifies an action to execute juste after the user modified the entry. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<min:I>> : Specifies the lower bound of the range the user can select the value. <<I>> must be an integer that is at least zero. This option can be specified at creation time only.

<ITEM> <<max:I>> : Specifies the upper bound of the range the user can select the value. <<I>> must be an integer. This option can be specified at creation time only.

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;


</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

<ITEM> <<icursor(I)>> : Arrange for the insertion cursor to be displayed just before the character given by <<I>>. <<I>> must be an integer.

<ITEM> <<scan(...)>> : This command is used to implement scanning on entries. It has two forms, depending on option: 
<LIST>
<ITEM> <<scan(mark X Y)>> : Records X and Y and the entry's current view; used in conjunction with later <<scan(dragto ...)>> commands. Typically this command is associated with a mouse button press in the widget and <<X>> and <<Y>> are the coordinates of the mouse. <<X>> and <<Y>> must be valid distances (see <ptr to="misc.distance">).

<ITEM> <<scan(dragto X Y)>> : This command computes the difference between its <<X>> and <<Y>> arguments (which are
        typically mouse coordinates) and the <<X>> and <<Y>> arguments to the last <<scan(mark ...)>>
        command for the widget. It then adjusts the view by 10 times the difference in
        coordinates. This command is typically associated with mouse motion events in the
        widget, to produce the effect of dragging the listbox at high speed through its
        window.

</LIST>

<ITEM> <<index(A I)>> : Binds I to an integer giving index value that corresponds to <<A>>. 

</LIST>

</section>
