Extending the GNC-Event enumeration (QOF API Change?)

Neil Williams linux at codehelp.co.uk
Fri Feb 10 19:05:57 EST 2006


On Friday 10 February 2006 11:04 pm, Derek Atkins wrote:
> I need to extend the list of events in qof/gnc-event.h to add
> at least two new events (I'm not sure what to call them, yet).
> I'd rather get them into the QOF code now rather than need to
> figure out how to get them in later on when I find the time
> to rework the events in the register, etc.

Good idea and a very important point.

In general, there are no problems adding elements to the API. If there's no 
overlap or replacement of existing interfaces, it's simple.

As far as events are concerned, I'm unconvinced that QOF needs to know 
anything more about the event than:
1. This event is / is not different to the other events.
2. There is / is not a handler registered for this event.
3. That there are certain default events that it can use for it's own actions 
- qof_init() can set these up, once the change is in.

Quite what each event does, means or achieves beyond that is actually 
application-specific. i.e. QOF neither knows nor cares about why you need to 
handle 'container_member_added' differently to GNC_EVENT_CREATE. QOF should 
not have to know either. It just needs to have a "baseline" and it should 
allow any application to set as many event types as that application needs.

In that context, exposing the enum is prohibitively restrictive and it needs 
to be deprecated in libqof1 so that it can be replaced in libqof2.

> So what's the best way to go about this?  The events I'm
> going to want to get are to handle:
>
>   container_member_added
>   container_member_removed
>   container_member_changed
>
> Note that there's an ADD and REMOVE already, but these are currently
> used to handle the reshuffling of accounts in the account tree.  I
> want to specifically get events when a transaction is added to an
> account or removed from an account (or when a GncEntry is added or
> removed from an Invoice).

As far as gnc-event should be concerned, they are just different events. The 
identity or meaning of the event is of no concern to QOF, except that each 
event must be uniquely identifiable to be matched with the handler.

These might as well just be events 1 through 10 - but strings are easier to 
use in a hashtable.

> This way we can differentiate between changes made to an account via
> the Edit Account dialog and changes made to an account through the
> register.
>
> I guess the /biggest/ problem is that the event enumeration list
> is part of the QOF API and not very extensible.  :(

Scheduled for conversion when gnc-event.c becomes qofevent.c. I'm thinking of 
a similar method to qoflog - an internal hashtable.

Consider the enum deprecated. I'll implement a generic version that 
applications can use as they see fit.

> So, what do we do here?

I'll look at it further over the weekend but here's my first thoughts:

1. the enum can be retired for new code. I'll look at an arbitrary event_ID 
tag - much like a QofLogModule - that is simply a key to lookup a value 
because that is all QOF actually needs here. Like QofLogModule, a const 
gchar* may be the best type. Say, QofEventName - to reinforce the idea that 
this is not a strict set of types.
2. Support old code by setting the enum values as defaults in the table and 
implementing deprecated wrappers that do the conversion for us (via 
enum_as_string macros). The bit operators would not be necessary.
3. New code could use a new handler definition - using a const gchar* instead 
of GNCEngineEventType. Again, a deprecated wrapper takes care of backwards 
compatibility, maintaining support for the current API whilst still extending 
it.
4. It is the responsibility of the application to use the same string when 
registering as when calling. Any unregistered eventname (i.e. typo) would be 
equivalent to GNC_EVENT_NONE.

Old style handlers would be ignored if a new style event is passed (the 
enum_as_string macro would return NULL and the opposite conversion would 
return GNC_EVENT_NONE). Old style events would be converted to the enum value 
to maintain compatibility.

There may be hidden problems in this so don't take this as absolute - it's 
just my first thoughts before I turn in for the night. (As such, some parts 
may have suffered from me being tired!)

I'll look at it again in the morning - a test routine has become all the more 
important now.

-- 

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/20060210/e21840eb/attachment.bin


More information about the gnucash-devel mailing list