event.txt 6.0 KB

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