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

    File:    Event.h
    Author:  Copyright  1992 Jason Williams (for code by John Winters)
    Version: 1.01 (14 Jul 1993)
    Purpose: High-level WIMP event dispatch to a hierarchy of user event
             handling functions.
    Mods:    14 July 1993 - Added Event_Initialise3
             20 Mar 1995  - JPS Added veneers for global vars for use with DLLs
*/


#ifndef __dl_event_h
#define __dl_event_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_core_h
#include "Core.h"
#endif

#ifndef __dl_wimp_h
#include "Wimp.h"
#endif



/*  NOTES
 *  =====
 *
 *  Event supplies a set of high-level functions for proper handling of WIMP
 *  events.
 *  It polls the WIMP for you, and then passes the resulting event to one of
 *  your designated handler routines. Events are cascaded down through your
 *  handlers until one of them returns TRUE, indicating that the event has
 *  been successfully dealt with. This allows you to have application-wide
 *  defaults for certain event types, with occasional overrides of that
 *  default for specific windows or icons.
 *
 *  Handlers can be registered for the following (priority-ordered) things:
 *
 *    Specific window, specific icon, specific event.
 *    Specific window, specific icon, any event.
 *    Specific window, any icon, specific event.
 *    Specific window, any icon, any event.
 *    Any window, specific event.
 *    Any window, any event.
 *
 *  When an non window-related event occurs, the order is as follows:
 *
 *    Any window, specific event.
 *    Any window, any event.
 *
 *  A set of default handlers is also provided (handlers.c): You can copy
 *  the code for the handlers you need into your own program as a base event
 *  handling system.
 *
 *  Any event which has no registered handlers will automatically be masked
 *  out in subsequent Wimp_Polls. (Except for "Quit" messages)
 *
 *  NULL events are treated (slightly) specially compared to other events.
 *  After registering handler(s) for NULL events they will be turned on.
 *  (They will NOT be turned on if you request a handler for ALL events. To
 *  enable NULL events, you must specifically register a handler for
 *  event_NULL events.)
 *  As a default, Wimp_Poll will be used, but functions are supplied for
 *  you to set a minimum return time (as in Wimp_PollIdle) if NULL events
 *  are wanted less frequently 
 *  TWO options for NULL event handling are open to you:
 *    Each NULL event is passed to ALL registered handlers,
 *      (To allow you to do important things as often as possible)
 *    Each handler gets one NULL event in turn, in a round-robin fashion.
 *      (To allow you to multitask several "subtask" functions alongside
 *       each other with ease)
 */



/* user event_handler function */
typedef BOOL (*event_handler) (event_pollblock *poll_block, void *reference);


/* JS 01 Apr 1995, 10 Apr 1995 */
/* Added function veneers for globals which must be  */
/* used if compiling for use with DeskLib DLLs.       */

#ifdef _DeskLib_SDLS
  extern event_pollmask  *Event__Ref_mask( void);
  extern int             *Event__Ref_taskhandle( void);
  extern unsigned int    *Event__Ref_wimpversion( void);
  extern char            *Event__Ref_taskname( void);
  extern event_pollblock *Event__Ref_lastevent( void);
#endif

#if defined( _DeskLib_SDLS) && !defined( _DeskLib_Event)
  #define event_mask        (*Event__Ref_mask())
  #define event_taskhandle  (*Event__Ref_taskhandle())
  #define event_wimpversion (*Event__Ref_wimpversion())
  #define event_taskname    (Event__Ref_taskname())
  #define event_lastevent   (*Event__Ref_lastevent())
#else
  extern event_pollmask  event_mask;         /* Mask used by event_ FNs for Wimp_Poll */
  extern int             event_taskhandle;   /* WIMP task-handle of this application  */
  extern unsigned int    event_wimpversion;  /* Wimp version number * 100             */
  extern char            event_taskname[40]; /* Application name                      */
  extern event_pollblock event_lastevent;    /* Last event received by event_()       */
#endif



extern BOOL Event_Claim(event_type eventtype,
                        window_handle window,  icon_handle icon,
                        event_handler handler, void *reference);
/*
 * Call this function to claim an event. This attaches the given handler
 * function to the given event for all future event processing.
 *    eventtype should be event_ANY  - to handle all events, or
 *              an event type        - to handle a specific event
 *    window    should be event_ANY  - if not window-specific, or
 *              a window handle      - to attach ONLY to that window
 *    icon      should be event_ANY  - if not icon-specific, or
 *              an icon handle       - to attach ONLY to that icon
 *              (NOTE: if icon != event_ANY, window MUST be defined)
 *
 *    handler   is the address of your handler function
 *    reference is a handle for any user-data you want passed to the
 *              function whenever it is called.
 */


extern BOOL Event_Release(event_type event,
                          window_handle  window, icon_handle icon,
                          event_handler handler, void *reference);
/*
 * This will release your claim on an event, removing the given handler
 * from further usage.
 * The parameters passed in should be the same as those passed to 
 * Event_Claim.
 */


extern void Event_ReleaseWindow(window_handle window);
/*
 * This is similar to Event_Release, but rather than delinking ONE handler
 * it delinks ALL handlers attached to the given window. This should be done
 * if you close/delete the window using low-level routines. (It is done
 * automatically if you use Window_ calls to remove the window)
 */



extern void Event_Process(event_pollblock *event);
/*
 * Call this to process a Wimp_Poll event. It will cascade the event down
 * through the event-handler hierarchy until one of your event handlers
 * returns TRUE to indicate succesful handling of the message.
 * NOTE that Event_Poll calls Wimp_Poll and Event_Process for you.
 */


extern void Event_Poll(void);
/*
 * Main event poll routine. Use as in:
 * while (TRUE)
 *   Event_Poll();
 */


extern void Event_Initialise(char *taskname);
/*
 * Call this once to initialise the Wimp and the event manager
 * **** This call is obsolescent, and should only be used if you still need
 *      RISC OS 2 compatability - see Event_InitialisePlus, below.
 */


extern void Event_Initialise3(char *taskname, int version, int *messages);
/*
 * Extended version of Event_Initialise which allows the wimp version
 * number to be set and the list of acceptable messages to be passed
 *
 * This function should only be used for version numbers of 300 or greater
 * (i.e. for tasks which will only run on RISC OS 3 or later versions).
 */


extern void Event_CloseDown(void);
/*
 * Call this to CloseDown (quit) the application
 */




typedef BOOL (*event_claimorreleasefn)( 
		event_type	eventtype, 
		window_handle	window, 
		icon_handle	icon, 
		event_handler	handler, 
		void		*reference
		);
/*
This is the function-type of the Event_Claim and Event_Release
functions. Useful for writing functions which accept a pointer to either
of these functions, in order to claim or release a set of events
consistently
*/




#ifdef __cplusplus
}
#endif


#endif
