[Gnucash-changes] QOF_TYPE_CHOICE handlers
Neil Williams
codehelp at cvs.gnucash.org
Fri Aug 12 10:31:57 EDT 2005
Log Message:
-----------
QOF_TYPE_CHOICE handlers
Tags:
----
gnucash-gnome2-dev
Added Files:
-----------
gnucash/src/engine:
qofchoice.c
qofchoice.h
Revision Data
-------------
--- /dev/null
+++ src/engine/qofchoice.h
@@ -0,0 +1,151 @@
+/***************************************************************************
+ * qofchoice.h
+ *
+ * Thu Jul 7 12:25:24 2005
+ * Copyright 2005 Neil Williams
+ * linux at codehelp.co.uk
+ ****************************************************************************/
+/*
+ * 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 Library 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ */
+
+#ifndef _QOFCHOICE_H
+#define _QOFCHOICE_H
+
+/** @addtogroup Choice
+
+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.
+
+\verbatim
+{ FOO_PARAM, BAR_ID, (QofAccessFunc)qofFooGetBar, (QofSetterFunc)qofFooSetBar },
+\endverbatim
+
+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.
+
+-# ::QOF_TYPE_COLLECT - one to many entities all of only one type.
+ - Handles links between one object and a series of objects
+ that are \b all of the same type, e.g. a simple list.
+-# ::QOF_TYPE_CHOICE - one to a single entity of many possible types.
+ - Handles links between one object and a series of
+\b 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:
+\verbatim
+QOF_TYPE_CHOICE<QOF_X, QOF_Y, QOF_Z>
+\endverbatim
+It holds a single entity of type X, Y, or Z for the purposes of QOF
+or ::QSF. 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.
+
+-# Each ::QOF_TYPE_CHOICE parameter provides access to \b ONE entity of
+a pre-determined set of object types.
+-# The entity type within the choice can be determined at run time.
+-# Each entity can have a different *type* of entity to it's siblings,
+provided that it is one of the pre-determined object types.
+-# Objects declare themselves as containing choices and other objects
+can add themselves to the list of acceptable choices of suitable objects.
+-# QOF_TYPE_CHOICE is transparent - objects should retrieve the e_type of
+the received entity and handle the entity appropriately.
+-# 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.
+-# 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.
+-# 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.
+
+ @{
+*/
+
+/** @file qofchoice.h
+ @brief Linking one entity to a single entity of many possible types.
+ @author Copyright (c) 2005 Neil Williams <linux at codehelp.co.uk>
+*/
+#include "qofclass.h"
+#include "qofobject.h"
+
+/** \brief Identify an object as containing a choice. */
+#define QOF_TYPE_CHOICE "choice"
+
+/** \brief 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.
+
+ at param type Type of object/entity.
+
+ at return TRUE if one or more choice parameters has been
+registered using the object definition, otherwise FALSE.
+*/
+gboolean qof_object_is_choice(QofIdType type);
+
+/** \brief Set an object as using QOF_TYPE_CHOICE. */
+gboolean qof_choice_create(char* type);
+
+/** \brief Add the choices for this parameter to the object.
+
+ at param choice The choice object.
+ at param add The object to be added as an option.
+ at param param The parameter that will be used to get or set options.
+
+ at return FALSE if object is not a choice object or on error
+ otherwise TRUE.
+*/
+gboolean qof_choice_add_class(char* choice, char* add, char* param_name);
+
+/** \brief Return the list of all object types usable with this parameter.
+
+ at param type The choice object type.
+ at param param_name The name of the parameter that will be used to
+ get or set options.
+
+ at return 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.
+*/
+GList* qof_object_get_choices(QofIdType type, QofParam *param);
+
+/** \brief Is the choice valid for this param_name?
+
+ at param choice_obj The object containing the QOF_TYPE_CHOICE parameter.
+ at param param_name The name of a QOF_TYPE_CHOICE parameter in this object.
+ at param choice The QofIdType to look for in the list of choices.
+
+ at return TRUE if choice is found in the list of allowed choices for
+this parameter of this object. Otherwise, FALSE
+*/
+gboolean qof_choice_check(char* choice_obj, char *param_name, char* choice);
+
+
+/** @} */
+#endif /* _QOFCHOICE_H */
--- /dev/null
+++ src/engine/qofchoice.c
@@ -0,0 +1,109 @@
+/***************************************************************************
+ * qofchoice.c
+ *
+ * Thu Jul 7 12:24:30 2005
+ * Copyright 2005 Neil Williams
+ * linux at codehelp.co.uk
+ ****************************************************************************/
+/*
+ * 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 Library 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ */
+
+#include <glib.h>
+#include "qofchoice.h"
+
+static GHashTable *qof_choice_table = NULL;
+
+/* To initialise, call qof_choice_add_class in
+qof_object_register for the choice object. */
+static gboolean qof_choice_is_initialized(void)
+{
+ if(!qof_choice_table)
+ {
+ qof_choice_table = g_hash_table_new(g_str_hash, g_str_equal);
+ }
+ if(!qof_choice_table) { return FALSE; }
+ return TRUE;
+}
+
+gboolean qof_object_is_choice(QofIdType type)
+{
+ gpointer value, check;
+
+ value = NULL;
+ check = NULL;
+ g_return_val_if_fail(qof_choice_is_initialized(), FALSE);
+ g_return_val_if_fail(type != NULL, FALSE);
+ value = g_hash_table_lookup(qof_choice_table, type);
+ if((GHashTable*)value) { return TRUE; }
+ g_message("DEBUG: QOF_TYPE_CHOICE setup failed for %s\n", type);
+ return FALSE;
+}
+
+gboolean
+qof_choice_create(char* type)
+{
+ GHashTable *param_table;
+
+ g_return_val_if_fail(type != NULL, FALSE);
+ g_return_val_if_fail(qof_choice_is_initialized() == TRUE, FALSE);
+ param_table = g_hash_table_new(g_str_hash, g_str_equal);
+ g_hash_table_insert(qof_choice_table, type, param_table);
+ return TRUE;
+}
+
+gboolean qof_choice_add_class(char* select, char* option, char* param_name)
+{
+ GHashTable *param_table;
+ GList *option_list;
+
+ option_list = NULL;
+ param_table = NULL;
+ g_return_val_if_fail(select != NULL, FALSE);
+ g_return_val_if_fail(qof_object_is_choice(select), FALSE);
+ param_table = (GHashTable*)g_hash_table_lookup(qof_choice_table, select);
+ g_return_val_if_fail(param_table, FALSE);
+ option_list = (GList*)g_hash_table_lookup(param_table, param_name);
+ option_list = g_list_append(option_list, option);
+ g_hash_table_insert(param_table, param_name, option_list);
+ return TRUE;
+}
+
+GList* qof_object_get_choices(QofIdType type, QofParam *param)
+{
+ GList *choices;
+ GHashTable *param_table;
+
+ g_return_val_if_fail(type != NULL, NULL);
+ g_return_val_if_fail(qof_choice_is_initialized() == TRUE, FALSE);
+ choices = NULL;
+ param_table = g_hash_table_lookup(qof_choice_table, type);
+ choices = g_hash_table_lookup(param_table, param->param_name);
+ return choices;
+}
+
+gboolean qof_choice_check(char* choice_obj, char *param_name, char* choice )
+{
+ GList *choices, *result;
+ GHashTable *param_table;
+
+ choices = result = NULL;
+ g_return_val_if_fail(qof_object_is_choice(choice_obj), FALSE);
+ param_table = g_hash_table_lookup(qof_choice_table, choice_obj);
+ choices = g_hash_table_lookup(param_table, param_name);
+ result = g_list_find(choices, choice);
+ if(!result) { return FALSE; }
+ return TRUE;
+}
More information about the gnucash-changes
mailing list