## EClientComboBox EClientComboBox — Combo box of EClient instances |

## Synopsis

    #include <e-util/e-util.h>

    struct              EClientComboBox;
    GtkWidget *         e_client_combo_box_new              (EClientCache *client_cache,
                                                             const gchar *extension_name);
    EClientCache *      e_client_combo_box_ref_client_cache (EClientComboBox *combo_box);
    void                e_client_combo_box_set_client_cache (EClientComboBox *combo_box,
                                                             EClientCache *client_cache);
    EClient *           e_client_combo_box_get_client_sync  (EClientComboBox *combo_box,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_combo_box_get_client       (EClientComboBox *combo_box,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EClient *           e_client_combo_box_get_client_finish
                                                            (EClientComboBox *combo_box,
                                                             GAsyncResult *result,
                                                             GError **error);
    EClient *           e_client_combo_box_ref_cached_client
                                                            (EClientComboBox *combo_box,
                                                             ESource *source);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkComboBox
                                     +----ESourceComboBox
                                           +----EClientComboBox

## Implemented Interfaces

EClientComboBox implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Properties

      "client-cache"             EClientCache*         : Read / Write / Construct Only

## Description

EClientComboBox extends the functionality of ESourceComboBox by providing convenient access to EClient instances with EClientCache.

As a future enhancement, this widget may also display status information about the backends associated with the displayed data sources, similar to EClientSelector.

## Details

### struct EClientComboBox

    struct EClientComboBox;

### e_client_combo_box_new ()

    GtkWidget *         e_client_combo_box_new              (EClientCache *client_cache,
                                                             const gchar *extension_name);

Creates a new EClientComboBox widget that lets the user pick an ESource from the provided `client_cache`. The displayed sources are restricted to those which have an `extension_name` extension.

`client_cache` : | an EClientCache
`extension_name` : | the name of an ESource extension
Returns : | a new EClientComboBox

### e_client_combo_box_ref_client_cache ()

    EClientCache *      e_client_combo_box_ref_client_cache (EClientComboBox *combo_box);

Returns the EClientCache passed to `e_client_combo_box_new()`.

The returned EClientCache is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`combo_box` : | an EClientComboBox
Returns : | an EClientCache

### e_client_combo_box_set_client_cache ()

    void                e_client_combo_box_set_client_cache (EClientComboBox *combo_box,
                                                             EClientCache *client_cache);

Simultaneously sets the "client-cache" and "registry" properties.

This function is intended for cases where `combo_box` is instantiated by a GtkBuilder and has to be given an EClientCache after it is fully constructed.

`combo_box` : | an EClientComboBox

### e_client_combo_box_get_client_sync ()

    EClient *           e_client_combo_box_get_client_sync  (EClientComboBox *combo_box,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

Obtains a shared EClient instance for `source`, or else creates a new EClient instance to be shared.

The "extension-name" property determines the type of EClient to obtain. See `e_client_cache_get_client_sync()` for a list of valid extension names.

If a request for the same `source` and "extension-name" is already in progress when this function is called, this request will "piggyback" on the in-progress request such that they will both succeed or fail simultaneously.

Unreference the returned EClient with `g_object_unref()` when finished with it. If an error occurs, the function will set `error` and return `NULL`.

`combo_box` : | an EClientComboBox
`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | an EClient, or `NULL`

### e_client_combo_box_get_client ()

    void                e_client_combo_box_get_client       (EClientComboBox *combo_box,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously obtains a shared EClient instance for `source`, or else creates a new EClient instance to be shared.

The "extension-name" property determines the type of EClient to obtain. See `e_client_cache_get_client_sync()` for a list of valid extension names.

If a request for the same `source` and "extension-name" is already in progress when this function is called, this request will "piggyback" on the in-progress request such that they will both succeed or fail simultaneously.

When the operation is finished, `callback` will be called. You can then call `e_client_combo_box_get_client_finish()` to get the result of the operation.

`combo_box` : | an EClientComboBox
`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

### e_client_combo_box_get_client_finish ()

    EClient *           e_client_combo_box_get_client_finish
                                                            (EClientComboBox *combo_box,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_client_combo_box_get_client()`.

Unreference the returned EClient with `g_object_unref()` when finished with it. If an error occurred, the function will set `error` and return `NULL`.

`combo_box` : | an EClientComboBox
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | an EClient, or `NULL`

### e_client_combo_box_ref_cached_client ()

    EClient *           e_client_combo_box_ref_cached_client
                                                            (EClientComboBox *combo_box,
                                                             ESource *source);

Returns a shared EClient instance for `source` and the value of "extension-name" if such an instance is already cached, or else `NULL`. This function does not create a new EClient instance, and therefore does not block.

The returned EClient is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`combo_box` : | an EClientComboBox
`source` : | an ESource
Returns : | an EClient, or `NULL`

## Property Details

### The `"client-cache"` property

      "client-cache"             EClientCache*         : Read / Write / Construct Only

Cache of shared EClient instances.