home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / PopUps / Docs / 2 < prev    next >
Encoding:
Text File  |  1993-05-24  |  6.9 KB  |  178 lines
  1. The PopUp system is supplied as an application (known as the PopUp Server)
  2. which supplies the actual PopUp windows, and a relocatable module (the
  3. PopUp Manager) which provides a simple but powerful interface to PopUps.
  4.  
  5. In this documentation, 'client task' refers to any task/application that
  6. is using the PopUp manager to provide windows such as ProgInfo, SaveAs,
  7. etc.
  8.  
  9. The PopUpManager module supplies two SWI calls for the creation and
  10. removal of PopUps. However, before describing them, I will detail the
  11. fundamental data structure used by the PopUp system...
  12.  
  13.  
  14. Application parameter block
  15. ===========================
  16.  
  17.   This block is supplied to the PopUp_Open SWI by the client task.
  18.   The block specifies all the necessary information about what PopUp
  19.   is desired, and how it should appear.
  20.  
  21.   The block is divided into 2 portions.
  22.   The first 24 bytes are filled in by the client to indicate which PopUp
  23.   is desired, and where/how to open it.
  24.   The remainder of the block is set aside for PopUp-specific data -
  25.     definitions of the available PopUps and the data they expect can be found
  26.     in the document '4 PopUps'
  27.  
  28.   The header is thus defined as follows:
  29.   block
  30.     +00 0/CR terminated string identifying PopUp (12 chars incl. terminator)
  31.         Note that the case of this string is unimportant
  32.         e.g. "ProgInfo"
  33.     +12 (word) OS-coordinate X position for PopUp to appear
  34.     +16 (word) OS-coordinate Y position for PopUp to appear
  35.  
  36.     +20 (byte) Application flag byte (see below)
  37.     +21 (byte) Reserved - must be 0
  38.     +22 (byte) Reserved - must be 0
  39.     +23 (byte) Reserved - must be 0
  40.  
  41.     (+24 onwards then contains the PopUp-specific data)
  42.  
  43.   The block is defined as 220 bytes long (this is so that it will fit neatly
  44.   into a Wimp message).
  45.  
  46.  
  47. Application flag byte
  48. =====================
  49.  
  50. This byte contains values requesting special service from the application.
  51. Currently, the defined flags bits are:
  52.   bit  value  name      meaning if set/meaning if clear
  53.    0    &01   IsLeaf    a MENU PopUp is a menu leaf/
  54.                           a MENU PopUp is a standalone 'submenu' dialogue.
  55.    1    &02   IsStatic  the PopUp should be STATIC (permanent)/
  56.                           the PopUp should be a MENU PopUp (non-permanent)
  57.  
  58. Notes:
  59.   All undefined bits should be zero.
  60.   If the 'IsStatic' bit is set, the 'IsLeaf' bit is ignored.
  61.   A standalone menu PopUp IS different from a static PopUp.
  62.  
  63.  
  64. PopUpManager SWI interface
  65. ==========================
  66.  
  67. SWI "PopUp_Open" (&46D40)
  68. -------------------------
  69.  
  70. Entry: R0 = pointer to application parameter block (see above)
  71.  
  72. Exit:  R0 = 0 for failure, else non-zero positive PopUp Handle
  73.        All other regs preserved
  74.  
  75. Description:
  76.        This SWI instructs the PopUp Manager to open the PopUp described
  77.        in the parameter block.
  78.  
  79.        After initiating the opening of the requested PopUp, this SWI will
  80.        return a PopUp Handle if it succeeded.
  81.  
  82.        For reasons beyond our control, the window will be opened in the near
  83.        future *after* the SWI has returned. (This means that it is feasible
  84.        that you will get back a valid PopUpHandle but no window will
  85.        eventuate! However, if your request is reasonable, this unhappy event
  86.        should not occur often.)
  87.  
  88.        Due to a refusal on the part of the WIMP to allow a task (the PopUp
  89.        Manager) to attach a window (the PopUp) to another task's menu,
  90.        this call *may* generate a Message_PopUpRequest (see '3 Messages)
  91.        in order to correctly open the PopUp - this is very simple to handle
  92.        and is described in the next file.
  93.  
  94.        At a later stage, some PopUps may wish to return a new state (a new
  95.        colour, font, etc) to you - this is also described later, in the
  96.        section on Message_PopUpState.
  97.  
  98.        Apart from this, PopUp_Open is a 'set and forget' function. This
  99.        especially applies to ProgInfo, which, as it supplies no return data,
  100.        is entirely supported by the addition of one SWI call...
  101.  
  102.  
  103. ------------------------------------------------------------------------------
  104.  
  105. SWI "PopUp_Close"
  106. Entry: R0 = PopUp handle as returned by PopUp_Open
  107.  
  108. Exit:  R0 is set to 0 
  109.        All other regs preserved
  110.  
  111. Description:
  112.        This SWI is used to close a PopUp.
  113.        This should only be done in cases like (for example) the 'owning'
  114.        window/document being closed, etc.
  115.  
  116.        Note that it is not necessary to use this call on a MENU PopUp, as
  117.        it will go away automatically if you close the menu tree - thus
  118.        a better way of closing menu PopUps is to SYS "Wimp_CreateMenu",,-1
  119.  
  120.        If your application quits unexpectedly it does not need to call
  121.        PopUp_Close for any static PopUps which it is using - The PopUp Server
  122.        automatically detects the passing of your task and will remove any
  123.        PopUp windows which you 'own'.
  124.  
  125.  
  126.  
  127. ==============================================================================
  128.  
  129. The PopUpManager also supplies 2 more SWIs. These are only for internal
  130. communications between the server and manager, and MUST NOT be called by
  131. normal client applications. They are described below in case you feel the
  132. urge to write your own server application... (preferably a module!)
  133.  
  134. SWI "PopUp_Register"
  135. Entry: R0 => PopUp id string (max 12 chars, including terminator)
  136.        R1 =  PopUp flag word
  137.        R2 =  Server's task handle
  138.  
  139. Exit:  R0 =  1 if you are now the registered server for this PopUp type,
  140.              else R0 = 0
  141.        All other regs preserved
  142.  
  143. Description:
  144.        This SWI call registers the given WIMP task as the server which will
  145.        handle all requests for the given type of PopUp in the future.
  146.        The SWI is therefore usually called several times by the typical server,
  147.        to register it as providing several PopUp types.
  148.  
  149.        Note that if an existing server has already registered for a given
  150.        PopUp type, your registration will supercede the old one (so your server
  151.        will replace the other one for this PopUp type)
  152.  
  153.        The PopUp flag word is as follows:
  154.          bit 0 (value &01): This PopUp type supports a MENU instantiation
  155.          bit 1 (value &02): This PopUp type supports multiple STATIC
  156.                             instantiations
  157.  
  158.        Note that your server MUST support all types of instantiation that are
  159.        defined in the "PopUps" document file, otherwise some programs which
  160.        expect the default set of PopUp types may be unable to get the window
  161.        that they desire...
  162.  
  163. ------------------------------------------------------------------------------
  164.  
  165. SWI "PopUp_Deregister"
  166. Entry: R0 => PopUp id string (max 12 chars, including terminator)
  167.        R1 =  (ignored)
  168.        R2 =  Server's task handle
  169.  
  170. Exit:  All registers preserved
  171.  
  172. Description:
  173.        This SWI de-registers the given server so that it is no longer expected
  174.        to supply support for the given PopUp type. Note that if another server
  175.        has taken over this PopUp type, this call has no effect at all.
  176.  
  177. ------------------------------------------------------------------------------
  178.