Tk::JComboBox Package Info
Tutorial | FAQ | Changes/Bug fixes
Version:0.01
DSLIP:bdpOp
Author:Rob Seegel
Maintainer:Rob Seegel
Package:JComboBox
Platforms:Linux
Unix
Windows

SYNOPSIS

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.


HEIRARCHY

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


DESCRIPTION

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.


COMPONENTS

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

  Subwidgets:
Name:ED_Button
class:Label
Editable Button. When the JComboBox is in editable mode, this widget is used as the 'Button' that triggers the popup listbox. Care should be taken, because it is actually a Label widget, bound to act as a Button, this is mostly to work around inconsistancies with Button across platforms.
Name:ED_Entry
class:Entry
Editable Entry. Used for Entry when the JComboBox is in editable mode.
Name:Listbox
class:Scrolled Listbox
Refers to the Listbox which pops up when the ComboBox Button is activated.
Name:Popup
class:Toplevel
The Toplevel window that Listbox is packed into
Name:RO_Button
class:Label
Readonly Button. When the JComboBox is in readonly mode, both the 'entry' and the 'button' (both labels) are used as buttons that trigger the popup listbox. This widget is the portion of the button that displays the down arrow
Name:RO_Entry
class:Label
Read Only Entry. This 'Entry', combined with RO_Button, form the button for the button in readonly mode.


OPTIONS

  Widget-specific Options:
-background
-buttonbitmap
-buttonborderwidth
-buttonimage
-buttonrelief
-choices
-font
-gap
-listhighlight
-maxrows
-mode
-popupbackground
-popupborderwidth
-popuprelief
-selectbackground
-selectcommand
-selectforeground
-state
-textvariable
-validate
Name:background
class:Background
Switch:-background
Aliases:-bg
Sets the background color for the base widget, the Button which triggers the Popup, and the window which holds the Listbox (ED_Button, RO_Button, RO_Entry, and Popup). Default is the normal default background color for whichever platform you are on.
Switch:-buttonbitmap
Aliases:-bbmp
Specifies the bitmap to be used for the Button (ED_Button and RO_Button) that activates the popup. Default is Tk::JComboBox::downarrow, which is defined by the class
Switch:-buttonimage
Aliases:-bimg
Specifies the image to be used for the Button (ED_Button and RO_Button) that activates the popup. No default is defined, because -buttonbmp is used for the down arrow, by default
Switch:-buttonborderwidth
Aliases:-bbd
Only used in editable mode. This option configures borderwidth for the Button (ED_Button) that activates the popup. In readonly mode, -borderwidth is used
Switch:-buttonrelief
Aliases:-brelief
Only used in editable mode. This option configures relief option for the Button (ED_Button) that activates the popup. In readonly mode, -relief is used. Default value is raised.
Switch:-choices
Aliases:-options
Sets the elements which make up the list of list items displayed in the Listbox. This option expects an array reference to a list of scalars, a list of hash references or a mix of the two. Every time it is set, all existing list elements are deleted and replaced with the new set. For more details, see the section on Adding Elements to JComboBox
Name:font
class:Font
Switch:-font
Specifies the font to be used for all Subwidgets which display characters (Listbox, ED_Entry, and RO_Entry)
Name:gap
class:Gap
Switch:-gap
Specifies the amount of space (in chars) between the longest list element and the JCombobox Button (both RO_Button and ED_Button). The Default value for this option is 2.
Name:listHighlight
class:ListHighlight
Switch:-listhighlight
Defines a set of extra bindings for the Listbox that highlights a list element when the mouse pointer is over it, regardless of whether or not Button-1 is pressed. This is a behavior typically seen in Win32 ComboBox components. Possible values for this option are 1 (enabled), and 0 (disabled). Default value is 1.
Switch:-maxrows
Aliases:-visiblerows
Controls the number of visible items within the popup listbox at any given time. If this value is set to a number that is less than the total number of list items, then the listbox is set to the height of the submitted value and a scrollbar is used automatically so that the remaining items can be scrolled to. This option is recommended for long lists. The default value is undef.
Name:mode
class:Mode
Switch:-mode
Specifies the mode for the Listbox. There are two different modes, editable and readonly. In editable mode, the widget resembles an Entry widget with a button next to it, and the Entry is editable. In readonly mode, the entire widget resembles a button, and items can only be selected from the listbox. The default value is readonly.
Name:popupBackground
class:PopupBackground
Switch:-popupbackground
Aliases:-pbg
Configures the background color for the toplevel window (Popup) that contains the Listbox. Defaults to #D9D9D9 for Unix and SystemButtonFacefor Win32.
Name:popupborderwidth
class:Popupborderwidth
Switch:-popupborderwidth
Aliases:-pbd
Configures the borderwidth for the toplevel window (Popup) that contains the Listbox. This option can be used with -popupbackground and -popuprelief to create different sorts of borders for the Popup listbox window. default value for this option is 2
Name:popupRelief
class:PopupRelief
Switch:-popuprelief
Aliases:-prelief
Configures the relief for the toplevel window (Popup) that contains the the Listbox. Default value is flat
Name:selectBackground
class:SelectBackground
Switch:-selectBackground
Aliases:-selectbg
Configures the -selectbackground for both the JComboBox Entry (ED_Entry), and the Listbox. Defaults to #C3C3C3 for Unix and SystemHighlight for Win32.
Name:selectCommand
class:selectCommand
Switch:-selectcommand
Aliases:-scmd
Sets a callback to be executed everytime a list item is selected. The callback is passed two parameters (in addition to any others you defined): the selected index, and the selected value. There is no default callback
Name:selectForeground
class:SelectForeground
Switch:-selectForeground
Aliases:-selectfg
Configures the -selectforeground for the JComboBox Entry (ED_Entry), and the Listbox. Defaults to Black for Unix and SystemHighlightText for Win32.
Name:state
class:State
Switch:-state
Specified one of two states for the JComboBox: normal and disabled. When the state is normal The Popup Listbox cannot be triggered except using widget methods, and the selected value cannot be changed using the Listbox or widget methods. The default value for this option is normal
Name:textVariable
class:Variable
Switch:-textvariable
Sets the -textvariable to the JComboBox Entry. Unlike the standard option called -textvariable, this should be used for read only purposes only. That is, if you want to pass in a SCALAR reference, so that can variable will reflect the current selection of the JComboBox. If a variable is set external to the widget, it will modify the Entry while in editable mode. This use should generally be avoided in preference of the appropriate widget methods. This variable will reflect the named or displayed value only.
Name:validate
class:Validate
Switch:-validate
Selects the mode in which validation should operate. This option works exactly like the -validate option for Entry, except that it supports two additional modes: match and csmatch. Refer to section on validation for more information on these additional modes. Default value for this option is none.

  Inherited Options:
-borderwidth
-class
-cursor
-highlightbackground
-highlightcolor
-highlightthickness
-relief
-takefocus



METHODS


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:

The following would return the index of the first matching list item where AK completely matched that item's value.
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.


hidePopup()

Causes the popup listbox to be withdrawn from the screen, unmapping it. Hiding and showing the popup listbox is generally handled by various event handlers, but is available for use in custom handlers or other use.


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:

The following example produces exactly the same result as the example given for addItem
$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 )


This document was written by Rob Seegel on 20 May 2001