| Tk::Getopt - User configuration window for Tk with interface to Getopt::Long |
Tk::Getopt - User configuration window for Tk with interface to Getopt::Long
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"]);
Tk::Getopt provides an interface to access command line options via Getopt::Long and editing with a graphical user interface via a Tk window.
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.
The arguments for new are:
Example:
new Tk::Getopt(-getopt => [\%options,
"opt1=i", "opt2=s" ...]);
=s for string, =i for integer,
! for boolean, =f for float etc., see the Getopt::Long manpage) for a
detailed list. The third element is optional and contains the default
value (otherwise the default is undefined). Further elements are
optional too and describe more attributes. For a complete list of
these attributes refer to OPTTABLE ARGUMENTS.
If an option has no name, then the third element in the description array will be used as an global message for the current option page. This message can be multi-line. Example: ['', '', 'This is an explanation for this option group.']
To insert horizontal lines, use: ['', '', '-']
Here is an example for a simple opttable:
@opttable =
('First section',
['', '', 'Section description'],
['debug', '!', 0],
['age', '=i', 18],
'Second section',
['', '', 'Description for 2nd section'],
['browser', '=s', 'tkweb'],
['foo', '=f', undef],
);
new Tk::Getopt(-opttable => \@opttable,
-options => \%options);
eval {} and check $@. Possible exceptions are No Data::Dumper
(cannot find the Data::Dumper module) and Writing failed (cannot
write to file).
If you want to process options which does not appear in the GUI, you have two alternatives:
new constructor and mark all
non-GUI options with nogui, e.g.
new Tk::Getopt(-opttable => ['not-in-gui', '!', undef,
nogui => 1], ...)
Example:
use Tk::Getopt;
use Getopt::Long;
$Getopt::Long::passthrough = 1;
GetOptions('options!' => \$preloadopt);
$Getopt::Long::passthrough = 0;
$opt = new Tk::Getopt( ... );
$opt->get_options;
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:
saveoptions method, use the specified variable
reference instead of the -var reference. This is useful if -var
is a subroutine reference.
-buttons => [qw/ok apply cancel undo lastsaved save defaults/]
A minimal set could look like (here OK means accept and save)
-buttons => [qw/oksave cancel/]
(and using less buttons is recommended).
Frame to embed the editor into another toplevel
widget (do not forget to pack the frame!). See also the -pack
option below.
-transient => $mw
-toplevel with a non-Toplevel widget (e.g. Frame) and
using the -wait option, then packing have to be done through the
-pack option. The argument to this option is a array reference of
pack options, e.g.
$opt->option_editor(-toplevel => "Frame",
-wait => 1,
-pack => [-fill => "both", -expand => 1]);
optedit,
undo, lastsaved, save, defaults, ok, cancel,
helpfor.
Since the option editor uses the NoteBook widget, options may be
grouped in several pages. Grouping is only possible if using the
-opttable variant of new. Help messages are shown in balloons and,
if specified, in a statusbar.
option_editor returns a reference to the created window.
Note: this method returns immediately to the calling program.
Buttons in the option editor window:
new.
new.
The option types are translated to following widgets:
Additional attributes in an option description have to be key-value pairs with following keys:
callback, but only applies in interactive mode.
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 the Tk::Optionmenu manpage (in fact, for
displaying this option an Optionmenu is used).
choices => ["one", "two", "three"]
choices => [["english" => "en"],
["deutsch" => "de"],
["hrvatski" => "hr"]]
_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 the Tk::NumEntry manpage:
['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
]);
These methods operate on option entries:
The argument to -opttable can be converted to a Getopt::Long
compatible argument list with the following function:
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;
}
You need at least:
Be sure to pass a real hash reference (not a uninitialized reference)
to the -options switch in new Tk::Getopt. Use either:
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.
Slaven Rezic <slaven@rezic.de>
This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl Getopt::Long Data::Dumper Tk Tk::FileDialog Tk::NoteBook Tk::Tiler Safe
| Tk::Getopt - User configuration window for Tk with interface to Getopt::Long |