home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Event < prev    next >
Encoding:
Text File  |  1996-07-22  |  8.7 KB  |  245 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 Desk_Event_Initialise3
  17.              20 Mar 1995  - JPS Added veneers for global vars for use with DLLs
  18.              22 Jul 1996  - JPS Added Desk_Event_MessagesClaim and
  19.                                 Desk_Event_MessagesRelease.
  20. */
  21.  
  22.  
  23. #ifndef __Desk_Event_h
  24. #define __Desk_Event_h
  25.  
  26. #ifdef __cplusplus
  27.     extern "C" {
  28. #endif
  29.  
  30.  
  31. #ifndef __Desk_Core_h
  32.     #include "Desk.Core.h"
  33. #endif
  34.  
  35. #ifndef __Desk_Wimp_h
  36. #include "Desk.Wimp.h"
  37. #endif
  38.  
  39.  
  40.  
  41. /*  NOTES
  42.  *  =====
  43.  *
  44.  *  Event supplies a set of high-level functions for proper handling of WIMP
  45.  *  events.
  46.  *  It polls the WIMP for you, and then passes the resulting event to one of
  47.  *  your designated handler routines. Events are cascaded down through your
  48.  *  handlers until one of them returns Desk_bool_TRUE, indicating that the event has
  49.  *  been successfully dealt with. This allows you to have application-wide
  50.  *  defaults for certain event types, with occasional overrides of that
  51.  *  default for specific windows or icons.
  52.  *
  53.  *  Handlers can be registered for the following (priority-ordered) things:
  54.  *
  55.  *    Specific window, specific icon, specific event.
  56.  *    Specific window, specific icon, any event.
  57.  *    Specific window, any icon, specific event.
  58.  *    Specific window, any icon, any event.
  59.  *    Any window, specific event.
  60.  *    Any window, any event.
  61.  *
  62.  *  When an non window-related event occurs, the order is as follows:
  63.  *
  64.  *    Any window, specific event.
  65.  *    Any window, any event.
  66.  *
  67.  *  A set of default handlers is also provided (handlers.c): You can copy
  68.  *  the code for the handlers you need into your own program as a base event
  69.  *  handling system.
  70.  *
  71.  *  Any event which has no registered handlers will automatically be masked
  72.  *  out in subsequent Desk_Wimp_Polls. (Except for "Quit" messages)
  73.  *
  74.  *  NULL events are treated (slightly) specially compared to other events.
  75.  *  After registering handler(s) for NULL events they will be turned on.
  76.  *  (They will NOT be turned on if you request a handler for ALL events. To
  77.  *  enable NULL events, you must specifically register a handler for
  78.  *  Desk_event_NULL events.)
  79.  *  As a default, Desk_Wimp_Poll will be used, but functions are supplied for
  80.  *  you to set a minimum return time (as in Desk_Wimp_PollIdle) if NULL events
  81.  *  are wanted less frequently 
  82.  *  TWO options for NULL event handling are open to you:
  83.  *    Each NULL event is passed to ALL registered handlers,
  84.  *      (To allow you to do important things as often as possible)
  85.  *    Each handler gets one NULL event in turn, in a round-robin fashion.
  86.  *      (To allow you to multitask several "subtask" functions alongside
  87.  *       each other with ease)
  88.  */
  89.  
  90.  
  91.  
  92. typedef Desk_bool (*Desk_event_handler) ( Desk_event_pollblock *Desk_poll_block, void *reference);
  93. /* 
  94. User Desk_event_handler function. Return Desk_bool_TRUE if the event has been handled.
  95.  */
  96.  
  97.  
  98. /* JS 01 Apr 1995, 10 Apr 1995 */
  99. /* Added function veneers for globals which must be  */
  100. /* used if compiling for use with DeskLib DLLs.       */
  101.  
  102. #ifdef Desk__using_SDLS
  103.   extern Desk_event_pollmask  *Desk_Event__Ref_mask( void);
  104.   extern int             *Desk_Event__Ref_taskhandle( void);
  105.   extern unsigned int    *Desk_Event__Ref_wimpversion( void);
  106.   extern char            *Desk_Event__Ref_taskname( void);
  107.   extern Desk_event_pollblock *Desk_Event__Ref_lastevent( void);
  108. #endif
  109.  
  110. #if defined( Desk__using_SDLS) && !defined( Desk__making_Event)
  111.   #define Desk_Event_mask        (*Desk_Event__Ref_mask())
  112.   #define Desk_Event_taskhandle  (*Desk_Event__Ref_taskhandle())
  113.   #define Desk_Event_wimpversion (*Desk_Event__Ref_wimpversion())
  114.   #define Desk_Event_taskname    (Desk_Event__Ref_taskname())
  115.   #define Desk_Event_lastevent   (*Desk_Event__Ref_lastevent())
  116. #else
  117.   extern Desk_event_pollmask  Desk_Event_mask;         /* Mask used by Desk_event_ FNs for Desk_Wimp_Poll */
  118.   extern int             Desk_Event_taskhandle;   /* WIMP task-handle of this application  */
  119.   extern unsigned int    Desk_Event_wimpversion;  /* Wimp version number * 100             */
  120.   extern const char*     Desk_Event_taskname; /* Application name                      */
  121.   extern Desk_event_pollblock    Desk_Event_lastevent;    /* Last event received by Desk_event_()       */
  122. #endif
  123.  
  124.  
  125.  
  126. extern Desk_bool Desk_Event_Claim(Desk_event_type eventtype,
  127.                         Desk_window_handle window,  Desk_icon_handle icon,
  128.                         Desk_event_handler handler, void *reference);
  129. /*
  130.  * Call this function to claim an event. This attaches the given handler
  131.  * function to the given event for all future event processing.
  132.  *    eventtype should be Desk_event_ANY  - to handle all events, or
  133.  *              an event type        - to handle a specific event
  134.  *    window    should be Desk_event_ANY  - if not window-specific, or
  135.  *              a window handle      - to attach ONLY to that window
  136.  *    icon      should be Desk_event_ANY  - if not icon-specific, or
  137.  *              an icon handle       - to attach ONLY to that icon
  138.  *              (NOTE: if icon != Desk_event_ANY, window MUST be defined)
  139.  *
  140.  *    handler   is the address of your handler function
  141.  *    reference is a handle for any user-data you want passed to the
  142.  *              function whenever it is called.
  143.  */
  144.  
  145.  
  146. extern Desk_bool Desk_Event_Release(Desk_event_type event,
  147.                           Desk_window_handle  window, Desk_icon_handle icon,
  148.                           Desk_event_handler handler, void *reference);
  149. /*
  150.  * This will release your claim on an event, removing the given handler
  151.  * from further usage.
  152.  * The parameters passed in should be the same as those passed to 
  153.  * Desk_Event_Claim.
  154.  */
  155.  
  156.  
  157. extern void Desk_Event_ReleaseWindow(Desk_window_handle window);
  158. /*
  159.  * This is similar to Desk_Event_Release, but rather than delinking ONE handler
  160.  * it delinks ALL handlers attached to the given window. This should be done
  161.  * if you close/delete the window using low-level routines. (It is done
  162.  * automatically if you use Desk_Window_ calls to remove the window)
  163.  */
  164.  
  165.  
  166.  
  167. extern void Desk_Event_Process(Desk_event_pollblock *event);
  168. /*
  169.  * Call this to process a Desk_Wimp_Poll event. It will cascade the event down
  170.  * through the event-handler hierarchy until one of your event handlers
  171.  * returns Desk_bool_TRUE to indicate succesful handling of the message.
  172.  * NOTE that Desk_Event_Poll calls Desk_Wimp_Poll and Desk_Event_Process for you.
  173.  */
  174.  
  175.  
  176. extern void Desk_Event_Poll(void);
  177. /*
  178.  * Main event poll routine. Use as in:
  179.  * while (Desk_bool_TRUE)
  180.  *   Desk_Event_Poll();
  181.  */
  182.  
  183.  
  184. extern void Desk_Event_Initialise( const char *taskname);
  185. /*
  186.  * Call this once to initialise the Wimp and the event manager
  187.  * **** This call is obsolescent, and should only be used if you still need
  188.  *      RISC OS 2 compatability - see Desk_Event_InitialisePlus, below.
  189.  */
  190.  
  191.  
  192. extern void Desk_Event_Initialise3( const char *taskname, int version, const int *messages);
  193. /*
  194.  * Extended version of Desk_Event_Initialise which allows the wimp version
  195.  * number to be set and the list of acceptable messages to be passed
  196.  *
  197.  * This function should only be used for version numbers of 300 or greater
  198.  * (i.e. for tasks which will only run on RISC OS 3 or later versions).
  199.  */
  200.  
  201.  
  202. extern void Desk_Event_CloseDown(void);
  203. /*
  204.  * Call this to CloseDown (quit) the application
  205.  */
  206.  
  207.  
  208.  
  209.  
  210. typedef Desk_bool (*Desk_event_claimorreleasefn)( 
  211.         Desk_event_type    eventtype, 
  212.         Desk_window_handle    window, 
  213.         Desk_icon_handle    icon, 
  214.         Desk_event_handler    handler, 
  215.         void    *reference
  216.         );
  217. /*
  218. This is the function-type of the Desk_Event_Claim and Desk_Event_Release
  219. functions. Useful for writing functions which accept a pointer to either
  220. of these functions, in order to claim or release a set of events
  221. consistently
  222. */
  223.  
  224.  
  225. void    Desk_Event_MessagesClaim( Desk_event_handler handler, void* reference);
  226. /*
  227. Claims all message events - Desk_event_USERMESSAGE,
  228. Desk_event_USERMESSAGERECORDED, Desk_event_ACK.
  229.  
  230. Release with Desk_Event_MessagesRelease.
  231.  */
  232.  
  233. void    Desk_Event_MessagesRelease( Desk_event_handler handler, void* reference);
  234. /*
  235. Releases message events - see Desk_Event_MessagesClaim.
  236.  */
  237.  
  238.  
  239. #ifdef __cplusplus
  240. }
  241. #endif
  242.  
  243.  
  244. #endif
  245.