QOF: Event: QOF event handlers.


Files
file	qofevent.h
	QOF event handling interface.
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.
#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)
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)

Define Documentation

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

Since:: 0.7.0

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 Documentation

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.

typedef gint QofEventId

Define the type of events allowed.

Definition at line 40 of file qofevent.h.

Function Documentation

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.

00293 {
00294     if (!entity)
00295         return;
00296 
00297     if (suspend_counter)
00298         return;
00299 
00300     qof_event_generate_internal (entity, event_id, event_data);
00301 }

gint qof_event_register_handler	(	QofEventHandler	handler,
		gpointer	handler_data
	)

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.

00109 {
00110     HandlerInfo *hi;
00111     gint handler_id;
00112 
00113     ENTER ("(handler=%p, data=%p)", handler, user_data);
00114 
00115     /* sanity check */
00116     if (!handler)
00117     {
00118         PERR ("no handler specified");
00119         return 0;
00120     }
00121 
00122     /* look for a free handler id */
00123     handler_id = find_next_handler_id ();
00124 
00125     /* Found one, add the handler */
00126     hi = g_new0 (HandlerInfo, 1);
00127 
00128     hi->handler = handler;
00129     hi->user_data = user_data;
00130     hi->handler_id = handler_id;
00131 
00132     handlers = g_list_prepend (handlers, hi);
00133     LEAVE ("(handler=%p, data=%p) handler_id=%d", handler, user_data,
00134         handler_id);
00135     return handler_id;
00136 }

void qof_event_resume ( void )

Resume engine event generation.

Definition at line 200 of file qofevent.c.

00201 {
00202     if (suspend_counter == 0)
00203     {
00204         PERR ("suspend counter underflow");
00205         return;
00206     }
00207 
00208     suspend_counter--;
00209 }

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.

00190 {
00191     suspend_counter++;
00192 
00193     if (suspend_counter == 0)
00194     {
00195         PERR ("suspend counter overflow");
00196     }
00197 }

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.

00140 {
00141     GList *node;
00142 
00143     ENTER ("(handler_id=%d)", handler_id);
00144     for (node = handlers; node; node = node->next)
00145     {
00146         HandlerInfo *hi = node->data;
00147 
00148         if (hi->handler_id != handler_id)
00149             continue;
00150 
00151         /* Normally, we could actually remove the handler's node from the
00152            list, but we may be unregistering the event handler as a result
00153            of a generated event, such as GNC_EVENT_DESTROY.  In that case,
00154            we're in the middle of walking the GList and it is wrong to
00155            modify the list. So, instead, we just NULL the handler. */
00156         if (hi->handler)
00157             LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
00158                 hi->handler, hi->user_data);
00159 #ifndef QOF_DISABLE_DEPRECATED
00160         if (hi->old_handler)
00161             LEAVE ("(handler_id=%d) handler=%p data=%p", handler_id,
00162                 hi->old_handler, hi->user_data);
00163 #endif
00164 
00165         /* safety -- clear the handler in case we're running events now */
00166         hi->handler = NULL;
00167 #ifndef QOF_DISABLE_DEPRECATED
00168         hi->old_handler = NULL;
00169 #endif
00170 
00171         if (handler_run_level == 0)
00172         {
00173             handlers = g_list_remove_link (handlers, node);
00174             g_list_free_1 (node);
00175             g_free (hi);
00176         }
00177         else
00178         {
00179             pending_deletes++;
00180         }
00181 
00182         return;
00183     }
00184 
00185     PERR ("no such handler: %d", handler_id);
00186 }

Event: QOF event handlers. [Query Object Framework]

Files

Default events for backwards compatibility.

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

Event: QOF event handlers.
[Query Object Framework]