Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

combobox - Tool

	Package	display
	Module	widgets

Postscript file available

A widget for selecting one or more items from a list.

include "combobox.g"

Description

The combobox combines a text entry widget with a popup listbox and a label to provide a handy GUI way to select one or more items from a list. The combobox has an internal data store - a list of strings - and a way to keep track of which of these strings is currently selected. You can think of the listbox as the visual representation of the data store, and the text entry widget as the visual representation of the current selection.

Items in the combobox data store are always strings, so the application must do whatever is necessary to interpret strings as numbers, or file names, or any other application-specific tool. The most common use of the combobox will be for the interactive selection of items by the user in the popup listbox, by using the mouse. The combobox immediately displays these selections in the text extry widget. Users may also edit and type directly into the text entry widget; a carriage return in the text entry widget usually causes the current contents of that widget to be added to the combobox data store (and the listbox) as a new item. The current contents of the text entry widget can be retrieved at any time by a ``getentry ()'' call. The current listbox selection may be retrieved at any time by a ``get('selected')'' call. The entry contents may not be the same as the listbox selection if, for example, the user has edited the entry contents but not yet hit return. The application can choose to retrieve the entry contents at any time and, if necessary, add items to the combobox (and optionally make one of these the current selection).

When the user presses the arrow button which causes the listbox to pop up, the listbox grabs the input focus. The user then usually has only two options: clicking the left mouse button on an item in the listbox, which selects that item and puts it into the combobox entry field, or clicking anywhere else which causes the listbox to be dismissed and nothing to happen. If the combobox has been set to display a clear button through the use of the canclearpopup attribute then the user can also click on the clear button. This clears all of the items from the internal data store as well as clearing the entry before dismissing the listbox. If the listbox has scrollbars, the user can manipulate those.

The combobox emits events through the agent returned by the agent member function. Standard events include ``select'', when the user makes a selection in the combobox or hits return in the entry, causing a new selection, ``return'', when the user hits return in the entry (which also generates a selection if addonreturn is T) and a ``press'', when the user presses the button which displays the listbox. The bind member function can be used to bind any x-event to this same agent.

One limitation in glishtk is that it is impossible to query the true size of an entry widget. The best one can do is query the requested size when the widget was constructed. This makes it impossible for the listbox popup to always have the same width as the entry widget in the combobox.

One further caveat is that the indexing into the internal data store through member functions such as get, insert, and delete, is 0-relative. This is to make it identical to the indexing in the glishtk listbox widget which the combobox uses. This means that the first item in the list is at index number 0 and if there are N items in the list the the last item in the list is at index number 'N1'. In addition to being able to index by integer, there are three string indices which are useful: 'active', 'selected', and 'end'. Of these, 'active' and 'end' also can be used in glishtk listbox indexing. The third, 'selected' was added as a natural synonym for 'active'.

The combobox emits events through the agent returned by the ``agent'' member function.

return

When the user hits return in the combobox entry. The value of this event is the contents of the entry box when the user hit return.

select

When the user selects something from the popup list box or after a return if the combobox has addonreturn turned on (the default case).

clear

When the user presses the ``Clear'' button on the popup.

press

When the user presses the arrow button

user defined

Through the use of the ``bind'' member function, the application can bind X-events to the entry widget. When a bound event occurs in the entry widget it is emitted through this agent with the name the user chose in the invocation of ``bind''.

Example

f := frame()
cb := combobox(f,'Colors',"red blue green yellow amber saffron");
print cb.get('selected')
# the string ``red'' is printed out
cb.select(2)
print cb.get('selected')
# the string ``green'' is printed out due to 0-relative indexing
cb.insert('orange', 2)
a := cb.get(0,'end')
# a now contains "red blue orange green yellow amber saffron"
# The selection is maintained at green, which now has an index of 3