This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Crypt/UnixCrypt, Next: Crypt/xDBM_File, Prev: Crypt/Twofish2, Up: Module List perl-only implementation of the crypt function. *********************************************** NAME ==== Crypt::UnixCrypt - perl-only implementation of the crypt function. SYNOPSIS ======== use Crypt::UnixCrypt; $hashed = crypt($plaintext,$salt); # always use this module's crypt BEGIN { $Crypt::UnixCrpyt::OVERRIDE_BUILTIN = 1 } use Crypt::UnixCrypt; DESCRIPTION =========== This module is for all those poor souls whose perl port answers to the use of crypt() with the message `The crypt() function is unimplemented due to excessive paranoia.'. This module won't overload a built-in crypt() unless forced by a true value of the variable `$Crypt::UnixCrypt::OVERRIDE_BUILTIN'. If you use this module, you probably neither have a built-in crypt() function nor a `crypt(3)' in this node manpage; so I'll supply the appropriate portions of its description (from my Linux system) here: crypt is the password encryption function. It is based on the Data Encryption Standard algorithm with variations intended (among other things) to discourage use of hardware implementations of a key search. $plaintext is a user's typed password. $salt is a two-character string chosen from the set [a-zA-Z0-9./]. This string is used to perturb the algorithm in one of 4096 different ways. By taking the lowest 7 bit of each character of $plaintext (filling it up to 8 characters with zeros, if needed), a 56-bit key is obtained. This 56-bit key is used to encrypt repeatedly a constant string (usually a string consisting of all zeros). The returned value points to the encrypted password, a series of 13 printable ASCII characters (the first two characters represent the salt itself). Warning: The key space consists of 2**56 equal 7.2e16 possible values. Exhaustive searches of this key space are possible using massively parallel computers. Software, such as crack(1), is available which will search the portion of this key space that is generally used by humans for passwords. Hence, password selection should, at minimum, avoid common words and names. The use of a passwd(1) program that checks for crackable passwords during the selection process is recommended. The DES algorithm itself has a few quirks which make the use of the crypt(3) interface a very poor choice for anything other than password authentication. If you are planning on using the crypt(3) interface for a cryptography project, don't do it: get a good book on encryption and one of the widely available DES libraries. COPYRIGHT ========= This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself. AUTHORS ======= Written by Martin Vorlaender, martin@radiogaga.harz.de, 11-DEC-1997. Based upon Java source code written by jdumas@zgs.com, which in turn is based upon C source code written by Eric Young, eay@psych.uq.oz.au. CAVEATS ======= In extreme situations, this function doesn't behave like `crypt(3)', e.g. when called with a salt not in [A-Za-z0-9./]{2}. SEE ALSO ======== perl(1), perlfunc(1), crypt(3).  File: pm.info, Node: Crypt/xDBM_File, Next: Curses, Prev: Crypt/UnixCrypt, Up: Module List encrypt almost any kind of dbm file *********************************** NAME ==== Crypt::xDBM_File - encrypt almost any kind of dbm file SYNOPSIS ======== use Crypt::xDBM_File; use GDBM_File; # remember to only load those you really want use SDBM_File; use NDBM_File; use Fcntl; # neede by SDBM_File and NDBM_File tie %hash, 'Crypt::xDBM_File', crypt_method, key, 'GDBM_FILE', $filename, &GDBM_WRCREAT, 0640; tie %hash, 'Crypt::xDBM_File', 'IDEA', "my_key", 'NDBM_FILE', $filename, O_RDWR|O_CREAT, 0640; tie %hash, 'Crypt::xDBM_File', 'DES', "my_key", 'SDBM_FILE', $filename, O_RDWR|O_CREAT, 0640; tie %hash, 'Crypt::xDBM_File', 'Crypt::Blowfish', "my key", 'GDBM_FILE', $filename, &GDBM_WRCREAT, 0640; DESCRIPTION =========== Crypt::xDBM_File encrypts/decrypts the data in a gdbm,ndbm,sdbm (and maybe even berkeleyDB, but I didn't test that) file. It gets tied to a hash and you just access the hash like normal. The crypt function can be any of the CPAN modules that use encrypt, decrypt, keysize, blocksize (so Crypt::IDEA, Crypt::DES, Crypt::Blowfish, ... should all work) You can in a single dbm file mix encryption methods, just be prepared to handle the binary muck that you get from trying to decrypt with an algorithm different from the one a key was originally encrypted in (for example if you do a keys or values, you'll get all of the keys regardless of who encrypted them). ***IMPORTANT*** Encryption keys (the key you pass in on the tie line) will be padded or truncated to fit the keysize(). Data (the key/values of the hash) is padded to fill complete blocks of blocksize(). The padding is stripped before being returned to the user so you shouldn't need to worry about it (except truncated keys). Read the doc that comes with crypt function to get an idea of what these sizes are. If keysize or blocksize returns a zero the default is set to 8 bytes (64 bits). AUTHOR ====== Eric Estabrooks, eric@urbanrage.com SEE ALSO ======== perl(1).  File: pm.info, Node: Curses, Next: Curses/Forms, Prev: Crypt/xDBM_File, Up: Module List terminal screen handling and optimization ***************************************** NAME ==== Curses - terminal screen handling and optimization SYNOPSIS ======== use Curses; initscr; ... endwin; DESCRIPTION =========== `Curses' is the interface between Perl and your system's curses(3) library. For descriptions on the usage of a given function, variable, or constant, consult your system's documentation, as such information invariably varies (:-) between different curses(3) libraries and operating systems. This document describes the interface itself, and assumes that you already know how your system's curses(3) library works. Unified Functions ----------------- Many curses(3) functions have variants starting with the prefixes *w-*, *mv-*, and/or *wmv-*. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, `addch()' has three other variants: `waddch()', `mvaddch()', and `mvwaddch()'. The variants aren't very interesting; in fact, we could roll all of the variants into original function by allowing a variable number of arguments and analyzing the argument list for which variant the user wanted to call. Unfortunately, curses(3) predates varargs(3), so in C we were stuck with all the variants. However, `Curses' is a Perl interface, so we are free to "unify" these variants into one function. The section `"Supported Functions"' in this node below lists all curses(3) function supported by `Curses', along with a column listing if it is *unified*. If so, it takes a varying number of arguments as follows: `function( [win], [y, x], args );' *win* is an optional window argument, defaulting to `stdscr' if not specified. *y, x* is an optional coordinate pair used to move the cursor, defaulting to no move if not specified. args are the required arguments of the function. These are the arguments you would specify if you were just calling the base function and not any of the variants. This makes the variants obsolete, since their functionality has been merged into a single function, so `Curses' does not define them by default. You can still get them if you want, by setting the variable `$Curses::OldCurses' to a non-zero value before using the `Curses' package. See `"Perl 4.X `cursperl' in this node Compatibility"' for an example of this. Objects ------- Objects are supported. Example: $win = new Curses; $win->addstr(10, 10, 'foo'); $win->refresh; ... Any function that has been marked as *unified* (see `"Supported Functions"' in this node below and `"Unified Functions"' in this node above) can be called as a method for a Curses object. Do not use `initscr()' if using objects, as the first call to get a `new Curses' will do it for you. COMPATIBILITY ============= Perl 4.X `cursperl' Compatibility --------------------------------- `Curses' has been written to take advantage of the new features of Perl. I felt it better to provide an improved curses programming environment rather than to be 100% compatible. However, many old `curseperl' applications will probably still work by starting the script with: BEGIN { $Curses::OldCurses = 1; } use Curses; Any old application that still does not work should print an understandable error message explaining the problem. Some functions and variables are not supported by `Curses', even with the BEGIN line. They are listed under `"curses(3) items not supported by Curses"' in this node. The variables `$stdscr' and `$curscr' are also available as functions `stdscr' and `curscr'. This is because of a Perl bug. See the `BUGS' in this node section for details. Incompatibilities with previous versions of `Curses' ---------------------------------------------------- In previous versions of this software, some Perl functions took a different set of parameters than their C counterparts. This is no longer true. You should now use `getstr($str)' and `getyx($y, $x)' instead of `$str = getstr()' and `($y, $x) = getyx()'. Incompatibilities with other Perl programs ------------------------------------------ menu.pl, v3.0 and v3.1 There were various interaction problems between these two releases and Curses. Please upgrade to the latest version (v3.3 as of 3/16/96). DIAGNOSTICS =========== * Curses function '%s' called with too %s arguments at ... You have called a `Curses' function with a wrong number of arguments. * argument %d to Curses function '%s' is not a Curses %s at ... =item * argument is not a Curses %s at ... The argument you gave to the function wasn't what it wanted. This probably means that you didn't give the right arguments to a *unified* function. See the DESCRIPTION section on `Unified Functions' in this node for more information. * Curses function '%s' is not defined by your vendor at ... You have a `Curses' function in your code that your system's curses(3) library doesn't define. * Curses variable '%s' is not defined by your vendor at ... You have a `Curses' variable in your code that your system's curses(3) library doesn't define. * Curses constant '%s' is not defined by your vendor at ... You have a `Curses' constant in your code that your system's curses(3) library doesn't define. * Curses does not support the curses function '%s', used at ... You have a curses(3) function in your code that the `Curses' module doesn't support. * Curses does not support the curses variable '%s', used at ... You have a curses(3) variable in your code that the `Curses' module doesn't support. * Curses does not support the curses constant '%s', used at ... You have a bareword in your code that is trying to be interpreted as a `Curses' constant, but `Curses' doesn't know anything about it. * Curses::Vars::FETCH called with bad index at ... =item * Curses::Vars::STORE called with bad index at ... You've been playing with the tie interface to the `Curses' variables. Don't do that. :-) * Anything else Check out the `perldiag' man page to see if the error is in there. BUGS ==== If you use the variables `$stdscr' and `$curscr' instead of their functional counterparts (`stdscr' and `curscr'), you might run into a bug in Perl where the "magic" isn't called early enough. This is manifested by the `Curses' package telling you `$stdscr' isn't a window. One workaround is to put a line like `$stdscr = $stdscr' near the front of your program. Probably many more. AUTHOR ====== William Setzer SYNOPSIS OF PERL CURSES SUPPORT =============================== Supported Functions ------------------- Supported Unified? Supported via $OldCurses[*] --------- -------- ------------------------ addch Yes waddch mvaddch mvwaddch echochar Yes wechochar addchstr Yes waddchstr mvaddchstr mvwaddchstr addchnstr Yes waddchnstr mvaddchnstr mvwaddchnstr addstr Yes waddstr mvaddstr mvwaddstr addnstr Yes waddnstr mvaddnstr mvwaddnstr attroff Yes wattroff attron Yes wattron attrset Yes wattrset standend Yes wstandend standout Yes wstandout chgat Yes wchgat mvchgat mvwchgat COLOR_PAIR No PAIR_NUMBER No beep No flash No bkgd Yes wbkgd bkgdset Yes wbkgdset getbkgd Yes border Yes wborder box Yes hline Yes whline mvhline mvwhline vline Yes wvline mvvline mvwvline erase Yes werase clear Yes wclear clrtobot Yes wclrtobot clrtoeol Yes wclrtoeol start_color No init_pair No init_color No has_colors No can_change_color No color_content No pair_content No delch Yes wdelch mvdelch mvwdelch deleteln Yes wdeleteln insdelln Yes winsdelln insertln Yes winsertln getch Yes wgetch mvgetch mvwgetch ungetch No has_key No getstr Yes wgetstr mvgetstr mvwgetstr getnstr Yes wgetnstr mvgetnstr mvwgetnstr getyx Yes getparyx Yes getbegyx Yes getmaxyx Yes getmaxy Yes getmaxx Yes inch Yes winch mvinch mvwinch inchstr Yes winchstr mvinchstr mvwinchstr inchnstr Yes winchnstr mvinchnstr mvwinchnstr initscr No endwin No isendwin No newterm No set_term No delscreen No cbreak No nocbreak No echo No noecho No halfdelay No intrflush Yes keypad Yes meta Yes nodelay Yes notimeout Yes raw No noraw No qiflush No noqiflush No timeout Yes wtimeout typeahead No insch Yes winsch mvinsch mvwinsch insstr Yes winsstr mvinsstr mvwinsstr insnstr Yes winsnstr mvinsnstr mvwinsnstr instr Yes winstr mvinstr mvwinstr innstr Yes winnstr mvinnstr mvwinnstr def_prog_mode No def_shell_mode No reset_prog_mode No reset_shell_mode No resetty No savetty No getsyx No setsyx No curs_set No napms No getmouse No ungetmouse No mousemask No enclose Yes wenclose mouse_trafo Yes wmouse_trafo mouseinterval No BUTTON_RELEASE No BUTTON_PRESS No BUTTON_CLICK No BUTTON_DOUBLE_CLICK No BUTTON_TRIPLE_CLICK No BUTTON_RESERVED_EVENTNo move Yes wmove clearok Yes idlok Yes idcok Yes immedok Yes leaveok Yes setscrreg Yes wsetscrreg scrollok Yes nl No nonl No overlay No overwrite No copywin No newpad No subpad No prefresh No pnoutrefresh No pechochar No refresh Yes wrefresh noutrefresh Yes wnoutrefresh doupdate No redrawwin Yes redrawln Yes wredrawln scr_dump No scr_restore No scr_init No scr_set No scroll Yes scrl Yes wscrl slk_init No slk_set No slk_refresh No slk_noutrefresh No slk_label No slk_clear No slk_restore No slk_touch No slk_attron No slk_attrset No slk_attr No slk_attroff No slk_color No baudrate No erasechar No has_ic No has_il No killchar No longname No longname No termattrs No termname No touchwin Yes touchline Yes touchline Yes untouchwin Yes touchln Yes wtouchln is_linetouched Yes is_wintouched Yes unctrl No keyname No filter No use_env No putwin No getwin No delay_output No flushinp No newwin No delwin Yes mvwin Yes subwin Yes derwin Yes mvderwin Yes dupwin Yes syncup Yes wsyncup syncok Yes cursyncup Yes wcursyncup syncdown Yes wsyncdown resize Yes wresize flusok Yes getcap No touchoverlap No new_panel No bottom_panel No top_panel No show_panel No update_panels No hide_panel No panel_window No replace_panel No move_panel No panel_hidden No panel_above No panel_below No set_panel_userptr No panel_userptr No del_panel No [*] To use any functions in this column, the variable `$Curses::OldCurses' must be set to a non-zero value before using the `Curses' package. See `"Perl 4.X cursperl Compatibility"' in this node for an example of this. Supported Variables ------------------- LINES COLS stdscr curscr COLORS COLOR_PAIRS Supported Constants ------------------- ERR OK ACS_BLOCK ACS_BOARD ACS_BTEE ACS_BULLET ACS_CKBOARD ACS_DARROW ACS_DEGREE ACS_DIAMOND ACS_HLINE ACS_LANTERN ACS_LARROW ACS_LLCORNER ACS_LRCORNER ACS_LTEE ACS_PLMINUS ACS_PLUS ACS_RARROW ACS_RTEE ACS_S1 ACS_S9 ACS_TTEE ACS_UARROW ACS_ULCORNER ACS_URCORNER ACS_VLINE A_ALTCHARSET A_ATTRIBUTES A_BLINK A_BOLD A_CHARTEXT A_COLOR A_DIM A_INVIS A_NORMAL A_PROTECT A_REVERSE A_STANDOUT A_UNDERLINE COLOR_BLACK COLOR_BLUE COLOR_CYAN COLOR_GREEN COLOR_MAGENTA COLOR_RED COLOR_WHITE COLOR_YELLOW KEY_A1 KEY_A3 KEY_B2 KEY_BACKSPACE KEY_BEG KEY_BREAK KEY_BTAB KEY_C1 KEY_C3 KEY_CANCEL KEY_CATAB KEY_CLEAR KEY_CLOSE KEY_COMMAND KEY_COPY KEY_CREATE KEY_CTAB KEY_DC KEY_DL KEY_DOWN KEY_EIC KEY_END KEY_ENTER KEY_EOL KEY_EOS KEY_EXIT KEY_F0 KEY_FIND KEY_HELP KEY_HOME KEY_IC KEY_IL KEY_LEFT KEY_LL KEY_MARK KEY_MAX KEY_MESSAGE KEY_MIN KEY_MOVE KEY_NEXT KEY_NPAGE KEY_OPEN KEY_OPTIONS KEY_PPAGE KEY_PREVIOUS KEY_PRINT KEY_REDO KEY_REFERENCE KEY_REFRESH KEY_REPLACE KEY_RESET KEY_RESTART KEY_RESUME KEY_RIGHT KEY_SAVE KEY_SBEG KEY_SCANCEL KEY_SCOMMAND KEY_SCOPY KEY_SCREATE KEY_SDC KEY_SDL KEY_SELECT KEY_SEND KEY_SEOL KEY_SEXIT KEY_SF KEY_SFIND KEY_SHELP KEY_SHOME KEY_SIC KEY_SLEFT KEY_SMESSAGE KEY_SMOVE KEY_SNEXT KEY_SOPTIONS KEY_SPREVIOUS KEY_SPRINT KEY_SR KEY_SREDO KEY_SREPLACE KEY_SRESET KEY_SRIGHT KEY_SRSUME KEY_SSAVE KEY_SSUSPEND KEY_STAB KEY_SUNDO KEY_SUSPEND KEY_UNDO KEY_UP KEY_MOUSE BUTTON1_RELEASED BUTTON1_PRESSED BUTTON1_CLICKED BUTTON1_DOUBLE_CLICKED BUTTON1_TRIPLE_CLICKED BUTTON1_RESERVED_EVENT BUTTON2_RELEASED BUTTON2_PRESSED BUTTON2_CLICKED BUTTON2_DOUBLE_CLICKED BUTTON2_TRIPLE_CLICKED BUTTON2_RESERVED_EVENT BUTTON3_RELEASED BUTTON3_PRESSED BUTTON3_CLICKED BUTTON3_DOUBLE_CLICKED BUTTON3_TRIPLE_CLICKED BUTTON3_RESERVED_EVENT BUTTON4_RELEASED BUTTON4_PRESSED BUTTON4_CLICKED BUTTON4_DOUBLE_CLICKED BUTTON4_TRIPLE_CLICKED BUTTON4_RESERVED_EVENT BUTTON_CTRL BUTTON_SHIFT BUTTON_ALT ALL_MOUSE_EVENTS REPORT_MOUSE_POSITION NCURSES_MOUSE_VERSION curses(3) items not supported by `Curses' ----------------------------------------- Functions --------- tstp scanw wscanw mvscanw mvwscanw _putchar fullname [*] stdscr and curscr are also available via the Perl functions `stdscr' and `curscr'. See `"Perl 4.X cursperl Compatibility"' in this node for more information.  File: pm.info, Node: Curses/Forms, Next: Curses/Widgets, Prev: Curses, Up: Module List Curses-based form handling for Curses::Widgets ********************************************** NAME ==== Curses::Forms - Curses-based form handling for Curses::Widgets Doc/Module Version info ======================= $Id: Forms.pod,v 0.2 2000/02/29 08:47:25 corliss Exp $ SYNOPSIS ======== use Curses::Forms; $form = Curses::Forms->new({ 'Y' => 1, 'X' => 0, 'LINES' => $LINES - 2, 'COLS' => $COLS }); $form->add( { 'type' => 'list_box', 'name' => 'cal_list', 'ypos' => 0, 'xpos' => 0, 'lines' => 8, 'cols' => $COLS - 2, 'title' => ' Calendars ', 'list' => \@list }, { 'type' => 'txt_field', 'name' => 'record', 'ypos' => 10, 'xpos' => 0, 'regex' => "\tqQ", 'lines' => $LINES - 14, 'cols' => $COLS - 2, 'title' => ' Record ', 'edit' => 0 }); $form->set_defaults( DEF_FUNC => \&clock); $form->tab_order("cal_list"); $form->bind( ["cal_list", "[ \n]", "Mod_Oth", \&rtrv_cal_rec, "record" ], ["cal_list", "[qQ]", "Quit_Form"], ["cal_list", "[bB]", "Mod_Oth", \&browse_cal, "record" ]); $form->activate; REQUIREMENTS ============ Requires the Curses module, Curses or nCurses libraries, and Curses::Widgets. You must still 'use Curses;' in your script, as well as 'use Curses::Widgets'. Curses::Widgets v1.1 is the minimum version needed. DESCRIPTION =========== This module provides an object-oriented approach to managing separate forms composed of multiple widgets. This approach removes the need to code any handling for form navigation. Only the list of widgets, the widget tab order, and any special key/function bindings need be used. Once the form is initialised, it handles everything else on its own. PUBLIC METHODS ============== * new * add * bind * tab_order * set_defaults * activate * refresh_forms METHODS ======= new --- The 'new' method returns an object handle by which the form is both initialised and managed. One argument, in the form of an anonymous hash, much be passed which specifies the desired geometry. This method merely creates and initialises the object, no error checking is done outside of verifying that the following parameters were passed: Parameter ------------------------------------------------ Y The y coordinate for the top-left corner of the form X The x coordinate for the top-left corner of the form LINES The number of lines in the form COLS The number of columns in the form B $form = Curses::Forms->new({ 'Y' => 1, 'X' => 0, 'LINES' => $LINES - 2, 'COLS' => $COLS }); add --- The 'add' method is used to add widgets to the form, each widget being passed as an anonymous hash. All the necessary options for the specific widget type must be passed, along with two other parameters: Parameters ----------- type The type of widget, as specified by the function name in Curses::Widgets name A unique name for referencing on the form (this will be the identifier used in the tab_order and bind methods) The only error checking done at this point is ensuring that each widget is named, and uniquely so, as well as ensuring that the widget type is a type known to the module. To get a list of options for the different types of widgets, see the documentation for *Curses::Widgets*. B $form->add( { 'type' => 'list_box', 'name' => 'cal_list', 'ypos' => 0, 'xpos' => 0, 'lines' => 8, 'cols' => $COLS - 2, 'title' => ' Calendars ', 'list' => \@list }, { 'type' => 'txt_field', 'name' => 'record', 'ypos' => 10, 'xpos' => 0, 'regex' => "\tqQ", 'lines' => $LINES - 14, 'cols' => $COLS - 2, 'title' => ' Record ', 'edit' => 0 }); bind ---- The 'bind' method allows certain functions and actions to be bound to specific widgets, and triggered by specific key strokes. Each action/function binding is passed as an anonymous array, each containing the following fields, in the following order: Bind record ----------- $anon[0] The name of widget to bind the action to $anon[1] The input regex which will trigger the action (the widget must not trap for the regex above, but must exit with that input to allow the form to call this binding) $anon[2] The action to be taken $anon[3] The function to call (only needed for Mod_Own/Mod_Oth) $anon[4] The name of the widget to call the action on (only needed for Mod_Oth) Actions ------------ Quit_Form Exit the activate routine, and return all the current widget values Nxt_Wdgt Move the active widget focus to the next widget as specified by the tab order. Mod_Own Call the specified function and pass it a reference to the current widget's state hash Mod_Oth Call the specified function and pass it a reference to both the current and the specified widget This method must not be called until the widgets are already added to the form. If you call it before, it will trigger a series of warnings about attempts to bind to a non-existent widget. One should note that bindings for specific widgets and keys can be stacked, with the bindings for that widget/key combination processed in the order in which they were passed to the form. It is important to note that any function called must adhere to the following guidelines: 1) It must accept two or three arguments, depending on whether the function must serve Mod_Own or Mod_Oth calls, respectively. The first argument will always be the key pressed which activated the binding. The second and third will be references to state hashes, where all widget options may be manipulated directly, according to the argument names listed in the B documentation for those widget types. 2) If desired, it may return the string "Quit_Form" if you wish it to exit the current form after calling that function. In the example below, the following routine will be bound to a list box widget (as will be seen in the next example). Upon pressing the 'a' key, a input box will be displayed. If the user enters either an A, R, W, or O, the contents of the list box will be modified. If the user presses a 'd' while the list box has the focus, though, the highlighted entry will be deleted from the list. B local *mod_priv = sub { my $key = shift; my $in_ref = shift; my ($priv, $button, $prompt); if (lc($key) eq "a") { $prompt = "Type 'A' for Administrative,\n " . "'R' for read,\n 'W' for write,\n or " . "'O' for other."; ($priv, $button) = input_box( 'title' => 'Add Privilege', 'prompt'=> $prompt, 'function' => \&clock); Curses::Forms->refresh_forms; if ($button) { $priv = uc($priv); if ($priv eq "A") { push(@{$$in_ref{'list'}}, 'Administrative') unless (grep /Admin/, @{$$in_ref{'list'}}); } elsif ($priv eq "R") { push(@{$$in_ref{'list'}}, 'Read') unless (grep /Read/, @{$$in_ref{'list'}}); } elsif ($priv eq "W") { push(@{$$in_ref{'list'}}, 'Write') unless (grep /Write/, @{$$in_ref{'list'}}); } elsif ($priv eq "O") { push(@{$$in_ref{'list'}}, 'Other') unless (grep /Other/, @{$$in_ref{'list'}}); } else { status_bar(0, "'$_' is not a valid option."); beep(); } @{$$in_ref{'list'}} = sort @{$$in_ref{'list'}}; } } elsif ($key =~ /^[Dd]$/) { splice(@{$$in_ref{'list'}}, $$in_ref{'selected'}, 1); } }; The following example shows the above function being bound to the list box, which is named 'privs'. B $form->bind(["privs", "[aAdD]", "Mod_Own", \&mod_priv ], ["command", "[ \n]", "Mod_Own", \&action ]); tab_order --------- The 'tab_order' method takes a list of widget names in the order that they should be given the focus as the user navigates from one to the other. Note that you can leave widgets out of this order if their only function is to display information pushed into them via the Mod_Oth action, etc. You can also redefine widget order as needed, since each time the method is called, the entire order array is cleared before processing the passed list. The only error-checking this method does is to verify that each widget specified in the order was defined via the 'add' method. B $form->tab_order(qw( f_name email name psswd privs command )); set_defaults ------------ The 'set_defaults' method allows the setting of form-wide defaults. It is called with a series of key/value pairs, of which the following keys are valid: Keys ------------ DEF_FUNC Subroutine reference, to be used in the background while each widget is waiting for input. Defaults to ''. DEF_TAB String, for interpolation in a regex which will be the default key triggering a change in focus to the next widget in the tab order. Defaults to "\t". DEF_ACTV String, the default colour to be used by widgets when they have the focus. Colour choices are those supported by the 'select_colour' function provided by B. Defaults to 'green'. DEF_INACTV String, the default colour to be used by widgets when they do not have the focus. Defaults to 'red'. BORDER Boolean, a true or false value which controls whether or not the form has a border. Defaults to 0. BORDER_COLOUR String, with the colour to be used when drawing the form border. Defaults to the default foreground colour. TITLE String, the title to be superimposed on the form border, or where the form border would be if used. All arguments are optional, and if the defaults are acceptable, this method can be completely ignored. The only error-checking done is a check on each key/value pair to see if they are a known option. B $form->set_defaults(DEF_FUNC => \&clock, BORDER => 1, BORDER_COLOUR => 'blue', TITLE => ' Add User '); activate -------- The 'activate' method is used for two purpose: to simply display the form in it's current state and immediately exit, and to display and activate the form, capturing input and managing widget navigation until the 'Quit_Form' action is recieved. To display the form, pass the method any argument that evaluates to 'true'. To activate the form, call the method with no arguments. Error checking is done upon each call to ensure that the form geometry won't exceed the current console dimensions, as well as for each widget, to ensure their geometry doesn't exceed the form's dimensions. B $form->activate; refresh_forms ------------- The 'refresh_forms' method is a class method, not an object method (though calling it via the object reference will achieve the same objective). The purpose of this function to clean the screen of any form remnants in background forms. For example, consider the situation of three forms with the following dimensions: +-Form 1----------------------------------------------------+ | | | +-Form 2------------------------------+ | | | | | | | +-Form 3-----------------------------+ | | | | | | | | | | | | | +------------------------------------+ | | | | | | +-------------------------------------+ | +-----------------------------------------------------------+ The scenario here is that an action taken on Form 1 prompted Form 2 to pop up, and an action on Form 2 prompted Form 3 to be displayed. Because each form is created in its own private window (not a sub or derived window from the master window created during Curses initialisation), when Form 3, disappears, and Form 2 regains the focus, the region outside of Form 2 will not be refreshed to remove the overlapping Form 3 region, leaving you with the following: +-Form 1----------------------------------------------------+ | | | +-Form 2------------------------------+ | | | | | | | |----+ | | | | | | | | | | | | | |----+ | | | | | | +-------------------------------------+ | +-----------------------------------------------------------+ Calling this class method will send a touchwin and refresh signal to each of the windows, from back to front, leaving you with: +-Form 1----------------------------------------------------+ | | | +-Form 2------------------------------+ | | | | | | | | | | | | | | | | | | | | | | | | | | +-------------------------------------+ | +-----------------------------------------------------------+ It is good to call this function whenever a child window is closed whose borders extended past the parent window's borders. B Curses::Forms->refresh_forms; Troubleshooting =============== Curses::Forms will never intentionally kill your script. It does do some basic checks upon creation and before executing certain methods, and if it finds something amiss, it will use the warn function to report the error. When testing scripts that use this module, you'd be well advised to pipe STDERR to a file, so that it doesn't mess with the current display. Checking that file later will show you what specific areas of the script have problems. Otherwise, the display might become corrupted, and cause perfectly valid function calls to *appear* screwey, when it was only the fact that the STDERR moved the cursor location before the next STDOUT output could be rendered. If you run into problems that appear to be the fault of the module, please send me the STDERR output and a script that demonstrates the problem. HISTORY ======= See the Changelog for in depth change history. AUTHOR ====== All bug reports, gripes, adulations, and comments can be sent to Arthur Corliss, at *corliss@odinicfoundation.org*.  File: pm.info, Node: Curses/Widgets, Next: Cwd, Prev: Curses/Forms, Up: Module List Curses-based widgets and functions ********************************** NAME ==== Curses::Widgets - Curses-based widgets and functions Doc/Module Version info ======================= $Id: Widgets.pod,v 1.2 2000/03/17 00:30:03 corliss Exp corliss $ SYNOPSIS ======== use Curses::Widgets; --or-- use Curses::Widgets qw( :standard ); # same as above use Curses::Widgets qw( :functions ); # just functions use Curses::Widgets qw( :all ); # everything REQUIREMENTS ============ Requires the Curses module, Curses or nCurses libraries. You must still 'use Curses;' in your script as well. DESCRIPTION =========== This module provides a standard library of functions and widgets for use in creating Curses-based interfaces. Should work reliably with both Curses and nCurses libraries. Current widgets include: Text field (txt_field) List box (list_box) Button sets (buttons) Calendar (calendar) Message box (msg_box) Input box (input_box) Extra functions include: select_colour line_split grab_key init_scr Note that all of the widgets strictly use named parameters, while the functions use unamed arguments. All of them either return values, or modify references that were passed as arguments. Also note, for purpose of screen geometry, that all values passed for specifying 'cols' and 'lines' refers only to the dimensions of the actual content area, and does not include the border decorations. You will typically need to plan for an additional 2 for both 'cols' and 'lines' to account for these. EXPORTED ======== Default ------- * txt_field * buttons * list_box * calendar * msg_box * input_box * select_colour * init_scr OK -- * line_split * grab_key WIDGETS ======= Text field ---------- The text field widget creates a derived window (which uses coordinates relative to the passed window) with a border surrounding the text. When used interactively, it handles its own input, passing back only the keys it doesn't know how to handle, as well as the final content string and cursor position. If border decorations are enabled (they are, by default), the widget provides an arrow superimposed on the border to indicate whether there is content that can be scrolled to in that direction. The arrow only appears when the content exceeds the display area. The field is underlined if border decorations are turned off. Currently, this widget will handle any normal characters to be inserted into the content string, and the following keys: Key Curses Constant ------------------------------- backspace KEY_BACKSPACE delete KEY_DC left arrow KEY_LEFT right arrow KEY_RIGHT up arrow KEY_UP down arrow KEY_DOWN page up KEY_PPAGE home KEY_HOME,KEY_FIND end KEY_END,KEY_SEARCH All parameters are passed as named parameters: Parameter Commments ----------------------------------- window object handle to parent window for the widget ypos integer, optional, default is 1 xpos integer, optional, default is 1 lines integer, optional, default is 1 cols integer, optional, default is $COLS - 2 content string, optional, default is "\n" password integer, optional default is 0 pos integer, optional default is 0 border string, optional default is 'red' decorations integer, optional default is 1 edit integer, optional default is 1 hz_scroll integer, optional default is 0 function reference, optional draw_only integer, optional default is 0 l_limit integer, optional c_limit integer, optional title string, optional regex string, optional, default is "\t" cursor_disable integer, optional default is 0 'window' is a object handle to a predefined window or subwindow. A quick tip for debugging: if either 'xpos', 'ypos', 'lines', or 'cols' cause any portion of the window to extend passed the boundaries of the parent window, the module will print an error message to STDERR, and immediately exit the routine-no attempt will be made to draw or activate the widget. 'border' is the English name of the common console colours. See the 'select_colour' function for a list of available colours. 'content' is a string containing the text you wish to fill the field with. 'password' will cause all text to show up as asterixs when printed. This is obviously intended for input that needs visual feedback, while maintaining content security. 'pos' refers to the cursor position for use in interactive mode, so that input can be inserted or appended to the content string. This is ignored if passed in conjunction with the draw_only parameter. Valid settings are 0 - length($string), or -1 to place the cursor at the end of the string. 'decorations' enables or disables the border/title/arrow decorations on the field. When disabled, the field will be underlined, to give some visual indication of the size of the field. 'edit' turns on or off editing capabilities in the widget. The field is still navigable with all special keys, but no cursor will be printed, and the content will not be affected by typed input. 'hz_scroll' enables horizontal scrolling in the text field, instead of the normal behaviour of splitting on white space and presenting a new line. This will only work with one line widgets. If you call this widget with any value of 'lines' greater than one, horizontal scrolling will automatically be disabled. 'function' is a scalar reference to a subroutine that can be called by the widget when it times out, waiting for input. For this to work, it assumes a halfdelay(10) has been called, or on some other interval. 'l_limit' and 'c_limit' are completely optional, and can be used together, if desired. Both are integers, and can limit the content in the text field. Which ever limit is hit first will be honoured. 'title' is an optional string that will be superimposed over the top-left border in reverse video. 'regex' is a string of all the characters that you wish to use to shift focus off the text field, and return the contents. By default, the tab character is used ("\t"). This string is interpolated inside of character class brackets, so don't include regex specific punctuation. If you wish both new lines and tabs to shift focus, you would use "\t\n". 'cursor_disable' disables the internal routine that prints it's own cursor. It's best used when you are passing it a background function that updates another portion of the screen, otherwise, when that update occurs, the cursor would disappear from the field. However, if you don't have such a function, the cursor will appear right next to the software cursor, giving it the appearance of a two character cursor. In those situations, you should use this option to disable the software cursor. The memory allocated for the window is released when the widget routine exits. B txt_field( 'window' => $window, 'ypos' => 2, 'xpos' => $COLS - 5, 'lines' => $LINES - 10, 'cols' => $COLS - 10, 'content' => $note, 'border' => 'red', 'draw_only' => 1); B<(Interactive)> ($key, $rtrnd_note, $pos) = txt_field( 'window' => $window, 'ypos' => 2, 'xpos' => $COLS - 5, 'lines' => $LINES - 10, 'cols' => $COLS - 10, 'content' => $note, 'border' => 'green', 'pos' => length($note), 'function' => \&clock); List box -------- The list box widget creates a derived window that holds a scrollable list of items, surounded by a border. When called interactively, it handles it's own input for navigation. Any keys not used for navigation are returned, as well as the currently selected item, unless the 'regex' option is used. If so, it will only return if the key matches the regex. Key Curses Constant ------------------------------- up arrow KEY_UP down arrow KEY_DOWN page up KEY_PPAGE page down KEY_PPAGE The widget provides an arrow superimposed on the border to indicate whether there is content that can be scrolled to in that direction. The arrow only appears when the content exceeds the display area. All parameters are passed as named parameters: Parameter Commments ----------------------------------- window object handle to parent window for the widget ypos integer, optional, default is 1 xpos integer, optional, default is 1 lines integer, optional, default is 1 cols integer, optional, default is $COLS - 2 list hash or array reference border string, optional default is 'red' selected integer, optional, default is first element function reference, optional draw_only integer, optional default is 0 title string, optional regex string, optional sort string, optional default is 'numeric' All previously described parameters maintain their same use and warnings. 'list' can be either a hash reference or an array reference. If a hash is passed, the value will be displayed, but the key will be returned as the selected entry. The list will also be numerically sorted according to key value when displayed. If 'list' is an array reference, the list will be displayed in array order, and the index number of the element will be returned as the selected value. 'regex' works in the same manner as the the equivalent option in txt_field. 'sort' determines the type of sort used on the key values of lists passed as hashes (it has no affect on lists passed as lists). It defaults to a 'numeric' sort, but if you wish it to use an 'alphabetic' sort, you just need to set it accordingly. B list_box( 'window' => $main, 'ypos' => 2, 'lines' => 10, 'cols' => 25, 'list' => \%list, 'border' => 'red', 'selected' => 1, 'draw_only' => 1); b<(Interactive)> ($input, $selected) = list_box( 'window' => $main, 'ypos' => 2, 'xpos' => 5, 'lines' => 10, 'cols' => 25, 'list' => \@list, 'border' => 'green', 'selected' => $last, 'function' => \&clock); Button set ---------- The button bar creates a derived window as well, printing the passed buttons, and handles the key strokes to navigate amongst them, while passing any other keystrokes and the currently selected button. The button set can be rendered either vertically or horizontally, and the keystrokes that can be used for navigation depend upon that. Like the list_box, if the 'regex' option is used, it will only return on matching values. Key Curses Constant ------------------------------- left arrow KEY_LEFT right arrow KEY_RIGHT up arrow KEY_UP down arrow KEY_DOWN All parameters are passed as named parameters: Parameter Commments ----------------------------------- window object handle to parent window for the widget buttons reference ypos integer, optional, default is 1 xpos integer, optional, default is 1 active_button integer, optional function reference, optional vertical integer, optional draw_only integer, optional default is 0 spacing integer, default is 2 regex string, optional Again, all previously described parameters remain the same. Boundary checking is still done for the entire bar, and if it exceeds them it will simply be skipped without drawing, while sending an error message stating as much to STDERR. 'buttons' is an array reference with each element a separate button. 'active_button' is the element's positional reference. 'spacing' is the number of whitespace used to separate the buttons (spaces in horizontal mode, lines in vertical mode). If 'vertical' is passed with a Perlish true value the button set will be rendered as a vertical set. B buttons( 'window' => $win_bar, 'buttons' => \@buttons, 'active_button'=> 2, 'draw_only' => 1); b<(Interactive)> ($input, $selected) = buttons( 'windows' => $win_bar, 'buttons' => \@buttons, 'active_button' => $last, 'function' => \&clock); Calendar -------- The calendar widget creates a fully navigable calendar in a derived, bordered window. The calendar controls its own input until it captures a keystroke it doesn't explicitly handle. In that case, it returns the key. Like the button_bar and list_box, though, this widget has a regex function. Key Curses Constant ------------------------------- left arrow KEY_LEFT right arrow KEY_RIGHT up arrow KEY_UP down arrow KEY_DOWN home KEY_HOME page up KEY_PPAGE page down KEY_NPAGE The home key, in this case, moves the selected date to the the current date. The page up and down keys move the calendar from month to month. All parameters are passed as named parameters: Parameter Commments ----------------------------------- window object handle to parent window for the widget ypos integer, optional, default is 1 xpos integer, optional, default is 1 date_disp reference border string, optional default is 'red' function reference, optional draw_only integer, optional default is 0 t_colour string, optional default is 'yellow' e_colour string, optional default is 'red' events reference regex string, optional 'date_disp' is an array reference that holds the desired date to display (in day, month, year format). If date_disp is not passed (or an empty list reference is given instead), it will be initialised with the current date. Should the widget be called in interactive mode, the reference will be modified to display the last date navigated to by the user. The first element, [0], is the day, the second, [1], the month, and the third, [2], the year. 't_colour' highlights the current date in the desired colour. If colour is not available, then the current date will be displayed in bold. 'e_colour' will highlight each date found in the 'events' array ref in the desired colour. Date formats for the 'event' array must be 'dd/mm/yyyy', with no leading zeros. B calendar( 'window' => $main, 'date_disp' => \@date, 'border' => 'red', 'draw_only' => 1); B<(Interactive)> $input = calendar( 'window' => $main, 'date_disp' => \@date, 'border' => 'blue', 'function' => \&clock); Message Box ----------- The msg_box displays the passed message in a new window that erases once acknowledged. It automatically scales and centers itself according to the console and the passed message. Parameter Commments ----------------------------------- title string, optional message string, optional border string, optional defaults to 'blue' function reference, optional mode integer, optional All previously described options remain the same. It only responds to the ENTER or space key. Mode refers to the buttons drawn with the message. By default, it only draws an OK button, but if set to 2, it will display both an OK and a CANCEL button. In that instance, the widget will return a 1 if OK was selected, or a 0 if CANCEL was selected. B msg_box( 'title' => "Critical Error!", 'message' => "Now, you've done it!", 'border' => "red"); Note that there is a minimum needed console size for this to work, which is currently 5 rows by 14 columns. If the console size is at least that size, the message box will render. Also note, though, that both the message and the title may get chomped down to alloted window space, if you pass it more than it can display. Further, if the function parameter is used, and the passed function updates the screen, you may see the message box disappear, though it is still trapping key strokes. To avoid this behaviour, refresh the current screen before calling this function. Input Box --------- The input_box displays a dialog box with a prompt, a one-line input field, and a two buttons, OK and *CANCEL*. Like the msg_box, this widget automatically scales and centers itself according to the prompt. Unlike the msg_box, however, this widget returns two values; the first being the value of the text field, the second being a 1 if the OK button was pressed, or a 0 if the *CANCEL* button was pressed. Hitting ENTER while in the text field is a shortcut for pressing the OK button. Parameter Commments ----------------------------------- title string, optional prompt string, optional cols integer, optional border string, optional defaults to 'blue' f_colour string, optional defaults to 'yellow' c_limit defaults to 4096 content string, optional function reference, optional 'cols' overrides the internally calculated width requirements (formerly determined by the prompt width) to the specified setting. This forces the field width to be cols - 2 in width as well. 'f_colour' is the colour to use for the text field border when it has the focus. It will use the same colour set in 'border' This widget requires a minimum console size for this to work, which is 8 rows by 24 columns. Both the title and the prompt may be chomped to accomodate available screen space. 'c_limit' is simply passed to the text widget to restrict the length of the typed string. Horizontal scrolling is enabled. B ($field, $button) = input_box( 'title' => 'Password', 'prompt' => 'Enter Password:', 'border' => 'blue'); If the function parameter is used, and the passed function updates the screen, you may see the message box disappear, though it is still trapping key strokes. To avoid this behaviour, refresh the current screen before calling this function. FUNCTIONS ========= select_colour ------------- Usage: *select_colour($window, foreground [, background])* This function sets the character attributes for all subsequent characters to the specified colour, for the specified window. The first two arguments are required, the first being an object handle to the window, and the second a string denoting the desired foreground colour. A background colour can also be given, but if not, it defaults to black. Valid colours are black, cyan, green, magenta, red, white, blue, and yellow. All attributes stay in effect until another set is declared, or all attributes are reset via *attrset(0)*. B select_colour($main, 'yellow'); init_scr -------- Usage: *init_scr($miny, $minx)* This function tests the terminal for both minimum dimensions and interactivity. If either condition is detected to be unsatisfactory, it produces a warning on STDERR, and returns a false condition. If it tests okay, however, it will return a handle to a new Curses object. It will also set the default keypad, halfdelay, noecho, and cbreak options. The miny and minx, minimum lines and columns, respectively, are optional. If omitted, the standard console size of 25 lines by 80 columns will be checked for. B $mwh = init_scr(40, 80); line_split (not exported by default) ------------------------------------ Usage: *line_split(string, line_length)* This function returns the submitted string as a list, each element being a separate line. It accounts for not only column limits, but whitespace as well, splitting a sentence by whitespace, so as to not break words. B @lines = line_split($note, 80); grab_key (not exported by default) ---------------------------------- Usage: *grab_key($wh [, \&func_ref])* This function returns the pressed key, calling the passed function reference while waiting. Only the first argument is mandatory, that being the object handle for the window gathering the key strokes. The function reference passed will be called while waiting for a key to pressed, but only works if you've initialised the console for half-blocking mode. Ie., to call that function every half a second: halfdelay(5); Troubleshooting =============== Curses::Widgets will never intentionally kill your script. It does do some basic checks before executing some routines, and if it finds something amiss, it will use the warn function to report the error. When testing scripts that use this module, you'd be well advised to pipe STDERR to a file, so that it doesn't mess with the current display. Checking that file later will show you what specific areas of the script have problems. Otherwise, the display might become corrupted, and cause perfectly valid function calls to *appear* screwey, when it was only the fact that the STDERR moved the cursor location before the next STDOUT output could be rendered. You should also consider overloading the __DIE__ signal handler, to make sure that Curses returns your terminal to a usable state in case of fatal errors. If you run into problems that appear to be the fault of the module, please send me the STDERR output and a script that demonstrates the problem. HISTORY ======= See the Changelog for in depth change history. So far, I haven't broken any of the default exported functions, so most scripts should run unmodified. 2000/02/21 - v1.1 Improved error handling/reporting, misc bug fixes, and major feature additions to the input_box, txt_field, list_box, and calendar. Added init_scr function 2000/01/15 - v1.0 Version promotion for first stable release 2000/01/15 - v0.10 Degugging, added input_box, msg_box widgets 1999/11/17 - v0.9 Internal calendar generation, improved error handling/ reporting, added spacing argument to button bar, removed init_colours function 1999/06/17 - v0.8 Added line_split function, title options, minor rewrites 1999/04/14 - v0.7 Added l_limit/c_limit to text field 1999/02/02 - v0.6 Colour-capability detection added, up/down charactersadded for content out-of-view indication, additional debugging 1999/01/11 - v0.5 Debugging 1999/01/10 - v0.4 Special key support added, special character constants used, new select_colour function 1999/01/03 - v0.3 rewrite/optimisation 1998/12/30 - v0.2 rewrite/optimisation 1998/12/29 - v0.1 Initial release (text field, list box, buttons, calendar) AUTHOR ====== All bug reports, gripes, adulations, and comments can be sent to Arthur Corliss, at *corliss@odinicfoundation.org*.