## GnomeDbCombo

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

## Synopsis

                GnomeDbCombo;
    GType       gnome_db_combo_get_type         (void);
    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
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkComboBox
                                     +----GnomeDbCombo

## Implemented Interfaces

GnomeDbCombo implements AtkImplementorIface, 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 retreive values of the currently selected row.

## Details

### GnomeDbCombo

    typedef struct _GnomeDbCombo GnomeDbCombo;

### gnome_db_combo_get_type ()

    GType       gnome_db_combo_get_type         (void);

Returns : |

### 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.

`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);

Associate a GdaDataModel with the given combo widget. Doing so makes the combo widget refresh its list of values and display the values contained in the model, in the given position. A NULL `model` will make the combo empty and disassociate the previous model, if any.

`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 stored in the GnomeDbCombo.

`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`.

`combo` : | a GnomeDbCombo widget
`values` : | a list of GdaValue objects
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.

`combo` : | a GnomeDbCombo widget
Returns : | a new list of values

### 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 the 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 GdaValue 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 GdaValue 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`

## Property Details

### The "`model`" property

      "model"                GdaDataModel          : Read / Write