NAME
    OpenWindow -- Open an Intuition window.

SYNOPSIS
    window = openwindow( newwindow )
    D0                   A0

    struct window *openwindow( struct newwindow * );

FUNCTION
    Opens an Intuition window of the given dimensions and position,
    with the properties specified in the newwindow structure.
    Allocates everything you need to get going.

    New for V36: there is an extensive discussion of public Screens
    and visitor windows at the end of this section.  Also,
    you can provide extensions to the newwindow parameters using
    and array of tagitem structures.  see the discussion below,
    and the documentation for the function openscreentaglist().

    Before you call OpenWindow(), you must initialize an instance of
    a newwindow structure.  newwindow is a structure that contains
    all of the arguments needed to open a window.  The newwindow
    structure may be discarded immediately after it is used to open
    the window.

    If Type == CUSTOMSCREEN, you must have opened your own screen
    already via a call to openscreen().  then intuition uses your screen
    argument for the pertinent information needed to get your window
    going.  On the other hand, if type == one of the Intuition's standard
    screens, your screen argument is ignored.  Instead,
    Intuition will check to see whether or not that screen
    already exists:  if it doesn't, it will be opened first before
    Intuition opens your window in the standard screen.

    New for V36: If you specify Type == WBENCHSCREEN, then your
    window will appear on the Workbench screen, unless the global
    public screen mode SHANGHAI is set, in which case your window
    will be "hijacked" to the default public screen.  See also
    setpubscreenmodes().

    New for V36: If the WFLG_NW_EXTENDED flag is set, it means that the
    field 'ExtNewWindow->Extension' points to an array of TagItems, as
    defined in intuition/tagitem.h.  This provides an extensible means
    of providing extra parameters to OpenWindow.  For compatibility
    reasons, we could not add the 'Extension' field to the newwindow
    structure, so we have define a new structure extnewwindow, which
    is identical to newwindow with the addition of the extension field.

    We recommend that rather than using ExtNewWindow.Extension, you
    use the new Intuition function openwindowtaglist() and its
    varargs equivalent OpenWindowTags().  We document the window
    attribute tag ID's (ti_Tag values) here, rather than in
    openwindowtaglist(), so that you can find all the parameters
    for a new window defined in one place.

    If the WFLG_SUPER_BITMAP flag is set, the bitmap variable must point
    to your own bitmap.

    The DetailPen and the BlockPen are used for system rendering; for
    instance, the title bar is first filled using the BlockPen, and then
    the gadgets and text are rendered using DetailPen.  You can either
    choose to supply special pens for your window, or, by setting either
    of these arguments to -1, the screen's pens will be used instead.

    Note for V36: The DetailPen and BlockPen no longer determine
    what colors will be used for window borders, if your window
    opens on a "full-blown new look screen."

INPUTS
    newwindow = pointer to an instance of a newwindow structure.  that
           structure is initialized with the following data:
-------------------------------------------------------------------------
    Left = the initial x-position for your window
    Top = the initial y-position for your window
    Width = the initial width of this window
    Height = the initial height of this window

    DetailPen = pen number (or -1) for the rendering of window details
     (like gadgets or text in title bar)
    BlockPen = pen number (or -1) for window block fills (like title bar)
    [For V36: Title bar colors are determined otherwise.]

    Flags = specifiers for your requirements of this window, including:
         which system gadgets you want attached to your window:

        - WFLG_DRAGBAR allows this window to be dragged
        - WFLG_DEPTHGADGET lets the user depth-arrange this window
        - WFLG_CLOSEGADGET attaches the standard close gadget
        - WFLG_SIZEGADGET allows this window to be sized.

        If you ask for the WFLG_SIZEGADGET gadget, you must specify one or
        both of the flags WFLG_SIZEBRIGHT and WFLG_SIZEBBOTTOM below; if
        you don't, the default is WFLG_SIZEBRIGHT.  See the following items
        WFLG_SIZEBRIGHT and WFLG_SIZEBBOTTOM for more details.

        - WFLG_SIZEBRIGHT is a special system gadget flag that
          you set to specify whether or not you want the
          RIGHT border adjusted to account for the physical size
          of the sizing gadget.  The sizing gadget must, after
          all, take up room in either the right or bottom border
          (or both, if you like) of the window.  Setting either
          this or the WFLG_SIZEBBOTTOM flag selects which edge
          will take up the slack.  This will be particularly
          useful to applications that want to use the extra space
          for other gadgets (like a proportional gadget and two
          Booleans done up to look like scroll bars) or, for
          for instance, applications that want every possible
          horizontal bit and are willing to lose lines vertically.
          NOTE:  if you select WFLG_SIZEGADGET, you must select
          either WFLG_SIZEBRIGHT or WFLG_SIZEBBOTTOM or both.  If
          you select neither, the default is WFLG_SIZEBRIGHT.
        - WFLG_SIZEBBOTTOM is a special system gadget flag that
          you set to specify whether or not you want the
          BOTTOM border adjusted to account for the physical size
          of the sizing gadget.  For details, refer to
          WFLG_SIZEBRIGHT above.

        - WFLG_GIMMEZEROZERO for easy but expensive output

        what type of window layer you want, either:
        - WFLG_SIMPLE_REFRESH
        - WFLG_SMART_REFRESH
        - WFLG_SUPER_BITMAP

        - WFLG_BACKDROP for whether or not you want this window to be one
          of Intuition's special backdrop windows.  See WFLG_BORDERLESS
          as well.

        - WFLG_REPORTMOUSE for whether or not you want to "listen" to
          mouse movement events whenever your window is the active
          one.  After you've opened your window, if you want to change
          you can later change the status of this via a call to
          reportmouse().  whether or not your window is listening to
          mouse is affected by gadgets too, since they can cause you
          to start getting reports too if you like.  The mouse move
          reports (either InputEvents or messages on the IDCMP) that
          you get will have the x/y coordinates of the current mouse
          position, relative to the upper-left corner of your window
          (WFLG_GIMMEZEROZERO notwithstanding).  This flag can work in
          conjunction with the IDCMP Flag called IDCMP_MOUSEMOVE, which
          allows you to listen via the IDCMP.

        - WFLG_BORDERLESS should be set if you want a window with no
          border padding.  Your window may have the border variables
          set anyway, depending on what gadgetry you've requested for
          the window, but you won't get the standard border lines and
          spacing that comes with typical windows.

          This is a good way to take over the entire screen, since you
          can have a window cover the entire width of the screen using
          this flag.  This will work particularly well in conjunction
          with the WFLG_BACKDROP flag (see above), since it allows you
          to open a window that fills the ENTIRE screen.  NOTE:  this is
          not a flag that you want to set casually, since it may cause
          visual confusion on the screen.  The window borders are the
          only dependable visual division between various windows and
          the background screen.  Taking away that border takes away
          that visual cue, so make sure that your design doesn't need
          it at all before you proceed.

        - WFLG_ACTIVATE is the flag you set if you want this window to
          automatically become the active window.  The active
          window is the one that receives input from the keyboard and
          mouse.  It's usually a good idea to to have the window you
          open when your application first starts up be an ACTIVATED
          one, but all others opened later not be ACTIVATED (if the
          user is off doing something with another screen, for
          instance, your new window will change where the input is
          going, which would have the effect of yanking the input rug
          from under the user).  Please use this flag thoughtfully and
          carefully.

          Some notes: First, your window may or may not be active
          by the time this function returns.  Use the IDCMP_ACTIVEWINDOW
          IDCMP message to know when your window has become active.
          Also, be very careful not to mistakenly specify the
          obsolete flag names WINDOWACTIVE or ACTIVEWINDOW.  These are
          used in other contexts, and their values unintentionally added
          to your flags can cause most unfortunate results.  To avoid
          confusion, they are now know as WFLG_WINDOWACTIVE and
          IDCMP_ACTIVEWINDOW.

        - WFLG_RMBTRAP, when set, causes the right mouse button events
          to be trapped and broadcast as events.  You can receive
          these events through either the IDCMP or the console.

        - WFLG_NOCAREREFRESH indicates that you do not wish to
          be responsible for calling beginrefresh() and endrefresh()
          when your window has exposed regions (i.e., when the
          IDCMP_REFRESHWINDOW message would be generated).  See also
          the descriptions of these two functions.

        - WFLG_NW_EXTENDED (V36) indicates that newwindow in fact points
          to an extnewwindow structure, and that the 'extension'
          field points to an array of tagitem structures, with
          meaning described below.

    IDCMPFlags = IDCMP is the acronym for Intuition Direct Communications
        message port.  (it's intuition's sole acronym.) if any of the
        IDCMP Flags is selected, Intuition will create a pair of
        message ports and use them for direct communications with the
        task opening this window (as compared with broadcasting
        information via the Console device).  See the "Input and
        Output Methods" chapter of the Intuition Reference Manual for
        complete details.

        You request an IDCMP by setting any of these flags.  Except
        for the special VERIFY flags, every other flag you set tells
        Intuition that if a given event occurs which your program
        wants to know about, it is to broadcast the details of that
        event through the IDCMP rather than via the Console device.
        This allows a program to interface with Intuition directly,
        rather than going through the Console device.

        Many programs have elected to use IDCMP communication
        exclusively, and not to associate a console with their
        windows at all.  Some operations, such as IDCMP_MENUVERIFY,
        can ONLY be achieved using IDCMP.

        The IDCMP flags you can set are:

        - IDCMP_REQVERIFY is the flag which, like IDCMP_SIZEVERIFY and ...

        - IDCMP_MENUVERIFY (see immediately below), specifies that you
          want to make sure that your graphical state is quiescent
          before something extraordinary happens.  In this case, the
          extraordinary event is that a rectangle of graphical data is
          about to be blasted into your window.  if you're drawing
          directly into its screen, you probably will wish to make sure
          that you've ceased drawing before the user is allowed to bring
          up the DMRequest you've set up, and the same for when system
          has a request for the user.  Set this flag to ask for that
          verification step.

        - IDCMP_REQCLEAR is the flag you set to hear a message whenever
          a requester is cleared from your window.  If you are using
          IDCMP_REQVERIFY to arbitrate access to your screen's bitmap, it
          is safe to start your output once you have heard an
          IDCMP_REQCLEAR for each IDCMP_REQSET.

        - IDCMP_REQSET is a flag that you set to receive a broadcast
          for each requester that is opened in your window.  Compare
          this with IDCMP_REQCLEAR above.  This function is distinct
          from IDCMP_REQVERIFY.  This functions merely tells you that a
          requester has opened, whereas IDCMP_REQVERIFY requires you to
          respond before the requester is opened.

        - IDCMP_MENUVERIFY is the flag you set to have Intuition stop
          and wait for you to finish all graphical output to your
          window before rendering the menus.  Menus are currently
          rendered in the most memory-efficient way, which involves
          interrupting output to all windows in the screen before the
          menus are drawn.  If you need to finish your graphical
          output before this happens, you can set this flag to make
          sure that you do.

        - IDCMP_SIZEVERIFY means that you will be doing output to your
          window which depends on a knowledge of the current size of the
          window.  If the user wants to resize the window,  you may want
          to make sure that any queued output completes before the sizing
          takes place (critical text, for instance).  If this is the
          case, set this flag.   Then, when the user wants to size,
          Intuition will send you the IDCMP_SIZEVERIFY message and wait()
          until you reply that it's OK to proceed with the sizing. NOTE:
          when we say that Intuition will wait() until you reply, what
          we're really saying is that user will WAIT until you reply, which
          suffers the great negative potential of User-Unfriendliness.
          So remember:  use this flag sparingly, and, as always with any
          IDCMP message you receive, reply to it promptly!  then, after
          user has sized the window, you can find out about it using
          IDCMP_NEWSIZE.

        With all the "VERIFY" functions, it is not save to leave them
        enabled at any time when your task may not be able to respond
        for a long period.

        It is NEVER safe to call AmigaDOS, directly or indirectly, when
        a "VERIFY" function is active.  If AmigaDOS needs to put up a
        disk requester for you, your task might end up waiting for the
        requester to be satisfied, at the same time as Intuition is
        waiting for your response.  The result is a complete machine
        lockup.  USE modifyidcmp() to turn off any verify messages
        BEFORE CALLING dos.library!!

        For V36: If you do not respond to the verification IntuiMessages
        within the user specified timeout duration, Intuition will abort
        the operation.  This eliminates the threat of these easy
        deadlocks, but can result in a confused user.  Please try
        hard to continue to avoid "logical deadlocks".

        - IDCMP_NEWSIZE is the flag that tells Intuition to send an IDCMP
          message to you after the user has resized your window.  At
          this point, you could examine the size variables in your
          window structure to discover the new size of the window.
          See also the IDCMP_CHANGEWINDOW IDCMP flag.

        - IDCMP_REFRESHWINDOW when set will cause a message to be sent
          whenever your window needs refreshing.  This flag makes
          sense only with WFLG_SIMPLE_REFRESH and WFLG_SMART_REFRESH
          windows.

        - IDCMP_MOUSEBUTTONS will get reports about mouse-button up/down
          events broadcast to you (Note:  only the ones that
          don't mean something to Intuition.  If the user clicks the
          select button over a gadget, Intuition deals with it and you
          don't find out about it through here).

        - IDCMP_MOUSEMOVE will work only if you've set the
          WFLG_REPORTMOUSE flag above, or if one of your gadgets has the
          GACT_FOLLOWMOUSE flag set.  Then all mouse movements will be
          reported here, providing your window is active.

        - IDCMP_GADGETDOWN means that when the User "selects" a gadget
          you've created with the GACT_IMMEDIATE flag set, the fact
          will be broadcast through the IDCMP.

        - IDCMP_GADGETUP means that when the user "releases" a gadget that
          you've created with the GACT_RELVERIFY flag set, the fact
          will be broadcast through the IDCMP.  This message is
          only generated if the release is "good", such as releasing
          the select button over a Boolean gadget, or typing ENTER
          in a string gadget.

        - IDCMP_MENUPICK selects that menu number data will be sent via
          the IDCMP.

        - IDCMP_CLOSEWINDOW means broadcast the IDCMP_CLOSEWINDOW event
          through the IDCMP rather than the console.

        - IDCMP_RAWKEY selects that all IDCMP_RAWKEY events are
          transmitted via the IDCMP.  Note that these are absolutely RAW
          keycodes, which you will have to translate before using.
          Setting this and the MOUSE flags effectively eliminates the need
          to open a Console device to get input from the keyboard and
          mouse.  Of course, in exchange you lose all of the console
          features, most notably the "cooking" of input data and
          the systematic output of text to your window.

        - IDCMP_VANILLAKEY is for developers who don't want the hassle
          of IDCMP_RAWKEYS.  This flag will return all the keycodes after
          translation via the current country-dependent keymap.  When
          you set this flag, you will get IntuiMessages where the Code
          field has a decoded ANSI character code representing the key
          struck on the keyboard.  Only codes that map to a single
          character are returned: you can't read such keys as HELP or
          the function keys with IDCMP_VANILLAKEY.

          NOTE FOR V36: If you have both IDCMP_RAWKEY and IDCMP_VANILLAKEY
          set, Intuition will send an IDCMP_RAWKEY event for those
          *downstrokes* which do not map to single-byte characters
          ("non-vanilla" keys).  In this way you can easily detect cursor
          keys, function keys, and the Help key without sacrificing the
          convenience of IDCMP_VANILLAKEY.

        - IDCMP_INTUITICKS gives you simple timer events from Intuition
          when your window is the active one; it may help you avoid
          opening and managing the timer device.  With this flag set,
          you will get only one queued-up INTUITICKS message at a
          time.  If Intuition notices that you've been sent an
          IDCMP_INTUITICKS message and haven't replied to it, another
          message will not be sent.  Intuition receives timer events and
          considers sending you an IDCMP_INTUITICKS message approximately
          ten times a second.

        - IDCMP_DELTAMOVE gives raw (unscaled) input event delta X/Y
          values.  This is so you can detect mouse motion regardless of
          screen/window/display boundaries.  This works a little
          strangely: if you set both IDCMP_MOUSEMOVE and IDCMP_DELTAMOVE.
          IDCMPFlags, you will get IDCMP_MOUSEMOVE messages with delta
          x/y values in the MouseX and MouseY fields of the
          IDCMPMessage.

        - IDCMP_NEWPREFS indicates you wish to be notified when the
          system-wide preferences changes.  for v36, there is a new
          environment mechanism to replace preferences, which we
          recommend you consider using instead.

        - Set IDCMP_ACTIVEWINDOW and IDCMP_INACTIVEWINDOW to get messages
          when those events happen to your window.  Take care not to
          confuse this "ACTIVEWINDOW" with the familiar sounding, but
          totally different "WINDOWACTIVE" flag.  These two flags have
          been supplanted by "IDCMP_ACTIVEWINDOW" and "WFLG_WINDOWACTIVE".
          Use the new equivalent terms to avoid confusion.

        - Set IDCMP_DISKINSERTED or IDCMP_DISKREMOVED to learn when
          removable disks are inserted or removed, respectively.

        - IDCMP_IDCMPUPDATE is a new class for V36 which is used as
          a channel of communication from custom and boopsi gadgets
          to your application.

        - IDCMP_CHANGEWINDOW is a new class for V36 that will be sent
          to your window whenever its dimensions or position are changed
          by the user or the functions sizewindow(), movewindow(),
          changewindowbox(), or zipwindow().

        - IDCMP_MENUHELP is new for V37.  If you specify the WA_MenuHelp
          tag when you open your window, then when the user presses the
          HELP key on the keyboard during a menu session, Intuition will
          terminate the menu session and issue this even in place of an
          IDCMP_MENUPICK message.
            - NEVER follow the NextSelect link for MENUHELP messages.
            - You will be able to hear MENUHELP for ghosted menus.
              (This lets you tell the user why the option is ghosted.)
            - Be aware that you can receive a MENUHELP message whose code
              corresponds to a menu header or an item that has sub-items
              (which does not happen for MENUPICK).  The code may also be
              MENUNULL.
            - LIMITATION:  if the user extend-selects some checkmarked
              items with the mouse, then presses MENUHELP, your
              application will only hear the MENUHELP report.  You
              must re-examine the state of your checkmarks when you
              get a MENUHELP.
            - Availability of MENUHELP in V36 is not directly
              controllable.  We apologize...

    Gadgets = the pointer to the first of a linked list of the your own
          Gadgets which you want attached to this window.  can be null
          if you have no Gadgets of your own

   CheckMark = a pointer to an instance of the struct image where can
          be found the imagery you want used when any of your
          menu items is to be checkmarked.  If you don't want to
          supply your own imagery and you want to just use
          Intuition's own checkmark, set this argument to NULL

   Text = a null-terminated line of text to appear on the title bar of
          your window (may be null if you want no text)

   Type = the screen type for this window.  If this equal CUSTOMSCREEN,
          you must have already opened a CUSTOMSCREEN (see text above).
          Types available include:
              - WBENCHSCREEN
              - CUSTOMSCREEN
              - PUBLICSCREEN (new for V36, see text below)

   screen = if your type is one of intuition's standard screens, then
          this argument is ignored.  However, if Type == CUSTOMSCREEN,
          this must point to the structure of your own screen

   bitmap = if you have specified wflg_super_bitmap as the type of
           refreshing you want for this window, then this value points to a
           instance of the struct bitmap.  However, if the refresh type
           is NOT WFLG_SUPER_BITMAP, this pointer is ignored.

   MinWidth, MinHeight, MaxWidth, MaxHeight = the size limits for this
          window.  These must be reasonable values, which is to say that
          the minimums cannot be greater than the current size, nor can
          the maximums be smaller than the current size.  If they are,
          they're ignored.  Any one of these can be initialized to zero,
          which means that that limit will be set to the current
          dimension of that axis.  The limits can be changed after the
          window is opened by calling the windowlimits() routine.

          NOTE: ORIGINALLY, we stated that:

          "If you haven't requested the WFLG_SIZEGADGET option, these
          variables are ignored so you don't have to initialize them."

          It is now clear that a variety of programs take it upon
          themselves to call sizewindow() (or changewindowbox()) without
          your program's consent or consulting your WFLG_SIZEGADGE
          option.  To protect yourself against the results, we strongly
          urge that if you supply suitable values for these fields even
          if you do not specify WFLG_SIZEGADGET.

          The maximums may be LARGER than the current size, or even
          larger than the current screen.  The maximums should be set to
          the highest value your application can handle.  This allows
          users with larger display devices to take full advantage of
          your software.  If there is no good reason to limit the size,
          then don't.  -1 or ~0 indicates that the maximum size is only
          limited by the size of the window's screen.

          See also the docs on the function windowlimits() for more
          information.

   Extension (New for V36) = a pointer to an array (or chain of arrays)
        of TagItems to specify additional parameters to OpenWindow().
        TagItems in general are described in utility/tagitem.h,
        and the OpenWindow tags are defined in intuition/intuition.h
        and described here.  For items pertaining to Public Screens
        and visitor windows, please see below.

    Here are the TagItem.ti_Tag values that are defined for OpenWindow
    (and openwindowtaglist()).

    Certain tags simply override equivalent values in newwindow,
    and allow you to open a window using openwindowtaglist() without
    having a newwindow structure at all.  in each case, cast
    the corresponding data to ULONG and put it in ti_Data.

    The compatible tag items include:

    WA_Left
    WA_Top
    WA_Width
    WA_Height
    WA_DetailPen
    WA_BlockPen
    WA_IDCMP
    WA_Flags        - initial values for Flags before looking at other
                    Boolean component Tag values
    WA_Gadgets
    WA_Checkmark
    WA_Title
    WA_CustomScreen - also implies CUSTOMSCREEN property
    WA_SuperBitMap - also implies WFLG_SUPER_BITMAP refresh mode.
    WA_MinWidth
    WA_MinHeight
    WA_MaxWidth
    WA_MaxHeight

    These Boolean tag items are alternatives to the NewWindow.Flags
    Boolean attributes with similar names.

    WA_SizeGadget           - equivalent to WFLG_SIZEGADGET
    WA_DragBar              - equivalent to WFLG_DRAGBAR
    WA_DepthGadget          - equivalent to WFLG_DEPTHGADGET
    WA_CloseGadget          - equivalent to WFLG_CLOSEGADGET
    WA_Backdrop             - equivalent to WFLG_BACKDROP
    WA_ReportMouse          - equivalent to WFLG_REPORTMOUSE
    WA_NoCareRefresh        - equivalent to WFLG_NOCAREREFRESH
    WA_Borderless           - equivalent to WFLG_BORDERLESS
    WA_Activate             - equivalent to WFLG_ACTIVATE
    WA_RMBTrap              - equivalent to WFLG_RMBTRAP
    WA_WBenchWindow         - equivalent to WFLG_WBENCHWINDOW
                              (system PRIVATE)
    WA_SimpleRefresh        - only specify if TRUE
    WA_SmartRefresh         - only specify if TRUE
    WA_SizeBRight           - equivalent to WFLG_SIZEBRIGHT
    WA_SizeBBottom          - equivalent to WFLG_SIZEBBOTTOM
    WA_GimmeZeroZero        - equivalent to WFLG_GIMMEZEROZERO

    The following tag items specify new attributes of a window.

    WA_ScreenTitle - You can specify the screen title associated
        with your window this way, and avoid a call to setwindowtitles()
        when your window opens.

    WA_AutoAdjust - a Boolean attribute which says that it's OK
        to move or even shrink the dimensions of this window
        to fit it on the screen, within the dimension
        limits specified by MinWidth and MinHeight.
        Someday, this processing might be sensitive to the
        currently visible portion of the screen the window
        will be opening on, so don't draw too many conclusions
        about the auto-adjust algorithms.
        (Normally, this attribute defaults to FALSE.  However,
        if you call OpenWindowTags() or openwindowtaglist()
        with a NULL newwindow pointer, this attribute defaults
        to TRUE).

    WA_InnerWidth
    WA_InnerHeight - You can specify the dimensions of the interior
        region of your window, independent of what the border
        thicknesses will be.  You probably want to specify
        WA_AutoAdjust to allow Intuition to move your window
        or even shrink it so that it is completely on screen.

        Note: using these tags puts some reasonable restrictions
        on the gadgets you can specify as "border" gadgets when
        you open your window.  Since border gadgets determine
        the border dimensions and hence the overall dimensions of
        your window, those dimensions cannot be used calculating
        the position or dimensions of border gadgets.

        Here's the complete list of restrictions:
        - GACT_LEFTBORDER gadgets cannot be GFLG_RELWIDTH if
          WA_InnerWidth is used.
        - GACT_RIGHTBORDER gadgets MUST be GFLG_RELRIGHT if
          WA_InnerWidth is used.
        - GACT_TOPBORDER gadgets cannot be GFLG_RELHEIGHT if
          WA_InnerHeight is used.
        - GACT_BOTTOMBORDER gadgets MUST be GFLG_RELBOTTOM if
          WA_InnerHeight is used.

    WA_PubScreenName - This tag item declares that you want your window
        to open as a visitor window on the public screen whose name
        is pointed to by (UBYTE *) ti_Data.

    WA_PubScreen - Open as a visitor window on the public screen
        whose address if provided as (struct screen *) ti_data.
        To ensure that this screen remains open long enough, you
        must either:
            1) Be the screen's owner
            2) have another window already open on the screen
            3) use lockpubscreen()
        Using exec.library/forbid() is not sufficient.

        You can provide ti_Data to be NULL (zero), without any
        of the above precautions, to specify the default public screen.

    WA_PubScreenFallBack - This Boolean attribute specifies that a
        visitor window should "fall back" to opening on the default
        public screen if the explicitly specify public screen is not
        available.

    WA_WindowName - this visionary specification of a window
        rendezvous name string is not yet implemented.

    WA_Colors - this equally great idea about associating a palette
        specification with the active window may not ever be implemented.

    WA_Zoom - ti_Data points to an array of four WORD's to be used
        as the initial Left/Top/Width/Height of the "alternate
        Zoom position and dimensions."  The presence of this tag
        item implies that you want a Zoom gadget, even though you
        might not have a sizing gadget.

    WA_MouseQueue - This tag specifies a limit for the number
        of outstanding IDCMP_MOUSEMOVE IntuiMessages that Intuition
        will send to your window.  You can change the value of this
        limit after the window is open using setmousequeue().

    WA_RptQueue - This tag specifies a limit for the number of
        outstanding repeated-IDCMP_RAWKEY, repeated-IDCMP_VANILLAKEY,
        and repeated-IDCMP_IDCMPUPDATE IntuiMessages that Intuition will
        send to your window.  Currently, there is no function to adjust
        the repeat-key queue.

    WA_BackFill - ti_Data is a pointer to a hook structure that
        the Layers library will call when your window needs
        "backfilling."  See layers.library/installlayerhook().

    WA_MenuHelp - ti_Data is a boolean.  If true, enables the MenuHelp
        feature for this window.  See IDCMP_MENUHELP above.  (Ignored
        in V36 and earlier).

NOTES
    Regarding Public Screens, you can specify a window to be a
    "visitor window" on a public screen in one of several ways.
    In each case, you must be sure not to specify a newwindow
    type of CUSTOMSCREEN.  You should use the value PUBLICSCREEN.

    There are actually several ways you can specify which screen
    you want a visitor window to be opened on:

        1) Specify the name of the public screen WA_PubScreenName,
        or a NULL pointer, in ti_Data.  The name might have been
        provided by the user.  A NULL pointer means to use the
        default public screen.

        If the named screen cannot be found, the default public screen
        will be used if the Boolean attribute WA_PubScreenFallBack
        is TRUE.

        2) Specify a pointer to a public screen using the
        WA_PubScreen tag item.  The WA_PubScreenFallBack
        attribute has no effect.  You can specify the default
        public screen by providing a NULL pointer.

        You can also specify the pointer by setting NewWindow.Type
        to PUBLICSCREEN, and specifying the public screen pointer
        in NewWindow.Screen.  The WA_PubScreen tag item has precedent
        over this technique.

        Unless NULL, the screen pointer provided MUST be a valid
        public screen.  You may ensure this several ways:

        - Be the owner of the screen.
        - Have a window already open on the screen.
        - Use lockpubscreen() to prevent the screen from closing.
        - specifying the WFLG_VISITOR bit in NewWindow.Flags is not
          supported.

        It is anticipated that the last will be the most common method
        of opening public screens because you often want to examine
        properties of the screen your window will be using in order
        to compensate for differences in dimension, depth, and font.

        The standard sequence for this method is as follows:
        lockpubscreen() - obtain a pointer and a promise
        layout window       - adapt your window to the screen you will use
        OpenWindow()        - using the pointer you specify
        unlockpubscreen()     - once your window is open, you can let go
                              of the lock on the public screen
        ... normal window even processing ...
        closewindow().

    Regarding "service" windows, such as those opened for a system
    requester or file requester associated with a given "client"window.
    These windows should NOT be "visitor" windows.  Open them
    using NewWindow.Type = CUSTOMSCREEN and NewWindow.Screen
    equal to the screen of the client window (window->WScreen).
    You can also use WA_CustomScreen, which has precedence.

    This ensures that the requester service window will be allowed to
    open on the same screen as the client window, even if that
    screen is not a public screen, or has private status.

    This has an implication for service/client protocol: when you
    pass a window pointer to any system requester routine or
    to a routine which creates some other other service window,
    you MUST keep your window open until the client window
    is closed.

    If a requester service will allow a NULL client window, this
    should indicate to open the service window on the default public
    screen (probably Workbench).  The correct way to get a pointer
    to this screen is to call LockPubScreen( NULL ).  In this
    case, you want to open as a visitor window, which means you
    should use either PUBLICSCREEN or WA_PubScreen, described above.
    You should call unlockpubscreen() after your visitor window is open.

    As of V36, gadgets in the right and bottom border
    (specified with GACT_RIGHTBORDER and GACT_BOTTOMBORDER) only
    contribute to the dimensions of the borders if they are also
    GFLG_RELRIGHT and GFLG_RELBOTTOM, respectively.

RESULT
    If all is well, returns the pointer to your new window
    If anything goes wrong, returns NULL

BUGS
    When you open a window, Intuition will set the font of
    the window's rastport to the font of the window's screen.
    This does not work right for GimmeZeroZero windows: the
    BorderRPort rastport has the font set correctly, but
    Window.RPort is set up with the system default font.
    For compatibility reasons, we won't be fixing this problem.

    Also, there is a compatibility trick going on with the
    default font of your window's rastport if the screen's
    font is "fancy."  See the SA_SysFont attribute described
    under openscreen().

    Unless you arrange otherwise, each window you open will allocate
    a signal for your task from the 16 "user signals."
    If no signal is available, your window will not be able
    to be opened.  In early V36 versions and before, Intuition didn't
    check this condition, but just left you with an unusable port.

SEE ALSO
   openwindowtaglist(), openscreen(), modifyidcmp(), setwindowtitles(),
    lockpubscreen(), setdefaultpubscreen(), zipwindow(),
    layers.library/installlayerhook(), setpubscreenmodes()