## GdictDatabaseChooser

GdictDatabaseChooser — Display the list of available databases

## Synopsis

                        GdictDatabaseChooser;
                        GdictDatabaseChooserClass;
    GtkWidget*          gdict_database_chooser_new          (void);
    GtkWidget*          gdict_database_chooser_new_with_context
                                                            (GdictContext *context);
    GdictContext*       gdict_database_chooser_get_context  (GdictDatabaseChooser *chooser);
    void                gdict_database_chooser_set_context  (GdictDatabaseChooser *chooser,
                                                             GdictContext *context);
    gchar**             gdict_database_chooser_get_databases
                                                            (GdictDatabaseChooser *chooser,
                                                             gsize *length);
    gint                gdict_database_chooser_count_databases
                                                            (GdictDatabaseChooser *chooser);
    gboolean            gdict_database_chooser_has_database (GdictDatabaseChooser *chooser,
                                                             const gchar *database);
    void                gdict_database_chooser_refresh      (GdictDatabaseChooser *chooser);
    void                gdict_database_chooser_clear        (GdictDatabaseChooser *chooser);
    GtkWidget*          gdict_database_chooser_add_button   (GdictDatabaseChooser *chooser,
                                                             const gchar *button_text);
    gchar*              gdict_database_chooser_get_current_database
                                                            (GdictDatabaseChooser *chooser);
    gboolean            gdict_database_chooser_select_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);
    gboolean            gdict_database_chooser_set_current_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);
    gboolean            gdict_database_chooser_unselect_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkVBox
                                           +----GdictDatabaseChooser

## Implemented Interfaces

GdictDatabaseChooser implements AtkImplementorIface and GtkBuildable.

## Properties

      "context"                  GdictContext*         : Read / Write / Construct
      "count"                    gint                  : Read

## Signals

      "database-activated"                             : Run Last
      "selection-changed"                              : Run Last

## Description

Each GdictContext has a list of databases, that is dictionaries that can be queried. GdictDatabaseChooser is a widget that queries a given GdictContext and displays the list of available databases.

GdictDatabaseChooser is available since Gdict 0.10

## Details

### GdictDatabaseChooser

    typedef struct _GdictDatabaseChooser GdictDatabaseChooser;

### GdictDatabaseChooserClass

    typedef struct {
      void (*database_activated) (GdictDatabaseChooser *chooser,
    		  	      const gchar          *name,
    			      const gchar          *description);
      void (*selection_changed)  (GdictDatabaseChooser *chooser);
    } GdictDatabaseChooserClass;

### gdict_database_chooser_new ()

    GtkWidget*          gdict_database_chooser_new          (void);

Creates a new GdictDatabaseChooser widget. A Database chooser widget can be used to display the list of available databases on a dictionary source using the GdictContext representing it. After creation, the GdictContext can be set using `gdict_database_chooser_set_context()`.

Returns : | the newly created GdictDatabaseChooser widget.

Since 0.10

### gdict_database_chooser_new_with_context ()

    GtkWidget*          gdict_database_chooser_new_with_context
                                                            (GdictContext *context);

Creates a new GdictDatabaseChooser, using `context` as the representation of the dictionary source to query for the list of available databases.

`context` : | a GdictContext
Returns : | the newly created GdictDatabaseChooser widget.

Since 0.10

### gdict_database_chooser_get_context ()

    GdictContext*       gdict_database_chooser_get_context  (GdictDatabaseChooser *chooser);

Retrieves the GdictContext used by `chooser`.

`chooser` : | a GdictDatabaseChooser
Returns : | a GdictContext or `NULL`

Since 0.10

### gdict_database_chooser_set_context ()

    void                gdict_database_chooser_set_context  (GdictDatabaseChooser *chooser,
                                                             GdictContext *context);

Sets the GdictContext to be used to query a dictionary source for the list of available databases.

`chooser` : | a GdictDatabaseChooser
`context` : | a GdictContext

Since 0.10

### gdict_database_chooser_get_databases ()

    gchar**             gdict_database_chooser_get_databases
                                                            (GdictDatabaseChooser *chooser,
                                                             gsize *length);

Gets the list of available database names.

`chooser` : | a GdictDatabaseChooser
`length` : | return location for the length of the returned vector
Returns : | a newly allocated, `NULL` terminated string vector containing database names. Use `g_strfreev()` to deallocate it.

Since 0.10

### gdict_database_chooser_count_databases ()

    gint                gdict_database_chooser_count_databases
                                                            (GdictDatabaseChooser *chooser);

Returns the number of databases found.

`chooser` : | a GdictDatabaseChooser
Returns : | the number of databases or -1 if no context is set

Since 0.10

### gdict_database_chooser_has_database ()

    gboolean            gdict_database_chooser_has_database (GdictDatabaseChooser *chooser,
                                                             const gchar *database);

Checks whether the `chooser` displays `database`

`chooser` : | a GdictDatabaseChooser
`database` : | the name of a database
Returns : | `TRUE` if the search database name is present

Since 0.10

### gdict_database_chooser_refresh ()

    void                gdict_database_chooser_refresh      (GdictDatabaseChooser *chooser);

Reloads the list of available databases.

`chooser` : | a GdictDatabaseChooser

Since 0.10

### gdict_database_chooser_clear ()

    void                gdict_database_chooser_clear        (GdictDatabaseChooser *chooser);

Clears `chooser`.

`chooser` : | a GdictDatabaseChooser

Since 0.10

### gdict_database_chooser_add_button ()

    GtkWidget*          gdict_database_chooser_add_button   (GdictDatabaseChooser *chooser,
                                                             const gchar *button_text);

Adds a GtkButton with `button_text` to the button area on the bottom of `chooser`. The `button_text` can also be a stock ID.

`chooser` : | a GdictDatabase
`button_text` : | text of the button
Returns : | the newly packed button.

Since 0.10

### gdict_database_chooser_get_current_database ()

    gchar*              gdict_database_chooser_get_current_database
                                                            (GdictDatabaseChooser *chooser);

Retrieves the name of the currently selected database inside `chooser`

`chooser` : | a GdictDatabaseChooser
Returns : | the name of the selected database. Use `g_free()` on the returned string when done using it

Since 0.10

### gdict_database_chooser_select_database ()

    gboolean            gdict_database_chooser_select_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);

Selects the database with `db_name` inside the `chooser` widget.

`chooser` : | a GdictDatabaseChooser
`db_name` : | name of the database to select
Returns : | `TRUE` if the database was found and selected

Since 0.10

### gdict_database_chooser_set_current_database ()

    gboolean            gdict_database_chooser_set_current_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);

Sets `db_name` as the current database. This function will select and activate the corresponding row, if the database is found.

`chooser` : | a GdictDatabaseChooser
`db_name` : | the name of the database
Returns : | `TRUE` if the database was found and set

Since 0.10

### gdict_database_chooser_unselect_database ()

    gboolean            gdict_database_chooser_unselect_database
                                                            (GdictDatabaseChooser *chooser,
                                                             const gchar *db_name);

Unselects the database `db_name` inside the `chooser` widget

`chooser` : | a GdictDatabaseChooser
`db_name` : | name of the database to unselect
Returns : | `TRUE` if the database was found and unselected

Since 0.10

## Property Details

### The `"context"` property

      "context"                  GdictContext*         : Read / Write / Construct

The GdictContext used to retrieve the list of available databases.

Since 0.10

### The `"count"` property

      "count"                    gint                  : Read

The number of displayed databases or, if no GdictContext is set, -1.

Allowed values: >= -1

Default value: -1

Since 0.12

## Signal Details

### The `"database-activated"` signal

    void                user_function                      (GdictDatabaseChooser *chooser,
                                                            gchar                *name,
                                                            gchar                *description,
                                                            gpointer              user_data)        : Run Last

The ::database-activated signal is emitted each time the user activated a row in the database chooser widget, either by double clicking on it or by a keyboard event.

`chooser` : | the database chooser that received the signal
`name` : | the name of the activated database
`description` : | the description of the activated database
`user_data` : | user data set when the signal handler was connected.

Since 0.10

### The `"selection-changed"` signal

    void                user_function                      (GdictDatabaseChooser *chooser,
                                                            gpointer              user_data)      : Run Last

The ::selection-changed signal is emitted each time the selection inside the database chooser has been changed.

`chooser` : | the database chooser that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.12