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

<refnamediv>
<refname>GnomeDbCombo</refname><refpurpose>A combo box with data to be displayed as a <link linkend="GdaDataModel"><type>GdaDataModel</type></link></refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



struct      <link linkend="GnomeDbCombo-struct">GnomeDbCombo</link>;
struct      <link linkend="GnomeDbComboClass">GnomeDbComboClass</link>;
struct      <link linkend="GnomeDbComboPrivate">GnomeDbComboPrivate</link>;
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-db-combo-new">gnome_db_combo_new</link>              (void);
<link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gnome-db-combo-new-with-model">gnome_db_combo_new_with_model</link>   (<link linkend="GdaDataModel">GdaDataModel</link> *model,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);
<link linkend="void">void</link>        <link linkend="gnome-db-combo-set-model">gnome_db_combo_set_model</link>        (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="GdaDataModel">GdaDataModel</link> *model,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);
<link linkend="GdaDataModel">GdaDataModel</link>* <link linkend="gnome-db-combo-get-model">gnome_db_combo_get_model</link>      (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);
<link linkend="void">void</link>        <link linkend="gnome-db-combo-add-undef-choice">gnome_db_combo_add_undef_choice</link> (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="gboolean">gboolean</link> add_undef_choice);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-db-combo-set-values">gnome_db_combo_set_values</link>       (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             const <link linkend="GSList">GSList</link> *values);
<link linkend="GSList">GSList</link>*     <link linkend="gnome-db-combo-get-values">gnome_db_combo_get_values</link>       (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-db-combo-undef-selected">gnome_db_combo_undef_selected</link>   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);
<link linkend="gboolean">gboolean</link>    <link linkend="gnome-db-combo-set-values-ext">gnome_db_combo_set_values_ext</link>   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             const <link linkend="GSList">GSList</link> *values,
                                             <link linkend="gint">gint</link> *cols_index);
<link linkend="GSList">GSList</link>*     <link linkend="gnome-db-combo-get-values-ext">gnome_db_combo_get_values_ext</link>   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);

</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="GtkContainer">GtkContainer</link>
                           +----<link linkend="GtkBin">GtkBin</link>
                                 +----<link linkend="GtkComboBox">GtkComboBox</link>
                                       +----GnomeDbCombo
                                             +----<link linkend="GnomeDbDsnSelector">GnomeDbDsnSelector</link>
                                             +----<link linkend="GnomeDbProviderSelector">GnomeDbProviderSelector</link>
</synopsis>

</refsect1>



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

</refsect1>


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

  &quot;<link linkend="GnomeDbCombo--model">model</link>&quot;                <link linkend="GdaDataModel">GdaDataModel</link>         : Read / Write
</synopsis>
</refsect1>



<refsect1>
<title>Description</title>
<para>
This widget acts like the <link linkend="GtkComboBox"><type>GtkComboBox</type></link> widget which it inherits, 
but displays data from a provided <link linkend="GdaDataModel"><type>GdaDataModel</type></link>
and it is easy to set the currently selected row or retrieve values of the currently selected row.
</para>
<para>
Specifically it is possible to show only some columns of the data model when using the
<link linkend="gnome-db-combo-new-with-model"><function>gnome_db_combo_new_with_model()</function></link> and <link linkend="gnome-db-combo-set-model"><function>gnome_db_combo_set_model()</function></link> functions by passing these functions
an array of integers (containing the column number of each column to display), and the size of
that array.
</para>
</refsect1>

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

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

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

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

</para></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-new"/>gnome_db_combo_new ()</title>
<indexterm><primary>gnome_db_combo_new</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_db_combo_new              (void);</programlisting>
<para>
Create a new GnomeDbCombo widget.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created widget.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-new-with-model"/>gnome_db_combo_new_with_model ()</title>
<indexterm><primary>gnome_db_combo_new_with_model</primary></indexterm><programlisting><link linkend="GtkWidget">GtkWidget</link>*  gnome_db_combo_new_with_model   (<link linkend="GdaDataModel">GdaDataModel</link> *model,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);</programlisting>
<para>
Create a new GnomeDbCombo widget with a model. See <link linkend="gnome-db-combo-set-model"><function>gnome_db_combo_set_model()</function></link> for
more information about the <parameter>n_cols</parameter> and <parameter>cols_index</parameter> usage.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>model</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GdaDataModel"><type>GdaDataModel</type></link> object.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_cols</parameter>&nbsp;:</term>
<listitem><simpara> number of columns in the model to be shown
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cols_index</parameter>&nbsp;:</term>
<listitem><simpara> index of each column to be shown
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the newly-created widget.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-set-model"/>gnome_db_combo_set_model ()</title>
<indexterm><primary>gnome_db_combo_set_model</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_combo_set_model        (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="GdaDataModel">GdaDataModel</link> *model,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);</programlisting>
<para>
Makes <parameter>combo</parameter> display data stored in <parameter>model</parameter> (makes the
combo widget refresh its list of values and display the values contained
in the model). A NULL <parameter>model</parameter> will make the combo empty
and disassociate the previous model, if any.
</para>
<para>
if <parameter>n_cols</parameter> is 0, then all the columns of <parameter>model</parameter> will be displayed in <parameter>combo</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>model</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GdaDataModel"><type>GdaDataModel</type></link> object.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_cols</parameter>&nbsp;:</term>
<listitem><simpara> number of columns in the model to be shown
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cols_index</parameter>&nbsp;:</term>
<listitem><simpara> index of each column to be shown
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-get-model"/>gnome_db_combo_get_model ()</title>
<indexterm><primary>gnome_db_combo_get_model</primary></indexterm><programlisting><link linkend="GdaDataModel">GdaDataModel</link>* gnome_db_combo_get_model      (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);</programlisting>
<para>
This function returns the <link linkend="GdaDataModel"><type>GdaDataModel</type></link> from which <parameter>combo</parameter> displays values.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a <link linkend="GdaDataModel"><type>GdaDataModel</type></link> containing the data from the <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-add-undef-choice"/>gnome_db_combo_add_undef_choice ()</title>
<indexterm><primary>gnome_db_combo_add_undef_choice</primary></indexterm><programlisting><link linkend="void">void</link>        gnome_db_combo_add_undef_choice (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="gboolean">gboolean</link> add_undef_choice);</programlisting>
<para>
Tells if <parameter>combo</parameter> should add a special entry representing an "undefined choice". The default is
that only the available choices in <parameter>combo</parameter>'s model are presented.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>add_undef_choice</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-set-values"/>gnome_db_combo_set_values ()</title>
<indexterm><primary>gnome_db_combo_set_values</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_db_combo_set_values       (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             const <link linkend="GSList">GSList</link> *values);</programlisting>
<para>
Sets the currently selected row of <parameter>combo</parameter> from the values stored in <parameter>values</parameter>. 
</para>
<para>
WARNING: <parameter>values</parameter> must contain one value for each column set to be displayed when the
data model was associated to <parameter>combo</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>values</parameter>&nbsp;:</term>
<listitem><simpara> a list of <link linkend="GValue"><type>GValue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if a row in the model was found to match the list of values.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-get-values"/>gnome_db_combo_get_values ()</title>
<indexterm><primary>gnome_db_combo_get_values</primary></indexterm><programlisting><link linkend="GSList">GSList</link>*     gnome_db_combo_get_values       (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);</programlisting>
<para>
Get a list of the currently selected values in <parameter>combo</parameter>. The list itself must be free'd using <link linkend="g-slist-free"><function>g_slist_free()</function></link>, 
but not the values it contains.
</para>
<para>
WARNING: <parameter>values</parameter> will contain one value for each column set to be displayed when the
data model was associated to <parameter>combo</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new list of values, or <literal>NULL</literal> if there is no displayed data in <parameter>combo</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-undef-selected"/>gnome_db_combo_undef_selected ()</title>
<indexterm><primary>gnome_db_combo_undef_selected</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_db_combo_undef_selected   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo);</programlisting>
<para>
Tell if the currently selected entry represents the "undefined choice" entry.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-set-values-ext"/>gnome_db_combo_set_values_ext ()</title>
<indexterm><primary>gnome_db_combo_set_values_ext</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    gnome_db_combo_set_values_ext   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             const <link linkend="GSList">GSList</link> *values,
                                             <link linkend="gint">gint</link> *cols_index);</programlisting>
<para>
Sets the currently selected row of <parameter>combo</parameter> from the values stored in <parameter>values</parameter>, assuming that
these values correspond to the columns listed in <parameter>cols_index</parameter>. <parameter>cols_index</parameter> must contain at least as
many <link linkend="gint"><type>gint</type></link> as there are elements in <parameter>values</parameter>;
</para>
<para>
if <parameter>cols_index</parameter> is <literal>NULL</literal>, then it is assumed that <parameter>values</parameter> has the same number of columns 
than <parameter>combo</parameter>'s data
model and that the values in <parameter>values</parameter> are ordered in the same way as the columns of 
<parameter>combo</parameter>'s data model.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>values</parameter>&nbsp;:</term>
<listitem><simpara> a list of <link linkend="GValue"><type>GValue</type></link> objects
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cols_index</parameter>&nbsp;:</term>
<listitem><simpara> array of gint, index of column to which each value in <parameter>values</parameter> corresponds, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> TRUE if a row in the model was found to match the list of values.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="gnome-db-combo-get-values-ext"/>gnome_db_combo_get_values_ext ()</title>
<indexterm><primary>gnome_db_combo_get_values_ext</primary></indexterm><programlisting><link linkend="GSList">GSList</link>*     gnome_db_combo_get_values_ext   (<link linkend="GnomeDbCombo">GnomeDbCombo</link> *combo,
                                             <link linkend="gint">gint</link> n_cols,
                                             <link linkend="gint">gint</link> *cols_index);</programlisting>
<para>
Get a list of the currently selected values in <parameter>combo</parameter>. The list itself must be free'd using <link linkend="g-slist-free"><function>g_slist_free()</function></link>, 
but not the values it contains. If there is no selected value in <parameter>combo</parameter>, then <literal>NULL</literal> is returned.
</para>
<para>
if n_cols equals 0 and <parameter>cols_index</parameter> is <literal>NULL</literal>, then a <link linkend="GValue"><type>GValue</type></link> will be returned for each column of <parameter>combo</parameter>'s data model.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>combo</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="GnomeDbCombo"><type>GnomeDbCombo</type></link> widget
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_cols</parameter>&nbsp;:</term>
<listitem><simpara> the number of columns for which values are requested
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cols_index</parameter>&nbsp;:</term>
<listitem><simpara> an array of <parameter>n_cols</parameter> <link linkend="gint"><type>gint</type></link> indicating which column to get a value for, or <literal>NULL</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new list of values, or <literal>NULL</literal> if there is no displayed data in <parameter>combo</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1>
<title>Properties</title>
<variablelist>
<varlistentry><term><anchor id="GnomeDbCombo--model"/>&quot;<literal>model</literal>&quot; (<link linkend="GdaDataModel">GdaDataModel</link> : Read / Write)</term>
<listitem>
<para></para>
</listitem></varlistentry>

</variablelist>
</refsect1>




</refentry>
