home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / Event < prev    next >
Encoding:
Text File  |  1993-07-13  |  7.0 KB  |  176 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Event.h
  12.     Author:  Copyright © 1992 Jason Williams (for code by John Winters)
  13.     Version: 1.01 (14 Jul 1993)
  14.     Purpose: High-level WIMP event dispatch to a hierarchy of user event
  15.              handling functions.
  16.     Mods:    14 July 1993 - Added Event_Initialise3
  17. */
  18.  
  19.  
  20. #ifndef __dl_event_h
  21. #define __dl_event_h
  22.  
  23. #ifndef __dl_core_h
  24. #include "Core.h"
  25. #endif
  26.  
  27. #ifndef __dl_wimp_h
  28. #include "Wimp.h"
  29. #endif
  30.  
  31.  
  32.  
  33. /*  NOTES
  34.  *  =====
  35.  *
  36.  *  Event supplies a set of high-level functions for proper handling of WIMP
  37.  *  events.
  38.  *  It polls the WIMP for you, and then passes the resulting event to one of
  39.  *  your designated handler routines. Events are cascaded down through your
  40.  *  handlers until one of them returns TRUE, indicating that the event has
  41.  *  been successfully dealt with. This allows you to have application-wide
  42.  *  defaults for certain event types, with occasional overrides of that
  43.  *  default for specific windows or icons.
  44.  *
  45.  *  Handlers can be registered for the following (priority-ordered) things:
  46.  *
  47.  *    Specific window, specific icon, specific event.
  48.  *    Specific window, specific icon, any event.
  49.  *    Specific window, any icon, specific event.
  50.  *    Specific window, any icon, any event.
  51.  *    Any window, specific event.
  52.  *    Any window, any event.
  53.  *
  54.  *  When an non window-related event occurs, the order is as follows:
  55.  *
  56.  *    Any window, specific event.
  57.  *    Any window, any event.
  58.  *
  59.  *  A set of default handlers is also provided (handlers.c): You can copy
  60.  *  the code for the handlers you need into your own program as a base event
  61.  *  handling system.
  62.  *
  63.  *  Any event which has no registered handlers will automatically be masked
  64.  *  out in subsequent Wimp_Polls. (Except for "Quit" messages)
  65.  *
  66.  *  NULL events are treated (slightly) specially compared to other events.
  67.  *  After registering handler(s) for NULL events they will be turned on.
  68.  *  (They will NOT be turned on if you request a handler for ALL events. To
  69.  *  enable NULL events, you must specifically register a handler for
  70.  *  event_NULL events.)
  71.  *  As a default, Wimp_Poll will be used, but functions are supplied for
  72.  *  you to set a minimum return time (as in Wimp_PollIdle) if NULL events
  73.  *  are wanted less frequently 
  74.  *  TWO options for NULL event handling are open to you:
  75.  *    Each NULL event is passed to ALL registered handlers,
  76.  *      (To allow you to do important things as often as possible)
  77.  *    Each handler gets one NULL event in turn, in a round-robin fashion.
  78.  *      (To allow you to multitask several "subtask" functions alongside
  79.  *       each other with ease)
  80.  */
  81.  
  82.  
  83.  
  84. /* user event_handler function */
  85. typedef BOOL (*event_handler) (event_pollblock *poll_block, void *reference);
  86.  
  87. extern event_pollmask event_mask;   /* Mask used by event_ FNs for Wimp_Poll */
  88. extern int event_taskhandle;        /* WIMP task-handle of this application  */
  89. extern unsigned int event_wimpversion;   /* Wimp version number * 100        */
  90. extern char event_taskname[40];          /* Application name                 */
  91. extern event_pollblock event_lastevent;  /* Last event received by event_()  */
  92.  
  93.  
  94. /* Event_Claim ------------------------------------------------------------
  95.  * Call this function to claim an event. This attaches the given handler
  96.  * function to the given event for all future event processing.
  97.  *    eventtype should be event_ANY  - to handle all events, or
  98.  *              an event type        - to handle a specific event
  99.  *    window    should be event_ANY  - if not window-specific, or
  100.  *              a window handle      - to attach ONLY to that window
  101.  *    icon      should be event_ANY  - if not icon-specific, or
  102.  *              an icon handle       - to attach ONLY to that icon
  103.  *              (NOTE: if icon != event_ANY, window MUST be defined)
  104.  *
  105.  *    handler   is the address of your handler function
  106.  *    reference is a handle for any user-data you want passed to the
  107.  *              function whenever it is called.
  108.  */
  109. extern BOOL Event_Claim(event_type eventtype,
  110.                         window_handle window,  icon_handle icon,
  111.                         event_handler handler, void *reference);
  112.  
  113.  
  114. /* Event_Release ----------------------------------------------------------
  115.  * This will release your claim on an event, removing the given handler
  116.  * from further usage.
  117.  * The parameters passed in should be the same as those passed to 
  118.  * Event_Claim.
  119.  */
  120. extern BOOL Event_Release(event_type event,
  121.                           window_handle  window, icon_handle icon,
  122.                           event_handler handler, void *reference);
  123.  
  124.  
  125. /* Event_ReleaseWindow ----------------------------------------------------
  126.  * This is similar to Event_Release, but rather than delinking ONE handler
  127.  * it delinks ALL handlers attached to the given window. This should be done
  128.  * if you close/delete the window using low-level routines. (It is done
  129.  * automatically if you use Window_ calls to remove the window)
  130.  */
  131. extern void Event_ReleaseWindow(window_handle window);
  132.  
  133.  
  134.  
  135. /* Event_Process ----------------------------------------------------------
  136.  * Call this to process a Wimp_Poll event. It will cascade the event down
  137.  * through the event-handler hierarchy until one of your event handlers
  138.  * returns TRUE to indicate succesful handling of the message.
  139.  * NOTE that Event_Poll calls Wimp_Poll and Event_Process for you.
  140.  */
  141. extern void Event_Process(event_pollblock *event);
  142.  
  143.  
  144. /* Event_Poll -------------------------------------------------------------
  145.  * Main event poll routine. Use as in:
  146.  * while (TRUE)
  147.  *   Event_Poll();
  148.  */
  149. extern void Event_Poll(void);
  150.  
  151.  
  152. /* Event_Initialise -------------------------------------------------------
  153.  * Call this once to initialise the Wimp and the event manager
  154.  * **** This call is obsolescent, and should only be used if you still need
  155.  *      RISC OS 2 compatability - see Event_InitialisePlus, below.
  156.  */
  157. extern void Event_Initialise(char *taskname);
  158.  
  159.  
  160. /* Event_Initialise3 ------------------------------------------------------
  161.  * Extended version of Event_Initialise which allows the wimp version
  162.  * number to be set and the list of acceptable messages to be passed
  163.  *
  164.  * This function should only be used for version numbers of 300 or greater
  165.  * (i.e. for tasks which will only run on RISC OS 3 or later versions).
  166.  */
  167. extern void Event_Initialise3(char *taskname, int version, int *messages);
  168.  
  169.  
  170. /* Event_CloseDown --------------------------------------------------------
  171.  * Call this to CloseDown (quit) the application
  172.  */
  173. extern void Event_CloseDown(void);
  174.  
  175. #endif
  176.