<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 <gnome.h> 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> :</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> :</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> :</entry> <entry> Pointer to GnomeEntry object. </entry></row> <row><entry align="right"><parameter>history_id</parameter> :</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> :</entry> <entry> Pointer to GnomeEntry object. </entry></row> <row><entry align="right"><parameter>save</parameter> :</entry> <entry> If <literal>TRUE</literal>, history entry will be saved to config file </entry></row> <row><entry align="right"><parameter>text</parameter> :</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> :</entry> <entry> Pointer to GnomeEntry object. </entry></row> <row><entry align="right"><parameter>save</parameter> :</entry> <entry> If <literal>TRUE</literal>, history entry will be saved to config file </entry></row> <row><entry align="right"><parameter>text</parameter> :</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> :</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> :</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>