GtkDataEntry: GtkExtra Reference Manual

## GtkDataEntry GtkDataEntry — a data entry widget, based on GtkEntry |

## Functions

GtkDataEntry * | gtk_data_entry_new ()
const gchar * | gtk_data_entry_get_description ()
void | gtk_data_entry_set_description ()
const gchar * | gtk_data_entry_get_data_type ()
void | gtk_data_entry_set_data_type ()
const gchar * | gtk_data_entry_get_data_format ()
void | gtk_data_entry_set_data_format ()
const gchar * | gtk_data_entry_get_text ()
void | gtk_data_entry_set_text ()
gint | gtk_data_entry_get_max_length_bytes ()
void | gtk_data_entry_set_max_length_bytes ()

## Properties

gchar * | dataformat | Read / Write
gchar * | datatype | Read / Write
gchar * | description | Read / Write
gint | max-length-bytes | Read / Write
gchar * | text | Read / Write

## Types and Values

struct | GtkDataEntry

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkEntry
                        ╰── GtkDataEntry

## Implemented Interfaces

GtkDataEntry implements AtkImplementorIface, GtkBuildable, GtkEditable and GtkCellEditable.

## Includes

    #include <gtkextra.h>

## Description

GtkDataEntry provides additional properties:

- “description” - no functionality, a place for private information that cannot be put anywhere else

- “datatype” - no functionality, a datatype hint for the application because any widget content is text

- “dataformat” - a formatting instruction that controls what you see when the widget doesn't have input focus

- “text” - set the contents of the widget. if the widget doesn't have input focus text will be formatted according to the data_format

- “max-length-bytes” - set the maximum byte length for the contents of the widget.

The main reason for this widget is to provide a formatting entry widget for numeric data like integer, float, money which also supports NULL values (GtkSpinButton is nice but doesn't support empty field values). Handling of Null values is supported by all SQL database systems. The Null values are represented by empty field contents.

When editing field contents, all data formatting is removed before the focus enters the widget. As soon as the focus leaves the widget, data will be nicely formatted again.

As an additional feature, the minus sign (negative numbers) can be entered at the end of the data. As soon as you leave the field it will be placed properly in front of the number.

See also: `gtk_data_format()`

## Functions

### gtk_data_entry_new ()

    GtkDataEntry *
    gtk_data_entry_new (void);

Creates a new GtkDataEntry Widget.

#### Returns

the new GtkDataEntry Widget

### gtk_data_entry_get_description ()

    const gchar *
    gtk_data_entry_get_description (GtkDataEntry *data_entry);

Retrieves the GtkDataEntry description.

#### Parameters

data_entry | a GtkDataEntry |

#### Returns

a pointer to the contents of the widget as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored.

### gtk_data_entry_set_description ()

    void
    gtk_data_entry_set_description (GtkDataEntry *data_entry,
                                    const gchar *description);

Sets the GtkDataEntry description.

Basically, you can use the description for your own programming purpose. The GtkDataEntry recognizes the keywords below, which have a special meaning.

- Ignore(vString) - silently ignore all characters in vString

- Map(vString1|vString) - map each character in vString1 to the corresponding character in vString2 with the same index

- Accept(vString) - accept only characters in vString, sound bell for invalid characters

- Reject(vString) - ignore all characters in vString, sound bell for invalid characters

Evaluation order: Ignore, Map, not Accept or Reject

vString's are a literate character lists. They may contain valid utf-8 character sequences and the following escape sequences: \a, \b, \f, \n, \r, \t, \v, \. vStrings are not quoted like a normal C string, they are delimited by round brackets or the pipe symbol, see above.

#### Parameters

data_entry | a GtkDataEntry |
description | the description or NULL |

### gtk_data_entry_get_data_type ()

    const gchar *
    gtk_data_entry_get_data_type (GtkDataEntry *data_entry);

Retrieves the GtkDataEntry data_type.

#### Parameters

data_entry | a GtkDataEntry |

#### Returns

a pointer to the contents of the widget as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored.

### gtk_data_entry_set_data_type ()

    void
    gtk_data_entry_set_data_type (GtkDataEntry *data_entry,
                                  const gchar *data_type);

Sets the GtkDataEntry data type for application use.

#### Parameters

data_entry | a GtkDataEntry |
data_type | the data type or NULL |

### gtk_data_entry_get_data_format ()

    const gchar *
    gtk_data_entry_get_data_format (GtkDataEntry *data_entry);

Retrieves the GtkDataEntry data_format.

See `gtk_data_format()` for details.

#### Parameters

data_entry | a GtkDataEntry |

#### Returns

a pointer to the contents of the widget as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored.

### gtk_data_entry_set_data_format ()

    void
    gtk_data_entry_set_data_format (GtkDataEntry *data_entry,
                                    const gchar *data_format);

Sets the GtkDataEntry data type for application use. The display will not be refreshed upon change.

See `gtk_data_format()` for details.

#### Parameters

data_entry | a GtkDataEntry |
data_format | the data type or NULL |

### gtk_data_entry_get_text ()

    const gchar *
    gtk_data_entry_get_text (GtkDataEntry *data_entry);

Retrieves the GtkDataEntry contents. All formatting will be removed.

#### Parameters

data_entry | a GtkDataEntry |

#### Returns

a pointer to the contents of the widget as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored.

### gtk_data_entry_set_text ()

    void
    gtk_data_entry_set_text (GtkDataEntry *data_entry,
                             const gchar *text);

Sets the GtkDataEntry contents. The contents will be formatted due to the current data_format.

#### Parameters

data_entry | a GtkDataEntry |
text | the contents to be set |

### gtk_data_entry_get_max_length_bytes ()

    gint
    gtk_data_entry_get_max_length_bytes (GtkDataEntry *data_entry);

Retrieves the maximum byte length for the contents of GtkDataEntry.

#### Parameters

data_entry | a GtkDataEntry |

#### Returns

maximum byte length or 0.

Since: 3.0.6

### gtk_data_entry_set_max_length_bytes ()

    void
    gtk_data_entry_set_max_length_bytes (GtkDataEntry *data_entry,
                                         gint max_length_bytes);

Sets the maximum byte length for the contents of the GtkDataEntry. Existing content will not be truncted.

#### Parameters

data_entry | a GtkDataEntry |
max_length_bytes | maximum byte length or 0 |

Since: 3.0.6

## Types and Values

### struct GtkDataEntry

    struct GtkDataEntry;

The GtkDataEntry struct contains only private data. It should only be accessed through the functions described below.

## Property Details

### The `“dataformat”` property

      “dataformat”               gchar *

a formatting string that controls what you see when the widget doesn't contain input focus.

See `gtk_data_format()` for details.

Flags: Read / Write

Default value: ""

### The `“datatype”` property

      “datatype”                 gchar *

no functionality, a datatype hint for the application because any widget content is text.

Flags: Read / Write

Default value: ""

### The `“description”` property

      “description”              gchar *

Description of the GtkDataEntry, no functionality, a place for private information that cannot be put anywhere else.

Flags: Read / Write

Default value: ""

### The `“max-length-bytes”` property

      “max-length-bytes”         gint

Set the maximum length in bytes for the GtkDataEntry. For details see gtk_data_entry_set_max_length_bytes.

Sometimes, systems cannot handle UTF-8 string length correctly, to overcome this problem, you can use the maximum string length in bytes. When setting both limits, max-length and max-length-bytes, both must be fulfilled.

Flags: Read / Write

Allowed values: [0,65535]

Default value: 0

Since: 3.0.6

### The `“text”` property

      “text”                     gchar *

Set the contents of the GtkDataEntry. For details see gtk_data_entry_set_text.

Flags: Read / Write

Default value: ""