GdauiDataEntry

## GdauiDataEntry GdauiDataEntry — Data entry widget |

## Synopsis

                        GdauiDataEntry;
    void                gdaui_data_entry_set_value_type     (GdauiDataEntry *de,
                                                             GType type);
    GType               gdaui_data_entry_get_value_type     (GdauiDataEntry *de);
    void                gdaui_data_entry_set_value          (GdauiDataEntry *de,
                                                             const GValue *value);
    GValue *            gdaui_data_entry_get_value          (GdauiDataEntry *de);
    gboolean            gdaui_data_entry_content_is_valid   (GdauiDataEntry *de,
                                                             GError **error);
    void                gdaui_data_entry_set_reference_value
                                                            (GdauiDataEntry *de,
                                                             const GValue *value);
    const GValue *      gdaui_data_entry_get_reference_value
                                                            (GdauiDataEntry *de);
    void                gdaui_data_entry_set_reference_current
                                                            (GdauiDataEntry *de);
    void                gdaui_data_entry_set_default_value  (GdauiDataEntry *de,
                                                             const GValue *value);
    void                gdaui_data_entry_set_attributes     (GdauiDataEntry *de,
                                                             GdaValueAttribute attrs,
                                                             GdaValueAttribute mask);
    GdaValueAttribute   gdaui_data_entry_get_attributes     (GdauiDataEntry *de);
    GdaDataHandler *    gdaui_data_entry_get_handler        (GdauiDataEntry *de);
    gboolean            gdaui_data_entry_can_expand         (GdauiDataEntry *de,
                                                             gboolean horiz);
    void                gdaui_data_entry_set_editable       (GdauiDataEntry *de,
                                                             gboolean editable);
    gboolean            gdaui_data_entry_get_editable       (GdauiDataEntry *de);
    void                gdaui_data_entry_grab_focus         (GdauiDataEntry *de);

## Object Hierarchy

      GInterface
       +----GdauiDataEntry

## Signals

      "contents-activated"                             : Run First
      "contents-modified"                              : Run First
      "contents-valid"                                 : Run Last
      "expand-changed"                                 : Run First
      "status-changed"                                 : Run First

## Description

The GdaUiDataEntry is an interface for widgets (simple or complex) which lets the user view and/or modify a GValue.

This interface is implemented by widgets which feature data editing (usually composed of an editing area and a button to have some more control on the value being edited). The interface allows to control how the widget works and to query the value and the attributes of the data held by the widget.

The widget can store the original value (to be able to tell if the value has been changed by the user) and a default value (which will be returned if the user explicitly forces the widget to be set to the default value). Control methods allow to set the type of value to be edited (the requested type must be compatible with what the widget can handle), set the value (which replaces the currently edited value), set the value and the original value (the value passed as argument is set and is also considered to be the original value).

GdaUiDataEntry widgets are normally created using the `gdaui_new_data_entry()` function.

## Details

### GdauiDataEntry

    typedef struct _GdauiDataEntry GdauiDataEntry;

### gdaui_data_entry_set_value_type ()

    void                gdaui_data_entry_set_value_type     (GdauiDataEntry *de,
                                                             GType type);

Sets the type of value the GdauiDataEntry will handle. The type must be compatible with what the widget can handle.

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`type` : | the GType of the data to be displayed

Since 4.2

### gdaui_data_entry_get_value_type ()

    GType               gdaui_data_entry_get_value_type     (GdauiDataEntry *de);

Fetch the type of data the GdauiDataEntry handles

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | the GType type

Since 4.2

### gdaui_data_entry_set_value ()

    void                gdaui_data_entry_set_value          (GdauiDataEntry *de,
                                                             const GValue *value);

Push a value into the GdauiDataEntry. The value parameter must either be:

- of type GDA_TYPE_NULL (may be created using `gda_value_new_null()`) to represent a NULL value (SQL NULL), or

- of type specified using `gdaui_data_entry_set_value_type()`, or

- NULL to represent an undetermined value (usually an error)

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`value` : | a GValue, or `NULL`. [allow-none]

Since 4.2

### gdaui_data_entry_get_value ()

    GValue *            gdaui_data_entry_get_value          (GdauiDataEntry *de);

Fetch the value held in the GdauiDataEntry widget. If the value is set to NULL, the returned value is of type GDA_TYPE_NULL. If the value is set to default, then the returned value is of type GDA_TYPE_NULL or is the default value if it has been provided to the widget (and is of the same type as the one provided by `de`).

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | a new GValue. [transfer none]

Since 4.2

### gdaui_data_entry_content_is_valid ()

    gboolean            gdaui_data_entry_content_is_valid   (GdauiDataEntry *de,
                                                             GError **error);

Tests the validity of `de`'s contents. The validity is a determined from:

- the `de` widget itself if it is capable of doing it (depending on the implementation)

- the results of the "contents-valid" signal which can be connected from

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`error` : | a place to store an error, or `NULL`. [allow-none]
Returns : | TRUE if `de`'s contents is valid

Since 4.2

### gdaui_data_entry_set_reference_value ()

    void                gdaui_data_entry_set_reference_value
                                                            (GdauiDataEntry *de,
                                                             const GValue *value);

Push a value into the GdauiDataEntry in the same way as `gdaui_data_entry_set_value()` but also sets this value as the reference value.

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`value` : | a GValue, or `NULL`. [allow-none]

Since 4.2

### gdaui_data_entry_get_reference_value ()

    const GValue *      gdaui_data_entry_get_reference_value
                                                            (GdauiDataEntry *de);

Fetch the reference value held in the GdauiDataEntry widget

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | the GValue (not modifiable). [transfer none]

Since 4.2

### gdaui_data_entry_set_reference_current ()

    void                gdaui_data_entry_set_reference_current
                                                            (GdauiDataEntry *de);

Tells that the current value in `de` is to be considered as the reference value

`de` : | a GtkWidget object which implements the GdauiDataEntry interface

Since 4.2

### gdaui_data_entry_set_default_value ()

    void                gdaui_data_entry_set_default_value  (GdauiDataEntry *de,
                                                             const GValue *value);

Sets the default value for the GdauiDataEntry which gets displayed when the user forces the default value. If it is not set then it is set to type GDA_TYPE_NULL. The value parameter must either be:

- NULL or of type GDA_TYPE_NULL, or

- of type specified using `gdaui_data_entry_set_value_type()`.

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`value` : | a GValue, or `NULL`. [allow-none]

Since 4.2

### gdaui_data_entry_set_attributes ()

    void                gdaui_data_entry_set_attributes     (GdauiDataEntry *de,
                                                             GdaValueAttribute attrs,
                                                             GdaValueAttribute mask);

Sets the parameters of the GdauiDataEntry. Only the attributes corresponding to the mask are set, the other ones are ignored.

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`attrs` : | the attributes to set (OR'ed between them)
`mask` : | the mask corresponding to the considered attributes

Since 4.2

### gdaui_data_entry_get_attributes ()

    GdaValueAttribute   gdaui_data_entry_get_attributes     (GdauiDataEntry *de);

Retrieves the parameters of the GdauiDataEntry widget.

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | the OR'ed bits corresponding to the attributes.

Since 4.2

### gdaui_data_entry_get_handler ()

    GdaDataHandler *    gdaui_data_entry_get_handler        (GdauiDataEntry *de);

Fetch the GdaDataHandler the GdauiDataEntry is using

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | the GdaDataHandler object. [transfer none]

Since 4.2

### gdaui_data_entry_can_expand ()

    gboolean            gdaui_data_entry_can_expand         (GdauiDataEntry *de,
                                                             gboolean horiz);

Used for the layout of GdaDataEntry widgets in containers: queries if `de` requires horizontal or vertical expansion, depending on `horiz`

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`horiz` : | `TRUE` to query horizontal expansion requirements, or `FALSE` for vertical
Returns : | `TRUE` if the widget requires expansion

Since 4.2

### gdaui_data_entry_set_editable ()

    void                gdaui_data_entry_set_editable       (GdauiDataEntry *de,
                                                             gboolean editable);

Set if `de` can be modified or not by the user

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
`editable` : | set to `TRUE` to have an editable data entry

Since 4.2

### gdaui_data_entry_get_editable ()

    gboolean            gdaui_data_entry_get_editable       (GdauiDataEntry *de);

Tells if `de` can be edited by the user

`de` : | a GtkWidget object which implements the GdauiDataEntry interface
Returns : | `TRUE` if `de` is editable

Since 4.2

### gdaui_data_entry_grab_focus ()

    void                gdaui_data_entry_grab_focus         (GdauiDataEntry *de);

Makes `de` grab the focus for the window it's in

`de` : | a GtkWidget object which implements the GdauiDataEntry interface

Since 4.2

## Signal Details

### The `"contents-activated"` signal

    void                user_function                      (GdauiDataEntry *gdauidataentry,
                                                            gpointer        user_data)           : Run First

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

### The `"contents-modified"` signal

    void                user_function                      (GdauiDataEntry *gdauidataentry,
                                                            gpointer        user_data)           : Run First

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

### The `"contents-valid"` signal

    gboolean            user_function                      (GdauiDataEntry *gdauidataentry,
                                                            gpointer        arg1,
                                                            gpointer        user_data)           : Run Last

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

### The `"expand-changed"` signal

    void                user_function                      (GdauiDataEntry *gdauidataentry,
                                                            gpointer        user_data)           : Run First

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

### The `"status-changed"` signal

    void                user_function                      (GdauiDataEntry *gdauidataentry,
                                                            gpointer        user_data)           : Run First

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