home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / amiga / opalvisn / lsidocs.lha / BuildReq.doc next >
Encoding:
Text File  |  1993-06-14  |  12.5 KB  |  317 lines
  1.  
  2.                 INTRODUCTION
  3.  
  4. This   document  describes  OpalPaint's  Build_Request  function  which  is
  5. available to all OpalPaint modules.  Build_Request provides a simple way of
  6. generating  requesters while keeping a consistent OpalPaint style interface
  7. for the user.
  8.  
  9. Build_Request  is  the  requester function used to build all of OpalPaint's
  10. requesters.   Build_Request  provides a consistent interface through all of
  11. the  requesters,  providing  functions  such  as double click on gadgets to
  12. close  requesters,  keyboard  equivalents  for  OK  and  CANCEL,  requester
  13. dragging and help.  It is STRONGLY suggested that you use this function for
  14. all  requesters,  if however you need more control for an interface such as
  15. the  ChromaCTRL  draw mode the pointers to OpalPaints screen and window are
  16. provided to most OpalPaint modules.
  17.  
  18. Build_Request  can  be  called  recursively,  for  example, a gadget on one
  19. requester  can cause another requester to be displayed without removing the
  20. first.
  21.  
  22. There  are  2  versions  of Build_Request available, the best one to use is
  23. Build_Req_Tags,  which  takes  its  parameters  as  a standard AmigaDOS 2.0
  24. taglist.   The Build_Request function takes its parameters on the stack and
  25. is  provided for backward compatibility, it should however be considered as
  26. obselete.
  27.  
  28.  
  29. OpalPaint/Build_Req_Tags
  30.  
  31.    SYNOPSIS
  32.     Res = Build_Req_Tags (struct TagItem *TagList);
  33.  
  34.  
  35.    INPUTS
  36.     Pointer to a standard 2.0 taglist.
  37.  
  38.    RETURNS
  39.     TRUE if the user hit the OK gadget.
  40.     FALSE if the user hit the CANCEL gadget.
  41.  
  42.  
  43.    FUNCTION
  44.  
  45.     TagItem descriptions:
  46.  
  47.     OPBR_Width
  48.        Specifies the requester width in pixels.
  49.  
  50.     OPBR_Height
  51.        Specifies the requester height in pixels.
  52.  
  53.         OPBR_Flags
  54.        Various flags to specify the requirement for the requester:
  55.  
  56.         BRF_CANCEL    Include a Cancel gadget in the requester.
  57.         BRF_RETURN      Don't handle messages, return after building
  58.                 requester (user only if absolutely necessary).
  59.         BRF_MBUTTONS    Call GadgetFunc when SELECTUP messages are received.
  60.         BRF_NOOK    Don't include an OK gadget in requester.
  61.         BRF_MEDGADS    Use Medium size OK & Cancel gadgets
  62.         BRF_BIGGADS    Use larger OK & Cancel gadgets
  63.         BRF_GADHELP    Gadget dynamic help text is being used.
  64.         BRF_FORCETOP    Make sure requester is above menu bar if possible.
  65.         BRF_DRAGABLE    Requester can be dragged by the user.
  66.         BRF_AMIGAGUIDE    Enable Online help.
  67.  
  68.     OPBR_IText
  69.        Pointer to an IntuiText structure to be displayed in the requester.
  70.        This  can be a linked list of structures to specify headings and
  71.        other text in the requester which are not part of a gadget structure.
  72.  
  73.     OPBR_Gadgets
  74.        Pointer to a gadget list structure of the gadgets to be displayed
  75.        in the requester (NOTE: the REQGADGET flags must be set on all 
  76.        gadgets). See below for a description of gadget functions.
  77.  
  78.     OPBR_GadFunc
  79.        Pointer to a function which will be called when a gadget is hit.
  80.        See below for a description.
  81.  
  82.     OPBR_InitFunc
  83.        Pointer to a function which will be called shortly after the
  84.        requester is displayed, this function can be used for custom
  85.        rendering into the requester. See below for a desciption.
  86.  
  87.     OPBR_MouseMoveFunc
  88.        Pointer to a function which will be called when a MOUSEMOVE
  89.        message is received. This function is useful for giving
  90.        dynamic feedback with propgadgets. See below for description.
  91.  
  92.     OPBR_HelpX
  93.        Left edge of region to display gadget dynamic help text. This
  94.        edge must be specified in pixels relative to the requester
  95.        left edge. See below for a description of dynamic help.
  96.  
  97.     OPBR_HelpY
  98.        Top edge of region to display gadget dynamic help text. This
  99.        edge must be specified in pixels relative to the requester
  100.        top edge. See below for a description of dynamic help.
  101.  
  102.     OPBR_AGuideName
  103.        Pointer to the name of the AmigaGuide file for online help.
  104.        See below for a description of online help.
  105.  
  106.     OPBR_Context
  107.        Pointer to a context structure for online help. See below
  108.        for a description of online help.
  109.  
  110.  
  111. OpalPaint  will  center  the  requester  within the main screen.  Requester
  112. positioning  is important as OpalPaint's screen size will vary depending on
  113. whether the machine is PAL or NTSC and the amount of chip ram available.
  114.  
  115.  
  116.               GADGETS IN REQUESTERS
  117.  
  118. Build_Request  will  always  add  an OK Gadget to the requester (unless the
  119. BRF_NOOK  flag is specified) and will add a Cancel gadget if the BRF_CANCEL
  120. flag is specified.
  121.  
  122. Gadget  ID  1  is  used  for  the OK gadget and ID 2 is used for the Cancel
  123. gadget,  gadget  ID's should start from 3.  If the GadgetID is <100 and the
  124. gadget  is  double clicked on by the user, the requester will automatically
  125. be closed.
  126.  
  127. Build_Request  also  handles  mutual exclusion automatically.  The first 32
  128. gadgets  can  take part in mutual exclusion.  Bits 1&2 correspond to OK and
  129. Cancel  gadgets,  bit  3  corresponds  to the first gadget in the specified
  130. list.  Whenever a gadget is selected who's MutualExclude field is non-zero,
  131. Build_Request  will check each of the first 32 gadgets in the requester one
  132. at  a time, if the bit corresponding to a gadget is set, and that gadget is
  133. selected,  it  will  be deselected and refreshed.  Also, Build_Request will
  134. not allow the user to deselect a gadget if its had a non-zero MutualExclude
  135. field,  the  only  way  it can be deselected is by selecting another gadget
  136. which will exclude it.
  137.  
  138.                CALLBACK FUNCTIONS
  139.  
  140. To  provide  complete control over the requester, OpalPaint allows CallBack
  141. functions  to  be  used  to  pass control back to your program at different
  142. times  during  the  life  of  the  requester.  You must be aware that these
  143. functions will be called under OpalPaint's context (even for LSIModules) so
  144. you   must   be  careful  that  the  data  segment  register  is  correctly
  145. initialised.   This  can be done by using FAR code or by using the 'saveds'
  146. option in SAS/C.  You must also disable stack checking.
  147.  
  148. You  should also note that the callback functions are called using standard
  149. C conventions (i.e.  parameters on the stack).
  150.  
  151. The   requester   can   be  closed  during  CallBack  functions  using  the
  152. OPEndRequest function.
  153.  
  154.  
  155.     INITFUNC
  156.  
  157. Synopsis:
  158.     void InitFunc (struct RastPort *ReqRP,struct Requester *Req),
  159.  
  160.  
  161. This  is a pointer to a function which will be called immediately after the
  162. requester  has been built.  This function can be used to do your own custom
  163. rendering  into the requester, to render borders etc.  InitFunc is passed a
  164. pointer  to  the  Requester structure, as well as the Requester's RastPort.
  165. You may want to save these pointers to perform rendering in the 'MMFunc' or
  166. 'GadgetFunc' functions.
  167.  
  168. NOTE:  Whenever the requester is dragged, this requester will be closed and
  169. then  reopened at the new location, and InitFunc will then be called again.
  170. It  is  important  that  InitFunc can be called mulitiple times without any
  171. side  effects.  For example problems will occur if you assume that InitFunc
  172. will  only  be  called  once,  and  perform and AddGList() function without
  173. checking  the gadget list, this will cause an invalid gadget list structure
  174. if the gadgets are added more than once.
  175.  
  176.  
  177.     GADGETFUNC
  178.  
  179. Synopsis:
  180.     void GadgetFunc (struct Gadget *Gad, BOOL DClick, BOOL RMB, BOOL Tick)
  181.  
  182. GadgetFunc  is  executed  whenever  a  gadget  has  been  hit  and,  if the
  183. BRF_MBUTTONS  flag  is specified, when a SELECTUP message is received.  The
  184. point  at  which  this  function is called when a gadget is selected by the
  185. user  will  depend on the settings of the RELVERIFY and GADGIMMEDIATE flags
  186. in the gadget structure.
  187.  
  188. 'GadgetFunc'  is  passed  a  pointer to the gadget structure for the gadget
  189. that  has been selected, as well as the DClick, RMB and TICK flags.  DClick
  190. is  TRUE  if  a  gadget has been double clicked on, if the GadgetID is less
  191. than  100,  the requester will be closed down immediatelty after GadgetFunc
  192. had  been  called.   RMB is TRUE if the gadget was selected using the right
  193. mouse  button  instead  of  the  left mouse button.
  194.  
  195. If  you  wish  a  gadget to Auto-Repeat, such as an arrow gadget associated
  196. with  a  prop  gadget,  then  you  can  enable  INTUITICK messages from the
  197. GadgetFunc  when the GADGETDOWN message is received, whenever Build_Request
  198. receives  an  INTUITICK message, it will call GadgetFunc with 'Tick' set to
  199. TRUE.
  200.  
  201. If  the  BRF_MBUTTONS  flag  is  set  and  a  SELECTUP message is received,
  202. Build_Request will call GadgetFunc with the Gadget parameter set to NULL.
  203.  
  204.     MMFUNC
  205.  
  206. Synopsis:
  207.     void MMFunc (struct Gadget *Gad)
  208.  
  209. MMFunc  is  a  pointer  to  a  function  which  will  get called whenever a
  210. MOUSEMOVE  message,  or  a GADGETDOWN message on a propgadget, is received.
  211. This  can  be  used  to  dynamically  update text in a requester whenever a
  212. propgadget  is  moved.   Note  that the FOLLOWMOUSE flag must be set in the
  213. gadget structure.
  214.  
  215.  
  216.             HELP IN REQUESTERS
  217.  
  218. Build_Request  provides two types of help within the requesters.  The first
  219. is  called  'Dynamic  Help'  and  is  used  to display help text within the
  220. requester whenever the user moves the mouse pointer over a gadget with help
  221. text associated with it.
  222.  
  223. The  second  form  of  help is called 'OnLine Help', this uses the standard
  224. AmigaDOS  2.0  AmigGuide  interface  to  bring  up  a  seperate help screen
  225. whenever the user hits the HELP key when within the requester.
  226.  
  227.         DYNAMIC HELP
  228.  
  229. Build_Request  also  supports  dynamic  help.   To use this feature set the
  230. BRF_GADHELP   Flag  and  set  OPBR_HelpX  and  OPBR_HelpY  to  specify  the
  231. top-lefthand  edge  of a region used to display help text.  For each gadget
  232. which  has  help  text,  set  the UserData field in the gadget structure to
  233. point  to  a  help  string.  This help string can contain multiple lines of
  234. null  (0)  terminated string, and is finally terminated with 2 nulls.  If a
  235. line  of  text  starts with 0xFA, the line will be printed in Blue, else it
  236. will be white.
  237.  
  238. To see dynamic help in action see the Brush Manipulation menu in OpalPaint
  239. (Right mouse button on the 'B1' gadget).
  240.  
  241.  
  242.         ONLINE HELP
  243.  
  244. Online  help  will  display  a standard AmigaGuide window whenever the user
  245. hits  the  HELP  key within a requester.  This help is context sensitive in
  246. that if the user poisitions the mouse pointer over a gadget it will jump to
  247. the  correct  page for that gadget, if the user is not over a gadget then a
  248. page giving a general description of the requester should be displayed.
  249.  
  250. To  use  online help, you must set the BRF_AMIGAGUIDE flags and specify the
  251. name  of  the  AmigaGuide file contains the HyperText format help using the
  252. OPBR_AGuideName   (within   OpalPaint   itself,   this   field   is  always
  253. 'OpalPaint:Help/OpalPaint.guide').
  254.  
  255. A  context  structure  must  also  be  passed using OPBR_Context, this is a
  256. standard  context structure used by the amigaguide.library.  Basically this
  257. is  an  array of string pointers pointing to the node names associated with
  258. each  gadget.   The  first  entry  should  be the node containing a general
  259. description  of  the requester.  The following nodes will be indexed by the
  260. GadgetID  of the gadget under the mouse pointer when HELP was pressed.  The
  261. first  GadgetID  should  be  3, so GadgetID-2 is used as the index.  If the
  262. GadgetID  is greater than 100 (disabling the double click feature) then 100
  263. will be subtracted from the ID.
  264.  
  265. Therefore  some  thought  has to go into the assignment of GadgetID's.  For
  266. example  lets  say  you have 4 gadgets in the requester, the first two will
  267. close  the  requester  when  double clicked, and the second two won't, then
  268. assign  the  GadgetID's  3,4 to the first two and 105,106 to the second two
  269. gadgets.   The  following  context structure will then be indexed correctly
  270. using those ID's:
  271.  
  272. STRPTR MyReq_Context[] = 
  273.     { "General_Info",    /* General description of requester */
  274.       "Gad1_Help",        /* Help for GadgetID 3 */
  275.       "Gad2_Help",        /* Help for GadgetID 4 */
  276.       "Gad3_Help",        /* Help for GadgetID 105 (note: ID-100) */
  277.       "Gad4_Help"        /* Help for GadgetID 106 (note: ID-100) */
  278.     };
  279.  
  280.  
  281. Build_Request  will  display  the  standard  OpalPaint  help for the OK and
  282. Cancel gadgets (GadgetID's 1&2).
  283.  
  284.  
  285.  
  286.  
  287. OpalPaint/OPEndRequest
  288.  
  289.    SYNOPSIS
  290.     void OPEndRequest(void)
  291.  
  292.    INPUTS
  293.     None
  294.  
  295.    RESULTS
  296.     None
  297.  
  298.    FUNCTION
  299.  
  300. This function will end a requester created with Build_Request.  This can be
  301. used  within  any of the callback functions (such as GadgetFunc) to end the
  302. requester without the user hiting OK or CANCEL.  This function MUST be used
  303. if  you  wish  to  close  the  requester  DO NOT use the intuition function
  304. EndRequest as OpalPaint needs to do its own cleaning up.
  305.  
  306.  
  307.  
  308.  
  309.                        Martin Boyd, Opal Technology.
  310.  
  311.  
  312.    If you have any questions I am contactable at (in order of preference):
  313.  
  314.    OpalVision BBS +1 310 793 7142  'MartinB'
  315.    Internet:  Martin_David_Boyd@cup.portal.com
  316.    Bix:  mboyd
  317.