GnuCash  4.8a-132-gcdaeb421d+
Files | Macros
Choice and collect : One to many links.

Objects can be linked together one-to-one by simply using the name of the related object as the parameter type in the QofClass parameter list. More...

Files

file  qofchoice.h
 Linking one entity to other entities of many possible types.
 

Macros

#define QOF_MOD_CHOICE   "qof.choice"
 
gboolean qof_object_is_choice (QofIdTypeConst type)
 Does this object contain a choice parameter? More...
 
gboolean qof_choice_create (char *type)
 Set an object as using QOF_TYPE_CHOICE. More...
 
gboolean qof_choice_add_class (const char *choice, char *add, char *param_name)
 Add the choices for this parameter to the object. More...
 
GList * qof_object_get_choices (QofIdType type, QofParam *param)
 Return the list of all object types usable with this parameter. More...
 
gboolean qof_choice_check (const char *choice_obj, const char *param_name, const char *choice)
 Is the choice valid for this param_name? More...
 
#define QOF_TYPE_CHOICE   "choice"
 Identify an object as containing a choice. More...
 

Detailed Description

Objects can be linked together one-to-one by simply using the name of the related object as the parameter type in the QofClass parameter list.

{ FOO_PARAM, BAR_ID, (QofAccessFunc)qofFooGetBar, (QofSetterFunc)qofFooSetBar },

This is limited as each FOO entity can contain only one reference to a single BAR entity per parameter. Also, this parameter cannot be used to link to a similar object, OBJ. This requires "one to many" links.

There are two types of one-to-many links in QOF.

  1. QOF_TYPE_COLLECT - one to many entities all of only one type.
    • Handles links between one object and a series of objects that are all of the same type, e.g. a simple list.
  2. QOF_TYPE_CHOICE - one to a single entity of many possible types.
    • Handles links between one object and a series of dissimilar objects, one of each type.

Currently, there is no explicit way to support many-to-many links but existing methods can be combined to give approximately the same results.

A QOF_TYPE_CHOICE object is like a C++ template. QOF_TYPE_CHOICE doesn't really exist by itself:

QOF_TYPE_CHOICE<QOF_X, QOF_Y, QOF_Z>

It holds a single entity of type X, Y, or Z for the purposes of QOF. For querying the object it queries as if it's an X, Y, or Z.

Each choice type has it's own definition of the allowable objects - each of which need to be registered as normal. Objects can declare themselves to be one option of a particular choice. There is no requirement for any object to be either a choice or an option for a choice object.

  1. Each QOF_TYPE_CHOICE parameter provides access to ONE entity of a pre-determined set of object types.
  2. The entity type within the choice can be determined at run time.
  3. Each entity can have a different type of entity to it's siblings, provided that it is one of the pre-determined object types.
  4. Objects declare themselves as containing choices and other objects can add themselves to the list of acceptable choices of suitable objects.
  5. QOF_TYPE_CHOICE is transparent - objects should retrieve the e_type of the received entity and handle the entity appropriately.
  6. The number of different entity types that can be pre-determined for any one QOF_TYPE_CHOICE parameter is not fixed. You can have as many types as the QofAccessFunc and QofSetterFunc can handle.
  7. Any one parameter can only have one QOF type. You cannot have a parameter that is both QOF_TYPE_COLLECT and QOF_TYPE_CHOICE any more than you can have one parameter that is both ::QOF_TYPE_BOOLEAN and ::QOF_TYPE_NUMERIC.
  8. When setting references using QOF_TYPE_CHOICE, QOF passes a single entity to the QofSetterFunc and it is left to the function to determine how to handle that entity type. When retrieving references using QOF_TYPE_CHOICE, the object must return a single entity matching one of the choice types.

Macro Definition Documentation

◆ QOF_TYPE_CHOICE

#define QOF_TYPE_CHOICE   "choice"

Identify an object as containing a choice.

Note
Choice

Definition at line 108 of file qofchoice.h.

Function Documentation

◆ qof_choice_add_class()

gboolean qof_choice_add_class ( const char *  choice,
char *  add,
char *  param_name 
)

Add the choices for this parameter to the object.

Parameters
choiceThe choice object.
addThe object to be added as an option.
param_nameThe parameter that will be used to get or set options.
Returns
FALSE if object is not a choice object or on error otherwise TRUE.

Definition at line 78 of file qofchoice.cpp.

81 {
82  GHashTable *param_table;
83  GList *option_list;
84 
85  option_list = NULL;
86  param_table = NULL;
87  g_return_val_if_fail(select != NULL, FALSE);
88  g_return_val_if_fail(qof_object_is_choice(select), FALSE);
89  param_table = (GHashTable*)g_hash_table_lookup(qof_choice_table, select);
90  g_return_val_if_fail(param_table, FALSE);
91  option_list = (GList*)g_hash_table_lookup(param_table, param_name);
92  option_list = g_list_append(option_list, option);
93  g_hash_table_insert(param_table, param_name, option_list);
94  return TRUE;
95 }
gboolean qof_object_is_choice(QofIdTypeConst type)
Does this object contain a choice parameter?
Definition: qofchoice.cpp:48

◆ qof_choice_check()

gboolean qof_choice_check ( const char *  choice_obj,
const char *  param_name,
const char *  choice 
)

Is the choice valid for this param_name?

Parameters
choice_objThe object containing the QOF_TYPE_CHOICE parameter.
param_nameThe name of a QOF_TYPE_CHOICE parameter in this object.
choiceThe QofIdType to look for in the list of choices.
Returns
TRUE if choice is found in the list of allowed choices for this parameter of this object. Otherwise, FALSE

Definition at line 110 of file qofchoice.cpp.

113 {
114  GList *choices, *result;
115  GHashTable *param_table;
116 
117  choices = result = NULL;
118  g_return_val_if_fail(qof_object_is_choice(choice_obj), FALSE);
119  param_table = static_cast<GHashTable*>(g_hash_table_lookup(qof_choice_table, choice_obj));
120  choices = static_cast<GList*>(g_hash_table_lookup(param_table, param_name));
121  result = g_list_find(choices, choice);
122  if (!result)
123  {
124  return FALSE;
125  }
126  return TRUE;
127 }
gboolean qof_object_is_choice(QofIdTypeConst type)
Does this object contain a choice parameter?
Definition: qofchoice.cpp:48

◆ qof_choice_create()

gboolean qof_choice_create ( char *  type)

Set an object as using QOF_TYPE_CHOICE.

Definition at line 67 of file qofchoice.cpp.

68 {
69  GHashTable *param_table;
70 
71  g_return_val_if_fail(type != NULL, FALSE);
72  g_return_val_if_fail(qof_choice_is_initialized() == TRUE, FALSE);
73  param_table = g_hash_table_new(g_str_hash, g_str_equal);
74  g_hash_table_insert(qof_choice_table, type, param_table);
75  return TRUE;
76 }

◆ qof_object_get_choices()

GList* qof_object_get_choices ( QofIdType  type,
QofParam *  param 
)

Return the list of all object types usable with this parameter.

Parameters
typeThe choice object type.
paramThe name of the parameter that will be used to get or set options.
Returns
NULL on error or if no options exist for this parameter, otherwise a GList of all QofIdType object type(s) available via this choice object using this parameter.

Definition at line 97 of file qofchoice.cpp.

98 {
99  GList *choices;
100  GHashTable *param_table;
101 
102  g_return_val_if_fail(type != NULL, NULL);
103  g_return_val_if_fail(qof_choice_is_initialized() == TRUE, FALSE);
104  choices = NULL;
105  param_table = static_cast<GHashTable*>(g_hash_table_lookup(qof_choice_table, type));
106  choices = static_cast<GList*>(g_hash_table_lookup(param_table, param->param_name));
107  return choices;
108 }

◆ qof_object_is_choice()

gboolean qof_object_is_choice ( QofIdTypeConst  type)

Does this object contain a choice parameter?

Returns TRUE if any parameter in the object definition uses a choice of elements, whether or not those parameters contain any data.

Parameters
typeType of object/entity.
Returns
TRUE if one or more choice parameters has been registered using the object definition, otherwise FALSE.

Definition at line 48 of file qofchoice.cpp.

49 {
50  gpointer value = NULL;
51 
52  if (!qof_choice_is_initialized())
53  {
54  return FALSE;
55  }
56  g_return_val_if_fail(type != NULL, FALSE);
57  value = g_hash_table_lookup(qof_choice_table, type);
58  if ((GHashTable*)value)
59  {
60  return TRUE;
61  }
62  DEBUG (" QOF_TYPE_CHOICE setup failed for %s\n", type);
63  return FALSE;
64 }
#define DEBUG(format, args...)
Print a debugging message.
Definition: qoflog.h:264