7.11 Numberentry widget

local 
   N R
   Desc=numberentry(min:0 max:100
                    init:10
                    handle:N
                    return:R
                    action:proc{$} {Show {N get($)}} end)
in 
   {{QTk.build td(Desc)} show}
   {Wait R}
   {Show R}
end

7.11.1 Description

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.

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.

Indices

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:

7.11.2 Parameter List

Specific Parameters

1 action actionh init max min return show state width

Non Specific Parameters

background borderwidth cursor exportselection feature font foreground glue handle highlightbackground highlightcolor highlightthickness insertbackground insertborderwidth insertofftime insertontime insertwidth justify look onCreation padx pady relief selectbackground selectborderwidth selectforeground takefocus tooltips

7.11.3 Method List

'raise'

'raise'(1:W): If the W argument is omitted then the command raises the widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the 'raise' command will insert this widget into the stacking order just above W; this could end up either raising or lowering the widget.

bind

bind(event:E action:A args:LA append:AP): Specifies an action LA to execute when the event E is triggered.

get

get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.

getFocus

getFocus(force:B): if B is false (or by default): if the application currently has the input focus on the widget's display, this command resets the input focus for the widget's display to the widget. If the application doesn't currently have the input focus on the widget's display, the widget will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, it will be redirected it to the widget. If B is true: sets the focus of the widget's display to the widget, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. B must be a boolean.

getGrabStatus

getGrabStatus(1:V): Binds V to the atom none if there is no grab on the widget, to the atom local if there is a local grab and to global if there is a global grab. V must be a free variable.

icursor

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

index

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

lower

lower(1:W): If the W argument is omitted then the command lowers the widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the lower command will insert this widget into the stacking order just below W; this could end up either raising or lowering the widget.

releaseGrab

releaseGrab: Releases the grab on the widget if there is one, otherwise does nothing.

scan

scan(...): This command is used to implement scanning on entries. It has two forms, depending on option:

set

set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.

setGrab

setGrab(global:B): Sets a grab on the widget. If B is true then the grab is global, otherwise it is local (B false by default). If a grab was already in effect for this application then it is automatically released. If there is already a grab on the widget and it has the same global/local form as the requested grab, then the command does nothing. Local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. Warning: whe a grab is set, it is define for the whole Oz process so that it will prevent the user to do input to other windows as well. Moreover a grab is still effective even if the window that contains the grabbed widgets is hidden. B must be a boolean.

winfo

winfo(parameter1:value1 ... parameterX:valueX): This commands works like the get method, but for window-related information. For more details, see Section 8.9.

7.11.4 Detailed Parameters List

1

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

action

action:C: Specifies an action to execute right after the user modified the entry. C can take several different forms (see Section 4.3.1).

actionh

actionh:C: Similar to the action parameter where then handle of the widget is given as a parameter to the action to be executed. This parameter overrides the action parameter when present.

init

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

max

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.

min

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.

background

background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).

borderwidth

borderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. P must be a valid screen distance (see Section 8.6).

cursor

cursor:A: Specifies the mouse cursor to be used for the widget. A must be a valid cursor (see Section 8.7)

exportselection

exportselection:B: Specifies whether or not a selection in the widget should also be the X selection. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections. B must be a boolean.

feature

feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.

font

font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)

foreground

foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)

glue

glue:A: Specifies how a widget must fit in its own available place. A must be an atom that is any combination of n, s, w and e. If a direction is specified, the corresponding border is glued to its neighbor or border of the frame if there is no neighbor. If a direction is not specified, the corresponding border if such that the widget takes just the width or height it needs to draw itself. If none of opposite directions is specified, the widget is centered. For more details, see Section 4.1.

handle

handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.

highlightbackground

highlightbackground:C: Specifies the color to display in the traversal highlight region when the widget does not have the input focus. C must be a valid color (see Section 8.2)

highlightcolor

highlightcolor:C: Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. C must be a valid color (see Section 8.2)

highlightthickness

highlightthickness:P: Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. If the value is zero, no focus highlight is drawn around the widget. P must be a valid screen distance (see Section 8.6).

insertbackground

insertbackground:C: Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). C must be a valid color (see Section 8.2).

insertborderwidth

insertborderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. P must be a valid screen distance (see Section 8.6).

insertofftime

insertofftime:I: Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "off" in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time. I must be a positive integer value.

insertontime

insertontime:I: Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "on" in each blink cycle. I must be a positive integer value.

insertwidth

insertwidth:P: Specifies a value indicating the total width of the insertion cursor. If a border has been specified for the insertion cursor (using the insertborderwidth option), the border will be drawn inside the width specified by the insertwidth option. P must be a valid screen distance (see Section 8.6).

justify

justify:A: When there are multiple lines of text displayed in a widget, this option determines how the lines line up with each other. Must be one of these atoms: left, center, or right. left means that the lines' left edges all line up, center means that the lines' centers are aligned, and right means that the lines' right edges line up.

look

look:L: Specifies a look to use for the widget. A look specifies default values for the parameters of widgets. This parameter can be specified at creation time only. Moreover changing a look will not change the appearance of widgets that are already displayed with that look. See Section 5.1 for more details.

onCreation

onCreation:P: When a widget is created, for example by QTk.build, this parameter specifies an action to execute right after the widget has been created, but before returning from the build instruction. It is usefull if one needs the handle of the widget to initialize it in ways not permitted by its description record (for example binding the Enter or Leave mouse events).

padx

padx:P: Specifies how much horizontal external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

pady

pady:P: Specifies how much vertical external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

relief

relief:A: Specifies the 3-D effect desired for the widget. Must be one of these atoms: raised, sunken, flat, ridge, solid or groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

selectbackground

selectbackground:C: Specifies the background color to use when displaying selected items. C must be a valid color (see Section 8.2).

selectborderwidth

selectborderwidth:P: pecifies a non-negative value indicating the width of the 3-D border to draw around selected items. P must be a valid screen distance (see Section 8.6).

selectforeground

selectforeground:C: Specifies the foreground color to use when displaying selected items. C must be a valid color (see Section 8.2).

takefocus

takefocus:B: Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the takeFocus option. A value of false means that the widget should be skipped entirely during keyboard traversal. true means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.

tooltips

tooltips:VS: Specifies a tooltip for the widget. A tooltip is a small message that appears when the mouse cursor if left still over the widget for a while. If VS is set to nil, no tooltip will appear at all. VS must be a virtual string.

return

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

show

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.

state

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.

width

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.


Donatien Grolaux
Version 1.3.0 (20040413)