<refentry id="GnomeDbFormatEntry">
<refmeta>
<refentrytitle>GnomeDbFormatEntry</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBGNOMEDB-4.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GnomeDbFormatEntry</refname><refpurpose>A GtkEntry with formatting options</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



struct      <link linkend="GnomeDbFormatEntry-struct">GnomeDbFormatEntry</link>;
struct      <link linkend="GnomeDbFormatEntryClass">GnomeDbFormatEntryClass</link>;
struct      <link linkend="GnomeDbFormatEntryPrivate">GnomeDbFormatEntryPrivate</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-db-format-entry-new">gnome_db_format_entry_new</link>       (void);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-max-length">gnome_db_format_entry_set_max_length</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="gint">gint</link> max);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-format">gnome_db_format_entry_set_format</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *format,
                                             const <link linkend="gchar">gchar</link> *mask,
                                             const <link linkend="gchar">gchar</link> *completion);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-decimal-places">gnome_db_format_entry_set_decimal_places</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="gint">gint</link> nb_decimals);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-separators">gnome_db_format_entry_set_separators</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="guchar">guchar</link> decimal,
                                             <link linkend="guchar">guchar</link> thousands);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-edited-type">gnome_db_format_entry_set_edited_type</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="GType">GType</link> type);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-prefix">gnome_db_format_entry_set_prefix</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *prefix);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-suffix">gnome_db_format_entry_set_suffix</link>
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *suffix);
<link linkend="void">void</link>        <link linkend="gnome-db-format-entry-set-text">gnome_db_format_entry_set_text</link>  (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *text);
<link linkend="gchar">gchar</link>*      <link linkend="gnome-db-format-entry-get-text">gnome_db_format_entry_get_text</link>  (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry);

</synopsis>
</refsynopsisdiv>

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

  <link linkend="GObject">GObject</link>
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
         +----<link linkend="GtkObject">GtkObject</link>
               +----<link linkend="GtkWidget">GtkWidget</link>
                     +----<link linkend="GtkEntry">GtkEntry</link>
                           +----GnomeDbFormatEntry
</synopsis>

</refsect1>



<refsect1>
<title>Implemented Interfaces</title>
<para>
GnomeDbFormatEntry implements
 <link linkend="GtkCellEditable">GtkCellEditable</link>,  <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link> and  <link linkend="GtkEditable">GtkEditable</link>.</para>

</refsect1>


<refsect1>
<title>Properties</title>
<synopsis>

  &quot;<link linkend="GnomeDbFormatEntry--completion">completion</link>&quot;           <link linkend="gchararray">gchararray</link>           : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--decimal-sep">decimal-sep</link>&quot;          <link linkend="guchar">guchar</link>               : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--edited-type">edited-type</link>&quot;          <link linkend="guint">guint</link>                : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--format">format</link>&quot;               <link linkend="gchararray">gchararray</link>           : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--mask">mask</link>&quot;                 <link linkend="gchararray">gchararray</link>           : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--max-length">max-length</link>&quot;           <link linkend="gint">gint</link>                 : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--n-decimals">n-decimals</link>&quot;           <link linkend="gint">gint</link>                 : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--prefix">prefix</link>&quot;               <link linkend="gchararray">gchararray</link>           : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--suffix">suffix</link>&quot;               <link linkend="gchararray">gchararray</link>           : Read / Write
  &quot;<link linkend="GnomeDbFormatEntry--thousands-sep">thousands-sep</link>&quot;        <link linkend="guchar">guchar</link>               : Read / Write
</synopsis>
</refsect1>



<refsect1>
<title>Description</title>
<para>
The <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget is a <link linkend="GtkEntry"><type>GtkEntry</type></link> widget with the following additional features:
<itemizedlist>
  <listitem><para>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</para></listitem>
  <listitem><para>supports specifying a string format when the user has to enter a string with a specific format, see
  <link linkend="gnome-db-format-entry-set-format"><link linkend="gnome-db-format-entry-set-format"><function>gnome_db_format_entry_set_format()</function></link></link> for more information</para></listitem>
  <listitem><para>supports specifying the number of decimals any non integer number can have</para></listitem>
  <listitem><para>supports specifying prefix and/or a suffix strings which will always be displayed and not modifyable</para></listitem>
</itemizedlist>
</para>
</refsect1>

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

</para></refsect2>
<refsect2>
<title><anchor id="GnomeDbFormatEntryClass"/>struct GnomeDbFormatEntryClass</title>
<indexterm><primary>GnomeDbFormatEntryClass</primary></indexterm><programlisting>struct GnomeDbFormatEntryClass {

	GtkEntryClass              parent_class;
};
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GnomeDbFormatEntryPrivate"/>struct GnomeDbFormatEntryPrivate</title>
<indexterm><primary>GnomeDbFormatEntryPrivate</primary></indexterm><programlisting>struct GnomeDbFormatEntryPrivate;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-new"/>gnome_db_format_entry_new ()</title>
<indexterm><primary>gnome_db_format_entry_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_db_format_entry_new       (void);</programlisting>
<para>
Creates a new <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly created <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-max-length"/>gnome_db_format_entry_set_max_length ()</title>
<indexterm><primary>gnome_db_format_entry_set_max_length</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_max_length
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="gint">gint</link> max);</programlisting>
<para>
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.
</para>
<para>
The difference with <link linkend="gtk-entry-set-max-length"><function>gtk_entry_set_max_length()</function></link> is that the max length does not take into account
the prefix and/or suffix parts which may have been set.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max</parameter>&nbsp;:</term>
<listitem><simpara> the maximum length of the entry, or 0 for no maximum.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-format"/>gnome_db_format_entry_set_format ()</title>
<indexterm><primary>gnome_db_format_entry_set_format</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_format
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *format,
                                             const <link linkend="gchar">gchar</link> *mask,
                                             const <link linkend="gchar">gchar</link> *completion);</programlisting>
<para>
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:
<itemizedlist>
  <listitem><para>'0': digits</para></listitem>
  <listitem><para>'9': digits excluded 0</para></listitem>
  <listitem><para>'@': alpha</para></listitem>
  <listitem><para>'^': alpha converted to upper case</para></listitem>
  <listitem><para>'#': alphanumeric</para></listitem>
  <listitem><para>'*': any char</para></listitem>
</itemizedlist>
</para>
<para>
if <parameter>mask</parameter> is not <literal>NULL</literal>, then it must contain the exact same number of characters as <parameter>format</parameter>; 
it is then interpreted in the following way: for a character C in <parameter>format</parameter>, if the character at the same
position in <parameter>mask</parameter> is the space character (' '), then C will not interpreted as a writable format
character as defined above.
</para>
<para>
if <parameter>completion</parameter> is not <literal>NULL</literal>, then it must contain the exact same number of characters as <parameter>format</parameter>. 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
<parameter>format</parameter> string, then the character at a position P in this string is used.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
<listitem><simpara> the format specification of the data to edit
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mask</parameter>&nbsp;:</term>
<listitem><simpara> a 'mask' string helping understand <parameter>format</parameter>, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>completion</parameter>&nbsp;:</term>
<listitem><simpara> a 'completions' string, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-decimal-places"/>gnome_db_format_entry_set_decimal_places ()</title>
<indexterm><primary>gnome_db_format_entry_set_decimal_places</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_decimal_places
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="gint">gint</link> nb_decimals);</programlisting>
<para>
Sets the number of decimals which must be displayed in <parameter>entry</parameter> when entering
a non integer numerical value</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>nb_decimals</parameter>&nbsp;:</term>
<listitem><simpara> the number of decimals which must be displayed in <parameter>entry</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-separators"/>gnome_db_format_entry_set_separators ()</title>
<indexterm><primary>gnome_db_format_entry_set_separators</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_separators
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="guchar">guchar</link> decimal,
                                             <link linkend="guchar">guchar</link> thousands);</programlisting>
<para>
Sets the decimal and thousands separators to use within <parameter>entry</parameter> when it contains a numerical value</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>decimal</parameter>&nbsp;:</term>
<listitem><simpara> the character to use as a decimal separator, or 0 for default (locale specific) separator
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>thousands</parameter>&nbsp;:</term>
<listitem><simpara> the character to use as a thousands separator, or 0 for no separator at all
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-edited-type"/>gnome_db_format_entry_set_edited_type ()</title>
<indexterm><primary>gnome_db_format_entry_set_edited_type</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_edited_type
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             <link linkend="GType">GType</link> type);</programlisting>
<para>
Specifies what type of data is edited in <parameter>entry</parameter></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&nbsp;:</term>
<listitem><simpara> the type of data expected to be edited <parameter>entry</parameter> itself returns a string,
       <parameter>type</parameter> specifies into what type that string will be converted)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-prefix"/>gnome_db_format_entry_set_prefix ()</title>
<indexterm><primary>gnome_db_format_entry_set_prefix</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_prefix
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *prefix);</programlisting>
<para>
Sets <parameter>prefix</parameter> as a prefix string of <parameter>entry</parameter>: that string will always be displayed in the
text entry, will not be modifiable, and won't be part of the returned text</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter>&nbsp;:</term>
<listitem><simpara> a prefix string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-suffix"/>gnome_db_format_entry_set_suffix ()</title>
<indexterm><primary>gnome_db_format_entry_set_suffix</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_suffix
                                            (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *suffix);</programlisting>
<para>
Sets <parameter>suffix</parameter> as a suffix string of <parameter>entry</parameter>: that string will always be displayed in the
text entry, will not be modifiable, and won't be part of the returned text</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>suffix</parameter>&nbsp;:</term>
<listitem><simpara> a suffix string
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-set-text"/>gnome_db_format_entry_set_text ()</title>
<indexterm><primary>gnome_db_format_entry_set_text</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_format_entry_set_text  (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry,
                                             const <link linkend="gchar">gchar</link> *text);</programlisting>
<para>
Sets <parameter>text</parameter> into <parameter>entry</parameter>. 
</para>
<para>
As a side effect, if <parameter>text</parameter> is <literal>NULL</literal>, then the entry will
be completely empty, whereas if <parameter>text</parameter> is the empty string (""), then
<parameter>entry</parameter> 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
<link linkend="gtk-entry-set-text"><function>gtk_entry_set_text()</function></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
<listitem><simpara> the text to set into <parameter>entry</parameter>, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-format-entry-get-text"/>gnome_db_format_entry_get_text ()</title>
<indexterm><primary>gnome_db_format_entry_get_text</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*      gnome_db_format_entry_get_text  (<link linkend="GnomeDbFormatEntry">GnomeDbFormatEntry</link> *entry);</programlisting>
<para>
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 <link linkend="gtk-entry-get-text"><function>gtk_entry_get_text()</function></link> since the latest will return the complete text
in <parameter>entry</parameter> including prefix and/or suffix and/or format.
</para>
<para>
Note: <literal>NULL</literal> may be returned if this method is called while the widget is working on some
internal modifications, or if <link linkend="gnome-db-format-entry-set-text"><function>gnome_db_format_entry_set_text()</function></link> was called with a <literal>NULL</literal>
as its <parameter>text</parameter> argument.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>entry</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbFormatEntry"><type>GnomeDbFormatEntry</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new string, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1>
<title>Properties</title>
<variablelist>
<varlistentry><term><anchor id="GnomeDbFormatEntry--completion"/>&quot;<literal>completion</literal>&quot; (<link linkend="gchararray">gchararray</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--decimal-sep"/>&quot;<literal>decimal-sep</literal>&quot; (<link linkend="guchar">guchar</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--edited-type"/>&quot;<literal>edited-type</literal>&quot; (<link linkend="guint">guint</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--format"/>&quot;<literal>format</literal>&quot; (<link linkend="gchararray">gchararray</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--mask"/>&quot;<literal>mask</literal>&quot; (<link linkend="gchararray">gchararray</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--max-length"/>&quot;<literal>max-length</literal>&quot; (<link linkend="gint">gint</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--n-decimals"/>&quot;<literal>n-decimals</literal>&quot; (<link linkend="gint">gint</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--prefix"/>&quot;<literal>prefix</literal>&quot; (<link linkend="gchararray">gchararray</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--suffix"/>&quot;<literal>suffix</literal>&quot; (<link linkend="gchararray">gchararray</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>
<varlistentry><term><anchor id="GnomeDbFormatEntry--thousands-sep"/>&quot;<literal>thousands-sep</literal>&quot; (<link linkend="guchar">guchar</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>

</variablelist>
</refsect1>




</refentry>
