## GnomeDbFormatEntry

GnomeDbFormatEntry — A GtkEntry with formatting options

## Synopsis

                        GnomeDbFormatEntry;
                        GnomeDbFormatEntryClass;
                        GnomeDbFormatEntryPrivate;
    GtkWidget*          gnome_db_format_entry_new           (void);
    void                gnome_db_format_entry_set_max_length
                                                            (GnomeDbFormatEntry *entry,
                                                             gint max);
    void                gnome_db_format_entry_set_format    (GnomeDbFormatEntry *entry,
                                                             const gchar *format,
                                                             const gchar *mask,
                                                             const gchar *completion);
    void                gnome_db_format_entry_set_decimal_places
                                                            (GnomeDbFormatEntry *entry,
                                                             gint nb_decimals);
    void                gnome_db_format_entry_set_separators
                                                            (GnomeDbFormatEntry *entry,
                                                             guchar decimal,
                                                             guchar thousands);
    void                gnome_db_format_entry_set_edited_type
                                                            (GnomeDbFormatEntry *entry,
                                                             GType type);
    void                gnome_db_format_entry_set_prefix    (GnomeDbFormatEntry *entry,
                                                             const gchar *prefix);
    void                gnome_db_format_entry_set_suffix    (GnomeDbFormatEntry *entry,
                                                             const gchar *suffix);
    void                gnome_db_format_entry_set_text      (GnomeDbFormatEntry *entry,
                                                             const gchar *text);
    gchar*              gnome_db_format_entry_get_text      (GnomeDbFormatEntry *entry);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkEntry
                               +----GnomeDbFormatEntry

## Implemented Interfaces

GnomeDbFormatEntry implements GtkEditable, AtkImplementorIface and GtkCellEditable.

## Properties

      "completion"               gchararray            : Read / Write
      "decimal-sep"              guchar                : Read / Write
      "edited-type"              guint                 : Read / Write
      "format"                   gchararray            : Read / Write
      "mask"                     gchararray            : Read / Write
      "max-length"               gint                  : Read / Write
      "n-decimals"               gint                  : Read / Write
      "prefix"                   gchararray            : Read / Write
      "suffix"                   gchararray            : Read / Write
      "thousands-sep"            guchar                : Read / Write

## Description

The GnomeDbFormatEntry widget is a GtkEntry widget with the following additional features:

- supports specifying a specific expected data type (such as G_TYPE_INT for example) and the widget will only allow the user to enter a text which can be converted to the expected data type

- supports specifying a string format when the user has to enter a string with a specific format, see `gnome_db_format_entry_set_format()` for more information

- supports specifying the number of decimals any non integer number can have

- supports specifying prefix and/or a suffix strings which will always be displayed and not modifyable

## Details

### GnomeDbFormatEntry

    typedef struct _GnomeDbFormatEntry GnomeDbFormatEntry;

### GnomeDbFormatEntryClass

    typedef struct {
    	GtkEntryClass              parent_class;
    } GnomeDbFormatEntryClass;

### GnomeDbFormatEntryPrivate

    typedef struct _GnomeDbFormatEntryPrivate GnomeDbFormatEntryPrivate;

### gnome_db_format_entry_new ()

    GtkWidget*          gnome_db_format_entry_new           (void);

Creates a new GnomeDbFormatEntry widget.

Returns : | the newly created GnomeDbFormatEntry widget.

### gnome_db_format_entry_set_max_length ()

    void                gnome_db_format_entry_set_max_length
                                                            (GnomeDbFormatEntry *entry,
                                                             gint max);

Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit.

The difference with `gtk_entry_set_max_length()` is that the max length does not take into account the prefix and/or suffix parts which may have been set.

`entry` : | a GnomeDbFormatEntry.
`max` : | the maximum length of the entry, or 0 for no maximum.

### gnome_db_format_entry_set_format ()

    void                gnome_db_format_entry_set_format    (GnomeDbFormatEntry *entry,
                                                             const gchar *format,
                                                             const gchar *mask,
                                                             const gchar *completion);

Set the edited string's format. Characters in the format are of two types: writeable: writeable characters are characters that will be replaced with and underscore and where you can enter text. fixed: every other characters are fixed characters, where text cant' be edited Possible values for writeable characters are:

- '0': digits

- '9': digits excluded 0

- '@': alpha

- '^': alpha converted to upper case

- '#': alphanumeric

- '*': any char

if `mask` is not `NULL`, then it must contain the exact same number of characters as `format`; it is then interpreted in the following way: for a character C in `format`, if the character at the same position in `mask` is the space character (' '), then C will not interpreted as a writable format character as defined above.

if `completion` is not `NULL`, then it must contain the exact same number of characters as `format`. A When the entry has a cursor at a position P and the character to enter is not what's expected at position P in the `format` string, then the character at a position P in this string is used.

`entry` : | a GnomeDbFormatEntry.
`format` : | the format specification of the data to edit
`mask` : | a 'mask' string helping understand `format`, or `NULL`
`completion` : | a 'completions' string, or `NULL`

### gnome_db_format_entry_set_decimal_places ()

    void                gnome_db_format_entry_set_decimal_places
                                                            (GnomeDbFormatEntry *entry,
                                                             gint nb_decimals);

Sets the number of decimals which must be displayed in `entry` when entering a non integer numerical value

`entry` : | a GnomeDbFormatEntry widget
`nb_decimals` : | the number of decimals which must be displayed in `entry`

### gnome_db_format_entry_set_separators ()

    void                gnome_db_format_entry_set_separators
                                                            (GnomeDbFormatEntry *entry,
                                                             guchar decimal,
                                                             guchar thousands);

Sets the decimal and thousands separators to use within `entry` when it contains a numerical value

`entry` : | a GnomeDbFormatEntry widget
`decimal` : | the character to use as a decimal separator, or 0 for default (locale specific) separator
`thousands` : | the character to use as a thousands separator, or 0 for no separator at all

### gnome_db_format_entry_set_edited_type ()

    void                gnome_db_format_entry_set_edited_type
                                                            (GnomeDbFormatEntry *entry,
                                                             GType type);

Specifies what type of data is edited in `entry`

`entry` : | a GnomeDbFormatEntry widget
`type` : | the type of data expected to be edited `entry` itself returns a string, `type` specifies into what type that string will be converted)

### gnome_db_format_entry_set_prefix ()

    void                gnome_db_format_entry_set_prefix    (GnomeDbFormatEntry *entry,
                                                             const gchar *prefix);

Sets `prefix` as a prefix string of `entry`: that string will always be displayed in the text entry, will not be modifiable, and won't be part of the returned text

`entry` : | a GnomeDbFormatEntry widget
`prefix` : | a prefix string

### gnome_db_format_entry_set_suffix ()

    void                gnome_db_format_entry_set_suffix    (GnomeDbFormatEntry *entry,
                                                             const gchar *suffix);

Sets `suffix` as a suffix string of `entry`: that string will always be displayed in the text entry, will not be modifiable, and won't be part of the returned text

`entry` : | a GnomeDbFormatEntry widget
`suffix` : | a suffix string

### gnome_db_format_entry_set_text ()

    void                gnome_db_format_entry_set_text      (GnomeDbFormatEntry *entry,
                                                             const gchar *text);

Sets `text` into `entry`.

As a side effect, if `text` is `NULL`, then the entry will be completely empty, whereas if `text` is the empty string (""), then `entry` will display the prefix and/or suffix and/or format string if they have been set. Except this case, calling this method is similar to calling `gtk_entry_set_text()`

`entry` : | a GnomeDbFormatEntry widget
`text` : | the text to set into `entry`, or `NULL`

### gnome_db_format_entry_get_text ()

    gchar*              gnome_db_format_entry_get_text      (GnomeDbFormatEntry *entry);

Get a new string containing the contents of the widget as a string without the prefix and/or suffix and/or format if they have been specified. This method differs from calling `gtk_entry_get_text()` since the latest will return the complete text in `entry` including prefix and/or suffix and/or format.

Note: `NULL` may be returned if this method is called while the widget is working on some internal modifications, or if `gnome_db_format_entry_set_text()` was called with a `NULL` as its `text` argument.

`entry` : | a GnomeDbFormatEntry.
Returns : | a new string, or `NULL`

## Property Details

### The "`completion`" property

      "completion"               gchararray            : Read / Write

Default value: NULL

### The "`decimal-sep`" property

      "decimal-sep"              guchar                : Read / Write

Default value: 46

### The "`edited-type`" property

      "edited-type"              guint                 : Read / Write

Default value: 64

### The "`format`" property

      "format"                   gchararray            : Read / Write

Default value: NULL

### The "`mask`" property

      "mask"                     gchararray            : Read / Write

Default value: NULL

### The "`max-length`" property

      "max-length"               gint                  : Read / Write

Allowed values: >= 0

Default value: 0

### The "`n-decimals`" property

      "n-decimals"               gint                  : Read / Write

Allowed values: >= -1

Default value: -1

### The "`prefix`" property

      "prefix"                   gchararray            : Read / Write

Default value: NULL

### The "`suffix`" property

      "suffix"                   gchararray            : Read / Write

Default value: NULL

### The "`thousands-sep`" property

      "thousands-sep"            guchar                : Read / Write

Default value: 44