Window Communication

Communicating with Intuition

Intuition can notify an application when the user moves the mouse, makes a menu choice, selects an application gadget or changes the window's size. To find out about user activity from Intuition, there are two methods:

• Use the Intuition Direct Communications Message Port (IDCMP) system. Input events are received as standard Exec messages at a port Intuition creates for your window.
• Use the console.device to receive all input events as character sequences.

The IDCMP

The IDCMP gives an application convenient access to many types of user input events through the Exec message and port system. Intuition input event messages include mouse and keyboard activity as well as high level events from menus and gadgets.

With the IDCMP, you specify the input events you want to know about when you open the window. The input events are specified with one or more of the IDCMP flags in <intuition/intuition.h>. Use the flags with the WA_IDCMP tag for the OpenWindowTagList() (or OpenWindowTags()) function. Or, set the flags in NewWindow.IDCMPFlags for the OpenWindow() function. If any IDCMP flags are set when the window is opened, Intuition automatically creates a message port for you to receive messages about user activity. If NULL is specified for IDCMP flags, no port is created. For more information on receiving messages from Intuition, see the IDCMP section in Intuition Input and Output Methods.

The Console Device

An alternative to the message system used by the IDCMP is the console device. The console device gives your application input data translated to ASCII characters or ANSI escape sequences. Raw (untranslated) input is also available through the console device as ANSI escape sequences.

The console device also provides for convenient output of control codes and non-proportional (mono-spaced) text to the window. Output is character based, and includes capabilities such as automatic line wrapping and scrolling. The console device automatically formats and interprets the output stream. Output is kept within the window boundaries automatically so the application need not worry about overwriting the border (no GimmeZeroZero window required).

The console device must be opened by the application before it is used. See Intuition Input and Output Methods or refer to Console Device for more information about using the console device with your Intuition windows.

The IDCMP and the Active Window

On the Amiga, all input is directed to a single window called the active window. In general, changing the active window should be left up to the user. (The user activates a window by pressing the select button while the pointer is within the window boundaries.) If the active window is changed, the user may be confused if the change was not performed at their direction. Hence, new windows should be activated only when they open as a direct and synchronous response to the user's action. Existing windows should almost never be activated by the application.

An application can learn when one of its windows is activated or deactivated by setting the IDCMP flags IDCMP_ACTIVEWINDOW and IDCMP_INACTIVEWINDOW. When these flags are specified, the program will receive a message each time the user activates the window or causes the window to become inactive by activating some other window.

The application may specify that a window is to become active when it opens. This is done with the WA_Activate tag or by setting WFLG_ACTIVATE in NewWindow.Flags when the window is opened.

The application may also activate an existing window. This is done by calling the ActivateWindow() function, which will activate the window as soon as possible. Try to use this function only in response to user action since it may cause a shift in the input focus:

LONG ActivateWindow( struct Window *window );

This function call may have its action deferred. Do not assume that the selected window has become active when this call returns. Intuition will inform the application when this window has become active by sending an IDCMP_ACTIVEWINDOW message. Getting this message is the only supported way of tracking the activation status of your windows.

The IDCMP and Gadgets

One way for a user to communicate with a program running under Intuition is through the use of gadgets. There are two basic kinds of gadgets: system gadgets, which are predefined and managed by Intuition, and application gadgets.

System Gadgets

System gadgets on each window provide the user with the ability to manage the following aspects of the window: size, position and depth. These gadgets are managed by Intuition and the application does not need to take any action for them to operate properly. An additional system gadget is provided for the "close window" function. The close action is not directly managed by Intuition; selecting the close gadget will simply send a message to the application, which is responsible for closing the window.

All of these gadgets are optional, and independent of each other. The graphic representations of these gadgets are predefined, and Intuition always displays them in the same standard locations in the window borders.

The application may choose to be notified when the window changes size, or it may choose to control the timing of the sizing of the window. Controlling the timing of sizing operations is done through the use of the IDCMP_SIZEVERIFY message. IDCMP_SIZEVERIFY messages time out if the application does not respond fast enough. When these an IDCMP_SIZEVERIFY message times out the window sizing operation is cancelled by Intuition.

No information is available to the program on user changes to the depth arrangement of a window. However a refresh message will be sent if part of the window needs to be redrawn as a result of a change to the depth arrangement.

Notification of changes to the position of the window or the size of the window are available through the IDCMP_CHANGEWINDOW and IDCMP_NEWSIZE flags. The application specifies the initial size, the maximum and minimum limits for sizing, and whether the sizing gadget is contained in the right border, bottom border or both borders. (See the section on "Border Dimensions" for information on how the specification of the sizing gadget affects the border sizes.)

The drag gadget has no imagery other than the implicit imagery of the title bar. Setting the window title does not interfere with drag gadget operation, nor does the drag gadget interfere with the display of the window title.

Application Gadgets

The application may place gadgets in windows to request various kinds of input from the user. These gadgets may be specified in the OpenWindowTagList() call, or they may be created and added to the window later. For details about creating and using gadgets, see Intuition Gadgets and GadTools Library.