612 lines
32 KiB
HTML
612 lines
32 KiB
HTML
|
<HTML><HEAD><TITLE>Tk Built-In Commands - listbox manual page</TITLE></HEAD><BODY>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M2" NAME="L632">NAME</A>
|
||
|
|
<DL><DD>listbox - Create and manipulate listbox widgets</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M3" NAME="L633">SYNOPSIS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><B>listbox</B> <I>pathName </I>?<I>options</I>?
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M4" NAME="L634">STANDARD OPTIONS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="options.htm#M-background">-background or -bg, background, Background</A>
|
||
|
|
<DD><A HREF="options.htm#M-borderwidth">-borderwidth or -bd, borderWidth, BorderWidth</A>
|
||
|
|
<DD><A HREF="options.htm#M-cursor">-cursor, cursor, Cursor</A>
|
||
|
|
<DD><A HREF="options.htm#M-exportselection">-exportselection, exportSelection, ExportSelection</A>
|
||
|
|
<DD><A HREF="options.htm#M-font">-font, font, Font</A>
|
||
|
|
<DD><A HREF="options.htm#M-foreground">-foreground or -fg, foreground, Foreground</A>
|
||
|
|
<DD><A HREF="options.htm#M-height">-height</A>
|
||
|
|
<DD><A HREF="options.htm#M-highlightbackground">-highlightbackground, highlightBackground, HighlightBackground</A>
|
||
|
|
<DD><A HREF="options.htm#M-highlightcolor">-highlightcolor, highlightColor, HighlightColor</A>
|
||
|
|
<DD><A HREF="options.htm#M-highlightthickness">-highlightthickness, highlightThickness, HighlightThickness</A>
|
||
|
|
<DD><A HREF="options.htm#M-listvar">-listvar</A>
|
||
|
|
<DD><A HREF="options.htm#M-relief">-relief, relief, Relief</A>
|
||
|
|
<DD><A HREF="options.htm#M-selectbackground">-selectbackground, selectBackground, Foreground</A>
|
||
|
|
<DD><A HREF="options.htm#M-selectborderwidth">-selectborderwidth, selectBorderWidth, BorderWidth</A>
|
||
|
|
<DD><A HREF="options.htm#M-selectforeground">-selectforeground, selectForeground, Background</A>
|
||
|
|
<DD><A HREF="options.htm#M-setgrid">-setgrid, setGrid, SetGrid</A>
|
||
|
|
<DD><A HREF="options.htm#M-takefocus">-takefocus, takeFocus, TakeFocus</A>
|
||
|
|
<DD><A HREF="options.htm#M-width">-width</A>
|
||
|
|
<DD><A HREF="options.htm#M-xscrollcommand">-xscrollcommand, xScrollCommand, ScrollCommand</A>
|
||
|
|
<DD><A HREF="options.htm#M-yscrollcommand">-yscrollcommand, yScrollCommand, ScrollCommand</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M8" NAME="L638">WIDGET-SPECIFIC OPTIONS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M9" NAME="L639">-height, height, Height</A>
|
||
|
|
<DD><A HREF="listbox.htm#M10" NAME="L640">-listvar, listVariable, Variable</A>
|
||
|
|
<DD><A HREF="listbox.htm#M11" NAME="L641">-selectmode, selectMode, SelectMode</A>
|
||
|
|
<DD><A HREF="listbox.htm#M12" NAME="L642">-width, width, Width</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M13" NAME="L643">DESCRIPTION</A>
|
||
|
|
<DD><A HREF="listbox.htm#M14" NAME="L644">INDICES</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M15" NAME="L645"><I>number</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M16" NAME="L646"><B>active</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M17" NAME="L647"><B>anchor</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M18" NAME="L648"><B>end</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M19" NAME="L649"><B>@</B><I>x</I><B>,</B><I>y</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M20" NAME="L650">WIDGET COMMAND</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M21" NAME="L651"><I>pathName </I><B>activate</B> <I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M22" NAME="L652"><I>pathName </I><B>bbox</B> <I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M23" NAME="L653"><I>pathName </I><B>cget</B> <I>option</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M24" NAME="L654"><I>pathName </I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?</A>
|
||
|
|
<DD><A HREF="listbox.htm#M25" NAME="L655"><I>pathName </I><B>curselection</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M26" NAME="L656"><I>pathName </I><B>delete </B><I>first </I>?<I>last</I>?</A>
|
||
|
|
<DD><A HREF="listbox.htm#M27" NAME="L657"><I>pathName </I><B>get </B><I>first</I> ?<I>last</I>?</A>
|
||
|
|
<DD><A HREF="listbox.htm#M28" NAME="L658"><I>pathName </I><B>index </B><I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M29" NAME="L659"><I>pathName </I><B>insert </B><I>index </I>?<I>element element ...</I>?</A>
|
||
|
|
<DD><A HREF="listbox.htm#M30" NAME="L660"><I>pathName </I><B>itemcget </B><I>index option</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M31" NAME="L661"><I>pathName </I><B>itemconfigure </B><I>index</I> ?<I>option</I>? ?<I>value</I>? ?<I>option value ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M32" NAME="L662"><B>-background </B><I>color</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M33" NAME="L663"><B>-foreground </B><I>color</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M34" NAME="L664"><B>-selectbackground </B><I>color</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M35" NAME="L665"><B>-selectforeground </B><I>color</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M36" NAME="L666"><I>pathName </I><B>nearest </B><I>y</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M37" NAME="L667"><I>pathName </I><B>scan</B> <I>option args</I></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M38" NAME="L668"><I>pathName </I><B>scan mark </B><I>x y</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M39" NAME="L669"><I>pathName </I><B>scan dragto </B><I>x y</I>.</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M40" NAME="L670"><I>pathName </I><B>see </B><I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M41" NAME="L671"><I>pathName </I><B>selection </B><I>option arg</I></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M42" NAME="L672"><I>pathName </I><B>selection anchor </B><I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M43" NAME="L673"><I>pathName </I><B>selection clear </B><I>first </I>?<I>last</I>?</A>
|
||
|
|
<DD><A HREF="listbox.htm#M44" NAME="L674"><I>pathName </I><B>selection includes </B><I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M45" NAME="L675"><I>pathName </I><B>selection set </B><I>first </I>?<I>last</I>?</A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M46" NAME="L676"><I>pathName </I><B>size</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M47" NAME="L677"><I>pathName </I><B>xview </B><I>args</I></A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M48" NAME="L678"><I>pathName </I><B>xview</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M49" NAME="L679"><I>pathName </I><B>xview</B> <I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M50" NAME="L680"><I>pathName </I><B>xview moveto</B><I> fraction</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M51" NAME="L681"><I>pathName </I><B>xview scroll </B><I>number what</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M52" NAME="L682"><I>pathName </I><B>yview </B><I>?args</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="listbox.htm#M53" NAME="L683"><I>pathName </I><B>yview</B></A>
|
||
|
|
<DD><A HREF="listbox.htm#M54" NAME="L684"><I>pathName </I><B>yview</B> <I>index</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M55" NAME="L685"><I>pathName </I><B>yview moveto</B><I> fraction</I></A>
|
||
|
|
<DD><A HREF="listbox.htm#M56" NAME="L686"><I>pathName </I><B>yview scroll </B><I>number what</I></A>
|
||
|
|
</DL>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M57" NAME="L687">DEFAULT BINDINGS</A>
|
||
|
|
<DL>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="listbox.htm#M58" NAME="L688">KEYWORDS</A>
|
||
|
|
</DL><HR>
|
||
|
|
<H3><A NAME="M2">NAME</A></H3>
|
||
|
|
listbox - Create and manipulate listbox widgets
|
||
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||
|
|
<B>listbox</B> <I>pathName </I>?<I>options</I>?<BR>
|
||
|
|
<H3><A NAME="M4">STANDARD OPTIONS</A></H3>
|
||
|
|
<DL>
|
||
|
|
<DT><B><A HREF="options.htm#M-background">-background or -bg, background, Background</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-borderwidth">-borderwidth or -bd, borderWidth, BorderWidth</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-cursor">-cursor, cursor, Cursor</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-exportselection">-exportselection, exportSelection, ExportSelection</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-font">-font, font, Font</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-foreground">-foreground or -fg, foreground, Foreground</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-height">-height</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-highlightbackground">-highlightbackground, highlightBackground, HighlightBackground</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-highlightcolor">-highlightcolor, highlightColor, HighlightColor</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-highlightthickness">-highlightthickness, highlightThickness, HighlightThickness</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-listvar">-listvar</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-relief">-relief, relief, Relief</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-selectbackground">-selectbackground, selectBackground, Foreground</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-selectborderwidth">-selectborderwidth, selectBorderWidth, BorderWidth</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-selectforeground">-selectforeground, selectForeground, Background</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-setgrid">-setgrid, setGrid, SetGrid</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-takefocus">-takefocus, takeFocus, TakeFocus</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-width">-width</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-xscrollcommand">-xscrollcommand, xScrollCommand, ScrollCommand</A></B>
|
||
|
|
<DT><B><A HREF="options.htm#M-yscrollcommand">-yscrollcommand, yScrollCommand, ScrollCommand</A></B>
|
||
|
|
</DL>
|
||
|
|
<H3><A NAME="M8">WIDGET-SPECIFIC OPTIONS</A></H3>
|
||
|
|
<DL>
|
||
|
|
<DT>Command-Line Name: <B><A NAME="M9">-height</A></B>
|
||
|
|
<DT>Database Name: <B>height</B>
|
||
|
|
<DT>Database Class: <B>Height</B>
|
||
|
|
<DD>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.
|
||
|
|
<P><DT>Command-Line Name: <B><A NAME="M10">-listvar</A></B>
|
||
|
|
<DT>Database Name: <B>listVariable</B>
|
||
|
|
<DT>Database Class: <B><A HREF="../TkCmd/variable.htm">Variable</A></B>
|
||
|
|
<DD>Specifies the name of a variable. The value of the variable is a list
|
||
|
|
to be displayed inside the widget; if the variable value changes
|
||
|
|
then the widget will automatically update itself to reflect the new value.
|
||
|
|
Attempts to assign a bad list value to a variable in use as a listvar
|
||
|
|
will cause an error. Attempts to unset a variable in use as a listvar
|
||
|
|
will fail but will not generate an error.
|
||
|
|
<P><DT>Command-Line Name: <B><A NAME="M11">-selectmode</A></B>
|
||
|
|
<DT>Database Name: <B>selectMode</B>
|
||
|
|
<DT>Database Class: <B>SelectMode</B>
|
||
|
|
<DD>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 <B>single</B>, <B>browse</B>, <B>multiple</B>,
|
||
|
|
or <B>extended</B>; the default value is <B>browse</B>.
|
||
|
|
<P><DT>Command-Line Name: <B><A NAME="M12">-width</A></B>
|
||
|
|
<DT>Database Name: <B>width</B>
|
||
|
|
<DT>Database Class: <B>Width</B>
|
||
|
|
<DD>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.
|
||
|
|
</DL>
|
||
|
|
<H3><A NAME="M13">DESCRIPTION</A></H3>
|
||
|
|
The <B>listbox</B> command creates a new window (given by the
|
||
|
|
<I>pathName</I> 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 <B>listbox</B> command returns its
|
||
|
|
<I>pathName</I> argument. At the time this command is invoked,
|
||
|
|
there must not exist a window named <I>pathName</I>, but
|
||
|
|
<I>pathName</I>'s parent must exist.
|
||
|
|
<P>
|
||
|
|
A listbox is a widget that displays a list of strings, one per line.
|
||
|
|
When first created, a new listbox has no elements.
|
||
|
|
Elements may be added or deleted using widget commands described
|
||
|
|
below. In addition, one or more elements may be selected as described
|
||
|
|
below.
|
||
|
|
If a listbox is exporting its selection (see <B>exportSelection</B>
|
||
|
|
option), then it will observe the standard X11 protocols
|
||
|
|
for handling the selection.
|
||
|
|
Listbox selections are available as type <B><A HREF="../TkCmd/string.htm">STRING</A></B>;
|
||
|
|
the value of the selection will be the text of the selected elements, with
|
||
|
|
newlines separating the elements.
|
||
|
|
<P>
|
||
|
|
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 <B>xScrollCommand</B>
|
||
|
|
and <B>yScrollCommand</B> options.
|
||
|
|
They also support scanning, as described below.
|
||
|
|
|
||
|
|
<H3><A NAME="M14">INDICES</A></H3>
|
||
|
|
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:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M15"><I>number</I></A><DD>
|
||
|
|
Specifies the element as a numerical index, where 0 corresponds
|
||
|
|
to the first element in the listbox.
|
||
|
|
<P><DT><A NAME="M16"><B>active</B></A><DD>
|
||
|
|
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 <B>activate</B>
|
||
|
|
widget command.
|
||
|
|
<P><DT><A NAME="M17"><B>anchor</B></A><DD>
|
||
|
|
Indicates the anchor point for the selection, which is set with the
|
||
|
|
<B><A HREF="../TclCmd/selection.htm">selection anchor</A></B> widget command.
|
||
|
|
<P><DT><A NAME="M18"><B>end</B></A><DD>
|
||
|
|
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 <B>index</B> and <B>insert</B>
|
||
|
|
it refers to the element just after the last one.
|
||
|
|
<P><DT><A NAME="M19"><B>@</B><I>x</I><B>,</B><I>y</I></A><DD>
|
||
|
|
Indicates the element that covers the point in the listbox window
|
||
|
|
specified by <I>x</I> and <I>y</I> (in pixel coordinates). If no
|
||
|
|
element covers that point, then the closest element to that
|
||
|
|
point is used.
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
In the widget command descriptions below, arguments named <I>index</I>,
|
||
|
|
<I>first</I>, and <I>last</I> always contain text indices in one of
|
||
|
|
the above forms.
|
||
|
|
|
||
|
|
<H3><A NAME="M20">WIDGET COMMAND</A></H3>
|
||
|
|
The <B>listbox</B> command creates a new Tcl command whose
|
||
|
|
name is <I>pathName</I>. This
|
||
|
|
command may be used to invoke various
|
||
|
|
operations on the widget. It has the following general form:
|
||
|
|
<PRE><I>pathName option </I>?<I>arg arg ...</I>?</PRE>
|
||
|
|
<I>Option</I> and the <I>arg</I>s
|
||
|
|
determine the exact behavior of the command. The following
|
||
|
|
commands are possible for listbox widgets:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M21"><I>pathName </I><B>activate</B> <I>index</I></A><DD>
|
||
|
|
Sets the active element to the one indicated by <I>index</I>.
|
||
|
|
If <I>index</I> is outside the range of elements in the listbox
|
||
|
|
then the closest element is activated.
|
||
|
|
The active element is drawn with an underline when the widget
|
||
|
|
has the input focus, and its index may be retrieved with the
|
||
|
|
index <B>active</B>.
|
||
|
|
<P><DT><A NAME="M22"><I>pathName </I><B>bbox</B> <I>index</I></A><DD>
|
||
|
|
Returns a list of four numbers describing the bounding box of
|
||
|
|
the text in the element given by <I>index</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 <I>index</I> is visible on the
|
||
|
|
screen,
|
||
|
|
or if <I>index</I> 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,
|
||
|
|
including any parts that are not visible.
|
||
|
|
<P><DT><A NAME="M23"><I>pathName </I><B>cget</B> <I>option</I></A><DD>
|
||
|
|
Returns the current value of the configuration option given
|
||
|
|
by <I>option</I>.
|
||
|
|
<I>Option</I> may have any of the values accepted by the <B>listbox</B>
|
||
|
|
command.
|
||
|
|
<P><DT><A NAME="M24"><I>pathName </I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?</A><DD>
|
||
|
|
Query or modify the configuration options of the widget.
|
||
|
|
If no <I>option</I> is specified, returns a list describing all of
|
||
|
|
the available options for <I>pathName</I> (see <B><A HREF="../TclLib/ConfigWidg.htm">Tk_ConfigureInfo</A></B> for
|
||
|
|
information on the format of this list). If <I>option</I> is specified
|
||
|
|
with no <I>value</I>, then the command returns a list describing the
|
||
|
|
one named option (this list will be identical to the corresponding
|
||
|
|
sublist of the value returned if no <I>option</I> is specified). If
|
||
|
|
one or more <I>option-value</I> 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.
|
||
|
|
<I>Option</I> may have any of the values accepted by the <B>listbox</B>
|
||
|
|
command.
|
||
|
|
<P><DT><A NAME="M25"><I>pathName </I><B>curselection</B></A><DD>
|
||
|
|
Returns a list containing the numerical indices of
|
||
|
|
all of the elements in the listbox that are currently selected.
|
||
|
|
If there are no elements selected in the listbox then an empty
|
||
|
|
string is returned.
|
||
|
|
<P><DT><A NAME="M26"><I>pathName </I><B>delete </B><I>first </I>?<I>last</I>?</A><DD>
|
||
|
|
Deletes one or more elements of the listbox. <I>First</I> and <I>last</I>
|
||
|
|
are indices specifying the first and last elements in the range
|
||
|
|
to delete. If <I>last</I> isn't specified it defaults to
|
||
|
|
<I>first</I>, i.e. a single element is deleted.
|
||
|
|
<P><DT><A NAME="M27"><I>pathName </I><B>get </B><I>first</I> ?<I>last</I>?</A><DD>
|
||
|
|
If <I>last</I> is omitted, returns the contents of the listbox
|
||
|
|
element indicated by <I>first</I>,
|
||
|
|
or an empty string if <I>first</I> refers to a non-existent element.
|
||
|
|
If <I>last</I> is specified, the command returns a list whose elements
|
||
|
|
are all of the listbox elements between <I>first</I> and <I>last</I>,
|
||
|
|
inclusive.
|
||
|
|
Both <I>first</I> and <I>last</I> may have any of the standard
|
||
|
|
forms for indices.
|
||
|
|
<P><DT><A NAME="M28"><I>pathName </I><B>index </B><I>index</I></A><DD>
|
||
|
|
Returns the integer index value that corresponds to <I>index</I>.
|
||
|
|
If <I>index</I> is <B>end</B> the return value is a count of the number
|
||
|
|
of elements in the listbox (not the index of the last element).
|
||
|
|
<P><DT><A NAME="M29"><I>pathName </I><B>insert </B><I>index </I>?<I>element element ...</I>?</A><DD>
|
||
|
|
Inserts zero or more new elements in the list just before the
|
||
|
|
element given by <I>index</I>. If <I>index</I> is specified as
|
||
|
|
<B>end</B> then the new elements are added to the end of the
|
||
|
|
list. Returns an empty string.
|
||
|
|
<P><DT><A NAME="M30"><I>pathName </I><B>itemcget </B><I>index option</I></A><DD>
|
||
|
|
Returns the current value of the item configuration option given
|
||
|
|
by <I>option</I>. <I>Option</I> may have any of the values accepted
|
||
|
|
by the <B>listbox itemconfigure</B> command.
|
||
|
|
<P><DT><A NAME="M31"><I>pathName </I><B>itemconfigure </B><I>index</I> ?<I>option</I>? ?<I>value</I>? ?<I>option value ...</I>?</A><DD>
|
||
|
|
Query or modify the configuration options of an item in the listbox.
|
||
|
|
If no <I>option</I> is specified, returns a list describing all of
|
||
|
|
the available options for the item (see <B><A HREF="../TclLib/ConfigWidg.htm">Tk_ConfigureInfo</A></B> for
|
||
|
|
information on the format of this list). If <I>option</I> is specified
|
||
|
|
with no <I>value</I>, then the command returns a list describing the
|
||
|
|
one named option (this list will be identical to the corresponding
|
||
|
|
sublist of the value returned if no <I>option</I> is specified). If
|
||
|
|
one or more <I>option-value</I> 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. The following options
|
||
|
|
are currently supported for items:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M32"><B>-background </B><I>color</I></A><DD>
|
||
|
|
<I>Color</I> specifies the background color to use when displaying the
|
||
|
|
item. It may have any of the forms accepted by <B><A HREF="../TclLib/GetColor.htm">Tk_GetColor</A></B>.
|
||
|
|
<P><DT><A NAME="M33"><B>-foreground </B><I>color</I></A><DD>
|
||
|
|
<I>Color</I> specifies the foreground color to use when displaying the
|
||
|
|
item. It may have any of the forms accepted by <B><A HREF="../TclLib/GetColor.htm">Tk_GetColor</A></B>.
|
||
|
|
<P><DT><A NAME="M34"><B>-selectbackground </B><I>color</I></A><DD>
|
||
|
|
<I>color</I> specifies the background color to use when displaying the
|
||
|
|
item while it is selected. It may have any of the forms accepted by
|
||
|
|
<B><A HREF="../TclLib/GetColor.htm">Tk_GetColor</A></B>.
|
||
|
|
<P><DT><A NAME="M35"><B>-selectforeground </B><I>color</I></A><DD>
|
||
|
|
<I>color</I> specifies the foreground color to use when displaying the
|
||
|
|
item while it is selected. It may have any of the forms accepted by
|
||
|
|
<B><A HREF="../TclLib/GetColor.htm">Tk_GetColor</A></B>.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M36"><I>pathName </I><B>nearest </B><I>y</I></A><DD>
|
||
|
|
Given a y-coordinate within the listbox window, this command returns
|
||
|
|
the index of the (visible) listbox element nearest to that y-coordinate.
|
||
|
|
<P><DT><A NAME="M37"><I>pathName </I><B>scan</B> <I>option args</I></A><DD>
|
||
|
|
This command is used to implement scanning on listboxes. It has
|
||
|
|
two forms, depending on <I>option</I>:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M38"><I>pathName </I><B>scan mark </B><I>x y</I></A><DD>
|
||
|
|
Records <I>x</I> and <I>y</I> and the current view in the listbox
|
||
|
|
window; used in conjunction with later <B>scan dragto</B> commands.
|
||
|
|
Typically this command is associated with a mouse button press in
|
||
|
|
the widget. It returns an empty string.
|
||
|
|
<P><DT><A NAME="M39"><I>pathName </I><B>scan dragto </B><I>x y</I>.</A><DD>
|
||
|
|
This command computes the difference between its <I>x</I> and <I>y</I>
|
||
|
|
arguments and the <I>x</I> and <I>y</I> arguments to the last
|
||
|
|
<B>scan mark</B> 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.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M40"><I>pathName </I><B>see </B><I>index</I></A><DD>
|
||
|
|
Adjust the view in the listbox so that the element given by <I>index</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.
|
||
|
|
<P><DT><A NAME="M41"><I>pathName </I><B>selection </B><I>option arg</I></A><DD>
|
||
|
|
This command is used to adjust the selection within a listbox. It
|
||
|
|
has several forms, depending on <I>option</I>:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M42"><I>pathName </I><B>selection anchor </B><I>index</I></A><DD>
|
||
|
|
Sets the selection anchor to the element given by <I>index</I>.
|
||
|
|
If <I>index</I> 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 <B>anchor</B> may be used to refer to the anchor
|
||
|
|
element.
|
||
|
|
<P><DT><A NAME="M43"><I>pathName </I><B>selection clear </B><I>first </I>?<I>last</I>?</A><DD>
|
||
|
|
If any of the elements between <I>first</I> and <I>last</I>
|
||
|
|
(inclusive) are selected, they are deselected.
|
||
|
|
The selection state is not changed for elements outside
|
||
|
|
this range.
|
||
|
|
<P><DT><A NAME="M44"><I>pathName </I><B>selection includes </B><I>index</I></A><DD>
|
||
|
|
Returns 1 if the element indicated by <I>index</I> is currently
|
||
|
|
selected, 0 if it isn't.
|
||
|
|
<P><DT><A NAME="M45"><I>pathName </I><B>selection set </B><I>first </I>?<I>last</I>?</A><DD>
|
||
|
|
Selects all of the elements in the range between
|
||
|
|
<I>first</I> and <I>last</I>, inclusive, without affecting
|
||
|
|
the selection state of elements outside that range.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M46"><I>pathName </I><B>size</B></A><DD>
|
||
|
|
Returns a decimal string indicating the total number of elements
|
||
|
|
in the listbox.
|
||
|
|
<P><DT><A NAME="M47"><I>pathName </I><B>xview </B><I>args</I></A><DD>
|
||
|
|
This command is used to query and change the horizontal position of the
|
||
|
|
information in the widget's window. It can take any of the following
|
||
|
|
forms:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M48"><I>pathName </I><B>xview</B></A><DD>
|
||
|
|
Returns a list containing two elements.
|
||
|
|
Each element is a real fraction between 0 and 1; together they describe
|
||
|
|
the horizontal 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 <B>-xscrollcommand</B>
|
||
|
|
option.
|
||
|
|
<P><DT><A NAME="M49"><I>pathName </I><B>xview</B> <I>index</I></A><DD>
|
||
|
|
Adjusts the view in the window so that the character position given by
|
||
|
|
<I>index</I> is displayed at the left edge of the window.
|
||
|
|
Character positions are defined by the width of the character <B>0</B>.
|
||
|
|
<P><DT><A NAME="M50"><I>pathName </I><B>xview moveto</B><I> fraction</I></A><DD>
|
||
|
|
Adjusts the view in the window so that <I>fraction</I> of the
|
||
|
|
total width of the listbox text is off-screen to the left.
|
||
|
|
<I>fraction</I> must be a fraction between 0 and 1.
|
||
|
|
<P><DT><A NAME="M51"><I>pathName </I><B>xview scroll </B><I>number what</I></A><DD>
|
||
|
|
This command shifts the view in the window left or right according to
|
||
|
|
<I>number</I> and <I>what</I>.
|
||
|
|
<I>Number</I> must be an integer.
|
||
|
|
<I>What</I> must be either <B>units</B> or <B>pages</B> or an abbreviation
|
||
|
|
of one of these.
|
||
|
|
If <I>what</I> is <B>units</B>, the view adjusts left or right by
|
||
|
|
<I>number</I> character units (the width of the <B>0</B> character)
|
||
|
|
on the display; if it is <B>pages</B> then the view adjusts by
|
||
|
|
<I>number</I> screenfuls.
|
||
|
|
If <I>number</I> is negative then characters farther to the left
|
||
|
|
become visible; if it is positive then characters farther to the right
|
||
|
|
become visible.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M52"><I>pathName </I><B>yview </B><I>?args</I>?</A><DD>
|
||
|
|
This command is used to query and change the vertical position of the
|
||
|
|
text in the widget's window.
|
||
|
|
It can take any of the following forms:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M53"><I>pathName </I><B>yview</B></A><DD>
|
||
|
|
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 values passed to scrollbars via the <B>-yscrollcommand</B>
|
||
|
|
option.
|
||
|
|
<P><DT><A NAME="M54"><I>pathName </I><B>yview</B> <I>index</I></A><DD>
|
||
|
|
Adjusts the view in the window so that the element given by
|
||
|
|
<I>index</I> is displayed at the top of the window.
|
||
|
|
<P><DT><A NAME="M55"><I>pathName </I><B>yview moveto</B><I> fraction</I></A><DD>
|
||
|
|
Adjusts the view in the window so that the element given by <I>fraction</I>
|
||
|
|
appears at the top of the window.
|
||
|
|
<I>Fraction</I> is a fraction between 0 and 1; 0 indicates the first
|
||
|
|
element in the listbox, 0.33 indicates the element one-third the
|
||
|
|
way through the listbox, and so on.
|
||
|
|
<P><DT><A NAME="M56"><I>pathName </I><B>yview scroll </B><I>number what</I></A><DD>
|
||
|
|
This command adjusts the view in the window up or down according to
|
||
|
|
<I>number</I> and <I>what</I>.
|
||
|
|
<I>Number</I> must be an integer.
|
||
|
|
<I>What</I> must be either <B>units</B> or <B>pages</B>.
|
||
|
|
If <I>what</I> is <B>units</B>, the view adjusts up or down by
|
||
|
|
<I>number</I> lines; if it is <B>pages</B> then
|
||
|
|
the view adjusts by <I>number</I> screenfuls.
|
||
|
|
If <I>number</I> is negative then earlier elements
|
||
|
|
become visible; if it is positive then later elements
|
||
|
|
become visible.
|
||
|
|
<P></DL>
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M57">DEFAULT BINDINGS</A></H3>
|
||
|
|
Tk automatically creates class bindings for listboxes that give them
|
||
|
|
Motif-like behavior. Much of the behavior of a listbox is determined
|
||
|
|
by its <B>selectMode</B> option, which selects one of four ways
|
||
|
|
of dealing with the selection.
|
||
|
|
<P>
|
||
|
|
If the selection mode is <B>single</B> or <B>browse</B>, at most one
|
||
|
|
element can be selected in the listbox at once.
|
||
|
|
In both modes, clicking button 1 on an element selects
|
||
|
|
it and deselects any other selected item.
|
||
|
|
In <B>browse</B> mode it is also possible to drag the selection
|
||
|
|
with button 1.
|
||
|
|
<P>
|
||
|
|
If the selection mode is <B>multiple</B> or <B>extended</B>,
|
||
|
|
any number of elements may be selected at once, including discontiguous
|
||
|
|
ranges. In <B>multiple</B> mode, clicking button 1 on an element
|
||
|
|
toggles its selection state without affecting any other elements.
|
||
|
|
In <B>extended</B> 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.
|
||
|
|
<P>
|
||
|
|
Most people will probably want to use <B>browse</B> mode for
|
||
|
|
single selections and <B>extended</B> mode for multiple selections;
|
||
|
|
the other modes appear to be useful only in special situations.
|
||
|
|
<P>
|
||
|
|
Any time the selection changes in the listbox, the virtual event
|
||
|
|
<B><<ListboxSelect>></B> will be generated. It is easiest to bind
|
||
|
|
to this event to be made aware of any changes to listbox selection.
|
||
|
|
<P>
|
||
|
|
In addition to the above behavior, the following additional behavior
|
||
|
|
is defined by the default bindings:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT>[1]<DD>
|
||
|
|
In <B>extended</B> 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.
|
||
|
|
<P><DT>[2]<DD>
|
||
|
|
In <B>extended</B> mode, pressing button 1 with the Control 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.
|
||
|
|
<P><DT>[3]<DD>
|
||
|
|
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.
|
||
|
|
<P><DT>[4]<DD>
|
||
|
|
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.
|
||
|
|
<P><DT>[5]<DD>
|
||
|
|
If the Up or Down key is pressed, the location cursor (active
|
||
|
|
element) moves up or down one element.
|
||
|
|
If the selection mode is <B>browse</B> or <B>extended</B> then the
|
||
|
|
new active element is also selected and all other elements are
|
||
|
|
deselected.
|
||
|
|
In <B>extended</B> mode the new active element becomes the
|
||
|
|
selection anchor.
|
||
|
|
<P><DT>[6]<DD>
|
||
|
|
In <B>extended</B> mode, Shift-Up and Shift-Down move the location
|
||
|
|
cursor (active element) up or down one element and also extend
|
||
|
|
the selection to that element in a fashion similar to dragging
|
||
|
|
with mouse button 1.
|
||
|
|
<P><DT>[7]<DD>
|
||
|
|
The Left and Right keys scroll the listbox view left and right
|
||
|
|
by the width of the character <B>0</B>.
|
||
|
|
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.
|
||
|
|
<P><DT>[8]<DD>
|
||
|
|
The Prior and Next keys scroll the listbox view up and down
|
||
|
|
by one page (the height of the window).
|
||
|
|
<P><DT>[9]<DD>
|
||
|
|
The Home and End keys scroll the listbox horizontally to
|
||
|
|
the left and right edges, respectively.
|
||
|
|
<P><DT>[10]<DD>
|
||
|
|
Control-Home sets the location cursor to the the first element in
|
||
|
|
the listbox, selects that element, and deselects everything else
|
||
|
|
in the listbox.
|
||
|
|
<P><DT>[11]<DD>
|
||
|
|
Control-End sets the location cursor to the the last element in
|
||
|
|
the listbox, selects that element, and deselects everything else
|
||
|
|
in the listbox.
|
||
|
|
<P><DT>[12]<DD>
|
||
|
|
In <B>extended</B> 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.
|
||
|
|
<P><DT>[13]<DD>
|
||
|
|
In <B>multiple</B> 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.
|
||
|
|
<P><DT>[14]<DD>
|
||
|
|
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.
|
||
|
|
<P><DT>[15]<DD>
|
||
|
|
In <B>extended</B> 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.
|
||
|
|
<P><DT>[16]<DD>
|
||
|
|
In <B>extended</B> mode, the Escape key cancels the most recent
|
||
|
|
selection and restores all the elements in the selected range
|
||
|
|
to their previous selection state.
|
||
|
|
<P><DT>[17]<DD>
|
||
|
|
Control-slash selects everything in the widget, except in
|
||
|
|
<B>single</B> and <B>browse</B> modes, in which case it selects
|
||
|
|
the active element and deselects everything else.
|
||
|
|
<P><DT>[18]<DD>
|
||
|
|
Control-backslash deselects everything in the widget, except in
|
||
|
|
<B>browse</B> mode where it has no effect.
|
||
|
|
<P><DT>[19]<DD>
|
||
|
|
The F16 key (labelled Copy on many Sun workstations) or Meta-w
|
||
|
|
copies the selection in the widget to the clipboard, if there is
|
||
|
|
a selection.
|
||
|
|
|
||
|
|
<P></DL>
|
||
|
|
<P>
|
||
|
|
The behavior of listboxes can be changed by defining new bindings for
|
||
|
|
individual widgets or by redefining the class bindings.
|
||
|
|
|
||
|
|
<H3><A NAME="M58">KEYWORDS</A></H3>
|
||
|
|
<A href="../Keywords/L.htm#listbox">listbox</A>, <A href="../Keywords/W.htm#widget">widget</A>
|
||
|
|
<HR><PRE>
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1990 The Regents of the University of California.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||
|
|
</BODY></HTML>
|