GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CURSES::APPLICATION (3)

.ds Aq ’

NAME

Curses::Application - Curses Application Framework

CONTENTS

MODULE VERSION

$Id: Application.pm,v 0.2 2002/11/14 19:40:42 corliss Exp corliss $

SYNOPSIS



  use Curses::Application;

  $app = Curses::Application->new({
      FOREGROUND  => white,
      BACKGROUND  => blue,
      TITLEBAR    => 1,
      STATUSBAR   => 1,
      CAPTION     => My Application,
      MAINFORM    => { name => defname },
      MINY        => 20,
      MINX        => 60,
      ALTFBASE    => MyCompany::Forms,
      ALTBASE     => MyCompany::Widgets,
    });

  ($y, $x) = $app->maxyx;
  $mwh = $app->mwh;

  $app->titlebar($caption);
  $app->statusbar($message);

  $app->draw;
  $app->redraw;

  $app->addFormDef(MyForm, { %formopts });
  $app->createForm($name, $def);
  $form = $app->getForm(MainFrm);
  $app->delForm(Main);
  $app->execForm(Main);

  $app->execute;



REQUIREMENTS

Curses Curses::Widgets Curses::Forms

DESCRIPTION

Curses::Application attempts to relieve the programmer of having to deal directly with Curses at all. Based upon Curses::Widgets and Curses::Forms, all one should have to do is define the application forms and contents in the DATA block of a script. Curses::Application will take care of the rest.

INTRODUCTION

This module follows many of the conventions established by the Curses::Widgets and Curses::Forms modules, being built upon that framework. One area of special note, however, is the declaration of forms used within the application.

<B>Curses::ApplicationB> differentiates between forms and form definitions. A form is an instance of any particular form definition. Keeping that line of separation simplifies the development of MDI (Multiple Document Interface) applications.

Form definitions can be provided in two ways: as a list of definitions in the main::DATA block, or individually by using the <B>addFormDefB> method. The former would normally be the simplest way to do so.

At the end of your script, declare a DATA block using Perl’s <B>__DATA__B> token. In that DATA block place a hash declaration (%forms) which contains a key/value pair for each form definition. The key being the name of the definition, and the value being a hash reference to the form declarations (see the <B>Curses::FormsB> pod for directives available to that module). The only extra key that should be in each form’s hash reference should be a <B>TYPEB> directive, which would point to a module name relative to the base Curses::Forms class. If you omit this key, then it will be assumed that the form is a Curses::Forms object, or some custom derivative as specified in <B>ALTPATHB>.



  Example:
  ========

  __DATA__
 
  %forms = (
    Main    => {
      TYPE      => Custom,
      ALTBASE   => MyCompany::Forms,
      LINES     => 10,
      COLUMNS   => 80,
      DERIVED   => 0,
      WIDGETS   => {
        ...
        },
      ...
      },
    );



Just as Curses::Forms allows you to use custom derivatives of Curses::Widgets, this module also allows you to use custom derivatives of Curses::Forms using the <B>ALTBASEB> directive. Similarly, the OnEnter and OnExit events are also supported on per-form basis. Instead of passing the form reference as an argument to the call it passes the application object reference.

<B>NOTEB>: The main form (as declared with <B>MAINFORMB>) will always be a derived form and the size of the screen minus any title or status bars used. This is overridden in the object constructor, so expect those options to be set as such.

FUNCTIONS

This module exports the functions and constants provided by Curses::Forms::Dialog and child modules:



  Functions
  ---------
  dialog, input, logon, scankey

  Constants
  ---------
  BTN_OK, BTN_YES, BTN_NO, BTN_CANCEL, BTN_HELP



This should provide all of the functionality needed within your main application code. The intent of this module is to prevent you from having to know and/or use the entire Curses family of modules directly. The only thing you will need to be aware of is the appropriate configuration syntax for both forms and widgets.

If you need access to the <B>pushwhB>, etc., functions, you’ll need to add:



  use Curses::Forms;



to your main script body, and they’ll be imported directly.

METHODS

    new



  $app = Curses::Application->new({
      FOREGROUND  => white,
      BACKGROUND  => blue,
      TITLEBAR    => 1,
      STATUSBAR   => 1,
      CAPTION     => My Application,
      MAINFORM    => { name => defname },
      MINY        => 20,
      MINX        => 60,
      ALTFBASE    => MyCompany::Forms,
      ALTBASE     => MyCompany::Widgets,
    });



The <B>newB> class method returns a Curses::Application object. All arguments are optional, provided you’re happy with the defaults, with the exception of <B>MAINFORMB>. That directive is a key/value pair consisting of the form name and the name of the form definition.



  Argument    Default  Description
  ============================================================
  FOREGROUND    undef  Default foreground colour
  BACKGROUND    undef  Default background colour
  CAPTIONCOL    undef  Default caption colour
  TITLEBAR          0  Whether or not to show a title bar
  STATUSBAR         0  Whether or not to show a status bar
  CAPTION          $0  Default caption to show in the titlebar
  MINY             24  Minimum lines needed for application
  MINX             80  Minimum columns needed for application
  ALTFBASE      undef  Alternate namespace to search for forms
  ALTBASE       undef  Alternate namespace to search for widgets
  FORMDEFS         {}  Form definitions
  INPUTFUNC \&scankey  Default input routine



<B>MAINFORMB> is the form first display by the application when executed.

If either <B>MINYB> or <B>MINXB> is not satisfied, this method will return undef instead of an object reference to Curses::Application.

Like Curses::Forms, all colour choices are passed to each form that doesn’t explicitly declare their own. Alternate namespaces are also passed.

    maxyx



  ($y, $x) = $app->maxyx;



Returns the maximum Y and X coordinates for the screen.

    mwh



  $mwh = $app->mwh;



Returns a handle to the curses window handle.

    titlebar



  $app->titlebar($newcaption);



This method updates the application caption used in the titlebar and immediately updates screen with a refresh. If you’d prefer to have it updated at the next application refresh (such as the next <B>drawB> method call) you should use the <B>setFieldB> method instead, and update the <B>CAPTIONB> field.

    statusbar



  $app->statusbar($message);



This method updates the statusbar message and immediately updates screen with a refresh. If you’d prefer to have it updated at the next application refresh (such as the next <B>drawB> method call) you should use the <B>setFieldB> method instead, and update the <B>MESSAGEB> field.

    draw



  $app->draw;



Flushes all screen changes to the terminal.

    redraw



  $app->redraw;



Redraws the entire screen.

    addFormDef



  $app->addFormDef(MyForm, { %formopts });



Adds another form definition to the current library. Returns a true if successful, and a false if not (such as if the form type requested is provided by an unavailable module).

    createForm



  $app->createForm($name, $def);



Creates a form object based on the named definition. Returns a handle to the form if successful, and a false if not.

    getForm



  $form = $app->getForm(MainFrm);



Returns a handle to the specified form. If that form does not exist, the object generates a warning and returns undef.

    delForm



  $app->delForm(Main);



Deletes the form object by that name.

    execForm



  $app->execForm(Main);



Executes the form specified by name. This form must be created beforehand via the <B>createFormB> method. Returns the return value of the form’s <B>executeB> method.

    execute



  $app->execute;



Causes the main form to execute. Once the main form exits, this call will exit as well.

HISTORY

2002/11/12 - Initial release.

AUTHOR/COPYRIGHT

(c) 2001 Arthur Corliss (corliss@digitalmages.com)
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 APPLICATION (3) 2002-11-14

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.