Outline of new qofevent support

[Neil Williams]

The changes focus on adding extra support for application-specific event names 
rather than changing the event mechanism itself.

1. The existing events are retained as defaults, initialised internally.
2. These default events remain available to all currently registered event 
handlers of type GNCEngineEventHandler which are now deprecated.
3. A new handler prototype is added: QofEventHandler:
typedef void(* QofEventHandler)(QofEntity *ent, QofEventNameConst event_type, 
gpointer user_data) where QofEventNameConst is a const gchar*. Only these new 
handlers will be able to see both default and added events. Although the 
added names will be available via a foreach, the events themselves cannot be 
passed to the deprecated handler so there is no point in trying to access the 
event names.
4. New events are added as simple strings using void 
qof_event_add_name ( QofEventNameConst new_event_name ) at any time prior to 
generating an event using that name.
5. Unless an event name is added, events generated using that name will not 
appear to handlers. (You'll get a PWARN in the qoflog output.)
6. Support for generating events using only the GUID and QofIdType is 
deprecated. Future event generation should always use the QofEntity (to 
ensure the GUID really does relate to the supplied QofIdType and to provide 
handlers with access to the QofCollection, QofInstance and QofBook for that 
entity).
7. Within new handlers, event names can be processed using a new callback 
prototype: typedef void(*QofEventNameCB )(QofEventNameConst name, gpointer 
user_data) using the function: void 
qof_event_name_foreach  ( QofEventNameCB func, gpointer user_data ). This 
replaces the switch(GNCEngineEventType) syntax of deprecated handlers.
8. GNC_EVENT_ALL is a no-op. It was not supported by gnc-event (it dropped 
through to the empty default case) and there appears little use for it now.
9. As with all other deprecated code in QOF, the functions have moved to 
deprecated.c, the declarations to deprecated.h. Both files will be removed 
when QOF moves to libqof2 (sometime after gnucash 2.0.0 is on full release).
10. Using the deprecated handlers puts messages in the qoflog output (when 
enabled) to that effect.
11. Any one HandlerInfo can only hold either one deprecated old handler or one 
new style QofEventHandler so unregistering a handler_id removes whichever 
handler was specified.
12. gnc_event_register_handler is now deprecated and pointed at 
qof_event_register_old_handler by a define in deprecated.h. Use 
qof_event_register_handler for new handlers.

Testing continues and then I'll make a QOF 0.6.2 release.

-- 

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20060220/99a246a7/attachment.bin