diff -Nru libgda-5.0.4.orig/doc/C/data-model-writing.xml libgda-5.0.4/doc/C/data-model-writing.xml --- libgda-5.0.4.orig/doc/C/data-model-writing.xml 1970-01-01 01:00:00.000000000 +0100 +++ libgda-5.0.4/doc/C/data-model-writing.xml 2013-07-18 02:34:39.868134274 +0200 @@ -0,0 +1,199 @@ + +Libgda"> +]> + + Implementing your own data model + + 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. + + + Implementing a new GdaDataModel is simply a matter of + creating a new GObject which implements the GdaDataModel + 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 + GObject's documentation, or + online. + + + + Virtual methods + + The interface's methods which can and/or need to be implemented are defined below. + + + + i_get_n_rows() - optional + 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. + + + + i_get_n_columns() - required + This method, returns the total number of columns in the data model, or -1 if unknown. + + + + i_describe_column() - required + This method describes a column; it returns (without any ownership to the caller) a + GdaColumn for each existing column, or NULL otherwise. + + + + i_get_access_flags() - required + This method defines how the data model may be accessed (randomly, only using a cursor, ...) + + + + i_get_value_at() - required for random access + This method is used to access the contents of a data model, specifically + a GValue 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 gda_data_model_get_value_at() + for more information about the lifetime of the returned GValue. + + + + i_get_attributes_at() - optional + This method returns, for a (column,row) position in the data model, the attributes + of the adressed "cell". + + + + i_create_iter() - optional + This method can be implemented to create specific + GdaDataModelIter or to customize them. + + + + i_iter_at_row() - optional + 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). + + + + i_iter_next() - required for cursor based access + 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. + + + + i_iter_prev() - optional for cursor based access + 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. + + + + i_set_value_at() - optional + This method needs to be defined if the data model allows each value in a (column,row) position + to be modified individually. + + + + + i_iter_set_value() - optional + This method can be defined if a specific treatment is required when a modification made + to a GdaDataModelIter is propagated to the data model. + It should seldom, if ever, be necessary to implement it. + + + + i_set_values() - optional + This method needs to be defined if the data model allows modifications to be made for + one complete row at a time. See the + gda_data_model_set_values() method for + more information about the arguments + + + + i_append_values() - optional + 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 gda_data_model_append_values() for + more information. + + + + i_append_row() - optional + 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). + + + + i_remove_row() - optional + This method should be implemented if the data model needs to support row removal. + + + + i_find_row() - optional + 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. + + + + i_set_notify() - optional + This method should be implemented if the data model needs to honor the + gda_data_model_freeze() and + gda_data_model_thaw() methods. If + this method is not implemented, then these two methods will have no effect. + + + + + i_get_notify() - optional + This method should be implemented if the data model needs to honor the + gda_data_model_freeze() and + gda_data_model_thaw() methods. If + this method is not implemented, then these two methods will have no effect. + + + + i_send_hint() - optional + This method should be implemented if the data model needs to be able to treat + hints, see gda_data_model_send_hint() for + more information + + + + i_get_exceptions() - optional + 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 + gda_data_model_get_exceptions() method. + + + + + Signalling changes + + When the data model changes, it needs to signal its changes. However, only the changes from + the initial state need to be notified, in situations such as: + + a row which has already been accessed is modified or removed + the total number of rows changes, and that number has already been obtained and + was known (i.e. different than -1) + + + + To signal changes, one of the following methods has to be used: + + gda_data_model_row_inserted(): to be called after a row has been inserted + gda_data_model_row_updated(): to be called after a row has been updated + gda_data_model_row_removed(): to be called after a row has been removed + gda_data_model_reset(): to be called + when the data model has changed in a way it's not possible or desirable to signal all the changes + using any combination of the above methods (for example when the whole contents has changed, or + when the number and/or types of columns has changed) + + + + Moreover, when the data model's access flags have changed, the implementation should signal it by + emitting the "access-changed" signal. + + + diff -Nru libgda-5.0.4.orig/doc/C/migration3.xml libgda-5.0.4/doc/C/migration3.xml --- libgda-5.0.4.orig/doc/C/migration3.xml 1970-01-01 01:00:00.000000000 +0100 +++ libgda-5.0.4/doc/C/migration3.xml 2013-07-18 02:34:28.803238296 +0200 @@ -0,0 +1,40 @@ + +Libgda"> +]> + + Migration from 4.X versions + Overview + Version 5.0 of &LIBGDA; is a small evolution to adapt to the GTK3 environment; as such it is API + compatible with versions 4.0.x or 4.2.x. However there are some few behavioural changes explicited + below. + + + + GDA_TYPE_NULL + + Previous versions of &LIBGDA; represented SQL NULL values as a GValue completely filled + with zeros (i.e. of type G_TYPE_INVALID), and GDA_TYPE_NULL was thus equivalent to G_TYPE_INVALID. + + + This new version introduces a new specific type for the same GDA_TYPE_NULL (which means + GDA_TYPE_NULL no longer equals G_TYPE_INVALID). The most common sources of errors brought by this + change are: + + if you used g_value_init() on a + value of type GDA_TYPE_NULL, then you'll have to eight clear the value first, or replace + that call with a call to gda_value_reset_with_type() + the gda_g_type_from_string() function + now returns G_TYPE_INVALID if it does not know how to interpret the argument, so testing the return + value now also involves testing for the G_TYPE_INVALID value. + creating a GValue using g_new0() resulted + in a GDA_TYPE_NULL value, which is not longer the case; the value needs to be initialized + with a call to g_value_init() + testing for NULL values using G_IS_VALUE does not work anymore, you'll have to + replace them with GDA_VALUE_HOLDS_NULL() + + + + +