home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Intuition / IDCMP / IDCMP.doc < prev    next >
Text File  |  1993-10-12  |  22KB  |  604 lines
  1. 8    IDCMP
  2.  
  3. 8.1  INTRODUCTION
  4.  
  5. We have in the last four chapters talked about IDCMP, but have
  6. never actually explained what it is. But in this chapter we
  7. will at last satisfy your hunger for more information. IDCMP
  8. stands for Intuition's Direct Communications Messages Ports
  9. (nice), and is the most commonly used way of receiving messages
  10. from Intuition, and the only way to communicate to Intuition.
  11.  
  12.  
  13.  
  14. 8.2  IDCMP PORTS
  15.  
  16. When something happens inside the Amiga, a disk is inserted, a
  17. gadget is selected etc, a message is automatically created.
  18. Intuition will then examine the messages and check if your
  19. program is interested to hear about it. (Every window has a
  20. list of none or more IDCMP flags which tells Intuition what
  21. this window is interested of.) If a program is interested of
  22. the message, that program will receive a special message
  23. (IntuiMessage), which contains interesting information about
  24. the message.
  25.  
  26. ---------------------------   Messages created inside the Amiga.
  27. | DISKINSERTED   MENUPICK |   For example, a disk is inserted,
  28. |    CLOSEWINDOW          |   a menu is activated, a window is
  29. |  NEWSIZE    GADGETDOWN  |   closed etc...
  30. ---------------------------
  31.     |   |   |   |   |
  32.     V   V   V   V   V
  33.       -------------           Intuition examines every message
  34.       | INTUITION |           and checks if any program is
  35.       -------------           interested of it.
  36.      /            \
  37. DISKINSERTED   GADGETDOWN     If program A is interested of
  38.     |              |          DISKINSERTED messages, Intuition
  39.     V              V          will pass that one along to
  40. ------------- -------------   program A. If program B is 
  41. | PROGRAM A | | PROGRAM B |   interested in GADGETDOWN messages
  42. ------------- -------------   program B will receive a message
  43.                               every time a gadget is selected
  44.                               in program B's window.
  45.  
  46.                               All other messages which no
  47.                               program were interested in will
  48.                               be thrown away.
  49.  
  50.  
  51. Intuition will always start to examine the active window
  52. first, and many IDCMP messages will probably be "swallowed".
  53. If program B is active, and Intuition has found a GADGETDOWN
  54. message, that message would be passed to program B, and all
  55. other programs would never hear about it.
  56.  
  57. Some messages are important for all programs, such as
  58. DISKINSERTED, and will be passed to ALL "interested" windows.
  59. (If a window has its IDCMPFlags field set to DISKINSERTED, that
  60. window is interested about disk inserted messages.)
  61.  
  62.  
  63.  
  64. 8.3  HOW TO RECEIVE IDCMP MESSAGES
  65.  
  66. If you want to receive messages from Intuition you need to:
  67.  
  68.   1. Open an IDCMP port.
  69.   2. Wait for messages.
  70.   3. Collect the messages.
  71.   4. Examine them.
  72.   5. Reply. (Tell Intuition that you have read the message)
  73.  
  74.  
  75.  
  76. 8.3.1  OPEN IDCMP PORTS
  77.  
  78. The IDCMP port can be automatically allocated by Intuition when
  79. you open a window. You only need to specify in the NewWindow
  80. structure's IDCMPFlags field which messages you want to receive
  81. from Intuition, and the rest is done for you. For example, if
  82. you open a window with the IDCMPFlags field set to GADGETDOWN,
  83. a port would be allocated for you, and your program would
  84. receive a message every time a gadget has been selected.
  85.  
  86. If you already have opened a window you can later change the
  87. IDCMP ports by calling the function ModifyIDCMP().
  88.  
  89.  
  90.  
  91. 8.3.2  WAIT FOR MESSAGES
  92.  
  93. Once an IDCMP port has been opened your program only need to
  94. wait until one or more messages arrives. There are two
  95. different ways of waiting for messages:
  96.  
  97. 1. The Passive Way. Your program is halted and will only wake
  98.                     up when a message arrives. This will
  99.                     increase the speed of other applications
  100.                     since the CPU does not need to bother about
  101.                     your program as long as it is sleeping. Use
  102.                     the function Wait().
  103.  
  104. 2. The Active Way.  Your program tries to collect a message,
  105.                     and if it could not find any message it
  106.                     tries again. This is necessary if you want
  107.                     your program to continue doing something,
  108.                     and not stop waiting for a message to
  109.                     arrive.
  110.  
  111.  
  112.  
  113. 8.3.3  COLLECT MESSAGES
  114.  
  115. When you collect a message you should use the function
  116. GetMsg(). It will return a pointer to an IntuiMessage
  117. structure, which contains all important information about the
  118. message, or NULL if it could not collect any message.
  119.  
  120.  
  121.  
  122. 8.3.4  EXAMINE THE MESSAGE
  123.  
  124. Once you have collected a message successfully you can examine
  125. the IntuiMessage structure. The IntuiMessag structure look like
  126. this:
  127.  
  128. struct IntuiMessage
  129. {
  130.   struct Message ExecMessage;
  131.   ULONG Class;
  132.   USHORT Code;
  133.   USHORT Qualifier;
  134.   APTR IAddress;
  135.   SHORT MouseX, MouseY;
  136.   ULONG Seconds, Micros;
  137.   struct Window *IDCMPWindow;
  138.   struct IntuiMessage *SpecialLink;
  139. };
  140.  
  141. ExecMessage:  Used by the Exec so do not touch it.
  142.  
  143. Class:        Contains the IDCMP flag.
  144.  
  145. Code:         Contains some special values which is closely
  146.               related to the IDCMP flag (Class). For example,
  147.               if you receive a MENUVERIFY message you can
  148.               examine the Code field to see if it is your
  149.               program's Menu (Code == MENUHOT) or some
  150.               other program's Menu (Code == MENUWAITING) that
  151.               will be displayed. If you on the other hand
  152.               receives RAWKEY or VANILLAKEY messages the Code
  153.               field will contain the key code and so on.
  154.  
  155. Qualifier:    If your program receives RAWKEY messages
  156.               (untranslated keycodes), this field contains
  157.               information like if the SHIFT or CTRL key was
  158.               pressed or not. (A copy of the ie_Qualifier.)
  159.  
  160. MouseX:       X position of the pointer relative to the top
  161.               left corner of your window.
  162.  
  163. MouseY:       Y position of the pointer relative to the top
  164.               left corner of your window.
  165.  
  166. Seconds:      Copy of the system clock's seconds.
  167.  
  168. Micros:       Copy of the system clock's microseconds.
  169.  
  170. IAddress:     Pointer to that object that created the message.
  171.               For example, if you receive a GADGETDOWN message,
  172.               this field contains a pointer to the Gadget that
  173.               was selected.
  174.  
  175. IDCMPWindow:  Pointer back to the window that sent this message.
  176.  
  177. SpecialLink:  Used by Exec and Intuition so do not touch it.
  178.  
  179.  
  180. The best way to examine this structure is to copy all important
  181. values and then reply as fast as possible. (Intuition will be
  182. slowed down if you do not reply fast.) You can then (after you
  183. have replied) check the copied values. (Remember! Do not use
  184. the IntuiMessage structure any more once you have replied.)
  185.  
  186.  
  187.  
  188. 8.3.5  REPLY
  189.  
  190. Once your program has read everything it is interested of it
  191. should reply back to Intuition by calling the function
  192. ReplyMsg(). This tells Intuition that you have finished with
  193. reading the message.
  194.  
  195. Important! Once you have replied you may NOT examine/change the
  196. IntuiMessage structure any more. Some other program or Intuition
  197. may use it!
  198.  
  199.  
  200.  
  201. 8.3.6  EXAMPLE
  202.  
  203. Here is an example of how your program should collect and
  204. process IDCMP messages: (This is the Passive Way of collecting
  205. messages.)
  206.  
  207.  
  208. /* 1. Wait until a message arrive: */
  209. Wait( 1 << my_window->UserPort->mp_SigBit );
  210.  
  211. /* (my_window is a pointer to a window.)     */
  212. /* (Do not bother to much about the funny formula.) */ 
  213.  
  214.  
  215. /* 2. Try to collect a message: */
  216. my_message = GetMsg( my_window->UserPort );
  217.  
  218.  
  219. /* Could we collect a message? (If message == NULL we have */
  220. /* not collected any message.                              */
  221. if( my_message )
  222. {
  223.   /* YES! We have collected a message successfully. */
  224.  
  225.  
  226.   /* 3. We should now examine the IntuiMessage structure, */
  227.   /*    and save any important values. (If we save the    */
  228.   /*    information we can reply as soon as possible, and */
  229.   /*    later examine the values.)                        */
  230.   class   = my_message->Class;
  231.   code    = my_message->Code;
  232.   address = my_message->IAddress;
  233.   
  234.  
  235.   /* 4. We should now reply since we have finished reading */
  236.   /*    the IntuiMessage structure. (Your progra