use Tk::JComboBox;
...
my $jcb = $parent->JComboBox(?options, ...?)

Creates and returns a JComboBox widget. The appearance and behavior of the widget can be configured by passing one or more options, described in more detail below.

Tk::Widget // Tk::Frame // Tk::JComboBox

JComboBox is a composite widget which contains a text label or Entry, a Button, and a popup Listbox. It performs the same sort of tasks that can be accomplished using BrowseEntry, ComboEntry, Optionmenu, and MenuEntry.

JComboBox borrows heavily from the Java Swing component bearing the same name, and although this widget is not as fully featured, many of the method names, and the general behavior will be familiar for those familiar with that component. Like the Java component, this widget has two different forms: editable and uneditable.

In the uneditable form, JComboBox resembles Optionmenu. It is basically a button that activates a a popup list. Items from the list are displayed on the Button when they are selected.

When editable, JComboBox resembles ComboEntry, MenuEntry, or BrowseEntry to varying degrees. That is, the widget is composed of an Entry widget with a Button to the right of it. Like the uneditable form, a button press will activate a popup list.

Note: Having two distinct appearances depending on whether or not the widget is editable or not was an intentional design decision. It makes sense from a usability standpoint. An uneditable text string that is contained in an area that looks as though it should be editable is a misleading context clue which can potentially confuse users. With a little extra effort, this appearance can be overridden in whatever matter you choose, but it is not recommended.

For more detailed information on using this widget, refer to the JComboBox tutorial.

WARNING: Directly accessing and configuring JComboBox's subwidgets should generally be avoided when possible. For most cases, options are provided that will configure them. In addition, The subwidget names are more descriptive of the each widget's function and not it's actual class, and this could lead to confusion. For example, There is not a single Button widget within JComboBox, but there are Subwidgets labeled as Buttons (Label widgets)

The subwidgets below are only documented to provide a better understanding of which parts of the JComboBox are affected by the options, and to provide an extra degree of flexibility for customization not provided for using only the options. Take nothing for granted and read the following carefully before configuring one the subwidgets

• addItem( string, ?option => value, ... )
• clearSelection()
• getItemIndex( string, ?option => value, ... )
• getItemCount()
• getSelectedIndex()
• getItemNameAt( index )
• getItemValueAt( index )
• getSelectedValue()
• hidePopup()
• index( index )
• insertItemAt( index, string, ?option => value, ... )
• popupIsVisible()
• removeAllItems()
• removeItemAt( index )
• see( index )
• setSelected( string, ?option => value, ... )
• setSelectedIndex( index )
• showPopup()

addItem( string, ?option => value, ... )

Appends a new List item to be used in the Popup Listbox. string is a scalar variable that is displayed in the Listbox. This method takes two options: -selected and -value.

Options:

-selected => selected

Where selected is a boolean value (true/yes/1) and determines whether or not the list item is the select item within the JComboBox. The default value for this is false and any subsequent call that uses this option, overrides previous ones.

-value => value

where value is an alternate string associated with the List Item for times when it's desirable to have a value other than the one displayed (I find it to be useful for database applications)

Example:

$jcb->addItem('ALASKA', -value => 'AK', -selected => 1);

clearSelection()

Clears the currently selected item in the JComboBox if one is selected

getItemIndex( string, ?option => value, ... )

Searches the JCombobox for the first item that matches the given string and returns that item's index. If no match is found, the method returns undef. This method has two optional parameters: -mode and -type.

Options:

-type => type

Where type is either name, the displayed text, or value, the alternate value associated with the item. If an item in the JComboBox does not have a value defined, then that item's name is used. The default type is name.

-mode => mode

where mode affects the how the given string is compared to a list item. Values include: exact, usecase, and ignorecase. In the exact mode, the string must completely match a list item, including it's case. In usecase mode, the string must match the beginning of the list item, including it's case, and in ignorecase mode, the string must match the beginning of the list item, but doesn't care about the case. The default mode is exact.

Example:

my $index = $jcb->getItemIndex('AK', -type => 'value');

getItemCount()

Returns the number of list items stored in the JComboBox.

getSelectedIndex()

Returns the index of the current selected item or undef if there isn't one selected.

getSelectedValue()

Returns the value of the current selected item or undef if there isn't one selected. In the case of an editable JComboBox, if no items are selected, then the text in the entry is returned.

getItemNameAt( index )

Returns the string displayed in the listbox at the given index.

getItemValueAt( index )

Returns the alternate text associated with the list item at the given index if it's set. Otherwise, will return the the displayed item.

index( index )

Returns the integer index value that corresponds to index. If index is end then return value is a count of the number of elements in the listbox (not the index of the last element).

insertItemAt( index, string, ?option => value, ... )

Inserts a new list item into the JComboBox at the specified index. string is a scalar variable that is displayed in the Listbox. This method takes two options: -selected and -value. Refer to this section on indices in the Listbox documention.

Options:

-selected => selected

Where selected is a boolean value (true/yes/1) and determines whether or not the list item is the select item within the JComboBox. The default value for this is false and any subsequent call that uses this option, overrides previous ones.

-value => value

where value is an alternate string associated with the List Item for times when it's desirable to have a value other than the one displayed (I find it to be useful for database applications)

Example:

$jcb->insertItemAt('end', 'ALASKA', -value => 'AK', -selected => 1);

popupIsVisible()

Returns 1 if the popup is mapped, 0 if it isn't

removeAllItems()

Completely removes all list items from the JComboBox, and clears any selected item if present.

removeItemAt( index )

Deletes a single list item from the JCombobox at the specified index.

see( index )

Adjusts the JComboBox so that the list item indicated by the given index is visible. If the Listbox is hidden, it will be made visible, and the the list will shift so that the item is viewable as necessary.

setSelectedIndex( index )

Selects the list item that exists at the given index.

showPopup()

Displays the popup listbox ( normally triggered by the JComboBox button )