rom/intuition/modifyidcmp.c

   1 /*
   2     Copyright © 1995-2013, 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 a 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 *****************************************************************************/
  94 {
  95     AROS_LIBFUNC_INIT
  96
  97     DEBUG_MODIFYIDCMP(dprintf("ModifyIDCMP: Window 0x%lx IDCMP 0x%lx Old 0x%lx\n",
  98                               window, flags, window->IDCMPFlags));
  99
 100     SANITY_CHECKR(window,FALSE)
 101
 102 #ifdef SKINS
 103     if (((struct IntWindow *)window)->specialflags & SPFLAG_USERPORT)
 104     {
 105         window->IDCMPFlags = flags;
 106         if (!flags)
 107         {
 108             Forbid();
 109             window->UserPort = NULL;
 110             Permit();
 111         }
 112         return TRUE;
 113     }
 114 #endif
 115
 116     Forbid();
 117
 118     if (!window->IDCMPFlags && flags && !window->UserPort)
 119     {
 120         window->UserPort = CreateMsgPort ();
 121
 122         if (!window->UserPort)
 123         {
 124             Permit();
 125             return FALSE;
 126         }
 127     }
 128
 129     window->IDCMPFlags = flags;
 130
 131     if (!flags)
 132     {
 133         if (window->UserPort)
 134         {
 135             DeleteMsgPort (window->UserPort);
 136             window->UserPort = NULL;
 137         }
 138     }
 139
 140     Permit();
 141
 142     return TRUE;
 143
 144     AROS_LIBFUNC_EXIT
 145 } /* ModifyIDCMP */