Bwidget Source Code
Artifact [5e74423307]
Not logged in

Artifact 5e74423307dbf7601c019c13e4a3c0e568180c22:


<HTML>
<HEAD><TITLE>ComboBox</TITLE></HEAD>
<BODY BGCOLOR=white>
<DL><DT><I><A HREF="#descr">NAME</A></I></DT>
<DD><B>ComboBox</B>
 - ComboBox widget
</DD></DL>
<DL>
<DT><I>CREATION</I></DT>
<DD><A HREF="#descr"><B>ComboBox</B></A> <I>pathName</I> ?<I>option value...</I>?</DD>
</DL>
<DL>
<DT><I><A HREF="ArrowButton.html">OPTIONS from <B>ArrowButton</B></A></I></DT>
<DD><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0>
<TR>
<TD>&nbsp;&nbsp;-background or -bg</TD>
<TD>&nbsp;&nbsp;-disabledforeground</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-foreground or -fg</TD>
<TD>&nbsp;&nbsp;-state</TD>
</TR>
</TABLE></DD>
</DL>
<DL>
<DT><I><A HREF="Entry.html">OPTIONS from <B>Entry</B></A></I></DT>
<DD><TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0>
<TR>
<TD>&nbsp;&nbsp;-command</TD>
<TD>&nbsp;&nbsp;-disabledforeground</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-dragenabled</TD>
<TD>&nbsp;&nbsp;-dragendcmd</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-dragevent</TD>
<TD>&nbsp;&nbsp;-draginitcmd</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-dragtype</TD>
<TD>&nbsp;&nbsp;-dropcmd</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-dropenabled</TD>
<TD>&nbsp;&nbsp;-dropovercmd</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-droptypes</TD>
<TD>&nbsp;&nbsp;-editable</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-entrybg (see <B>-background</B>)</TD>
<TD>&nbsp;&nbsp;-entryfg (see <B>-foreground</B>)</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-exportselection</TD>
<TD>&nbsp;&nbsp;-font</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-helptext</TD>
<TD>&nbsp;&nbsp;-helptype</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-helpvar</TD>
<TD>&nbsp;&nbsp;-highlightbackground</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-highlightcolor</TD>
<TD>&nbsp;&nbsp;-highlightthickness</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-insertbackground</TD>
<TD>&nbsp;&nbsp;-insertborderwidth</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-insertofftime</TD>
<TD>&nbsp;&nbsp;-insertontime</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-insertwidth</TD>
<TD>&nbsp;&nbsp;-justify</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-selectbackground</TD>
<TD>&nbsp;&nbsp;-selectborderwidth</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-selectforeground</TD>
<TD>&nbsp;&nbsp;-show</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-state</TD>
<TD>&nbsp;&nbsp;-takefocus</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-text</TD>
<TD>&nbsp;&nbsp;-textvariable</TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;-width</TD>
<TD>&nbsp;&nbsp;-xscrollcommand</TD>
</TR>
</TABLE></DD>
</DL>
<DL>
<DT><I><A HREF="#wso">WIDGET-SPECIFIC OPTIONS</A></I></DT>
<DD><TABLE CELLSPACING=0 CELLSPACING=0 BORDER=0>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-autocomplete">-autocomplete</A></TD>
<TD>&nbsp;&nbsp;<A HREF="#-autopost">-autopost</A></TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-bwlistbox">-bwlistbox</A></TD>
<TD>&nbsp;&nbsp;<A HREF="#-expand">-expand</A></TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-height">-height</A></TD>
<TD>&nbsp;&nbsp;<A HREF="#-hottrack">-hottrack</A></TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-images">-images</A></TD>
<TD>&nbsp;&nbsp;<A HREF="#-listboxwidth">-listboxwidth</A></TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-modifycmd">-modifycmd</A></TD>
<TD>&nbsp;&nbsp;<A HREF="#-postcommand">-postcommand</A></TD>
</TR>
<TR>
<TD>&nbsp;&nbsp;<A HREF="#-values">-values</A></TD>
</TR>
</TABLE></DD>
</DL>
<DL>
<DT><I><A HREF="#wc">WIDGET COMMAND</A></I></DT>
<DD><I>pathName</I> <A HREF="#bind"><B>bind</B></A>
 ?<I>arg...</I>?
</DD>
<DD><I>pathName</I> <A HREF="#cget"><B>cget</B></A>
 <I>option</I>
</DD>
<DD><I>pathName</I> <A HREF="#clearvalue"><B>clearvalue</B></A>
</DD>
<DD><I>pathName</I> <A HREF="#configure"><B>configure</B></A>
 ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...?
</DD>
<DD><I>pathName</I> <A HREF="#get"><B>get</B></A></DD>
<DD><I>pathName</I> <A HREF="#getentry"><B>getentry</B></A></DD>
<DD><I>pathName</I> <A HREF="#getlistbox"><B>getlistbox</B></A></DD>
<DD><I>pathName</I> <A HREF="#getvalue"><B>getvalue</B></A></DD>
<DD><I>pathName</I> <A HREF="#icursor"><B>icursor</B></A>
<I>index</I>
</DD>
<DD><I>pathName</I> <A HREF="#post"><B>post</B></A></DD>
<DD><I>pathName</I> <A HREF="#setvalue"><B>setvalue</B></A>
 <I>index</I>
</DD>
<DD><I>pathName</I> <A HREF="#unpost"><B>unpost</B></A></DD>
</DL>
<BR><HR WIDTH="100%"><BR>
<B><A NAME="descr"></A>DESCRIPTION</B><BR>
<P>

ComboBox widget enables the user to select a value among a list given by
the <B>values</B> option.  The list of possible values can be popped by
pressing the ArrowButton or by clicking in the entry when <B>editable</B>
value of the ComboBox is <B>false</B>.<BR> If <B>editable</B> value of the
ComboBox is <B>true</B> and the entry has the focus, the user can press the
top and bottom arrow keys to modify its value. If the current value exactly
match a value in the list, then the previous (for top arrow key) or then
next (for bottom arrow key) value in the list is displayed.  If the current
value match the beginning of a value in the list, then this value is
displayed.  If the current value doesnt match anything, then the first
value is displayed.

</P>
<BR><HR WIDTH="50%"><BR>
<B><A NAME="wso">WIDGET-SPECIFIC OPTIONS</A></B><BR>
<DL>
    <DT><A NAME="-autocomplete"><B>-autocomplete</B></A></DT>
    <DD>
    Specifies whether or not the combobox should attempt to auto-complete
    the value in the entry field as the user types.  If true, the combobox
    will fill in a value that it finds in its value list as the user types
    into the entry.
    </DD>
</DL>

<DL>
    <DT><A NAME="-autopost"><B>-autopost</B></A></DT>
    <DD>
    Specifies whether or not the combobox should post the drop down as
    the user types.  If true, the combobox will post and scroll to the
    entry that most closely matches the user entry.
    </DD>
</DL>

<DL>
    <DT><A NAME="-bwlistbox"><B>-bwlistbox</B></A></DT>
    <DD>
    Specifies that the combobox should use a BWidget listbox in its drop
    down instead of the standard Tk option.  This option is enabled by
    default if the <b>-images</b> option is not empty.
    </DD>
</DL>

<DL><DT><A NAME="-expand"><B>-expand</B></A></DT>
<DD>

Specifies the value expansion behavior for the window. It must be
<B>none</B> (default) or <B>tab</B>. If <B>tab</B> is specified, then
a Tab binding is added to attempt to expand the current value based on
the other values in <B>-values</B>.
</DD>
</DL>

<DL><DT><A NAME="-height"><B>-height</B></A></DT>
<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.
</DD>

<DL>
    <DT><A NAME="-hottrack"><B>-hottrack</B></A></DT>
    <DD>
    The selection in the drop down listbox will follow the mouse cursor
    as it moves.
    </DD>
</DL>

<DL>
    <DT><A NAME="-images"><B>-images</B></A></DT>
    <DD>
    A list of images that correspond to the <b>-values</b> option.  Each
    image will be drawn next to its value in the drop down.  This option
    enables the <b>-bwlistbox</b> by default as it is needed to display
    images.
    </DD>
</DL>

<DL>
    <DT><A NAME="-listboxwidth"><B>-listboxwidth</B></A></DT>
    <DD>
    Specifies the width of the listbox in the drop down.  Defaults to the
    same size as the combobox.
    </DD>
</DL>

</DL>
<DL><DT><A NAME="-modifycmd"><B>-modifycmd</B></A></DT>
<DD>

Specifies a Tcl command called when the user modify the value of the ComboBox by selecting it in the listbox or pressing arrow key.
</DD>
</DL>
<DL><DT><A NAME="-postcommand"><B>-postcommand</B></A></DT>
<DD>

Specifies a Tcl command called before the listbox of the ComboBox is mapped.
</DD>
</DL>
<DL><DT><A NAME="-values"><B>-values</B></A></DT>
<DD>

Specifies the values to display in the listbox of the ComboBox.
</DD>
</DL>
<HR WIDTH="50%"><BR>
<B><A NAME="wc">WIDGET COMMAND</A></B><BR>
<DL><DT><A NAME="bind"><I>pathName</I> <B>bind</B></A>
 ?<I>arg...</I>?
</DT><DD>

Set bindings on the entry widget.

</DD></DL>
<DL><DT><A NAME="cget"><I>pathName</I> <B>cget</B></A>
 <I>option</I>
</DT><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 creation command.

</DD></DL>

<DL><DT><A NAME="clearvalue"><I>pathName</I> <B>clearvalue</B></A>
</DT><DD>

Clears the current text of the ComboBox.

</DD></DL>

<DL><DT><A NAME="configure"><I>pathName</I> <B>configure</B></A>
 ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...?
</DT><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>.  If <I>option</I> is specified with no
<I>value</I>, then the command returns a list describing the one named
<I>option</I> (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 creation command.  Read-only options are not be modified.

</DD></DL>

<DL><DT><A NAME="get"><I>pathName</I> <B>get</B></A>
</DT><DD>

Returns the current contents of the entry.

</DD></DL>

<DL><DT><A NAME="getentry"><I>pathName</I> <B>getentry</B></A>
</DT><DD>

Returns the path to the contained entry widget.

</DD></DL>

<DL><DT><A NAME="getlistbox"><I>pathName</I> <B>getlistbox</B></A>
</DT><DD>

Returns the path to the listbox in the drop down.

</DD></DL>

<DL><DT><A NAME="getvalue"><I>pathName</I> <B>getvalue</B></A>
</DT><DD>

Returns the index of the current text of the ComboBox in the list of values,
or -1 if it doesn't match any value.

</DD></DL>

<DL><DT><A NAME="icursor"><I>pathName</I> <B>icursor</B></A>
 <I>index</I>
</DT><DD>

Arrange for the insertion cursor to be displayed just before the
character given by <i>index</i>.  Returns an empty string.

</DD></DL>

<DL><DT><A NAME="post"><I>pathName</I> <B>post</B></A>
</DT><DD>

Post the drop down.

</DD></DL>

<DL><DT><A NAME="setvalue"><I>pathName</I> <B>setvalue</B></A>
 <I>index</I>
</DT><DD>

Set the text of the ComboBox to the value indicated by <I>index</I> in the list of values.
<I>index</I> may be specified in any of the following forms:
<P>
<DL COMPACT>
<DT>
<B>last</B>
<DD>
Specifies the last element of the list of values.
<DT><B>first</B>
<DD>
Specifies the first element of the list of values.
<DT>
<B>next</B>
<DD>
Specifies the element following the current (ie returned by <B>getvalue</B>) in the list
of values.
<DT><B>previous</B>
<DD>
Specifies the element preceding the current (ie returned by <B>getvalue</B>) in the list
of values.
<DT>
@<I>number</I>
<DD>
Specifies the integer index in the list of values.
</DL>

</DD></DL>

<DL><DT><A NAME="unpost"><I>pathName</I> <B>unpost</B></A>
</DT><DD>

Unpost the drop down.

</DD></DL>

<HR><BR><B>BINDINGS</B><BR><BR>

When Entry of the ComboBox has the input focus, it has the following bindings, in addition
to the default Entry bindings:
<UL>
<LI>Page up set the value of the ComboBox to the first value.
<LI>Page down set the value of the ComboBox to the last value.
<LI>Arrow up set the value of the ComboBox to the previous value.
<LI>Arrow down set the value of the ComboBox to the next value.
<LI>If <B>-autopost</B> is enabled, Escape unposts the listbox.
</UL>
If the listbox is not mapped and ComboBox is not editable or disabled,
mouse button 1 on the Entry cause the listbox to popup, as if the user press the ArrowButton.

</BODY></HTML>