/ 
Tk-Options-0.21
/ Tk::Options

NAME

Tk::Options - Access to options via Getopt::Long and Tk window interface

SYNOPSIS

    use Tk::Options;
    ...
    @opttable = (['opt1', '=s', 'default'], ['opt2', '!', 1], ...);
    $opt = new Tk::Options(-opttable => \@opttable,
                           -options => \%options,
			   -filename => "$ENV{HOME}/.options");
    $opt->load_options;
    $opt->process_options;
    $opt->do_options;
    ...
    $opt->options_editor($top);

DESCRIPTION

Tk::Options provides an interface to access options via Getopt::Long (command line) and via a Tk window.

The API of this package is likely to change!

REQUIREMENTS

Tk::Options needs Data::Dumper and, of course, the Tk package. You can found these packages at CPAN.

METHODS

new Tk::Options(arg_hash)

Constructs a new object of the class Tk::Options. Arguments are delivered in a hash with following keys:

-opttable

This argument is mandatory and should be a reference to an array containing all used options. Elements of this array may be strings, which indicate the beginning of a new group, or array references describing the options. The first element of this array is the name of the option, the second is the type (string, integer, boolean etc., see Getopt::Long) of this option. The third element is optional and is the default value (otherwise the default is undefined). The fourth element is optional too and have to be a reference to a hash:

alias

An array of aliases also accepted by Getopt::Long.

label

A label to be displayed in the options editor instead of the option name.

help

A short help string used by usage and the Balloon help facility in options_editor.

longhelp

A long help string used by options_editor.

choices

An array of additional choices for the options editor.

from

The beginning of a range for an integer or float value.

to

The end of a range for an integer or float value.

strict

Must be used with choices or from/to. When set to true, options have to match either the choices or the range between from and to.

var

Use variable instead of $options->{optname} to store the value.

Example:
    @opttable = (['debug', '!', 0,
		  {'sub' => sub { $^W = 1 
				    if $options->{'debug'}; }}],
                 ['age', '=i', 18,
		  {'strict' => 1, 'from' => 0, 'to' => 100,
		   'alias' => ['year', 'years']}],
                 ['browser', '=s', 'tkweb',
		  {'choices' => ['mosaic', 'netscape',
				 'lynx', 'chimera'],
		   'label' => 'WWW browser program'}],
		 ['foo', '=f', undef,
		  {'help' => 'This is a short help',
		   'longhelp' => 'And this is a slightly longer help'}]);
-options

This argument is mandatory and should be a reference to a (empty) hash. Options are set into this hash.

-filename

This argument is optional and specified the filename for loading saved options from a file.

load_options(filename)

Loads options from file filename, or, if not specified, from object's filename as specified in new. The loading is done with a do-Statement. The loaded file should have a reference to a hash named loadoptions.

save_options(filename)

Writes options to file filename, or, if not specified, from object's filename as specified in new. The saving is done with Data::Dumper.

process_options

Gets options via GetOptions. Returns the same value as GetOptions, i.e. 0 indicates that the function detected one or more errors.

usage

Generates an usage string from object's opttable. The usage string is constructed from the option name, default value and help entries.

do_options([undo_hash])

Checks wheather given values are valid (if strict is set) and calls any subroutines specified by the sub option. If undo_hash is given and the new value of an option did not change, no sub is called.

options_editor(widget, [string_hash])

Pops the options editor up. The editor provides facilitied for editing options, undoing, restoring to their default valued and saving to the default options file.

BUGS

Not all of Getopt::Long is supported (using arrays or hashs for options).

This POD is out of date.

AUTHOR

Slaven Rezic <eserte@cs.tu-berlin.de>

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), Getopt::Long(3), Data::Dumper(3), Tk(3), Tk::NoteBook(3)