[QOF-devel] Outline of new qofevent support

[Derek Atkins]

Quoting Neil Williams <linux at codehelp.co.uk>:

> On Tuesday 21 February 2006 5:07 am, Derek Atkins wrote:
>> Actually, I just thought of something..  I'd like to have events that
>> have both subject AND object..  Right now we just have a Subject +
>> Verb (QofEntity + QofEventId).  I'd like to add an object, too, so we
>> could have an event Subject + Verb + Object (QofEntity + QofEventId +
>> gpointer).
>
> OK. QOF can do that.

Well, QOF would need to be modified.. but yeah.. ;)

>> The generator and consumer of the QofEventId need to
>> agree on what the object of the event is.
>
> Absolutely. This would almost certainly mean a different QofEventId for each
> type of object used and expected. That can't be resolved by QOF, it needs to
> be stated in the docs and left to the user to ensure it actually happens that
> way.

Well, maybe.   It would mean defining that a particular QofEventId when
applied to a particular QofEntityId would (or would not) imply a particular
type of argument in the callback.  Nothing says that QOF_EVENT_FOO when
applied to QofTypeFoo implies an argument of X and when applied to a 
QofTypeBar
implies an argument of Y.

Admittedly, it would be nice to standardize, but in the grand scheme of
things it's just a contract between the event generator and the event
consumer.

> Do you actually want a gpointer or would a QofEntity be a better choice?

I don't know.  I think passing gpointer is more general..  However all
the uses I have in mind only require a QofEntity (actually a QofInstance).

>> Could we add a second set of APIs that parallel the existing set
>> that let me pass an extra object back to the event handler?
>
> ... object, rather than argument, yes?

*shrugs*   The Name is unimportant to me...

>> I'd propose:
>>
>>   typedef void (*QofEventHandlerWithArg)(QofEntity*, QofEventId, gpointer);
>
> WithArg infers non-objects being passed (like a GHashTable or GList, an
> arbitrary struct / iterator, some arbitrary const gchar* or other weird bits
> of memory) - was this your intention or would this be a better, clearer, name
> base?

Actually, yes, this was my intention -- it's closer to the way g_signal
works -- g_signal lets you pass any kind of arguments back to the caller.
Indeed, you can even define signals with MULTIPLE callback arguments!
So, leaving it as a gpointer leaves it a little closer to where we'll
get to be eventually with qof2.

> QofEventHandlerWithObject
>
> Your use case certainly centres on an item that is more of an Object 
> than some
> arbitrary argument.
>
> I prefer the idea of restricting it to objects - or more precisely, a
> QofEntity.

Why this restriction?

> Maybe even use QofEventHandlerWithEntity
>
>>   void qof_event_add_handler_with_arg(QofEventHandlerWithArg);
>
> qof_event_register_handler_with_object
> or qof_event_register_handler_with_entity
> and ditto below:
>
>>   void qof_event_del_handler_with_arg(QofEventHandlerWithArg);
>
> qof_event_unregister_handler_with_object
>
>>   void qof_event_with_arg(QofEntity*, QofEventId, gpointer);
>
> qof_event_gen_with_object ?
>
>> I admit this would be a LOT easier if QOF were based on gobject and we
>> used g_signal...  Mea Culpa.
>
> Issue postponed until closer to libqof2 which in turn is certainly after G2.
>
>> What do you think?
>
> Do you need this for QOF 0.6.2 (which otherwise could be released 
> tomorrow) or
> 0.6.3 which is a likely release in the first week of April (coinciding
> possibly with 1.9.3)? (i.e. as this is something you've just recently thought
> up, is the idea due to an immediate need, educated foresight or wishlist?)
>
> (I'd like QOF to have a 5-6 week release cycle during the life of gnucash
> 1.9.x and probably beyond during the life of libqof1. There are a lot of
> issues to resolve in libqof1 and I'm tackling them one at a time. I want each
> release to only have one new format added with it's old format being
> deprecated.)

I have an immediate use for it..  I'd like to set up an event handler that
gets called whenever we add a new transaction into a particular account..
The idea is that I can attach this handler to the A/R account and whenever
a new transaction appears (or changes) I can perform business-level processing
on the transaction.  For example, I can tell whether the transaction is tied
to an invoice/lot or not, and if not I can try to figure it out or maybe
ask the user for help...

So, yes, this is something I'd like to see in 0.6.2.

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available