Files | |
file | qofevent.h |
QOF event handling interface. | |
Defines | |
#define | QOF_MAKE_EVENT(x) (1<<(x)) |
Allow application-specific events to be created. | |
#define | QOF_EVENT_BASE 8 |
Typedefs | |
typedef gint | QofEventId |
typedef void(* | QofEventHandler )(QofEntity *ent, QofEventId event_type, gpointer handler_data, gpointer event_data) |
Handler invoked when an event is generated. | |
Functions | |
gint | qof_event_register_handler (QofEventHandler handler, gpointer handler_data) |
Register a handler for events. | |
void | qof_event_unregister_handler (gint handler_id) |
Unregister an event handler. | |
void | qof_event_gen (QofEntity *entity, QofEventId event_type, gpointer event_data) |
Invoke all registered event handlers using the given arguments. | |
void | qof_event_suspend (void) |
Suspend all engine events. | |
void | qof_event_resume (void) |
Default events for backwards compatibility. | |
These defaults merely replicate previous behaviour, any process can define their own events.
| |
#define | QOF_EVENT_NONE (0) |
#define | QOF_EVENT_CREATE QOF_MAKE_EVENT(0) |
#define | QOF_EVENT_MODIFY QOF_MAKE_EVENT(1) |
an entity is about to be modified. | |
#define | QOF_EVENT_DESTROY QOF_MAKE_EVENT(2) |
#define | QOF_EVENT_ADD QOF_MAKE_EVENT(3) |
#define | QOF_EVENT_REMOVE QOF_MAKE_EVENT(4) |
#define | QOF_EVENT_COMMIT QOF_MAKE_EVENT(5) |
an entity has been modified. | |
#define | QOF_EVENT__LAST QOF_MAKE_EVENT(QOF_EVENT_BASE-1) |
#define | QOF_EVENT_ALL (0xff) |
#define QOF_EVENT_BASE 8 |
Allow scope for more defaults in future. Additional event identifiers must be based on this when using QOF_MAKE_EVENT().
Definition at line 57 of file qofevent.h.
#define QOF_EVENT_COMMIT QOF_MAKE_EVENT(5) |
an entity has been modified.
Added for QofUndo so that the altered state of an entity can be stored to allow the change to be undone and then redone.
Definition at line 92 of file qofevent.h.
#define QOF_EVENT_CREATE QOF_MAKE_EVENT(0) |
an entity has been created.
Definition at line 71 of file qofevent.h.
#define QOF_EVENT_DESTROY QOF_MAKE_EVENT(2) |
an entity is about to be destroyed.
Definition at line 81 of file qofevent.h.
#define QOF_EVENT_MODIFY QOF_MAKE_EVENT(1) |
an entity is about to be modified.
In addition to previous usage, can used for QofUndo so that the original state of an entity can be stored before modification to allow the change to be undone and then redone.
Definition at line 79 of file qofevent.h.
#define QOF_EVENT_NONE (0) |
init value - invalid.
Definition at line 69 of file qofevent.h.
#define QOF_MAKE_EVENT | ( | x | ) | (1<<(x)) |
Allow application-specific events to be created.
Used together with QOF_EVENT_BASE to simplify creation of application events without interfering with any new events added within QOF.
#define APP_EVENT_A QOF_MAKE_EVENT(QOF_EVENT_BASE+0) #define APP_EVENT_B QOF_MAKE_EVENT(QOF_EVENT_BASE+1)
Definition at line 53 of file qofevent.h.
typedef void(* QofEventHandler)(QofEntity *ent, QofEventId event_type, gpointer handler_data, gpointer event_data) |
Handler invoked when an event is generated.
ent,: | Entity generating the event | |
event_type,: | The id of the event, including additional identifiers and the older defaults. | |
handler_data,: | data supplied when handler was registered. | |
event_data,: | data to be supplied when handler is invoked. |
Definition at line 104 of file qofevent.h.
typedef gint QofEventId |
Define the type of events allowed.
Definition at line 40 of file qofevent.h.
void qof_event_gen | ( | QofEntity * | entity, | |
QofEventId | event_type, | |||
gpointer | event_data | |||
) |
Invoke all registered event handlers using the given arguments.
Certain default events are used by QOF:
Any other events are entirely the concern of the application.
entity,: | the entity generating the event | |
event_type,: | the name of the event. | |
event_data,: | Data to be passed to the event handler just for this one event. Can be NULL. |
Definition at line 235 of file qofevent.c.
00236 { 00237 if (!entity) 00238 return; 00239 00240 if (suspend_counter) 00241 return; 00242 00243 qof_event_generate_internal (entity, event_id, event_data); 00244 }
gint qof_event_register_handler | ( | QofEventHandler | handler, | |
gpointer | handler_data | |||
) |
Register a handler for events.
handler,: | handler to register | |
handler_data,: | data provided when handler is invoked |
Definition at line 72 of file qofevent.c.
00073 { 00074 HandlerInfo *hi; 00075 gint handler_id; 00076 00077 ENTER ("(handler=%p, data=%p)", handler, user_data); 00078 00079 /* sanity check */ 00080 if (!handler) 00081 { 00082 PERR ("no handler specified"); 00083 return 0; 00084 } 00085 00086 /* look for a free handler id */ 00087 handler_id = find_next_handler_id (); 00088 00089 /* Found one, add the handler */ 00090 hi = g_new0 (HandlerInfo, 1); 00091 00092 hi->handler = handler; 00093 hi->user_data = user_data; 00094 hi->handler_id = handler_id; 00095 00096 handlers = g_list_prepend (handlers, hi); 00097 LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data, 00098 handler_id); 00099 return handler_id; 00100 }
void qof_event_resume | ( | void | ) |
Resume engine event generation.
Definition at line 156 of file qofevent.c.
00157 { 00158 if (suspend_counter == 0) 00159 { 00160 PERR ("suspend counter underflow"); 00161 return; 00162 } 00163 00164 suspend_counter--; 00165 }
void qof_event_suspend | ( | void | ) |
Suspend all engine events.
This function may be called multiple times. To resume event generation, an equal number of calls to qof_event_resume must be made.
Definition at line 145 of file qofevent.c.
00146 { 00147 suspend_counter++; 00148 00149 if (suspend_counter == 0) 00150 { 00151 PERR ("suspend counter overflow"); 00152 } 00153 }
void qof_event_unregister_handler | ( | gint | handler_id | ) |
Unregister an event handler.
handler_id,: | the id of the handler to unregister |
Definition at line 103 of file qofevent.c.
00104 { 00105 GList *node; 00106 00107 ENTER ("(handler_id=%d)", handler_id); 00108 for (node = handlers; node; node = node->next) 00109 { 00110 HandlerInfo *hi = node->data; 00111 00112 if (hi->handler_id != handler_id) 00113 continue; 00114 00115 /* Normally, we could actually remove the handler's node from the 00116 list, but we may be unregistering the event handler as a result 00117 of a generated event, such as GNC_EVENT_DESTROY. In that case, 00118 we're in the middle of walking the GList and it is wrong to 00119 modify the list. So, instead, we just NULL the handler. */ 00120 if (hi->handler) 00121 LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id, 00122 hi->handler, hi->user_data); 00123 00124 /* safety -- clear the handler in case we're running events now */ 00125 hi->handler = NULL; 00126 00127 if (handler_run_level == 0) 00128 { 00129 handlers = g_list_remove_link (handlers, node); 00130 g_list_free_1 (node); 00131 g_free (hi); 00132 } 00133 else 00134 { 00135 pending_deletes++; 00136 } 00137 00138 return; 00139 } 00140 00141 PERR ("no such handler: %d", handler_id); 00142 }