combobox::combobox - Create and manipulate dropdown combobox widgets
package require combobox ?2.0?
combobox::combobox pathName ?options?
combobox
-background -borderwidth -cursor -font -foreground -height -highlightthickness -highlightbackground -highlightcolor -maxheight -relief -selectbackground -selectborderwidth -selectforeground -state -textvariable -xscrollcommand
See the options manual entry for detailed descriptions of the above options.
Command-Line Name: -command
Database Name: command
Database Class: Command
Defines a command to be run whenver the user selects a value from the dropdown list box. If the combobox is editable, the command will also be called whenever the user presses return or the widget loses the keyboard focus and the value has changed. The command will have two values appended to it: the name of the window and the new value of the combobox. The value is considered to have changed if it differs from the value when the entry first gained focus, or since the last time the command was called.
It is important to note that if the combobox has an associated -textvariable, the command will not be called if the value of the variable is changed external to the combobox.
Command-Line Name: -commandstate
Database Name: commandState
Database Class: State
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
Database Name: editable
Database Class: 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
Database Name: height
Database Class: Height
Specifies the hight of the dropdown list, 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
Database Name: image
Database Class: 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
Database Name: maxHeight
Database Class: Height
Sets the maximum height of the dropdown list, 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 list will be as large as the total number of items in the list. The maxheight defaults to 10.
Command-Line Name: -value
Database Name: value
Database Class: Value
Specifies the value for the combobox.
Command-Line Name: -width
Database Name: width
Database Class: 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 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.
Returns the index of the dropdown list item that matches the value of the combobox, or -1 if the combobox is editable and the string doesn't match a value in the list.
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 manipulate the items in the dropdown list. It has several forms, depending on option:
Deletes one or more elements of the dropdown list. 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 element is deleted.
If last is omitted, returns the contents of the dropdown list 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 dropdown list elements between first and last, inclusive. Both first and last may have any of the standard forms for indices.
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 dropdown list (not the index of the last 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.
Returns a decimal string indicating the total number of elements in the dropdown list.
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.
Selects the item in the dropdown list represented by index and makes that the current value of the combobox.
(to be filled in later; its the same as for an entry widget)
This command returns a list of internal widget names if given no arguments, or returns the internal widget path for the widget identified by name.
This command is used to query and change the horizontal position of the text in the widget's window. It can take any of the following forms:
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 entry'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.
Adjusts the view in the window so that the character given by index is displayed at the left edge of the window.
Adjusts the view in the window so that the character fraction of the way through the text appears at the left edge of the window. Fraction must be a fraction between 0 and 1.
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 average-width characters 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.
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.
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 list is visible. That, or get a better window manager.