home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Intuition / Requesters / Requesters.doc < prev    next >
Text File  |  1993-10-12  |  24KB  |  669 lines
  1. 5    REQUESTERS
  2.  
  3. 5.1  INTRODUCTION
  4.  
  5. Requesters are boxes filled with some sort of information which
  6. the user need to respond to. It can be as simple as a question
  7. to insert a disk in the internal drive, or a fully functional
  8. file requester. Requesters are like small windows with some
  9. gadgets connected to it, and they will first disappear when the
  10. user has "satisfied the request".
  11.  
  12.  
  13.  
  14. 5.2  DIFFERENT TYPES OF REQUESTERS
  15.  
  16. There exist three different types of requesters:
  17. - System requesters
  18. - Application requesters
  19. - Double-menu requesters
  20.  
  21.  
  22.  
  23. 5.2.1  SYSTEM REQUESTERS
  24.  
  25. System requesters are opened and maintained by Intuition, and
  26. your program has no control over them. If the user, for
  27. example, is trying to load a file from drive df1:, and there is
  28. no disk present, the operating system would open the following
  29. request:
  30.  
  31.   -----------------------------------
  32.   | System Request ============[*][*]
  33.   -----------------------------------
  34.   | No disk present              |  |
  35.   | in unit  1                   |  |
  36.   |                              |  |
  37.   | ---------         ---------- |  |
  38.   | | Retry |         | Cancel | |  |
  39.   | ---------         ---------- |  |
  40.   --------------------------------[*]
  41.  
  42.  
  43. One important thing about System requesters is that they are
  44. like small windows. You can move around them, push them behind
  45. or in front of other windows/requesters, and resize them.
  46.  
  47.  
  48.  
  49. 5.2.2  APPLICATION REQUESTERS
  50.  
  51. This is the type of requester your program can open. They can
  52. be of any size (limited only by the size of the screen), and
  53. can be as simple or as complicated as you want.
  54.  
  55. If you only want a Yes/No (True/False) requester you can call
  56. the function AutoRequest(), and Intuition will open and take
  57. care of the rest. If you on the other hand want a more
  58. sophisticated requester you need to declare and initialize a
  59. Requester structure with your requirements, and call the
  60. function Request().
  61.  
  62. It is important to notice that an Application requester can not
  63. be moved around, resized etc (the window containing the
  64. requester can still, of course, be moved around and resized).
  65. It is only the System requesters, and the very simple
  66. requesters opened by the AutoRequest function, which acts like
  67. small windows.
  68.  
  69. There is also one other big difference. When an Application
  70. requester has been activated the user can no longer select
  71. gadgets connected to the window. The window has been "frozen".
  72. Eg. try Example4, and you will notice that you can not select
  73. the close-window gadget as long as the requester is active. On
  74. the other hand, if a System requester has been activated, the
  75. user can still click on the close-window gadget, and a
  76. CLOSEWINDOW message is sent.
  77.  
  78.  
  79.  
  80. 5.2.3  DOUBLE-MENU REQUESTERS
  81.  
  82. Double-menu requesters are like normal Application requesters
  83. except that they will open first, and only, when the user
  84. double-clicks on the mouse menu button. To create a Double-menu
  85. requester you need to declare and initialize a Requester
  86. structure, and then call the function SetDMRequest(). Whenever
  87. the user from now on double-clicks on the menu button on the
  88. mouse, the requester will be opened. Call the function
  89. ClearDMRequest() when you do not want the user to be able to
  90. open the requester any more.
  91.  
  92. Only one DM-requester may be connected to each window.
  93.  
  94.  
  95.  
  96. 5.3  GRAPHICS FOR REQUESTERS
  97.  
  98. You can render a requester in two different ways. You can
  99. either tell Intuition what you want, and everything is rendered
  100. for you, or you can supply Intuition with your own customized
  101. Bitmap (which has been rendered by yourself).
  102.  
  103. If you want Intuition to draw the requester for you, you only
  104. need to decide what colour the background of the requester
  105. should be filled with, and declare and initialize one or more
  106. Border and IntuiText structures.
  107.  
  108. If you supply your own customized Bitmap Intuition will not
  109. draw anything itself. That means that all gadget connected to
  110. that requester does not need to have any Border/IntuiText/Image
  111. structures connected to them, since Intuition will not bother
  112. about them.
  113.  
  114.  
  115.  
  116. 5.4  POSITION
  117.  
  118. The requester can either be positioned relative to the top left
  119. corner of the window, or relative to the pointer position. If
  120. you want to position the requester relative to the window, you
  121. simply set the LeftEdge and TopEdge variables as desired. If
  122. you, on the other hand, want it relative to the pointer
  123. position, set the POINTREL flag, and initialize RelLeft and
  124. RelTop as desired.
  125.  
  126.  
  127.  
  128. 5.5  REQUESTERS AND GADGETS
  129.  
  130. When you create a requester, except when you call the function
  131. AutoRequest(), you need to connect at least one gadget to the
  132. requester. Gadgets connected to a requester works exactly the
  133. same as gadgets connected to a window but with two important
  134. differences:
  135.  
  136. 1. Every gadget connected to a requester MUST have the
  137.    REQGADGET flag set in the GadgetType field.
  138.  
  139. 2. At least one gadget must satisfy the request, which means at
  140.    least one gadget must have the ENDGADGET flag set in the
  141.    Activation field. (Once a gadget with an ENDGADGET flag set
  142.    is selected, the requester is satisfied, and will close.)
  143.  
  144. Remember that the user should always be able to find a safe way
  145. to leave the requester without affecting anything. The "way out
  146. gadget" (CANCEL, RESUME etc) should also always be placed on
  147. the right side in the requester. Here is an example:
  148.  
  149.   ---------------------------------------
  150.   | System Request ================[*][*]
  151.   ---------------------------------------
  152.   | Do you really want to quit?      |  |
  153.   |                                  |  |
  154.   |                                  |  |
  155.   | -------                   ------ |  |
  156.   | | Yes |                   | No | |  |
  157.   | -------                   ------ |  |
  158.   ------------------------------------[*]
  159.  
  160. Note that the Yes/True/Retry button is always on the left side
  161. and that the No/False/Cancel button is always on the right side.
  162.  
  163. IMPORTANT! Make sure that the Gadgets are inside the
  164. requester, since Intuition will not do any boundary checking.
  165.  
  166.  
  167.  
  168. 5.6  SIMPLE REQUESTERS
  169.  
  170. If you just want a simple requester with a True/False (or just
  171. False) option, you can use the function AutoRequest(). You give
  172. Intuition some information about how the requester should look
  173. like (height, text etc), and Intuition takes care of everything
  174. else. It opens the requester, put your program to rest, and
  175. when finished, returns a boolean value which tells your program
  176. what the user selected. If the user selected the left gadget
  177. (positive) it returns TRUE, and if the user selected the right
  178. gadget (negative) it returns FALSE.
  179.  
  180. Example:
  181.  
  182.   result = AutoRequest( window, info_text, pos_text, neg_text,
  183.                         pos_IDCMP, neg_IDCMP, width, height );
  184.  
  185.   window:    Pointer to a window if there exist one, else NULL.
  186.  
  187.   info_text: Pointer to an IntuiText structure containing the
  188.              "body text".
  189.  
  190.   pos_text:  Pointer to an IntuiText structure containing the
  191.              "positive text". Eg: "TRUE", "YES", "RETRY" etc.
  192.              (Optional)
  193.  
  194.   neg_text:  Pointer to an IntuiText structure containing the
  195.              "negative text". Eg: "FALSE", "NO", "CANCEL" etc.
  196.  
  197.   pos_IDCMP: The IDCMP flags which satisfy the "positive"
  198.              gadget. (The flag RELVERIFY is already set.)
  199.  
  200.   pos_IDCMP: The IDCMP flags which satisfy the "negative"
  201.              gadget. (The flag RELVERIFY is already set.)
  202.  
  203.   width:     How many pixels wide the requester should be.
  204.  
  205.   height:    How many lines high the requester should be.
  206.  
  207.  
  208.  
  209. 5.7  OPEN A REQUESTERS
  210.  
  211. If you want to use a more complicated requester instead of the
  212. Simple requester you need to:
  213.  
  214. 1. Declare and initialize a Requester structure with your
  215.    requirements.
  216.  
  217. 2. Declare and initialize the Gadget structures which are
  218.    going to be connected to the requester.
  219.  
  220. 3. Call the function Request() in order to display the
  221.    requester as a normal requester, or call the function
  222.    SetDMRequest() to enable the user to bring up the requester
  223.    as a Double-menu requester.
  224.  
  225.  
  226.  
  227. 5.7.1  INITIALIZE A REQUESTER
  228.  
  229. If you want to use a requester you need to declare and
  230. initialize a Requester structure which look like this:
  231.  
  232. struct Requester
  233. {
  234.   struct Requester *OlderRequest;
  235.   SHORT LeftEdge, TopEdge;
  236.