NAME

Term::Screen::Wizard - A wizard on your terminal...

SYNOPSIS

        use Term::Screen::Wizard;

        $scr = new Term::Screen::Wizard;

        $scr->clrscr();

        $scr->add_screen(
              NAME => "PROCES",
              HEADER => "Give me the new process id",
              CANCEL => "Esc - Annuleren",
              NEXT   => "Ctrl-Enter - Volgende",
              PREVIOUS => "F3 - Vorige",
              FINISH => "Ctrl-Enter - Klaar",
              PROMPTS => [
                 { KEY => "PROCESID", PROMPT => "Proces Id", LEN=>32, VALUE=>"123456789.00.04" , ONLYVALID => "[a-zA-Z0-9.]*" },
                 { KEY => "TYPE", PROMPT => "Intern or Extern Process (I/E)", CONVERT => "up", LEN=>1, ONLYVALID=>"[ieIE]*" },
                 { KEY => "OMSCHRIJVING", PROMPT => "Description of Proces", LEN=>75 },
                 { KEY => "PASSWORD", PROMPT => "Enter a password", LEN=>14, PASSWORD=>1 }
                        ],

# # OK This helptext is in Dutch, but it's clear how it works isn't it? # HELPTEXT => "\n\n\n". " In dit scherm kan een nieuw proces Id worden opgevoerd\n". "\n". " ProcesId - is het ingevoerde Proces Id\n". " Intern/Extern - is het proces belastingdienst intern of niet?\n". " Omschrijving - Een korte omschrijving van het proces.\n" );

        $scr->add_screen(
           NAME => "X.400",,
           HEADER => "Voer het X.400 adres in",
#
# So the point is you can change the Wizard 'buttons'.
#
           CANCEL => "Esc - Annuleren",
           NEXT   => "Ctrl-Enter - Volgende",
           PREVIOUS => "F3 - Vorige",
           FINISH => "Ctrl-Enter - Klaar",
           PROMPTS => [
             { KEY => "COUNTRY", PROMPT => "COUNTRY", LEN => 2, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "AMDM",    PROMPT => "AMDM",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "PRDM",    PROMPT => "PRDM",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "ORG",     PROMPT => "ORGANISATION",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "OU1",     PROMPT => "UNIT1",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "OU2",     PROMPT => "UNIT2",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
             { KEY => "OU3",     PROMPT => "UNIT3",    LEN => 16, CONVERT => "up", ONLYVALID => "[^/]*" },
           ],
           HELPTEXT => "\n\n\n".
                   "  In dit scherm kan een standaard X.400 adres worden ingevoerd voor een ProcesId",
        );

        $scr->add_screen(
           NAME => "GETALLEN",,
           HEADER => "Voer getallen in",
           CANCEL => "Esc - Annuleren",
           NEXT   => "Ctrl-Enter - Volgende",
           PREVIOUS => "F3 - Vorige",
           FINISH => "Ctrl-Enter - Klaar",
           PROMPTS => [
             { KEY => "ANINT",     PROMPT => "INT",     LEN => 10, CONVERT => "up", ONLYVALID => "[0-9]*" },
             { KEY => "ADOUBLE",  PROMPT => "DOUBLE",  LEN => 16, CONVERT => "up", ONLYVALID => "[0-9]+([.,][0-9]*)?" },
           ],
        );

        $scr->wizard();

        $scr->wizard("PROCES","GETALLEN");

        $scr->clrscr();

        %values=$scr->get_keys();
        @array=( "PROCES", "X.400", "GETALLEN" );

        for $i (@array) {
          print "\n$i\n\r";
          for $key (keys % { $values{$i} }) {
            my $val=$values{$i}{$key};
            print "  $key=$val\n\r";
          }
        }

        %values=$scr->get_keys("X.400","PROCES");

        exit;

DESCRIPTION

This is a module to have a Wizard on a Terminal. It inherits from Term::Screen::ReadLine. The module provides some functions to add screens. The result is a Hash with keys that have the (validated) values that the used inputted on the different screens.

USAGE

Description of the interface.

 add_screen(
    NAME      => <name of screen>,
    HEADER    => <header to put on top of screen>,
    CANCEL    => <text of cancel 'button', defaults to 'Esc - Cancel'>,
    NEXT      => <text of next 'button', defaults to 'Ctrl-Enter - Next'>,
    PREVIOUS  => <text of previous 'button', defaults tro 'PgUp - Previous'>,
    FINISH    => <text of finish 'button', defaults to 'Ctrl-Enter - Finish>,
    HELP      => <text of help 'button', defaults to 'F1 - Help'>,
    HELPTEXT  => <text to put on your helpscreen>
    NOFINISH  => <1/0 - Inidicates that this wizard is/is not (1/0) part
                        of an ongoing 'wizard sequence'>
    READONLY  => <1/0 - read only option to get a read only screen>
    PROMPTS   => <array of fields to input>
 )

   This function add's a screen to the list of screens that the wizards goes
   through sequentially. If NOFINISH==1, the finish 'button' is not used. Use
   this, if the last screen of this wizard is not actually the last screen
   of a sequence of wizards.

   For instance, if you need to go one way or the other after the first screen,
   you provide a wizard with one screen and no FINISH button. After that you
   call the next sequence of screens.

           PROMPTS => [
             { KEY => "ANINT",     PROMPT => "INT",     LEN => 10, CONVERT => "up", ONLYVALID => "[0-9]*", READONLY => 1 },
             { KEY => "ADOUBLE",  PROMPT => "DOUBLE",  LEN => 16, CONVERT => "up", ONLYVALID => "[0-9]+([.,][0-9]*)?" },
             { KEY => "DATE",  PROMPT => "DATE",  LEN => 8, CONVERT => "up", ONLYVALID => "[0-9]+", VALIDATOR => "ValidateCCYYMMDD" },
           ]

     sub ValidateCCYYMMDD {
       my $wizard=shift;
       my $line=shift;
       (...)

       return <1/0>
     }

  Note the entries in PROMPTS :

     KEY         is the hash key with what you can access the field.
     PROMPT      is the prompt to use for the field.
     LEN         is the maximum length of the field.
     CONVERT     'up' or 'lo' for uppercase or lowercase. If not used
                 it won't convert.
     ONLYVALID   is a regex to use for validation. Note: validation is
                 done *before* conversion! If not used, no validation is
                 done.
     VALUE       a default value to use. This value will change if the
                 wizard is used.
     VALIDATOR   a validator sub to validate a line of input, after it has
                 been inputted.
     READONLY    Set this prompt readonly.


 del_screen(<name>)

   This function deletes a screen with given name from the list of screens.


 get_keys([screens])

   Optional arguments are screens to use. Example:

      %values=$a->get_keys()                    -> gives all screens.
      %values=$a->get_keys("PROCESS","NUMBERS") -> gives only screens PROCESS and NUMBERS.

   This function gives you all the keys in a hash of a hash. Actually
   a hash of screens and each screen a hash of keys. See synopsis for
   usage.


 set(SCREEN,KEY,VALUE)

   To set key KEY of screen SCREEN equal to VALUE. Example:

      $wizard->set("NUMBERS",HEADER,"This is the new header");
  
   sets the HEADER of screen NUMBERS to a new value.

      $wizard->set("NUMBERS","ADOUBLE",999.999);

   sets the prompt ADOUBLE of screen NUMBERS to 999.999

   More examples:

        $scr->set("GETALLEN",HEADER,"dit is de header");
        $scr->set("GETALLEN","ADOUBLE",999.99);
        $scr->set("PROCES",READONLY,1);
        $scr->set("PROCES",HEADER,"proces scherm is read only nu");
        $scr->set("GETALLEN",PROMPTS,ANINT,READONLY,1);      

 wizard([screens])

    Optional arguments are screens to use. Example:

      $result=$a->wizard()          -> processes all screens.
      $result=$a->wizard("PROCESS") -> processes only screen PROCESS.

   This function starts the wizard.
   Possible results are:

            ="cancel",  the user canceled the wizard; values are not updated.
            ="finish",  the user finished the wizard.
            ="next",    the user finished the wizard and the last prompt
                        has option "NOFINISH".

AUTHOR

  Hans Dijkema <hans@oesterholt-dijkema.emailt.nl>