GadTools gadgets follow the same input model as other Intuition
components.  When the user operates a GadTools gadget, Intuition notifies
the application about the input event by sending an intuimessage.  the
application can get these messages at the window.userport.  however
GadTools gadgets use different message handling functions to get and reply
these messages.  Instead of the Exec functions getmsg() and replymsg(),
applications should get and reply these messages through a pair of special
GadTools functions, gt_getimsg() and gt_replyimsg().

    struct IntuiMessage *GT_GetIMsg(struct MsgPort *iport)
    void  GT_ReplyIMsg(struct IntuiMessage *imsg)

For gt_getimsg(), the iport argument should be set to the window's
UserPort.  For gt_replyimsg(), the imsg argument should be set to a
pointer to the intuimessage returned by gt_getimsg().

These functions ensure that the application only sees the gadget events
that concern it and in a desirable form.  For example, with a GadTools
slider gadget, a message only gets through to the application when the
slider's level actually changes and that level can be found in the
intuimessage's code field:

    imsg = GT_GetIMsg(win->UserPort);
    object = imsg->IAddress;
    class = imsg->Class;
    code = imsg->Code;
    GT_ReplyIMsg(imsg);
    switch (class)
        {
        case IDCMP_MOUSEMOVE:
            if (object == slidergad)
                {
                printf("Slider at level %ld\n", code);
                }
            ...
            break;
        ...
        }

In general, the intuimessages received from gadtools contain more
information in the code field than is found in regular intuition gadget
messages.  Also, when dealing with GadTools a lot of messages (mostly
idcmp_mousemoves) do not have to be processed by the application.  these
are two reasons why dealing with GadTools gadgets is much easier than
dealing with regular Intuition gadgets.  Unfortunately this processing
cannot happen magically, so applications must use gt_getimsg() and
gt_replyimsg() where they would normally have used getmsg() and replymsg().

gt_getimsg() actually calls getmsg() to remove a message from the
specified window's UserPort.  If the message pertains to a GadTools gadget
then some dispatching code in GadTools will be called to process the
message.  What the program will receive from GT_GetIMsg() is actually a
copy of the real intuimessage, possibly with some supplementary
information from GadTools, such as the information typically found in the
code field.

The gt_replyimsg() call will take care of cleaning up and replying to the
real intuimessage.

    Warning:
    --------
    When an idcmp_mousemove message is received from a gadtools gadget,
    GadTools arranges to have the gadget's pointer in the iaddress
    field of the intuimessage.  while this is extremely convenient, it
    is also untrue of messages from regular Intuition gadgets (described
    in the "intuition gadgets" chapter).  do not make the mistake of
    assuming it to be true.

This description of the inner workings of gt_getimsg() and gt_replyimsg()
is provided for understanding only; it is crucial that the program make no
assumptions or interpretations about the real intuimessage.  any such
inferences are not likely to hold true in the future.  See the section on
documented side-effects for more information.