NAME
        GT_FilterIMsg -- filter an intuimessage through gadtools. (v36)

   SYNOPSIS
        modimsg = GT_FilterIMsg(imsg)
        D0                      A1

        struct intuimessage *gt_filterimsg(struct intuimessage *);

   FUNCTION
        NOTE WELL:  Extremely few programs will actually need this function.
        You almost certainly should be using gt_getimsg() and gt_replyimsg()
        only, and not GT_FilterIMsg() and gt_postfilterimsg().

        GT_FilterIMsg() takes the supplied intuimessage and asks the
        gadget toolkit to consider and possibly act on it.  returns
        NULL if the message was only of significance to a GadTools gadget
        (i.e. not to you), else returns a pointer to a modified IDCMP
        message, which may contain additional information.

        You should examine the Class, Code, and IAddress fields of
        the returned message to learn what happened.  Do not make
        interpretations based on the original imsg.

        You should use gt_postfilterimsg() to revert to the original
        intuimessage once you are done with the modified one.

   INPUTS
        imsg - an intuimessage you obtained from a window's userport.

   RESULT
        modimsg - a modified intuimessage, possibly with extra information
                  from GadTools, or NULL. When NULL, the message passed in to
                  the function should be sent back to Intuition via replymsg()

   NOTES
        Starting with V39, this function actually expects and returns
        pointers to extintuimessage structures, but the prototype was not
        changed for source code compatibility with older software.

   WARNING
        If this function returns NULL, you must call replymsg() on the
        intuimessage you passed in to gt_filterimsg(). that is, if the
        message was processed by the toolkit you must reply this message
        to Intuition since gadtools will not do this automatically.

   SEE ALSO
        gt_getimsg(), gt_postfilterimsg()