![[Contents]](../images/toc_d.gif)
![[Index]](../images/index_d.gif)
![[Help]](../images/help_d.gif)
![[Retrace]](../images/retrace_d.gif)
![[Browse <]](../images/prev.gif)
![[Browse >]](../images/next.gif)
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()