rom/intuition/modifyidcmp.c

   1 /*
   2     Copyright © 1995-2007, The AROS Development Team. All rights reserved.
   3     Copyright © 2001-2003, The MorphOS Development Team. All Rights Reserved.
   4     $Id$
   5 */
   6
   7 #include "intuition_intern.h"
   8 #include <proto/exec.h>
   9
  10 /*****************************************************************************
  11
  12     NAME */
  13 #include <intuition/intuition.h>
  14 #include <proto/intuition.h>
  15
  16     AROS_LH2(BOOL, ModifyIDCMP,
  17
  18 /*  SYNOPSIS */
  19          AROS_LHA(struct Window *, window, A0),
  20          AROS_LHA(ULONG          , flags, D0),
  21
  22 /*  LOCATION */
  23          struct IntuitionBase *, IntuitionBase, 25, Intuition)
  24
  25 /*  FUNCTION
  26     This routine modifies the state of your window's IDCMP (Intuition
  27     Direct Communication Message Port).
  28
  29     Depending on the current state in the IDCMPFlags of the window and
  30     the specified flags these actions are possible:
  31
  32     IDCMP   flags   Action
  33       0   0 Nothing happens
  34       0  !=0    The flags are copied in the IDCMPFlags of the window
  35             and a MessagePort is created and stored in the
  36             UserPort of the window.
  37      !=0      0 The IDCMPFlags are cleared and the MessagePort in the
  38             UserPort is deleted.
  39      !=0     !=0    The flags are copied to the IDCMPFlags of the
  40             window.
  41
  42     INPUTS
  43     window - The window to change the IDCMPFlags in.
  44     flags - New flags for the IDCMPFlags of the window. See
  45         intuition/intuition.h for the available flags.
  46
  47     RESULT
  48     TRUE if the change could be made and FALSE otherwise.
  49
  50     NOTES
  51     You can set up the Window->UserPort to any port of your own
  52     before you call ModifyIDCMP().  If IDCMPFlags is non-null but
  53     your UserPort is already initialized, Intuition will assume that
  54     it's a valid port with task and signal data preset and Intuition
  55     won't disturb your set-up at all, Intuition will just allocate
  56     the Intuition message port half of it.  The converse is true
  57     as well:  if UserPort is NULL when you call here with
  58     IDCMPFlags == NULL, Intuition will deallocate only the Intuition
  59     side of the port.
  60
  61     This allows you to use a port that you already have allocated:
  62
  63     - OpenWindow() with IDCMPFlags equal to NULL (open no ports)
  64     - set the UserPort variable of your window to any valid port of your
  65       own choosing
  66     - call ModifyIDCMP with IDCMPFlags set to what you want
  67     - then, to clean up later, set UserPort equal to NULL before calling
  68       CloseWindow() (leave IDCMPFlags alone)  BUT FIRST: you must make
  69       sure that no messages sent your window are queued at the port,
  70       since they will be returned to the memory free pool.
  71
  72     For an example of how to close a window with a shared IDCMP,
  73     see the description for CloseWindow().
  74
  75     Intuition v50 features WA_UserPort tag, which allows to set
  76     the UserPort at OpenWindow stage. Please note that using this tag
  77     changes the behaviour of ModifyIDCMP() slightly. Creating/disposing
  78     message ports is now up to the app. ModifyIDCMP(win,0) still clears
  79     win->UserPort pointer, but the message port is NOT disposed - you
  80     need to store it and dispose yourself! Also calling
  81     ModifyIDCMP(win,someidcmp) on a window with NULL win->UserPort will
  82     NOT create a new port!
  83
  84     EXAMPLE
  85
  86     BUGS
  87
  88     SEE ALSO
  89     OpenWindow(), CloseWindow(), intuition/extensions.h
  90
  91     INTERNALS
  92
  93     HISTORY
  94     29-10-95    digulla automatically created from
  95                 intuition_lib.fd and clib/intuition_protos.h
  96
  97 *****************************************************************************/
  98 {
  99     AROS_LIBFUNC_INIT
 100
 101     DEBUG_MODIFYIDCMP(dprintf("ModifyIDCMP: Window 0x%lx IDCMP 0x%lx Old 0x%lx\n",
 102                               window, flags, window->IDCMPFlags));
 103
 104     SANITY_CHECKR(window,FALSE)
 105
 106 #ifdef SKINS
 107     if (((struct IntWindow *)window)->specialflags & SPFLAG_USERPORT)
 108     {
 109         window->IDCMPFlags = flags;
 110         if (!flags)
 111         {
 112             Forbid();
 113             window->UserPort = NULL;
 114             Permit();
 115         }
 116         return TRUE;
 117     }
 118 #endif
 119
 120     Forbid();
 121
 122     if (!window->IDCMPFlags && flags && !window->UserPort)
 123     {
 124         window->UserPort = CreateMsgPort ();
 125
 126         if (!window->UserPort)
 127         {
 128             Permit();
 129             return FALSE;
 130         }
 131     }
 132
 133     window->IDCMPFlags = flags;
 134
 135     if (!flags)
 136     {
 137         if (window->UserPort)
 138         {
 139             DeleteMsgPort (window->UserPort);
 140             window->UserPort = NULL;
 141         }
 142     }
 143
 144     Permit();
 145
 146     return TRUE;
 147
 148     AROS_LIBFUNC_EXIT
 149 } /* ModifyIDCMP */