GdaDataProxy

## GdaDataProxy GdaDataProxy — Proxy to hold modifications for any GdaDataModel, and provides the GdaDataModel interface itself |

## Synopsis

                GdaDataProxy;
                GdaDataProxyClass;
                GdaDataProxyPrivate;
    GObject*    gda_data_proxy_new              (GdaDataModel *model);
    GdaDataModel* gda_data_proxy_get_proxied_model
                                                (GdaDataProxy *proxy);
    gint        gda_data_proxy_get_proxied_model_n_cols
                                                (GdaDataProxy *proxy);
    gint        gda_data_proxy_get_proxied_model_n_rows
                                                (GdaDataProxy *proxy);
    gboolean    gda_data_proxy_is_read_only     (GdaDataProxy *proxy);
    GSList*     gda_data_proxy_get_values       (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint *cols_index,
                                                 gint n_cols);
    guint       gda_data_proxy_get_value_attributes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col);
    void        gda_data_proxy_alter_value_attributes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col,
                                                 guint alter_flags);
    gint        gda_data_proxy_get_proxied_model_row
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row);
    void        gda_data_proxy_delete           (GdaDataProxy *proxy,
                                                 gint proxy_row);
    void        gda_data_proxy_undelete         (GdaDataProxy *proxy,
                                                 gint proxy_row);
    gboolean    gda_data_proxy_row_is_deleted   (GdaDataProxy *proxy,
                                                 gint proxy_row);
    gint        gda_data_proxy_find_row_from_values
                                                (GdaDataProxy *proxy,
                                                 GSList *values,
                                                 gint *cols_index);
    void        gda_data_proxy_cancel_row_changes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col);
    gboolean    gda_data_proxy_apply_row_changes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 GError **error);
    gboolean    gda_data_proxy_has_changed      (GdaDataProxy *proxy);
    gboolean    gda_data_proxy_row_has_changed  (GdaDataProxy *proxy,
                                                 gint proxy_row);
    gint        gda_data_proxy_get_n_new_rows   (GdaDataProxy *proxy);
    void        gda_data_proxy_set_sample_size  (GdaDataProxy *proxy,
                                                 gint sample_size);
    gint        gda_data_proxy_get_sample_size  (GdaDataProxy *proxy);
    void        gda_data_proxy_set_sample_start (GdaDataProxy *proxy,
                                                 gint sample_start);
    gint        gda_data_proxy_get_sample_start (GdaDataProxy *proxy);
    gint        gda_data_proxy_get_sample_end   (GdaDataProxy *proxy);
    gboolean    gda_data_proxy_apply_all_changes
                                                (GdaDataProxy *proxy,
                                                 GError **error);
    gboolean    gda_data_proxy_cancel_all_changes
                                                (GdaDataProxy *proxy);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaDataProxy

## Implemented Interfaces

GdaDataProxy implements GdaDataModel.

## Properties

      "autocommit"           gboolean              : Read / Write
      "model"                gpointer              : Read / Write / Construct Only
      "prepend-null-entry"   gboolean              : Read / Write

## Signal Prototypes

    "row-delete-changed"
                void        user_function      (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gboolean arg2,
                                                gpointer user_data);
    "sample-changed"
                void        user_function      (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gint arg2,
                                                gpointer user_data);
    "sample-size-changed"
                void        user_function      (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gpointer user_data);

## Description

This object stores modifications made to a GdaDataModel object which is proxied until asked to make the changes inside the GdaDataModel, it also filters the proxied data model to show only a sample (a defined number of continuous rows) of it.

Specifically, for a proxied data model having `nb_cols` columns and `nb_rows` rows, the GdaDataProxy object has the following attributes:

- `2 * nb_cols` columns:

  - the first (>= 0) `nb_cols` columns are the current values stored in the proxy (which correspond to the values of the proxied data model if the considered row has not been changed). The associated values are writable.

  - the last `nb_cols` columns are the values stored in the proxied data model, at column `col - nb_cols`

- a variable number of rows depending on the following attributes:

  - if the proxy is configured to have an empty row as the first row

  - if the proxy only displays parts of the proxied data model

  - if new rows have been added to the proxy

Note that unless explicitely mentionned, the columns are read-only.

## Details

### GdaDataProxy

    typedef struct _GdaDataProxy GdaDataProxy;

### GdaDataProxyClass

    typedef struct {
    	GdaObjectClass          parent_class;

    	void                 (* row_delete_changed)  (GdaDataProxy *proxy, gint row, gboolean to_be_deleted);
    	void                 (* sample_size_changed) (GdaDataProxy *proxy, gint sample_size);
    	void                 (* sample_changed)      (GdaDataProxy *proxy, gint sample_start, gint sample_end);
    } GdaDataProxyClass;

### GdaDataProxyPrivate

    typedef struct _GdaDataProxyPrivate GdaDataProxyPrivate;

### gda_data_proxy_new ()

    GObject*    gda_data_proxy_new              (GdaDataModel *model);

Creates a new proxy of type `type`

`model` : |
Returns : | a new GdaDataProxy object

### gda_data_proxy_get_proxied_model ()

    GdaDataModel* gda_data_proxy_get_proxied_model
                                                (GdaDataProxy *proxy);

Fetch the GdaDataModel which `proxy` does proxy

`proxy` : | a GdaDataProxy object
Returns : | the proxied data model

### gda_data_proxy_get_proxied_model_n_cols ()

    gint        gda_data_proxy_get_proxied_model_n_cols
                                                (GdaDataProxy *proxy);

Get the number of columns in the proxied data model

`proxy` : | a GdaDataProxy object
Returns : | the number of columns, or -1 if an error occured

### gda_data_proxy_get_proxied_model_n_rows ()

    gint        gda_data_proxy_get_proxied_model_n_rows
                                                (GdaDataProxy *proxy);

Get the number of rows in the proxied data model

`proxy` : | a GdaDataProxy object
Returns : | the number of rows, or -1 if an error occured

### gda_data_proxy_is_read_only ()

    gboolean    gda_data_proxy_is_read_only     (GdaDataProxy *proxy);

`proxy` : | a GdaDataProxy object
Returns : | TRUE if the proxied data model is itself read-only

### gda_data_proxy_get_values ()

    GSList*     gda_data_proxy_get_values       (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint *cols_index,
                                                 gint n_cols);

Retreive a whole list of values from the `proxy` store. This function calls `gda_data_proxy_get_value()` for each column index specified in `cols_index`, and generates a GSlist on the way.

`proxy` : | a GdaDataProxy object
`proxy_row` : | a proxy row
`cols_index` : |
`n_cols` : |
Returns : | a new list of values (the list must be freed, not the values), or `NULL` if an error occured

### gda_data_proxy_get_value_attributes ()

    guint       gda_data_proxy_get_value_attributes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col);

Get the attributes of the value stored at (proxy_row, col) in `proxy`, which is an ORed value of GdaValueAttribute flags

`proxy` : | a GdaDataProxy object
`proxy_row` : | a proxy row
`col` : | a valid proxy column
Returns : | the attribute

### gda_data_proxy_alter_value_attributes ()

    void        gda_data_proxy_alter_value_attributes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col,
                                                 guint alter_flags);

Alters the attributes of the value stored at (proxy_row, col) in `proxy`. the `alter_flags` can only contain the GDA_VALUE_ATTR_IS_NULL, GDA_VALUE_ATTR_IS_DEFAULT and GDA_VALUE_ATTR_IS_UNCHANGED flags (other flags are ignored).

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number
`col` : | a valid column number
`alter_flags` : | flags to alter the attributes

### gda_data_proxy_get_proxied_model_row ()

    gint        gda_data_proxy_get_proxied_model_row
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row);

Get the `proxy`'s proxied model row corresponding to `proxy_row`

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number
Returns : | the proxied model's row, or -1 if `proxy` row which only exists `proxy`

### gda_data_proxy_delete ()

    void        gda_data_proxy_delete           (GdaDataProxy *proxy,
                                                 gint proxy_row);

Marks the row `proxy_row` to be deleted

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number

### gda_data_proxy_undelete ()

    void        gda_data_proxy_undelete         (GdaDataProxy *proxy,
                                                 gint proxy_row);

Remove the "to be deleted" mark at the row `proxy_row`, if it existed.

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number

### gda_data_proxy_row_is_deleted ()

    gboolean    gda_data_proxy_row_is_deleted   (GdaDataProxy *proxy,
                                                 gint proxy_row);

Tells if the row number `proxy_row` is marked to be deleted.

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number
Returns : |

### gda_data_proxy_find_row_from_values ()

    gint        gda_data_proxy_find_row_from_values
                                                (GdaDataProxy *proxy,
                                                 GSList *values,
                                                 gint *cols_index);

Find the first row where all the values in `values` at the columns identified at `cols_index` match.

NOTE: the `cols_index` array MUST contain a column index for each value in `values`

`proxy` : | a GdaDataProxy object
`values` : | a list of GdaValue values
`cols_index` : | an array of gint containing the column number to match each value of `values`
Returns : | proxy row number if the row has been identified, or -1 otherwise

### gda_data_proxy_cancel_row_changes ()

    void        gda_data_proxy_cancel_row_changes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 gint col);

Resets data at the corresponding row and column. `row` and `col` can be <0 if all the corresponding rows and columns are to be resetted.

`proxy` : | a GdaDataProxy object
`proxy_row` : |
`col` : |

### gda_data_proxy_apply_row_changes ()

    gboolean    gda_data_proxy_apply_row_changes
                                                (GdaDataProxy *proxy,
                                                 gint proxy_row,
                                                 GError **error);

Commits the modified data in the proxy back into the GdaDataModel.

`proxy` : | a GdaDataProxy object
`proxy_row` : | the row number to commit
`error` : | place to store the error, or `NULL`
Returns : | TRUE if no error occured.

### gda_data_proxy_has_changed ()

    gboolean    gda_data_proxy_has_changed      (GdaDataProxy *proxy);

Tells if `proxy` contains any modifications not applied to the proxied data model.

`proxy` : | a GdaDataProxy object
Returns : | TRUE if there are some modifications in `proxy`

### gda_data_proxy_row_has_changed ()

    gboolean    gda_data_proxy_row_has_changed  (GdaDataProxy *proxy,
                                                 gint proxy_row);

Tells if the row number `proxy_row` has changed

`proxy` : | a GdaDataProxy object
`proxy_row` : | A proxy row number
Returns : |

### gda_data_proxy_get_n_new_rows ()

    gint        gda_data_proxy_get_n_new_rows   (GdaDataProxy *proxy);

Get the number of rows which have been added to `proxy` and which are not part of the proxied data model.

`proxy` : | a GdaDataProxy object
Returns : | the number of new rows

### gda_data_proxy_set_sample_size ()

    void        gda_data_proxy_set_sample_size  (GdaDataProxy *proxy,
                                                 gint sample_size);

Sets the size of each chunck of fata to display: the maximum number of rows which can be displayed at a time. The default value is arbitrary 300 as it is big enough to be able to display quite a lot of data, but small enough to avoid too much data displayed at the same time.

Note: the rows which have been added but not yet commited will always be displayed regardless of the current chunck of data, and the modified rows which are not visible when the displayed chunck of data changes are still held as modified rows.

To remove the chuncking of the data to display, simply pass `sample_size` the 0 value.

`proxy` : | a GdaDataProxy object
`sample_size` : | the requested size of a chunck, or 0

### gda_data_proxy_get_sample_size ()

    gint        gda_data_proxy_get_sample_size  (GdaDataProxy *proxy);

Get the size of each chunk of data displayed at a time.

`proxy` : | a GdaDataProxy object
Returns : | the chunck (or sample) size, or 0 if chunking is disabled.

### gda_data_proxy_set_sample_start ()

    void        gda_data_proxy_set_sample_start (GdaDataProxy *proxy,
                                                 gint sample_start);

Sets the number of the first row to be displayed.

`proxy` : | a GdaDataProxy object
`sample_start` : | the number of the first row to be displayed

### gda_data_proxy_get_sample_start ()

    gint        gda_data_proxy_get_sample_start (GdaDataProxy *proxy);

Get the row number of the first row to be displayed.

`proxy` : | a GdaDataProxy object
Returns : | the number of the first row being displayed.

### gda_data_proxy_get_sample_end ()

    gint        gda_data_proxy_get_sample_end   (GdaDataProxy *proxy);

Get the row number of the last row to be displayed.

`proxy` : | a GdaDataProxy object
Returns : | the number of the last row being displayed.

### gda_data_proxy_apply_all_changes ()

    gboolean    gda_data_proxy_apply_all_changes
                                                (GdaDataProxy *proxy,
                                                 GError **error);

Apply all the changes stored in the proxy to the proxied data model. The changes are done row after row, and if an error occurs, then it is possible that not all the changes to all the rows have been applied.

`proxy` : | a GdaDataProxy object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occured

### gda_data_proxy_cancel_all_changes ()

    gboolean    gda_data_proxy_cancel_all_changes
                                                (GdaDataProxy *proxy);

Cancel all the changes stored in the proxy (the `proxy` will be reset to its state as it was just after creation).

`proxy` : | a GdaDataProxy object
Returns : | TRUE if no error occured

## Properties

### The "`autocommit`" property

      "autocommit"           gboolean              : Read / Write

Default value: FALSE

### The "`model`" property

      "model"                gpointer              : Read / Write / Construct Only

### The "`prepend-null-entry`" property

      "prepend-null-entry"   gboolean              : Read / Write

Default value: FALSE

## Signals

### The "row-delete-changed" signal

    void        user_function                  (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gboolean arg2,
                                                gpointer user_data);

`gdadataproxy` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The "sample-changed" signal

    void        user_function                  (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gint arg2,
                                                gpointer user_data);

`gdadataproxy` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The "sample-size-changed" signal

    void        user_function                  (GdaDataProxy *gdadataproxy,
                                                gint arg1,
                                                gpointer user_data);

`gdadataproxy` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.