GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TK::GETOPT (3)

.ds Aq ’

NAME

Tk::Getopt - User configuration window for Tk with interface to Getopt::Long

CONTENTS

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

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 <B>newB>. Unlike other packages in the Tk hierarchy, this package does not define a Tk widget. The graphical interface is calles by the method <B>option_editorB>.

After creating an object with <B>newB>, you can parse command line options by calling <B>get_optionsB>. This method calls itself <B>Getopt::Long::GetOptionsB>.

METHODS

<B>new Tk::Getopt(B>arg_hash<B>)B> 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 <B>Getopt::Long::GetOptionsB> by using <B>-getoptB> or a more powerful interface by using <B>-opttableB>. Internally, the option description will be converted to the <B>-opttableB> interface. One of the arguments <B>-getoptB> or <B>-opttableB> are mandatory.

The arguments for <B>newB> are:
-getopt <B>-getoptB> should be a reference to a hash or an array. This hash has the same format as the argument to the <B>Getopt::Long::GetOptionsB> function. Look at Getopt::Long for a detailed description. Note also that not all of <B>GetOptionsB> is implemented, see BUGS for further information.

Example:



    new Tk::Getopt(-getopt => [\%options,
                               "opt1=i", "opt2=s" ...]);



-opttable <B>-opttableB> provides a more powerful interface. The options are stored in variables named $opt_XXX or in a hash when <B>-optionsB> is given (see below). <B>-opttableB> should be a reference to an array containing all 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 (=s for string, =i for integer, ! for boolean, =f for float etc., see Getopt::Long) 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);



-options This argument should be a reference to an (empty) hash. Options are set into this hash. If this argument is missing, options will be stored in variables named $opt_XXX.
-filename This argument is optional and specifies the filename for loading and saving options.
-nosafe If set to true, do not use a safe compartment when loading options (see <B>load_optionsB>).
-useerrordialog If set to true, then use an error dialog in user-relevant error conditions. Otherwise, the error message is printed to STDERR. This only includes errors which may happen in normal operation, but not programming errors like specifying erroneous options. If no Tk context is available (i.e. there is no MainWindow), then the error message will also be printed to STDERR.

<B>set_defaultsB> Sets default values. This only applies if the <B>-opttableB> variant is used.
<B>load_options(B>filename<B>)B> Loads options from file <B>filenameB>, or, if not specified, from object’s filename as specified in <B>newB>. The loading is done in a safe compartment ensure security.The loaded file should have a reference to a hash named $loadoptions.
<B>save_options(B>filename<B>)B> Writes options to file <B>filenameB>, or, if not specified, from object’s filename as specified in <B>newB>. 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).
<B>get_optionsB> Gets options via <B>GetOptionsB>. Returns the same value as <B>GetOptionsB>, 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:
o Use the <B>-opttableB> variant of the new constructor and mark all non-GUI options with <B>noguiB>, e.g.



    new Tk::Getopt(-opttable => [not-in-gui, !, undef,
                                 nogui => 1], ...)



o Use Getopt::Long::passthrough and process non-GUI options directly with <B>Getopt::Long::GetOptionsB>. The remaining args can be passed to <B>get_optionsB>.

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;



<B>usageB> Generates an usage string from object’s opttable. The usage string is constructed from the option name, default value and help entries.
<B>process_options(B>[undo_hash]<B>)B> Checks wheather given values are valid (if <B>strictB> is set) and calls any callbacks specified by the <B>subB> option. If <B>undo_hashB> is given and the new value of an option did not change, no sub is called.
<B>option_editor(B>widget, [arguments ...]<B>)B> 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:
-callback Execute additional callback after creating the option editor. Arguments passed to this callback are: reference to the Tk::Getopt object and a reference to the option editor window.
-nosave Disable saving of options.
-savevar When saving with the saveoptions method, use the specified variable reference instead of the -var reference. This is useful if -var is a subroutine reference.
-buttons Specify, which buttons should be drawn. It is advisable to draw at least the OK and Cancel buttons. The default set looks like this:



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

-toplevel Use another widget class instead of <B>ToplevelB> for embedding the option editor, e.g. Frame to embed the editor into another toplevel widget (do not forget to pack the frame!). See also the -pack option below.
-transient Set the transient flag on the toplevel window. See the description of the transient method in Tk::Wm.



    -transient => $mw



-pack If using -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]);



-statusbar Use an additional status bar for help messages.
-string Change button labels and title. This argument should be a hash reference with all or a subset of the following keys: optedit, undo, lastsaved, save, defaults, ok, cancel, helpfor.
-wait Do not return immediately, but rather wait for the user pressing OK or Cancel.
-page Raise the named notebook page (if grouping is used, see below).

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.

<B>option_editorB> returns a reference to the created window.

Note: this method returns immediately to the calling program.

Buttons in the option editor window:
OK Accept options and close option editor window.
Cancel Set old values and close option editor window.
Undo Set old values. Further selections toggle between new and old values.
Last saved Set last saved options. This button is not displayed if no filename was given in new.
Save Save options to file. This button is not displayed if no filename was given in new.

The option types are translated to following widgets:
Boolean <B>CheckbuttonB> (<B>_boolean_widgetB>)
Integer and Float <B>ScaleB>, if <B>rangeB> is set, otherwise either <B>BrowseEntryB> or <B>EntryB> (<B>_integer_widgetB>, <B>_float_widgetB>).
String <B>BrowseEntryB> if <B>choicesB> is set, otherwise <B>entryB> (<B>_string_widgetB>). <B>FileDialogB> if <B>subtypeB> is set to <B>fileB>.

<B>option_dialog(B>widget, [arguments ...]<B>)B> This method works like option_editor, but it shows the option editor as a modal dialog. Additionaly, the return value is either <B>okB> or <B>cancelB> depending on how the user quits the editor.

OPTTABLE ARGUMENTS

Additional attributes in an option description have to be key-value pairs with following keys:
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:
optdef The opttable item definition for this option.
bag A hash reference which is persistent for this process_options call. This can be used to share state between multiple callbacks.
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 <B>usageB> and the Balloon help facility in <B>option_editorB>.
longhelp A long help string used by <B>option_editorB>.
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 <B>choicesB> or <B>rangeB>. 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 GUIs help window
          ]);



OPTION ENTRY METHODS

These methods operate on option entries:
<B>varref(B>optentry<B>)B> Return the variable reference for this entry.
<B>optextra(B>optentry, optarg<B>)B> Return the value for the specified optarg argument. See the OPTTABLE ARGUMENTS section above for a list of possible arguments.

COMPATIBILITY

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;
  }



REQUIREMENTS

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

BUGS

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.

AUTHOR

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.

SEE ALSO

perl Getopt::Long Data::Dumper Tk Tk::FileDialog Tk::NoteBook Tk::Tiler Safe
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 GETOPT (3) 2008-09-23

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.