NAME

Tk::PopUpSelectBox - A new scrolled pop-up selection-widget (with MULTI-level selections)

SYNOPSIS

    use Tk;
    use Tk::PopUpSelectBox

    my $current_class;
    my @all_classes = qw(cat dog bird);
    my $demo_xpm;
	
    my $mw = MainWindow->new();
	
    # prepare some graphics
    setup_pixmap();

    # create a demo 
    my $popupselectbox = $mw->PopUpSelectBox (
        -text     => "Class",
        -image    => $demo_xpm, # use this line for personal pics or
        #-bitmap  => '@' . Tk->findINC('cbxarrow.xbm'));
        -command  => \&class_cb,
        -options  => [ @all_classes ],
        -variable => \$current_class, 
		-tearoff  => '1',
		-listmaxheight => 10,
		-activate => '0',
   )->pack;
	
    Tk::MainLoop;
	
    sub class_cb
    {
        print "class_cb called with [@_], \$current_class = >$current_class<\n";
    }
    sub setup_pixmap
    {
        my $cbxarrow_data = <<'cbxarrow_EOP';
	/* XPM */
	static char *cbxarrow[] = {
	"11 14 2 1",
	". c none",
	"  c black",
	"...........",
	"....   ....",
	"....   ....",
	"....   ....",
	"....   ....",
	"....   ....",
	".         .",
	"..       ..",
	"...     ...",
	"....   ....",
	"..... .....",
	"...........",
	".         .",
	".         ."
	};
cbxarrow_EOP

        $demo_xpm = $mw->Pixmap(-data => $cbxarrow_data);
    }
	

DESCRIPTION

A new dialog style widget that can replace the custom Optionbox whenever the itemlist is too long. Useful in applications that want to use a more flexible option menu. It's a 1:1 replacement for the custom Optionbox, supporting the same Options / commands.

You can tie a scalar-value to the Optionbox widget, enable/disable it, assign a callback, that is invoked each time the Optionbox is changed, as well as set Option-values and configure any of the options understood by Tk::Frame(s) like -relief, -bg, ... . (see docs of TK::Optionmenu) for details

METHODS

set_option()

'set_option($newvalue)' allows to set/reset the widget methodically, $newvalue will be aplied to the labeltext (if visible) and the internal variable regardless if it is a list previously store in options.

NOTE: You should prefer interacting with the widget via a variable.

add_options()

'add_options(@newoptions)' allows to enter additonal options that will be displayed in the pull-down menu list.

You should prefer to use a Configure ('-options' => ...).

NOTE: Unless You specify -activate => 0 for the widget each time you use add_options the first item will be set to be the current one and any assigned callback gets called.

popup()

'popup()' allows to immediately popup the menu to force the user to do some selection.

itemtable()

'itemtable()' retrieves a list of all current selection items. Requesting a listcontext retrieves a label/value based hash, retrieving a scalar retrieves a hash-ref. NOTE the -separator setting for the hierarchical delimiter wherever applied.

OPTIONS

-variable

'-variable' allows to specify a reference to a scalar-value. Each time the widget changes by user interaction, the variable is changed too. Every variable change is immediately mapped in the widget too.

-command

'-command' can be used to supply a callback for processing after each change of the Option value. This callback receives as parameters 'current' value + label + full-label for hierarcical (sub)lists. NOTE the -separator setting for the hierarchical delimiter applied for full-label.

-image

'-image' can be used to supply a personal bitmap for the menu-button. In difference to the original Optionmenu the std. menu-indicator is switched off, if a graphic/bitmap is used , although it might be re-enabled manually with a '-indicatoron =\ 1'> setting. If no image and no bitmap is specified the text given with '-text' or the current selected optiontext is displayed in the button.

-options

'-options' expects a reference to a list of options.

plain format: label, label, [ label, value ], [ label, value ], [ label, value ], ... multi-level selection: The methodology is the same as before: Whenever instead of a label an Array-reference is found it is suggested as a subitem-list. It is poosible to mix plain items, items with spec'd values other than the label in any level. example: label, label, [ label, value ], [[keylabel, \@subopts], undef], [ label, value ], See the supplied example for further information.

-activate

'-activate' expects 0/1 and rules whether the first item applied with -options gets set 'current'. see NOTE above.

-listmaxheight or -rows

'-listmaxheight' defines the height of the selection list. default is 20.

-separator

'-separator' defines the separator character that is used for the internal representation of the tree delimiter. Invoking a callback via set_options the target function get [value, label & full-hierarchical label]. The f-h-label uses the specified separator. Default is '.'

-autolistwidth

'-autolistwidth' expects 0/1 and defines whether the pop'd up list will dynamically adapt its width.

-autolimitheight

'-autolistwidth' expects 0/1 and defines whether the pop'd up list will not be heigher than the value definable via '-listmaxheight'

-validatecommand

'-validatecommand' defines a Callback function to evaluate the current selection. It is invoked with the_widget, value, label, full_label, old_value and old_label. Returning FALSE will reject the current selection.

Please see the TK:Optionmenu docs for details on all other aspects of these widgets.

AUTHORS

Michael Krause, KrauseM_AT_gmx_DOT_net

This code may be distributed under the same conditions as Perl.

V0.02 (C) March 2008