/*
    ####             #    #     # #
    #   #            #    #       #          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 __Desk_EventMsg_h
#define __Desk_EventMsg_h

#ifdef __cplusplus
	extern "C" {
#endif

#ifndef __Desk_Event_h
	#include "Desk.Event.h"
#endif


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


extern Desk_bool Desk_EventMsg_Claim(Desk_message_action messagetype, Desk_window_handle window,
                           Desk_event_handler handler, void *reference);
/*
 * Much like Desk_Event_Claim.
 * Pass in the type of message (message action) you wish to handle, or
 * Desk_event_ANY to handle ALL messages.
 * Pass in the window for which this applies (Desk_event_ANY == all windows)
 * Also pass in the handler function itself (a standard Desk_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 Desk_EventMsg_Release(Desk_message_action messagetype, Desk_window_handle window,
                            Desk_event_handler handler);
/*
 * Release the handler for a specific message type and specific window
 * combination.
 * If you pass in Desk_event_ANY for the messagetype, only non-message-specific
 * handlers may be released. (c.f. Desk_EventMsg_ReleaseMessage)
 * If you pass in Desk_event_ANY for the window handle, only non-window-specific
 * handlers may be released. (c.f. Desk_EventMsg_ReleaseWindow)
 */


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


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

#ifdef __cplusplus
}
#endif


#endif
