home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / MagicEYE.lha / MagicEYE / SCREENNO.LHA / ScreenNotify / screennotify.doc < prev    next >
Encoding:
Text File  |  1995-03-26  |  9.7 KB  |  310 lines
  1. TABLE OF CONTENTS
  2.  
  3. screennotify.library/AddCloseScreenClient
  4. screennotify.library/AddPubScreenClient
  5. screennotify.library/AddWorkbenchClient
  6. screennotify.library/RemCloseScreenClient
  7. screennotify.library/RemPubScreenClient
  8. screennotify.library/RemWorkbenchClient
  9.  
  10. screennotify.library/AddCloseScreenClient screennotify.library/AddCloseScreenClient
  11.  
  12.    NAME
  13.         AddCloseScreenClient -- Add a client for CloseScreen() notifications
  14.  
  15.    SYNOPSIS
  16.         handle = AddCloseScreenClient(screen, msgport, priority)
  17.         D0                            A0      A1       D0
  18.  
  19.         APTR AddCloseScreenClient(struct Screen *, struct MsgPort *, BYTE);
  20.  
  21.    FUNCTION
  22.         Add a task as client for CloseScreen() notifications. Each time
  23.         the specified (or any) screen will be closed a ScreenNotifyMessage
  24.         is sent to the message port. The snm_Type field will contain the
  25.         value SCREENNOTIFY_TYPE_CLOSESCREEN. The snm_Value field will
  26.         contain the pointer to the screen structure.
  27.  
  28.    NOTES
  29.         When a task with an active CloseScreen() notification calls
  30.         CloseScreen() it won't receive a notification in order to
  31.         prevent a dead lock!
  32.  
  33.         When a task with no free signal bits calls CloseScreen() the
  34.         notification will not be sent!
  35.  
  36.    INPUTS
  37.         screen   - pointer to the screen structure or NULL to match any screen
  38.         msgport  - pointer to a message port to which the notification
  39.                    messages should be sent
  40.         priority - priority for client in the notification list [-128..127]
  41.  
  42.    RESULTS
  43.         handle   - non-NULL if registration was successful
  44.  
  45.    EXAMPLES
  46.         struct Screen *s;
  47.         struct MsgPort *p;
  48.         APTR handle;
  49.         struct ScreenNotifyMessage *snm;
  50.  
  51.         if (p = CreateMsgPort()) {
  52.          if (handle = AddCloseScreenClient(s, p, 0)) {
  53.           ....
  54.           while (snm = (struct ScreenNotifyMessage *) GetMsg(p)) {
  55.  
  56.            if (snm->snm_Type == SCREENNOTIFY_TYPE_CLOSESCREEN) {
  57.             /* Screen was closed, do your stuff */
  58.            ....
  59.            }
  60.            ReplyMsg((struct Message *) snm);
  61.           }
  62.           ....
  63.           while (!RemCloseScreenClient(handle)) Delay(10);
  64.          }
  65.          DeleteMsgPort(p);
  66.         }
  67.  
  68.    SEE ALSO
  69.         RemCloseScreenClient(), libraries/screennotify.h
  70.  
  71. screennotify.library/AddPubScreenClient screennotify.library/AddPubScreenClient
  72.  
  73.    NAME
  74.         AddPubScreenClient -- Add a client for PubScreenStatus() notifications
  75.  
  76.    SYNOPSIS
  77.         handle = AddPubScreenClient(msgport, priority)
  78.         D0                          A0       D0
  79.  
  80.         APTR AddPubScreenClient(struct MsgPort *, BYTE);
  81.  
  82.    FUNCTION
  83.         Add a task as client for PubScreenStatus() notifications. Each time
  84.         this function is called to modify the PSNF_PRIVATE flag of a public
  85.         screen a ScreenNotifyMessage is sent to the message port. The snm_Type
  86.         field will contain the value SCREENNOTIFY_TYPE_PUBLICSCREEN when the
  87.         flag is cleared (the screen is made public). The snm_Type field will
  88.         contain the value SCREENNOTIFY_TYPE_PRIVATESCREEN when the flag is set
  89.         (the screen will be made private). The snm_Value field will contain
  90.         the pointer to the PubScreenNode structure.
  91.  
  92.    NOTES
  93.         When a task with an active PubScreenStatus() notification calls
  94.         PubScreenStatus() it won't receive a notification to in order to
  95.         prevent a dead lock!
  96.  
  97.         When a task with no free signal bits calls PubScreenStatus() the
  98.         notification will not be sent!
  99.  
  100.         Under certain circumstances it may not be possible to find out the
  101.         PubScreenNode for the screen. In these cases no notification will
  102.         be sent.
  103.  
  104.    WARNING
  105.         Programs using PubScreenStatus() (or Intuition functions which use
  106.         this function) after locking the public screen list will cause a
  107.         dead lock. E.g. MUI 2.3 (or older) has this problem, but it will be
  108.         fixed in future MUI versions.
  109.  
  110.    INPUTS
  111.         msgport  - pointer to a message port to which the notification
  112.                    messages should be sent
  113.         priority - priority for client in the notification list [-128..127]
  114.  
  115.    RESULTS
  116.         handle   - non-NULL if registration was successful
  117.  
  118.    EXAMPLES
  119.         struct Screen *s;
  120.         struct MsgPort *p;
  121.         APTR handle;
  122.         struct ScreenNotifyMessage *snm;
  123.  
  124.         if (p = CreateMsgPort()) {
  125.          if (handle = AddPubScreenClient(s, p, 0)) {
  126.           ....
  127.           while (snm = (struct ScreenNotifyMessage *) GetMsg(p)) {
  128.  
  129.            switch (snm->snm_Type) {
  130.             case SCREENNOTIFY_TYPE_PUBLICSCREEN:
  131.              /* A screen was made public, do your stuff */
  132.              ....
  133.              break;
  134.             case SCREENNOTIFY_TYPE_PRIVATESCREEN:
  135.              /* A screen will be made private, do your stuff */
  136.              ....
  137.              break;
  138.            }
  139.            ReplyMsg((struct Message *) snm);
  140.           }
  141.           ....
  142.           while (!RemCloseScreenClient(handle)) Delay(10);
  143.          }
  144.          DeleteMsgPort(p);
  145.         }
  146.  
  147.    SEE ALSO
  148.         RemCloseScreenClient(), libraries/screennotify.h
  149.  
  150. screennotify.library/AddWorkbenchClient screennotify.library/AddWorkbenchClient
  151.  
  152.    NAME
  153.         AddWorkbenchClient -- Add a client for Workbench notifications
  154.  
  155.    SYNOPSIS
  156.         handle = AddWorkbenchClient(msgport, priority)
  157.         D0                          A0       D0
  158.  
  159.         APTR AddWorkbenchClient(struct MsgPort *, BYTE);
  160.  
  161.    FUNCTION
  162.         Add a task as client for Workbench notifications. Each time the
  163.         Workbench will be closed or opened a ScreenNotifyMessage is sent
  164.         to the message port. The snm_Type field will contain the value
  165.         SCREENNOTIFY_TYPE_WORKBENCH. The snm_Value field will contain one
  166.         of the following values:
  167.  
  168.             FALSE - The Workbench will be closed. The client should close
  169.                     all its windows on the Workbench screen.
  170.  
  171.             TRUE  - The Workbench is open. The client may open its windows
  172.                     on the Workbench screen again.
  173.  
  174.    NOTES
  175.         When a task with an active Workbench notification calls
  176.         CloseWorkBench() or OpenWorkBench() it won't receive a
  177.         notification in order to prevent a dead lock!
  178.  
  179.         When a task with no free signal bits calls CloseWorkBench() or
  180.         OpenWorkBench() the notification will not be sent!
  181.  
  182.    INPUTS
  183.         msgport  - pointer to a message port to which the notification
  184.                    messages should be sent.
  185.         priority - priority for client in the notification list [-128..127]
  186.  
  187.    RESULTS
  188.         handle   - non-NULL if registration was successful
  189.  
  190.    EXAMPLES
  191.         struct MsgPort *p;
  192.         APTR handle;
  193.         struct ScreenNotifyMessage *snm;
  194.  
  195.         if (p = CreateMsgPort()) {
  196.          if (handle = AddWorkbenchClient(p, 0)) {
  197.           ....
  198.           while (snm = (struct ScreenNotifyMessage *) GetMsg(p)) {
  199.  
  200.            if (snm->snm_Type == SCREENNOTIFY_TYPE_WORKBENCH)
  201.             switch (snm->snm_Value) {
  202.              case FALSE: /* Workbench close notification */
  203.               ....
  204.               break;
  205.              case TRUE:  /* Workbench open notification */
  206.               ....
  207.               break;
  208.             }
  209.            ReplyMsg((struct Message *) snm);
  210.           }
  211.           ....
  212.           while (!RemWorkbenchClient(handle)) Delay(10);
  213.          }
  214.          DeleteMsgPort(p);
  215.         }
  216.  
  217.    SEE ALSO
  218.         RemWorkbenchClient(), libraries/screennotify.h
  219.  
  220. screennotify.library/RemCloseScreenClient screennotify.library/RemCloseScreenClient
  221.  
  222.    NAME
  223.         RemCloseScreenClient -- Remove a client for CloseScreen() notifications
  224.  
  225.    SYNOPSIS
  226.         success = RemCloseScreenClient(handle)
  227.         D0                             A0
  228.  
  229.         BOOL RemCloseScreenClient(APTR);
  230.  
  231.    FUNCTION
  232.         Remove a client from the notification list.
  233.  
  234.    INPUTS
  235.         handle  - value returned by AddCloseScreenClient().
  236.  
  237.    RESULTS
  238.         success - TRUE if the client could successfully be removed.
  239.                   FALSE if the library was busy. The task should go to
  240.                   sleep for a short while and then retry.
  241.  
  242.    EXAMPLES
  243.         APTR handle;
  244.         ....
  245.         while (!RemCloseScreenClient(handle)) Delay(10);
  246.  
  247.    SEE ALSO
  248.         AddCloseScreenClient()
  249.  
  250. screennotify.library/RemPubScreenClient screennotify.library/RemPubScreenClient
  251.  
  252.    NAME
  253.         RemPubScreenClient -- Remove a client for PubScreenStatus() notifications
  254.  
  255.    SYNOPSIS
  256.         success = RemPubScreenClient(handle)
  257.         D0                           A0
  258.  
  259.         BOOL RemPubScreenClient(APTR);
  260.  
  261.    FUNCTION
  262.         Remove a client from the notification list.
  263.  
  264.    INPUTS
  265.         handle  - value returned by AddPubScreenClient().
  266.  
  267.    RESULTS
  268.         success - TRUE if the client could successfully be removed.
  269.                   FALSE if the library was busy. The task should go to
  270.                   sleep for a short while and then retry.
  271.  
  272.    EXAMPLES
  273.         APTR handle;
  274.         ....
  275.         while (!RemPubScreenClient(handle)) Delay(10);
  276.  
  277.    SEE ALSO
  278.         AddPubScreenClient()
  279.  
  280. screennotify.library/RemWorkbenchClient screennotify.library/RemWorkbenchClient
  281.  
  282.    NAME
  283.         RemWorkbenchClient -- Remove a client for Workbench notifications
  284.  
  285.    SYNOPSIS
  286.         success = RemWorkbenchClient(handle)
  287.         D0                           A0
  288.  
  289.         BOOL RemWorkbenchClient(APTR);
  290.  
  291.    FUNCTION
  292.         Remove a client from the notification list.
  293.  
  294.    INPUTS
  295.         handle  - value returned by AddWorkbenchClient().
  296.  
  297.    RESULTS
  298.         success - TRUE if the client could successfully be removed.
  299.                   FALSE if the library was busy. The task should go to
  300.                   sleep for a short while and then retry.
  301.  
  302.    EXAMPLES
  303.         APTR handle;
  304.         ....
  305.         while (!RemWorkbenchClient(handle)) Delay(10);
  306.  
  307.    SEE ALSO
  308.         AddWorkbenchClient()
  309.  
  310.