NAME

SYNOPSIS

    use Tk::Getopt;
    @opttable = (['opt1', '=s', 'default'], ['opt2', '!', 1], ...);
    $opt = new Tk::Getopt(-opttable => \@opttable,
                          -options => \%options,
                          -filename => "$ENV{HOME}/.options");
    $opt->set_defaults;     # set default values
    $opt->load_options;     # configuration file
    $opt->get_options;      # command line
    $opt->process_options;  # process callbacks, check restrictions ...
    print $options->{'opt1'}, $options->{'opt2'} ...;
    ...
    $top = new MainWindow;
    $opt->option_editor($top);

or using a Getopt::Long-like interface

    $opt = new Tk::Getopt(-getopt => ['help'   => \$HELP,
                                      'file:s' => \$FILE,
                                      'foo!'   => \$FOO,
                                      'num:i'  => \$NO,
                                     ]);

or an alternative Getopt::Long interface

    %optctl = ('foo' => \$foo,
               'bar' => \$bar);
    $opt = new Tk::Getopt(-getopt => [\%optctl, "foo!", "bar=s"]);

DESCRIPTION

Unlike Getopt::Long, this package uses a object oriented interface, so you have to create a new Tk::Getopt object with new. Unlike other packages in the Tk hierarchy, this package does not define a Tk widget. The graphical interface is calles by the method option_editor.

After creating an object with new, you can parse command line options by calling get_options. This method calls itself Getopt::Long::GetOptions.

METHODS

new Tk::Getopt(arg_hash)

Constructs a new object of the class Tk::Getopt. Arguments are passed in a hash (just like Tk widgets and methods). There are many variants to specify the option description. You can use an interface similar to Getopt::Long::GetOptions by using -getopt or a more powerful interface by using -opttable. Internally, the option description will be converted to the -opttable interface. One of the arguments -getopt or -opttable are mandatory.

The arguments for new are:

set_defaults

Sets default values. This only applies if the -opttable variant is used.

load_options(filename)

Loads options from file filename, or, if not specified, from object's filename as specified in new. The loading is done in a safe compartment ensure security.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. Since saving may fail, you should call this method inside of "eval {}" and check $@. Possible exceptions are "No Data::Dumper" (cannot find the Data::Dumper module) and "Writing failed" (cannot write to file).

get_options

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

If you want to process options which does not appear in the GUI, you have two alternatives:

usage

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

process_options([undo_hash])

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

option_editor(widget, [arguments ...])

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

The option editor is non-modal. For a modal dialog, see below for the "option_dialog" method.

The first argument is the parent widget. Further optional arguments are passed as a hash:

option_dialog(widget, [arguments ...])

This method works like "option_editor", but it shows the option editor as a modal dialog. Additionaly, the return value is either ok or cancel depending on how the user quits the editor.

OPTTABLE ARGUMENTS

alias

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

callback

Call a subroutine every time the option changes (e.g. after pressing on Apply, Ok or after loading). The callback will get a hash with the following keys as argument:

callback-interactive

Like "callback", but only applies in interactive mode.

label

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

help

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

longhelp

A long help string used by option_editor.

choices

An array of additional choices for the option editor.

If "strict" is set to a true value, then the elements of choices may also contain array references. In this case the first value of the "sub" array references are the display labels and the second value the used value. This is similar to Tk::Optionmenu (in fact, for displaying this option an Optionmenu is used).

     choices => ["one", "two", "three"]

     choices => [["english"  => "en"],
                 ["deutsch"  => "de"],
                 ["hrvatski" => "hr"]]
    

range

An array with the beginning and end of a range for an integer or float value.

strict

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

subtype

Valid subtypes are file, savefile, dir, geometry, font and color. These can be used with string options. For file and savefile, the GUI interface will pop up a file dialog, using getOpenFile for the former and getSaveFile for the latter. For dir, the GUI interface will pop up a dialog for selecting directories (using either Tk::chooseDirectory, Tk::DirSelect, or a custom dialog built on top of Tk::DirTree). If the geometry subtype is specified, the user can set the current geometry of the main window. The color subtype is not yet implemented.

var

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

nogui

This option will not have an entry in the GUI.

size

Create an entry with the specified size.

maxlength

Restrict the maximum number of characters in entries.

widget

This should be a reference to a subroutine for creating an own widget. Folowing arguments will be passed to this subroutine: a reference to the Tk::Getopt object, Frame object, and the options entry. The options entry should be used to get the variable reference with the "_varref" method. The subroutine should create a widget in the frame (packing is not necessary!) and should return a reference to the created widget.

A sample with an opttable entry for a custom numeric entry using the CPAN module Tk::NumEntry:

   ['numentry', '=i', 50,
    range => [0, 100],
    widget => sub { numentry_widget(@_) },
   ],
    

And "numentry_widget" defined as:

    use Tk::NumEntry;
    sub numentry_widget {
        my($self, $frame, $opt) = @_;
        my $v = $self->varref($opt);
        $frame->NumEntry(-minvalue => $opt->[3]{range}[0],
                         -maxvalue => $opt->[3]{range}[1],
                         -variable => $v,
                         -value => $$v,
                        );
    }
    

Here is an example for using a complex opttable description:

    @opttable =
        ('Misc',   # Head of first group
         ['debug', # name of the option (--debug)
          '!',     # type boolean, accept --nodebug
          0,       # default is 0 (false)
          callback => sub { $^W = 1
                                if $options->{'debug'}; }
          # additional attribute: callback to be called if
          # you set or change the value
          ],
         ['age',
          '=i',    # option accepts integer value
          18,
          strict => 1, # value must be in range
          range => [0, 100], # allowed range
          alias => ['year', 'years'] # possible aliases
          ],
         'External', # Head of second group
         ['browser',
          '=s',    # option accepts string value
          'tkweb',
          choices => ['mosaic', 'netscape',
                      'lynx', 'chimera'],
          # choices for the list widget in the GUI
          label => 'WWW browser program'
          # label for the GUI instead of 'browser'
          ],
         ['foo',
          '=f',    # option accepts float value
          undef,   # no default value
          help => 'This is a short help',
          # help string for usage() and the help balloon
          longhelp => 'And this is a slightly longer help'
          # longer help displayed in the GUI's help window
          ]);

OPTION ENTRY METHODS

varref(optentry)

Return the variable reference for this entry.

optextra(optentry, optarg)

Return the value for the specified optarg argument. See the "OPTTABLE ARGUMENTS" section above for a list of possible arguments.

COMPATIBILITY

  sub opttable_to_getopt {
      my(%args) = @_;
      my $options = $args{-options};
      my @getopt;
      for (@{$args{-opttable}}) {
        if (ref $_) {
            push @getopt, $_->[0].$_->[1];
            if (defined $_->[3] and ref $_->[3] ne 'HASH') {
                my %h = splice @$_, 3;
                $_->[3] = \%h;
            }
            if ($_->[3]{'var'}) {
                push @getopt, $_->[3]{'var'};
            } else {
                push @getopt, \$options->{$_->[0]};
            }
        }
      }
      @getopt;
  }

REQUIREMENTS

• perl5.004 (perl5.003 near 5.004 may work too, e.g perl5.003_26)
• Tk400.202 (better: Tk800.007) (only if you want the GUI)
• Data-Dumper-2.07 (only if you want to save options and it's anyway standard in perl5.005)

BUGS

    my %options;
    my $opt = new Tk::Getopt(-options => \%options ...)

or

    my $options = {};
    my $opt = new Tk::Getopt(-options => $options ...)

Note the initial assignement for $options in the second example.

Not all of Getopt::Long is supported (array and hash options, <>, abbrevs).

The option editor probably should be a real widget.

The option editor window may grow very large if NoteBook is not used (should use a scrollable pane).

If the user resizes the window, the buttons at bottom may disappear. This is confusing and it is advisable to disallow the resizing:

    $opt_editor = $opt->option_editor;
    $opt_editor->resizable(0,0);

The API will not be stable until version 1.00.

This manual is confusing. In fact, the whole module is confusing.

Setting variables in the editor should not set immediately the real variables. This should be done only by Apply and Ok buttons.

There's no -font option (you have to use tricks with the option db and a special Name for the option editor):

    $top->optionAdd("*somename*font" => $font);
    $opt->option_editor(Name => "somename", ...);

There's no (easy) way to get a large option editor fit on small screens. Try -font, if it would exist, but see above.

AUTHOR

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

SEE ALSO