home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / popup / manual.txt < prev    next >
Text File  |  1993-10-23  |  5KB  |  145 lines
  1.                     "Popup" Programmers Manual
  2.                     --------------------------
  3.      Using  a popup menu in one of your programs is  simple,  just 
  4. follow these steps...
  5.  
  6.                             ----------
  7.  
  8. Firstly,  you  must include the file "popup.h" at the top of  your 
  9. source code using a #include statment such as...
  10.  
  11. #include "popup.h"
  12.  
  13.                             ----------
  14.  
  15. Secondly,  you must include the header file that you created  with 
  16. the editor.  This file must be included AFTER the above  file,  as 
  17. some of the definitions in "popup.h" are used in this file.
  18.  
  19.                             ----------
  20.  
  21. Your program must open a VDI virtual workstation,  even if it does 
  22. not use the VDI, as the popup system does use it.
  23.  
  24.                             ----------
  25.  
  26. You should call the external function "PopupInit" like this...
  27.  
  28. PopupInit(width,height,handle);
  29.  
  30. where  "width" and "height" are the screen's width and  height  in 
  31. pixels.  These  values  are returned from the "v_opnvwk"  call  in 
  32. work_out[0] and work_out[1].  "handle" is the virtual  workstation 
  33. handle that you obtained from "v_opnvwk".  So,  a typical call  to 
  34. PopupInit may look like this...
  35.  
  36. PopupInit(work_out[0]+1,work_out[1]+1,ws_handle);
  37.  
  38.                             ----------
  39.  
  40. If you are going to replace the GEM menu bar with a popup version, 
  41. then  the following call is required directly after the  PopupInit 
  42. call.
  43.  
  44. PopupRegister(menu_bar);
  45.  
  46. where "menu_bar" is a character pointer to a string that  contains 
  47. your menu bar. For example...
  48.  
  49. char *menu_bar="  Desk  File  Options";
  50.  
  51. ...would be an example of a menu bar. You should also define these 
  52. external variables at the top of your file...
  53.  
  54. extern int PopupMenu_Index;
  55. extern int PopupMenu_X;
  56. extern int PopupMenu_y;
  57.  
  58. You  will  also need to define the  variables  NPLANES,  MENUDISP, 
  59. CH_HEIGHT,  CH_WIDTH,  SCR_W and SCR_H.  These variables depend on 
  60. the screen resolution,  and the demo program shows you how to  set 
  61. them correctly.
  62.  
  63.                             ----------
  64.  
  65. You may now call the main popup function like this...
  66.  
  67. item=Popup(menu,buttonflag,mainflag);
  68.  
  69. where...
  70.  
  71. "menu" is the name of the menu that you wish to display.
  72.  
  73. "buttonflag"  is either 1 or 0.  1 indicates that this is a  drop-
  74. down menu,  of the sort that is terminated by a left button click. 
  75. 0  indicates that this is a hold-down menu,  of the sort  that  is 
  76. terminated by the release of the left button.
  77.  
  78. "mainflag" is either 1 or 0. 1 indicates that this call is for the 
  79. main  menu  bar.   Generally  speaking,  you  should  use  0.  The 
  80. demonstration file contains three functions for the management  of 
  81. top menus:  "topmenu_choice", "topmenu_useitem" and "menu_switch". 
  82. Examination  of  the demo source will show you how  to  use  these 
  83. functions to create a fully functioning top-line menu bar.
  84.  
  85. "item"  is the index number of the item that was selected  by  the 
  86. user when he/she clicked the button.  If no item was selected (the 
  87. user  clicked  outside  the menu box),  or  a  disabled  item  was 
  88. selected,  or an item that has a sub-menu was selected then -1  is 
  89. returned.  Remember  that  you gave all your items  names  in  the 
  90. editor, so a simple "switch" statement is all that's required.
  91.  
  92. So, to show a "drop-down" popup (!) menu, called "MENU_FILE", that 
  93. has three named entries:  "ITM_LOAD",  "ITM_SAVE", and "ITM_QUIT", 
  94. the following should work...
  95.  
  96. switch((item=Popup(MENU_FILE,1,0)))
  97. {
  98.   case ITM_LOAD:
  99.     load_file();         /* your load function */
  100.     break;
  101.   case ITM_SAVE:
  102.     save_file();         /* your save function */
  103.     break;
  104.   case ITM_QUIT:
  105.     quit();              /* your quit function */
  106.     break;
  107. }
  108.  
  109. Here's a hint, setting check marks in menus is very easy. Take for 
  110. example  the menu item "ITM_VERIFY",  that is in the  menu  called 
  111. "MENU_FILE" that is checked if the variable "verify" is 1,  or not 
  112. checked  if it is zero.  The following line of code would set  the 
  113. check mark appropriately.
  114.  
  115. MENU_FILE[ITM_VERIFY].flags=
  116.  verify ? MSELECTABLE|MCHECKED : MSELECTABLE;
  117.  
  118. The  constants  "MSELECTABLE" and "MCHECKED" are  defined  in  the 
  119. header file "popup.h", as is the MITEM structure.
  120.  
  121.                             ----------
  122.  
  123. Don't  forget  to link one of the two supplied object  files  with 
  124. your code. The file "popup_sr.o" is for people who use the -rr AND
  125. the  -w  switches  on  the  Lattice  'C'  V5  compiler.  The  file 
  126. "popup_s.o" is for people who use the -w option only.  There is no 
  127. support for those of you that use 32 bit integers, that means that 
  128. you must use the -w option.
  129.  
  130. If  you do not have the Lattice 'C' V5 compiler then  registration 
  131. becomes a necessity. Registered users receive the source code that 
  132. created  the above two object files.  It would be a fairly  simple 
  133. job for any competent programmer to make the necessary adjustments 
  134. to the source code to make it compatible with other compilers,  or 
  135. compilers that use ridiculous 32 bit integers.
  136.  
  137.                             ----------
  138.  
  139. If  a  registered user gets stuck while trying to  use  the  popup 
  140. menus,  I will do my best to sort that person out. Please be aware 
  141. that this cannot constitute writing your entire program for you. I 
  142. can only help where I would be of genuine assistance.
  143.  
  144.  
  145.