RISC DISC 1/RISC_DISC_1.iso/pd_share/code/gcc/!GCC/patches/DeskLib/h/Event

Text File | 1994-10-03 | 7.0 KB | 183 lines

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


#ifndef __dl_event_h
#define __dl_event_h

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

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


#ifdef __cplusplus
extern "C" {
#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);

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_()  */


/* Event_Claim ------------------------------------------------------------
 * 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_Claim(event_type eventtype,
                        window_handle window,  icon_handle icon,
                        event_handler handler, void *reference);


/* Event_Release ----------------------------------------------------------
 * 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 BOOL Event_Release(event_type event,
                          window_handle  window, icon_handle icon,
                          event_handler handler, void *reference);


/* Event_ReleaseWindow ----------------------------------------------------
 * 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_ReleaseWindow(window_handle window);



/* Event_Process ----------------------------------------------------------
 * 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_Process(event_pollblock *event);


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


/* Event_Initialise -------------------------------------------------------
 * 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_Initialise(char *taskname);


/* Event_Initialise3 ------------------------------------------------------
 * 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_Initialise3(char *taskname, int version, int *messages);


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

#ifdef __cplusplus
           }
#endif

#endif