MULTI-LEVEL PULL-DOWN MENUS REFERENCE GUIDE Version 2.0 April 15, 1989 Copyright (C) 1987-1989 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 T A B L E O F C O N T E N T S 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 3 Purpose . . . . . . . . . . . . . . . . . . . . . . . 3 Fill-in-the-Blank . . . . . . . . . . . . . . . . . . 3 2. FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 4 checkforpop . . . . . . . . . . . . . . . . . . . . . 4 checkforpulldown . . . . . . . . . . . . . . . . . . 4 checkglobalkeys . . . . . . . . . . . . . . . . . . . 4 displayfields . . . . . . . . . . . . . . . . . . . . 4 enter . . . . . . . . . . . . . . . . . . . . . . . . 5 enterseq . . . . . . . . . . . . . . . . . . . . . . 5 getoverridestats . . . . . . . . . . . . . . . . . . 5 getuserpullstats . . . . . . . . . . . . . . . . . . 5 gotokeydispatcher . . . . . . . . . . . . . . . . . . 6 helpkeypressed . . . . . . . . . . . . . . . . . . . 6 hiliterow . . . . . . . . . . . . . . . . . . . . . . 6 initpull . . . . . . . . . . . . . . . . . . . . . . 6 initpulldata . . . . . . . . . . . . . . . . . . . . 6 popped . . . . . . . . . . . . . . . . . . . . . . . 7 pulldirectory . . . . . . . . . . . . . . . . . . . . 7 pullhelpwndw . . . . . . . . . . . . . . . . . . . . 7 readkbd . . . . . . . . . . . . . . . . . . . . . . . 7 setcmdseq . . . . . . . . . . . . . . . . . . . . . . 8 showerrmsg . . . . . . . . . . . . . . . . . . . . . 8 showmsg . . . . . . . . . . . . . . . . . . . . . . . 8 showtopline . . . . . . . . . . . . . . . . . . . . . 8 strjl . . . . . . . . . . . . . . . . . . . . . . . . 9 strjr . . . . . . . . . . . . . . . . . . . . . . . . 9 topkeypressed . . . . . . . . . . . . . . . . . . . . 9 turnarrows . . . . . . . . . . . . . . . . . . . . . 9 workwndw . . . . . . . . . . . . . . . . . . . . . . 9 3. DATA STRUCTURE . . . . . . . . . . . . . . . . . . . . 10 Configuration Macros . . . . . . . . . . . . . . . . 10 Main Menu Declarations . . . . . . . . . . . . . . . 11 Submenu Declarations . . . . . . . . . . . . . . . . 16 Message Line Declarations . . . . . . . . . . . . . . 17 Help Window Declarations . . . . . . . . . . . . . . 18 Data Window/Entry Declarations . . . . . . . . . . . 20 APPENDIX A: MEMORY ALLOCATION . . . . . . . . . . . . . . 25 Static vs. Dynamic . . . . . . . . . . . . . . . . . 25 Global Memory . . . . . . . . . . . . . . . . . . . . 25 Dynamic Memory . . . . . . . . . . . . . . . . . . . 25 Code Size . . . . . . . . . . . . . . . . . . . . . . 26 APPENDIX B: ERROR MESSAGES . . . . . . . . . . . . . . . 27 2 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 1. I N T R O D U C T I O N PURPOSE This document is a technical reference manual describing each routine and variable in detail in a format similar to the TC manual. The routines are described in alphabetical order. Since this manual is on disk, you can find your interest easily with any search utility. Application - Because PULLC calls QWIKC and WNDWC, all routines will perform in the following applications: . All video text modes - 0, 1, 2, 3 and 7. . Any column mode - 40, 80, or variable. . For IBM PC, XT, AT, PCjr, PC convertible, all PS/2 models, 3270 PC, and compatibles. . With MDA, CGA, EGA, MCGA, VGA, 8214/A, all Hercules video cards. . Perform routines in both absolute and window-relative coordinates. Please note that the demonstration files are set to work on an 80 column mode on video page 0 in a non-multi-tasking environment. However, these can be changed with the source code. FILL-IN-THE-BLANK Since most of PULLC is based on the fill-in-the-blank concept for structures, there are only a few functions that you would need to know about data entries and specialized programming of user windows. Most of your interest will probably be in the Data Structure section that follows later, so you know which "blanks" you can fill. Chapter 1, Introduction Page 3 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 2. F U N C T I O N S In this section, a detailed description is provided for each function and function. --------------------------------------------------------------------------- checkforpop PULLC --------------------------------------------------------------------------- Function Sets pop to 1 if menu(s) need to be removed. Syntax void checkforpop(void); Remarks This function is primarily used in user windows that to interface with the pull-down menus. It analyzes the current status of the menu control flags to see if one or more menus need to be removed. Return value None. See also checkforpulldown Example See the User Window section in PULLC20.DOC. --------------------------------------------------------------------------- checkforpulldown PULLC --------------------------------------------------------------------------- Function Displays help message, reads keyboard input, and permits background processing while keyboard is idle. Syntax void checkforpulldown( unsigned char msglinenum ); Remarks This function is primarily used in user windows that to interface with the pull-down menus. It analyzes the current status of the menu control flags to see if it has reached its destination menu/window. If waitforkbd is 0 when entering this function, it will assume that key and extkey are set correctly and not wait for the keyboard input for just one pass. readkbd and kbdidle are called. Return value None. See also checkforpop, kbdidle, readkbd Example See the User Window section in PULLC20.DOC. --------------------------------------------------------------------------- checkglobalkeys PULLSTAT --------------------------------------------------------------------------- Function Provides a case of global keystrokes to access any part of the program at any time. Syntax void checkglobalkeys(void); Remarks Global keys can be any extended key. The contents are optional, but the function must exist. Return value None. See also getuserpullstats, getoverridestats --------------------------------------------------------------------------- displayfields PULLC --------------------------------------------------------------------------- Function Displays the contents of a sequence of data entry fields given the first and last structure index numbers. Syntax void displayfields( unsigned char first, unsigned char last ); Remarks Fields are displayed in window-relative coordinates. Chapter 2, Functions Page 4 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 Return value None. See also enter, enterseq --------------------------------------------------------------------------- enter PULLC --------------------------------------------------------------------------- Function Edits a field for a single data entry given the data entry structure. Syntax void enter( int recnum ); Remarks This function is used if you want to customize your own sequence of entry. recnum is the index number of the data entry. This function only shows the string being edited for input. For output display, use displayfields. Return value None. See also displayfields, enterseq --------------------------------------------------------------------------- enterseq PULLC --------------------------------------------------------------------------- Function Edits a sequence of fields for data entry given the data entry structure indices. Syntax void enterseq( int first, int last, int *start ); Remarks This function handles full editing of a sequence of data entries handled by smart hilite algorithms. The sequence of entry is the order of dataentrynames in PULLDATA.C. First/last are the first and last structure index numbers in the sequence. Start is where you want the hilite to start, and keeps up with the current structure. Use displayfields once before editing. Return value None. See also displayfields, enter --------------------------------------------------------------------------- getoverridestats PULLSTAT --------------------------------------------------------------------------- Function Overrides any default configurations set by getuserpullstats and initpull. Syntax void getoverridestats(void); Remarks If you have any exceptions for your menu structures, place your assignments in this function. The contents are optional, but the function must exist. Return value None. See also checkglobalkeys, getuserpullstats --------------------------------------------------------------------------- getuserpullstats PULLSTAT --------------------------------------------------------------------------- Function Initializes all menus, windows and message lines for the pull-down environment. Syntax void getuserpullstats(void); Remarks The contents are optional, but the function must exist. Return value None. See also checkglobalkeys, getoverridestats Chapter 2, Functions Page 5 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 --------------------------------------------------------------------------- gotokeydispatcher PULLC --------------------------------------------------------------------------- Function Turns control over to PULLC. Syntax void gotokeydispatcher(void); Remarks This function is called by your main program after all the data structures have been initialized. Return value None. Example See PULLDEMO.C. --------------------------------------------------------------------------- helpkeypressed PULLC --------------------------------------------------------------------------- Function Trivial function determins if the context-sensitive help key has been pressed. Syntax int helpkeypressed(void); Remarks PULLC is currently assigned the F1 key for the help window. Return value The return value is either 0 or 1. See also topkeypressed, pullhelpwndw --------------------------------------------------------------------------- hiliterow PULLC --------------------------------------------------------------------------- Function Highlights a line in a menu. Syntax void hiliterow( unsigned char row, int attr ); Remarks This function can be used in any user menu to show the hilite bar by simply changing the attribute. Row is a window-relative row and attr is the attribute for the hilite. Return value None. --------------------------------------------------------------------------- initpull PULLC --------------------------------------------------------------------------- Function Initializes WNDWC and PULLC structures. Syntax void initpull( int attr, char clearscr, char cursorok ); Remarks Attr is the attribute of WINDOW0 and is also assigned to the global variable initattr. If clearscr is 1, it will clear the screen which is not necessary for PERMMODE windows. If cursorok is 0, the cursor shape may be changed (see WNDWC initwindow() source for details.) This function must be called only once. Return value None. --------------------------------------------------------------------------- initpulldata PULLWORK --------------------------------------------------------------------------- Function Initializes data entry/window structures. Syntax void initpulldata(void); Remarks initpulldata is called by initpull. Return value None. Chapter 2, Functions Page 6 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 --------------------------------------------------------------------------- popped PULLC --------------------------------------------------------------------------- Function Used to detect if all menus have all been removed before executing menu functions. Syntax void popped(void); Remarks This function is called in functions called by the menu funcptr. PULLC executes the funcptr function twice when popped is used. It sets several flags for you including popandprocess. The first time popped is tested it returns 0 and sets the appropriate flags. When the menus are removed and funcptr is executed again, popped will return 1. This allows your statement to read like plain English. Return value popped returns either 0 or 1. Example This function is called by a funcptr in a menu: void myfunc(void) { if(popped) domyfunc(); } --------------------------------------------------------------------------- pulldirectory PULLDIR --------------------------------------------------------------------------- Function Displays the contents of the current disk directory. Syntax void pulldirectory( char *nametochange, char *nametohilite ); Remarks Pressing RETURN on the hilited item will assign it to nametochange. If nametohilite is not NULL, the menu will be displayed initially with the hilite centered in the menu on nametohilite. If nametohilite is NULL, the hilite will just be centered on the first page. Return value None. Example See PULLSTAT.PAS for PULLDEMO.PAS. --------------------------------------------------------------------------- pullhelpwndw PULLC --------------------------------------------------------------------------- Function Displays a context-sensitive help window. Syntax void pullhelpwindow( unsigned char wndwnum ); Remarks This function can be called in any function where keyboard input is tested. wndwnum is the helpwndw index number, but using the helpwndwnames is easier. Return value None. See also helpkeypressed --------------------------------------------------------------------------- readkbd PULLC --------------------------------------------------------------------------- Function Reads keyboard input and permits background processing while keyboard is idle. Syntax void readkbd( char *extkey, unsigned char *key ); Remarks extkey is set to 1 if the key is extended. key is the character of the key entered. In addition, holding down the Alt key will display the global key combination message. Chapter 2, Functions Page 7 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 Also, while the keyboard is idle, the kbdidle function is being continually executed. Return value None. See also checkforpulldown, kbdidle --------------------------------------------------------------------------- setcmdseq PULLC --------------------------------------------------------------------------- Function Sets PULL control flags to shortest path to the new menu. Syntax void setcmdseq( seqstr_t newcmdseq ); Remarks newcmdseq is the sequence of command letters pressed after F10 to arrive at a new menu or window. newcmdseq and the current position, cmdseq, are compared to create an new path by setting morecmdseq and poplevels. Return value None. --------------------------------------------------------------------------- showerrmsg PULLC --------------------------------------------------------------------------- Function Shows an error message on the message line. Syntax void showerrmsg( int errmsgnum ); Remarks errmsgnum is the index of the errmsgline to display. It is easier to use the errmsgnames enumeration to identify the message to display. This message is usually used by data entry routines. After pressing ESC to acknowledge the message, the original message is restored. Return value None. See also showmsg Example Show the error message line named MYERRMSG_EM: showerrmsg( MYERRMSG_EM ); --------------------------------------------------------------------------- showmsg PULLC --------------------------------------------------------------------------- Function Shows a message on the message line. Syntax void showmsg( unsigned char msgnum ); Remarks msgnum is the index of the msgline to display. It is easier to use the msglinenames enumeration to identify the message to display. Return value None. See also checkforpulldown, showerrmsg Example Show the message line named MYMSG_ML: showmsg( MYMSG_ML ); --------------------------------------------------------------------------- showtopline PULLC --------------------------------------------------------------------------- Function Simply displays the unhighlighted Top Line Menu. Syntax void showtopline(void); Remarks This function is used to initially display the Top Line menu for the screen design in PULLWORK.C or PULLSHEL.C. It writes the string toplinestr to the screen which is Chapter 2, Functions Page 8 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 assembled by initpull. --------------------------------------------------------------------------- strjl PULLC --------------------------------------------------------------------------- Function Returns a string left justified in a field of spaces. Syntax char far *strjl( char far *instr, char far *outstr, unsigned char field ); Return value strjl returns a far pointer to outstr. Remarks If field is less than the length of the string, nothing is done. See also strjr --------------------------------------------------------------------------- strjr PULLC --------------------------------------------------------------------------- Function Returns a string right justified in a field of spaces. Syntax char far *strjr( char far *instr, char far *outstr, unsigned char field ); Return value strjr returns a far pointer to outstr. Remarks If field is less than the length of the string, the string is simply returned. See also strjl --------------------------------------------------------------------------- topkeypressed PULLC --------------------------------------------------------------------------- Function Trivial function returns 1 if the top line menu key has been pressed. Syntax int topkeypressed(void); Return value topkeypressed returns 0 or 1. Remarks PULLC is currently assigned the F10 key for the top line menu. See also helpkeypressed --------------------------------------------------------------------------- turnarrows PULLC --------------------------------------------------------------------------- Function Displays or removes arrows on the highlighted line of a menu that pulls down a submenu or user window. Syntax void turnarrows( int toggle ); Remarks This function is used primarily to interface with user windows that require the arrows to be turned on or off. Return value None. Example See the User Window section in PULLC20.DOC. --------------------------------------------------------------------------- workwndw PULLWORK --------------------------------------------------------------------------- Function Provides a switch statement containing steps for the work window as the main part of the program. Syntax void workwndw(void); Remarks The contents are optional, but the function must exist. Return value None. Example See PULLSHEL.C and PULLDEMO.C. Chapter 2, Functions Page 9 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 3. D A T A S T R U C T U R E This section will help describe the data structure of PULLC and how it can be adjusted. The variables in PC20VAR.C are allocated according to the macros set in PULLC20.H. There are several basic variables, but if desired, there are additional variables for virtual windows and multiple video pages. Please refer to the source code in PC20VAR.C and PULLC20.H for the exact listing. CONFIGURATION MACROS These constants configure the size of the data structure. If you have the complete source code, the macros can trim the PULLC code to fit the requirements of your application program. While developing the program, you can balloon these values so that PULLC does not need to be recompiled every time the program expands. Macro Value Description -------------------- ----- -------------------------------------------- NUM_OF_MAIN_MENUS 1-255 Sets the number of main menus to be allocated in the heap. NUM_OF_SUB_MENUS 1-255 Sets the number of submenus to be allocated in the heap. MAX_MENU_LINES 1-253 Sets the maximum number of menu lines in each menu structure. MAX_CHARS_PER_LINE 1-247 Sets the maximum number of characters per line in all menu lines. It also limits the size of the title for the data windows. NUM_OF_DATA_WNDWS 1-255 Sets the number of data window structures to be held in the heap. NUM_OF_DATA_ENTRIES 1-255 Sets the number of data entry structures to be held in the heap. DATA_STR_SIZE 1-255 Sets the size of a data entry string. This is calculated as the maximum number of characters that can be entered in a data entry of any kind, plus one. NUM_OF_HELP_WNDWS 1-255 Sets the number of help window structures to be declared as static data. TOTAL_HELP_LINES 1-255 Sets the maximum number of help lines to be declared in the helpline array as static data. HELP_CHARS_PER_LINE 1-241 Sets the maximum number of characters per line in all help windows. Remember this excludes the two extra spaces between Chapter 3, Data Structure Page 10 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 border and text, as well as the null at end of string. NUM_OF_MSG_LINES 1-255 Sets the maximum number of message lines to be declared in the msgline array as static data. CRT_STR_SIZE 1-255 Sets the maximum number of characters that can appear on a CRT. NUM_OF_ERR_MSG_LINES 1-up Sets the maximum number of message lines to be declared in the errmsgline array as static data. ERR_STR_SIZE 1-255 Sets the maximum number of characters in a single errstrline message (plus one for null). This is usually less than CRT_STR_SIZE, but cannot be greater. MAIN MENU DECLARATIONS The following enumerations, typedefs, variables, and macros are used primarily for the main menus. The variables are described, as closely as possible, in the order of their appearance in the file PULLC20.H. Enumerations - These definitions are used for assigning values to menu structure members. Enum name Description ------------ ----------------------------------------------------------- menumodes This enumeration gives a name for three different menu modes. Each mode controls how each line will interact with the other lines. Name Description --------------- -------------------------------------- EXEC_CHOICE Executes the functions indicated by funcptr and does not interact with the other menu lines. This is the default. SINGLE_CHOICE Flags only the selected line in the menu and turns off all other flags. If funcptr is not NULL, it will also execute the function before flagging. MULTIPLE_CHOICE Toggles the flag on any line in the menu. If funcptr is not NULL, it will also execute the function before flagging. linemodes This enumeration gives a name for seven different line modes for any one line in the menu. Name Description ------------ ------------------------------------------ Chapter 3, Data Structure Page 11 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 CHOICE Interacts with the rest of the menu according to the given menu mode. EXEC_ONLY Only executes funcptr and ignores flagging. NO_CHOICE Disables line as a valid choice, but can be restored by replacing the original line mode. COMMENT Places text on the line with a different attribute and passed by the highlight. PARTITION Places a horizontal border through the menu and is passed by the highlight. TO_DATA_WNDW Places a dot symbol on the line and pulls down a data entry window. TO_SUB_MENU Places a three-bar symbol on the line and pulls down a submenu. TO_USER_WNDW Places a three-bar symbol on the line and executes funcptr. toggle This enumeration is just a practical way of understanding the source code to indicate the common binary conditions of On/Off and Yes/No. Type definitions - These typedefs are used to structure variables for the main menus: fptr This is the typedef established for function pointers and is a generic pointer type. crtstr_t Combined with crtstr_t, this typedef will limit the size of strings needed to display data onto the screen. It is usually used for message lines. seqstr_t This typedef is used for strings that keep a record of the command sequence. Since the sequence is not greater than the number of windows on the screen at any one time, MAXWINDOW is used. menu_t This structure is used to fully describe any menu. Each member is worth describing. title - For main menus, this name will appear on the top line menu. cmdltrs - initpull assigns the first letter of each menu line to be its corresponding command letter. This string keeps these assignments in sequence so that the line 1 letter is position 1, line 2 is position 2, etc. line - This is the array of the actual text that will appear on each menu line. The default is "". linemode - This array is the line mode corresponding to each line. The default is CHOICE. flagged - This array is the status of the flag corresponding to each line. The default is 0. Chapter 3, Data Structure Page 12 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 linknum - This array has the byte value of submenu or data window names of structures to be linked. The default is 0. funcptr - This array has the pointers for executing functions when the menu line is selected. The default is NULL which executes nothing. parentdir - This is the linking direction assigned to the parent menu of this menu (which would be a submenu). For main menus, this value is NO_DIR. linkdir - This is the linking direction assigned to all submenus on this menu which is determined by initpull. menumode - This is the menu mode. menulines - This is the number of lines contained in this menu and is determined by initpull. namecol - For main menus, this is the column that the hilite is to appear on the top line menu which would highlight the title. row .. cols - These variables locate and size the window for the menu. defaultline - This is the line to be highlighted when the program first starts. hiliteline - This is the current position of the hilite on this menu. singleflagline - This is the line that has the only flag in SINGLE_CHOICE menu mode. The following variables control the attributes in the menus. SAMEATTR is not suggested. battr - Border wattr - Entire window contents hattr - Hilite lattr - Command letter cattr - COMMENT line Border - This is the border style used for the menu. backtodefault - If set to 1, the hilite will return to the defaultline every time the menu is pulled down. The default is 0. changed - PULLC will toggle this to 1 if any of the flags have been altered. It is up to the programmer to reset it to 0 if it is needed. Chapter 3, Data Structure Page 13 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 msglinenum - This is the index number of the msgline to be displayed concurrently with this menu. helpwndwnum - This is the index number of the helpwndw structure to be displayed for this menu when context- sensitive help is requested. Variables - The following are the global variables used to create and control the pull-down menus: Variable Description ------------ ----------------------------------------------------------- mainmenu (Type: menu_t *) This is the pointer to the array of main menu structures in the heap. topmenu (Type: menu_t) As each menu structure is accessed, main menu or submenu, a copy of the structure is made in topmenu to increase speed and save code. The structure is saved back in the heap after use. mri (Type: int) When a menu is copied into topmenu, the array index of the structure is saved in this variable for later reference. lastmainmenu (Type: unsigned char) This is the index of the last main menu displayed on the far right of the top line menu. It is <=NUM_OF_MAIN_MENUS. toplinestr (Type: crtstr_t) This is the actual string that appears as the top line menu when showtopline is used. toplinerow (Type: unsigned char) This is the row on which toplinestr appears. mainmenurow (Type: unsigned char) This is the row on which the top border of the main menus appears. Attributes - The following variables control the default attributes and border in all the main menus and the top line menu. Name Type Description ------------- ------------- ------------------------------------- initattr unsigned char base screen, set by attr in initpull. toplineattr unsigned char top line menu. toplinehattr unsigned char hilite on top line menu. toplinelattr unsigned char command letters on top line menu. mainmenuwattr unsigned char entire window contents. mainmenubattr unsigned char main menu border. mainmenuhattr unsigned char hilite in main menu. mainmenulattr unsigned char command letters in main menu. mainmenucattr unsigned char comment line. mainmenubrdr unsigned char main menu border style. Chapter 3, Data Structure Page 14 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 Keyboard - The following variables contain the last keyboard input from readkbd or checkforpulldown. Variable Description ------------ ----------------------------------------------------------- key (Type: unsigned char) Contains the key code of the input. extkey (Type: char) Set to 1 if extended key. waitforkbd (Type: char) Causes a wait for keyboard input when executing checkforpulldown. If it is 0, then the current values of key and extkey are considered valid and execution continues. waitforkbd is initialized to 1 in PC20DATA.C. Control Flags - The following variables programmably control the pull-down menus in lieu of the end user. Variable Description ------------ ----------------------------------------------------------- pulldown (Type: char) When set to 1, the menus will be pulled down from their current position according to the sequence in morecmdseq. pop (Type: char) This flag is controlled by checkforpop, which sets it to 1 if the program needs to pop out of the current menu. poptoworkwndw (Type: char) If 1, the menus will all pop and return control to the work window. poptotop (Type: char) If 1, control is set to highlight the top line menu. popandprocess (Type: char) This flag is controlled by the popped function to execute a funcptr in the menus after all the menus have been popped. poplevels (Type: unsigned char) This flag is controlled by setcmdseq or can be used manually. It simply pops the number of levels of menus/windows. quit (Type: char) This flag controls execution of the program. If set true, the program will terminate with all menus popped. Menu Sequence - The following variables indicate the current status of the menus and work windows. You can know what the current menu is and the current sequence of letter commands to get there. Variable Description ------------ ----------------------------------------------------------- topcmdltrs (Type: string) This is the counterpart of cmdltrs for the Chapter 3, Data Structure Page 15 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 top line menu. It holds the command letters for the top line menu where character 0 corresponds to the first main menu, character 1 to the second, etc. cmdseq (Type: seqstr_t) This is the current sequence of letters used to arrive at the current menu/window where the last character is the last menu. While in the work window, this string is null. Do not change this string. morecmdseq (Type: seqstr_t) When performing a programmed pulldown, this is the sequence of letters yet to be executed in the same order as cmdseq. mpulled (Type: unsigned char) This is the index of the current main menu pulled. spulled (Type: unsigned char) This is the index of the current submenu pulled. If no submenu is pulled, this value is 0. hilited (Type: char) This is the row number of the currently highlighted line. accessedworkwndw (Type: char) This is a handy flag available for testing in your program. If you are in the menus and you run your custom routine with funcptr to set this to 0, the next time the work window is accessed, this variable will be set to 1. accessedmenus (Type: char) This is a handy flag available for testing in your program. If you are in the work window and set this to 0, the next time the menus are accessed, this variable will be set to 1. workwndwstep (Type: int) This is the current step number assigned to the work windows in PULLWORK. topworkwndwname (Type: int) This is the name of the work window to be selected for access or the current one on top. inworkwndw (Type: char) When set to 1, this flag indicates if the program is in the work window. It is otherwise in the menus. Key macros - Several key macros have already been provided for frequently used keys. Please refer to PULLC20.H for the listing. SUBMENU DECLARATIONS The following type and variables are used for the sub menus. The variables are described, as closely as possible, in the order of their appearance in the file PULLC20.H. The program was carefully planned so that main menu structures would match that of the submenus. Chapter 3, Data Structure Page 16 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 The row/col fields in the menu structure for submenus default to zero so that PULLC can locate them at run time for the slide-up configuration. If they are set to non-zero values in PULLSTAT, then the menu will be located absolutely to the screen at (row,col). Variables - The following are the static variables used to allocate and configure the submenus: Variable Description ------------ ----------------------------------------------------------- submenu (Type: menu_t *) This is the pointer to the array of submenu menu structures in the heap. lastsubmenu (Type: unsigned char) This is the index of the highest submenu index number in use. It is <=NUM_OF_SUB_MENUS. Attributes - The following variables control the default attributes and border in all the submenus. Name Type Description ------------ ------------- ------------------------------------- submenuwattr unsigned char entire window contents. submenubattr unsigned char submenu border. submenuhattr unsigned char hilite in submenu. submenulattr unsigned char command letters in submenu. submenucattr unsigned char COMMENT line. submenubrdr unsigned char submenu border style. MESSAGE LINE DECLARATIONS The following typedef and variables are used to generate normal key messages or error messages on the message line. Typedef - The following typedef is the only one needed for error messages: Type Description ------------- ----------------------------------------------------------- errmsgstr_t This is the type used to give the size for all error messages based on ERR_MSG_SIZE. Since they are usually short, they can be trimmed to the length of the longest one (add one for null). Variables - The following variables are given initial values to process the messages on the message line. Variables Description ----------------- ------------------------------------------------------ currentmsglinenum (Type: int) This is the index of the current msgline displayed on the screen. Initialized to 0. enablekeystatus (Type: char) When set to 1, the status of NumLock, ScrollLock, and CapsLock will appear on the message line. Initialized to 1. Chapter 3, Data Structure Page 17 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 More Variables - The following variables allocate space for the messages in static data and control the location of the messages and the key status indicators: Variable Description ------------ ----------------------------------------------------------- msgline (Type: array of crtstr_t strings) This array allocates static data space for the messages. If you intend to have several messages, you should consider making this data in the heap. errmsgline (Type: array of errmsgstr_t) This array allocates global data space for the error messages. If you intend to have several messages, you should consider making this data in the heap. msglinerow (Type: unsigned char) This is the absolute row on which all messages and error messages are to appear. capslockcol (Type: unsigned char) This is the column on the message line row on which the status indicators will appear. Attributes - The following variables control the attributes on the message line. Name Type Description ------------- ------------- ------------------------------ errmsgattr unsigned char For error messages. keystatusattr unsigned char For the key status indicators. msglineattr unsigned char For the normal messages. HELP WINDOW DECLARATIONS The following types and variables are used to create context-sensitive help windows. Typedef - The following structure is the only one needed for help windows: Type Description ------------ ----------------------------------------------------------- helpwndw_t This structure is used to fully describe any help window. Each field is described below: firstline/lastline - This is the first and last indexes in the helplines array that has the messages to appear in the help window. linestoshow - For now, the help window is a single page display and so this value is simply the number of lines from firstline to lastline. row .. cols - These variables locate and size the help window. helpbottomrow and HELP_CHARS_PER_LINE are used Chapter 3, Data Structure Page 18 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 to calculate these values. The following variables control the attributes in the menus. SAMEATTR is not permitted. battr - Border set by helpwndwbattr wattr - Entire window contents set by helpwndwwattr border - This is the border style used around the window and set to helpwndwbrdr by default. hwmodes - This is the window modes used to create the window on the screen. helpwndwmodes is used to set this value by default. msglinenum - This is the index number of the msgline to be displayed concurrently with the help window and is set by default to helpmsglinenum. Variables - The following variables allocate space for the structures and help lines in static data and control the location and appearance of the window: Variable Description -------------- --------------------------------------------------------- helpwndw (Type: array of helpwndw_t) This array allocates static data space for the help windows. If you intend to have many help windows, you should consider making this data disk-based. helpline (Type: array of errmsgstr_t) This array allocates static data space for all the help lines. helpbottomrow (Type: unsigned char) This is the default row on which the bottom row of the help window is to appear. This keeps help windows down lower. helpwndwmodes (Type: unsigned char) This is the default used to set helpwndw[x].hwmodes. See PULLC20.DOC for setting this variable. helpmsglinenum (Type: unsigned char) This is the index of msgline for the message to appear concurrently with the help window. The index HELP_ML has been reserved as the default, but new ones can be used as well. Attributes - The following variables control the default attributes and border in all the submenus. Name Type Description ------------- -------- ------------------------------------- helpwndwwattr unsigned char entire window contents. helpwndwbattr unsigned char help window border. helpwndwbrdr unsigned char help window border style. Chapter 3, Data Structure Page 19 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 DATA WINDOW / ENTRY DECLARATIONS The following enumerations, typedefs, and variables are used to create data entry windows and work window data entry fields. Enumerations - The following enums are used to structure the data window/entry structures: Enumeration Description -------------- --------------------------------------------------------- typesofdata This enum is used to indicate the type of data being processed. Although the identifier list is intuitive, here is the list indicating its corresponding data type: Name Data type --------- ------------- BYTES char UNSIGNED_BYTES unsigned char INTS int UNSIGNED_INTS unsigned int LONGS longs UNSIGNED_LONGS unsigned long FLOATS float DOUBLES doubles USERNUMS datastr_t CHARS char STRINGS datastr_t setnames This enum identifies character sets to be used for filtering each keystroke. All of the names except FILENAME_SET, PATH_SET, and MASK_SET are reserved, but you can add your own sets before NO_SET. Type Definitions - The following typedefs are used to structure the data window/entry structures: entryset_t This is the structure for allocating the data entry filter sets for the array entryset. dataentry_t This structure is used to fully describe any data entry. Each member is described below: varaddr - This pointer contains the address where the contents of the entry are stored. typeofdata - This declares the type of data located at varaddr. It is up to your programming skills to make sure that varaddr and typeofdata agree. row .. col - For data windows, these values default to (1,2) for the field location. For data entry, this is Chapter 3, Data Structure Page 20 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 the window-relative location of the field. field - This is the number of columns designated for the input and output to be displayed. maxfield - This is the maximum number of characters that can appear in a field. They can be less than or greater than field. If greater, flex-field entry is used. For strings, be sure that maxfield is no longer than the string destination +1 or DATA_STR_SIZE. precision - For floats and doubles, this value is used to format the output display. gcvt(), which chooses either ecvt() or fcvt() format based on precision, is used for the conversion. setname - This is the name of the set used to filter the keystrokes into the field. This variable is set by default according to typeofdata. translatefunc - This function pointer is used to execute a function to intercept the keystroke for translation. The default is NULL. checkrangeproc - This function pointer is used to execute a function for checking the range or content of the entry before it is stored in the assigned variable. The default is NULL. justify_output - The justification of the output in data entry fields can be displayed by displayfields either right or left justified. By default, numbers are right justified and strings left. The following variables control the attributes in the menus. iattr - Input default set by datawndwiattr oattr - Output default set by datawndwoattr msglinenum - This is the index number of the msgline to be displayed concurrently with this entry during input. helpwndwnum - This is the index number of the helpwndw record to be displayed when context-sensitive help is requested. datawndw_t This structure is used to fully describe any data window. Each member is described below: title - This is the title to appear centered on the top row of the border. The default is "". dwrow / dwcol - If these values are the default zero, PULLC will locate the window at run time for the slide- Chapter 3, Data Structure Page 21 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 under configuration. Non-zero values will override PULLC and locate the window absolute to the screen. battr - This is the attribute of the data window border. border - This is the border style of the border. entry - (Type: dataentry_t) This is a structure within the datawndw_t that fully describes the field inside the window. datastr_t Combined with DATA_STR_SIZE, this type definition will limit the size of strings that can be entered/read from any data entry. datapad_t This structure conveniently groups all of the data needed for the data pad. Each one of the fields is described below. storemode - If set to 1, the data pad will store the data to its destination variable, else the data pad reads the contents of the variable. valid - The result saved from the validity check for numbers is 1 if it passes, otherwise 0. datastored - If the data passes the validity check, the range check, and is stored, this variable is set to 1. It is later used to set topmenu.changed to 1. newdata - This flag is used internally to indicate an untampered entry has been displayed for editing. Once the data is edited, this value is 0. pulldw - This flag indicates that a pull-down data window is being used for data entry. fieldindex - This is the index of datastr for the first character shown in the field. cursorofs - This is the offset from fieldindex for the position of the cursor. hattr - The attribute for the hilite used to move from field to field in the work window or user window can be any attribute. If SAMEATTR is used, only the cursor is moved and the output attribute remains unchanged. errmsg - After a range check, if this value is zero, the entry value is in range. If not, it is the number of the error message to be displayed. flex - If maxfield is greater than field, this value is set to 1 to indicate a flex field. Chapter 3, Data Structure Page 22 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 justify - This indicates the type of justification for the input and output display of the field. Input is always left, but output can either be left or right. dataspace - The last field in the data pad is the scratch pad for placing any type of data. To access the data, use one of the following macros: Macro Data type ----------- ------------- bytedata char ubytedata unsigned char intdata int uintdata unsigned int longdata long ulongdata unsigned long floatdata float doubledata double userdata string chardata char strdata string Initialized array - entryset is the array of the actual sets of valid characters used for filtering the keystrokes before being entered into the field. Along with each index name is the application of the set. All sets except HEX_SET, FILENAME_SET, PATH_SET, and MASK_SET are reserved. Other sets can be appended. Index name Application ------------ ----------------------------------------- UNSIGNED_SET For unsigned bytes, ints, and longs SIGNED_SET For bytes, ints, and longs FLOAT_SET For floats and doubles CHAR_SET For chars, strings and misc. entry HEX_SET For USERNUMS and specifically hexadecimal FILENAME_SET For DOS file names PATH_SET For DOS full path file names MASK_SET For DOS full path file names with wildcard Variables - The following variables allocate space for data windows, data entries, and the data pad: Variable Description ------------ --------------------------------------------------------- dwi (Type: int) Data window index used to save the current data window index number currently in topdatawndw. dei (Type: int) Data entry index used to save the current data entry index number currently in topentry. topdatawndw (Type: datawndw_t) The current datawndw structure is copied into this structure, thus saving code. Chapter 3, Data Structure Page 23 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 topentry (Type: dataentry_t) The current dataentry structure is copied into this structure, thus saving code. datawndw (Type: datawndw_t *) This pointer points to the array of data window structures in the heap. dataentry (Type: dataentry_t *) This pointer points to the array of data entry structures in the heap. datastr (Type: datastr_t) This is the actual string edited on the screen during an entry into a field. The size of the string is limited by DATA_STR_SIZE. datapad (Type: datapad_t) This is the data pad used to transfer data between the destination variable and the screen. autotab (Type: char) When set to 1 for enterseq, the hilite will advance to the next field automatically after entry. autonumlock (Type: char) For numerical entries, this flag will automatically turn on NumLock, which is shown on the message line with the key status indicator. Chapter 3, Data Structure Page 24 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 A P P E N D I X A : M E M O R Y A L L O C A T I O N This section covers the memory requirements for static data in the data segment and dynamic data in the heap. This will give you the figures on how to estimate the memory needed for your program. CHOOSING STATIC VS. DYNAMIC As is, PULLC uses both static and dynamic memory for structures and messages. The menus and data window/entry structure arrays are dynamic while the help window and messages use static data. Depending on the needs of your application program, you can change these variables to pointers or arrays instead and modify PULLC to allocate or not allocate the required memory for them. This can only be done if you have the source code. Note: ALL allocation in PULLC is done using calloc or malloc. This causes the pointers to be near or far based on the model size. PULLDEMO - In the demonstration, it was chosen to use the messages and help windows as static data since the program was so small. In larger programs that need more static data, these arrays can be shifted to dynamic memory or even to disk. We have not provided any routines for this. However, with PULLC's flexibility, no serious problems should stand in your way if you choose to do this. GLOBAL MEMORY Global Memory - The following values reflect both the approximate minimum data requirements when global memory is a premium, and the allocation used in PULLC20S.LIB using the current configuration macros: Min Demo Features Bytes Bytes Comments ------------------------------- ----- ----- ------------------- Basic pull-down menus 652 652 Submenus 12 12 Data window/entry, filter sets 579 675 Help windows 34 4611 Used static in demo Messages 16 1326 Used static in demo ----- ----- Total allocation 1293 7276 Of course your application will vary, but these figures give you a good estimate of the amount of memory being used. The demo figures for the help windows and messages are higher because the text strings were placed in static data. DYNAMIC MEMORY Dynamic Variables - To alleviate using static data, dynamic variables are used for permanent and temporary use. The allocation for menus and data window/entry structures are permanent throughout the program. Many other Appendix A: Memory Allocation Page 25 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 functions such as pulling down menus temporarily use the heap to perform operations. Permanent Variables - Based on the macros near the top of PULLC20.H, the following allocation can be calculated: Demo Arrays Calculation Bytes ------------ --------------------------------------------------- ----- Menus sizeof(menu_t)*(NUM_OF_MAIN_MENUS+NUM_OF_SUB_MENUS) 6045 Data windows sizeof(datawndw_t)*(NUM_OF_DATA_WNDWS) 768 Data entries sizeof(topentry)*(NUM_OF_DATA_ENTRIES) 220 Again, this is just a general idea of what your program would allocate. This is totally dependent on the values defined for the configuration macros. Temporary Variables - When pulling down menus, the underlays are accessed in a serial fashion, so your calculations can be exact. There is no need to double the size of the heap needed as you would for random access. For a further discussion on dynamic memory allocation for windows, please refer to the appendix in WNDWREF.DOC. CODE SIZE Code Size - PULLC is also very frugal with with code. Here is the approximate breakdown for code usage in the Small model (sizes will vary between models): Code Description Bytes ------------------------------- ----- Basic pull-down menus 4148 Additional for submenus 1177 Additional for data wndw/entry 4138 (with floating point, 4594) Additional for help windows 808 Additional for messages 764 ----- Total code 11035 (with floating point, 11491) This gives you a good idea of how small the code really is! Appendix A: Memory Allocation Page 26 PULLC Multi-level Pull-Down Menus Reference Guide, Version 2.0 A P P E N D I X B : E R R O R M E S S A G E S PULLC uses the GOOF module just as WNDWC does, although the GOOFS.OBJ and GOOF.C included with PULLC differ from those in WNDWC. Should you make a mistake in programming with windows or PULLC, the program will terminate with an error message window on the CRT to reveal any problem. The GOOF module can be freely edited. WNDWC The following error messages occur when a mistake has been made in creating or controlling windows: "Not enough heap space" - The minimum heap size is too small. Increase the size as required in APPENDIX A of WNDWC20A.DOC. "Too many windows" - Tried to create more windows than MAXWINDOW allows. Either remove windows or increase MAXWINDOW. "Too many virtual windows" - Tried to create more virtual windows than MAXVIRTUALWINDOW allows. Either remove windows or increase MAXVIRTUALWINDOW. "Perm window out of order" - Tried to create a PERMMODE window while a normal window is the top window. Remove or hide window before making a permanent window. Routinely, all PERMMODE windows are created first. "No window to remove" - Tried to remove the initial window WINDOW0 which is permanent. "Hidden window not found" - Tried to write to a hidden window that does not exist. Check for the correct name. "Virtual screen not found" - Tried to write to a virtual screen that does not exist. Check for the correct name. "Video page not available" - Tried to write to a video page that has not been allocated or does not exist for the hardware as expected. Be sure to use MAXVALIDPAGE. PULLC Only the following error message will occur in PULLC: "A Submenu could not fit" - Tried to fit a menu that was too wide to fit in the slide-up configuration. Set location_warning to 0 and test all submenus to see if the slide-under alternative is acceptable. If not, override the default location by manually assigning the row and col values of the menu record in getuserpullstats. Appendix B: Error Messages Page 27