NAME

Tk::Optionbox - Another pop-up option-widget (with MULTI-level selections)

SYNOPSIS

    use Tk;
    use Tk::Optionbox

    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 $optionbox = $mw->Optionbox (
        -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',
		-rows => 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

Another menu button style widget that can replace the default Optionmenu. Useful in applications that want to use a more flexible option menu. It's based on the default TK::Optionmenu, beside that it can handle menubuttons without the persistent, ugly menu-indicator, suitable for perl Tk800.x (developed with Tk800.024).

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.

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.

NOTE: Version 1.4 adds a secondary level to selections: instead of the plain format label, label, [ label, value ], [ label, value ], [ label, value ], you must use this format: [ label, value ], [[keylabel, \@subopts], undef], [ label, value ], NOTE: Version 1.6 adds TRUE multi-level selections. 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. 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.

-rows

'-rows' defines after how many entries the list gets split into another row. default is 25. This values applies also for sub-item-lists

-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 '.'

-tearoff

'-tearoff' defines whether the pop'd up list will have a tear-off entry at first position.

-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.

V1.6 (C) September 2005