[Contents] [index] [Help] [Retrace] [browse <] [Browse >]

The intuimessage structure is an exec message that has been extended to
include Intuition specific information.  The ExecMessage field in the
IntuiMessage is an actual instance of a message structure and is used by
Exec to manage the transmission of the message.  The Intuition extensions
of the IntuiMessage are used to transmit specialized Intuition data to the
program.

    struct IntuiMessage
        {
        struct Message ExecMessage;
        ULONG Class;
        UWORD Code;
        UWORD Qualifier;
        APTR IAddress;
        WORD MouseX, MouseY;
        ULONG Seconds, Micros;
        struct Window *IDCMPWindow;
        struct IntuiMessage *SpecialLink;
        };

The IntuiMessage structure fields are as follows:

ExecMessage
    This field is maintained by Exec.  It is used for linking the message
    into the system and broadcasting it to a message port.  See the
    chapter "exec messages and ports" for more information on the message
    structure and its use.

Class
    Class contains the IDCMP type of this specific message.  By comparing
    the Class field to the IDCMP flags, the application can determine the
    type of this message.  Each message may only have a single IDCMP type.

Code
    Code contains data set by Intuition, such as menu numbers or special
    code values.  The meaning of the Code field changes depending on the
    IDCMP type, or Class, of the message.  Often the code field will
    simply contain a copy of the code of the input event which generated
    this IntuiMessage.

    For example, when the message is of class idcmp_rawkey, code contains
    the raw key code generated by the keyboard device.  When the message
    is of class idcmp_vanillakey, code contains the key mapped ascii
    character.

Qualifier
    This contains a copy of the ie_Qualifier field that is transmitted to
    Intuition by the input device.  This field is useful if your program
    handles raw key codes, since the Qualifier tells the program, for
    instance, whether or not the Shift key or Ctrl key is currently
    pressed.  Check the <devices/inputevent.h> file for the definitions
    of the qualifier bits.

MouseX and MouseY
    Every IntuiMessage will have the mouse coordinates in these
    variables.  The coordinates can either be expressed as absolute
    offsets from the upper left corner of the window, or expressed as the
    amount of change since the last reported positions (delta). If
    idcmp_deltamove is set, then these numbers will represent delta
    positions from the last position.  All messages will have zero in
    these values except idcmp_mousemove and idcmp_mousebutton events,
    which will have the correct delta values for the movement.  If
    IDCMP_DELTAMOVE is not set, then these numbers are the actual window
    offset values.

Seconds and Micros
    These values are copies of the current system clock, in seconds and
    microseconds.  They are set when Intuition generates the message.

    Microseconds (Micros) range from zero up to one million minus one.
    The 32 bits allocated to the Seconds variable has enough accuracy to
    count up to 139 years.  Time is measured from Jan 1, 1978.

IAddress
    Typically this variable contains the address of some Intuition
    object, such as a gadget.  The type of the object depends on the
    Class of the IntuiMessage.  Do not assume that the object is of a
    certain type before checking the Class of the object.

    The IAddress pointer is defined only for the following IDCMP Classes.
    Do not attempt to dereference or otherwise interpret the IAddress
    field of any other type of IntuiMessage.

        IntuiMessage Class  Meaning of IAddress Field
        ------------------  -------------------------
        idcmp_gadgetdown    iaddress points to the gadget.
        idcmp_gadgetup      iaddress points to the gadget.
        idcmp_rawkey        iaddress points to the dead-key information.
        idcmp_idcmpupdate   iaddress points to a tag item list.
        Other classes       No meaning.

    In particular, for idcmp_mousemove intuimessages emanating from
    gact_followmouse gadgets, the iaddress field does not point to the
    gadget.  Interpreting the IAddress as a gadget pointer and trying to
    access the gadget's fields before ascertaining that the event is an
    idcmp_gadgetup or idcmp_gadgetdown event is incorrect, and can lead
    to subtle or serious problems.

    (Note that GadTools gadgets do arrange for the IAddress to point to
    the gadget when idcmp_mousemove messages appear).

IDCMPWindow
    Contains the address of the window to which this message was sent.
    If the application is sharing the window's userport between multiple
    windows, IDCMPWindow allows it to determine which of the windows the
    message was sent to.

SpecialLink
    For system use only.