home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / prog / source / dorqstr.lha / Request.doc < prev   
Text File  |  1987-10-12  |  7KB  |  177 lines
  1.  
  2. DoRequest Programmer Guide
  3. From the Amiga Programmer's Suite Book 1, by RJ Mical
  4. Copyright (C) 1987, Robert J. Mical
  5.  
  6.  
  7.  
  8.  
  9.  
  10. ============================================================================
  11. === DOREQUEST PROGRAMMER'S REFERENCE========================================
  12. ============================================================================
  13.  
  14. The DoRequest() function manages requesters for you.  This is a simple 
  15. routine that bases its efforts on a data structure called ReqSupport.
  16. You initialize a ReqSupport structure and then call DoRequest() 
  17. with the address of it.  DoRequest() displays the requester and then 
  18. handles the user's interaction with the requester until an end condition 
  19. is found, at which time control is returned to you.  When DoRequest() 
  20. returns, the GadgetID of the last selected gadget can be found in your 
  21. support structure's SelectedGadgetID field.  
  22.  
  23. Normally, the DoRequest() function ends when the user has selected one 
  24. of your requester gadgets with the ENDGADGET flag set.  There is one 
  25. special case, however:  your GadgetHandler procedure, should you 
  26. specify a vector to one (described below), must return a long value 
  27. of zero or non-zero.  If it returns a non-zero value, the requester 
  28. is closed and control is returned to your program.  
  29.  
  30. There are several procedure vectors in the ReqSupport structure.  
  31. By filling in these vectors, you specify that you want DoRequest() 
  32. to call your procedures if certain events occur while the requester 
  33. is being displayed.  For example, the GadgetHandler procedure vector 
  34. allows you to specify the address of a procedure that should be called 
  35. whenever the user selects one of your requester gadgets.  The 
  36. MouseMoveHandler lets you respond when mouse movements are reported.  
  37. You set a procedure vector to NULL if you want no action taken when 
  38. that event occurs.  The vectors are itemized under "Initializing the 
  39. ReqSupport" below.  
  40.  
  41. This is an example of setting a procedure vector:
  42.     LONG gotGadget(gadget, x, y)
  43.     struct Gadget *gadget;
  44.     SHORT x, y;
  45.     {
  46.         printf("Got a gadget with ID of %ld\n", gadget->GadgetID);
  47.         if (gadget->GadgetID == END_OF_THE_WORLD) return(TRUE);
  48.         return(FALSE);
  49.     }
  50.  
  51.         ...
  52.         reqsupport.GadgetHandler = gotGadget;
  53.         DoRequest(&reqsupport);
  54.  
  55.  
  56.  
  57. And that's all there is to DoRequest().  It's just a convenience tool 
  58. for requester programmers.  I created it once long time ago, and now 
  59. I never have to bother creating such a mechanism again.  And now 
  60. neither do you.  
  61.  
  62. Consider carving this routine to suit your needs.  If it doesn't do what 
  63. you want, hack it!  For example, my original routine didn't handle 
  64. DISKINSERTED events, but I needed DISKINSERTED events for the 
  65. FileIO Requester so this routine handles them now!  
  66.  
  67.  
  68.  
  69.  
  70. === Initializing the ReqSupport structure ===================================
  71.  
  72. These are the ReqSupport structure fields that must be initialized 
  73. before you call DoRequest().  
  74.  
  75.  
  76. struct Requester Requester;
  77.     Yes, a complete Requester structure!  Make it a good one.
  78.  
  79.  
  80. struct Window *Window;
  81.     As all requesters open in windows, before you open a requester 
  82.     you must have opened a window, even if it's a window that's opened 
  83.     just for the requester.  You write the address of the window 
  84.     structure (as returned by Intuition's OpenWindow() function) into 
  85.     this variable.  
  86.  
  87.  
  88. LONG (*StartRequest)();
  89.     This is a procedure vector.  If this field is not NULL, the 
  90.     routine pointed to by this field will be called after the requester 
  91.     is created but before any event processing takes place.  Your 
  92.     routine will be passed no arguments.  
  93.  
  94.  
  95. LONG (*GadgetHandler)();
  96.     This is a procedure vector.  If this field is not NULL, the 
  97.     routine pointed to by this field will be called with each 
  98.     GADGETUP event.  GADGETUP events occur whenever the user 
  99.     selects a gadget that has the RELVERIFY flag set.  Your 
  100.     GadgetHandler will passed three arguments:  the address of 
  101.     the gadget and the x and y coordinates of the gadget hit.  
  102.     Your routine must return a long value of zero or non-zero, 
  103.     depending on whether you want the requester to be terminated.  
  104.     If it returns a non-zero value, the requester will be closed 
  105.     and control returned to your program.  
  106.  
  107. LONG (*NewDiskHandler)();
  108.     This is a procedure vector.  If this field is not NULL, the 
  109.     routine pointed to by this field will be called with each 
  110.     DISKINSERTED event.  Your NewDiskHandler will be passed no 
  111.     arguments.
  112.  
  113. LONG (*MouseMoveHandler)();
  114.     This is a procedure vector.  If this field is not NULL, the 
  115.     routine pointed to by this field will be called when the 
  116.     mouse moves.  The mouse is seen to move when the user has 
  117.     selected a requester gadget that has the FOLLOWMOUSE flag set.
  118.     Your MouseMoveHandler will be passed no arguments.
  119.  
  120.  
  121.  
  122.  
  123.  
  124. ============================================================================
  125. === DOREQUEST FUNCTION CALL ================================================
  126. ============================================================================
  127.  
  128. *** DoRequest() **********************************************************
  129.  
  130. NAME
  131.     DoRequest  --  Creates and manages a requester
  132.  
  133.  
  134. SYNOPSIS
  135.     DoRequest(ReqSupport);
  136.  
  137.  
  138. FUNCTION
  139.     Creates a requester according to the specifications laid out
  140.     by you in a ReqSupport structure, and manages the interaction
  141.     with the requester for you.  In the end this routine returns control
  142.     to you with an identifier describing which gadget the user selected
  143.     to terminate the requester; this identifier can be found in the
  144.     SelectedGadgetID field of your ReqSupport structure.
  145.  
  146.     Note that if anything goes wrong while trying to create the 
  147.     requester (usually out of memory) this routine returns 
  148.     immediately with the SelectedGadgetID field set to zero.
  149.     Because of this, you should either avoid GadgetIDs of zero
  150.     or at least you should have your Cancel Gadget have an
  151.     ID of zero.
  152.  
  153.     You can specify routines that will be called when certain events
  154.     occur while the requester is displayed.  For instance, you can
  155.     specify that a particular routine be called every time the
  156.     user selects any of the requester gadgets.  See the documentation
  157.     and the ReqSupport structure for details about what
  158.     routine vectors you can supply.
  159.  
  160.  
  161. INPUTS
  162.     ReqSupport = pointer to a ReqSupport structure
  163.  
  164.  
  165. RESULT
  166.     Returns the identifier of the gadget that ended the requester
  167.     in the ReqSupport's SelectedGadgetID field.
  168.     If anything goes wrong (usually out of memory) the SelectedGadgetID
  169.     field is set to zero.
  170.  
  171.  
  172. EXAMPLE
  173.     See the FileIO Requester source code for a detailed example of using
  174.     this routine.
  175.  
  176.  
  177.