\begindata{text,537620288}
\textdsversion{12}
\template{default}
\define{italic
menu:[Font,Italic]
attr:[FontFace Italic Int Set]}
\define{bold
menu:[Font,Bold]
attr:[FontFace Bold Int Set]}
\define{chapter
menu:[Title,Chapter]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{section
menu:[Title,Section]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 2]}
\define{subsection
menu:[Title,Subsection]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{paragraph
menu:[Title,Paragraph]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Italic Int Set]}
\define{bigger
menu:[Font,Bigger]
attr:[FontSize PreviousFontSize Point 2]}
\define{indent
menu:[Region,Indent]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]}
\define{typewriter
menu:[Font,Typewriter]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{display
menu:[Region,Display]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[Justification LeftJustified Point 0]}
\define{example
menu:[Region,Example]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Justification LeftJustified Point 0]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{description
menu:[Region,Description]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Indent LeftEdge Inch -32768]}
\define{quotation
menu:[Region,Quotation]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[RightMargin RightMargin Inch 32768]
attr:[FontFace Italic Int Set]}
\define{subscript
menu:[Font~1,Subscript~31]
attr:[Script PreviousScriptMovement Point 2]
attr:[FontSize PreviousFontSize Point -2]}
\define{superscript
menu:[Font~1,Superscript~30]
attr:[Script PreviousScriptMovement Point -6]
attr:[FontSize PreviousFontSize Point -2]}
\define{smaller
menu:[Font,Smaller]
attr:[FontSize PreviousFontSize Point -2]}
\define{heading
menu:[Title,Heading]
attr:[LeftMargin LeftMargin Inch -13107]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{majorheading
menu:[Title,MajorHeading]
attr:[Justification Centered Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{formatnote
menu:[Region,FormatNote]
attr:[Flags PassThru Int Set]}
\define{subheading
menu:[Title,Subheading]
attr:[Justification LeftJustified Point 0]
attr:[FontFace Bold Int Set]}
\define{center
menu:[Justify,Center]
attr:[Justification Centered Point 0]}
\define{flushleft
menu:[Justify,FlushLeft]
attr:[Justification LeftJustified Point 0]}
\define{flushright
menu:[Justify,FlushRight]
attr:[Justification RightJustified Point 0]}
\define{leftindent
menu:[Region,LeftIndent]
attr:[LeftMargin LeftMargin Inch 32768]}
\majorheading{C Panel and Menus Handling Package

}
\center{Author - Larry K. Raper

Menu Code by Mark Chance

Unix Support by Mike Sclafani

Version 2.0

(C) Copyright IBM Corporation 1986, 1987, 1988

Program Property of IBM

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $}}}

\heading{Abstract

}
This package supports monochrome, color, and B/W displays via the standard PC 
BIOS Int 0x10 Video Interface.  Also supported are terminals with cursor 
movement capability via the curses/termcap interface on Unix systems.


Provides high level definition of input and output screens for easy user 
manipulation.  Also provides programmer-friendly mechanisms for defining 
hierarchic menus in the style of Lotus 1-2-3.


The normal sequence of the panel handler calls is


1.  InitPanels		(once)

2.  SaveVideoEnv		(once)

3.  DrawPanel		(as needed)

4.  GetKey		(once)

5.  RestoreVideoEnv	(once)


The normal sequence of the menu handler calls is


1.  InitMenus		(once)

2.  SetBaseMenu		(once)

3.  MenuInput		(as needed)


The keytab provided to GetKey is presumed to contain an exit key.


\heading{General Panel Data Structures}


There are several useful definitions provided in the panel input/output 
package.  To use these your program must #include "panel.h".


\subheading{PANEL}


This is the fundamental output structure.


struct \{

    char	prow, pcol,	Starting row, column of panel.  (0,0) is upper left.

	pattr,		Panel attribute from list of field attribute values

	plen;		Number of characters for input.  Zero for an output panel.

    char  *pdata;		Panel text data

    \};


A panel array ends in (0,0,0,0,NULL).


Example:

\example{
PANEL login_boilerplate2[] = \{

    19,  3, RVIDEO, 0, "F1",

    19,  6, NORMAL, 0, "Login",

    19, 13, RVIDEO, 0, "F2",

    19, 16, NORMAL, 0, "Logout",

    19, 27, RVIDEO, 0, "PgDn",

    19, 32, NORMAL, 0, "Display other sessions",

    19, 60, RVIDEO, 0, "Esc",

    19, 64, NORMAL, 0, "Return to DOS",

     0, 0, 0, 0, NULL

     \};


PANEL PCSERVER_lines[] = \{

    14,  3, NORMAL, 0, "Root Directory ",

    16,  8, NORMAL, 0, "PC Drive  ",

    0, 0, 0, 0, NULL

    \};


PANEL *PanelArray[] = \{

    login_boilerplate1,

    login_boilerplate2,

    PCSERVER_lines,

    No_PCSERVER_lines,

    login_data,

    NULL\};}


\subheading{FIELD

}
A field is the fundamental input structure.  Each field consists of one or 
more extents for input and one prompt that will be shown when the field has 
the input focus.


struct field \{

    struct field *freturn;		Next field on 'return' key

    struct field *fup;			                    'up'

    struct field *fdown;		                    'down'

    struct field *fleft;		                    'left'

    struct field *fright;		                    'right'

    XTENT *flocation;		Field location ending in a zero-triplet 

    unsigned char fattr;		Video attribute of field

    char   ftype;			Type of data in field

    char  *fdata;			Data to display in field

    PRMPT *fprompt;		Prompt to show when in field

    void (*fmodifyhandler)();		Function to call when field is modified

    void (*fentryhandler)();		Function to call on entry

    void (*fexithandler)();		Function to call on exit

    \};


\subheading{XTENT}


An extent is one segment of a field.  Generally extents do not cross lines.


struct \{

    unsigned char xrow, xcol, xlen;	Row, column, and length vector

    \};


\subheading{PRMPT}


A prompt is the text shown at the bottom of the screen when the user moves the 
cursor into a new field.


typedef struct \{

    char plen;		Prompt length

    char *pdata;		Prompt text

    \} PRMPT;


Example:


\example{PRMPT toprompt = \{0, "Enter the names of people to send the message 
to" \};

XTENT to_xtents[] = \{ 1, 4, TOCC_FIELD_LEN, 2, 4, TOCC_FIELD_LEN, 3, 4, 
TOCC_FIELD_LEN, 0, 0, 0 \};

char to_data[1+TOCC_FIELD_LEN*3];


PRMPT subprompt =\{0, "Enter the subject of your message" \};

XTENT subj_xtents[] = \{ 4, 9, SUBJ_FIELD_LEN, 0, 0, 0 \};

char subj_data[1+SUBJ_FIELD_LEN];


PRMPT ccprompt = \{0, "Enter the names of people to receive copies of your 
message" \};

XTENT cc_xtents[] = \{ 5, 4, TOCC_FIELD_LEN, 6, 4, TOCC_FIELD_LEN, 7, 4, 
TOCC_FIELD_LEN, 0, 0, 0 \};

char cc_data[1+ TOCC_FIELD_LEN*3];


PRMPT boprompt = \{0, "Enter the text of your message" \};


FIELD entry_fields[] = \{

/\italic{*0:To:*/} &entry_fields[1], &entry_fields[3], &entry_fields[1],

    &entry_fields[1], &entry_fields[1], to_xtents, NORMAL,

    FTYPE_ASC, to_data, &toprompt, SetSavethepage, (int (*)()) NULL, (int 
(*)())NULL,

/\italic{*1:Su:*/} &entry_fields[2], &entry_fields[0], &entry_fields[2],

    &entry_fields[2], &entry_fields[2], subj_xtents, NORMAL,

    FTYPE_ASC, subj_data, &subprompt, SetSavethepage, (int (*)()) NULL, (int 
(*)())NULL,

/\italic{*2:CC:*/} &entry_fields[3], &entry_fields[1], &entry_fields[3],

    &entry_fields[3], &entry_fields[3], cc_xtents, NORMAL,

    FTYPE_ASC, cc_data, &ccprompt, SetSavethepage, (int (*)()) NULL, (int 
(*)())NULL,

/\italic{*3:bod*/} &entry_fields[0], &entry_fields[2], &entry_fields[0],

    &entry_fields[0], &entry_fields[0], (XTENT *) NULL, NORMAL,

    FTYPE_SCR, NIL, &boprompt, SetSavethepage, (int (*)()) NULL, 
EntryPageDnKey,

    NULL_FIELD

    \};


FIELD *FieldArray[] = \{

     entry_fields,

     (FIELD *) NULL,

     \};}


\subheading{Field attribute values}


NORMAL	Normal on all displays

HILITE		Hilite on all displays

RVIDEO		Reverse Video

BLINKH		Blink + HILITE

REGDIF		RVIDEO unless B/W adapter

NORMCE	Same as NORMAL, unless color

NORMCI	Same as NORMAL, unless color

HILITC		Same as HILITE, unless color

RVIDHI		Reverse Video + HILITE

WHTBLU	While on blue, or normal

INVISI		Invisible

RINVIS		Reverse Video & invisible data

UNDERN	Normal underline

UNDERH	Hilited underline


\subheading{Field type values}


FTYPE_ASC	character string

FTYPE_INT	integer

FTYPE_YN	yes or no

FTYPE_SEL	cursor selection field

FTYPE_WRD	word (without blanks)

FTYPE_SCR	automatic scroll field


\subheading{KEYTAB}


This structure allows you to build tables which define how to treat special 
keys.  The key codes are defined in keycodes.h which contains definitions for 
both the PC and terminals.


struct \{

    int scan_code;

    FIELD *(*keyhandler)();

    \};


Example

\example{
KEYTAB login_keys[] = \{

    KEYCODE_F1,  NewLogin,			/* F1 	*/

    KEYCODE_F2,  NewLogout,		/* F2 	*/

    KEYCODE_PAGE_DOWN,  NewPriorSession,	/* PgDn */

    KEYCODE_PAGE_UP,  NewNextSession,	/* PgUp */

    KEYCODE_ESCAPE,  EscapeKey,		/* Esc  */

    0, 0\};


FIELD *EscapeKey (curfield)

FIELD *curfield;

    \{

    RestoreVideoEnv (&vp, PANEL_NOCLEAR, 22);

    longjmp (endpanel1, -1);

    \}

}

\subheading{VIDEOPARMS}


This structure holds the state of the system's video parameters.  Generally 
you will not need to change these.


struct \{

    unsigned char palette;

    unsigned char page;

    unsigned char attr;

    unsigned char mode;

    unsigned char columns;

    \};


Example


\example{VIDEOPARMS	vp;

SaveVideoEnv(&vp, 1);

...

RestoreVideoEnv( &vp, PANEL_CLEAR, 0);}



\heading{Menu Creation Data Structures (lmenus.h)}


The package provides data and constant definitions for the 1-2-3 style menus 
enhancements.  Your program must #include "lmenus.h".


\subheading{MKEYTAB

}
This structure is just like KEYTAB except that the handling functions return 
integers instead of field pointers.


struct \{

    int scan_code;		Key code

    int (*keyhandler)();	Handling function

    \} MKEYTAB;


\subheading{MENU_OPTS

}
This structure defines one menu option.  It consists of the one word 
description and a prompt to be displayed when the option is highlighted.


struct \{

    char *Option;		Option word

    PRMPT prompt;	Description of option

    \} MENU_OPTS;


\subheading{MENU_TREE

}
This structure provides the definition of the menu hierarchy.  The first 
element is an index into an array of menu options, the second is a pointer to 
a sub-menu.  (Currently the nesting has only been tested to a level of 3 deep.


struct \{

    int this;

    MENU_TREE *submenu;

    \} ;


Example:


\example{MENU_OPTS vui_menus[] = \{

#define OPT_D_READ 0

"Read", \{0, "Display the list of messages in the highlighted folder"\},

#define OPT_D_ADD 1

"Create", \{0, "Create a new folder"\},

.......

NIL, \{0, NIL\},

\}


MENU_TREE bb_menu[] = \{

OPT_D_READ, (MENU_TREE *)NIL,

OPT_S_POST, (MENU_TREE *)NIL,

OPT_D_INFO, d_info_menu,

OPT_D_SUBSCR, d_subscr_menu,

NULL_MENU

\};


MENU_TREE d_info_menu[] = \{

OPT_D_BRIEF, (MENU_TREE *)NIL,

OPT_D_LONG, (MENU_TREE *)NIL,

NULL_MENU

\};}


The OPT_* constants can be used in the calling program to process the various 
options that are entered by the user.

 	

\heading{Function Calls for Paneling}


To use the functions listed in this section you must compile and link in the 
panelp.c module.


\subheading{InitPanels

}This procedure fills in the length fields in panel and field arrays to agree 
with the corresponding constant strings.  Some minimal consistency checking is 
also performed.

\example{
InitPanels (p, f)

PANEL *p[];

FIELD *f[];}


\subheading{SaveVideoEnv

}This routine should be called early in your program to allow you to exit and 
return the machine to the state is was prior to running your program.

\example{
SaveVideoEnv (vp)

VIDEOPARMS *vp;}


\subheading{RestoreVideoEnv}

This routine should be called just before your program exits.

\example{
RestoreVideoEnv (vp, clear, cursor_row)

VIDEOPARMS *vp;

int clear;

int cursor_row;}


\subheading{ShowString

}This routine allows you to put a text string on the screen.  Generally there 
are higher-level routines that are preferred.  Attr is one of the Field 
Attribute Values.

\example{
ShowString (data, row, col, len, attr)

char *data;

unsigned char row, col, len, attr;}


\subheading{ShowCursor}

This routine redisplays the field currently with input focus.  (At one time 
this field was displayed in reverse video, but it was considered too harsh for 
data entry especially when red is used as the background color, plus it takes 
a while to paint the screen reverse over slow terminals.)

\example{
ShowCursor();}


\subheading{EraseCursor}

This routine removes highlighting from the current field.

\example{
EraseCursor();}


\subheading{ShowPrompt

}This routine displays a prompt.  Again, there are higher-level routines that 
are preferred.


\example{ShowPrompt(msg)

PRMPT *msg;

}
\subheading{DrawPanel}

This routine displays a panel on the screen.

\example{
DrawPanel (panel, inputfield, clear)

PANEL *panel;				An array of panels

FIELD *inputfield;			First field (may be NULL)

int clear;				Flag to indicate clearing the screen}


For the \italic{clear} argument use either of the two constants:

\leftindent{PANEL_CLEAR

PANEL_NOCLEAR}


\subheading{ShowMsg}

\example{
ShowMsg (msg)

PRMPT *msg;}


\subheading{ErrorBeep}

\example{
ErrorBeep();}


\subheading{ShowError}

\example{
ShowError (msg)

PRMPT *msg;}


\subheading{ClearError

}
\example{ClearError();

}
\subheading{ClearLine


}\example{ClearLine(line_no)

int line_no;

}
\subheading{ClearScreen


}\example{ClearScreen();

}
\subheading{RedrawScreen

}This routine is only be needed in a Unix terminal environment.


\example{RedrawScreen();

}
\subheading{UpdateScreen

}This routine is only be needed in a Unix terminal environment.

\subheading{
}\example{UpdateScreen();

}
\subheading{GetCurrentField}

\example{
FIELD *GetCurrentField ();}


\subheading{SetCurrentField}

This routine causes \italic{newfield} to become the current field.  The exit 
handler on the current field is called, its highlighting removed and the entry 
handler of the new field is called and it is highlighted.

\example{
SetCurrentField (newfield, prompt)

FIELD *newfield;

int prompt;}


\subheading{RestoreCurrentField}

This routine changes the current field, but does not update the screen or call 
any of the entry or exit handlers.

\example{
RestoreCurrentField (curfield)

FIELD *curfield;}


\subheading{GetKey}

Wait for the user to press a key, then process the value.

\example{
GetKey (keytable)

KEYTAB *keytable;}


\subheading{GetFromUser

}Use this routine to get an arbitrary string from the user.


\example{GetFromUser(row, col, length, default, field_type, return_str)

int row, col, length;

char *default, field_type, *return_str;

}
\subheading{GetNUser

}Use this routine to get a number within a specified range from the user.


\example{GetNUser(row, col, length, min, max, val_out)

int row, col, length, min, max, *val_out;

}
\subheading{GetSUser

}This routine gets a string from the user using the default locations for 
input and output.


\example{GetSUser(msg, prompt, default, str_out)

char *msg, *prompt, *default, *str_out;

}
\subheading{GetStringFromUser

}Another version with fewer options.


\example{GetStringFromUser(prompt, output, length)

char *prompt, *output;

int length;

}
\subheading{GetBooleanFromUser

}This routine asks the user a yes/no question and returns a boolean value.


\example{GetBooleanFromUser(msg, default)

char *msg, default;

}
\subheading{ConfirmUser

}This routine displays the message and waits for the user to press return.


\example{ConfirmUser(msg)

char *msg;

}
\subheading{KeyHit

}This routine returns a true value if a key has been pressed.


\example{KeyHit();

}
\subheading{KeyIn

}This routine waits for the user to press a key and returns that value.  When 
possible use GetKey.


\example{KeyIn();

}
\subheading{SetCursorPosn

}
\example{SetCursorPosn();

}
\subheading{CursorOff

}This routine turns the flashing cursor off or moves it out of the way on 
terminals that can't turn off the cursor.


\example{CursorOff();

}
\subheading{CursorOn

}This routine turns the cursor on and displays it at the current input 
location.


\example{CursorOn();


}\heading{Function Calls for Menu bars

}
To use the functions listed in this section you must compile and link in the 
lmenus.c module.


\subheading{InitMenus

}Initialize a set of menus by determining the length of each prompt and 
inserting that value into the data structure.  This lets you avoid having to 
count the length of character strings.


\example{InitMenus(menu_opt)

MENU_OPTS *menu_opt;

}
\subheading{SetBaseMenu

}This lets the panelling code know what array you are using.  The menu trees 
contain indices into this array.


\example{SetBaseMenu(menu)

MENU_OPTS *menu;

}
\subheading{ShowMenu

}Display a specified menu.


\example{ShowMenu(menu_tree, current_option)

MENU_TREE menu_tree[];

int current_option;

}
\subheading{EraseMenuCursor

}Turn off the highlighting of a menu option.  Typically you will call this 
routine before beginning to process a menu option.


\example{EraseMenuCursor();

}
\subheading{ShowMenuCursor

}Call this routine to indicate that processing has finished and you are ready 
for input again.


\example{ShowMenuCursor();

}
\subheading{MenuInput

}Display a menu, handle keys according to the table and return a value.  The 
previous option is stored in last_opt_p.


\example{MenuInput( menu_tree, keytable, last_opt_p)

MENU_TREE menu_tree[];

MKEYTAB *keytable;

int *last_opt_p;

}
\subheading{ClearPrompt

}Erase the menu prompt.


\example{ClearPrompt();

}

\heading{Program Sample}


\example{
ShowPanel ()

\{

    FIELD *first_field;


    InitPanels (PanelArray, FieldArray);

    SaveVideoEnv (&vp);


    if (*p_hostname == 0)	first_field = &login_fields[HOSIDX];

    else first_field = &login_fields[USEIDX];


    DrawPanel (login_boilerplate1, NULL, PANEL_CLEAR);

    DrawPanel (login_boilerplate2, NULL, PANEL_NOCLEAR);

    DrawPanel (login_data,  first_field, PANEL_NOCLEAR);

    int i;


    if ((i = setjmp (endpanel1)) != 0) \{  /* Note: because of setjmp	 */

       StripInput ();			/* no register variables may */

       ExitKey ();			    	/* be used in this function. */

    \}


    GetKey (login_keys);

\}


MainMenu ()

\{

    quit = FALSE;


    while (!quit) \{

        if (reshow) \{

            DrawPanel(intro, NIL, PANEL_CLEAR);

            ShowBar();

            reshow=FALSE;

        \}

        opt = MenuInput(main_menu, f1_keys, &last_opt);

        if (opt<0) \{ /* They pressed escape */

            if (!GetBooleanFromUser("Do you really want to quit now?", FALSE))

                return(0);

        \}

        switch (opt) \{

        case OPT_G_MAIL:

            .....

        \}

    \}

\}


}
\heading{Implementer's Notes:

}
Aside from the files mentioned above: (panel.h, panelp.c, lmenus.h, lmenus.c, 
keycodes.h) there is a file that contains screen manipulation routines that 
are machine specific, panelmach.c.

\enddata{text,537620288}
