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

SYNOPSIS
 use Tk::SettingsDialog;
 # We'd like to confirm a few options
 # before running ReportToAcmeChief.pl:
 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!");
 $SD->AddVar("TESTING", \$TESTING, $SD->Bool());
 $SD->AddListVariable("Report Range", \$ReportRange, \@ReportRanges);
 $SD->AddVar("Starting Date", \$StartDate, $SD->DateType());
 $SD->AddVar("Email report to:", \$MailTo, $SD->String());
 # DoDialog/DumpValues to STDERR until you say 'y' or 'quit'.
 $SD->DoDialogUntilHappy(); 
 # 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...

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

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

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
or something ambiguous then you should explicitly supply the type as
the third argument to AddVar(). Use AddListVar() when you want to
restrict choices to a dropdown list. You can set variables that
represent a bool, int, float, string, date, color, file path, or
choice from a list that you supply. And you can also add a blank (for
spacing). AddHelp($text) adds a Help button to the dialog that shows
$text in a separate window.

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
call DoDialog() (or if you're nervous, DoDialogUntilHappy()), pick the
values you want in the dialog, and click OK. DumpValues() will print
out your variables after setting them in the dialog, with changes
marked.

Main functions: new('window title'): make a SettingsDialog AddVar:
pass description, reference to variable, type of variable -
StringType() takes two lines in the dialog, one for description and
one for value. AddListVar: pass description, reference to variable,
ref to array holding list AddNote: if you want a brief description at
top of dialog 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, repeated until you say 'y' or 'exit'.

EXAMPLES
 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 = "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 1 or 0", \$YesNo, $SD->Bool());
 $SD->AddVar("Integer variable to set", \$IntVariable, $SD->Whole());
 $SD->AddVar("FP variable to set", \$FloatVariable, $SD->Float());
 $SD->AddVar("String variable:", \$dummyStringParam, $SD->String());
 $SD->AddVar("Another string:", \$dummyStringParam2, $SD->String());
 $SD->NewColumn();
 $SD->AddBlank();
 $SD->AddListVariable("List variable", \$valueFromList, \@DummyList);
 $SD->AddVar("Test of a date variable", \$dummyDate, $SD->DateType());
 $SD->AddVar("Color variable", \$dummyColor, $SD->ColorType());
 $SD->AddVar("Pick yourself a file to play with", \$dirInFileOut);
 $SD->DoDialog(); # shows window where above variables can be changed
 # Print values of above variables after setting, to STDERR
 $SD->DumpValues();

 If all of your params are in a hash, with readable keys:
 use Tk::SettingsDialog;
 my %ConfigValues = (
                    'TESTING'         => 0,
                    'NUMBER OF PASSES'    => 3,
                    'REPORT TITLE'      => 'Acme Report',
                    'START DATE'      => '2010/09/01',
                    'ALT LINE COLOR'    => '#eeeeee',
                    # ... 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{$key});
    }
 $SD->DoDialog(); # view/change all %ConfigValues default values
 $SD->DumpValues();# prints above vars after setting, to STDERR

METHODS
`new($title)'

  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 1 or 0", \$YesNo, $SD->Bool());

`IntegerType() or Int() or Whole()'

  Whole number: 0 1 2 ...
  my $IntVariable = 1;
  $SD->AddVar("Integer variable", \$IntVariable, $SD->Whole());

`NumberType() or Number() or Float()'

  Floating point (exponent allowed).
  my $FloatVariable = 3.5;
  $SD->AddVar("FP variable to be set", \$FloatVariable, $SD->Float());

`StringType() or String()'

  Arbitrary string.
  my $dummyStringParam = "This is a dummy string value";
  $SD->AddVar("Set string", \$dummyStringParam, $SD->String());

`ColorType() or Color()'

  Tk color, eg '#ff88aa'.
  my $dummyColor = '#d0bbee'; # wasn't he in Harry Potter?
  $SD->AddVar("Colour variable", \$dummyColor, $SD->ColorType());

`ListType() or List()'

  Choice from list: note list must be added via AddListVar,
  not AddVar.
  my @DummyList = ('one', 'two', 'three', 'four');
  my $valueFromList = 'two';
  $SD->AddListVariable("Set list var", \$valueFromList, \@DummyList);

`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 date variable", \$dummyDate, $SD->DateType());

`FileType() or File() or FilePath() or FullPath()'

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

`Blank()'

  Blank placeholder, just for alignment.
  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

`NewColumn()'

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

`AddVariable($description, $valueRef, $type)'

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

`AddVar($description, $valueRef, $type)'

  Just a synonym for AddVariable.

`AddBlank()'

  Add a blank entry, to adjust spacing.
  $SD->AddBlank();
  [$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
  dropdown 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("Pick from menu", \$valueFromList, \@SomeList);

`AddListVar($description, $valueRef, $list)'

  A synonym for AddListVariable.

`AddNote($note)'

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

`AddHelp($helpText)'

  Very long note? Use AddHelp() instead of AddNote(), and the text
  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.

`DoDialog()'

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

`DoDialogUntilHappy()'

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

`DumpValues()'

  Print all variable values to STDERR.
  Changed ones are marked with '***'.
  Called by DoDialogUntilHappy, or call this yourself after DoDialog.
  $SD->DumpValues();

AUTHOR
Ken Earle (ken.earle@dewtell.com)

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

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

SEE ALSO
Tk::Getopt - User configuration window for Tk with interface to
Getopt::Long
[download]