QOF: Event: QOF event handlers.

QOF 0.7.5

Files | Macros | Typedefs | Functions
Event: QOF event handlers.
Query Object Framework

## Files
file | qofevent.h
| QOF event handling interface.

## Macros
#define | QOF_MAKE_EVENT(x) (1<<(x))
| Allow application-specific events to be created. More...
#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. More...

## Functions
gint | qof_event_register_handler (QofEventHandler handler, gpointer handler_data)
| Register a handler for events. More...
void | qof_event_unregister_handler (gint handler_id)
| Unregister an event handler. More...
void | qof_event_gen (QofEntity *entity, QofEventId event_type, gpointer event_data)
| Invoke all registered event handlers using the given arguments. More...
void | qof_event_suspend (void)
| Suspend all engine events. More...
void | qof_event_resume (void)

## Default events for backwards compatibility.
These defaults merely replicate previous behaviour, any process can define their own events. Note events 6, and 7 are "undefined" as of v0.6.3 for future libqof1 or libqof2 usage.
#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. More...
#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. More...
#define | QOF_EVENT__LAST QOF_MAKE_EVENT(QOF_EVENT_BASE-1)
#define | QOF_EVENT_ALL (0xff)

## Detailed Description

## Macro Definition Documentation

## ◆ QOF_EVENT_BASE

#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.

## ◆ QOF_EVENT_COMMIT

#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.

Since
  0.7.0

Definition at line 92 of file qofevent.h.

## ◆ QOF_EVENT_CREATE

#define QOF_EVENT_CREATE QOF_MAKE_EVENT(0)

an entity has been created.

Definition at line 71 of file qofevent.h.

## ◆ QOF_EVENT_DESTROY

#define QOF_EVENT_DESTROY QOF_MAKE_EVENT(2)

an entity is about to be destroyed.

Definition at line 81 of file qofevent.h.

## ◆ QOF_EVENT_MODIFY

#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.

## ◆ QOF_EVENT_NONE

#define QOF_EVENT_NONE (0)

init value - invalid.

Definition at line 69 of file qofevent.h.

## ◆ QOF_MAKE_EVENT

#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 Documentation

## ◆ QofEventHandler

typedef void(* QofEventHandler) (QofEntity *ent, QofEventId event_type, gpointer handler_data, gpointer event_data)

Handler invoked when an event is generated.

Parameters

  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.

## ◆ QofEventId

typedef gint QofEventId

Define the type of events allowed.

Definition at line 40 of file qofevent.h.

## Function Documentation

## ◆ qof_event_gen()

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:

- QOF_EVENT_DEFAULT_CREATE events should be generated after the object has been created and registered in the book.
- QOF_EVENT_DEFAULT_MODIFY events should be generated whenever any data member or submember (i.e., splits) is changed.

- QOF_EVENT_DEFAULT_DESTROY events should be called before the object has been destroyed or removed book.

  Any other events are entirely the concern of the application.

  Note
    QofEventHandler routines do NOT support generating events from a GUID and QofIdType - you must specify a genuine QofEntity.
  Parameters

    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 292 of file qofevent.c.

293 {
294 if (!entity)
295 return;
296
297 if (suspend_counter)
298 return;
299
300 qof_event_generate_internal (entity, event_id, event_data);
301 }

## ◆ qof_event_register_handler()

gint qof_event_register_handler | ( | QofEventHandler | handler,
|  | gpointer | handler_data
| ) |  |

Register a handler for events.

Parameters

  handler | handler to register
  handler_data | data provided when handler is invoked

Returns
  id identifying handler

Definition at line 108 of file qofevent.c.

109 {
110 HandlerInfo *hi;
111 gint handler_id;
112
113 ENTER ("(handler=%p, data=%p)", handler, user_data);
114
115 /* sanity check */
116 if (!handler)
117 {
118 PERR ("no handler specified");
119 return 0;
120 }
121
122 /* look for a free handler id */
123 handler_id = find_next_handler_id ();
124
125 /* Found one, add the handler */
126 hi = g_new0 (HandlerInfo, 1);
127
128 hi->handler = handler;
129 hi->user_data = user_data;
130 hi->handler_id = handler_id;
131
132 handlers = g_list_prepend (handlers, hi);
133 LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data,
134 handler_id);
135 return handler_id;
136 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
HandlerInfo
Definition: qofevent-p.h:31
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
HandlerInfo::handler
QofEventHandler handler
Definition: qofevent-p.h:36
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217

## ◆ qof_event_resume()

void qof_event_resume | ( | void |  | ) |

Resume engine event generation.

Definition at line 200 of file qofevent.c.

201 {
202 if (suspend_counter == 0)
203 {
204 PERR ("suspend counter underflow");
205 return;
206 }
207
208 suspend_counter--;
209 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183

## ◆ qof_event_suspend()

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 189 of file qofevent.c.

190 {
191 suspend_counter++;
192
193 if (suspend_counter == 0)
194 {
195 PERR ("suspend counter overflow");
196 }
197 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183

## ◆ qof_event_unregister_handler()

void qof_event_unregister_handler | ( | gint | handler_id | ) |

Unregister an event handler.

Parameters

  handler_id | the id of the handler to unregister

Definition at line 139 of file qofevent.c.

140 {
141 GList *node;
142
143 ENTER ("(handler_id=%d)", handler_id);
144 for (node = handlers; node; node = node->next)
145 {
146 HandlerInfo *hi = node->data;
147
148 if (hi->handler_id != handler_id)
149 continue;
150
151 /* Normally, we could actually remove the handler's node from the
152 list, but we may be unregistering the event handler as a result
153 of a generated event, such as GNC_EVENT_DESTROY. In that case,
154 we're in the middle of walking the GList and it is wrong to
155 modify the list. So, instead, we just NULL the handler. */
156 if (hi->handler)
157 LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
158 hi->handler, hi->user_data);
159 #ifndef QOF_DISABLE_DEPRECATED
160 if (hi->old_handler)
161 LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
162 hi->old_handler, hi->user_data);
163 #endif
164
165 /* safety -- clear the handler in case we're running events now */
166 hi->handler = NULL;
167 #ifndef QOF_DISABLE_DEPRECATED
168 hi->old_handler = NULL;
169 #endif
170
171 if (handler_run_level == 0)
172 {
173 handlers = g_list_remove_link (handlers, node);
174 g_list_free_1 (node);
175 g_free (hi);
176 }
177 else
178 {
179 pending_deletes++;
180 }
181
182 return;
183 }
184
185 PERR ("no such handler: %d", handler_id);
186 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
HandlerInfo
Definition: qofevent-p.h:31
LEAVE
#define LEAVE(format, args...)
Definition: qoflog.h:227
HandlerInfo::handler
QofEventHandler handler
Definition: qofevent-p.h:36
ENTER
#define ENTER(format, args...)
Definition: qoflog.h:217