## GnomeDbCombo GnomeDbCombo — A combo box with data to be displayed as a GdaDataModel |

## Synopsis

                        GnomeDbCombo;
                        GnomeDbComboClass;
                        GnomeDbComboPrivate;
    GtkWidget*          gnome_db_combo_new                  (void);
    GtkWidget*          gnome_db_combo_new_with_model       (GdaDataModel *model,
                                                             gint n_cols,
                                                             gint *cols_index);
    void                gnome_db_combo_set_model            (GnomeDbCombo *combo,
                                                             GdaDataModel *model,
                                                             gint n_cols,
                                                             gint *cols_index);
    GdaDataModel*       gnome_db_combo_get_model            (GnomeDbCombo *combo);
    void                gnome_db_combo_add_undef_choice     (GnomeDbCombo *combo,
                                                             gboolean add_undef_choice);
    gboolean            gnome_db_combo_set_values           (GnomeDbCombo *combo,
                                                             const GSList *values);
    GSList*             gnome_db_combo_get_values           (GnomeDbCombo *combo);
    gboolean            gnome_db_combo_undef_selected       (GnomeDbCombo *combo);
    gboolean            gnome_db_combo_set_values_ext       (GnomeDbCombo *combo,
                                                             const GSList *values,
                                                             gint *cols_index);
    GSList*             gnome_db_combo_get_values_ext       (GnomeDbCombo *combo,
                                                             gint n_cols,
                                                             gint *cols_index);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkComboBox
                                           +----GnomeDbCombo
                                                 +----GnomeDbDsnSelector
                                                 +----GnomeDbProviderSelector

## Implemented Interfaces

GnomeDbCombo implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Properties

      "model"                    GdaDataModel*         : Read / Write

## Description

This widget acts like the GtkComboBox widget which it inherits, but displays data from a provided GdaDataModel and it is easy to set the currently selected row or retrieve values of the currently selected row.

Specifically it is possible to show only some columns of the data model when using the `gnome_db_combo_new_with_model()` and `gnome_db_combo_set_model()` functions by passing these functions an array of integers (containing the column number of each column to display), and the size of that array.

## Details

### GnomeDbCombo

    typedef struct _GnomeDbCombo GnomeDbCombo;

### GnomeDbComboClass

    typedef struct {
    	GtkComboBoxClass     parent_class;
    } GnomeDbComboClass;

### GnomeDbComboPrivate

    typedef struct _GnomeDbComboPrivate GnomeDbComboPrivate;

### gnome_db_combo_new ()

    GtkWidget*          gnome_db_combo_new                  (void);

Create a new GnomeDbCombo widget.

Returns : | the newly-created widget.

### gnome_db_combo_new_with_model ()

    GtkWidget*          gnome_db_combo_new_with_model       (GdaDataModel *model,
                                                             gint n_cols,
                                                             gint *cols_index);

Create a new GnomeDbCombo widget with a model. See `gnome_db_combo_set_model()` for more information about the `n_cols` and `cols_index` usage.

`model` : | a GdaDataModel object.
`n_cols` : | number of columns in the model to be shown
`cols_index` : | index of each column to be shown
Returns : | the newly-created widget.

### gnome_db_combo_set_model ()

    void                gnome_db_combo_set_model            (GnomeDbCombo *combo,
                                                             GdaDataModel *model,
                                                             gint n_cols,
                                                             gint *cols_index);

Makes `combo` display data stored in `model` (makes the combo widget refresh its list of values and display the values contained in the model). A NULL `model` will make the combo empty and disassociate the previous model, if any.

if `n_cols` is 0, then all the columns of `model` will be displayed in `combo`.

`combo` : | a GnomeDbCombo widget.
`model` : | a GdaDataModel object.
`n_cols` : | number of columns in the model to be shown
`cols_index` : | index of each column to be shown

### gnome_db_combo_get_model ()

    GdaDataModel*       gnome_db_combo_get_model            (GnomeDbCombo *combo);

This function returns the GdaDataModel from which `combo` displays values.

`combo` : | a GnomeDbCombo widget.
Returns : | a GdaDataModel containing the data from the GnomeDbCombo widget.

### gnome_db_combo_add_undef_choice ()

    void                gnome_db_combo_add_undef_choice     (GnomeDbCombo *combo,
                                                             gboolean add_undef_choice);

Tells if `combo` should add a special entry representing an "undefined choice". The default is that only the available choices in `combo`'s model are presented.

`combo` : | a GnomeDbCombo widget
`add_undef_choice` : |

### gnome_db_combo_set_values ()

    gboolean            gnome_db_combo_set_values           (GnomeDbCombo *combo,
                                                             const GSList *values);

Sets the currently selected row of `combo` from the values stored in `values`.

WARNING: `values` must contain one value for each column set to be displayed when the data model was associated to `combo`.

`combo` : | a GnomeDbCombo widget
`values` : | a list of GValue
Returns : | TRUE if a row in the model was found to match the list of values.

### gnome_db_combo_get_values ()

    GSList*             gnome_db_combo_get_values           (GnomeDbCombo *combo);

Get a list of the currently selected values in `combo`. The list itself must be free'd using `g_slist_free()`, but not the values it contains.

WARNING: `values` will contain one value for each column set to be displayed when the data model was associated to `combo`.

`combo` : | a GnomeDbCombo widget
Returns : | a new list of values, or `NULL` if there is no displayed data in `combo`.

### gnome_db_combo_undef_selected ()

    gboolean            gnome_db_combo_undef_selected       (GnomeDbCombo *combo);

Tell if the currently selected entry represents the "undefined choice" entry.

`combo` : | a GnomeDbCombo widget
Returns : |

### gnome_db_combo_set_values_ext ()

    gboolean            gnome_db_combo_set_values_ext       (GnomeDbCombo *combo,
                                                             const GSList *values,
                                                             gint *cols_index);

Sets the currently selected row of `combo` from the values stored in `values`, assuming that these values correspond to the columns listed in `cols_index`. `cols_index` must contain at least as many gint as there are elements in `values`;

if `cols_index` is `NULL`, then it is assumed that `values` has the same number of columns than `combo`'s data model and that the values in `values` are ordered in the same way as the columns of `combo`'s data model.

`combo` : | a GnomeDbCombo widget
`values` : | a list of GValue objects
`cols_index` : | array of gint, index of column to which each value in `values` corresponds, or `NULL`
Returns : | TRUE if a row in the model was found to match the list of values.

### gnome_db_combo_get_values_ext ()

    GSList*             gnome_db_combo_get_values_ext       (GnomeDbCombo *combo,
                                                             gint n_cols,
                                                             gint *cols_index);

Get a list of the currently selected values in `combo`. The list itself must be free'd using `g_slist_free()`, but not the values it contains. If there is no selected value in `combo`, then `NULL` is returned.

if n_cols equals 0 and `cols_index` is `NULL`, then a GValue will be returned for each column of `combo`'s data model.

`combo` : | a GnomeDbCombo widget
`n_cols` : | the number of columns for which values are requested
`cols_index` : | an array of `n_cols` gint indicating which column to get a value for, or `NULL`
Returns : | a new list of values, or `NULL` if there is no displayed data in `combo`.

## Property Details

### The `"model"` property

      "model"                    GdaDataModel*         : Read / Write