NAME

Tk::ChoicesSet - display/edit a list of choices in a Set of single-selection Widgets.

SYNOPSIS

require Tk::ChoicesSet;
my $labels_and_values = [
    {label => 'foo', value => 1},
    {label => 'bar', value => 2},
    {label => 'baz', value => 3},
];
my $instance = $main_window->ChoicesSet(-labels_and_values =>
                                         $labels_and_values)->pack;
$instance->configure(-valuelist_variable => \$valuelist);
$instance->valuelist([1,3]);

DESCRIPTION

Tk::ChoicesSet creates a Set of widgets to display/edit a list of choices. Each widget allows for a single selection out of a given list of options. The widget class is configurable. Per default Tk::ChoicesSet uses Tk::MatchingBE which is included in the Tk-EntrySet package. This can be changed to any widget that supports index based access to the selection. Tk::ChoicesSet adds/removes widgets to match the size of the valuelist. When a selection-widgets state becomes undef (deselected), the value is deleted from the valuelist and the widget is removed from the set on view update. View updates are by default bound to the widgets -selectcmd for integration with MatchingBE. This is configurable through the -callback_installer option. The last widget in the Set is always empty to allow users to append values to the list. (If you need editable values with an optionlist for 'suggestions' and value based access to the widgets in the set, you might want to use Tk::EntrySet.) Tk::ChoicesSet handles label/value pairs or simple choices lists. Tk::ChoicesSet is a Tk::EntrySet derived widget.

METHODS

Tk::ChoicesSet supports the following methods:

valuelist([qw/a list of selected values/])

Get/Set the valuelist (arrayref).

indexlist([qw/a list of selected indexes/])

Get/Set the indexlist (arrayref). For internal use primarily.

labels_and_values([{label=>'aLabel',value=>'aValue'},{},{}])

Get/Set the options list (arrayref of hashes). Sets label and value of each element to the corresponding hash value.

choices([qw/a list of options to choose from/])

Get/Set the options list (arrayref). Sets label and value of each element to the value in the list. When used as a getter returns the list of option labels.

OPTIONS

Tk::ChoicesSet supports the following options:

-entryclass

A Tk widget class to be used for the entrywidgets. Defaults to 'MatchingBE'.

-entryoptions

Options to be passed to each entry on creation (arrayref).

-getter

A coderef which is used by Tk::ChoicesSet to read the Entrywidgets content. It gets passed the Entrywidget instance and is expected to return its selected index. Defaults to sub{ $_[0]->get_selected_index }, which is suitable for Tk::MatchingBE.

-setter

A coderef which is used by Tk::ChoicesSet to write the Entrywidgets content. It gets passed the Entrywidget instance and the new index value. Defaults to sub{ $_[0]->set_selected_index($_[1]) }, which is suitable for Tk::MatchingBE.

-callback_installer

A coderef which is called after each Entrywidgets instantiation. The callback_installer gets passed the Entrywidget and a coderef that will update the Tk::ChoicesSet view when called. Defaults to sub{$_[0]->configure(-selectcmd => $_[1])}, which is suitable for Tk::MatchingBE.

-unique_values

If set to true (default) duplicate elements will be removed on view updates.

-valuelist

Get/Set the list of selected values (arrayref).

-valuelist_variable

Ties a variable (scalarref) to the -valuelist atribute. This is a Scalar Tie only.

Examples

See the examples/ subdirectory.

AUTHOR

Christoph Lamprecht, ch.l.ngre@online.de

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Christoph Lamprecht

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.