RFC: Tk::SettingsDialog

Do you have a question? Post it now! No Registration Necessary.  Now with pictures!

SettingsDialog lets you add a simple settings dialog at the
beginning of a Perl script, for showing and setting the arguments
to the script. Before I attempt to submit this (my first module) to
CPAN, please tell me what you think.

A picture might help, you can find one of a slightly older version of
SettingsDialog at

Typically to set up the dialog you write one line per variable, eg
$sd->AddVariable("Report starting date", $report_start_date, $sd-
Quoted text here. Click to load it
 - which would show a date picker labelled "Report starting date" in
the dialog.

Variable "types" can be restricted to bool, int, date, color, file
path, etc,
and dropdown menus are shown for values to be selected from a list.
Each variable can have a brief explanation beside it, which I
personally need for scripts that I wrote more than six months ago and
haven't run since.

Full docs are below. Thanks for your time, hope you enjoy.

    Tk-SettingsDialog - an easy settings dialog for your perl script.

     use Tk::SettingsDialog;
     # We'd like to confirm a few options before running
     my $TESTING = 0;
     my @ReportRanges = ('Weekly', 'Monthly', 'Quarterly');
     my $ReportRange = 'Monthly';
     my $StartDate = '2010/09/01'; #YYYY/MM/DD
     my $MailTo = 'marv.ellis@acme.com';
     my $SD = SettingsDialog->new('Acme Report Config');
     $SD->AddNote("Confirm or change these before running!"); # shows
at top of dialog
     $SD->AddVar("TESTING", $TESTING, $SD->Bool());
     $SD->AddListVariable("Report Range", $ReportRange,
     $SD->AddVar("Starting Date", $StartDate, $SD->DateType());
     $SD->AddVar("Email report to:", $MailTo, $SD->String());
     $SD->DoDialogUntilHappy(); # DoDialog/DumpValues to STDERR until
you say 'y' or 'quit'.
     # After adjusting values and clicking OK in the dialog:
     #TESTING: |0|
     #*** Report Range: |Weekly|
     #*** Starting Date: |2010/09/20|
     #*** Email report to: |eta.hare@acme.com|
     #Are you happy with the values? (y/n/quit)
     ...program carries on if you type y, dialog repeats if n...

    Tk::SettingsDialog - slaps a simple dialog interface on the front
end of
    a perl program, so you can confirm or change its arguments. And
    forget to set an argument, or forget what it's for.

    A SettingsDialog is especially handy with batch programs that have
    complicated setup, or ones that you don't run very often. And it's
    fun than just typing the values on the command line and crossing

    Adding a variable to the dialog typically takes one line of code.
    AddVar() is used for most variables, and if you omit the type (int
    string etc) then SettingsDialog will usually guess the correct
type for
    you - but if it's a bool (0/1), or a string that contains a number
    something ambiguous then you should explicitly supply the type as
    third argument to AddVar(). Use AddListVar() when you want to
    choices to a dropdown list. You can set variables that represent a
    int, float, string, date, color, file path, or choice from a list
    you supply. And you can also add a blank (for spacing).
    adds a Help button to the dialog that shows $text in a separate

    All of your variables are passed to SettingsDialog by reference,
and all
    of the layout is taken care of for you, so all that remains is to
    DoDialog() (or if you're nervous, DoDialogUntilHappy()), pick the
    you want in the dialog, and click OK. DumpValues() will print out
    variables after setting them in the dialog, with changes marked.

    Main functions: new('window title'): make a SettingsDialog AddVar:
    description, reference to variable, type of variable -
    takes two lines in the dialog, one for description and one for
    AddListVar: pass description, reference to variable, ref to array
    holding list AddNote: if you want a brief description at top of
    DoDialog: dialog to show and set values for all variables added
    DumpValues: show values after setting - Dumped values show changed
    values with *** DoDialogUntilHappy: DoDialog/DumpValues loop,
    until you say 'y' or 'exit'.

     Here's an example showing just about everything:
     use Tk::SettingsDialog;
     # Some pretend arguments to our program 'BigBatch.pl':
     my $YesNo = 0; # ...or my $YesNo = shift @ARGV;...
     my $IntVariable = 1;
     my $FloatVariable = 3.5;
     my $dummyStringParam = "This is a dummy string value\nspread over
two lines";
     my $dummyStringParam2 = "The boy stood on the burning deck...";
     my @DummyList = ('one', 'two', 'three', 'four');
     my $valueFromList = 'two';
     my $dummyDate = '2008/11/27'; # note format must be yyyy/mm/dd
     my $dummyColor = '#d0bbee';
     my $dirInFileOut = 'C:/Perl/html';
     # - and now the dialog to confirm or change those:
     my $SD = Tk::SettingsDialog->new('BigBatch Config');
     $SD->AddNote("Check ALL of these!"); # shows at top of window
     $SD->AddVar("Boolean variable to be set to 1 or 0", $YesNo, $SD-
Quoted text here. Click to load it
     $SD->AddVar("Integer variable to be set", $IntVariable, $SD-
Quoted text here. Click to load it
     $SD->AddVar("FP variable to be set", $FloatVariable, $SD-
Quoted text here. Click to load it
     $SD->AddVar("Test of a string variable:", $dummyStringParam, $SD-
Quoted text here. Click to load it
     $SD->AddVar("Another string, this time on one line:", \
$dummyStringParam2, $SD->String());
     $SD->AddListVariable("Test of a list variable", $valueFromList,
     $SD->AddVar("Test of a date variable", $dummyDate, $SD-
Quoted text here. Click to load it
     $SD->AddVar("Test of a color variable", $dummyColor, $SD-
Quoted text here. Click to load it
     $SD->AddVar("Pick yourself a nice file to play with", \
     $SD->DoDialog(); # shows window where above variables can be
     $SD->DumpValues();# prints values of above variables after
setting, to STDERR

     If all of your params are in a hash, with readable keys:
     use Tk::SettingsDialog;
     my %ConfigValues = (
                                            'TESTING'               =>
                                            'NUMBER OF PASSES'      =>
                                            'REPORT TITLE'          =>
'Acme Report',
                                            'START DATE'            =>
                                            'ALT LINE COLOR'        =>
                                            # ... etc
     my $SD = Tk::SettingsDialog->new('BigBatch %ConfigValues');
     $SD->AddNote("CHECK ALL config values before running.");
     foreach my $key (sort keys %ConfigValues)
            # 'START DATE' will use the date picker, 'REPORT TITLE'
will be a string etc.
            $SD->AddVar($key, $ConfigValues);
     $SD->DoDialog(); # view/change all %ConfigValues default values
     $SD->DumpValues();# prints values of above variables after
setting, to STDERR

        Make a new SettingsDialog instance, optional window title.
        my $SD = Tk::SettingsDialog->new('Title of My Nifty Program');

  "BooleanType() or Bool()"
         NOTE the variable type can be left out when calling AddVar
for all except
        Bool variables, but results might not be perfect - a string
with initial
        value of '2009/01/07' will be treated as a date, for example.
        Boolean: 1 0
        my $YesNo = 0;
        $SD->AddVar("Bolean variable to be set to 1 or 0", $YesNo,

  "IntegerType() or Int() or Whole()"
        Whole number: 0 1 2 ...
        my $IntVariable = 1;
        $SD->AddVar("Integer variable to be set", $IntVariable, $SD-
Quoted text here. Click to load it

  "NumberType() or Number() or Float()"
        Floating point (exponent allowed).
        my $FloatVariable = 3.5;
        $SD->AddVar("FP variable to be set", $FloatVariable, $SD-
Quoted text here. Click to load it

  "StringType() or String()"
        Arbitrary string.
        my $dummyStringParam = "This is a dummy string value";
        $SD->AddVar("Test of a string variable", $dummyStringParam,

  "ColorType() or Color()"
        Tk color, eg '#ff88aa'.
        my $dummyColor = '#d0bbee'; # wasn't he in Harry Potter?
        $SD->AddVar("Test of a colour variable", $dummyColor, $SD-
Quoted text here. Click to load it

  "ListType() or List()"
        Choice from list: note list must be added via AddListVar, not
        my @DummyList = ('one', 'two', 'three', 'four');
        my $valueFromList = 'two';
        $SD->AddListVariable("Test of list variable", $valueFromList,

  "DateType() or Date() or YMD()"
        Date: NOTE date must be 'yyyy/mm/dd/'
        my $dummyDate = '2008/11/27'; # note format must be yyyy/mm/dd
        $SD->AddVar("Test of a date variable", $dummyDate, $SD-
Quoted text here. Click to load it

  "FileType() or File() or FilePath() or FullPath()"
        File (path).
        my $dirInFileOut = 'C:/Perl/html'; # pass directory, set path
in dialog
        $SD->AddVar("Pick a file", $dirInFileOut, $SD->FileType());

        Blank placeholder, just for alignment. If you're fussy about
such things....
        Pass undef as the $valueRef, eg
        $SD->AddVar("", undef, $SD->Blank());
        or you can leave out the type
        $SD->AddVar("", undef);
        or even leave out all args
        $SD->AddVar(); # $kBLANK by default

        If you have a LOT of variables, you can add a column on the
        NewColumn: after this call, AddVar and AddListVar entries will
        appear in the new column on the right, starting at the top.

  "AddVariable($description, $valueRef, $type)"
        Use to add all types except $kLIST to dialog. See example at
file top.
        OK, here's one example:
        my $IntVariable = 1;
        $SD->AddVar("Integer variable to be set", $IntVariable, $SD-
Quoted text here. Click to load it
        The '$type' such as $SD->Int(), is optional EXCEPT for -
Quoted text here. Click to load it
        but it's safer to supply it.

  "AddVar($description, $valueRef, $type)"
        Just a synonym for AddVariable.

        Add a blank entry, to adjust spacing.
        [$SD->AddVar(); also works.]

  "AddBool($description, $valueRef)"
        "Boolean" is the only type where type inference can't be done,
        so for clarity you can call this function instead of AddVar.
        my $IsItRaining = 0;
        $SD->AddBool("Is is raining?", $IsItRaining);
        Using AddVar instead:
        $SD->AddVar("Is is raining?", $IsItRaining, $SD->Bool());

  "AddBoolean($description, $valueRef)"
        A synonym for AddBool.

  "AddListVariable($description, $valueRef, $list)"
        Add variable, with values from a list (forces type to $kLIST).
        In the dialog you can pick a value for the variable from the
        list, or type anything you want. The initial value doesn't
have to be
        on the list either.
        my @SomeList = ('one', 'two', 'three', 'four');
        my $valueFromList = 'two';
        $SD->AddListVariable("Test of a list variable", \
$valueFromList, \@SomeList);

  "AddListVar($description, $valueRef, $list)"
        A synonym for AddListVariable.

        Only one note can be added - shown at top of window.

        Very long note? Use AddHelp() instead of AddNote(), and the
        instructions will be shown in a new window called
"Instructions and help"
        when user clicks the Help button.
        If AddHelp() is not called, no Help button is shown.

        Do the setting dialog, for all added variables and lists.

        Show setting dialog, dump values, ask for confirmation and
repeat while
        answer is not 'y'. Die if reply contains certain words (stop
exit die).

        Print all variable values to STDERR. Changed ones are marked
with '***'.
        Called by DoDialogUntilHappy, or call this yourself after

    Ken Earle (ken.earle@dewtell.com)

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

    Nothing special, but note you'll be pulling in Tk when you install

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

Site Timeline