The listbox displays a list of text items from which a user can select, by clicking on them. The listboxes have vertical scroll bars to allow viewing of a long list of items.
When programming in IDL, you create listbox widgets using the WIDGET_LIST function. For more information, see WIDGET_LIST.
For listbox widgets, you can set common attributes and listbox-specific attributes. For a list of common attributes, see Common Attributes. These are the listbox widget attributes:
The Height attribute specifies the height of the listbox based on the number of lines that are visible. The possible values for the attribute are 1 to n. By default, Height is set to 1, which indicates the default size of one line will be used.
Note that the final size of the widget may be adjusted to include space for scroll bars, which are not always visible, so the listbox might be slightly larger than specified.
In the generated *.pro file, this value specified with the YSIZE keyword to the widget creation routine.
The Initial Value attribute specifies the initial list of values that are placed in the list widget. By default, the list is empty, but you can set this value to a scalar string or a list of strings. List widgets are sized based on the length (in characters) of the longest item specified in the array of values.
To enter more than one string in the Value field, type in a string, then press Control+Enter (at the end of each line). This moves you to the next line. When you have entered as many strings as you want, press Enter to set the values.
In the generated *.pro file, this value is specified by the VALUE keyword to the widget creation routine.
The Multiple attribute determines if the user can select multiple list items. By default, the setting is False, which allows for only one selection. To enable multiple list item selection, set this value to True. Multiple selections are handled using the method appropriate to the platform the application is running on.
In the generated *.pro file, this value is specified with the MULTIPLE keyword to the widget creation routine.
The Tab Mode attribute specifies what support the widget has for receiving or losing focus through tabbing. By default, this value is set to Inherit.
| Note |
Allowable values are:
| Note |
| Note |
In the generated *.pro file, this value is specified with the TAB_MODE keyword to the widget creation routine. For more information on tabbing among widgets, see Tabbing in Widget Applications.
The Width attribute specifies the width of the listbox in characters. The possible values for the attribute are 0 to n. By default, Width is set to 0, which indicates that default sizing will be used, as long as the Component Sizing attribute is set to default.
By default, IDL sizes widgets to fit the situation. However, if the desired effect is not produced, use explicit Component Sizing with the Width attribute to set your own sizing. The final size of the widget may be adjusted to include space for the scroll bar, which is not always visible, so your widget may be slightly larger than specified.
In the generated *.pro file, this value specified with the XSIZE keyword to the widget creation routine.
For listbox widgets, you can set common event properties and listbox-specific event properties. By default, event values are not set. For a list of events common to all widgets, see Common Events.
The following is the event property specific to listbox widgets:
The OnContextEvent value is the routine name that is called when the user clicks the right-hand mouse button over the list widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when the user clicks the right-hand mouse button and is of the following type:
{WIDGET_CONTEXT, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L}
The X and Y fields give the device coordinates at which the event occurred, measured from the upper left corner of the base widget.
The OnSelectValue specifies a valid IDL routine name that is called when a list item is selected. When a user clicks on an item in the listbox to select the item, an event is generated.
When you set this event value, the calling sequence looks like this in the generated *_eventcb.pro file:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the returned event structure, which is of the following type:
{ WIDGET_LIST, ID:0L, TOP:0L, HANDLER:0L, INDEX:0L, CLICKS:0L }
The first three fields are the standard fields found in every widget event. INDEX returns the index of the selected item. This index can be used to subscript the array of names originally used to set the widget's value. CLICKS returns either 1 or 2, depending on how the list item was selected. If the list item is double-clicked, CLICKS is set to 2.
| Note |