.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Application 3" .TH Application 3 "2002-11-14" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" Curses::Application \- Curses Application Framework .SH "MODULE VERSION" .IX Header "MODULE VERSION" $Id: Application.pm,v 0.2 2002/11/14 19:40:42 corliss Exp corliss $ .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Curses::Application; .Ve .PP .Vb 12 \& $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', \& }); .Ve .PP .Vb 2 \& ($y, $x) = $app->maxyx; \& $mwh = $app->mwh; .Ve .PP .Vb 2 \& $app->titlebar($caption); \& $app->statusbar($message); .Ve .PP .Vb 2 \& $app->draw; \& $app->redraw; .Ve .PP .Vb 5 \& $app->addFormDef('MyForm', { %formopts }); \& $app->createForm($name, $def); \& $form = $app->getForm('MainFrm'); \& $app->delForm('Main'); \& $app->execForm('Main'); .Ve .PP .Vb 1 \& $app->execute; .Ve .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" Curses Curses::Widgets Curses::Forms .SH "DESCRIPTION" .IX Header "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 \&\s-1DATA\s0 block of a script. Curses::Application will take care of the rest. .SH "INTRODUCTION" .IX Header "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. .PP \&\fBCurses::Application\fR 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 \s-1MDI\s0 (Multiple Document Interface) applications. .PP Form definitions can be provided in two ways: as a list of definitions in the main::DATA block, or individually by using the \fBaddFormDef\fR method. The former would normally be the simplest way to do so. .PP At the end of your script, declare a \s-1DATA\s0 block using Perl's \fB_\|_DATA_\|_\fR token. In that \s-1DATA\s0 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 \fBCurses::Forms\fR pod for directives available to that module). The only extra key that should be in each form's hash reference should be a \&\fB\s-1TYPE\s0\fR 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 \&\fB\s-1ALTPATH\s0\fR. .PP .Vb 2 \& Example: \& ======== .Ve .PP .Vb 1 \& __DATA__ .Ve .PP .Vb 13 \& %forms = ( \& Main => { \& TYPE => 'Custom', \& ALTBASE => 'MyCompany::Forms', \& LINES => 10, \& COLUMNS => 80, \& DERIVED => 0, \& WIDGETS => { \& ... \& }, \& ... \& }, \& ); .Ve .PP 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 \fB\s-1ALTBASE\s0\fR 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. .PP \&\fB\s-1NOTE\s0\fR: The main form (as declared with \fB\s-1MAINFORM\s0\fR) 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. .SH "FUNCTIONS" .IX Header "FUNCTIONS" This module exports the functions and constants provided by Curses::Forms::Dialog and child modules: .PP .Vb 3 \& Functions \& --------- \& dialog, input, logon, scankey .Ve .PP .Vb 3 \& Constants \& --------- \& BTN_OK, BTN_YES, BTN_NO, BTN_CANCEL, BTN_HELP .Ve .PP 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. .PP If you need access to the \fBpushwh\fR, etc., functions, you'll need to add: .PP .Vb 1 \& use Curses::Forms; .Ve .PP to your main script body, and they'll be imported directly. .SH "METHODS" .IX Header "METHODS" .Sh "new" .IX Subsection "new" .Vb 12 \& $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', \& }); .Ve .PP The \fBnew\fR class method returns a Curses::Application object. All arguments are optional, provided you're happy with the defaults, with the exception of \fB\s-1MAINFORM\s0\fR. That directive is a key/value pair consisting of the form name and the name of the form definition. .PP .Vb 14 \& 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 \e&scankey Default input routine .Ve .PP \&\fB\s-1MAINFORM\s0\fR is the form first display by the application when executed. .PP If either \fB\s-1MINY\s0\fR or \fB\s-1MINX\s0\fR is not satisfied, this method will return undef instead of an object reference to Curses::Application. .PP Like Curses::Forms, all colour choices are passed to each form that doesn't explicitly declare their own. Alternate namespaces are also passed. .Sh "maxyx" .IX Subsection "maxyx" .Vb 1 \& ($y, $x) = $app->maxyx; .Ve .PP Returns the maximum Y and X coordinates for the screen. .Sh "mwh" .IX Subsection "mwh" .Vb 1 \& $mwh = $app->mwh; .Ve .PP Returns a handle to the curses window handle. .Sh "titlebar" .IX Subsection "titlebar" .Vb 1 \& $app->titlebar($newcaption); .Ve .PP 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 \fBdraw\fR method call) you should use the \fBsetField\fR method instead, and update the \fB\s-1CAPTION\s0\fR field. .Sh "statusbar" .IX Subsection "statusbar" .Vb 1 \& $app->statusbar($message); .Ve .PP 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 \fBdraw\fR method call) you should use the \&\fBsetField\fR method instead, and update the \fB\s-1MESSAGE\s0\fR field. .Sh "draw" .IX Subsection "draw" .Vb 1 \& $app->draw; .Ve .PP Flushes all screen changes to the terminal. .Sh "redraw" .IX Subsection "redraw" .Vb 1 \& $app->redraw; .Ve .PP Redraws the entire screen. .Sh "addFormDef" .IX Subsection "addFormDef" .Vb 1 \& $app->addFormDef('MyForm', { %formopts }); .Ve .PP 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). .Sh "createForm" .IX Subsection "createForm" .Vb 1 \& $app->createForm($name, $def); .Ve .PP Creates a form object based on the named definition. Returns a handle to the form if successful, and a false if not. .Sh "getForm" .IX Subsection "getForm" .Vb 1 \& $form = $app->getForm('MainFrm'); .Ve .PP Returns a handle to the specified form. If that form does not exist, the object generates a warning and returns undef. .Sh "delForm" .IX Subsection "delForm" .Vb 1 \& $app->delForm('Main'); .Ve .PP Deletes the form object by that name. .Sh "execForm" .IX Subsection "execForm" .Vb 1 \& $app->execForm('Main'); .Ve .PP Executes the form specified by name. This form must be created beforehand via the \fBcreateForm\fR method. Returns the return value of the form's \fBexecute\fR method. .Sh "execute" .IX Subsection "execute" .Vb 1 \& $app->execute; .Ve .PP Causes the main form to execute. Once the main form exits, this call will exit as well. .SH "HISTORY" .IX Header "HISTORY" .IP "2002/11/12 \- Initial release." 4 .IX Item "2002/11/12 - Initial release." .SH "AUTHOR/COPYRIGHT" .IX Header "AUTHOR/COPYRIGHT" (c) 2001 Arthur Corliss (corliss@digitalmages.com)