7.23 Tdscrollbar and lrscrollbar widgets

7.23.1 Description

A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a slider in the middle portion of the scrollbar. tdscrollbar displays a vertical scrollbar while lrscrollbar displays an horizontal one. It provides information about what is visible in an associated window that displays an document of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the document is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its document.

Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse.

Important: Scrollbars are most of the times used in conjonction with another widget (canvas, text widget, scroll frame). The widgets where it is relevant to have scrollbars support the tdscrollbar and lrscrollbar parameters that avoids to explicitly create scrollbar widgets. As a result, in usual situations, one should never need to use directly the tdscrollbar and lrscrollbar widgets.

ELEMENTS

A scrollbar displays five elements, which are referred to in the widget commands for the scrollbar:

• arrow1 : The top or left arrow in the scrollbar.

• trough1 : The region between the slider and arrow1.

• slider : The rectangle that indicates what is visible in the associated widget.

• trough2 : The region between the slider and arrow2.

• arrow2 : The bottom or right arrow in the scrollbar.

7.23.2 Parameter List

Specific Parameters

action actionh activerelief elementborderwidth jump width

Non Specific Parameters

activebackground background borderwidth cursor feature glue handle highlightbackground highlightcolor highlightthickness look onCreation padx pady relief repeatdelay repeatinterval takefocus throughcolor tooltips

7.23.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.

• Actions can be specified either as a procedure, a pair Port#Message or a pair Object#Method (see Section 4.3.3).

• Events are strings (see Section 8.11.1).

• The list of arguments LA specifies supplementary information to pass to the action, like the key code of a keypress, or the mouse coordinates of a mouse button click (see Section 8.11.2). If LA if not specified, nil is assumed.

• The boolean append parameter specifies if the binding overrides the previous binding for this event, or adds a supplementary action. If not specified, false is assumed.

delta

delta(X Y V): Binds V to a real number indicating the fractional change in the scrollbar setting that corresponds to a given change in slider position. For example, if the scrollbar is horizontal, the result indicates how much the scrollbar setting must change to move the slider X pixels to the right (Y is ignored in this case). If the scrollbar is vertical, the result indicates how much the scrollbar setting must change to move the slider Y pixels down.

fraction

fraction(X Y V): Binds V to a real number between 0 and 1 indicating where the point given by X and Y lies in the trough area of the scrollbar. The value 0 corresponds to the top or left of the trough, the value 1 corresponds to the bottom or right, 0.5 corresponds to the middle, and so on. X and Y must be pixel coordinates relative to the scrollbar widget. If X and Y refer to a point outside the trough, the closest point in the trough is used.

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.

identify

identify(X Y V): Binds V to the name of the element under the point given by X and Y (such as arrow1), or an empty string if the point does not lie in any element of the scrollbar. X and y must be pixel coordinates relative to the scrollbar widget.

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.

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.23.4 Detailed Parameters List

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

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.

activerelief:A: Specifies the relief to use when displaying the element that is active, if any. Elements other than the active element are always displayed with a raised relief. Must be one of these atoms: raised, sunken, flat, ridge, solid or groove.

elementborderwidth:P: Specifies the width of borders drawn around the internal elements of the scrollbar (the two arrows and the slider).If this value is less than zero, the value of the borderwidth option is used in its place. P must be a valid screen distance (see Section 8.6).

jump:B: Specifies when notifications are made about changes in the value. If the value is false, updates are made continuously as the slider is dragged. If the value is true, updates are delayed until the mouse button is released to end the drag; at that point a single notification is made (the value ``jumps'' rather than changing smoothly). B must be a boolean.

activebackground:C: Specifies the background color to use when drawing active elements. An element (a widget or portion of a widget) is active if the mouse cursor is positioned over the element and pressing a mouse button will cause some action to occur. For some elements on Windows and Macintosh systems, the active color will only be used while mouse button 1 is pressed over the element. C must be a valid color (see Section 8.2)

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: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:A: Specifies the mouse cursor to be used for the widget. A must be a valid cursor (see Section 8.7)

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.

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: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: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: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: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).

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: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: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: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: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.

repeatdelay:I: Specifies the number of milliseconds a button or key must be held down before it begins to auto-repeat. Used, for example, on the up- and down-arrows in scrollbars. I must be an integer.

repeatinterval:I: Used in conjunction with repeatdelay: once auto-repeat begins, this option determines the number of milliseconds between auto-repeats.

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.

throughcolor:C: Specifies the color to use for the rectangular trough areas in widgets such as scrollbars and scales. C must be a valid color (see Section 8.2).

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.

width:P: Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. P must be a valid screen distance (see Section 8.6).