OssoABookContactChooser

OssoABookContactChooser — Dialog for choosing OssoABookContacts.

Synopsis

#define             OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE
#define             OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE_STRING
                    OssoABookContactChooser;
gboolean            (*OssoABookContactChooserVisibleFunc)
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContact *contact,
                                                         gpointer user_data);
GQuark              osso_abook_contact_chooser_dbus_iface_quark
                                                        (void);
GtkWidget*          osso_abook_contact_chooser_new      (GtkWindow *parent,
                                                         const gchar *title);
GtkWidget*          osso_abook_contact_chooser_new_with_capabilities
                                                        (GtkWindow *parent,
                                                         const gchar *title,
                                                         OssoABookCapsFlags caps,
                                                         OssoABookContactOrder order);
GList*              osso_abook_contact_chooser_get_selection
                                                        (OssoABookContactChooser *chooser);
void                osso_abook_contact_chooser_select   (OssoABookContactChooser *chooser,
                                                         OssoABookContact *contact);
void                osso_abook_contact_chooser_select_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         GList *contacts);
void                osso_abook_contact_chooser_deselect_all
                                                        (OssoABookContactChooser *chooser);
void                osso_abook_contact_chooser_set_capabilities
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookCapsFlags caps);
void                osso_abook_contact_chooser_set_contact_order
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactOrder order);
void                osso_abook_contact_chooser_set_excluded_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         GList *contacts);
void                osso_abook_contact_chooser_set_minimum_selection
                                                        (OssoABookContactChooser *chooser,
                                                         unsigned int limit);
void                osso_abook_contact_chooser_set_maximum_selection
                                                        (OssoABookContactChooser *chooser,
                                                         unsigned int limit);
void                osso_abook_contact_chooser_set_done_label
                                                        (OssoABookContactChooser *chooser,
                                                         const char *label);
void                osso_abook_contact_chooser_set_model
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactModel *model);
void                osso_abook_contact_chooser_set_hide_offline_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         gboolean state);
void                osso_abook_contact_chooser_set_show_empty_note
                                                        (OssoABookContactChooser *chooser,
                                                         gboolean state);
OssoABookCapsFlags  osso_abook_contact_chooser_get_capabilities
                                                        (OssoABookContactChooser *chooser);
OssoABookContactOrder osso_abook_contact_chooser_get_contact_order
                                                        (OssoABookContactChooser *chooser);
GList*              osso_abook_contact_chooser_get_excluded_contacts
                                                        (OssoABookContactChooser *chooser);
unsigned int        osso_abook_contact_chooser_get_minimum_selection
                                                        (OssoABookContactChooser *chooser);
unsigned int        osso_abook_contact_chooser_get_maximum_selection
                                                        (OssoABookContactChooser *chooser);
const char*         osso_abook_contact_chooser_get_done_label
                                                        (OssoABookContactChooser *chooser);
OssoABookContactModel* osso_abook_contact_chooser_get_model
                                                        (OssoABookContactChooser *chooser);
GtkWidget*          osso_abook_contact_chooser_get_contact_view
                                                        (OssoABookContactChooser *chooser);
gboolean            osso_abook_contact_chooser_get_hide_offline_contacts
                                                        (OssoABookContactChooser *chooser);
gboolean            osso_abook_contact_chooser_get_show_empty_note
                                                        (OssoABookContactChooser *chooser);
void                osso_abook_contact_chooser_set_visible_func
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactChooserVisibleFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);
void                osso_abook_contact_chooser_refilter (OssoABookContactChooser *chooser);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----GtkDialog
                                             +----OssoABookContactChooser

Implemented Interfaces

OssoABookContactChooser implements AtkImplementorIface and GtkBuildable.

Properties

  "capabilities"             OssoABookCapsFlags    : Read / Write / Construct
  "contact-order"            OssoABookContactOrder  : Read / Write / Construct
  "contact-view"             OssoABookContactView*  : Read
  "done-label"               gchar*                : Read / Write
  "excluded-contacts"        OssoABookStringList*  : Read / Write / Construct
  "hide-offline-contacts"    gboolean              : Read / Write
  "maximum-selection"        guint                 : Read / Write
  "minimum-selection"        guint                 : Read / Write
  "model"                    OssoABookContactModel*  : Read / Write
  "show-empty-note"          gboolean              : Read / Write

Description

This dialog provides a user interface for choosing contacts. It allows the client application to request limits on the number of contacts, and filter the type of contacts which can be selected.

Details

OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE

#define             OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE

Name of the OssoABookContactChooser's D-Bus interface as GQuark.


OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE_STRING

#define             OSSO_ABOOK_CONTACT_CHOOSER_DBUS_IFACE_STRING

Name of the OssoABookContactChooser's D-Bus interface as string.


OssoABookContactChooser

typedef struct _OssoABookContactChooser OssoABookContactChooser;

All the fields of this structure are private to the object's implementation and should never be accessed directly.


OssoABookContactChooserVisibleFunc ()

gboolean            (*OssoABookContactChooserVisibleFunc)
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContact *contact,
                                                         gpointer user_data);

osso_abook_contact_chooser_dbus_iface_quark ()

GQuark              osso_abook_contact_chooser_dbus_iface_quark
                                                        (void);

osso_abook_contact_chooser_new ()

GtkWidget*          osso_abook_contact_chooser_new      (GtkWindow *parent,
                                                         const gchar *title);

This is a function to create a new contact chooser dialog with minimal parameters.

parent : A parent GtkWindow this dialog is transient for
title : The title of the dialog
Returns : The newly created OssoABookContactChooser widget

osso_abook_contact_chooser_new_with_capabilities ()

GtkWidget*          osso_abook_contact_chooser_new_with_capabilities
                                                        (GtkWindow *parent,
                                                         const gchar *title,
                                                         OssoABookCapsFlags caps,
                                                         OssoABookContactOrder order);

This function creates a new contact chooser dialog with the requested capabilities. Only contacts which match the capabilities are displayed.

parent : A parent GtkWindow this dialog is transient for
title : The title of the dialog
caps : Capabilities which contacts displayed in the dialog should have
order : The sort order of the contacts displayed in the dialog
Returns : The newly created OssoABookContactChooser widget

osso_abook_contact_chooser_get_selection ()

GList*              osso_abook_contact_chooser_get_selection
                                                        (OssoABookContactChooser *chooser);

This function returns a list of OssoABookContacts which were selected by the user in the dialog.

chooser : An OssoABookContactChooser
Returns : List of OssoABookContacts selected by the user. This list should be freed by the caller, but don't g_object_unref() the elements.

osso_abook_contact_chooser_select ()

void                osso_abook_contact_chooser_select   (OssoABookContactChooser *chooser,
                                                         OssoABookContact *contact);

Marks a contact in the dialog as selected. The contact is added to any existing selection.

chooser : An OssoABookContactChooser
contact : The OssoABookContact which is to be selected

osso_abook_contact_chooser_select_contacts ()

void                osso_abook_contact_chooser_select_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         GList *contacts);

Marks a list of OssoABookContacts in the dialog as selected. The contacts are added to any existing selection.

chooser : An OssoABookContactChooser
contacts : A list of OssoABookContacts which are to be selected. This list can be freed by the caller after calling this function.

osso_abook_contact_chooser_deselect_all ()

void                osso_abook_contact_chooser_deselect_all
                                                        (OssoABookContactChooser *chooser);

This function clears any existing selection in the contact chooser dialog. Any contacts which were selected by the user are unselected.

chooser : An OssoABookContactChooser

osso_abook_contact_chooser_set_capabilities ()

void                osso_abook_contact_chooser_set_capabilities
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookCapsFlags caps);

Sets the capabilities which the displayed contacts in the dialog must have. Contacts which do not have the requested capabilities are not shown in the dialog.

chooser : An OssoABookContactChooser
caps : The capabilities which contacts should have

osso_abook_contact_chooser_set_contact_order ()

void                osso_abook_contact_chooser_set_contact_order
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactOrder order);

Sets the sort order of the chooser's contact model. If order is OSSO_ABOOK_CONTACT_ORDER_NONE, then the order will follow the contact model's order (instead of setting it to unsorted order).

chooser : An OssoABookContactChooser
order : An OssoABookContactOrder to sort the model by

osso_abook_contact_chooser_set_excluded_contacts ()

void                osso_abook_contact_chooser_set_excluded_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         GList *contacts);

This function sets a list of OssoABookContacts which must not be displayed in the contact chooser dialog. These contacts will not be seen in the dialog by the user.

chooser : An OssoABookContactChooser
contacts : A list of OssoABookContacts which are not to be shown. This list can be freed later by the caller as it's duplicated internally.

osso_abook_contact_chooser_set_minimum_selection ()

void                osso_abook_contact_chooser_set_minimum_selection
                                                        (OssoABookContactChooser *chooser,
                                                         unsigned int limit);

This function sets the minimum number of contacts which must be selected by the user, before the user is able to submit the dialog.

Set both the minimum and maximum selection to 1 to show the dialog in single-selection mode, where just tapping on a single contact will submit it.

chooser : An OssoABookContactChooser
limit : The minimum number of contacts which must be selected

osso_abook_contact_chooser_set_maximum_selection ()

void                osso_abook_contact_chooser_set_maximum_selection
                                                        (OssoABookContactChooser *chooser,
                                                         unsigned int limit);

This function sets the maximum number of contacts which must be selected by the user, before the user is able to submit the dialog.

Set both the minimum and maximum selection to 1 to show the dialog in single-selection mode, where just tapping on a single contact will submit it.

chooser : An OssoABookContactChooser
limit : The maximum number of contacts which must be selected

osso_abook_contact_chooser_set_done_label ()

void                osso_abook_contact_chooser_set_done_label
                                                        (OssoABookContactChooser *chooser,
                                                         const char *label);

When the contact chooser dialog is in multi-selection mode, the user has to tap a 'Done' button to submit the dialog (after which the selection will be processed). This function lets you customize the label of this done button.

chooser : An OssoABookContactChooser
label : The label for the done button. This label text is copied internally, and label can be freed later by the caller.

osso_abook_contact_chooser_set_model ()

void                osso_abook_contact_chooser_set_model
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactModel *model);

Replaces the chooser's internal contact model with model.

chooser : An OssoABookContactChooser
model : An OssoABookContactModel to base the chooser upon

osso_abook_contact_chooser_set_hide_offline_contacts ()

void                osso_abook_contact_chooser_set_hide_offline_contacts
                                                        (OssoABookContactChooser *chooser,
                                                         gboolean state);

Sets whether contacts with offline presence should be hidden in the contact chooser.

If you call both osso_abook_contact_chooser_set_show_empty_note() and osso_abook_contact_chooser_set_hide_offline_contacts(), please call book_contact_chooser_set_hide_offline_contacts() first and then osso_abook_contact_chooser_set_show_empty_note() for better performance.

chooser : An OssoABookContactChooser
state : Set to TRUE if offline contacts should be hidden, FALSE otherwise

osso_abook_contact_chooser_set_show_empty_note ()

void                osso_abook_contact_chooser_set_show_empty_note
                                                        (OssoABookContactChooser *chooser,
                                                         gboolean state);

Sets whether to show the empty note when no contacts with the required capabilities exist.

If you call both osso_abook_contact_chooser_set_show_empty_note() and osso_abook_contact_chooser_set_hide_offline_contacts(), please call book_contact_chooser_set_hide_offline_contacts() first and then osso_abook_contact_chooser_set_show_empty_note() for better performance.

chooser : An OssoABookContactChooser
state : Set to TRUE if the empty note should be shown

osso_abook_contact_chooser_get_capabilities ()

OssoABookCapsFlags  osso_abook_contact_chooser_get_capabilities
                                                        (OssoABookContactChooser *chooser);

Returns the capabilities which the displayed contacts in the dialog are supposed to have. Contacts which do not have the requested capabilities are not shown in the dialog.

chooser : An OssoABookContactChooser
Returns : The capabilities which contacts in the dialog need to have

osso_abook_contact_chooser_get_contact_order ()

OssoABookContactOrder osso_abook_contact_chooser_get_contact_order
                                                        (OssoABookContactChooser *chooser);

Returns the sort order of the chooser's contact model. If the order is OSSO_ABOOK_CONTACT_ORDER_NONE, then the order will follow the contact model's existing order (instead of setting it to unsorted order).

chooser : An OssoABookContactChooser
Returns : The OssoABookContactOrder which the the model is sorted by

osso_abook_contact_chooser_get_excluded_contacts ()

GList*              osso_abook_contact_chooser_get_excluded_contacts
                                                        (OssoABookContactChooser *chooser);

Returns a list of OssoABookContacts which will not be displayed in the contact chooser dialog. These contacts will not be seen in the dialog by the user.

chooser : An OssoABookContactChooser
Returns : The list of OssoABookContacts which will not be shown. This list is managed internally by OssoABookContactChooser and must not be freed by the caller.

osso_abook_contact_chooser_get_minimum_selection ()

unsigned int        osso_abook_contact_chooser_get_minimum_selection
                                                        (OssoABookContactChooser *chooser);

Returns the minimum number of contacts which must be selected by the user, before the user is able to submit the dialog.

If both the minimum and maximum selection are 1, the the dialog is then shown in single-selection mode, where just tapping on a single contact will submit it.

chooser : An OssoABookContactChooser
Returns : The minimum number of contacts which must be selected

osso_abook_contact_chooser_get_maximum_selection ()

unsigned int        osso_abook_contact_chooser_get_maximum_selection
                                                        (OssoABookContactChooser *chooser);

Returns the maximum number of contacts which must be selected by the user, before the user is able to submit the dialog.

If both the minimum and maximum selection are 1, the the dialog is then shown in single-selection mode, where just tapping on a single contact will submit it.

chooser : An OssoABookContactChooser
Returns : The maximum number of contacts which must be selected

osso_abook_contact_chooser_get_done_label ()

const char*         osso_abook_contact_chooser_get_done_label
                                                        (OssoABookContactChooser *chooser);

When the contact chooser dialog is in multi-selection mode, the user has to tap a 'Done' button to submit the dialog (after which the selection will be processed). This function returns the label which is shown for this done button.

chooser : An OssoABookContactChooser
Returns : The label of the done button. This string is owned by the widget and must not be modified or freed.

osso_abook_contact_chooser_get_model ()

OssoABookContactModel* osso_abook_contact_chooser_get_model
                                                        (OssoABookContactChooser *chooser);

Returns the contact chooser's internal model.

chooser : An OssoABookContactChooser
Returns : The model of the contact chooser

osso_abook_contact_chooser_get_contact_view ()

GtkWidget*          osso_abook_contact_chooser_get_contact_view
                                                        (OssoABookContactChooser *chooser);

Returns the OssoABookContactView widget inside the contact chooser dialog.

chooser : An OssoABookContactChooser
Returns : The contact view widget in the chooser dialog

osso_abook_contact_chooser_get_hide_offline_contacts ()

gboolean            osso_abook_contact_chooser_get_hide_offline_contacts
                                                        (OssoABookContactChooser *chooser);

Returns whether contacts with offline presence are hidden in the contact chooser.

chooser : An OssoABookContactChooser
Returns : TRUE if offline contacts are hidden, FALSE otherwise

osso_abook_contact_chooser_get_show_empty_note ()

gboolean            osso_abook_contact_chooser_get_show_empty_note
                                                        (OssoABookContactChooser *chooser);

Returns whether the empty note is shown when no contacts with the required capabilities exist.

chooser : An OssoABookContactChooser
Returns : TRUE if empty note is shown, FALSE otherwise.

osso_abook_contact_chooser_set_visible_func ()

void                osso_abook_contact_chooser_set_visible_func
                                                        (OssoABookContactChooser *chooser,
                                                         OssoABookContactChooserVisibleFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy);

Sets a callback function which is called iteratively for all the contacts that can be displayed in the chooser (after they are filtered on the requested capabilities, etc.), to determine if they are to be shown in the dialog or not.

chooser : An OssoABookContactChooser
func : A callback function which determines if a contact are visible or not
user_data : A pointer to user data, which will be passed to the callback function
destroy : A callback function which is called either when a new destroy function is set, or when the chooser is destroyed

osso_abook_contact_chooser_refilter ()

void                osso_abook_contact_chooser_refilter (OssoABookContactChooser *chooser);

This function causes the contact chooser to re-evaluate whether contacts in the dialog are visible or not, and show or hide them appropriately.

chooser : An OssoABookContactChooser

Property Details

The "capabilities" property

  "capabilities"             OssoABookCapsFlags    : Read / Write / Construct

The set of permitted contact capabilities.

Default value: OSSO_ABOOK_CAPS_EMAIL|OSSO_ABOOK_CAPS_CHAT|OSSO_ABOOK_CAPS_VOICE|OSSO_ABOOK_CAPS_VIDEO|OSSO_ABOOK_CAPS_PHONE


The "contact-order" property

  "contact-order"            OssoABookContactOrder  : Read / Write / Construct

Sort order for contacts.

Default value: OSSO_ABOOK_CONTACT_ORDER_NONE


The "contact-view" property

  "contact-view"             OssoABookContactView*  : Read

The tree view listing the contacts.


The "done-label" property

  "done-label"               gchar*                : Read / Write

The text shown on the Done button when visible.

Default value: "wdgt_bd_done"


The "excluded-contacts" property

  "excluded-contacts"        OssoABookStringList*  : Read / Write / Construct

UIDs of contacts explicitly excluded from the model.


The "hide-offline-contacts" property

  "hide-offline-contacts"    gboolean              : Read / Write

Whether to hide offline contacts in the chooser.

Default value: FALSE


The "maximum-selection" property

  "maximum-selection"        guint                 : Read / Write

The maximum number of rows to be selected.

Allowed values: >= 1

Default value: 1


The "minimum-selection" property

  "minimum-selection"        guint                 : Read / Write

The minimum number of rows to be selected.

Allowed values: >= 1

Default value: 1


The "model" property

  "model"                    OssoABookContactModel*  : Read / Write

The tree model from which to retrieve contacts.


The "show-empty-note" property

  "show-empty-note"          gboolean              : Read / Write

Whether to show empty note when no contacts exist.

Default value: FALSE