DESCRIPTION

combobox Combobox Megawidget package require combobox 2.3 combobox::combobox pathName options

DESCRIPTION This package provides a new widget named "combobox" which combines an entry widget and a dropdown menu into a single widget.

STANDARD OPTIONS -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.

WIDGET-SPECIFIC OPTIONS -buttonbackground buttonBackground ButtonBackground Defines the background color of the button used to activate the dropdown list. -command command 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. -commandstate commandState State One of "normal" or "disabled". If set to "disabled", the value of the B<-command> option will not be evaluated when the value of the combobox changes. -disabledbackground disabledBackground DisabledBackground Defines the background color for the combobox when it is disabled. -disabledforeground disabledForeground DisabledForeground Defines the foreground color for the combobox when it is disabled. -dropdownwidth dropdownWidth DropdownWidth Defines the width of the dropdown list. If null or 0, the dropdown listbox width will be the same as the always-visible portion of the combobox (ie: the entry and menubutton). Otherwise the value specifies the number of average-sized characters to display in the dropdown listbox. -editable editable 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. -elementborderwidth elementBorderWidth BorderWidth Specifies the width of borders drawn around the internal elements of the widget (the button and the scrollbars for the dropdown list). -height height 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. -image image 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. -listvar listVariable ListVariable Specifies the name of a variable associated with the dropdown listbox. If the variable changes the listbox will automatically update itself to reflect the new value. Attempts to unset a variable in use as a listvar will fail but will not generate an error. -maxheight maxHeight Height Sets the maximum height of the dropdown list, in the event B<-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. -opencommand openCommand Command If this option is specified then it provides a Tcl command to execute each time the combobox is opened (eg: when the dropdown listbox is displayed). The command is invoked by the B<open> widget command before opening the combobox. -value value Value Specifies the value for the combobox. -width width 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.

OVERVIEW 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 -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.

WIDGET COMMAND 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:

pathName bbox index: 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.
pathName cget option: Returns the current value for the configuration option give by option. Option may have any of the values accepted by the combobox command.
pathName close: Causes the dropdown listbox of the widget to be withdrawn if it is currently displayed.
pathName configure option: 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.
pathName curselection: 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.
pathName delete first last: 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.
pathName get: Returns the combobox's string.
pathName icursor index: Arrange for the insertion cursor to be displayed just before the character given by index. Returns an empty string.
pathName index index: Returns the numerical index corresponding to index
pathName insert index string: Insert the characters of string just before the character indicated by index. Returns an empty string.
pathName list option args: This command is used to manipulate the items in the dropdown list. It has several forms, depending on option:

list delete first last

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.

list get first last

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.

list 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 dropdown list (not the index of the last element).

list 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.

list size

Returns a decimal string indicating the total number of elements in the dropdown list.
pathName open: Causes the dropdown listbox of the combobox to be displayed if it is currently hidden.
pathName scan option args: This command is used to implement scanning on the combobox entry widget. It has two forms, depending on option:

pathName scan mark x

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.

pathName scan dragto x

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.
pathName select index: Selects the item in the dropdown list represented by index and makes that the current value of the combobox.
pathName selection option arg: This command is used to adjus the selection within the editable portion of the combobox. It has several forms, depending on option:

pathName selection adjust index

Locate the end of the selection nearest to the character given by idnex (i.e. including but not going beyond index). The other end of the selection is made the anchor point for future select to commands. If the selection isn't currently in the editable portion of the combobox, then a new selection is created to include the characters between index and the most recent selection anchor point, inclusive. Returns an empty string.

pathName selection clear

Clear the selection if it is currently in this widget. If the selection isn't in this widget then the command has no effect. Returns an empty string.

pathname selection from index

Set the selection anchor point to just before the character given by index. Doesn't change the selection. Returns an empty string.

pathname selection parent

Returns 1 if there are characters selected in the editable portion of the combobox, otherwise it returns 0.

pathname selection range start end

Sets the selection to include the characters starting with the one indexed by start and ending with the one just before end. If end refers to the same character as start or an earlier one, then the selection is cleared.

pathname selection to index

If index is before the anchor point, set the selection to the characters from index up to but not including the anchor point. If index is the same as the anchor point, do nothing. If index is after the anchor point, set the selection to the characters from the anchor point up to but not including index. The anchor point is determined by the most recent select from or select adjust command in this widget. If the selection isn't in this widget then a new selection is created using the most recent anchor point specified for the widget. Returns an empty string.
pathName subwidget name: 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.
pathName xview args: 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:

pathName xview

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.

pathName xview index

Adjusts the view in the window so that the character given by index is displayed at the left edge of the window.

pathName xview moveto fraction

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.

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 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.

DEFAULT BINDINGS 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 Tab key will set the value to the string in the entry widget. If the list is displayed and an item is selected, Return will set the value of the combobox 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 with the value of the combobox remaining unchanged.

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.

BUGS 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.