## GnomeDbDataProxy

GnomeDbDataProxy — Proxy to hold modifications for any GnomeDbDataModel, and provides the GtkTreeModel interface

## Synopsis

                GnomeDbDataProxy;
    GType       gnome_db_data_proxy_get_type    (void);
    GObject*    gnome_db_data_proxy_new         (GnomeDbDataModel *model);
    gboolean    gnome_db_data_proxy_is_read_only
                                                (GnomeDbDataProxy *proxy);
    gint        gnome_db_data_proxy_get_n_rows  (GnomeDbDataProxy *proxy);
    gint        gnome_db_data_proxy_get_n_columns
                                                (GnomeDbDataProxy *proxy);
    gboolean    gnome_db_data_proxy_set_value   (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint col,
                                                 const GdaValue *value);
    const GdaValue* gnome_db_data_proxy_get_value
                                                (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint col);
    GSList*     gnome_db_data_proxy_get_values  (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint *cols_index,
                                                 gint n_cols);
    void        gnome_db_data_proxy_delete      (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);
    void        gnome_db_data_proxy_undelete    (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);
    void        gnome_db_data_proxy_append      (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);
    gboolean    gnome_db_data_proxy_get_iter_from_values
                                                (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 GSList *values,
                                                 gint *cols_index);
    GnomeDbDataModel* gnome_db_data_proxy_get_model
                                                (GnomeDbDataProxy *proxy);
    gboolean    gnome_db_data_proxy_has_been_modified
                                                (GnomeDbDataProxy *proxy);
    void        gnome_db_data_proxy_reset_all   (GnomeDbDataProxy *proxy);
    void        gnome_db_data_proxy_reset_value (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint col);
    gboolean    gnome_db_data_proxy_commit_all  (GnomeDbDataProxy *proxy,
                                                 GError **error);
    gboolean    gnome_db_data_proxy_commit_row  (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 GError **error);
    void        gnome_db_data_proxy_set_sample_size
                                                (GnomeDbDataProxy *proxy,
                                                 gint sample_size);
    gint        gnome_db_data_proxy_get_sample_size
                                                (GnomeDbDataProxy *proxy);
    void        gnome_db_data_proxy_set_sample_start
                                                (GnomeDbDataProxy *proxy,
                                                 gint sample_start);
    gint        gnome_db_data_proxy_get_sample_start
                                                (GnomeDbDataProxy *proxy);
    gint        gnome_db_data_proxy_get_sample_end
                                                (GnomeDbDataProxy *proxy);

## Object Hierarchy

      GObject
       +----GnomeDbBase
             +----GnomeDbDataProxy

## Implemented Interfaces

GnomeDbDataProxy implements GtkTreeModel.

## Properties

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

## Description

This object stores all the modifications made to a GnomeDbDataModel object until asked to make the changes inside the GnomeDbDataModel.

This object implements the GtkTreeModel interface (which makes it easy to display data contents in a GtkTreeView) through which the data values can be tested for modifications. The GtkTreeModel implementation has the following columns:

- PROXY_COL_MODEL_N_COLUMNS: gives the number of columns in the GnomeDbDataModel (for the un-modified data)

- PROXY_COL_MODEL_ROW: gives the number of rows in the GnomeDbDataModel (for the un-modified data)

- PROXY_COL_MODEL_POINTER: gives a pointer to the GnomeDbDataModel itself

- PROXY_COL_MODIFIED: TRUE if the row has been modified (compared to what's in the GnomeDbDataModel)

- PROXY_COL_TO_DELETE: TRUE if the row has been marked to be deleted

- 0 <= column < number of columns in the GnomeDbDataModel: the GdaValue for the column in the corresponding row

- number of columns in the GnomeDbDataModel <= column < 2*number of columns in the GnomeDbDataModel: the attributes of the value for the column in the corresponding row; the attribute is a guint value of OR'ed fields from the GnomeDbValueAttribute enumerated.

Note that only the PROXY_COL_TO_DELETE column and the columns corresponding to the GdaValue values are writable, and that all the columns can be read.

## Details

### GnomeDbDataProxy

    typedef struct _GnomeDbDataProxy GnomeDbDataProxy;

### gnome_db_data_proxy_get_type ()

    GType       gnome_db_data_proxy_get_type    (void);

Returns : |

### gnome_db_data_proxy_new ()

    GObject*    gnome_db_data_proxy_new         (GnomeDbDataModel *model);

Creates a new proxy of type `type`

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

### gnome_db_data_proxy_is_read_only ()

    gboolean    gnome_db_data_proxy_is_read_only
                                                (GnomeDbDataProxy *proxy);

`proxy` : | a GnomeDbDataProxy object
Returns : | TRUE if the data in `proxy` can't be modified

### gnome_db_data_proxy_get_n_rows ()

    gint        gnome_db_data_proxy_get_n_rows  (GnomeDbDataProxy *proxy);

Considering the data stored within `proxy`, get the number of rows.

`proxy` : | a GnomeDbDataProxy object
Returns : | the number of rows in the proxy's data

### gnome_db_data_proxy_get_n_columns ()

    gint        gnome_db_data_proxy_get_n_columns
                                                (GnomeDbDataProxy *proxy);

Considering the data stored within `proxy`, get the number of columns.

`proxy` : | a GnomeDbDataProxy object
Returns : | the number of columns in the data proxy

### gnome_db_data_proxy_set_value ()

    gboolean    gnome_db_data_proxy_set_value   (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint col,
                                                 const GdaValue *value);

Stores a value in the proxy.

`proxy` : | a GnomeDbDataProxy object
`iter` : |
`col` : |
`value` : | the value to store (gets copied)
Returns : | TRUE on succes

### gnome_db_data_proxy_get_value ()

    const GdaValue* gnome_db_data_proxy_get_value
                                                (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint col);

Retreive the value stored at the row pointed by `iter` and at the column `col`.

`proxy` : | a GnomeDbDataProxy object
`iter` : | a valid GtkTreeIter
`col` : |
Returns : | the GdaValue, or `NULL` on error

### gnome_db_data_proxy_get_values ()

    GSList*     gnome_db_data_proxy_get_values  (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 gint *cols_index,
                                                 gint n_cols);

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

`proxy` : | a GnomeDbDataProxy object
`iter` : | a valid GtkTreeIter
`cols_index` : |
`n_cols` : |
Returns : | a new list of values (the list must be freed, not the values), or `NULL` if an error occured

### gnome_db_data_proxy_delete ()

    void        gnome_db_data_proxy_delete      (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);

Marks the row pointerd by `iter` to be deleted

`proxy` : | a GnomeDbDataProxy object
`iter` : | A set GtkTreeIter

### gnome_db_data_proxy_undelete ()

    void        gnome_db_data_proxy_undelete    (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);

Remove the "to be deleted" mark the row pointerd by `iter`, if it existed.

`proxy` : | a GnomeDbDataProxy object
`iter` : | A set GtkTreeIter

### gnome_db_data_proxy_append ()

    void        gnome_db_data_proxy_append      (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter);

Appends a new row to the proxy.

`proxy` : | a GnomeDbDataProxy object
`iter` : | an unset GtkTreeIter to set to the appended row

### gnome_db_data_proxy_get_iter_from_values ()

    gboolean    gnome_db_data_proxy_get_iter_from_values
                                                (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 GSList *values,
                                                 gint *cols_index);

Sets `iter` to the first row where all the values in `values` at the columns identified at `cols_index` match. If the row can't be identified, then the contents of `iter` is not modified.

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

`proxy` : | a GnomeDbDataProxy object
`iter` : | an unset GtkTreeIter to set to the requested row
`values` : | a list of GdaValue values
`cols_index` : | an array of gint containing the column number to match each value of `values`
Returns : | TRUE if the row has been identified `iter` was set

### gnome_db_data_proxy_get_model ()

    GnomeDbDataModel* gnome_db_data_proxy_get_model
                                                (GnomeDbDataProxy *proxy);

Get the GnomeDbDataModel which holds the unmodified (reference) data of `proxy`

`proxy` : | a GnomeDbDataProxy object
Returns : | the GnomeDbDataModel

### gnome_db_data_proxy_has_been_modified ()

    gboolean    gnome_db_data_proxy_has_been_modified
                                                (GnomeDbDataProxy *proxy);

Tell if any modification has been made to the data, or if the data in `proxy` is the same as the one in the GnomeDbDataModel given when `proxy` was created

`proxy` : | a GnomeDbDataProxy object
Returns : | TRUE if some modifications have been made

### gnome_db_data_proxy_reset_all ()

    void        gnome_db_data_proxy_reset_all   (GnomeDbDataProxy *proxy);

Resets any modification made to `proxy`

`proxy` : | a GnomeDbDataProxy object

### gnome_db_data_proxy_reset_value ()

    void        gnome_db_data_proxy_reset_value (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 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 GnomeDbDataProxy object
`iter` : |
`col` : |

### gnome_db_data_proxy_commit_all ()

    gboolean    gnome_db_data_proxy_commit_all  (GnomeDbDataProxy *proxy,
                                                 GError **error);

Commits all the modified data in the proxy back into the GnomeDbDataModel. If an error occurs, then the data commiting stops, so some data might still need to be commited after that function returns FALSE.

`proxy` : | a GnomeDbDataProxy object
`error` : | place to store the error, or `NULL`
Returns : | TRUE if no error occured.

### gnome_db_data_proxy_commit_row ()

    gboolean    gnome_db_data_proxy_commit_row  (GnomeDbDataProxy *proxy,
                                                 GtkTreeIter *iter,
                                                 GError **error);

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

`proxy` : | a GnomeDbDataProxy object
`iter` : | the modified row to commit, stored as a GtkTreeIter, or `NULL`
`error` : | place to store the error, or `NULL`
Returns : | TRUE if no error occured.

### gnome_db_data_proxy_set_sample_size ()

    void        gnome_db_data_proxy_set_sample_size
                                                (GnomeDbDataProxy *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 GnomeDbDataProxy object
`sample_size` : | the requested size of a chunck, or 0

### gnome_db_data_proxy_get_sample_size ()

    gint        gnome_db_data_proxy_get_sample_size
                                                (GnomeDbDataProxy *proxy);

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

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

### gnome_db_data_proxy_set_sample_start ()

    void        gnome_db_data_proxy_set_sample_start
                                                (GnomeDbDataProxy *proxy,
                                                 gint sample_start);

Sets the number of the first row to be displayed.

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

### gnome_db_data_proxy_get_sample_start ()

    gint        gnome_db_data_proxy_get_sample_start
                                                (GnomeDbDataProxy *proxy);

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

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

### gnome_db_data_proxy_get_sample_end ()

    gint        gnome_db_data_proxy_get_sample_end
                                                (GnomeDbDataProxy *proxy);

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

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

## Property Details

### The "`autocommit`" property

      "autocommit"           gboolean              : Read / Write

Default value: FALSE

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

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

Default value: FALSE