Tk::JComboBox

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.

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

Directly accessing and configuring JComboBox's subwidgets should generally be avoided when possible. For most cases, options are provided which will configure the subwidgets. They are provided below for exceptions, and to provide a better idea of what a particular option will affect in the descriptions below.

It's worth noting that some of the names below serve more of a functional purpose than purely descriptive. There are some widgets, which have names that may be misleading. For example, there are Labels used instead of Button widgets yet they still are advertised as Buttons. This is because functionally, they are used like Buttons, but they do not support all the same options that Button widgets support. They are used instead for a more consistant appearance across platforms. For this reason, it's important to pay attention to the Class as well as the name listed in the table below.

• 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 )