Intuition Windows

This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

Intuition Windows

This chapter provides a general description of windows: how to open windows and define their characteristics; how to get the system gadgets for shaping, moving, closing, and depth arranging windows; how to handle window I/O; and how to preserve the display when windows get overlapped.

About Windows

Windows are rectangular display areas that open on screens. The window acts as a virtual terminal allowing a program to interact with the user as if it had the entire display all to itself.

Each window opens on a specific screen and takes certain characteristics, such as resolution, colors and display attributes, from that screen. These values cannot be adjusted on a window by window basis. Other window characteristics such as the text font are inherited from the screen but can be changed.

An application may open several windows at the same time on a single screen. The Workbench and other public (shareable) screens allow windows opened by different applications to coexist on the same screen.

Windows are moveable and can be positioned anywhere within the screen on which they exist. Windows may also have a title and borders containing various gadgets for controlling the window.

Window System Gadgets

Each window may have a number of system gadgets which allow the user to control window size, shape and arrangement. These gadgets are: the drag bar, the depth gadget, the sizing gadget, the zoom gadget and the close gadget.

The drag bar allows the user to change the position of the window with respect to the screen. The drag bar is in the top border of a window and occupies any space in the top border that is not used by other gadgets. The window may be dragged left, right, up and down on the screen, with the limitation that the entire window must remain within the screen's boundaries. This is done by positioning the pointer over the title bar, selecting the window and dragging to the new position. Window drag may be cancelled by pressing the right mouse button before the drag is completed.

A Window with System Gadgets

The depth gadget allows the user to depth arrange a window with respect to other windows on the screen. The depth gadget is always positioned in the upper right corner of the window. Clicking the depth gadget will move the front-most window behind all other windows. If the window is not the front-most, it will be moved to the front. Selecting the depth gadget with the Shift qualifier always moves the window to the back (behind other windows).

The sizing gadget allows the user to change the size of the window. Sizing is subject to minimum and maximum values set by the application. Width and height are independent in a sizing operation. The sizing gadget is always positioned in the lower right corner of the window. It allows the user to drag this corner of the window to a new position relative to the upper left corner of the window, thus changing the width and height of the window. Window sizing using the sizing gadget may be cancelled by pressing the right mouse button before the size is completed.

The zoom gadget allows the user to quickly alternate between two preset window size and position values. The zoom gadget is always placed immediately to the left of the depth gadget. If there is no depth gadget on the window, the zoom gadget will still appear next to where the depth gadget would have been.

The close gadget performs no direct action on the window, rather it causes Intuition to send a message to the application to close the window. This allows the application to perform any required processing or to warn the user before it closes the window. The close gadget is always positioned in the upper left corner of the window.

The Active Window

There is only one window in the system active at any time. The active window receives all user input, including keyboard and mouse events. This is also known as the input focus, as all input is focused at this single point.

Some areas of the active window are displayed more boldly than those on inactive windows. The active window's borders are filled in with a color which is designed to stand out from the background while inactive windows have their borders filled with the background color. The specific coloring of active and inactive windows is dependent on the screen on which the window is opened. See the section "DrawInfo and the 3D Look" in the "Intuition Screens" chapter for more information.

Windows have two optional titles: one for the window and one for the screen. The window title appears in the top border of the window, regardless of whether the window is active or inactive. The window's screen title appears in the screen's title bar only when the window is active. This gives the user a secondary clue as to what application is active in the screen.

The active window's menus are displayed on the screen when the right mouse button (the menu button ) is pressed. If the active window has no menus, then none will be displayed.

Each window may also have its own mouse-pointer image. Changing the active window will change the pointer to the one currently set for the new active window.

Window Types

There are several types of windows which are described in Window Types.

Other Window Functions

This section contains a brief overview of other Intuition functions that affect windows. For a complete description of all Intuition functions, see the SDK.

Menus and the Active Window

Menus for the active window will be displayed when the user presses the menu button on the mouse. Menus may be disabled for the window by not providing a menu strip, or by clearing the menus with ClearMenuStrip(). Similarly, if the active window has WFLG_RMBTRAP set, the menu button will not bring up the menus.

Two other functions, SetMenuStrip() and ResetMenuStrip(), are used to attach or update the menu strip for a window.

VOID ClearMenuStrip( struct Window *window );
BOOL SetMenuStrip( struct Window *window, struct Menu *menu );
BOOL ResetMenuStrip( struct Window *window, struct Menu *menu );

If SetMenuStrip() has been called for a window, ClearMenuStrip() must be called before closing the window. After ClearMenuStrip() has been called, the user can no longer access menus for this window. See Intuition Menus, for complete information about setting up menus.

Requesters in the Window

Requesters are temporary sub-windows, usually containing several gadgets, used to confirm actions, access files, or adjust the options of a command the user has just given. Request() creates and activates a requester in the window. EndRequest() removes the requester from the window.

BOOL Request( struct Requester *requester, struct Window *window );
VOID EndRequest( struct Requester *requester, struct Window *window );

For simple requesters in a format that matches system requesters, two new functions have been added to Release 2:

LONG EasyRequestArgs( struct Window *window, struct EasyStruct *easyStruct,
                      ULONG *idcmpPtr, APTR args );
LONG EasyRequest( struct Window *window, struct EasyStruct *easyStruct,
                  ULONG *idcmpPtr, APTR arg1, ... );

The EasyRequest() functions support requesters with one or more gadgets automatically providing a layout that is sensitive to the current font and screen resolution. See Intuition Requesters for more information on using requester functions.

Program Control of Window Arrangement

MoveWindow(), SizeWindow(), WindowToFront() and WindowToBack() allow the program to modify the size and placement of its windows. These calls are available in all versions of the operating system.

MoveWindowInFrontOf(), ChangeWindowBox() and ZipWindow() provide more flexible control over the size and placement of windows.

All of these functions are asynchronous. The window will not be affected by them immediately, rather, Intuition will act on the request the next time it receives an input event. Currently this happens at a minimum rate of ten times per second, and a maximum of sixty times per second. There is no guarantee that the operation has taken place when the function returns. In some cases, there are IDCMP messages which will inform the application when the change has completed (for example, an IDCMP_NEWSIZE event indicates that a resize operation has completed).

Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindow() to change the size of the window:

VOID MoveWindow( struct Window *window, LONG dx, LONG dy );
VOID SizeWindow( struct Window *window, LONG dx, LONG dy );

Note that both MoveWindow() and SizeWIndow() take the amount of change in each axis (delta values instead of absolute coordinates). To specify the coordinates as absolute numbers, use ChangeWindowBox(). The SizeWindow() function will respect the window's maximum and minimum dimensions only if the window has a sizing gadget.

ChangeWindowBox() allows an application to change the window size and position in a single call:

VOID ChangeWindowBox( struct Window *window, LONG left, LONG top, LONG width, LONG height );

Note that the position and size values are absolutes and not deltas. The window's maximum and minimum dimensions are always respected.

To depth arrange windows under program control, use WindowToFront() and WindowToBack():

VOID WindowToFront( struct Window *window );
VOID WindowToBack( struct Window *window );

WindowToFront() depth arranges a given window in front of all other windows on its screen. WindowToBack() depth arranges a given window behind all other windows on its screen.

To move a window in front of a specific, given window (as opposed to all windows), use MoveWindowInFrontOf():

VOID MoveWindowInFrontOf( struct Window *window, struct Window *behindWindow );

To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action that occurs when the user selects the zoom gadget:

VOID ZipWindow( struct Window *window );

The two zoom settings are the initial size and position of the window when it was first opened and the alternate position specified with the WA_Zoom tag. If no WA_Zoom tag is provided, the alternate position is taken from the window's minimum dimensions, unless the window was opened at its minimum dimension. In that case, the alternate position is taken from the window's maximum dimension.

Changing Message Queue Limits

Windows have limits on the number of mouse movement and repeat key messages that may be waiting at their IDCMP at any time. These queue limits prevent the accumulation of these messages, which may arrive at the IDCMP message port in large numbers.

Once a queue limit is reached, further messages of that type will be discarded by Intuition. The application will never hear about the discarded messages; they are gone forever. (Note that only mouse move and key repeat messages are limited this way. Other types of messages will still be added to the port.) Messages of the limited type will arrive at the port again after the application has replied to one of the messages in the queue.

The queue limits are independent of each other. Having reached the limit for one type of message does not prevent other types of messages (that have not yet reached their queuing limits) from being added to the IDCMP. Note that the queues apply only to the IDCMP and not to messages received directly via an input handler or from the console device.

Order of event arrival is not a factor in the message count. Messages may be sequential or interspersed with other events-only the number of messages of the specific type waiting at the IDCMP matters.

The WA_RptQueue tag allows setting an initial value for the repeat key backlog limit for the window. There is no function to change this value. The default value for WA_RptQueue is 3.

The WA_MouseQueue tag allows setting an initial value for the mouse message backlog limit for the window. The default value for WA_MouseQueue is 5. The number may later be changed with a call to SetMouseQueue():

LONG SetMouseQueue( struct Window *window, ULONG queueLength );

Note that real information may be lost if the queue fills and Intuition is forced to discard messages. See Intuition Mouse for more information.

Changing Pointer Position Reports

Pointer position messages to a window may be turned on and off by simply setting or clearing the WFLG_REPORTMOUSE flag bit in Window->Flags, in an atomic way, as explained for the WA_RMBTrap tag in the "Window Attributes" section above. Using this direct method of setting the flag avoids the historic confusion on the ordering of the arguments of the ReportMouse() function call.

Mouse reporting may be turned on even if mouse movements were not activated when the window was opened. The proper IDCMP flags must be set for the window to receive the messages. See Intuition Mouse for more details on enabling mouse reporting in an application.

Custom Pointers

The active window also has control over the pointer. If the active window changes the image for the pointer using the functions SetPointer() or ClearPointer(), the pointer image will change:

VOID SetPointer( struct Window *window, UWORD *pointer, LONG height,
                 LONG width, LONG xOffset, LONG yOffset );
 
VOID ClearPointer( struct Window *window );

SetPointer() sets up the window with a sprite definition for a custom pointer. If the window is active, the change takes place immediately. The pointer will not change if an inactive window calls SetPointer(). In this way, each window may have its own custom pointer that is displayed only when the window is active.

ClearPointer() clears the custom pointer from the window and restores it to the default Intuition pointer, which is set by the user. Setting a pointer for a window is discussed further in Intuition Pointer.

Function Reference

The following are brief descriptions of the Intuition functions that relate to the use of Intuition windows. See the SDK for details on each function call.

Functions for Intuition Windows

Function	Description
OpenWindowTagList()	Open a window.
OpenWindowTags()	Alternate calling sequence for OpenWindowTagList().
OpenWindow()	Obsolete way to open a window.
CloseWindow()	Close a window.
BeginRefresh()	Turn on optimized window refresh mode.
EndRefresh()	Turn off optimized window refresh mode.
RefreshWindowFrame()	Redraw the borders and border gadgets of an open window.
ActivateWindow()	Make an open window active.
SizeWindow()	Change the size of an open window.
MoveWindow()	Change the position of an open window.
ChangeWindowBox()	Change the size and position of an open window.
WindowLimits()	Change the minimum and maximum sizes of an open window.
WindowToBack()	Move a window behind all other windows.
WindowToFront()	Move a window in front of all other windows.
MoveWindowInFrontOf()	Move a window in front of another window.
ZipWindow()	Change the size of window to its alternate size.
SetWindowTitles()	Change the window titles for the window and the screen.
SetPointer()	Set up a custom pointer to display whenever the window is active.
ClearPointer()	Restore the mouse pointer to its default imagery.