GNOME.org
 

[libgda] Documentation corrections

commit b1563bfa26ac27cfbdfb72029ac10d06ead9cf35
Author: Vivien Malerba <malerba gnome-db org>
Date:   Wed Apr 4 19:47:11 2012 +0200

    Documentation corrections

 doc/C/data-model-writing.xml    |  166 +++++++++++++++++++++++++++++++++++++++
 doc/C/libgda-5.0-docs.sgml      |    1 +
 libgda-ui/gdaui-data-selector.c |    2 +-
 libgda/gda-data-model.c         |  102 +++++++-----------------
 libgda/gda-data-model.h         |    2 +
 5 files changed, 201 insertions(+), 72 deletions(-)
---
diff --git a/doc/C/data-model-writing.xml b/doc/C/data-model-writing.xml
new file mode 100644
index 0000000..193d4ad
--- /dev/null
+++ b/doc/C/data-model-writing.xml
@@ -0,0 +1,166 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd";[
+<!ENTITY LIBGDA          "<application>Libgda</application>">
+]>
+<sect1 id="gda-data-model-writing">
+  <title>Implementing your own data model</title>
+  <para>
+    You may need at some point to implement your own data model because the implementations in
+    &LIBGDA; don't suit your needs. This section is dedicated to explaining to you how this can be done.
+  </para>
+  <para>
+    Implementing a new <link linkend="GdaDataModel">GdaDataModel</link> is simply a matter of
+    creating a new GObject which implements the <link linkend="GdaDataModel">GdaDataModel</link>
+    interface, which is described below. Thos new class needs to inherit GObject, but needs not
+    be direct descendant of it. The way to subclass an object using GLib
+    is not covered in this documentation, for this matter reref to
+    <link linkend="howto-gobject-code">GObject's documentation</link>, or
+    <ulink url="http://developer.gnome.org/gobject/stable/howto-gobject.html";>online</ulink>.
+  </para>
+  <para>
+    The interface's methods which can and/or need to be implemented are defined below.
+  </para>
+
+  <sect2 id="i_get_n_rows">
+    <title>i_get_n_rows() - optional</title>
+    <para>This method, if implemented, returns the total number of rows in the data model, or -1 if
+    unknown. If it's not implemented, then it is assumed that -1 is returned in all cases.</para>
+  </sect2>
+
+  <sect2 id="i_get_n_columns">
+    <title>i_get_n_columns() - required</title>
+    <para>This method, returns the total number of columns in the data model, or -1 if unknown.</para>
+  </sect2>
+
+  <sect2 id="i_describe_column">
+    <title>i_describe_column() - required</title>
+    <para>This method describes a column; it returns (without any ownership to the caller) a
+    <link linkend="GdaColumn">GdaColumn</link> for each existing column, or NULL otherwise.</para>
+  </sect2>
+
+  <sect2 id="i_get_access_flags">
+    <title>i_get_access_flags() - required</title>
+    <para>This method defines how the data model may be accessed (randomly, only using a cursor, ...)</para>
+  </sect2>
+
+  <sect2 id="i_get_value_at">
+    <title>i_get_value_at() - required for random access</title>
+    <para>This method is used to access the contents of a data model, specifically
+    a <link linkend="GValue">GValue</link> is returned for each (column,row) position.
+    It must return NULL if the data model experienced an error for the specific (column,row)
+    position. See <link linkend="gda_data_model_get_value_at">gda_data_model_get_value_at()</link>
+    for more information about the lifetime of the returned GValue.</para>
+  </sect2>
+
+  <sect2 id="i_get_attributes_at">
+    <title>i_get_attributes_at() - optional</title>
+    <para>This method returns, for a (column,row) position in the data model, the attributes
+    of the adressed "cell".</para>
+  </sect2>
+
+  <sect2 id="i_create_iter">
+    <title>i_create_iter() - optional</title>
+    <para>This method can be implemented to create specific
+    <link linkend="GdaDataModelIter">GdaDataModelIter</link> or to customize them.</para>
+  </sect2>
+
+  <sect2 id="i_iter_at_row">
+    <title>i_iter_at_row() - optional</title>
+    <para>This method can be implemented if a specific implementation allows an iterator
+    to be moved quickly to a specific row (faster than iterating from row to row to the
+    requested row).</para>
+  </sect2>
+
+  <sect2 id="i_iter_next">
+    <title>i_iter_next() - required for cursor based access</title>
+    <para>This method is called to move an iterator to the next row; it's not necessary to
+    implement it if the data models supports random access.</para>
+  </sect2>
+
+  <sect2 id="i_iter_prev">
+    <title>i_iter_prev() - optional for cursor based access</title>
+    <para>This method is called to move an iterator to the previous row. It is only necessary to
+    implement it if the data model does not support random access and supports moving the
+    cursor backward.</para>
+  </sect2>
+
+  <sect2 id="i_set_value_at">
+    <title>i_set_value_at() - optional</title>
+    <para>This method needs to be defined if the data model allows each value in a (column,row) position
+    to be modified individually.
+    </para>
+  </sect2>
+
+  <sect2 id="i_iter_set_value">
+    <title>i_iter_set_value() - optional</title>
+    <para>This method can be defined if a specific treatment is required when a modification made
+    to a <link linkend="GdaDataModelIter">GdaDataModelIter</link> is propagated to the data model.
+    It should seldom, if ever, be necessary to implement it.</para>
+  </sect2>
+
+  <sect2 id="i_set_values">
+    <title>i_set_values() - optional</title>
+    <para>This method needs to be defined if the data model allows modifications to be made for
+    one complete row at a time. See the
+    <link linkend="gda_data_model_set_values">gda_data_model_set_values()</link> method for
+    more information about the arguments</para>
+  </sect2>
+
+  <sect2 id="i_append_values">
+    <title>i_append_values() - optional</title>
+    <para>This method can be implemented if the data model needs to support adding a row and defining the
+    values to be added in the same operation.
+    See <link linkend="gda_data_model_append_values">gda_data_model_append_values()</link> for
+    more information.</para>
+  </sect2>
+
+  <sect2 id="i_append_row">
+    <title>i_append_row() - optional</title>
+    <para>This method needs to be defined if the data model needs to support adding an empty row (i.e.
+    without any value specified in the new row).</para>
+  </sect2>
+
+  <sect2 id="i_remove_row">
+    <title>i_remove_row() - optional</title>
+    <para>This method should be implemented if the data model needs to support row removal.</para>
+  </sect2>
+
+  <sect2 id="i_find_row">
+    <title>i_find_row() - optional</title>
+    <para>This method can be implemented if the data model implements an indexing scheme which
+    allows it to find rows from values quickly than by analysing each row after another to
+    find the requested values.</para>
+  </sect2>
+
+  <sect2 id="i_set_notify">
+    <title>i_set_notify() - optional</title>
+    <para>This method should be implemented if the data model needs to honor the
+    <link linkend="gda_data_model_freeze">gda_data_model_freeze()</link> and
+    <link linkend="gda_data_model_thaw">gda_data_model_thaw()</link> methods. If
+    this method is not implemented, then these two methods will have no effect.
+    </para>
+  </sect2>
+
+  <sect2 id="i_get_notify">
+    <title>i_get_notify() - optional</title>
+    <para>This method should be implemented if the data model needs to honor the
+    <link linkend="gda_data_model_freeze">gda_data_model_freeze()</link> and
+    <link linkend="gda_data_model_thaw">gda_data_model_thaw()</link> methods. If
+    this method is not implemented, then these two methods will have no effect.</para>
+  </sect2>
+
+  <sect2 id="i_send_hint">
+    <title>i_send_hint() - optional</title>
+    <para>This method should be implemented if the data model needs to be able to treat
+    hints, see <link linkend="gda_data_model_send_hint">gda_data_model_send_hint()</link> for
+    more information</para>
+  </sect2>
+
+  <sect2 id="i_get_exceptions">
+    <title>i_get_exceptions() - optional</title>
+    <para>This method needs to be implemented if the data model keeps exceptions about the errors
+    it has encountered and may "export" these exceptions using the
+    <link linkend="gda_data_model_get_exceptions">gda_data_model_get_exceptions()</link> method.</para>
+  </sect2>
+</sect1>
diff --git a/doc/C/libgda-5.0-docs.sgml b/doc/C/libgda-5.0-docs.sgml
index 1cf92dc..c71d632 100644
--- a/doc/C/libgda-5.0-docs.sgml
+++ b/doc/C/libgda-5.0-docs.sgml
@@ -540,6 +540,7 @@
       <xi:include href="xml/gda-data-model-dir.xml"/>
       <xi:include href="xml/gda-data-proxy.xml"/>
       <xi:include href="xml/gda-data-comparator.xml"/>
+      <xi:include href="data-model-writing.xml"/>
     </chapter>
 
     <chapter id="trees">
diff --git a/libgda-ui/gdaui-data-selector.c b/libgda-ui/gdaui-data-selector.c
index 5dcaac4..ed1f172 100644
--- a/libgda-ui/gdaui-data-selector.c
+++ b/libgda-ui/gdaui-data-selector.c
@@ -87,7 +87,7 @@ gdaui_data_selector_iface_init (G_GNUC_UNUSED gpointer g_class)
  *
  * Queries the #GdaDataModel from which the data displayed by the widget implementing @iface
  * are. Beware that the returned data model may be different than the one used when the
- * widget was created in case it uses a #GdaDataProxy.
+ * widget was created in case it internally uses a #GdaDataProxy.
  *
  * Returns: (transfer none): the #GdaDataModel
  *
diff --git a/libgda/gda-data-model.c b/libgda/gda-data-model.c
index 843a983..5ed4544 100644
--- a/libgda/gda-data-model.c
+++ b/libgda/gda-data-model.c
@@ -377,8 +377,6 @@ gda_data_model_freeze (GdaDataModel *model)
 	
 	if (GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify)
 		(GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify) (model, FALSE);
-	else
-		g_warning ("%s() method not supported\n", __FUNCTION__);
 }
 
 /**
@@ -394,8 +392,6 @@ gda_data_model_thaw (GdaDataModel *model)
 
 	if (GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify)
 		(GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify) (model, TRUE);
-	else
-		g_warning ("%s() method not supported\n", __FUNCTION__);
 }
 
 /**
@@ -405,8 +401,7 @@ gda_data_model_thaw (GdaDataModel *model)
  *
  * Enable or disable notifications changes on the given data model.
  * 
- * Note: This function must be implemented but is recommended to use #gda_data_model_thaw
- * and #gda_data_model_freeze functions instead.
+ * Deprecated: 5.2: use gda_data_model_freeze() and gda_data_model_thaw() instead
  *
  * Virtual: i_set_notify
  */
@@ -416,10 +411,6 @@ gda_data_model_set_notify (GdaDataModel *model, gboolean do_notify_changes)
 	g_return_if_fail (GDA_IS_DATA_MODEL (model));
 	if (GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify)
 		(GDA_DATA_MODEL_GET_CLASS (model)->i_set_notify) (model, do_notify_changes);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-	}
 }
 
 /**
@@ -428,9 +419,6 @@ gda_data_model_set_notify (GdaDataModel *model, gboolean do_notify_changes)
  *
  * Returns the status of notifications changes on the given data model.
  * 
- * Note: This function must be implemented but is recommended to use #gda_data_model_thaw
- * and #gda_data_model_freeze functions instead.
- *
  * Virtual: i_get_notify
  */
 gboolean
@@ -439,11 +427,8 @@ gda_data_model_get_notify (GdaDataModel *model)
 	g_return_val_if_fail (GDA_IS_DATA_MODEL (model), FALSE);
 	if (GDA_DATA_MODEL_GET_CLASS (model)->i_get_notify)
 		return (GDA_DATA_MODEL_GET_CLASS (model)->i_get_notify) (model);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-		return FALSE;
-	}
+	else
+		return TRUE;
 }
 
 
@@ -494,7 +479,7 @@ gda_data_model_get_n_rows (GdaDataModel *model)
  * gda_data_model_get_n_columns:
  * @model: a #GdaDataModel object.
  *
- * Returns: the number of columns in the given data model.
+ * Returns: the number of columns in the given data model, or -1 if unknown.
  *
  * Virtual: i_get_n_columns
  */
@@ -507,7 +492,6 @@ gda_data_model_get_n_columns (GdaDataModel *model)
 		return (GDA_DATA_MODEL_GET_CLASS (model)->i_get_n_columns) (model);
 	else {
 		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
 		return -1;
 	}
 }
@@ -525,7 +509,7 @@ gda_data_model_get_n_columns (GdaDataModel *model)
  * WARNING: the returned #GdaColumn object belongs to the @model model and
  * and should not be destroyed; any modification will affect the whole data model.
  *
- * Returns: (transfer none): the description of the column.
+ * Returns: (transfer none) (allow-none): the description of the column.
  *
  * Virtual: i_describe_column
  */
@@ -538,7 +522,6 @@ gda_data_model_describe_column (GdaDataModel *model, gint col)
 		return (GDA_DATA_MODEL_GET_CLASS (model)->i_describe_column) (model, col);
 	else {
 		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
 		return NULL;
 	}
 }
@@ -950,8 +933,7 @@ gda_data_model_create_iter (GdaDataModel *model)
  *
  * Moves @iter to the row number given by @row.
  * 
- * Note: This function must be implemented but is recommended to use #GdaDataModelIter 
- * object directly.
+ * Deprecated: 5.2: use gda_data_model_iter_move_to_row() instead
  *
  * Virtual: i_iter_at_row
  */
@@ -960,13 +942,8 @@ gda_data_model_iter_at_row (GdaDataModel *model, GdaDataModelIter *iter, gint ro
 {
 	g_return_val_if_fail (GDA_IS_DATA_MODEL (model), FALSE);
 	g_return_val_if_fail (GDA_IS_DATA_MODEL_ITER (model), FALSE);
-	if (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_at_row)
-		return (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_at_row) (model, iter, row);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-		return FALSE;
-	}
+
+	return gda_data_model_iter_move_to_row (iter, row);
 }
 
 /**
@@ -976,8 +953,7 @@ gda_data_model_iter_at_row (GdaDataModel *model, GdaDataModelIter *iter, gint ro
  *
  * Moves @iter to the next row in @model.
  * 
- * Note: This function must be implemented but is recommended to use #GdaDataModelIter 
- * object directly.
+ * Deprecated: 5.2: use gda_data_model_iter_move_next() instead
  *
  * Virtual: i_iter_next
  */
@@ -986,72 +962,56 @@ gda_data_model_iter_next (GdaDataModel *model, GdaDataModelIter *iter)
 {
 	g_return_val_if_fail (GDA_IS_DATA_MODEL (model), FALSE);
 	g_return_val_if_fail (GDA_IS_DATA_MODEL_ITER (model), FALSE);
-	if (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_next)
-		return (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_next) (model, iter);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-		return FALSE;
-	}
+
+	return gda_data_model_iter_move_next (iter);
 }
 
 /**
- * gda_data_model_iter_set_value:
+ * gda_data_model_iter_prev:
  * @model: a #GdaDataModel object.
  * @iter: a #GdaDataModelIter object.
- * @col: the number of column to set value to
- * @value: the to use to set on
- * @error: a place to set errors
  *
- * Set @value to the given @column and row pointed by @iter in the given @model.
- * 
- * Note: This function must be implemented but is recommended to use #GdaDataModelIter 
- * object directly.
+ * Moves @iter to the next row in @model.
  *
- * Virtual: i_iter_set_value
+ * Deprecated: 5.2: use gda_data_model_iter_move_prev() instead
+ * 
+ * Virtual: i_iter_prev
  */
 gboolean 
-gda_data_model_iter_set_value (GdaDataModel *model, GdaDataModelIter *iter, gint col,
-						       const GValue *value, GError **error)
+gda_data_model_iter_prev (GdaDataModel *model, GdaDataModelIter *iter)
 {
 	g_return_val_if_fail (GDA_IS_DATA_MODEL (model), FALSE);
 	g_return_val_if_fail (GDA_IS_DATA_MODEL_ITER (model), FALSE);
-	if (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_set_value)
-		return (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_set_value) (model, iter, col, value, error);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-		return FALSE;
-	}
+
+	return gda_data_model_iter_move_prev (iter);
 }
 
 
 /**
- * gda_data_model_iter_prev:
+ * gda_data_model_iter_set_value:
  * @model: a #GdaDataModel object.
  * @iter: a #GdaDataModelIter object.
+ * @col: the number of column to set value to
+ * @value: the to use to set on
+ * @error: a place to set errors
  *
- * Moves @iter to the next row in @model.
+ * Set @value to the given @column and row pointed by @iter in the given @model.
  * 
- * Note: This function must be implemented but is recommended to use #GdaDataModelIter 
- * object directly.
+ * Deprecated: 5.2: use gda_data_model_iter_set_value_at() instead
  *
- * Virtual: i_iter_prev
+ * Virtual: i_iter_set_value
  */
 gboolean 
-gda_data_model_iter_prev (GdaDataModel *model, GdaDataModelIter *iter)
+gda_data_model_iter_set_value (GdaDataModel *model, GdaDataModelIter *iter, gint col,
+			       const GValue *value, GError **error)
 {
 	g_return_val_if_fail (GDA_IS_DATA_MODEL (model), FALSE);
 	g_return_val_if_fail (GDA_IS_DATA_MODEL_ITER (model), FALSE);
-	if (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_prev)
-		return (GDA_DATA_MODEL_GET_CLASS (model)->i_iter_prev) (model, iter);
-	else {
-		/* method not supported */
-		g_warning ("%s() method not supported\n", __FUNCTION__);
-		return FALSE;
-	}
+	
+	return gda_data_model_iter_set_value_at (iter, col, value, error);
 }
 
+
 /**
  * gda_data_model_append_values:
  * @model: a #GdaDataModel object.
diff --git a/libgda/gda-data-model.h b/libgda/gda-data-model.h
index 2235cb7..422c725 100644
--- a/libgda/gda-data-model.h
+++ b/libgda/gda-data-model.h
@@ -165,6 +165,8 @@ struct _GdaDataModelIface {
  *     <listitem><para>The #GdaDataAccessWrapper data model which offers a memory efficient random access on top of a
  * 	wrapped cursor based access data model</para></listitem>
  * </itemizedlist>
+ *
+ * Also see the section about <link linkend="gda-data-model-writing">writing your own GdaDataModel</link>
  */
 
 GType               gda_data_model_get_type               (void) G_GNUC_CONST;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]