listbox(n)
_________________________________________________________________
NAME
listbox - Create and manipulate listbox widgets
SYNOPSIS
listbox pathName ?options?
STANDARD OPTIONS
-background -foreground -relief -takefocus
-borderwidth -height -selectbackground-width
-cursor -highlightbackground -selectborderwidth-xscrollcommand
-exportselection -highlightcolor -selectforeground-yscrollcommand
-font -highlightthickness -setgrid
See the options manual entry for details on the standard
options.
WIDGET-SPECIFIC OPTIONS
Command-Line Name:-height
Database Name: height
Database Class: Height
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.
Command-Line Name:-selectmode
Database Name: selectMode
Database Class: SelectMode
Specifies one of several styles for manipulating
the selection. The value of the option may be
arbitrary, but the default bindings expect it to be
either single, browse, multiple, or extended; the
default value is browse.
Command-Line Name:-width
Database Name: width
Database Class: Width
Specifies the desired width for the window in char-
acters. 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.
_________________________________________________________________
DESCRIPTION
The listbox command creates a new window (given by the
pathName argument) and makes it into a listbox widget.
Additional options, described above, may be specified on
the command line or in the option database to configure
aspects of the listbox such as its colors, font, text, and
relief. The listbox command returns its pathName argu-
ment. At the time this command is invoked, there must not
exist a window named pathName, but pathName's parent must
exist.
A listbox is a widget that displays a list of strings, one
per line. When first created, a new listbox has no ele-
ments. Elements may be added or deleted using widget com-
mands described below. In addition, one or more elements
may be selected as described below. If a listbox is
exporting its selection (see exportSelection option), then
it will observe the standard X11 protocols for handling
the selection. Listbox selections are available as type
STRING; the value of the selection will be the text of the
selected elements, with newlines separating the elements.
It is not necessary for all the elements to be displayed
in the listbox window at once; commands described below
may be used to change the view in the window. Listboxes
allow scrolling in both directions using the standard
xScrollCommand and yScrollCommand options. They also sup-
port scanning, as described below.
INDICES
Many of the widget commands for listboxes take one or more
indices as arguments. An index specifies a particular
element of the listbox, in any of the following ways:
number 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 command.
anchor Indicates the anchor point for the selection,
which is set with the selection anchor widget
command.
end Indicates the end of the listbox. For most |
commands this refers to the last element in |
the listbox, but for a few commands such as |
index and insert it refers to the element just |
after the last one.
@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.
In the widget command descriptions below, arguments named
index, first, and last always contain text indices in one
of the above forms.
WIDGET COMMAND
The listbox command creates a new Tcl command whose name
is pathName. This command may be used to invoke various
operations on the widget. It has the following general
form:
pathName option ?arg arg ...?
Option and the args determine the exact behavior of the
command. The following commands are possible for listbox
widgets:
pathName activate index
Sets the active element to the one indicated by
index. If index is outside the range of elements |
in the listbox then the closest element is acti- |
vated. The active element is drawn with an under-
line when the widget has the input focus, and its
index may be retrieved with the index active.
pathName bbox index
Returns a list of four numbers describing the
bounding box of the text in the element 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 text (specified in pix-
els relative to the widget) and the last two ele-
ments give the width and height of the area, in
pixels. If no part of the element given by index
is visible on the screen, or if index refers to a |
non-existent element, then the result is an empty
string; if the element is partially visible, the
result gives the full area of the element, includ-
ing any parts that are not visible.
pathName cget option
Returns the current value of the configuration
option given by option. Option may have any of the
values accepted by the listbox command.
pathName 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 path-
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ-
ing the one named option (this list will be identi-
cal 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 listbox command.
pathName curselection
Returns a list containing the numerical indices of
all of the elements in the listbox that are cur-
rently selected. If there are no elements selected
in the listbox then an empty string is returned.
pathName delete first ?last?
Deletes one or more elements of the listbox. First
and last are indices specifying the first and last
elements in the range to delete. If last isn't
specified it defaults to first, i.e. a single ele-
ment is deleted.
pathName get first ?last?
If last is omitted, returns the contents of the
listbox element indicated by first, or an empty |
string if first refers to a non-existent element.
If last is specified, the command returns a list
whose elements are all of the listbox elements
between first and last, inclusive. Both first and
last may have any of the standard forms for
indices.
pathName index index
Returns the integer index value that corresponds to
index. If index is end the return value is a count |
of the number of elements in the listbox (not the |
index of the last element).
pathName insert index ?element element ...?
Inserts zero or more new elements in the list just
before the element given by index. If index is
specified as end then the new elements are added to
the end of the list. Returns an empty string.
pathName nearest y
Given a y-coordinate within the listbox window,
this command returns the index of the (visible)
listbox element nearest to that y-coordinate.
pathName scan option args
This command is used to implement scanning on list-
boxes. It has two forms, depending on option:
pathName scan mark x y
Records x and y and the current view in the
listbox 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.
pathName scan dragto x y.
This command computes the difference between
its x and y arguments and the x and y argu-
ments 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 list at high speed
through the window. The return value is an
empty string.
pathName see index
Adjust the view in the listbox so that the element
given by index 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.
pathName selection option arg
This command is used to adjust the selection within
a listbox. It has several forms, depending on
option:
pathName selection anchor index
Sets the selection anchor to the element
given by index. If index refers to a non- |
existent element, then the closest element |
is used. The selection anchor is the end of
the selection that is fixed while dragging
out a selection with the mouse. The index
anchor may be used to refer to the anchor
element.
pathName selection clear first ?last?
If any of the elements between first and
last (inclusive) are selected, they are des-
elected. The selection state is not changed
for elements outside this range.
pathName selection includes index
Returns 1 if the element indicated by index
is currently selected, 0 if it isn't.
pathName selection set first ?last?
Selects all of the elements in the range
between first and last, inclusive, without
affecting the selection state of elements
outside that range.
pathName size
Returns a decimal string indicating the total num-
ber of elements in the listbox.
pathName xview args
This command is used to query and change the hori-
zontal position of the information in the widget's
window. It can take any of the following forms:
pathName xview
Returns a list containing two elements.
Each element is a real fraction between 0
and 1; together they describe the horizon-
tal span that is visible in the window. For
example, if the first element is .2 and the
second element is .6, 20% of the listbox'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.
pathName xview index
Adjusts the view in the window so that the
character position given by index is dis-
played at the left edge of the window.
Character positions are defined by the width
of the character 0.
pathName xview moveto fraction
Adjusts the view in the window so that frac-
tion of the total width of the listbox text
is off-screen to the left. fraction must be
a fraction between 0 and 1.
pathName xview scroll 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 character
units (the width of the 0 character) 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.
pathName yview ?args?
This command is used to query and change the verti-
cal position of the text in the widget's window.
It can take any of the following forms:
pathName yview
Returns a list containing two elements, both
of which are real fractions between 0 and 1.
The first element gives the position of the
listbox element at the top of the window,
relative to the listbox as a whole (0.5
means it is halfway through the listbox, for
example). The second element gives the
position of the listbox element just after
the last one in the window, relative to the
listbox as a whole. These are the same val-
ues passed to scrollbars via the -yscroll-
command option.
pathName yview index
Adjusts the view in the window so that the
element given by index is displayed at the
top of the window.
pathName yview moveto fraction
Adjusts the view in the window so that the
element given by fraction appears at the top
of the window. Fraction is a fraction
between 0 and 1; 0 indicates the first ele-
ment in the listbox, 0.33 indicates the ele-
ment one-third the way through the listbox,
and so on.
pathName yview scroll number what
This command adjusts the view in the window
up or down according to number and what.
Number must be an integer. What must be
either units or pages. If what is units,
the view adjusts up or down by number lines;
if it is pages then the view adjusts by num-
ber screenfuls. If number is negative then
earlier elements become visible; if it is
positive then later elements become visible.
DEFAULT BINDINGS
Tk automatically creates class bindings for listboxes that
give them Motif-like behavior. Much of the behavior of a
listbox is determined by its selectMode option, which
selects one of four ways of dealing with the selection.
If the selection mode is single or browse, at most one
element can be selected in the listbox at once. In both
modes, clicking button 1 on an element selects it and des-
elects any other selected item. In browse mode it is also
possible to drag the selection with button 1.
If the selection mode is multiple or extended, any number
of elements may be selected at once, including discontigu-
ous ranges. In multiple mode, clicking button 1 on an
element toggles its selection state without affecting any
other elements. In extended mode, pressing button 1 on an
element selects it, deselects everything else, and sets
the anchor to the element under the mouse; dragging the
mouse with button 1 down extends the selection to include
all the elements between the anchor and the element under
the mouse, inclusive.
Most people will probably want to use browse mode for sin-
gle selections and extended mode for multiple selections;
the other modes appear to be useful only in special situa-
tions.
In addition to the above behavior, the following addi-
tional behavior is defined by the default bindings:
[1] In extended mode, the selected range can be
adjusted by pressing button 1 with the Shift key
down: this modifies the selection to consist of
the elements between the anchor and the element
under the mouse, inclusive. The un-anchored end of
this new selection can also be dragged with the
button down.
[2] In extended mode, pressing button 1 with the Con-
trol key down starts a toggle operation: the anchor
is set to the element under the mouse, and its
selection state is reversed. The selection state
of other elements isn't changed. If the mouse is
dragged with button 1 down, then the selection
state of all elements between the anchor and the
element under the mouse is set to match that of the
anchor element; the selection state of all other
elements remains what it was before the toggle
operation began.
[3] If the mouse leaves the listbox window with button
1 down, the window scrolls away from the mouse,
making information visible that used to be off-
screen on the side of the mouse. The scrolling
continues until the mouse re-enters the window, the
button is released, or the end of the listbox is
reached.
[4] Mouse button 2 may be used for scanning. If it is
pressed and dragged over the listbox, the contents
of the listbox drag at high speed in the direction
the mouse moves.
[5] If the Up or Down key is pressed, the location cur-
sor (active element) moves up or down one element.
If the selection mode is browse or extended then
the new active element is also selected and all
other elements are deselected. In extended mode
the new active element becomes the selection
anchor.
[6] In extended mode, Shift-Up and Shift-Down move the
location cursor (active element) up or down one
element and also extend the selection to that ele-
ment in a fashion similar to dragging with mouse
button 1.
[7] The Left and Right keys scroll the listbox view
left and right by the width of the character 0.
Control-Left and Control-Right scroll the listbox
view left and right by the width of the window.
Control-Prior and Control-Next also scroll left and
right by the width of the window.
[8] The Prior and Next keys scroll the listbox view up
and down by one page (the height of the window).
[9] The Home and End keys scroll the listbox horizon-
tally to the left and right edges, respectively.
[10] Control-Home sets the location cursor to the the
first element in the listbox, selects that element,
and deselects everything else in the listbox.
[11] Control-End sets the location cursor to the the
last element in the listbox, selects that element,
and deselects everything else in the listbox.
[12] In extended mode, Control-Shift-Home extends the
selection to the first element in the listbox and
Control-Shift-End extends the selection to the last
element.
[13] In multiple mode, Control-Shift-Home moves the
location cursor to the first element in the listbox
and Control-Shift-End moves the location cursor to
the last element.
[14] The space and Select keys make a selection at the
location cursor (active element) just as if mouse
button 1 had been pressed over this element.
[15] In extended mode, Control-Shift-space and Shift-
Select extend the selection to the active element
just as if button 1 had been pressed with the Shift
key down.
[16] In extended mode, the Escape key cancels the most
recent selection and restores all the elements in
the selected range to their previous selection
state.
[17] Control-slash selects everything in the widget,
except in single and browse modes, in which case it
selects the active element and deselects everything
else.
[18] Control-backslash deselects everything in the wid-
get, except in browse mode where it has no effect.
[19] The F16 key (labelled Copy on many Sun worksta-
tions) or Meta-w copies the selection in the widget
to the clipboard, if there is a selection.
The behavior of listboxes can be changed by defining new
bindings for individual widgets or by redefining the class
bindings.
KEYWORDS
listbox, widget