NAME

Karma::Input::Form -- the Karma System : From Interface


DESCRIPTION

Forms are just wrappers around the other input objects. The use of forms greatly simplifies the caller's code, and takes care of movement between fields automatically.


SYNOPSIS

Instantiating Forms

A new form may be created with the the following method call to Karma::Input::Form :

        $form = Karma::Input::Form->new(\%form, hlp_y, hlp_x, hlp_height, hlp_width);

\%form must be a reference to a hash that conforms to the structure described in Form Structure. The hlp dimensions specify the size and location of the help text window or status bar, whichever you prefer. This will be filled with the contents of the current field's help_text entry as the user navigates the form.

Form Structure

The forms that may be passed to Karma::Input::Form are shaped as follows:

        %form = {
                #### for multi-line fields:

                Name => [ num, 'multi', y, x, win_height, win_width,
                                     field_height, field_width,
                                     { 
                                        Default => default_text,
                                        Help    => help_text,
                                        Border  =>
                                              {
                                                ts => chtype,
                                                ls => chtype,
                                                rs => chtype,
                                                bs => chtype,
                                                tl => chtype,
                                                tr => chtype,
                                                bl => chtype,
                                                br => chtype
                                              }
                                     }
                        ],
                ....
                #### for single-line fields.
                Name => [ num, 'line', y, x, win_width, field_width,
                                     { 
                                        Default => default_text,
                                        Help    => help_text,
                                        Border  => same as above.
                                        Mask    => 1    # if for a password field.
                                     }
                        ],
                ....
                #### for single character fields:
                Char => [ num, 'char', y, x,
                          {
                                Default => default_char,
                                Others  => list_of_chars,
                                Echo    => bool,
                                Border  => bool,
                                Help    => help_text
                          }
                        ],
                ....
        }

Please note that default_text and help_text may be scalar strings, or references to arrays of strings.

type can be either one of: multi, line, char, radio, or check.

In the case of single character input default_char is the character to return if the user simply strikes enter, list_of_chars is a list of all of the characters to accept from the user. Finally, options contains one of ``echo'', ``noborder'', or ``'' (undef), depending on the caller's mood. echo will cause the character typed to be printed back to the user, and noborder will omit the display of decoration. The default is to display the border, and to refrain from repeating the users input.

The Karma::Input::Form class will attempt to determin on its own if the field borders happen to overlap eachother, those that do will be redrawn everytime they take focus. Otherwise, the border will be left as is. If this is underirable, you may force each boarder to redraw upon coming into focus by specifying the Touch => 1 option.

Also bear in mind that chtype is a curses integer character value. An example would be:

        ord 'h' | A_BOLD

Upon completion, become_interactive() will return the form filled with the values entered;

        %form = {
                Name => users_input | [ users, muti-line, input ] 
                ....
        }

Whether or not a field should return as an array is implied by its field_height attribute; If the height is greater than one it will return an anonymous array reference, otherwise a simple scalar string. This is the same rule that applies to regular (non form) input fields.

Fields in which nothing was typed will not be represented in the returned hash.

While entering data the user may switch through the fields using the tab, backtab, and arrow keys. The switching algorithm uses the number item in the form structure to determine whether a given field is next or previous, please choose these accordingly. once the user has passed the final field control is returned to the caller, who may then process the entered data and/or force the user to reenter it.