/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    EventMsg.h
    Author:  Copyright  1992 Jason Williams
    Version: 1.00 (16 Mar 1992)
    Purpose: Augments Event() routines to provide a better way of serving
             WIMP messages to a set of user handler functions
*/


#ifndef __dl_eventmsg_h
#define __dl_eventmsg_h

#ifdef __cplusplus
extern "C" {
#endif



extern void EventMsg_Initialise(void);
/*
 * Initialises the EventMsg system ready for use. Attaches EventMsg event
 * handlers to catch all incoming Wimp messages (events 17, 18).
 */


extern BOOL EventMsg_Claim(message_action messagetype, window_handle window,
                           event_handler handler, void *reference);
/*
 * Much like Event_Claim.
 * Pass in the type of message (message action) you wish to handle, or
 * event_ANY to handle ALL messages.
 * Pass in the window for which this applies (event_ANY == all windows)
 * Also pass in the handler function itself (a standard event_handler)
 * and your own reference.
 * Specific-window handlers will have priority over general handlers when
 * an incoming message is dispatched to your registered handlers.
 */


extern int EventMsg_Release(message_action messagetype, window_handle window,
                            event_handler handler);
/*
 * Release the handler for a specific message type and specific window
 * combination.
 * If you pass in event_ANY for the messagetype, only non-message-specific
 * handlers may be released. (c.f. EventMsg_ReleaseMessage)
 * If you pass in event_ANY for the window handle, only non-window-specific
 * handlers may be released. (c.f. EventMsg_ReleaseWindow)
 */


extern int EventMsg_ReleaseWindow(window_handle window);
/*
 * Finds and removes all message handlers that relate to the given window.
 * If you pass in event_ANY as the window handle, all non-window-specific 
 * handlers will be released.
 */


extern BOOL EventMsg_ReleaseMessage(message_action messagetype);
/*
 * Finds and removes all message handlers that relate to the specified 
 * message type. If you pass in event_ANY as the type, all handlers that
 * are not message-specific will be released.
 */

#ifdef __cplusplus
}
#endif


#endif
