## EmpathyContactSelector

EmpathyContactSelector — A widget used to choose from a list of contacts.

## Synopsis

    #include <libempathy-gtk/empathy-contact-selector.h>

                        EmpathyContactSelector;
    GtkWidget *         empathy_contact_selector_new        (EmpathyContactList *contact_list);
    EmpathyContact *    empathy_contact_selector_dup_selected
                                                            (EmpathyContactSelector *selector);
    gboolean            (*EmpathyContactSelectorFilterFunc) (EmpathyContact *contact,
                                                             gpointer user_data);
    void                empathy_contact_selector_set_visible
                                                            (EmpathyContactSelector *selector,
                                                             EmpathyContactSelectorFilterFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkComboBox
                                           +----EmpathyContactSelector

## Implemented Interfaces

EmpathyContactSelector implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

## Properties

      "contact-list"             EmpathyContactList*   : Read / Write / Construct Only

## Description

EmpathyContactSelector is a widget which extends GtkComboBox to provide a chooser of available contacts.

## Details

### EmpathyContactSelector

    typedef struct _EmpathyContactSelector EmpathyContactSelector;

Widget which extends GtkComboBox to provide a chooser of available contacts.

### empathy_contact_selector_new ()

    GtkWidget *         empathy_contact_selector_new        (EmpathyContactList *contact_list);

Creates a new EmpathyContactSelector.

`contact_list` : | an EmpathyContactList containing the contacts to list in the contact selector
Returns : | A new EmpathyContactSelector

### empathy_contact_selector_dup_selected ()

    EmpathyContact *    empathy_contact_selector_dup_selected
                                                            (EmpathyContactSelector *selector);

Returns a new reference to the contact which is currently selected in `selector`, or `NULL` if there is no contact selected. The returned contact should be unrefed with `g_object_unref()` when finished with.

`selector` : | An EmpathyContactSelector
Returns : | A new reference to the contact currently selected, or `NULL`

### EmpathyContactSelectorFilterFunc ()

    gboolean            (*EmpathyContactSelectorFilterFunc) (EmpathyContact *contact,
                                                             gpointer user_data);

A function which decides whether the contact indicated by `contact` is visible.

`contact` : | an EmpathyContact
`user_data` : | user data or `NULL`
Returns : | whether `contact` is visible

### empathy_contact_selector_set_visible ()

    void                empathy_contact_selector_set_visible
                                                            (EmpathyContactSelector *selector,
                                                             EmpathyContactSelectorFilterFunc func,
                                                             gpointer user_data);

Sets a filter on the `selector` so only contacts that return `TRUE` when passed into `func` are visible.

A typical usage for this function would be to only show contacts that can send or receive files. In this case, one could use the `empathy_contact_can_send_files()` function

`selector` : | an EmpathyContactSelector
`func` : | an EmpathyContactSelectorFilterFunc to filter the contacts
`user_data` : | data to pass to `func` or `NULL`

## Property Details

### The `"contact-list"` property

      "contact-list"             EmpathyContactList*   : Read / Write / Construct Only

An EmpathyContactList containing the contacts for the EmpathyContactSelector.