lib/event/event.txt

   1 = EVENTS =
   2
   3 The subsystem of events used in mc is based on fast binary trees engine.
   4
   5
   6 == Introduction ==
   7
   8 Subsystem of events is primarily designed to detach event source and event
   9 handler in source code level. For example, VFS module uses function to show
  10 messages, which is defined in the source code (not in the lib). In the lib,
  11 definition of this function will be difficult (because the function does
  12 a lot of calls of other functions from src). In this case, the transform
  13 of this function to event handler is needed, and the display messages process
  14 can be used as an event. Function as event handler should be registered
  15 at early stage of mc start. Later just call the event, absolutely without
  16 worrying whether the handler is tied to the event, and which function
  17 is an event handler now (in some situation, plugin will load and reassign
  18 this event handler to itself).
  19
  20
  21 === Usage ===
  22
  23 Events are applicable in any case. Sometimes it is hard to decide whether
  24 it should be a common function or it should be an event handler. The replacement
  25 of all functions used in keybindings process to event handler is good choice
  26 (or parts of the 'switch () {case:}' in keybindings handlers). All keybindings
  27 are described in lib/keybind.h.
  28
  29 The second argument to choose the solution (event handler or function) should be
  30 thought whether that transformation of function to the event handler is easy,
  31 the inverse process (handler to function) would be more difficult because
  32 one event can have multiple handlers and each handler may depend to another.
  33
  34 A third argument in the choice in favor of the event handlers can be a plug-ins
  35 (in future). In this case events is a way to give access to internal application
  36 resources without providing a low-level API. All plug-ins need is to know what and how
  37 call the event with proper structure type (#include "lib/event.h").
  38
  39
  40 == Structure ==
  41
  42 In general, the subsystem of events can be represented as following:
  43
  44    ------------------------------------            }
  45    |Group1        Group2   ...   GroupN|            }   Event groups (GTree)
  46    -------------------------------------           }
  47        |             |             |
  48       /|\           /|\           /|\
  49      / | \         / | ...       ... eventN        }
  50     /  |  \       /  ...                            }
  51    /   |   \      ...                                } Events by groups
  52    |   |    event3                                   } (GTree for any group)
  53    |   event2                                       }
  54    event1                                          }
  55    | | |  |
  56    f1f2...fN                                       } list of event handlers (GPtrArray for any event)
  57
  58
  59 This scheme allows to group events, and perform several handlers for one event.
  60
  61
  62 == Requirements for event handlers ==
  63
  64 The following function prototype is event handler:
  65
  66 gboolean mc_event_callback_func_t (
  67     const gchar *event_group,
  68     const gchar *event_name,
  69     gpointer init_data,
  70     gpointer event_data
  71 );
  72
  73 where:
  74  event_group:
  75     name of the group, where event was initiated
  76
  77  event_name:
  78     event name. event_name ans event_group uniquely identify an event.
  79     These parameters can be useful if event handler is tied to several events
  80     and the distinguish between different events (for example, function of logging)
  81     is required.
  82
  83  init_data:
  84     Arbitrary data, provided to the event handler.
  85     This data is provided by adding a handler to the event (the initialization data).
  86
  87  event_data:
  88     Data provided to the handler when the event occurred.
  89
  90 Handler should return TRUE to allow running all other handlers tied to this event;
  91 or FALSE if it is necessary to stop further processing of event (the remaining
  92 handlers are not called).
  93
  94 If one event will have multiple handlers, the order of execution is "Last added - first
  95 executed". This allows to override the standard event handlers (eg, in plug-ins).
  96
  97
  98 === Passing parameters to event handlers. Returning rezults ==
  99
 100 Due to the unification of the event handlers, there is no possibility to pass
 101 a certain number of parameters and get the results of execution. Pass of a single
 102 parameter (or get one result of an event handler) can be made as simple type casting
 103 for one variable when event is called. But this way isn't applicable if pass
 104 of several parameters (or get multiple return values) is required.
 105
 106 To solve this problem, you can pass the previously defined structure as universal
 107 pointer event_data. All structures used in the event handlers should be defined
 108 in the lib/event-types.h.
 109
 110 This way (the pass parameters as pointer to structure) has advantages and disadvantages.
 111
 112 Advantages:
 113  * any number of parameters and their types;
 114  * any number of return values and their types.
 115
 116 Disadvantages:
 117  * probability of error: call the event with the wrong structure. In this case,
 118    the handler will cast pointer to the structure on which it was designed.
 119    At this point funny bugs and very long debugging process (especially if segfault
 120    doesn't occur immediately) are possible;
 121  * in order for an event handler and the initiator of the event to "communicate"
 122    with each other, previously defined structures is needed.
 123
 124
 125 == Examples ==
 126
 127 === Logging ===
 128
 129 Consider the example of a temporary handler which simply logged the order
 130 of certain events (for example, to detect infinite loop).
 131
 132 Here event handler:
 133
 134 gboolean
 135 mc_temp_event_logger (const gchar *event_group, const gchar *event_name,
 136                       gpointer init_data, gpointer data)
 137 {
 138     (void) init_data;
 139     (void) data;
 140
 141     mc_log("Event: %s:%s",event_group,event_name);
 142     return TRUE;
 143 }
 144
 145 Add the following lines into src/event_init.c before "{NULL, NULL, NULL, NULL}" line
 146 as one record to the initialization structure.
 147
 148 {MCEVENT_GROUP_CORE, "clipboard_file_to_ext_clip", mc_temp_event_logger, NULL},
 149 {MCEVENT_GROUP_CORE, "clipboard_file_from_ext_clip", mc_temp_event_logger, NULL},
 150 {MCEVENT_GROUP_CORE, "clipboard_text_to_file", mc_temp_event_logger, NULL},
 151 {MCEVENT_GROUP_CORE, "clipboard_text_from_file", mc_temp_event_logger, NULL},
 152
 153 ...(there any other events which you want to monitor)...