home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 19
/
CD_ASCQ_19_010295.iso
/
vrac
/
boss.zip
/
BOSS_DOC.EXE
/
WN_PDOWN.DOC
< prev
Wrap
Text File
|
1992-03-08
|
18KB
|
468 lines
PDMENU AND PDITEM DATA STRUCTURES:
The heart of the pulldown menu system is the menu structure pdmenu. Each
menu has its own pdmenu structure which describes the menu.
The structure is defined in WINBOSS.H.
struct pditem { /* PULLDOWN menu item template */
int r; /* row in menu window for item */
int c; /* col in menu window for item*/
char *t; /* menu item text */
char hkc; /* the menu HotKey*/
int status; /* item status - active/in-active */
char type; /* item type, action, toggle,etc. */
int rv; /* item return value */
};
struct pdmenu { /* PULLDOWN menu structure */
WINDOWPTR wpsave; /* menu's window pointer */
int wa; /* window attribute */
int ba; /* border attribute */
int hka; /* hot key attribute */
int winopn; /* window is open flag */
int lndx; /* last index selected */
int fm; /* first menu item index */
int lm; /* last menu item index */
struct pditem item[WN_MXROWS*4]; /* a bunch of menu items */
} WNPD, *WNPDPTR; /* NOTE RELATIVE LIMIT */
The structure pditem is modelled on the structure pitem but has several
new fields.
The MENU HOTKEY is any letter in the menu text. The key is highlighted in
a menu display and pressing this key will immediately select the menu
item. The hotkey must have the same case (upper/lower) as its
corresponding letter in the menu text.
The STATUS field defines whether a menu item is active (1) or inactive (0).
Active items have their hotkeys highlighted and can be
selected by the user. Inactive menu items do not have their hotkey
highlighted and cannot be selected by the user.
The TYPE field holds a interger which defines the item's type.
Currently, there are 5 types available.
PDACTION - the item is an Action item. That is, selecting it will
invoke some action. Load, Save, Print are examples of Action items.
PDSELECT - an Action item that has been Selected. A program can use the
routine wn_pdtype to switch an PDACTION item to a PDSELECT item to signal
other parts of the program that the item has been selected.
For example, before a program prints, it can check the Load option to
see if the user has loaded any data.
PDBAR - this type is only used in a bar menu. It means that the item does
not have an associated pulldown menu.
PDTOGG - the item is a toggle. That is, selecting it simply toggles the
item ON and OFF.
PDETOGG - the item is an EXCLUSIVE toggle. Only one exclusive type toggle
in a menu can be ON. Turning one ON turns another OFF.
The RV field is the items return value.
PULLDOWN MENU ROUTINES:
The wn_pd pulldown system uses 10 routines which are briefly described
here.
wn_pdopen - opens a menu window if it is not yet open. Displays all the
menu items. The menu can be displayed as inactive or active. An active
menu has its item hotkeys highlighted. The only menu that would normally
be displayed as inactive would be the main bar menu.
wn_pdclose - closes a menu window.
wn_pdupdate - displays a specified item in normal or reverse video.
Primarily used by wn_pdget to indicate the current menu item being
pointed to.
wn_pdgettog - this routine has two uses. If it is supplied with a menu
item's return value (rv), it returns TRUE if the toggle is ON or FALSE if the
toggle is OFF. If it is supplied with a value of -1 instead of a return
value, it returns PDTOGOK if all menu toggles are OFF or the return value of
a toggle that is ON. The -1 option is primarily used to determine which, if
any, of a set of EXCLUSIVE toggles (mutually exclusive toggles) is ON.
wn_pdsettog - primarily used by wn_pdget to reverse the state of a toggle
when the user selects a toggle menu item. If the toggle is an exclusive type
and it has been turned ON, the routine turns OFF all other toggles in the
menu and returns the menu item INDEX of a toggle that was previously ON.
If none were ON, it returns PDTOGOK.
wn_pdactive - this routine takes a menu option's return value and
activates or de-activates the menu option based on the value of a second
argument. A program can use this routine to control which options a user
has available at any particular point in the program. This is one of
the systems most powerful features.
wn_pdtype - this routine serves two purposes. It can change the type code
of a menu item or return its current type code. This routine should only
be used to change type Action or type Selected or the reverse.
It's primary use is to let the type code serve as a flag that can be
tested to see if an item has been selected or not. As an example, the
code that exits a program can check the Load and Save menu items, if Load
has been selected, but Save has not, then it should ask the user if he
wants to save his data before exiting the program. NOTE: the system does not
automatically switch an Active type to a Selected type when an item is
selected. It is the program's duty to do this.
wn_pdget - this is the real work horse. It gets the user's menu choice
and returns the item's return code. A menu must be opened using wn_pdopen
BEFORE calling this routine. wn_pdget first displays the current choice
in reverse video. If all items in a menu are inactive, none are
highlighted. It then waits for the user to make a selection using the
arrow keys and ENTER or by pressing an item's hotkey. If the selected
item is not a toggle, the item's return code is returned. If it is a
toggle, its state is reversed, but the routine does not exit. If the user
presses ESC, the routine closes the menu window and returns 99.
Wn_pdget handles pulldown menus in a special way. When in a pulldown,
pressing the left arrow key returns 97 and pressing the right arrow key
returns 98. In both cases, the window is closed. The application program
can use these codes to take special action. The program PDDEMO
demonstrates one way of handling these codes by immediately activating
the adjacent main bar menu item and displaying its pulldown. In this way,
once a user has pulled down one menu, he can look at all the other
pulldown menus simply by pressing the left and right arrow keys.
wn_border - this is a handy little routine to select a single or double
ruled border for all subsequent windows.
wn_drawborder - this routine immediately redraws the border of a
specified window as single or double ruled.
THE PDDEMO PROGRAM:
As well as giving a good demonstration of the power of the system, this
program contains the basic code to implement almost all common menu
activities and one or two less common ones. As such, it can serve as the
basis for implementing your own menu system, probably with only minor
changes and the addition of routines that implement the actions of the
various menu items.
The look and contents are based on the menus found in many Microsoft
applications such as QuickBasic, QuickC, Windows and Excel.
The one thing where PDDEMO differs markedly from MS is in the key that
activates the main bar menu. I've used the slash key (like Lotus 123)
rather than the ALT key.
PDDEMO contains examples of toggle items (Setup/Color), exclusive toggles
(Setup/Printers), activating and de-activating menu options and even a
neat example of how turning ON a toggle in one menu, de-activates the
same option in another menu. Try selecting the same item for both the X
and Y axis using the View/Graphics option. Two level and three level
nested menus are also demonstrated. Most of the pulldown menus are
'single shot' menus. That is, you make a selection and then you are
returned to the main program. A couple are 'sticky' menus that allow you
to make several selections from the same pulldown menu. You close these
menus by pressing ESC.
THE WN_PD ROUTINES IN DETAIL:
1. wn_pdopen - opens and displays a menu.
USAGE
int wn_pdopen(page, row, col, width, height, wa, ba, hka, mx, Active)
int page, row, col; /* Refer to WINDOW BOSS DOCS (wn_open) */
int width, height,wa, ba; /* Refer to WINDOW BOSS DOCS (wn_open) */
int hka; /* hot key attribute */
struct pdmenu *mx; /* pointer to popup menu struct */
int Active; /* active or inactive menu */
This must be the first routine you call. Call it to open a new menu
window and display it, or call it to redisplay an existing menu. If
Action is FALSE, the menu item's hotkeys are not highlighted which
indicates to the user that the menu is not active. If Action is TRUE, the
hotkeys are highlighted using the hotkey attribute specified in the
menu's pdmenu structure.
RETURNS
Returns TRUE if successful or FALSE if it failed.
CAUTIONS AND ADDITIONAL NOTES:
None.
2. wn_pdclose - closes an open menu window.
USAGE
void wn_pdclose(mx)
struct pdmenu *mx; /* pointer to menu structure */
RETURNS
Nothing.
3. wn_pdupdate - displays a menu item in normal or reverse video.
USAGE
int wn_pdupdate(mx, item, style)
struct pdmenu *mx; /* pointer to menu structure. */
int item; /* index of menu item to update. */
int style; /* either PDNORMAL or PDREVERSE. */
Almost exclusively used by wn_pdget. However, PDDEMO does illustrate one
situation where an application program might call this routine. If style
is PDNORMAL, the item is displayed using the window and hotkey attributes
defined in the menu's pdmenu structure. If style is PDREVERSE, the item is
displayed using the reverse of the window attribute. The hotkey is
displayed using the hotkey attribute foreground and the reverse of the
window attribute's background. Item is the INDEX of the menu item, NOT
its return code.
RETURNS
Returns FALSE if the menu isn't open, otherwise it returns TRUE.
CAUTIONS and ADDITIONAL NOTES
Some care should be taken in selecting the window and hotkey attributes
so that the hotkey is highlighted in both normal and reverse video. Look
at the attributes used in PDDEMO.
4. wn_pdsettog - reverses the state of a toggle menu option and makes
sure that only one Exclusive toggle is ON at a time.
USAGE
int wn_pdsettog(mx, i)
struct pdmenu *mx; /* pointer to menu struct. */
int i; /* index of the menu item to toggle */
Mostly used by wn_pdget, but PDDEMO illustrates its use by an application
program. By definition, a menu item is an ON toggle if it has a type of
either PDTOGG or PDETOGG and the first character of the menu text
is √ (ALT-251). It is OFF if the first character is a blank. If
item has a type of PDETOGG (exclusive toggle) and has been toggled ON,
the routine checks the other toggles and if it finds one
that is ON, it turns it OFF.
RETURNS
Returns PDTOGOK in all cases but one. If it turns an exclusive type toggle ON
and finds another one that was ON, it returns the index of this item.
CAUTIONS and ADDITIONAL NOTES
When designing a menu, ALWAYS use a leading blank space in the menu text
to allow room for the √ toggle character. Don't mix PDTOGG type and
PDETOGG type toggles in the same menu as this will confuse the user
and wn_pdsettog will behave unpredictably.
5. wn_pdgettog - get the current toggle status of a specific item or the
return code of any PDETOGG type toggle that is ON.
USAGE
int wn_pdgettog(mx, i)
struct pdmenu *mx; /* pointer to menu structure. */
int i; /* menu RETURN VALUE or -1 */
Note that this routine uses menu item return codes, not menu item
indexes. If the argument 'i' contains a toggle menu item's return code,
the routine returns TRUE if the toggle is ON or FALSE if it is OFF. If 'i'
contains -1, the routine returns the return code of a type PDETOGG toggle
that is ON. If no toggles are ON, it returns PDTOGOK.
RETURNS
See above.
CAUTIONS and ADDITIONAL NOTES
PDDEMO illustrates an interesting application of wn_pdgettog and
wn_pdsettog to de-activate a menu item in one menu if the identical item
has been toggled ON in another menu. (see the routine dographics).
6. wn_pdactive - activates and de-activates a menu item.
USAGE
void wn_pdactive(mx, i, Action)
struct pdmenu *mx; /* pointer to menu structure. */
int i; /* menu item return code. */
int Action; /* TRUE=activate, FALSE=de-activate */
Use this routine to control which menu items a user can select at any
phase in your program. For example, you would want to de-activate the
Plot option until a user had used the Load option to load some data for
plotting.
RETURNS
None.
CAUTIONS and ADDITIONAL NOTES
NEVER de-activate a bar menu item that has a pulldown menu. The system can't
handle this situation. Instead, de-activate all the pulldown menu's
items. This is better anyway because it allows the user to look at the
menu even if he can't select any of its items at some phase in your
program.
This is one of the system's most powerful features. It allows the user to see
all available menu options while protecting him from selecting options
which might cause problems. Also, if used properly, it can help 'walk' a
new user through the program by activating options in a logical sequence ...
Load activates Run, Run activates Plot, Plot activates Plot Options and
so on.
7. wn_pdtype - sets a new item type or returns its current type.
USAGE
int wn_pdtype(mx, i, NewType, Action)
struct pdmenu *mx; /* pointer to menu structure. */
int i; /* menu item return code. */
int NewType; /* ignored if Action is FALSE */
int Action; /* TRUE or FALSE */
Use this routine to change an item with a type of PDACTIVE to a type
of PDSELECTED when a user has selected the item and its actions were
properly performed. Your program can then test the item type to see if
it has been selected. If Action is TRUE, the item is given the new type
specified in NewType. If Action is FALSE, the current type is returned.
In this case, the contents of NewType are ignored.
RETURN
See above.
CAUTIONS and ADDITIONAL NOTES
This routine should ONLY be used with PDACTIVE and PDSELECTED type menu items.
The primary use is to detect if data has been loaded, but not saved. See
PDDEMO for examples.
8. wn_pdget - lets a user select a menu item and returns the return code
of the item selected.
USAGE
int wn_pdget(mx)
struct pdmenu *mx; /* pointer to popup menu struct */
You must call wn_pdopen BEFORE calling this routine.
Once this routine is activated, the user can select an item from the menu
by using the left and right arrow keys (bar menus) or up and down arrow
keys (pulldown menus) to highlight an item and then press ENTER.
Alternatively, the user can simply press the item's hotkey to immediately
select an item. Items that are inactive cannot be selected.
If the item is an action item, the routine returns the
item's return code. If the item is a toggle, the routine
simply reverses the toggle status, it does not return. If the toggle is
exclusive, (only one ON at a time), it turns OFF any other toggle in the
menu that was ON.
If the user presses ESC, the routine closes the menu window and returns
99. For pulldown menus, pressing the left arrow key returns 97 and
pressing the right arrow key returns 98. In both cases, the menu window
is closed.
This routine does not close a menu if the user selects an Action item.
The application program must close the window using wn_pdclose.
RETURNS
If Action type item selected, it returns the item's return code.
ESC returns 99. In pulldown menus, left arrow returns 97, right arrow
returns 98.
CAUTIONS and ADDITIONAL NOTES
It's easy to operate the system. First call wn_pdopen to open an menu. Then
call wn_pdget to get a menu selection. Then call wn_pdclose to close the
menu. PDDEMO is the place to look for all the code you need.
9. wn_border - sets the border style for future windows.
USAGE
void wn_border(Style)
int Style;
This little routine can be used anywhere in a Windows BOSS program. All
it does is make a call to wn_boxset and supply it with the ASCII codes to
use for either a single ruled border (Style = 1) or double ruled border
(Style = 2). Saves having to look them up all the time.
RETURNS
None.
10. wn_drawborder - redraws an open window's border as either single or
double ruled.
USAGE
int wn_drawborder(w, Style)
struct wcb *w; /* pointer to window to re-draw */
int Style; /* 1 = single 2 = double ruled */
This little routine can be used anywhere in a Windows BOSS program. All
it does is make a call to wn_dborder and supply it with the ASCII codes
to use for either a single ruled border (Style = 1) or double ruled
border (Style = 2). Saves having to look them up all the time.
RETURNS
Returns 1 if successful or 0 if unsuccessful.
CAUTIONS and ADDITIONAL NOTES
The window becomes the active window after this call.