Phoenix CD 2.0

home *** CD-ROM | disk | FTP | other *** search

/ Phoenix CD 2.0 / Phoenix_CD.cdr / 02a / pull55.zip / PULLREF.DOC < prev next >

Wrap

Text File | 1989-08-24 | 82KB | 1,626 lines

MULTI-LEVEL PULL-DOWN MENUS REFERENCE GUIDE Version 5.5 August 24, 1989 Copyright (C) 1987-1989 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 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. PROCEDURES AND FUNCTIONS . . . . . . . . . . . . . . . 4 CheckForPop . . . . . . . . . . . . . . . . . . . . . 4 CheckForPullDown . . . . . . . . . . . . . . . . . . 4 CheckGlobalKeys . . . . . . . . . . . . . . . . . . . 4 DisplayFields . . . . . . . . . . . . . . . . . . . . 4 Enter . . . . . . . . . . . . . . . . . . . . . . . . 5 EnterSeq . . . . . . . . . . . . . . . . . . . . . . 5 GetOverrideStats . . . . . . . . . . . . . . . . . . 5 GetUserPullStats . . . . . . . . . . . . . . . . . . 5 GotoKeyDispatcher . . . . . . . . . . . . . . . . . . 5 HelpKeyPressed . . . . . . . . . . . . . . . . . . . 6 HiLiteRow . . . . . . . . . . . . . . . . . . . . . . 6 InitPull . . . . . . . . . . . . . . . . . . . . . . 6 InRangeW . . . . . . . . . . . . . . . . . . . . . . 6 Popped . . . . . . . . . . . . . . . . . . . . . . . 6 PullDirectory . . . . . . . . . . . . . . . . . . . . 7 PullHelpWndw . . . . . . . . . . . . . . . . . . . . 7 ReadKbd . . . . . . . . . . . . . . . . . . . . . . . 7 SetCmdSeq . . . . . . . . . . . . . . . . . . . . . . 7 ShowErrMsg . . . . . . . . . . . . . . . . . . . . . 8 ShowMsg . . . . . . . . . . . . . . . . . . . . . . . 8 ShowTopLine . . . . . . . . . . . . . . . . . . . . . 8 StrSL . . . . . . . . . . . . . . . . . . . . . . . . 8 StrSR . . . . . . . . . . . . . . . . . . . . . . . . 9 TopKeyPressed . . . . . . . . . . . . . . . . . . . . 9 TurnArrows . . . . . . . . . . . . . . . . . . . . . 9 WorkWndw . . . . . . . . . . . . . . . . . . . . . . 9 3. DATA STRUCTURE . . . . . . . . . . . . . . . . . . . . 10 Configuration Constants . . . . . . . . . . . . . . . 10 Main Menu Declarations . . . . . . . . . . . . . . . 11 Submenu Declarations . . . . . . . . . . . . . . . . 17 Message Line Declarations . . . . . . . . . . . . . . 17 Help Window Declarations . . . . . . . . . . . . . . 18 Data Window/Entry Declarations . . . . . . . . . . . 20 APPENDIX A: MEMORY ALLOCATION . . . . . . . . . . . . . . 25 Global vs. Dynamic . . . . . . . . . . . . . . . . . 25 Global Memory . . . . . . . . . . . . . . . . . . . . 25 Dynamic Memory . . . . . . . . . . . . . . . . . . . 25 Code Size . . . . . . . . . . . . . . . . . . . . . . 26 APPENDIX B: ERROR MESSAGES . . . . . . . . . . . . . . . 27 2 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 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 TP 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 PULL uses QWIK and WNDW, 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 PULL is based on the fill-in-the-blank concept for records, there are only a few procedures and 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 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 2. P R O C E D U R E S A N D F U N C T I O N S In this section, a detailed description is provided for each procedure and function. --------------------------------------------------------------------------- CheckForPop procedure Pull --------------------------------------------------------------------------- Function Sets Pop true if menu(s) need to be removed. Declaration CheckForPop Remarks This procedure 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. See also CheckForPullDown Example See the User Window section in PULL55.DOC. --------------------------------------------------------------------------- CheckForPullDown procedure Pull --------------------------------------------------------------------------- Function Displays help message, reads keyboard input, and permits background processing while keyboard is idle. Declaration CheckForPullDown (MsgLineNum: byte) Remarks This procedure 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 false when entering this procedure, 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 subroutines. Example See the User Window section in PULL55.DOC. See also CheckForPop, KbdIdle, ReadKbd --------------------------------------------------------------------------- CheckGlobalKeys procedure PullStat --------------------------------------------------------------------------- Function Provides a case of global keystrokes to access any part of the program at any time. Declaration Called indirectly by PULL. Remarks Global keys can be any extended key. The contents are optional, but the procedure must exist. You must include PullStat in at least on USES statement in the program even though it can compile without it. See also GetUserPullStats, GetOverrideStats --------------------------------------------------------------------------- DisplayFields procedure Pull --------------------------------------------------------------------------- Function Displays the contents of a sequence of data entry fields given the first and last record numbers. Declaration DisplayFields (First,Last: word) Remarks Fields are displayed in window-relative coordinates. See also Enter, EnterSeq Chapter 2, Procedures and Functions Page 4 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 --------------------------------------------------------------------------- Enter procedure Pull --------------------------------------------------------------------------- Function Edits a field for a single data entry given the Data Entry record. Declaration Enter (RecNum: word); Remarks This procedure is used if you want to customize your own sequence of entry. RecNum is the record number of the data entry. This procedure only shows the string being edited for input. For output display, use DisplayFields. See also DisplayFields, EnterSeq --------------------------------------------------------------------------- EnterSeq procedure Pull --------------------------------------------------------------------------- Function Edits a sequence of fields for data entry given the Data Entry records. Declaration EnterSeq (First,Last: word; VAR Start: word); Remarks This procedure 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.PAS. First/Last are the first and last record numbers in the sequence. Start is where you want the HiLite to start, and keeps up with the current record. Use DisplayFields once before editing. See also DisplayFields, Enter --------------------------------------------------------------------------- GetOverrideStats procedure PullStat --------------------------------------------------------------------------- Function Overrides any default configurations set by GetUserPullStats and InitPull. Declaration Called indirectly by PULL. Remarks If you have any exceptions for your menu records, place your assignments in this procedure. The contents are optional, but the procedure must exist. You must include PullStat in at least one USES statement in the program even though it can compile without it. See also CheckGlobalKeys, GetUserPullStats --------------------------------------------------------------------------- GetUserPullStats procedure PullStat --------------------------------------------------------------------------- Function Initializes all menus, windows and message lines for the pull-down environment. Declaration Called indirectly by PULL. Remarks You must include the PullStat in at least one USES statement in the program even though it can compile without it. See also CheckGlobalKeys, GetOverrideStats --------------------------------------------------------------------------- GotoKeyDispatcher procedure Pull --------------------------------------------------------------------------- Function Turns control over to PULL. Declaration GotoKeyDispatcher Chapter 2, Procedures and Functions Page 5 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 Remarks This procedure is called by your main program after all the data record have been initialized. Example See PULLDEMO.PAS. --------------------------------------------------------------------------- HelpKeyPressed function Pull --------------------------------------------------------------------------- Function Trivial function returns true if the context-sensitive help key has been pressed. Declaration HelpKeyPressed Result type boolean Remarks PULL is currently assigned the F1 key for the help window. See also TopKeyPressed, PullHelpWndw --------------------------------------------------------------------------- HiLiteRow procedure Pull --------------------------------------------------------------------------- Function Highlights a line in a menu. Declaration HiLiteRow (Row: byte; Attr: integer) Remarks This procedure 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. --------------------------------------------------------------------------- InitPull procedure Pull --------------------------------------------------------------------------- Function Initializes WNDW and PULL records. Declaration InitPull (Attr: integer; ClearScr: boolean) Remarks Attr is the attribute of Window0 and is also assigned to the global variable InitAttr. If ClearScr is true, it will clear the screen which is not necessary for PermMode windows. This procedure is required and is only used once. --------------------------------------------------------------------------- InRangeW function Pull --------------------------------------------------------------------------- Function Returns true if a word test value is between the high and low limits inclusive. Declaration InRangeW (Low,Value,High: word) Result type boolean Remarks The function will swap Low and High before testing if they are not in the correct order. Restrictions Negative values cannot be used. --------------------------------------------------------------------------- Popped function Pull --------------------------------------------------------------------------- Function Used to detect if all menus have all been removed before executing menu procedures. Declaration Popped Result type boolean Remarks This function is used in procedures called by the menu ProcPtr. PULL executes the ProcPtr procedure twice when Popped is used. It sets several flags for you including Chapter 2, Procedures and Functions Page 6 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 PopAndProcess. The first time Popped is tested it returns false and sets the appropriate flags. When the menus are removed and ProcPtr is executed again, Popped will be true. This allows your statement to read like plain English. Example This far procedure is called by a ProcPtr in a menu: procedure MyProc; begin if Popped then DoMyProc; end; --------------------------------------------------------------------------- PullDirectory procedure PullDir --------------------------------------------------------------------------- Function Displays the contents of the current disk directory. Declaration PullDirectory (VAR NameToChange: FileNameStr; NameToHiLite: FileNameStr); Remarks Pressing RETURN on the HiLited item will be assigned to NameToChange. If NameToHiLite is given, 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. Example See PULLSTAT.PAS for PULLDEMO.PAS. --------------------------------------------------------------------------- PullHelpWndw procedure Pull --------------------------------------------------------------------------- Function Displays a context-sensitive help window. Declaration PullHelpWindow (WndwNum: byte); Remarks This procedure can be used in any procedure where keyboard input is tested. WndwNum is the HelpWndw record number, but using the ordinal value of HelpWndwNames is easier to use. See also HelpKeyPressed --------------------------------------------------------------------------- ReadKbd procedure Pull --------------------------------------------------------------------------- Function Reads keyboard input and permits background processing while keyboard is idle. Declaration ReadKbd (VAR ExtKey: boolean; VAR Key: char); Remarks ExtKey is true 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. Also, while the keyboard is idle, the KbdIdle procedure is being continually executed. See also CheckForPullDown, KbdIdle --------------------------------------------------------------------------- SetCmdSeq procedure Pull --------------------------------------------------------------------------- Function Sets PULL control flags to shortest path to the new menu. Declaration SetCmdSeq (NewCmdSeq: SeqStr) 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 Chapter 2, Procedures and Functions Page 7 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 by setting MoreCmdSeq and PopLevels. --------------------------------------------------------------------------- ShowErrMsg procedure Pull --------------------------------------------------------------------------- Function Shows an error message on the message line. Declaration ShowErrMsg (ErrMsgNum: word); Remarks ErrMsgNum is the index of the ErrMsgLine to display. It is easier to use the ordinal value of ErrMsgNames 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. See also ShowMsg Example Show the error message line named MyErrMsg: ShowErrMsg (ord(MyErrMsg)); --------------------------------------------------------------------------- ShowMsg procedure Pull --------------------------------------------------------------------------- Function Shows a message on the message line. Declaration ShowMsg (MsgNum: byte) Remarks MsgNum is the index of the MsgLine to display. It is easier to use the ordinal value of MsgLineNames to identify the message to display. See also CheckForPullDown, ShowErrMsg Example Show the message line named MyMsg: ShowMsg (ord(MyMsg)); --------------------------------------------------------------------------- ShowTopLine procedure Pull --------------------------------------------------------------------------- Function Simply displays the unhighlighted Top Line Menu. Declaration ShowTopLine Remarks This procedure is used to initially display the Top Line menu for the screen design in PULLWORK.PAS or PULLSHEL.PAS. It writes the string TopLineStr to the screen which is assembled by InitPull. --------------------------------------------------------------------------- StrSL function Pull --------------------------------------------------------------------------- Function Returns a string left justified in a field of spaces. Declaration StrSL (S: string; Field: byte) Result type string Remarks If Field is less than the length of the string, the string is simply returned. See also StrSR Chapter 2, Procedures and Functions Page 8 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 --------------------------------------------------------------------------- StrSR function Pull --------------------------------------------------------------------------- Function Returns a string right justified in a field of spaces. Declaration StrSR (S: string; Field: byte) Result type string Remarks If Field is less than the length of the string, the string is simply returned. See also StrSL --------------------------------------------------------------------------- TopKeyPressed function Pull --------------------------------------------------------------------------- Function Trivial function returns true if the top line menu key has been pressed. Declaration TopKeyPressed Result type boolean Remarks PULL is currently assigned the F10 key for the top line menu. See also HelpKeyPressed --------------------------------------------------------------------------- TurnArrows procedure Pull --------------------------------------------------------------------------- Function Displays or removes arrows on the highlighted line of a menu that pulls down a submenu or user window. Declaration TurnArrows (Switch: Toggle) Remarks This procedure is used primarily to interface with user windows that require the arrows to be turned on or off. Example See the User Window section in PULL55.DOC. --------------------------------------------------------------------------- WorkWndw procedure PullWork --------------------------------------------------------------------------- Function Provides a case of steps for the work window as the main part of the program. Declaration Called indirectly by PULL. Remarks The contents are optional, but the procedure must exist. You must include PullWork in the USES statement of the main program even though it can compile without it. Example See PULLSHEL.PAS and PULLDEMO.PAS. Chapter 2, Procedures and Functions Page 9 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 3. D A T A S T R U C T U R E This section will help describe the data structure of PULL and how it can be adjusted. The variables in P55-VAR.INC are allocated according to the conditional directives and constants set at the beginning of the file. 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 P55-VAR.INC for the exact listing. CONFIGURATION CONSTANTS These constants configure the size of the data structure. If you have the complete source code, the constants can be trimmed to fit the requirements of your application program. While developing the program, you can balloon these values so that PULL does not need to be recompiled every time the program expands. Constant Value Description ---------------- ----- ------------------------------------------------ NumOfMainMenus 1-255 Sets the maximum number of main menu records to be held in the heap. NumOfSubMenus 1-255 Sets the maximum number of submenu records to be held in the heap. MaxMenuLines 1-253 Sets the maximum number of menu lines in each menu record. MaxCharsPerLine 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. NumOfDataWndws 1-255 Sets the maximum number of data window records to be held in the heap. NumOfDataEntries 1-255 Sets the maximum number of data entry records to be held in the heap. DataStrSize 1-255 Sets the maximum number of characters that can be entered in a data entry of any kind. NumOfHelpWndws 1-255 Sets the maximum number of help window records to be held in global data. TotalHelpLines 1-255 Sets the maximum number of help lines in the HelpLine array. A greater number of lines can be used if TP5 enumerated types are not used for the index. HelpCharsPerLine 1-241 Sets the maximum number of characters per line in all help windows. Remember this excludes the two extra spaces between border and text. NumOfMsgLines 1-255 Sets the maximum number of message lines to be Chapter 3, Data Structure Page 10 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 allocated in the MsgLine array. CrtStrSize 1-255 Sets the maximum number of characters that can appear on a CRT. NumOfErrMsgLines 1-up Sets the maximum number of message lines to be allocated in the ErrMsgLine array. ErrStrSize 1-255 Sets the maximum number of characters in a single ErrStrLine message. This is usually less than CrtStrSize, but cannot be greater. MAIN MENU DECLARATIONS The following types, variables and constants are used for primarily for the main menus. The variables are described in the order of their appearance in the file P55-VAR.INC. Types - These types are used to structure variables for the main menus: Type Description ------------ ----------------------------------------------------------- MenuModeType This enumerated type gives a name for three different menu modes. Each mode controls how each line will interact with the other lines. Name Description -------------- -------------------------------------- ExecChoice Executes the procedures indicated by ProcPtr and does not interact with the other menu lines. This is the default. SingleChoice Flags only the selected line in the menu and turns off all other flags. If ProcPtr is not nil, it will also execute the procedure before flagging. MultipleChoice Toggles the flag on any line in the menu. If ProcPtr is not nil, it will also execute the procedure before flagging. LineModeType This enumerated type gives a name for seven different line modes for any one line in the menu. Name Description ---------- ------------------------------------------ Choice Interacts with the rest of the menu according to the given menu mode. ExecOnly Only executes ProcPtr and ignores flagging. NoChoice 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. Chapter 3, Data Structure Page 11 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 ToDataWndw Places a dot symbol on the line and pulls down a data entry window. ToSubMenu Places a three-bar symbol on the line and pulls down a submenu. ToUserWndw Places a three-bar symbol on the line and executes ProcPtr. ProcPtrType This is the type established for procedure pointers and is a generic pointer type. Toggle This enumerated type is just a practical way of understanding the source code to indicate the common binary conditions of On/Off and Yes/No. CrtStrType Combined with CrtStrSize, this type will limit the size of strings needed to display data onto the screen. It is usually used for message lines. SeqStrType This type 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, Wndw.MaxWndw is used. MenuRec This record is used to fully describe any menu. Each field 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 boolean flag corresponding to each line. The default is false. LinkNum - This array has the byte value of submenu or data window names of records to be linked. The default is 0. ProcPtr - This array has the pointers for executing far procedures when the menu line is selected. The default is nil 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 NoDir. Chapter 3, Data Structure Page 12 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 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 SingleChoice menu mode. The following variables control the attributes in the menus. SameAttr is not permitted. 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 true, the HiLite will return to the DefaultLine every time the menu is pulled down. The default is false. Changed - PULL will toggle this to true if any of the flags have been altered. It is up to the programmer to reset it to false if it is needed. 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 record to be displayed for this menu when context- sensitive help is requested. MenuRecs This array allocates the total number of main menu records needed for the heap. They do not all have to be used. Variables - The following are the global variables used to create and Chapter 3, Data Structure Page 13 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 control the pull-down menus: Variable Description ------------ ----------------------------------------------------------- MainMenu (Type: ^MenuRecs) This is the pointer of the array of main menu records in the heap. TopMenu (Type: MenuRec) As each menu record is accessed, main menu or submenu, a copy of the record is made in TopMenu to increase speed and save code. The record is saved back in the heap after use. MRI (Type: word) When a menu is copied into TopMenu, the array index of the record is saved in this variable for later reference. LastMainMenu (Type: byte) This is the index of the last main menu displayed on the far right of the Top Line menu. It is <=NumOfMainMenus. TopLineStr (Type: CrtStrType) This is the actual string that appears as the Top Line menu when ShowTopLine is used. TopLineRow (Type: byte) This is the row on which TopLineStr appears. MainMenuRow (Type: byte) 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. SameAttr is not permitted in byte types. Name Type Description ------------- -------- ------------------------------------- InitAttr integer base screen, set by Attr in InitPull. TopLineAttr byte top line menu. TopLineHattr byte HiLite on top line menu. TopLineLattr byte command Letters on top line menu. MainMenuWattr byte entire Window contents. MainMenuBattr byte main menu Border. MainMenuHattr byte HiLite in main menu. MainMenuLattr byte command Letters in main menu. MainMenuCattr byte Comment line. MainMenuBrdr Borders main menu Border style. Keyboard - The following variables and constant contain the last keyboard input from ReadKbd or CheckForPullDown. Variable Description ------------ ----------------------------------------------------------- Key (Type: char) Contains the key code of the input. ExtKey (Type: boolean) Set true if extended key. Chapter 3, Data Structure Page 14 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 WaitForKbd (Type: boolean = true) This typed constant causes a wait for keyboard input when executing CheckForPullDown. If it is false, then the current values of Key and ExtKey are considered valid and execution continues. Control Flags - The following variables programmably control the pull-down menus in lieu of the end user. Variable Description ------------ ----------------------------------------------------------- PullDown (Type: boolean) When set true, the menus will be pulled down from their current position according to the sequence in MoreCmdSeq. Pop (Type: boolean) This flag is controlled by CheckForPop and sets it true if the program needs to pop out of the current menu. PopToWorkWndw (Type: boolean) If true, the menus will all pop and return control to the work window. PopToTop (Type: boolean) If true, control is set to highlight the Top Line menu. PopAndProcess (Type: boolean) This flag is controlled by the Popped function to execute a ProcPtr in the menus after all the menus have been popped. PopLevels (Type: byte) This flag is controlled by SetCmdSeq or can be used manually. It simply pops the number of levels of menus/windows. Quit (Type: boolean = false) This typed constant 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[NumOfMainMenus]) This is the counterpart of Menu.CmdLtrs for the Top Line menu. It holds the command letters for the Top Line menu where character 1 corresponds to the first main menu, character 2 to the second, etc. CmdSeq (Type: SeqStrType) 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. Chapter 3, Data Structure Page 15 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 MoreCmdSeq (Type: SeqStrType) When performing a programmed pull down, this is the sequence of letters yet to be executed in the same order as CmdSeq. MPulled (Type: byte) This is the index of the current main menu pulled. SPulled (Type: byte) This is the index of the current submenu pulled. If no submenu is pulled, this value is 0. HiLited (Type: byte) This is the row number of the currently highlighted line. AccessedWorkWndw (Type: boolean) This is a handy flag available for testing in your program. If you are in the menus and you run your custom routine with ProcPtr to set this false, the next time the work window is accessed, this variable will be true. AccessedMenus (Type: boolean) This is a handy flag available for testing in your program. If you are in the work window and set this false, the next time the menus are accessed, this variable will be true. WorkWndwStep (Type: byte) This is the current step number assigned to the work windows in PULLWORK.PAS. TopWorkWndwName (Type: WindowNames) This is the name of the work window to be selected for access or the current one on top. InWorkWndw (Type: boolean = true) When true, this typed constant indicates if the program is in the work window. It is otherwise in the menus. Addresses for Calls - The following pointers are used indirectly by indirect calls in PULL.TPU so that TP5 units can make calls forward outside of a unit and also be compatible with TP4. These are far addresses and are accessed as pointers with inline calls. Address variable Unit.Procedure -------------------- ------------------------- AddrGetUserPullStats PullStat.GetUserPullStats AddrGetOverrideStats PullStat.GetOverrideStats AddrWorkWndw PullWork.WorkWndw AddrCheckGlobalKeys PullStat.CheckGlobalKeys AddrKbdIdle PullWork.KbdIdle Untyped Key Constants - Several key constants have already been provided for frequently used keys. Please refer to P55-VAR.INC for the listing. Chapter 3, Data Structure Page 16 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 SUBMENU DECLARATIONS The following type and variables are used for the sub menus. The variables are described in the order of their appearance in the file P55-VAR.INC. The program was carefully planned so that main menu records would match that of the submenus. Type - This type is used to structure variables in the heap for the submenus: Type Description ------------ ----------------------------------------------------------- SubMenus This array allocates the total number of submenu records needed for the heap. They do not all have to be used. The Row/Col fields in the menu record for submenus default to zero so that PULL 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 global variables used to allocate and configure the submenus: Variable Description ------------ ----------------------------------------------------------- SubMenu (Type: ^MenuRecs) This is the pointer of the array of submenu menu records in the heap. LastSubMenu (Type: byte) This is the index of the highest submenu record number in use. It is <=NumOfSubMenus. Attributes - The following variables control the default attributes and border in all the submenus. SameAttr is not permitted in byte types. Name Type Description ------------ -------- ------------------------------------- SubMenuWattr byte entire Window contents. SubMenuBattr byte submenu Border. SubMenuHattr byte HiLite in submenu. SubMenuLattr byte command Letters in submenu. SubMenuCattr byte Comment line. SubMenuBrdr Borders submenu Border style. MESSAGE LINE DECLARATIONS The following type, constant and variables are used to generate normal key messages or error messages on the message line. Type - The following type is the only one needed for error messages: Chapter 3, Data Structure Page 17 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 Type Description ------------- ----------------------------------------------------------- ErrMsgStrType This is the type used to size the length for all error messages based on ErrMsgSize. Since they are usually short, they can be trimmed to the length of the longest one. Constants - The following constants are given initial values to process the messages on the message line. Constant Description ----------------- ------------------------------------------------------ CurrentMsgLineNum (Type: word = 0) This is the index of the current MsgLine displayed on the screen. EnableKeyStatus (Type: boolean = true) When true, the status of NumLock, ScollLock, and CapsLock will appear on the message line. Variables - The following variables allocate space for the messages in global data and control the location of the messages and the key status indicators: Variable Description ------------ ----------------------------------------------------------- MsgLine (Type: array of CrtStrType) This array allocates global 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 ErrMsgStrType) 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: byte) This is the absolute row on which all messages and error messages are to appear. CapsLockCol (Type: byte) 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. SameAttr is not permitted in byte types. Name Type Description ------------ ---- ------------------------------ ErrMsgAttr byte For error messages. KeyStatusAttr byte For the key status indicators. MsgLineAttr byte For the normal messages. HELP WINDOW DECLARATIONS The following types and variables are used to create context-sensitive help windows. Chapter 3, Data Structure Page 18 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 Type - The following record is the only one needed for help windows: Type Description ------------ ----------------------------------------------------------- HelpWndwRec This record 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 HelpCharsPerLine are used 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 records and help lines in global data and control the location and appearance of the window: Variable Description -------------- --------------------------------------------------------- HelpWndw (Type: array of HelpWndwRec) This array allocates global data space for the help windows. If you intend to have several help window, you should consider making this data disk based. HelpLine (Type: array of ErrMsgStrType) This array allocates global data space for all the help lines. If you intend to have several lines, you should consider making this data disk based. HelpBottomRow (Type: byte) This is the default row on which the bottom row of the help window is to appear. This keeps help windows down lower. Chapter 3, Data Structure Page 19 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 HelpWndwModes (Type: byte) This is the default used to set HelpWndw.HWmodes. See WNDW.DOC for setting this variable. HelpMsgLineNum (Type: byte) This is the index of MsgLine for the message to appear concurrently with the help window. The index HelpML 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. SameAttr is not permitted in byte types. Name Type Description ------------- -------- ------------------------------------- HelpWndwWattr byte entire Window contents. HelpWndwBattr byte help window Border. HelpWndwBrdr Borders help window Border style. DATA WINDOW / ENTRY DECLARATIONS The following types, constants and variables are used to create data entry windows and work window data entry fields. Types - The following types are used to structure the data window/entry records: Type Description -------------- --------------------------------------------------------- TypeOfDataType This enumerated type is used to indicate the type of data being processed. Although the identifier list is intuitive, here is the list indicating its corresponding type: Name Type --------- --------- Bytes byte Words word ShortInts shortint Integers integer LongInts longint Reals real UserNums DataStrType Chars char Strings DataStrType SetNames This enumerated type identifies character sets to be used for filtering each keystroke. The names up to CharSet are reserved, but the list can be appended. EntrySetArray This is the structure for allocating the data entry filter sets for the constant EntrySet. Chapter 3, Data Structure Page 20 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 DataEntryRec This record is used to fully describe any data entry. Each field is described below: VarAddr - This is the absolute address where the contents of the entry is 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, if these values default to (1,2) for the field location. For data entry, this is 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 which creates a flex-field entry. For strings, be sure that MaxField is no longer than the string destination or DataStrSize. Decimals - For reals, this value is used to format the output output display which is Real:Field:Decimals. If Decimals is negative then the format is Real:Field. 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. TranslateProc - This procedure pointer is used to execute a procedure to intercept the keystroke for translation. The default is nil. CheckRangeProc - This procedure pointer is used to execute a procedure for checking the range or content of the entry before it is stored in the assigned variable. The default is nil. JustifyOutput - 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. SameAttr is not permitted. 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 Chapter 3, Data Structure Page 21 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 record to be displayed when context-sensitive help is requested. DataWndwRec This record is used to fully describe any data window. Each field 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, PULL will locate the window at run time for the slide- under configuration. Non-zero values will override PULL 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: DataEntryRec) This is a record within the DataWndwRec that fully describes the field inside the window. DataWndws This sets the structure for all of the data window records to be allocated in the heap. DataEntries This sets the structure for all of the data entry records in a work/user window to be allocated in the heap. DataStrType Combined with DataStrSize, this type will limit the size of strings that can be entered/read from any data entry. DataPadRec This record conveniently groups all of the data needed for the Data Pad. Each one of the fields is described below. StoreMode - If true, 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 true if it passes. DataStored - If the data passes the validity check, the range check, and is stored, this variable is set true which is later used to set TopMenu.Changed to true. NewData - This flag is used internally to indicate an untampered entry has been displayed for editing. Once edited, this value is false. 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 Chapter 3, Data Structure Page 22 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 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 does not equal Field, this value is set to 1 to indicate a flex field. 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. TypeOfDataType - 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 variant field identifiers: Identifier Type ---------- --------- Bdata Bytes Wdata Words SIdata ShortInts Idata Integers Ldata LongInts Rdata Reals UNdata UserNums Cdata Chars Sdata Strings Typed Constant - EntrySet is the array of the actual sets used for filtering the keystrokes before being entered into the field. Along with each index name is the application of the set. The sets up to CharSet are reserved. Other sets can be appended. Index name Application ----------- ----------------------------------------- UnsignedSet For Bytes and Words SignedSet For ShortInts, Integers, and LongInts RealSet For Reals CharSet For Chars, Strings and misc. entry HexSet For UserNums and Hex FileNameSet For DOS file names PathSet For DOS full path file names MaskSet For DOS full path file names with wildcard Chapter 3, Data Structure Page 23 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 Variables - The following variables allocate space for data windows, data entries, and the data pad: Variable Description ------------ --------------------------------------------------------- DWI (Type: word) Data Window Index used to save the current data window record number currently in TopDataWndw. DEI (Type: word) Data Entry Index used to save the current data entry record number currently in TopEntry. TopDataWndw (Type: DataWndwRec) This is a copy of the record from the heap of the current DataWndwRec. This saves code. TopEntry (Type: DataEntryRec) This is a copy of the record from the heap of the current DataEntryRec. This saves code. DataWndw (Type: ^DataWndws) This pointer accesses the array of data window records in the heap. DataEntry (Type: ^DataEntry) This pointer accesses the array of data entry records in the heap. DataStr (Type: DataStrType) This is the actual string edited on the screen during an entry into a field. The length of the string is limited by DataStrSize. DataStrL (Type: byte) This is the current string length of DataStr by accessing DataStr[0]. DataPad (Type: DataPadRec) This is the data pad used to transfer data between the destination variable and the screen. AutoTab (Type: boolean) When set true for EnterSeq, the HiLite will advance to the next field automatically after entry. AutoNumLock (Type: boolean) For numerical entries, this flag will automatically turn on NumLock and is shown on the message line with the key status indicator. Chapter 3, Data Structure Page 24 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 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 global 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 GLOBAL VS. DYNAMIC As is, PULL uses both global and dynamic memory for records and messages. The menus and data window/entry records are dynamic while the help window and messages use global memory. Depending on the needs of your application program, you can change where these records are located by removing or adding the ^ symbol, if you have the source code, along with the usual HeapOK/GetMem instructions. PULLDEMO - In the demonstration, it was chosen to use the messages and help windows as global memory since the program was so small. In larger programs that need more global data, these records can be shifted to dynamic memory or even to disk. 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 PULL.TPU using the current configuration constants: 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 global in demo Messages 16 1326 Used global 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 message are higher because the text strings were placed in global memory. DYNAMIC MEMORY Dynamic Variables - To alleviate using global data, dynamic variables are used for permanent and temporary use. The allocation for menus and data window/entry records are permanent throughout the program. Many other procedures such as pulling down menus temporarily use the heap to perform operations. Permanent Variables - If the directives have been defined, the following allocation can be calculated: Appendix A: Memory Allocation Page 25 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 Records Calculation Demo Bytes ------------ ---------------------------------------------- ---------- Menus SizeOf(TopMenu)*(NumOfMainMenus+NumOfSubMenus) 7664 Data windows SizeOf(TopDataWndw)*(NumOfDataWndws) 658 Data entries SizeOf(TopEntry)*(NumOfDataEntries) 240 Again, this is just a general idea of what your program would allocate. This is totally dependent on the configuration constants you choose. 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 - PULL is also very frugal with with code. Here is the breakdown for code usage (this may vary slightly): Code Description Bytes ------------------------------- ----- Basic pull-down menus 4320 Additional for submenus 1056 Additional for data wndw/entry 3952 Additional for help windows 704 Additional for messages 880 ----- Total code 10912 Of course the TP5 smart compiler will optimize the code leaving out unused procedures. But this gives you a good idea of how small the code really is! Appendix A: Memory Allocation Page 26 PULL Multi-level Pull-Down Menus Reference Guide, Version 5.5 A P P E N D I X B : E R R O R M E S S A G E S PULL uses the same GOOF unit as WNDW does. Should you make a mistake in programming with windows or PULL, the program will terminate with an error message window on the CRT to reveal any problem. The program terminates through the GOOF unit which can be freely edited. WNDW 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 WNDW55.DOC. "Too many windows" - Tried to create more windows than MaxWndw allows. Either remove windows or increase MaxWndw. "Too many virtual windows" - Tried to create more virtual windows than MaxVirtualWndw allows. Either remove windows or increase MaxVirtualWndw. "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. PULL Only the following error message will occur in PULL: "A Submenu could not fit" - Tried to fit a menu that was too wide to fit in the slide-up configuration. Set LocationWarning false 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