NAME
Curses::Application - Curses Application Framework
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.
Curses::Application 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 addFormDef 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 __DATA__ 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 Curses::Forms pod for directives available to that module). The only extra key that should be in each form's hash reference should be a TYPE 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 ALTPATH.
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 ALTBASE 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.
NOTE: The main form (as declared with MAINFORM) 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_HELPThis 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 pushwh, 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 new class method returns a Curses::Application object. All arguments are optional, provided you're happy with the defaults, with the exception of MAINFORM. 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 routineMAINFORM is the form first display by the application when executed.
If either MINY or MINX 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 draw method call) you should use the setField method instead, and update the CAPTION 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 draw method call) you should use the setField method instead, and update the MESSAGE 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 createForm method. Returns the return value of the form's execute method.
execute
$app->execute;Causes the main form to execute. Once the main form exits, this call will exit as well.
HISTORY
AUTHOR/COPYRIGHT
(c) 2001 Arthur Corliss (corliss@digitalmages.com)