home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / popups / Docs / 3 < prev    next >
Text File  |  1993-05-22  |  6KB  |  146 lines
  1. The following Wimp messages are used by the PopUp system.
  2. There are 5 messages in all, but client applications should only ever
  3. involve themselves with the first 2 or 3 (the others are for internal use only)
  4.  
  5. For further example code showing how to handle these messages, see the
  6. PopUp test application's !RunImage file.
  7.  
  8. **** IMPORTANT NOTE **********************************************************
  9. * Strings passed to/from the PopUp system may be terminated by a 0 (NUL)     *
  10. * character as in C, or by a 13 (CR) character as in BASIC.                  *
  11. * This means you can pass strings directly to the manager without worrying,  *
  12. * but you MUST be careful when READING strings returned by the manager       *
  13. *                                                                            *
  14. * BASIC programmers should therefore use the following function to read any  *
  15. * strings passed back by the manager:                                        *
  16. *                                                                            *
  17. *   DEF FNzerostring(address%)            :REM Read a zero-terminated string *
  18. *   LOCAL A%                                                                 *
  19. *                                                                            *
  20. *   A%=address%                                                              *
  21. *   WHILE ?A% > 31: A%+=1: ENDWHILE                                          *
  22. *   ?A%=&0d                                                                  *
  23. *   =$address%                                                               *
  24. *                                                                            *
  25. * C and assembler programmers should use a similar function to read these    *
  26. * strings. DO NOT USE strcpy() strcat(), etc!                                *
  27. * DeskLib provides appropriate functions for this - see DeskLib:StringCR.h   *
  28. ******************************************************************************
  29.  
  30.  
  31. Message_PopUpRequest - &46D40
  32. =============================
  33.  
  34. This message is sent to the client application by the PopUp server when
  35. it needs to attach a PopUp as a leaf of one of your menus.
  36.  
  37. It contains data which you should simply passed straight on to
  38. Wimp_CreateSubMenu by the client application, e.g.
  39.   SYS "Wimp_CreateSubMenu",block!20,block!24,block!28
  40.  
  41. This message may be phased out if future implementations of the WIMP provide
  42. a cleaner way for the PopUp manager to operate.
  43.  
  44. Message contents:
  45.   block + 00    (Standard RISC OS Message header)
  46.  
  47.   block + 20    Window handle
  48.   block + 24    Open xpos
  49.   block + 28    Open ypos
  50.  
  51.  
  52. Message_PopUpState - &46D41
  53. ===========================
  54.  
  55. This message is sent from the PopUp server to the client application whenever
  56. the state of a PopUp changes.
  57.   This can happen:
  58.     * never,  as in 'ProgInfo' which never returns any data to the client
  59.     * once,   as in 'SaveAs' which returns once the user has clicked 'OK'
  60.               or finished dragging the file icon.
  61.     * often,  as in 'WimpColour', which returns a new value every time the
  62.               user chooses a new colour (an 'instant effect' window)
  63.  
  64. On receipt of this message, you should check the PopUp handle (and/or type)
  65. and take appropriate action with the enclosed data.
  66.  
  67. Note that with STATIC PopUps this does NOT indicate that they are closed.
  68. (see below)
  69.  
  70. Message contents:
  71.   block + 00    (Standard RISC OS Message header)
  72.  
  73.   block + 20    PopUp Handle
  74.   block + 24    PopUp type name string (12 chars incl. terminator)
  75.   block + 36    onwards --- PopUp specific data
  76.  
  77.  
  78. Message_PopUpClosed - &46D42
  79. ============================
  80.  
  81. This message is sent from the PopUp server to the client application whenever
  82. a STATIC PopUp is closed. (NOTE that this will NOT be sent for menu PopUps,
  83. which are more of a 'set and forget' entity)
  84.  
  85. It simply informs you that the given PopUp is no longer open. If the PopUp
  86. thinks there is any state to return to you then it will preceed this message
  87. with a PopUpState message.
  88.  
  89. Thus, you may recieve several PopUpState messages over time from the same
  90. PopUp, followed eventually by a single PopUpClosed message. You also may
  91. recieve nothing but a PopUpClosed message, indicating that the user cancelled
  92. the PopUp in a way that means the state has not changed.
  93.  
  94. You can ignore this message. It is only sent so that you may free any
  95. references to the PopUp that you may have stored - e.g. if you only ever open
  96. one static PopUp you probably won't need to bother with this message.
  97.  
  98. Message contents:
  99.   block + 00    (Standard RISC OS Message header)
  100.  
  101.   block + 20    PopUp Handle
  102.   block + 24    PopUp type name string (12 chars incl. terminator)
  103.  
  104.  
  105. ---
  106.  
  107. The following messages are only used internally between the server and the
  108. PopUp Manager module, so normal applications should not know about them.
  109.  
  110. Message_PopUpOpen - &46D43
  111. ==========================
  112.  
  113. Used internally between the PopUp Manager module and server application.
  114. When SWI PopUp_Open is called, the request is passed on to the appropriate
  115. server application via this message.
  116.  
  117. Message contents:
  118.   block + 00    (Standard RISC OS Message header)
  119.  
  120.   block + 20    PopUp Handle (generated by the Manager module)
  121.   block + 24    Application parameter block:
  122.            +24  PopUp type name string (12 chars)
  123.            +36  openx
  124.            +40  openy
  125.  
  126.            +44  flag byte
  127.            +45  reserved byte 1
  128.            +46  reserved byte 2
  129.            +47  reserved byte 3
  130.  
  131.            +48  onwards --- PopUp Specific data (max. 208 bytes)
  132.  
  133.  
  134. Message_PopUpClose - &46D44
  135. ===========================
  136.  
  137. Used internally between the PopUp Manager module and server application.
  138. When SWI PopUp_Close is called, the request is passed on to the appropriate
  139. server application via this message.
  140.  
  141. Message contents:
  142.   block + 00    (Standard RISC OS Message header)
  143.  
  144.   block + 20    PopUp Handle to close
  145.  
  146.