/usr/include/gnucash/gnc-component-manager.h is in gnucash-common 1:2.6.12-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 | /********************************************************************\
* gnc-component-manager.h - GUI component manager interface *
* Copyright (C) 2000 Dave Peticolas <dave@krondo.com> *
* *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
* the License, or (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License*
* along with this program; if not, write to the Free Software *
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *
\********************************************************************/
#ifndef GNC_COMPONENT_MANAGER_H
#define GNC_COMPONENT_MANAGER_H
#include <glib.h>
#include "qof.h"
#define NO_COMPONENT (-1)
typedef struct
{
QofEventId event_mask;
} EventInfo;
/* GNCComponentRefreshHandler
* Handler invoked to inform the component that a refresh
* may be needed.
*
* changes: if NULL, the component should perform a refresh.
*
* if non-NULL, changes is a GncGUID hash that maps
* GUIDs to EventInfo structs describing which
* events have been received. Entities not in
* the hash have not generated any events.
* Entities which have been destroyed will be in
* the hash, but may not exist anymore.
*
* Note since refreshes may not occur with every change,
* an entity may have all three change values.
*
* The component should use 'changes' to determine whether
* or not a refresh is needed. The hash table must not be
* changed.
*
* Notes on refreshing: when the handler is invoked any engine
* entities used by the component may have
* already been deleted. 'Refreshing' the
* component may require closing the component.
*
* Notes on dealing with destroyed entities: As stated above, entities
* in the changes GHashTable may no longer exist. So how can you
* determine if this has happened? Well, it's a good idea to check
* for the QOF_EVENT_DESTROY bit in the EventInfo structure. Of
* course, that means you need the hash key (GncGUID) for the destroyed
* entity. How are you going to get the GncGUID from the entity if the
* entity has already been destroyed? You're not. So, you have to
* save a COPY of the key (GncGUID) away beforehand.
*
* user_data: user_data supplied when component was registered.
*/
typedef void (*GNCComponentRefreshHandler) (GHashTable *changes,
gpointer user_data);
/* GNCComponentCloseHandler
* Handler invoked to close the component.
*
* user_data: user_data supplied when component was registered.
*
* Notes on closing: components are not automatically unregistered
* when the close handler is invoked. Components
* may not ignore the handler.
*/
typedef void (*GNCComponentCloseHandler) (gpointer user_data);
/* GNCComponentFindHandler
* Handler invoked when searching for a component.
*
* find_data: find_data supplied when search was started.
* user_data: user_data supplied when component was registered.
*
* Return: TRUE if the component matches the search criteria.
*/
typedef gboolean (*GNCComponentFindHandler) (gpointer find_data,
gpointer user_data);
/* GNCComponentHandler
* Generic handler used in iterating over components.
*
* component_class: class of component
* component_id: id of component
* iter_data: user_data supplied by caller
*
* Return: TRUE if the callback did something
*/
typedef gboolean (*GNCComponentHandler) (const char *component_class,
gint component_id,
gpointer user_data,
gpointer iter_data);
/* gnc_component_manager_init
* Initialize the component manager.
*/
void gnc_component_manager_init (void);
/* gnc_component_manager_shutdown
* Shutdown the component manager.
*/
void gnc_component_manager_shutdown (void);
/* gnc_register_gui_component
* Register a GUI component with the manager.
*
* component_class: a string defining a class of components
* certain component functions can be performed
* on all components in a class. For that reason,
* components in the same class should all use
* the same type for user_data.
*
* refresh_cb: refresh handler, may be NULL
* close_cb: close handler, may be NULL
* user_data: user_data argument for handlers
*
*
* Notes: After a refresh handler is registered, the
* component must use the API calls below to
* inform the component manager which engine
* entities are being 'watched', i.e., which
* engine entities may cause the component
* to need refreshing.
*
* When a component is first registered, it
* is not watching anything, and thus will
* not receive refresh events.
*
* Return: id of component, or NO_COMPONENT, if error
*/
gint gnc_register_gui_component (const char *component_class,
GNCComponentRefreshHandler refresh_handler,
GNCComponentCloseHandler close_handler,
gpointer user_data);
/* gnc_gui_component_set_session
* Set the associated session of this component
*
* component_id: id of component which is watching the entity
* session: the session this component is associated with
*/
void gnc_gui_component_set_session (gint component_id, gpointer session);
/* gnc_gui_component_watch_entity
* Add an entity to the list of those being watched by the component.
* Only entities with refresh handlers should add watches.
*
* component_id: id of component which is watching the entity
* entity: id of entity to watch
* event_mask: mask which determines which kinds of events are watched
* setting the mask to 0 turns off watching for the entity.
*/
void gnc_gui_component_watch_entity (gint component_id,
const GncGUID *entity,
QofEventId event_mask);
/* gnc_gui_component_watch_entity_type
* Watch all entities of a particular type.
*
* component_id: id of component which is watching the entity type
* entity_type: type of entity to watch, either GNC_ID_TRANS or
* GNC_ID_ACCOUNT
* event_mask: mask which determines which kinds of events are watched
* setting the mask to 0 turns off watching for the entity type
*/
void gnc_gui_component_watch_entity_type (gint component_id,
QofIdTypeConst entity_type,
QofEventId event_mask);
/* gnc_gui_get_entity_events
* Return the event info of the events which have been generated by
* the given entity.
*
* changes: a hash of changes as in the refresh handler
* entity: the GncGUID of the entity to get the event mask for
*
* Returns: the event info of the entity, or NULL
* if it is not found.
*/
const EventInfo * gnc_gui_get_entity_events (GHashTable *changes,
const GncGUID *entity);
/* gnc_gui_component_clear_watches
* Clear all watches for the component.
*
* component_id: id of component to clear watches for.
*/
void gnc_gui_component_clear_watches (gint component_id);
/* gnc_unregister_gui_component
* Unregister a gui component from the manager.
*
* component_id: id of component to unregister
*/
void gnc_unregister_gui_component (gint component_id);
/* gnc_unregister_gui_component_by_data
* Unregister a gui component using the user_data pointer.
*
* component_class: class component is in
* user_data: user_data pointer of component to unregister
* all components with that user_data in the
* class are unregistered.
*/
void gnc_unregister_gui_component_by_data (const char *component_class,
gpointer user_data);
/* gnc_suspend_gui_refresh
* Suspend refresh handlers by the component manager.
* This routine may be called multiple times. Each call
* increases the suspend counter (starts at zero).
*/
void gnc_suspend_gui_refresh (void);
/* gnc_resume_gui_refresh
* Resume refresh handlers by the component manager.
* Each call reduces the suspend counter by one. When
* the counter reaches zero, all changes which have
* occured since the last refresh are collected and
* passed to the components in refresh handlers.
*/
void gnc_resume_gui_refresh (void);
/* gnc_gui_refresh_all
* Force all components to refresh.
*
* This routine may only be invoked when the suspend counter
* is zero. It should never be mixed with the suspend/resume
* refresh routines.
*/
void gnc_gui_refresh_all (void);
/* gnc_gui_refresh_suspended
* Return TRUE if gui refreshes are suspended.
*/
gboolean gnc_gui_refresh_suspended (void);
/* gnc_close_gui_component
* Invoke the close handler for the indicated component.
*
* component_id: id of component to close
*/
void gnc_close_gui_component (gint component_id);
/* gnc_close_gui_component_by_data
* Invoke the close handler for components in the given
* class with the given user_data.
*
* component_class: class to close components in
* user_data: user_data of component to close
* all components with that user_data
* are closed.
*/
void gnc_close_gui_component_by_data (const char *component_class,
gpointer user_data);
/* gnc_close_gui_component_by_session
* Invoke the close handler for components with the given session
*
* session: session to close
* all components with that session
* are closed.
*/
void gnc_close_gui_component_by_session (gpointer session);
/* gnc_find_gui_components
* Search for components in the specified class.
*
* component_class: the class to search for components in
* must be non-NULL
* find_cb: the handler used to search for the component
* if NULL, all components in class are returned
* find_data: find_data passed to find_cb
*
* Returns: GList of user_data of found components, or NULL if none found
* The list should be freed with g_list_free().
*
* Notes on finding: components should not be registered or unregistered
* by the find callback.
*/
GList * gnc_find_gui_components (const char *component_class,
GNCComponentFindHandler find_handler,
gpointer find_data);
/* gnc_find_first_gui_component
* Search for the first matching component in the specified class.
*
* component_class: the class to search for components in
* must be non-NULL
* find_cb: the handler used to search for the component
* must be non-null
* find_data: find_data passed to find_cb
*
* Returns: user_data of first found component, or NULL if none found
*
* Notes on finding: components should not be registered or unregistered
* by the find callback.
*/
gpointer gnc_find_first_gui_component (const char *component_class,
GNCComponentFindHandler find_handler,
gpointer find_data);
/* gnc_forall_gui_components
* Invoke 'handler' for components in the database.
*
* component_class: class to iterate over, if NULL then
* all classes are iterated over
* handler: handler to invoke
* iter_data: data passed to handler
*
* Notes on forall: components may be unregistered by the handler,
* but no components should be registered.
*/
gint gnc_forall_gui_components (const char *component_class,
GNCComponentHandler handler,
gpointer iter_data);
#endif
|