<refentry id="GnomeEntry">
<refmeta>
<refentrytitle>GnomeEntry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOMEUI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GnomeEntry</refname><refpurpose>Entry widget with history tracking.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gnome.h&gt;


struct      <link linkend="GnomeEntry-struct">GnomeEntry</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-entry-new">gnome_entry_new</link>                 (const <link linkend="gchar">gchar</link> *history_id);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-entry-gtk-entry">gnome_entry_gtk_entry</link>           (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);
void        <link linkend="gnome-entry-set-history-id">gnome_entry_set_history_id</link>      (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             const <link linkend="gchar">gchar</link> *history_id);
void        <link linkend="gnome-entry-prepend-history">gnome_entry_prepend_history</link>     (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             <link linkend="gint">gint</link> save,
                                             const <link linkend="gchar">gchar</link> *text);
void        <link linkend="gnome-entry-append-history">gnome_entry_append_history</link>      (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             <link linkend="gint">gint</link> save,
                                             const <link linkend="gchar">gchar</link> *text);
void        <link linkend="gnome-entry-load-history">gnome_entry_load_history</link>        (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);
void        <link linkend="gnome-entry-save-history">gnome_entry_save_history</link>        (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);

</synopsis>
</refsynopsisdiv>

<refsect1>
<title>Object Hierarchy</title>
<synopsis>

  <link linkend="GtkObject">GtkObject</link>
   +----<link linkend="GtkWidget">GtkWidget</link>
         +----<link linkend="GtkContainer">GtkContainer</link>
               +----<link linkend="GtkBox">GtkBox</link>
                     +----<link linkend="GtkHBox">GtkHBox</link>
                           +----<link linkend="GtkCombo">GtkCombo</link>
                                 +----GnomeEntry
</synopsis>

</refsect1>




<refsect1>
<title>Description</title>
<para>
  This widget is a wrapper around the <link linkend="GtkEntry">GtkEntry</link> 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 <type>GnomeEntry</type> widget, and this identifier
  is used to load and save the history of the text.
</para>

<para>
  Here is an example of how to use the widget

  <example>
     <title>Sample usage of the GnomeEntry widget</title>
     <programlisting>
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));
     </programlisting>
  </example>
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GnomeEntry-struct">struct GnomeEntry</title>
<programlisting>struct GnomeEntry;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-entry-new">gnome_entry_new ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_entry_new                 (const <link linkend="gchar">gchar</link> *history_id);</programlisting>
<para>
Creates a new GnomeEntry widget.  If  <parameter>history_id</parameter> is
not <literal>NULL</literal>, then the history list will be saved and restored between
uses under the given id.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>history_id</parameter>&nbsp;:</entry>
<entry> If not <literal>NULL</literal>, the text id under which history data is stored
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Newly-created GnomeEntry widget.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-gtk-entry">gnome_entry_gtk_entry ()</title>
<programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_entry_gtk_entry           (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);</programlisting>
<para>
Obtain pointer to GnomeEntry's internal text entry</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Pointer to GtkEntry widget.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-set-history-id">gnome_entry_set_history_id ()</title>
<programlisting>void        gnome_entry_set_history_id      (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             const <link linkend="gchar">gchar</link> *history_id);</programlisting>
<para>
Set or clear the history id of the GnomeEntry widget.  If
<parameter>history_id</parameter> is <literal>NULL</literal>, the widget's history id is cleared.  Otherwise,
the given id replaces the previous widget history id.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
<row><entry align="right"><parameter>history_id</parameter>&nbsp;:</entry>
<entry> If not <literal>NULL</literal>, the text id under which history data is stored
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-prepend-history">gnome_entry_prepend_history ()</title>
<programlisting>void        gnome_entry_prepend_history     (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             <link linkend="gint">gint</link> save,
                                             const <link linkend="gchar">gchar</link> *text);</programlisting>
<para>
Adds a history item of the given <parameter>text</parameter> to the head of
the history list inside <parameter>gentry</parameter>.  If <parameter>save</parameter> is <literal>TRUE</literal>, the history
item will be saved in the config file (assuming that <parameter>gentry</parameter>'s
history id is not <literal>NULL</literal>).</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
<row><entry align="right"><parameter>save</parameter>&nbsp;:</entry>
<entry> If <literal>TRUE</literal>, history entry will be saved to config file
</entry></row>
<row><entry align="right"><parameter>text</parameter>&nbsp;:</entry>
<entry> Text to add
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-append-history">gnome_entry_append_history ()</title>
<programlisting>void        gnome_entry_append_history      (<link linkend="GnomeEntry">GnomeEntry</link> *gentry,
                                             <link linkend="gint">gint</link> save,
                                             const <link linkend="gchar">gchar</link> *text);</programlisting>
<para>
Adds a history item of the given <parameter>text</parameter> to the tail
of the history list inside <parameter>gentry</parameter>.  If <parameter>save</parameter> is <literal>TRUE</literal>, the
history item will be saved in the config file (assuming that
<parameter>gentry</parameter>'s history id is not <literal>NULL</literal>).</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
<row><entry align="right"><parameter>save</parameter>&nbsp;:</entry>
<entry> If <literal>TRUE</literal>, history entry will be saved to config file
</entry></row>
<row><entry align="right"><parameter>text</parameter>&nbsp;:</entry>
<entry> Text to add
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-load-history">gnome_entry_load_history ()</title>
<programlisting>void        gnome_entry_load_history        (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);</programlisting>
<para>
Loads a stored history list from the GNOME config file,
if one is available.  If the history id of <parameter>gentry</parameter> is <literal>NULL</literal>,
nothing occurs.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-entry-save-history">gnome_entry_save_history ()</title>
<programlisting>void        gnome_entry_save_history        (<link linkend="GnomeEntry">GnomeEntry</link> *gentry);</programlisting>
<para>
Force the history items of the widget to be stored
in a configuration file.  If the history id of <parameter>gentry</parameter> is <literal>NULL</literal>,
nothing occurs.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>gentry</parameter>&nbsp;:</entry>
<entry> Pointer to GnomeEntry object.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
  <link linkend="GnomeFileEntry">GnomeFileEntry</link>, <link linkend="GnomeIconEntry">GnomeIconEntry</link>, <link linkend="GnomePixmapEntry">GnomePixmapEntry</link>, <link linkend="GnomeNumberEntry">GnomeNumberEntry</link>
</para>
</refsect1>

</refentry>