src/main/event.h

   1 #ifndef EL__MAIN_EVENT_H
   2 #define EL__MAIN_EVENT_H
   3
   4 #include <stdarg.h>
   5
   6 #define EVENT_NONE (-1)
   7
   8
   9 /* This enum is returned by each event hook and determines whether we should
  10  * go on in the chain or finish the event processing. You want to always
  11  * return EVENT_HOOK_STATUS_NEXT. */
  12 /* More about EVENT_HOOK_STATUS_LAST - it means the event will get stuck on YOU
  13  * and won't ever get to any other hooks queued behind you. This is usually not
  14  * what you want. When I have plugin doing X with some document being loaded,
  15  * and then script doing Y with it and finally some internal gadget doing some
  16  * final touching of the document (say, colors normalization or so, I'm pulling
  17  * this off my head), you definitively want all of them to happen, no matter if
  18  * they are all successful or all unsuccessful or part of them successful. The
  19  * only exceptions I can think of are:
  20  *
  21  * * I really messed something up. Ie. I somehow managed to destroy the
  22  * document I got on input, but at least I know I did. Others don't and they
  23  * will crash, and the document is of no use anyway. So let me be the last one.
  24  *
  25  * * I discarded the event. Say I'm children-protection plugin and the innocent
  26  * kid drove me (unintentionally, of course) to some adult site. So I catch
  27  * the appropriate event as long as I know it is bad, and discard it. No luck,
  28  * Jonny. Oh, wait, you are going to write *own* plugin...?!
  29  *
  30  * * I transformed the even to another one. Say user pressed a key and I'm the
  31  * keybinding hook. So I've found the key in my keybinding table, thus I catch
  32  * it, lazy_trigger (TODO) the appropriate specific event (ie. "quit") and of
  33  * course discard the original one.
  34  *
  35  * --pasky */
  36 enum evhook_status {
  37         EVENT_HOOK_STATUS_NEXT,
  38         EVENT_HOOK_STATUS_LAST,
  39 };
  40
  41 /* The event hook prototype. Abide. */
  42 typedef enum evhook_status (*event_hook_T)(va_list ap, void *data);
  43
  44 /* This is convenience macro for hooks. Not all hooks may use all of their
  45  * parameters, but they usually have to fetch all of them. This silences
  46  * compiler ranting about unused variables then. It is recommended to run this
  47  * upon all the parameters (in case some of the get unused in future) like:
  48  *
  49  * evhook_use_params(param1 && param2 && param3);
  50  *
  51  * The compiler is probably going to optimize it away anyway. */
  52 #define evhook_use_params(x) if (0 && (x)) ;
  53
  54
  55 /*** The life of events */
  56
  57 /* This registers an event of name @name, allocating an id number for it. */
  58 /* The function returns the id or negative number upon error. */
  59 int register_event(unsigned char *name);
  60
  61 /* This unregisters an event number @event, freeing the resources it
  62  * occupied, chain of associated hooks and unallocating the event id for
  63  * further recyclation. */
  64 int unregister_event(int event);
  65
  66 int register_event_hook(int id, event_hook_T callback, int priority, void *data);
  67
  68 void unregister_event_hook(int id, event_hook_T callback);
  69
  70
  71 /*** Interface for table driven event hooks maintainance */
  72
  73 struct event_hook_info {
  74         unsigned char *name;
  75         int priority;
  76         event_hook_T callback;
  77         void *data;
  78 };
  79
  80 #define NULL_EVENT_HOOK_INFO { NULL, 0, NULL, NULL }
  81
  82 void register_event_hooks(struct event_hook_info *hooks);
  83 void unregister_event_hooks(struct event_hook_info *hooks);
  84
  85 /*** The events resolver */
  86
  87 /* This looks up the events table and returns the event id associated
  88  * with a given event @name. The event id is guaranteed not to change
  89  * during the event lifetime (that is, between its registration and
  90  * unregistration), thus it may be cached intermediatelly. */
  91 /* It returns the event id on success or a negative number upon failure
  92  * (ie. there is no such event). */
  93 int get_event_id(unsigned char *name);
  94
  95 /* This looks up the events table and returns the name of a given event
  96  * @id. */
  97 /* It returns the event name on success (statically allocated, you are
  98  * not permitted to modify it) or NULL upon failure (ie. there is no
  99  * such event). */
 100 unsigned char *get_event_name(int id);
 101
 102 #define set_event_id(event, name)                       \
 103         do {                                            \
 104                 if (event == EVENT_NONE)                \
 105                         event = get_event_id(name);     \
 106         } while (0)
 107
 108
 109 /*** The events generator */
 110
 111 void trigger_event(int id, ...);
 112
 113 void trigger_event_name(unsigned char *name, ...);
 114
 115 /*** The very events subsystem itself */
 116
 117 void init_event(void);
 118
 119 void done_event(void);
 120
 121
 122 #endif