Combobox::combobox - Create and manipulate dropdown combobox widgets
package require combobox ?1.06?
combobox::combobox pathName ?options?
combobox
-background -borderwidth -cursor -font -foreground -height -highlightthickness -highlightbackground -maxheight -relief -selectbackground -selectborderwidth -selectforeground -state -textvariable
See the options manual entry for detailed descriptions of the above options.
Command-Line Name: -command
Defines a command to be run whenver the value of the combobox changes. The command will have two values appended to it: the name of the window and the new value of the combobox.
Command-Line Name: -commandstate
One of ``normal'' or ``disabled''. If set to ``disabled'', the value of the -command option will not be evaluated when the value of the combobox changes.
Command-Line Name: -editable
A boolean value which specifies whether the entry widget of the combobox can be typed in. If false, values may only be set by selecting them from the dropdown list.
Command-Line Name: -height
Specifies the hight of the dropdown listbox, in number of lines. A value of zero will make the dropdown list just tall enough to hold all of the elements in the list. The height defaults to 10.
Command-Line Name: -image
Defines an image to use on the button used to drop down the list. If it is not specified it defaults to a small black triangle.
Command-Line Name: -maxheight
Sets the maximum height of the dropdown listbox, in the event -height is set to zero and there are a large number of items in the list. If this value is set to 0 (zero) the listbox will be as large as the total number of items in the listbox. The maxheight defaults to 10.
Command-Line Name: -value
Specifies the value for the combobox.
Command-Line Name: -width
Specifies an integer value indicating the desired width of the combobox entry widget, in average size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text.
The combobox command creates a new window (given by the pathName argument) and makes it into a dropdown combobox widget. Additional options, described above, may be specified on the command line. Currently no option database support is provided. The combobox command returns its pathName arguument. At the time this command is invoked, there must not exists a window named pathName, but pathName's parent must exist.
A combobox is a widget that displays a one-line text string, and allows that string to be edited or selected from a dropdown list. When first created a combobox's value is the null string unless a variable is associated with the widget using the i<-textvariable> option, in which case it will be the value stored in the associated variable.
The combobox entry wiget is capable of displaying strings that are too long to fit entirely within the widget's window. In this case only a portion of the string will be displayed; commands described below may be used to change the view in the window. Comboboxes use the standard xscrollcommand mechanism for interacting with scrollbars (see the description of the xscrollcommand option for details). They also support scanning, as described below.
The combobox 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.
Many of the widget commands take one or more indicies as arguments. For list commands the indicies may take one of the forms acceptable to the standard listbox command. For all other commands the indicies may take the form of an indicie for a standard entry widget. See the appropriate man pages for more information.
The following commands are possible for combobox widgets:
Returns a list of four numbers describing the bounding box of the characters 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 character (in pixels relative to the widget) and the last two elements give the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window.
Returns the current value for the configuration option give by option. Option may have any of the values accepted by the combobox command.
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName, though not in the same format as describe in Tk_ConfigureInfo. The format will be a list, where each element will be a list of two values: an option name and the current value.
If option is specified with no value, 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
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 entry command.
Delete one or more elements from the combobox entry widget. First is the index of the first character to delete, and last is the index of the character just after the last one to delete. If last isn't specified it defaults to first+1, i.e. a single character is deleted. This command returns an empty string.
Returns the combobox's string.
Arrange for the insertion cursor to be displayed just before the character given by index. Returns an empty string.
Returns the numerical index corresponding to index
Insert the characters of string just before the character indicated by index. Returns an empty string.
This command is used to implement scanning on the combobox entry widget. It has two forms, depending on option:
Records x and the current view in the entry 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.
This command computes the difference between its x argument and the x argument to the last scan mark command for the widget. It then adjusts the view left or right by 10 times the difference in x-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the entry at high speed through the window. The return value is an empty string.
(to be filled in later; its the same as for an entry widget)
(to be filled in later; its the same as for an entry widget)
Bindings in the entry widget of the combobox are the same as for normal entry widgets, with the following exceptions:
Double-clicking mouse button 1 over the entry widget will display the dropdown list if it is not displayed, and hide it if it is. The value of the combobox won't change.
If -editable is set to false, single-clicking mouse button 1 over the entry widget will display the dropdown list if it is not displayed, and hide it if it is. The value of the combobox won't change.
Pressing the Up, Down, Next and Prior buttons (up arrow, down arrow, page up and page down, respectively) will display the dropdown list if it is not displayed. If it is displayed, these buttons will change the current selection on the list.
If -editable is true, pressing the Return or Tabkey will set the value to the string in the entry widget. However, if the list is displayed and an item is selected, Return will set the value of the combox to the selected item.
If -editable is false, pressing the Return key when the list is displayed will result in the value of the combobox changing to the currently highlighted item in the list. The list will be closed.
Pressing the escape key when the list is displayed will result in the list being closed without changing the value of the combobox.
Clicking the mouse button over an element in the dropdown list will cause the clicked-on item to be the new value of the combobox, and the list will be closed.
If the combobox is disabled using the -state option, then the entry widget's view can still be adjusted and text in the entry can be selected, but no insertion cursor will be displayed, no text modification will be possible, and the list cannot be displayed.
With some window managers it may be possible to move the window that contains the combobox while the dropdown list is visible. In such a case the dropdown list will stay where it originally appeared. Well behaved window managers shouldn't let you move the window while the list is displayed.
It has been reported that with some virtual window managers, switching to a new virtual window while the dropdown list is visible will result in the dropdown list appearing by itself in the new virtual window.
So the lesson here is: don't dork with your windows while the dropdown listbox is visible. That, or get a better window manager.