## MgWorkWidget

MgWorkWidget — Interface used to perform common operations on widgets which implement it. The MgWorkForm and MgWorkGrid widgets do implement that interface.

## Synopsis

    struct      MgWorkWidget;
    struct      MgWorkWidgetIface;
    GType       mg_work_widget_get_type         (void);
    void        mg_work_widget_run              (MgWorkWidget *iface,
                                                 guint mode);
    void        mg_work_widget_set_mode         (MgWorkWidget *iface,
                                                 guint mode);
    void        mg_work_widget_entry_set_editable
                                                (MgWorkWidget *iface,
                                                 MgQfield *field,
                                                 gboolean editable);
    void        mg_work_widget_entry_show_actions
                                                (MgWorkWidget *iface,
                                                 MgQfield *field,
                                                 gboolean show_actions);
    void        mg_work_widget_alldata_show_actions
                                                (MgWorkWidget *iface,
                                                 gboolean show_actions);
    gboolean    mg_work_widget_is_exec_context_valid
                                                (MgWorkWidget *iface);
    MgParameter* mg_work_widget_get_param_for_field_exec
                                                (MgWorkWidget *iface,
                                                 MgQfield *field);
    MgParameter* mg_work_widget_get_param_for_field_sql_exec
                                                (MgWorkWidget *iface,
                                                 const gchar *field_name);
    MgParameter* mg_work_widget_get_param_for_field_data
                                                (MgWorkWidget *iface,
                                                 MgQfield *field);
    MgParameter* mg_work_widget_get_param_for_field_sql_data
                                                (MgWorkWidget *iface,
                                                 const gchar *field_name);
    GtkActionGroup* mg_work_widget_get_actions_group
                                                (MgWorkWidget *iface);
    void        mg_work_widget_perform_action   (MgWorkWidget *iface,
                                                 MgAction action);
    gboolean    mg_work_widget_has_been_changed (MgWorkWidget *iface);
    void        mg_work_widget_bind_to_work_widget_xml
                                                (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_xml_id,
                                                 MgWorkWidget *source_iface,
                                                 const gchar *source_field_xml_id);
    gboolean    mg_work_widget_bind_to_work_widget_sql
                                                (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_name,
                                                 MgWorkWidget *source_iface,
                                                 const gchar *source_field_name);
    void        mg_work_widget_bind_to_context  (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_xml_id,
                                                 MgContext *source_context,
                                                 const gchar *source_field_xml_id);
    void        mg_work_widget_bind_to_context_all
                                                (MgWorkWidget *dest_iface,
                                                 MgContext *source_context);

## Object Hierarchy

      GInterface
       +----MgWorkWidget

## Prerequisites

MgWorkWidget requires GObject.

## Known Implementations

MgWorkWidget is implemented by MgWorkForm, MgWorkGrid, MgWorkMatrix and MgWorkLayout.

## Description

## Details

### struct MgWorkWidget

    struct MgWorkWidget;

### struct MgWorkWidgetIface

    struct MgWorkWidgetIface {

    	GTypeInterface           g_iface;

    	/* virtual table */
    	void            (* run)                 (MgWorkWidget *iface, guint mode);
    	void            (* set_mode)            (MgWorkWidget *iface, guint mode);
    	void            (* set_entry_editable)  (MgWorkWidget *iface, MgQfield *field, gboolean editable);
    	void            (* show_entry_actions)  (MgWorkWidget *iface, MgQfield *field, gboolean show_actions);
    	void            (* show_global_actions) (MgWorkWidget *iface, gboolean show_actions);
    	MgParameter    *(* get_param_for_field) (MgWorkWidget *iface, MgQfield *field, const gchar *file_name, gboolean in_exec_context);
    	gboolean        (* has_been_changed)    (MgWorkWidget *iface);
    	MgContext      *(* get_exec_context)    (MgWorkWidget *iface);
    	GtkActionGroup *(* get_actions_group)   (MgWorkWidget *iface);
    };

### mg_work_widget_get_type ()

    GType       mg_work_widget_get_type         (void);

Returns : |

### mg_work_widget_run ()

    void        mg_work_widget_run              (MgWorkWidget *iface,
                                                 guint mode);

Makes the widget run the queries it has to run in order to display usefull data. Havin a separate step to "run" the widget allows to have the execution context related to other events.

If mode==0, then the `mode` argument is ignored and the previous mode is unchanged.

`iface` : | an object which implements the MgWorkWidget interface
`mode` : | an OR'ed collection of flags from MgEnumsMode

### mg_work_widget_set_mode ()

    void        mg_work_widget_set_mode         (MgWorkWidget *iface,
                                                 guint mode);

Changes the mode that was set when `mg_work_widget_run()` was called.

`iface` : | an object which implements the MgWorkWidget interface
`mode` : | an OR'ed collection of flags from MgEnumsMode

### mg_work_widget_entry_set_editable ()

    void        mg_work_widget_entry_set_editable
                                                (MgWorkWidget *iface,
                                                 MgQfield *field,
                                                 gboolean editable);

Sets if the data entry in the `iface` widget corresponding to `field` can be edited or not.

`iface` : | an object which implements the MgWorkWidget interface
`field` : | a MgQfield object which belongs to the MgQuery which `iface` uses
`editable` : |

### mg_work_widget_entry_show_actions ()

    void        mg_work_widget_entry_show_actions
                                                (MgWorkWidget *iface,
                                                 MgQfield *field,
                                                 gboolean show_actions);

Controls if MgDataEntry widget used to manipulate the data corresponding to the `field` field must show its actions or not. If `field` is `NULL`, then the `show_actions` flag applies for all the fields.

`iface` : | an object which implements the MgWorkWidget interface
`field` : | a MgQfield object which belongs to the MgQuery which `iface` uses
`show_actions` : |

### mg_work_widget_alldata_show_actions ()

    void        mg_work_widget_alldata_show_actions
                                                (MgWorkWidget *iface,
                                                 gboolean show_actions);

Controls if the action buttons provided by the `iface` widget (for instance SAVE, RESET, MOVE TO NEXT, etc) are displayed or not.

`iface` : | an object which implements the MgWorkWidget interface
`show_actions` : |

### mg_work_widget_is_exec_context_valid ()

    gboolean    mg_work_widget_is_exec_context_valid
                                                (MgWorkWidget *iface);

Checks if the `iface` widget can be run, that is if no parameter is missing in the queries that it needs to run.

`iface` : | an object which implements the MgWorkWidget interface
Returns : | TRUE if the exec context is valid

### mg_work_widget_get_param_for_field_exec ()

    MgParameter* mg_work_widget_get_param_for_field_exec
                                                (MgWorkWidget *iface,
                                                 MgQfield *field);

Get the MgParameter object corresponding to `field`, in the case `field` represents a parameter for the `iface` widget (that is a modification of the value of a returned value will provoque a data refresh in the `iface` widget).

`iface` : | an object which implements the MgWorkWidget interface
`field` : | a MgQfield object which belongs to the MgQuery which `iface` uses
Returns : |

### mg_work_widget_get_param_for_field_sql_exec ()

    MgParameter* mg_work_widget_get_param_for_field_sql_exec
                                                (MgWorkWidget *iface,
                                                 const gchar *field_name);

Get the MgParameter object corresponding to `field_name`, in the case `field_name` represents a parameter for the `iface` widget (that is a modification of the value of a returned value will provoque a data refresh in the `iface` widget).

`iface` : | an object which implements the MgWorkWidget interface
`field_name` : | the name of a MgQfield object which belongs to the MgQuery which `iface` uses
Returns : |

### mg_work_widget_get_param_for_field_data ()

    MgParameter* mg_work_widget_get_param_for_field_data
                                                (MgWorkWidget *iface,
                                                 MgQfield *field);

Get the MgParameter object corresponding to `field`, in the case `field` is a data which is manipulated by the widget, and which can be selected by the user.

`iface` : | an object which implements the MgWorkWidget interface
`field` : | a MgQfield object which belongs to the MgQuery which `iface` uses
Returns : | the requested MgParameter, or `NULL`

### mg_work_widget_get_param_for_field_sql_data ()

    MgParameter* mg_work_widget_get_param_for_field_sql_data
                                                (MgWorkWidget *iface,
                                                 const gchar *field_name);

Get the MgParameter object corresponding to `field_name`, in the case `field` is a data which is manipulated by the widget, and which can be selected by the user.

`iface` : | an object which implements the MgWorkWidget interface
`field_name` : | the name of a MgQfield object which belongs to the MgQuery which `iface` uses
Returns : | the requested MgParameter, or `NULL`

### mg_work_widget_get_actions_group ()

    GtkActionGroup* mg_work_widget_get_actions_group
                                                (MgWorkWidget *iface);

Each widget imlplementing the MgWorkWidget interface provides actions. Actions can be triggered using the `mg_work_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: "WorkWidgetNew", "MgWorkWidgetCommit", "WorkWidgetDelete, "WorkWidgetUndelete, "WorkWidgetReset",

- Record by record moving: "WorkWidgetFirstRecord", "WorkWidgetPrevRecord", "WorkWidgetNextRecord", "WorkWidgetLastRecord",

- Chuncks of records moving: "WorkWidgetFirstChunck", "WorkWidgetPrevChunck", "WorkWidgetNextChunck", "WorkWidgetLastChunck".

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

### mg_work_widget_perform_action ()

    void        mg_work_widget_perform_action   (MgWorkWidget *iface,
                                                 MgAction 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 MgWorkWidget interface
`action` : | a MgAction action

### mg_work_widget_has_been_changed ()

    gboolean    mg_work_widget_has_been_changed (MgWorkWidget *iface);

Tells if the user has changed any of the data displayed by `iface` since the last refresh.

`iface` : | an object which implements the MgWorkWidget interface
Returns : | TRUE if `iface` has been changed

### mg_work_widget_bind_to_work_widget_xml ()

    void        mg_work_widget_bind_to_work_widget_xml
                                                (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_xml_id,
                                                 MgWorkWidget *source_iface,
                                                 const gchar *source_field_xml_id);

Retreives the MgParameter objects for the `dest_field_xml_id` and `source_field_xml_id` and bind them together: when the 'source' parameter changes, the 'dest' one takes the value of the 'source' one.

`dest_iface` : | an object which implements the MgWorkWidget interface
`dest_field_xml_id` : |
`source_iface` : | an object which implements the MgWorkWidget interface
`source_field_xml_id` : |

### mg_work_widget_bind_to_work_widget_sql ()

    gboolean    mg_work_widget_bind_to_work_widget_sql
                                                (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_name,
                                                 MgWorkWidget *source_iface,
                                                 const gchar *source_field_name);

Retreives the MgParameter objects for the `dest_field_name` and `source_field_name` and bind them together: when the 'source' parameter changes, the 'dest' one takes the value of the 'source' one.

`dest_iface` : | an object which implements the MgWorkWidget interface
`dest_field_name` : |
`source_iface` : | an object which implements the MgWorkWidget interface
`source_field_name` : |
Returns : | FALSE if an error occured

### mg_work_widget_bind_to_context ()

    void        mg_work_widget_bind_to_context  (MgWorkWidget *dest_iface,
                                                 const gchar *dest_field_xml_id,
                                                 MgContext *source_context,
                                                 const gchar *source_field_xml_id);

Retreives the MgParameter objects for the `dest_field_xml_id` and `source_field_xml_id` and bind them together: when the 'source' parameter changes, the 'dest' one takes the value of the 'source' one.

`dest_iface` : | an object which implements the MgWorkWidget interface
`dest_field_xml_id` : |
`source_context` : | a MgContext object
`source_field_xml_id` : |

### mg_work_widget_bind_to_context_all ()

    void        mg_work_widget_bind_to_context_all
                                                (MgWorkWidget *dest_iface,
                                                 MgContext *source_context);

For each MgParameter of `source_context`, retreives the corresponding MgParameter in `dest_iface`'s exec. context, and bind the two together: when the 'source' parameter changes, the 'dest' one takes the value of the 'source' one.

`dest_iface` : | an object which implements the MgWorkWidget interface
`source_context` : | a MgContext object