home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / BOSS_DOC.ZIP / WN_PDOWN.DOC < prev   
Text File  |  1992-03-08  |  18KB  |  468 lines
  1. PDMENU AND PDITEM DATA STRUCTURES:
  2.  
  3.  
  4. The heart of the pulldown menu system is the menu structure pdmenu. Each
  5. menu has its own pdmenu structure which describes the menu.
  6. The structure is defined in WINBOSS.H.
  7.  
  8.   struct pditem {                    /* PULLDOWN menu item template */
  9.     int r;                           /* row in menu window for item */
  10.     int c;                           /* col in menu window for item*/
  11.     char *t;                         /* menu item text */
  12.     char hkc;                        /* the menu HotKey*/
  13.     int status;                      /* item status - active/in-active */
  14.     char type;                       /* item type, action, toggle,etc. */
  15.     int rv;                          /* item return value */
  16.   };
  17.  
  18.   struct pdmenu {                    /* PULLDOWN menu structure */
  19.     WINDOWPTR wpsave;                /* menu's window pointer */
  20.     int wa;                          /* window attribute */
  21.     int ba;                          /* border attribute */
  22.     int hka;                         /* hot key attribute */
  23.     int winopn;                      /* window is open flag */
  24.     int lndx;                        /* last index selected */
  25.     int fm;                          /* first menu item index */
  26.     int lm;                          /* last menu item index */
  27.     struct pditem item[WN_MXROWS*4]; /* a bunch of menu items */
  28.   } WNPD, *WNPDPTR;                  /* NOTE RELATIVE LIMIT */
  29.  
  30. The structure pditem is modelled on the structure pitem but has several
  31. new fields.
  32.  
  33. The MENU HOTKEY is any letter in the menu text. The key is highlighted in
  34. a menu display and pressing this key will immediately select the menu
  35. item. The hotkey must have the same case (upper/lower) as its
  36. corresponding letter in the menu text.
  37.  
  38. The STATUS field defines whether a menu item is active (1) or inactive (0).
  39. Active items have their hotkeys highlighted and can be
  40. selected by the user. Inactive menu items do not have their hotkey
  41. highlighted and cannot be selected by the user.
  42.  
  43. The TYPE field holds a interger which defines the item's type.
  44. Currently, there are 5 types available.
  45.  
  46.    PDACTION - the item is an Action item. That is, selecting it will
  47. invoke some action. Load, Save, Print are examples of Action items.
  48.  
  49.    PDSELECT - an Action item that has been Selected. A program can use the
  50. routine wn_pdtype to switch an PDACTION item to a PDSELECT item to signal
  51. other parts of the program that the item has been selected. 
  52. For example, before a program prints, it can check the Load option to
  53. see if the user has loaded any data.
  54.  
  55.    PDBAR - this type is only used in a bar menu. It means that the item does
  56. not have an associated pulldown menu.
  57.  
  58.    PDTOGG - the item is a toggle. That is, selecting it simply toggles the
  59. item ON and OFF.
  60.  
  61.    PDETOGG - the item is an EXCLUSIVE toggle. Only one exclusive type toggle
  62. in a menu can be ON. Turning one ON turns another OFF.
  63.  
  64. The RV field is the items return value.
  65.  
  66. PULLDOWN MENU ROUTINES:
  67.  
  68. The wn_pd pulldown system uses 10 routines which are briefly described
  69. here.
  70.  
  71. wn_pdopen - opens a menu window if it is not yet open. Displays all the
  72. menu items. The menu can be displayed as inactive or active. An active
  73. menu has its item hotkeys highlighted. The only menu that would normally
  74. be displayed as inactive would be the main bar menu.
  75.  
  76. wn_pdclose - closes a menu window.
  77.  
  78. wn_pdupdate - displays a specified item in normal or reverse video.
  79. Primarily used by wn_pdget to indicate the current menu item being
  80. pointed to.
  81.  
  82. wn_pdgettog - this routine has two uses. If it is supplied with a menu
  83. item's return value (rv), it returns TRUE if the toggle is ON or FALSE if the
  84. toggle is OFF. If it is supplied with a value of -1 instead of a return
  85. value, it returns PDTOGOK if all menu toggles are OFF or the return value of
  86. a toggle that is ON. The -1 option is primarily used to determine which, if
  87. any, of a set of EXCLUSIVE toggles (mutually exclusive toggles) is ON.
  88.  
  89. wn_pdsettog - primarily used by wn_pdget to reverse the state of a toggle
  90. when the user selects a toggle menu item. If the toggle is an exclusive type 
  91. and it has been turned ON, the routine turns OFF all other toggles in the
  92. menu and returns the menu item INDEX of a toggle that was previously ON.
  93. If none were ON, it returns PDTOGOK. 
  94.  
  95. wn_pdactive - this routine takes a menu option's return value and
  96. activates or de-activates the menu option based on the value of a second
  97. argument. A program can use this routine to control which options a user
  98. has available at any particular point in the program. This is one of
  99. the systems most powerful features.
  100.  
  101. wn_pdtype - this routine serves two purposes. It can change the type code
  102. of a menu item or return its current type code. This routine should only
  103. be used to change type Action or type Selected or the reverse.
  104. It's primary use is to let the type code serve as a flag that can be
  105. tested to see if an item has been selected or not. As an example, the
  106. code that exits a program can check the Load and Save menu items, if Load
  107. has been selected, but Save has not, then it should ask the user if he
  108. wants to save his data before exiting the program. NOTE: the system does not
  109. automatically switch an Active type to a Selected type when an item is 
  110. selected. It is the program's duty to do this. 
  111.  
  112. wn_pdget - this is the real work horse. It gets the user's menu choice
  113. and returns the item's return code. A menu must be opened using wn_pdopen
  114. BEFORE calling this routine. wn_pdget first displays the current choice
  115. in reverse video. If all items in a menu are inactive, none are
  116. highlighted. It then waits for the user to make a selection using the
  117. arrow keys and ENTER or by pressing an item's hotkey. If the selected
  118. item is not a toggle, the item's return code is returned. If it is a
  119. toggle, its state is reversed, but the routine does not exit. If the user
  120. presses ESC, the routine closes the menu window and returns 99.
  121. Wn_pdget handles pulldown menus in a special way. When in a pulldown,
  122. pressing the left arrow key returns 97 and pressing the right arrow key
  123. returns 98. In both cases, the window is closed. The application program
  124. can use these codes to take special action. The program PDDEMO
  125. demonstrates one way of handling these codes by immediately activating
  126. the adjacent main bar menu item and displaying its pulldown. In this way,
  127. once a user has pulled down one menu, he can look at all the other
  128. pulldown menus simply by pressing the left and right arrow keys. 
  129.  
  130. wn_border - this is a handy little routine to select a single or double
  131. ruled border for all subsequent windows.
  132.  
  133. wn_drawborder - this routine immediately redraws the border of a
  134. specified window as single or double ruled.
  135.  
  136.  
  137. THE PDDEMO PROGRAM:
  138.  
  139. As well as giving a good demonstration of the power of the system, this
  140. program contains the basic code to implement almost all common menu
  141. activities and one or two less common ones. As such, it can serve as the
  142. basis for implementing your own menu system, probably with only minor
  143. changes and the addition of routines that implement the actions of the
  144. various menu items.
  145.  
  146. The look and contents are based on the menus found in many Microsoft
  147. applications such as QuickBasic, QuickC, Windows and Excel. 
  148.  
  149. The one thing where PDDEMO differs markedly from MS is in the key that
  150. activates the main bar menu. I've used the slash key (like Lotus 123)
  151. rather than the ALT key. 
  152.  
  153. PDDEMO contains examples of toggle items (Setup/Color), exclusive toggles
  154. (Setup/Printers), activating and de-activating menu options and even a
  155. neat example of how turning ON a toggle in one menu, de-activates the
  156. same option in another menu. Try selecting the same item for both the X
  157. and Y axis using the View/Graphics option. Two level and three level
  158. nested menus are also demonstrated. Most of the pulldown menus are
  159. 'single shot' menus. That is, you make a selection and then you are
  160. returned to the main program. A couple are 'sticky' menus that allow you
  161. to make several selections from the same pulldown menu. You close these
  162. menus by pressing ESC.
  163.  
  164. THE WN_PD ROUTINES IN DETAIL:
  165.  
  166.  
  167. 1. wn_pdopen - opens and displays a menu.
  168.  
  169. USAGE
  170.  
  171.  
  172. int   wn_pdopen(page, row, col, width, height, wa, ba, hka, mx, Active)
  173. int page, row, col;               /* Refer to WINDOW BOSS DOCS (wn_open) */
  174. int width, height,wa, ba;         /* Refer to WINDOW BOSS DOCS (wn_open) */
  175. int hka;                          /* hot key attribute */
  176. struct pdmenu *mx;                /* pointer to popup menu struct */
  177. int Active;                       /* active or inactive menu */
  178.  
  179.  
  180. This must be the first routine you call. Call it to open a new menu
  181. window and display it, or call it to redisplay an existing menu. If
  182. Action is FALSE, the menu item's hotkeys are not highlighted which
  183. indicates to the user that the menu is not active. If Action is TRUE, the
  184. hotkeys are highlighted using the hotkey attribute specified in the
  185. menu's pdmenu structure.
  186.  
  187.  
  188. RETURNS
  189.  
  190. Returns TRUE if successful or FALSE if it failed.
  191.  
  192.  
  193. CAUTIONS AND ADDITIONAL NOTES:
  194.  
  195. None.
  196.  
  197.  
  198.  
  199. 2. wn_pdclose - closes an open menu window.
  200.  
  201. USAGE
  202.  
  203. void wn_pdclose(mx)
  204. struct pdmenu *mx;                /* pointer to menu structure */
  205.  
  206.  
  207. RETURNS
  208.  
  209. Nothing.
  210.  
  211. 3. wn_pdupdate - displays a menu item in normal or reverse video.
  212.  
  213.  
  214. USAGE
  215.  
  216. int    wn_pdupdate(mx, item, style)
  217. struct pdmenu *mx;                /* pointer to menu structure. */
  218. int     item;                     /* index of menu item to update. */
  219. int   style;                      /* either PDNORMAL or PDREVERSE. */
  220.  
  221. Almost exclusively used by wn_pdget. However, PDDEMO does illustrate one
  222. situation where an application program might call this routine. If style
  223. is PDNORMAL, the item is displayed using the window and hotkey attributes
  224. defined in the menu's pdmenu structure. If style is PDREVERSE, the item is
  225. displayed using the reverse of the window attribute. The hotkey is
  226. displayed using the hotkey attribute foreground and the reverse of the
  227. window attribute's background. Item is the INDEX of the menu item, NOT
  228. its return code.
  229.  
  230.  
  231. RETURNS
  232.  
  233. Returns FALSE if the menu isn't open, otherwise it returns TRUE.
  234.  
  235.  
  236. CAUTIONS and ADDITIONAL NOTES
  237.  
  238. Some care should be taken in selecting the window and hotkey attributes
  239. so that the hotkey is highlighted in both normal and reverse video. Look
  240. at the attributes used in PDDEMO. 
  241.  
  242. 4. wn_pdsettog - reverses the state of a toggle menu option and makes
  243.              sure that only one Exclusive toggle is ON at a time.
  244.  
  245.  
  246. USAGE
  247.  
  248.  
  249. int   wn_pdsettog(mx, i)
  250. struct pdmenu *mx;                /* pointer to menu struct. */
  251. int    i;                         /* index of the menu item to toggle */
  252.  
  253.  
  254. Mostly used by wn_pdget, but PDDEMO illustrates its use by an application
  255. program. By definition, a menu item is an ON toggle if it has a type of
  256. either PDTOGG or PDETOGG and the first character of the menu text 
  257. is √ (ALT-251). It is OFF if the first character is a blank. If 
  258. item has a type of PDETOGG (exclusive toggle) and has been toggled ON, 
  259. the routine checks the other toggles and if it finds one
  260. that is ON, it turns it OFF.
  261.  
  262.  
  263. RETURNS
  264.  
  265. Returns PDTOGOK in all cases but one. If it turns an exclusive type toggle ON
  266. and finds another one that was ON, it returns the index of this item.
  267.  
  268.  
  269. CAUTIONS and ADDITIONAL NOTES
  270.  
  271. When designing a menu, ALWAYS use a leading blank space in the menu text
  272. to allow room for the √ toggle character. Don't mix PDTOGG type and 
  273. PDETOGG type toggles in the same menu as this will confuse the user 
  274. and wn_pdsettog will behave unpredictably.
  275.  
  276. 5. wn_pdgettog - get the current toggle status of a specific item or the
  277.                  return code of any PDETOGG type toggle that is ON.
  278.  
  279.  
  280. USAGE
  281.  
  282. int wn_pdgettog(mx, i)
  283. struct pdmenu *mx;                /* pointer to menu structure. */
  284. int i;                            /* menu RETURN VALUE or -1 */
  285.  
  286.  
  287. Note that this routine uses menu item return codes, not menu item
  288. indexes. If the argument 'i' contains a toggle menu item's return code,
  289. the routine returns TRUE if the toggle is ON or FALSE if it is OFF. If 'i'
  290. contains -1, the routine returns the return code of a type PDETOGG toggle 
  291. that is ON. If no toggles are ON, it returns PDTOGOK.
  292.  
  293.  
  294. RETURNS
  295.  
  296. See above.
  297.  
  298.  
  299. CAUTIONS and ADDITIONAL NOTES
  300.  
  301. PDDEMO illustrates an interesting application of wn_pdgettog and
  302. wn_pdsettog to de-activate a menu item in one menu if the identical item
  303. has been toggled ON in another menu. (see the routine dographics).
  304.  
  305. 6. wn_pdactive - activates and de-activates a menu item.
  306.  
  307.  
  308. USAGE
  309.  
  310. void wn_pdactive(mx, i, Action)
  311. struct pdmenu *mx;                /* pointer to menu structure. */
  312. int i;                            /* menu item return code. */
  313. int Action;                       /* TRUE=activate, FALSE=de-activate */
  314.  
  315.  
  316. Use this routine to control which menu items a user can select at any
  317. phase in your program. For example, you would want to de-activate the
  318. Plot option until a user had used the Load option to load some data for
  319. plotting.
  320.  
  321.  
  322. RETURNS
  323.  
  324. None.
  325.  
  326.  
  327. CAUTIONS and ADDITIONAL NOTES
  328.  
  329. NEVER de-activate a bar menu item that has a pulldown menu. The system can't
  330. handle this situation. Instead, de-activate all the pulldown menu's
  331. items. This is better anyway because it allows the user to look at the
  332. menu even if he can't select any of its items at some phase in your
  333. program.
  334.  
  335. This is one of the system's most powerful features. It allows the user to see
  336. all available menu options while protecting him from selecting options
  337. which might cause problems. Also, if used properly, it can help 'walk' a
  338. new user through the program by activating options in a logical sequence ...
  339. Load activates Run, Run activates Plot, Plot activates Plot Options and
  340. so on.
  341.  
  342. 7. wn_pdtype - sets a new item type or returns its current type.
  343.  
  344.  
  345. USAGE
  346.  
  347.  
  348. int  wn_pdtype(mx, i, NewType, Action)
  349. struct pdmenu *mx;                /* pointer to menu structure. */
  350. int i;                            /* menu item return code. */
  351. int NewType;                      /* ignored if Action is FALSE */
  352. int Action;                       /* TRUE or FALSE */
  353.  
  354.  
  355. Use this routine to change an item with a type of PDACTIVE to a type 
  356. of PDSELECTED when a user has selected the item and its actions were 
  357. properly performed. Your program can then test the item type to see if 
  358. it has been selected. If Action is TRUE, the item is given the new type 
  359. specified in NewType. If Action is FALSE, the current type is returned. 
  360. In this case, the contents of NewType are ignored.
  361.  
  362.  
  363. RETURN
  364.  
  365. See above.
  366.  
  367.  
  368. CAUTIONS and ADDITIONAL NOTES
  369.  
  370. This routine should ONLY be used with PDACTIVE and PDSELECTED type menu items.
  371. The primary use is to detect if data has been loaded, but not saved. See
  372. PDDEMO for examples.
  373.  
  374. 8. wn_pdget - lets a user select a menu item and returns the return code
  375.               of the item selected.
  376.  
  377.  
  378. USAGE
  379.  
  380.  
  381. int wn_pdget(mx)
  382. struct pdmenu *mx;                /* pointer to popup menu struct */
  383.  
  384.  
  385. You must call wn_pdopen BEFORE calling this routine.
  386.  
  387. Once this routine is activated, the user can select an item from the menu
  388. by using the left and right arrow keys (bar menus) or up and down arrow
  389. keys (pulldown menus) to highlight an item and then press ENTER.
  390. Alternatively, the user can simply press the item's hotkey to immediately
  391. select an item. Items that are inactive cannot be selected.
  392.  
  393. If the item is an action item, the routine returns the
  394. item's return code. If the item is a toggle, the routine
  395. simply reverses the toggle status, it does not return. If the toggle is
  396. exclusive, (only one ON at a time), it turns OFF any other toggle in the
  397. menu that was ON.
  398.  
  399. If the user presses ESC, the routine closes the menu window and returns
  400. 99. For pulldown menus, pressing the left arrow key returns 97 and
  401. pressing the right arrow key returns 98. In both cases, the menu window
  402. is closed.
  403.  
  404. This routine does not close a menu if the user selects an Action item.
  405. The application program must close the window using wn_pdclose.
  406.  
  407.  
  408. RETURNS
  409.  
  410. If Action type item selected, it returns the item's return code.
  411. ESC returns 99. In pulldown menus, left arrow returns 97, right arrow
  412. returns 98.
  413.  
  414.  
  415. CAUTIONS and ADDITIONAL NOTES
  416.  
  417. It's easy to operate the system. First call wn_pdopen to open an menu. Then
  418. call wn_pdget to get a menu selection. Then call wn_pdclose to close the
  419. menu. PDDEMO is the place to look for all the code you need.
  420.  
  421. 9. wn_border - sets the border style for future windows.
  422.  
  423.  
  424. USAGE
  425.  
  426.  
  427. void   wn_border(Style)
  428. int Style;
  429.  
  430.  
  431. This little routine can be used anywhere in a Windows BOSS program. All
  432. it does is make a call to wn_boxset and supply it with the ASCII codes to
  433. use for either a single ruled border (Style = 1) or double ruled border
  434. (Style = 2). Saves having to look them up all the time.
  435.  
  436.  
  437. RETURNS
  438.  
  439. None.
  440.  
  441.  
  442. 10. wn_drawborder - redraws an open window's border as either single or
  443.                   double ruled.
  444.  
  445.  
  446. USAGE
  447.  
  448. int   wn_drawborder(w, Style)
  449. struct wcb *w;                    /* pointer to window to re-draw */
  450. int Style;                        /* 1 = single 2 = double ruled */
  451.  
  452.  
  453. This little routine can be used anywhere in a Windows BOSS program. All
  454. it does is make a call to wn_dborder and supply it with the ASCII codes
  455. to use for either a single ruled border (Style = 1) or double ruled
  456. border (Style = 2). Saves having to look them up all the time.
  457.  
  458.  
  459. RETURNS
  460.  
  461. Returns 1 if successful or 0 if unsuccessful.
  462.  
  463.  
  464. CAUTIONS and ADDITIONAL NOTES
  465.  
  466. The window becomes the active window after this call.
  467.  
  468.