ADDING WIDGETS

   Key      Description
   ====================================================
   TYPE     Type of widget, relative to Curses::Widgets
   OnEnter  Subroutine reference to be called when the
            widget first gains focus
   OnExit   Subroutine reference to be called when the 
            widget loses focus

Only TYPE is mandatory. The value is a string relative to the Curses::Widgets hierarchy. In other words, if you want a TextField widget, that's all you need to put in, not the full Curses::Widgets::TextField module name. This allows you to use new widgets with no special modifications needed in this module, as long as it's found within the Curses::Widgets namespace.

If you want to use custom widgets not in the Curses::Widgets namespace you must set the ALTBASE key to whatever the base class is called (i.e., 'MyCompany::Widgets', if all the widgets are within that heirarchy). The TYPE will use ALTBASE first, then, and if that fails, try Curses::Widgets. You can set ALTBASE to an array ref with multiple namespaces to search, if desired.

OnEnter and OnExit can be considered rudimentary event handlers. These subroutines are called when the widget gains and/or loses focus. These subroutines are always called with two arguments: a reference to the Curses::Forms object, and the last key stroke:

  @$sub($form, $key)

This allows you to use these handlers to update other widgets on the form, or take appropriate action as needed. For instance, suppose you had a database record form open, with two buttons: Commit, and Cancel. The former would save the database changes, while the latter would just close the form. You would accomplish this as so:

  # During widget declaration
  $form->new({
    ...
    WIDGETS => {
      ...
      btnCommitCancel => {
        ...
        OnExit  => \&CancelOrCommit,
        },
      },
    });

  # Subroutine somewhere else in your program code
  sub CancelOrCommit {
    my $form = shift;
    my $key = shift;
    my $btns = $form->getWidget('btnCommitCancel');

    # Make sure they user pressed <ENTER> to push a button
    return unless $key eq "\n";

    # The user pressed 'Commit'
    if ($btn->getField('VALUE') == 0) {
      # Save your record updates
      ...

    # The user pressed 'Cancel'
    } else {
      $form->setField(EXIT => 1);
    }
  }

As you can see, this example also explains a special field used by the Curses::Forms object: EXIT. Whenever you want the form to be closed due to some condition or user input just set EXIT to some true value. Once your subroutine exits this field will be checked, and if true, will cause the form to break out of the execute loop.

Another special field is the DONTSWITCH field, which tells the form to keep the focus where it is.

A point of clarification: if you use the getField/setField operations to retrieve and modify the WIDGETS key, this will have no affect on the current set of widgets in the form. This key is only used during object instantiation, with all object references to the widgets stored internally, but outside of the configuration hash. Therefore, you can modify widget parameters only by retrieving the object reference via the getWidget method. Also, you can add widgets via the addWidget but there is no method to delete them.

The form content area is always a derived window, so widgets should always place themselves relative to (0, 0), regardless of whether or not the form has a border.

ADDING SUBFORMS

The only change in subform behaviour versus form behaviour is that once the focus leaves the last widget in the tab order, focus switches back to the parent form tab order, instead of looping within that subform.

MANAGING OVERLAPPING FORMS

From time to time you may create windows that need to be redrawn with the other overlapping windows. Two functions are provided to handle this: pushwh and popwh. As you create the window you should use pushwh to put it in the array, and use popwh as soon as you delete it. If you'd like to manually refresh the screen, you may do so via the refreshwh subroutine.

To other functions are provided for lowering or raising the windows in the array: lowerwh and raisewh.

pushwh

  pushwh($mwh);

Pushes an external window handle onto the Curses::Forms-managed refresh array.

popwh

  popwh();

Pops a window handle off the Curses::Forms-managed refresh array.

refreshwh

  refreshwh();

Refreshes each window in order of the ordinal array.

raisewh

  raisewh($wh);

Raises the passed window in the array.

lowerwh

  lowerwh($wh);

Lowers the passed window in the array.

new

  $obj = Curses::Forms->new({
    ALTBASE     => 'MyCompany::Widgets',
    ALTFBASE    => 'MyCompany::Forms',
    COLUMNS     => 40,
    LINES       => 20,
    BORDER      => 1,
    BORDERCOL   => 'white',
    CAPTION     => 'New Record',
    CAPTIONCOL  => 'yellow',
    FOREGROUND  => 'black',
    BACKGROUND  => 'white',
    Y           => 1,
    X           => 1,
    INPUTFUNC   => \&scankey,
    DERIVED     => 0,
    AUTOCENTER  => 1,
    TABORDER    => [qw(btnOKCancel edtLogon edtPsswd)],
    FOCUSED     => 'edtLogon',
    WIDGETS     => {
      btnOKCancel   => {
        TYPE        => 'ButtonSet',
        LABELS      => [qw(OK Cancel)],
        Y           => 8,
        X           => 3,
        FOREGROUND  => 'white',
        BACKGROUND  => 'green',
        OnExit      => \&btns,
        },
      edtLogon      => {
        TYPE        => 'TextField',
        FOREGROUND  => 'white',
        BACKGROUND  => 'blue',
        CAPTION     => 'Logon',
        CAPTIONCOL  => 'yellow',
        LENGTH      => 21,
        Y           => 2,
        X           => 8,
        },
      edtPsswd      => {
        TYPE        => 'TextField',
        FOREGROUND  => 'white',
        BACKGROUND  => 'blue',
        CAPTION     => 'Password',
        CAPTIONCOL  => 'yellow',
        LENGTH      => 21,
        Y           => 5,
        X           => 8,
        PASSWORD    => 1,
      },
    });

This method instantiates a new instance of a Curses::Form object. All configuration directives, with the exception of COLUMNS and LINES are optional. The defaults for the rest are described below:

  Key         Default     Description
  ==============================================================
  BORDER            0     Display a border around the form
  BORDERCOL     undef     Foreground colour for border
  CAPTION       undef     Caption superimposed on border
  CAPTIONCOL    undef     Foreground colour for caption text
  FOREGROUND    undef     Foreground colour for form
  BACKGROUND    undef     Background colour for form
  Y                 0     Y coordinate for upper left corner
  X                 0     X coordinate for upper left corner
  INPUTFUNC \&scankey     Function to use to scan for keystrokes
  DERIVED           1     Whether to create the form as a derived
                          or new window
  TABORDER         []     Order in which widgets will get the 
                          focus
  FOCUSED       undef     Currently focused widget
  WIDGETS          {}     Widgets used on the form
  ALTBASE       undef     Alternate namespace to search for 
                          loadable widgets
  ALTFBASE      undef     Alternate namespace to search for 
                          loadable forms
  AUTOCENTER        0     Whether or not to center the form in the
                          display (only for non-derived windows)

The CAPTION is only valid when the BORDER is enabled. INPUTFUNC will be passed to each widget explicitly. FOREGROUND, BACKGROUND, and CAPTIONCOL will be passed to each widget if that widget's declaration doesn't specify it directly.

Please see the Introduction section on special handling of the declaration of widgets.

draw

  $form->draw($mwh);

This methods renders and displays the form in its current state. An optional second argument designates whether or not the focused widget should be drawn in active mode or not.

setField/getField

  $form->setField(BORDER => 1);
  @taborder = @{$form->getField('TABORDER')};

These methods are inherited from the Curses::Widgets module, and hence are syntactically the same. For more specifics please see that module.

addWidget

  $form->addWidget('btnClose', { %options });

This method allows you to add a widget to the form. Please see the INTRODUCTION for a more indepth explanation of this call. Returns a true if successful, or a false if not (if, for instance, you're trying to use a widget that module can be found for, or a widget by that name already exists).

getWidget

  $widget = $form->getWidget('btnClose');

Retrieves a reference to a widget object. Returns an undef if the widget does not exist under the passed name.

addSubform

  $form->addSubform('MainSubFrm', { %options });

This method allows you to add a subform to the form. Please see the INTRODUCTION for a more indepth explanation of this call. Returns a true if successful, or a false if not (if, for instance, you're trying to use a form that module can't be found for, or a widget by that name already exists).

getSubform

  $subform = $form->getSubform('MainSubFrm');

Retrieves a reference to a subform object. Returns an undef if the form does not exist under the passed name.

execute

  $form->execute($mwh);

This method starts the form loop to scan input and cycle through the widgets that can get focus. A valid window handle must be passed for any form using DERIVED mode.