Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeEntry

## Name

GnomeEntry -- Entry widget with history tracking.

## Synopsis

    #include <gnome.h>

    struct      GnomeEntry;
    GtkWidget*  gnome_entry_new                 (const gchar *history_id);
    GtkWidget*  gnome_entry_gtk_entry           (GnomeEntry *gentry);
    void        gnome_entry_set_history_id      (GnomeEntry *gentry,
                                                 const gchar *history_id);
    void        gnome_entry_prepend_history     (GnomeEntry *gentry,
                                                 gint save,
                                                 const gchar *text);
    void        gnome_entry_append_history      (GnomeEntry *gentry,
                                                 gint save,
                                                 const gchar *text);
    void        gnome_entry_load_history        (GnomeEntry *gentry);
    void        gnome_entry_save_history        (GnomeEntry *gentry);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBox
                         +----GtkHBox
                               +----GtkCombo
                                     +----GnomeEntry

## Description

This widget is a wrapper around the GtkEntry widget, but it provides a history mechanism for all the input entered into the widget. The way this works is that a special identifier is provided when creating the GnomeEntry widget, and this identifier is used to load and save the history of the text.

Here is an example of how to use the widget

Example 1. Sample usage of the GnomeEntry widget

    GtkWidget *gnomeentry, *gtkentry;
    char *text;

    ...

    /* create a gnome entry */
    gnomeentry = gnome_entry_new("some_history_id");

    /* get the GtkEntry widget */
    gtkentry = gnome_entry_gtk_entry (GNOME_ENTRY (gnomeentry));

    /* set the text to "BLAH" */
    gtk_entry_set_text(GTK_ENTRY(gtkentry), "BLAH");

    ...

    /*somewhere else we wish to retrieve the contents*/
    text = gtk_entry_get_text(GTK_ENTRY(gtkentry));

## Details

### struct GnomeEntry

    struct GnomeEntry;

### gnome_entry_new ()

    GtkWidget*  gnome_entry_new                 (const gchar *history_id);

Creates a new GnomeEntry widget. If `history_id` is not `NULL`, then the history list will be saved and restored between uses under the given id.

`history_id` : | If not `NULL`, the text id under which history data is stored
Returns : | Newly-created GnomeEntry widget.

### gnome_entry_gtk_entry ()

    GtkWidget*  gnome_entry_gtk_entry           (GnomeEntry *gentry);

Obtain pointer to GnomeEntry's internal text entry

`gentry` : | Pointer to GnomeEntry object.
Returns : | Pointer to GtkEntry widget.

### gnome_entry_set_history_id ()

    void        gnome_entry_set_history_id      (GnomeEntry *gentry,
                                                 const gchar *history_id);

Set or clear the history id of the GnomeEntry widget. If `history_id` is `NULL`, the widget's history id is cleared. Otherwise, the given id replaces the previous widget history id.

`gentry` : | Pointer to GnomeEntry object.
`history_id` : | If not `NULL`, the text id under which history data is stored

### gnome_entry_prepend_history ()

    void        gnome_entry_prepend_history     (GnomeEntry *gentry,
                                                 gint save,
                                                 const gchar *text);

Adds a history item of the given `text` to the head of the history list inside `gentry`. If `save` is `TRUE`, the history item will be saved in the config file (assuming that `gentry`'s history id is not `NULL`).

`gentry` : | Pointer to GnomeEntry object.
`save` : | If `TRUE`, history entry will be saved to config file
`text` : | Text to add

### gnome_entry_append_history ()

    void        gnome_entry_append_history      (GnomeEntry *gentry,
                                                 gint save,
                                                 const gchar *text);

Adds a history item of the given `text` to the tail of the history list inside `gentry`. If `save` is `TRUE`, the history item will be saved in the config file (assuming that `gentry`'s history id is not `NULL`).

`gentry` : | Pointer to GnomeEntry object.
`save` : | If `TRUE`, history entry will be saved to config file
`text` : | Text to add

### gnome_entry_load_history ()

    void        gnome_entry_load_history        (GnomeEntry *gentry);

Loads a stored history list from the GNOME config file, if one is available. If the history id of `gentry` is `NULL`, nothing occurs.

`gentry` : | Pointer to GnomeEntry object.

### gnome_entry_save_history ()

    void        gnome_entry_save_history        (GnomeEntry *gentry);

Force the history items of the widget to be stored in a configuration file. If the history id of `gentry` is `NULL`, nothing occurs.

`gentry` : | Pointer to GnomeEntry object.

## See Also

GnomeFileEntry, GnomeIconEntry, GnomePixmapEntry, GnomeNumberEntry

<<< Previous Page | Home | Up | Next Page >>>
GnomeDruidPageFinish | GnomeFileEntry