home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Simtel MSDOS 1992 June
/
SIMTEL_0692.cdr
/
msdos
/
turbopas
/
pull55.arc
/
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
