GnomeDbDataWidget

GnomeDbDataWidget — Interface to control data bound widgets

Synopsis

                    GnomeDbDataWidget;
enum                GnomeDbDataWidgetWriteMode;
GdaDataProxy *      gnome_db_data_widget_get_proxy      (GnomeDbDataWidget *iface);
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);
GtkActionGroup *    gnome_db_data_widget_get_actions_group
                                                        (GnomeDbDataWidget *iface);
void                gnome_db_data_widget_perform_action (GnomeDbDataWidget *iface,
                                                         GnomeDbAction action);
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_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_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".

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_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 GdaParameterList 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.