## GnomeDbDataWidget GnomeDbDataWidget — Interface to control data bound widgets |

## Synopsis

                        GnomeDbDataWidget;
    enum                GnomeDbDataWidgetWriteMode;
    GdaDataProxy*       gnome_db_data_widget_get_proxy      (GnomeDbDataWidget *iface);
    GtkActionGroup*     gnome_db_data_widget_get_actions_group
                                                            (GnomeDbDataWidget *iface);
    void                gnome_db_data_widget_perform_action (GnomeDbDataWidget *iface,
                                                             GnomeDbAction action);
    void                gnome_db_data_widget_column_show    (GnomeDbDataWidget *iface,
                                                             gint column);
    void                gnome_db_data_widget_column_hide    (GnomeDbDataWidget *iface,
                                                             gint column);
    void                gnome_db_data_widget_column_set_editable
                                                            (GnomeDbDataWidget *iface,
                                                             gint column,
                                                             gboolean editable);
    void                gnome_db_data_widget_column_show_actions
                                                            (GnomeDbDataWidget *iface,
                                                             gint column,
                                                             gboolean show_actions);

    GdaDataModelIter*   gnome_db_data_widget_get_current_data
                                                            (GnomeDbDataWidget *iface);
    GdaDataModel*       gnome_db_data_widget_get_gda_model  (GnomeDbDataWidget *iface);
    void                gnome_db_data_widget_set_gda_model  (GnomeDbDataWidget *iface,
                                                             GdaDataModel *model);
    gboolean            gnome_db_data_widget_set_write_mode (GnomeDbDataWidget *iface,
                                                             GnomeDbDataWidgetWriteMode mode);
    GnomeDbDataWidgetWriteMode gnome_db_data_widget_get_write_mode
                                                            (GnomeDbDataWidget *iface);

## Object Hierarchy

      GInterface
       +----GnomeDbDataWidget

## Prerequisites

GnomeDbDataWidget requires GObject.

## Known Implementations

GnomeDbDataWidget is implemented by GnomeDbRawForm and GnomeDbRawGrid.

## Signals

      "iter-changed"                                   : Run First
      "proxy-changed"                                  : Run First

## Description

The GnomeDbDataWidget is a common interface implemented by some data bound widgets which have the following in common:

- The data to display in the widget is contained in a GdaDataModel object (a "source" of data)

- If the "source" GdaDataModel allows it, modifications can be made (modifying existing rows, adding new rows, or removing some rows). Those modifications are internally stored in a GdaDataProxy object. (note that a GdaDataProxy object is always created, except if the "source" data model is itself a GdaDataProxy object)

- The widget also internally uses a GdaDataModelIter object which represents the current "selected" row (the selected row, or the one displayed).

- Writing back the modifications stored in the GdaDataProxy to the "source" data model is by default done only when requested, but can be specified otherwise (see `gnome_db_data_widget_set_write_mode()`)

## Details

### GnomeDbDataWidget

    typedef struct _GnomeDbDataWidget GnomeDbDataWidget;

### enum GnomeDbDataWidgetWriteMode

    typedef enum {
    	GNOME_DB_DATA_WIDGET_WRITE_ON_DEMAND           = 0, /* write only when explicitely requested */
    	GNOME_DB_DATA_WIDGET_WRITE_ON_ROW_CHANGE       = 1, /* write when the current selected row changes */
    	GNOME_DB_DATA_WIDGET_WRITE_ON_VALUE_ACTIVATED  = 2, /* write when user activates a value change */
    	GNOME_DB_DATA_WIDGET_WRITE_ON_VALUE_CHANGE     = 3  /* write when a parameters's value changes */
    } GnomeDbDataWidgetWriteMode;

Determines how modified data (stored in the GdaDataProxy object used internally by each GnomeDbDataWidget) is written back to the GdaDataModel which contains data to be displayed.

`GNOME_DB_DATA_WIDGET_WRITE_ON_DEMAND` | Modifications are written back on explicit demand (in this case all the modifications made to any row is written back)
`GNOME_DB_DATA_WIDGET_WRITE_ON_ROW_CHANGE` | Modifications are written back when the currently selected row changes (as when selecting another row), in this case only the modifications on the current row are written back
`GNOME_DB_DATA_WIDGET_WRITE_ON_VALUE_ACTIVATED` | Modifications are written back when the user "activates" the data entry (for example by pressing ENTER in a single line data entry), in this case only the modifications on the current row are written back
`GNOME_DB_DATA_WIDGET_WRITE_ON_VALUE_CHANGE` | Modifications are written back everytime a value changes (for instance everytime a letter is types when entering text); in this case only the modifications on the current row are written back (this option should only be used if the "source" data model accepts modifications without any test and without processing delays).

### gnome_db_data_widget_get_proxy ()

    GdaDataProxy*       gnome_db_data_widget_get_proxy      (GnomeDbDataWidget *iface);

Get a pointer to the GdaDataProxy being used by `iface`

`iface` : | an object which implements the GnomeDbDataWidget interface
Returns : | a GdaDataProxy pointer

### gnome_db_data_widget_get_actions_group ()

    GtkActionGroup*     gnome_db_data_widget_get_actions_group
                                                            (GnomeDbDataWidget *iface);

Each widget imlplementing the GnomeDbDataWidget interface provides actions. Actions can be triggered using the `gnome_db_data_widget_perform_action()` method, but using this method allows for the creation of toolbars, menus, etc calling these actions.

The actions are among:

- Data edition actions: "ActionNew", "ActionCommit", "ActionDelete, "ActionUndelete, "ActionReset",

- Record by record moving: "ActionFirstRecord", "ActionPrevRecord", "ActionNextRecord", "ActionLastRecord",

- Chuncks of records moving: "ActionFirstChunck", "ActionPrevChunck", "ActionNextChunck", "ActionLastChunck".

- Filtering: "ActionFilter"

`iface` : | an object which implements the GnomeDbDataWidget interface
Returns : | the GtkActionGroup with all the possible actions on the widget.

### gnome_db_data_widget_perform_action ()

    void                gnome_db_data_widget_perform_action (GnomeDbDataWidget *iface,
                                                             GnomeDbAction action);

Forces the widget to perform the selected `action`, as if the user had pressed on the corresponding action button in the `iface` widget, if the corresponding action is possible and if the `iface` widget supports the action.

`iface` : | an object which implements the GnomeDbDataWidget interface
`action` : | a GnomeDbAction action

### gnome_db_data_widget_column_show ()

    void                gnome_db_data_widget_column_show    (GnomeDbDataWidget *iface,
                                                             gint column);

Shows the data at `column` in the data model `iface` operates on

`iface` : | an object which implements the GnomeDbDataWidget interface
`column` : | column number to show

### gnome_db_data_widget_column_hide ()

    void                gnome_db_data_widget_column_hide    (GnomeDbDataWidget *iface,
                                                             gint column);

Hides the data at `column` in the data model `iface` operates on

`iface` : | an object which implements the GnomeDbDataWidget interface
`column` : | column number to hide

### gnome_db_data_widget_column_set_editable ()

    void                gnome_db_data_widget_column_set_editable
                                                            (GnomeDbDataWidget *iface,
                                                             gint column,
                                                             gboolean editable);

Sets if the data entry in the `iface` widget at `column` (in the data model `iface` operates on) can be edited or not.

`iface` : | an object which implements the GnomeDbDataWidget interface
`column` : | column number of the data
`editable` : |

### gnome_db_data_widget_column_show_actions ()

    void                gnome_db_data_widget_column_show_actions
                                                            (GnomeDbDataWidget *iface,
                                                             gint column,
                                                             gboolean show_actions);

Sets if the data entry in the `iface` widget at `column` (in the data model `iface` operates on) must show its actions menu or not.

`iface` : | an object which implements the GnomeDbDataWidget interface
`column` : | column number of the data, or -1 to apply the setting to all the columns
`show_actions` : |

### gnome_db_data_widget_get_current_data ()

    GdaDataModelIter*   gnome_db_data_widget_get_current_data
                                                            (GnomeDbDataWidget *iface);

Get the GdaDataModelIter object which contains all the parameters which in turn contain the actual data stored in `iface`. When the user changes what's displayed or what's selected (depending on the actual widget) in `iface`, then the parameter's values change as well.

`iface` : | an object which implements the GnomeDbDataWidget interface
Returns : | the GdaSet object for data (not a new object)

### gnome_db_data_widget_get_gda_model ()

    GdaDataModel*       gnome_db_data_widget_get_gda_model  (GnomeDbDataWidget *iface);

Get the current GdaDataModel used by `iface`

`iface` : | an object which implements the GnomeDbDataWidget interface
Returns : | the GdaDataModel, or `NULL` if there is none

### gnome_db_data_widget_set_gda_model ()

    void                gnome_db_data_widget_set_gda_model  (GnomeDbDataWidget *iface,
                                                             GdaDataModel *model);

Sets the data model which is used by `iface`.

`iface` : | an object which implements the GnomeDbDataWidget interface
`model` : | a valid GdaDataModel

### gnome_db_data_widget_set_write_mode ()

    gboolean            gnome_db_data_widget_set_write_mode (GnomeDbDataWidget *iface,
                                                             GnomeDbDataWidgetWriteMode mode);

Specifies the way the modifications stored in the GdaDataProxy used internally by `iface` are written back to the GdaDataModel which holds the data displayed in `iface`.

`iface` : | an object which implements the GnomeDbDataWidget interface
`mode` : |
Returns : | TRUE if the proposed mode has been taken into account

### gnome_db_data_widget_get_write_mode ()

    GnomeDbDataWidgetWriteMode gnome_db_data_widget_get_write_mode
                                                            (GnomeDbDataWidget *iface);

Get the way the modifications stored in the GdaDataProxy used internally by `iface` are written back to the GdaDataModel which holds the data displayed in `iface`.

`iface` : | an object which implements the GnomeDbDataWidget interface
Returns : | the write mode used by `iface`

## Signal Details

### The `"iter-changed"` signal

    void                user_function                      (GnomeDbDataWidget *dbdatawidget,
                                                            gpointer           arg1,
                                                            gpointer           user_data)         : Run First

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

### The `"proxy-changed"` signal

    void                user_function                      (GnomeDbDataWidget *dbdatawidget,
                                                            GdaDataProxy      *arg1,
                                                            gpointer           user_data)         : Run First

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