Read-only (readonly)

The JComboBox shown in the image above was cerated using the following code:

  use Tk;
  use Tk::JComboBox;

  my $mw = MainWindow->new;
  my $jcb = $mw->JComboBox(
     -choices => [qw/Black Blue Green Purple Red Yellow/],
  )->pack;

  MainLoop;

Editable

Optionally, the entry could be used to validate an entry. Visually, this mode resembles the typical combo box as seen on Win32 systems. It also resembles ComboEntry and looks somewhat like BrowseEntry.

The JComboBox in the image above was create using the following code:

  use Tk;
  use Tk::JComboBox;

  my $mw = MainWindow->new;
  my $jcb = $mw->JComboBox(
     -entrybackground => 'white',
     -mode => 'editable',
     -relief => 'sunken',
     -choices => [qw/Black Blue Green Purple Red Yellow/],
  )->pack;

  MainLoop;

Adding Items

   -choices => [
      { -name => 'Black',  -value => '#000000' },
      { -name => 'Blue',   -value => '#0000ff' },
      { -name => 'Green',  -value => '#008000' },
      { -name => 'Purple', -value => '#8000ff' },
      { -name => 'Red',    -value => '#ff0000' },
      { -name => 'Yellow', -value => '#ffff00' }
   ]

Although the usefulness is questionable, you can even use a mix of both hash references and scalars if you wish, like this:

   -choices => [
      'Black',
      { qw/-name Blue -value #0000ff/},
      'Green',
      'Purple',
      'Red',
      { qw/-name Yellow -value #ffff00/}
   ]

Adding One Item at a Time

The following inserts a new item into the list:

   ## If this line is added to one of the examples above, then it will add
   ## an item called 'Orange' after 'Red', and before 'Yellow'.

   $jcb->insertItemAt( 5, 'Orange', -value => '#FF8000');

The following code appends an entry to the end of the List:

  $jcb->addItem('Orange', -value => '#FF8000');

Marking Items as Selected

Here's an example using -choices:

  ## Sets Black as the default selected item. You can set more than 
  ## one item in the list as selected, but only the last item marked
  ## as selected will be selected.

  -choices => [
     { -name => 'Black',  -value => '#000000', -selected => 1 },
     { -name => 'Blue',   -value => '#0000ff' },
     { -name => 'Green',  -value => '#008000' },
     { -name => 'Purple', -value => '#8000ff' },
     { -name => 'Red',    -value => '#ff0000' },
     { -name => 'Yellow', -value => '#ffff00' }
  ]

Both of the methods that allow you to add items permit the -selected option:

  $jcb->insertItemAt( 5, 'Orange', -value => '#ff8000', -selected => 1 );

  $jcb->addItem( 'Orange', -value => '#ff8000', -selected => 1 );

There are also special methods specifically intended for setting the selection: setSelectedIndex and setSelected. Of the two, setSelectedIndex is simplest to use:

  ## Selects the first item in the list
  $jcb->setSelectedIndex( 0 );

setSelected is a bit more complex. For this method, a string is passed as a parameter, and the list is search starting at index 0, until the entire list has been searched or until the first match has been found. There are options that determine what string is compared against, and how the search is done.

-type

Describes the the list item type. This is which part of the item is being searched. The type has two possible values: name (the default), and value.

-mode

Describes the search mode. Currently, there are three: exact, usecase, and ignorecase. The pattern must exactly match the entire name or value, from beginning to end, including case when the mode is set to exact. The usecase and ignorecase modes apply the pattern to the beginning of the name or value, and the only difference between the two is whether or not case is significant. The default mode is exact.

Examples:

  use Tk; 
  use Tk::JComboBox;

  my $mw = MainWindow->new();
  my $jcb = $mw->JComboBox(
    -choices => [
      {qw/-name Black  -value 1/},
      {qw/-name Blue   -value 2/},
      {qw/-name Green  -value 3/},
      {qw/-name Purple -value 4/},
      'Red',
      {qw/-name Yellow -value 5/}]
  )->pack;

  ## Selects the last element, 'Yellow' using defaults for -type and -mode
  $jcb->setSelected( 'Yellow' );        

  ## Selects the list item 'Purple', using default for -mode
  $jcb->setSelected( '5', -type => 'value' );

  ## Selects the list item 'Red', using the default for -mode
  ## Remember that 'Red' is both the name and value for that item
  $jcb->setSelected( 'Red', -type => 'value' );

  ## Fails! There are no list item that begin with 'bl' 
  ## current selection unchanged
  $jcb->setSelected( 'bl', -mode => 'usecase' );

  ## Succeeds! Selects 'Black' - the first matching item
  $jcb->setSelected('bl', -mode => 'ignorecase' );
  
  MainLoop;

Removing List Items

To remove all items:

  $jcb->removeAllItems();

  ## The same thing can be accomplished using -choices
  $jcb->configure(-choices => []);

To remove a single item (the third item in the list):

  $jcb->removeItemAt( 2 );

Getting List Items

These two methods are nearly the same. getItemNameAt retrieves the displayed item or name at the specified index, and getItemValueAt returns the value (or name if a value is not set) at the specified index.

It's also easy to get information about the selected item using one of the following methods: getSelectedIndex(), getSelectedName(), and getSelectedValue(). The first method returns the selected index, or -1 if none of the items are selected. Strictly speaking, the other two methods aren't really necessary, since a combination of getSelectedIndex and getItemNameAt or getItemValueAt will do exactly what the getSelectedName or getSelectedValue methods do. They are only provided as a convenience.

Access Through the Choices Array

As shown in previous sections, the following code will initialize the JComboBox's internal Listbox with the contents of the array.

   use Tk;
   use Tk::JComboBox;

   my @choices = (qw/black green/, {qw/-name blue -value #0000ff/});
 
   my $mw = MainWindow->new;
   my $jcb = $mw->JComboBox(-choices => \@choices)->pack;

The JCombobox created by this code will have three entries: black, green, and blue. Another item can be added using a JComboBox method, like this:

   $jcb->addItem('red');

The choices array will reflect the change.

   ## prints "Items: 4"
   print "Items: " . scalar(@choices) . "\n"; 

   ## prints "4th Item: red"
   print "4th Item: " . $choices[3] . "\n";

The choices array can be used to change the newly added item.

   $choices[3] = 'orange';
   print "Item: " . $jcb->getItemNameAt(3) . "\n";  ## Item: orange

   $choices[3] = {qw/-name yellow -value #ffff00/};
   print "Item: "  . $jcb->getItemNameAt(3) . "\n";  ## Item: yellow
   print "Value: " . $jcb->getItemValueAt(3) . "\n"; ## Value: #ffff00

Adding Items Through the Array

There are several approaches that can be used to add new elements. The array can be reinitialized:

   print "Reinitializing Array:\n";
   @choices = (qw/one two three/);
   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 3
   print "Item1: " . $jcb->getItemNameAt(0) . "\n"; ## Item1: one
   print "Item2: " . $jcb->getItemNameAt(1) . "\n"; ## Item2: two
   print "Item3: " . $jcb->getItemNameAt(2) . "\n"; ## Item3: three

One or more Items can be added to the end of the list:

   print "\nAppending items using push:\n";
   push @choices, "four";
   push @choices, qw(five six);
 
   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 6
   print "Item4: " . $jcb->getItemNameAt(3) . "\n"; ## Item4: four
   print "Item5: " . $jcb->getItemNameAt(4) . "\n"; ## Item5: five
   print "Item6: " . $jcb->getItemNameAt(5) . "\n"; ## Item6: six

The same thing can be accomplished using splice:

   print "\nAppending items using splice:\n";
   splice @choices, @choices, 0, $seven;
   splice @choices, @choices, 0, qw(eight nine);

   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 9
   print "Item4: " . $jcb->getItemNameAt(6) . "\n"; ## Item4: seven
   print "Item5: " . $jcb->getItemNameAt(7) . "\n"; ## Item5: eight
   print "Item6: " . $jcb->getItemNameAt(8) . "\n"; ## Item6: nine

Items can be inserted to the beginning using unshift:

   print "\nAdding items using unshift\n";
   unshift @choices, qw(A B);
   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 11
   print "Item1: " . $jcb->getItemNameAt(0) . "\n"; ## Item1: A
   print "Item2: " . $jcb->getItemNameAt(1) . "\n"; ## Item2: B

Again, splice can do the same thing:

   print "\nEmulating unshift with splice\n";
   splice @choices, 0, 0, qw(C D);
   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 13
   print "Item1: " . $jcb->getItemNameAt(0) . "\n"; ## Item1: C
   print "Item2: " . $jcb->getItemNameAt(1) . "\n"; ## Item2: D

Splice can also be used to add entries to the middle:

   print "\nInserting elements into the List:\n";
   splice @choices, 6, 0, "E";
   print "Items: " . $jcb->getItemCount . "\n";     ## Items: 14
   print "Item1: " . $jcb->getItemNameAt(6) . "\n"; ## Item1: E

Remove Items Through the Array

Removing items is as easy as adding them with the various array methods. We can delete the first item:

   print "\nDeleting using shift:\n";
   print "Item: " . shift @choices, "\n";       ## Item: C
   print "Items: " . $jcb->getItemCount . "\n"; ## Items: 13

   print "\nDeleting from beginning using splice\n";
   print "Item: " . splice(@choices, 0, 1) . "\n"; ## Item: D
   print "Items: " . $jcb->getItemCount . "\n";    ## Items: 12

The Last:

   print "\nDeleting using pop:\n";        
   print "Item: " . pop @choices, "\n";          ## Item: nine
   print "Items: " . $jcb->getItemCount . "\n";  ## Items: 11

   print "\nDeleting from the end with splice:\n";
   print "Item: " . splice(@choices, -1) . "\n"; ## Item: eight
   print "Items: " . $jcb->getItemCount . "\n";  ## Items: 10

An element within the array:

   print "\nRemove using delete:\n";
   print "Item: " . delete $choices[2];           ## Item: one
   print "\nItems: " . $jcb->getItemCount . "\n"; ## Items: 9

Note that JComboBox overrides the basic behavior of delete where it applies to arrays. In JComboBox, when delete is used, it will delete the specified index no matter if it is at the end, the beginning, or middle, causing the other array elements to be adjusted as necessary. As with most other operations, the same effect can be achieved using splice.

   print "\nRemove using splice:\n";
   print "Item: " . splice @choices, 2, 1;        ## Item: two
   print "\nItems: " . $jcb->getItemCount . "\n"; ## Items: 8

Or all the items:

   print "\nRemove all items:\n";
   @choices = ();
   print "Items: " . $jcb->getItemCount . "\n"; ## Items: 0

The Autofind Option

-enable

Determines whether or not autofind, in any of its variations, should be switched on. If false, then a key press will have to effect on the JComboBox, except within editable mode and adding regular text. If enabled, the precise effect will depend on other autofind options and the JComboBox mode. In editable mode, the Entry contents (up to the insertion bar) will be used as a search string for autofind, and in readonly mode, only the pressed key will be used as the search string.

-casesensitive

Determines whether or not case matters when the autofind is searching for a matching list item. By default, this value is false, and case does not matter.

-showpopup

Determines whether or not to show the Popup listbox, when an item has been found within the list. For some applications, the popup may be unecessary if the item appears within the Combo Box's selection. By default, this option is enabled, and the popup is shown.

-select

Determines whether or to set the matching list item as selected. This is useful in readonly mode and you don't want to show the Popup. By default, this option is enabled.

-complete

When enabled, this option provides a basic auto-completion functionality that only affects editable mode. If this option is desired, then -select should be disabled. Both of these options cannot be used concurrently, and -select will always take precedence if both are set.

These options can be combined in various ways:

   ## autofind enabled, ignore case, select matching item, do not show popup
   -autofind => { -showpopup => 0 }

   ## autofind enabled, use case, select matching item, do not show popup
   -autofind => { -casesensitive => 1, -showpopup => 0 }

   ## autofind enabled, ignore case, use auto-completion, do not show popup
   -autofind => { -select => 0, -complete => 1, -showpopup => 0 }

The best way to famililarize yourself with these options is to experiement with the various combinations, and see what works best for your application. It's important to emphasize that these options have nothing to do with validation. Validation can be used in addition to these features, or not at all if you wish.

The -matchcommand option

The -autofind option assumes that each search is going to be anchored to the left side. For example, consider the case where I have a list containing the items: two three thirteen, and I have an editable JComboBox. The first letter I type is a t, annd it matches the first item two. I then type an h, which matches the second item next. This is the default behavior. In some cases, this may not fit in with how you would like items to be searched. The -matchcommand allows this behavior to be customized.

The option expects a callback that will be passed the search string, and the field that is being evaluated, and it is up to the callback to determine whether or not the field is a match for the search string or not. If it, the callback should return a 1, otherwise it should return 0.

The defined callback will be passed at least two parameters, plus one or more optional ones.

search String

This will be the first parameter passed to the getItemIndex method. When called from Autofind in readonly mode, this will be a single letter. In editable mode, this will be the contents of the Entry.

item

This will be an item from the JComboBox. The getItemIndex method allows a -type option, which may be set as name or value. In the case of name (the default), then the string that is displayed within the Listbox will be the item. In the case of -type being value, then the non-visible String associated with the name will be used as the item instead.

Optional parameters

The remainder of the parameters should be assigned to a hash map. Unless you pass your own custom parameters to getItemIndex, the only parameter you are likely to see is -mode. This is used by the default implementation (refer to the documentation for getItemIndex ) and you can choose to ignore or implement it if you wish.

An Example

If you wanted to anchor the search to the end of a string, it could be done like this:

   use Tk;
   use Tk::JComboBox;

   my $mw = MainWindow->new;
   my $jcb = $mw->JComboBox(
      -choices => [qw/one two three four five/],
      -mode => 'editable',
      -matchcommand => sub {
         my ($searchStr, $item) = @_;
         $item =~ /\Q$searchStr\E$/;
      }
   )->pack;

   MainLoop;

If you run, this, type 'e' in the entry, and the first item should be selected. Type 'e' again, and now the third entry should be selected.

The -restrictchoices Option

The -updownselect Option

The List Highlight Option

Validation Options

JComboBox supports validation in editable mode, by allowing the -validate and -validatecommand options to be set. These options work almost exactly like they do for the Entry widget. Generally, the -validate option is used to determine when the entry is validated, and the -validatecommand is used to specify the validation rule. Callbacks registered to the -validatecommand are passed several pieces of information, and are expected to use that information to evalulate whether the entry contents are valid or invalid. If Invalid, the callback should return a 0, and if valid, a 1 is expected.

Currently, JComboBox extends the -validate option slightly by offering two additional values: match and cs-match. Specifying one of these two values will essentially do the same thing that JComboBox does in readonly mode: limit the user to entries that are List items only. These options are translated to validate => "key" and an internal -validatecommand that enforces the rule. I'm unsure how useful these additional options are, but will leave them in for the time being.