7.4 Dropdownlistbox widget

local L D Desc=lr(label(handle:L) dropdownlistbox(init:[1 2 3 4 5 6] handle:D action:proc{$} {L set({List.nth {D get($)} {D get(firstselection:$)}})} end))in {{QTk.build Desc} show}end

A dropdownlistbox is a widget that displays a button with a down arrow. Clicking this button pops down a listbox allowing the user to select one of the displayed items. The listbox can ben pulled down either at the left or at the right of the button. Usually a label or an entry is placed at the left of the dropdownlistbox. The user can change the contents of that widget by selecting an item in the listbox.

A dropdownlistbox is a just a button and a listbox linked together. All parameters that begin by button configure the button part of the widget while the remaining parameters configure the listbox part of the widget. See these specific widgets for more details.

Indices

Many of the widget methods for listboxes take one or more indices as arguments. An index specifies a particular element of the listbox, in any of the following ways:

integer: Specifies the element as a numerical index, where 0 corresponds to the first element in the listbox.
active: Indicates the element that has the location cursor. This element will be displayed with an underline when the listbox has the keyboard focus, and it is specified with the activate widget method.
anchor: Indicates the anchor point for the selection, which is set with the selection anchor method.
end: Indicates the end of the listbox. For some commands this means just after the last element; for other commands it means the last element.
'@'#X#','#Y: Indicates the element that covers the point in the listbox window specified by X and Y (in pixel coordinates). If no element covers that point, then the closest element to that point is used.

7.4.2 Parameter List

Specific Parameters

1 action actionh buttonactivebackground buttonactiveforeground buttonbackground buttondefault buttondisabledforeground buttonforeground buttonhighlightbackground buttonhighlightcolor buttonhighlightthickness buttontakefocus firstselection height init reload return selection selectmode state width

Non Specific Parameters

background borderwidth cursor exportselection feature font glue handle highlightbackground highlightcolor highlightthickness look lrscrollbar onCreation padx pady relief scrollwidth selectbackground selectborderwidth selectforeground setgrid takefocus tdscrollbar tooltips

7.4.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 inthe stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). IfW is specified then it must be a handle to another widget that is either a sibling of this widget or thedescendant of a sibling of this widget. In this case the 'raise' command will insert this widget into the stacking orderjust above W; this could end up either raisingor lowering the widget.

activate

activate(I): Sets the active element to the one indicated by I. The active element is drawn with an underline when the widget has the input focus.

bbox

bbox(I V): Binds V to a list of four numbers describing the bounding box of the text in the element given by I. 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 text (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the element given by index is visible on the screen then the result is an empty list; if the element is partially visible, the result gives the full area of the element, including any parts that are not visible.

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.

delete

delete(I ?J): Deletes one or more elements of the listbox. I and J are indices specifying the first and last elements in the range to delete. If J isn't specified it defaults to I, i.e. a single element is deleted.

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.

index

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

insert

insert(I LVS): Inserts the list of virtual strings LVS just before the element at position I. If I is the atom end, the list is inserted after all elements.

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 inthe stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). IfW is specified then it must be a handle to another widget that is either a sibling of this widget or thedescendant of a sibling of this widget. In this case the lower command will insert this widget into the stacking orderjust below W; this could end up either raisingor lowering the widget.

nearest

nearest(I V): Given I, a y-coordinate within the listbox window, this command binds V to the index of the (visible) listbox element nearest to that y-coordinate.

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 listboxes. It has two forms, depending on option:

scan(mark X Y): Records X and Y and the listbox'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 Section 8.6).
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.

see

see(I): Adjust the view in the listbox so that the element given by I is visible. If the element is already visible then the command has no effect; if the element is near one edge of the window then the listbox scrolls to bring the element into view at the edge; otherwise the listbox scrolls to center the element.

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 willbe reported to other applications as if the grab had never occurred. A global grablocks out all applications on the screen, so that only the given subtree of the grabbing application will besensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, andwindow 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.

size

size(V): Binds V to an integer indicating the total number of elements in the listbox.

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

1:LVS: Specifies a list of virtual strings that represents the items in the listbox. This parameter can be only used with the set() and get() methods. LVS must be a list of virtual strings.

action

action:C: Specifies an action to execute right after the user changed the selection. 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.

buttonactivebackground

buttonactivebackground:C: Specifies background color for the button 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)

buttonactiveforeground

buttonactiveforeground:C: Specifies foreground color for the button 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)

buttonbackground

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

buttondefault

buttondefault:A: Specifies one of three states for the default ring of the button: normal, active, or disabled. In active state, the button is drawn with the platform specific appearance for a default button. In normal state, the button is drawn with the platform specific appearance for a non-default button, leaving enough space to draw the default button appearance. The normal and active states will result in buttons of the same size. In disabled state, the button is drawn with the non-default button appearance without leaving space for the default appearance. The disabled state may result in a smaller button than the active state ring. A must be one of these three atoms: normal, active, or disabled.

buttondisabledforeground

buttondisabledforeground:C: Specifies foreground color for the button to use when drawing a disabled element. If the option is specified as an empty string (which is typically the case on monochrome displays), disabled elements are drawn with the normal foreground color but they are dimmed by drawing them with a stippled fill pattern. C must be a valid color (see Section 8.2)

buttonforeground

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

buttonhighlightbackground

buttonhighlightbackground:C: Specifies the color for the button 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)

buttonhighlightcolor

buttonhighlightcolor:C: Specifies the color for the button 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)

buttonhighlightthickness

buttonhighlightthickness:P: Specifies a non-negative value indicating the width of the highlight rectangle of the button 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).

buttontakefocus

buttontakefocus:B: Determines whether the button 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 window should be skipped entirely during keyboard traversal. true means that the window should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.

firstselection

firstselection:V: Can be used with the get() method only. Binds V to the number of the first selected item.

height

height:I: Specifies the desired height for the window, in lines. If zero or less, then the desired height for the window is made just large enough to hold all the elements in the listbox. I must be an integer.

init

init:LVS: Specifies a list of virtual strings that represents the items in the listbox. This parameter can be only used at creation time. LVS must be a list of virtual strings.

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)

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

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.

lrscrollbar

lrscrollbar:B: Determines whether the widget has got a horizontal bar below. This option can be specified at creation time only. B must be a boolean.

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.

scrollwidth

scrollwidth:P: Specifies the width of the vertical and horizontal scrollbars. P must be a valid screen distance (see Section 8.6)

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

setgrid

setgrid:B: Determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the setgrid option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. B must be a boolean.

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.

tdscrollbar

tdscrollbar:B: Determines whether the widget has got a vertical bar at the right. This option can be specified at creation time only. 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.

reload

reload:V: This parameter can be only used with the get() method and returns a list of virtual strings that represents the contents of the listbox. This is the same as the 1 option except that it is slower. However if you use weird methods for modifying the contents of the list (using the tk method for example) and bypassing the methods described here, you may find cases where you need to use the reload parameter to resynchronize the states of Tk and QTk.

return

return:V: When the window is closed, V is bound to a list of virtual strings representing the items in the listbox. V must be a free variable.

selection

selection:LB: Specifies a list of booleans. This list contains as many booleans as there are items in the listbox. For each item, the corresponding boolean in the list is true if the item is selected, false otherwise. LB must be a list of booleans.

selectmode

selectmode:A: Specifies one of several styles for manipulating the selection. The value of A may be arbitrary, but the default bindings expect it to be either one of the following atoms: single, browse, multiple, or extended; the default value is browse.

state

state:A: Specifies one of three states for the button: normal, active, or disabled. In normal state the button is displayed using the foreground and background options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the activeforeground and activebackground options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledforeground and background options determine how the button is displayed. A must be one of these three atoms: normal, active, or disabled.

width

width:I: Specifies the desired width for the window in characters. If the font doesn't have a uniform width then the width of the character 0 is used in translating from character units to screen units. If zero or less, then the desired width for the window is made just large enough to hold all the elements in the listbox. I must be an integer.