refresh second pass

[James LewisMoss]

>>>>> On Thu, 30 Nov 2000 21:10:27 -0800, Dave Peticolas <dave@krondo.com> said:

 Dave> Here is a second pass at a refresh design and API. It's similar
 Dave> to the first, so I won't repost the intro or diagram. It has
 Dave> two major changes:

 Dave> 1. The CM API has been changed so that components specify which
 Dave>    entities they want to watch. Individual entities and whole
 Dave>    classes of entities may be watched. Watches are associated
 Dave>    with gui components, not with callbacks. This avoids having
 Dave>    tons of callbacks for each component.

 Dave>    Being able to register for classes of entities (i.e., you
 Dave>    watch all accounts) makes it easier to start simple and then
 Dave>    refine for efficiency later on.

 Dave>    The engine API is still very simple, but since there is only
 Dave>    going to be one component which listens to it right now (the
 Dave>    CM), it will be easy to change later on.


 Dave> 2. The terminology has been changed per Tyson Dowd's
 Dave>    suggestion.  Events & handlers are used instead of changes &
 Dave>    callbacks.

...

 Dave>  *
 Dave> * entity: the GUID of the entity generating the event
 Dave> * event_type: the type of event -- this should be one of the
 Dave> * GNCEngineEventType values, not a combination.
 Dave>  */
 Dave> void gnc_engine_generate_event (GUID *entity,
 Dave> GNCEngineEventType event_type);

This spot looks like the break between the two headers.  Correct?

 Dave>/* GNCComponentRefreshFunc
 Dave> * Handler invoked to inform the component that a refresh
 Dave> * may be needed.
 Dave>  *
 Dave> * changes: if NULL, the component should perform a refresh.
 Dave>  *
 Dave> * if non-NULL, changes is a GUID hash that maps
 Dave> * GUIDs to GNCEngineEventType bitmasks describing

...

 Dave> /* gnc_find_gui_component
 Dave> * Search for a component in the specified class.
 Dave>  *
 Dave> * component_class: the class to search for components in
 Dave> * find_cb: the handler used to search for the component
 Dave> * find_data: find_data passed to find_cb
 Dave>  *
 Dave> * Returns: user_data of found component, or NULL if none found
 Dave>  */
 Dave> gpointer gnc_find_gui_component (const char *component_class,
 Dave>                                  GNCComponentFindHandler
 Dave>                                  find_cb, gpointer find_data);

There can be multiple instances of a widget with COMPONENT_CLASS, but
only the first?/last?/one is returned here.  Maybe should return a
list?

 Dave> /* gnc_forall_gui_components
 Dave> * Invoke 'handler' for every component in the database.
 Dave>  *
 Dave> * handler: handler to invoke
 Dave> * iter_data: data passed to handler
 Dave>  */
 Dave> void gnc_forall_gui_components (GNCComponentHandler handler,
 Dave>                                 gpointer iter_data);

Maybe include a second arg here "const char *component_class" that if
non null would allow you to iterate over a particular component class?

Jim

-- 
@James LewisMoss <dres@debian.org>      |  Blessed Be!
@    http://jimdres.home.mindspring.com |  Linux is kewl!
@"Argue for your limitations and sure enough, they're yours." Bach