Merge branch 'sasl'

[empathy.git] / libempathy-gtk / empathy-contact-selector.c

diff --git a/libempathy-gtk/empathy-contact-selector.c b/libempathy-gtk/empathy-contact-selector.c
index 46e6e63a3a977d4cd72d477056fff247b4ddf53a..c70d2575acc66b991dd88a0d7e77eb7ac8783dd2 100644 (file)
--- a/libempathy-gtk/empathy-contact-selector.c
+++ b/libempathy-gtk/empathy-contact-selector.c
@@ -31,6 +31,23 @@
 
 #include "empathy-contact-selector.h"
 
+/**
+ * SECTION:empathy-contact-selector
+ * @title:EmpathyContactSelector
+ * @short_description: A widget used to choose from a list of contacts.
+ * @include: libempathy-gtk/empathy-contact-selector.h
+ *
+ * #EmpathyContactSelector is a widget which extends #GtkComboBox to provide
+ * a chooser of available contacts.
+ */
+
+/**
+ * EmpathyContactSelector:
+ * @parent: parent object
+ *
+ * Widget which extends #GtkComboBox to provide a chooser of available contacts.
+ */
+
 G_DEFINE_TYPE (EmpathyContactSelector, empathy_contact_selector,
     GTK_TYPE_COMBO_BOX)
 
@@ -74,7 +91,7 @@ contact_selector_get_number_online_contacts (GtkTreeModel *model)
 }
 
 static gboolean
-contact_selector_get_iter_for_blank_contact (GtkTreeModel *model,
+contact_selector_get_iter_for_blank_contact (GtkTreeStore *model,
                                              GtkTreeIter *blank_iter)
 {
   GtkTreeIter tmp_iter;
@@ -82,10 +99,10 @@ contact_selector_get_iter_for_blank_contact (GtkTreeModel *model,
   gboolean is_present = FALSE;
   gboolean ok;
 
-  for (ok = gtk_tree_model_get_iter_first (model, &tmp_iter);
-      ok; ok = gtk_tree_model_iter_next (model, &tmp_iter))
+  for (ok = gtk_tree_model_get_iter_first (GTK_TREE_MODEL (model), &tmp_iter);
+      ok; ok = gtk_tree_model_iter_next (GTK_TREE_MODEL (model), &tmp_iter))
     {
-      gtk_tree_model_get (model,
+      gtk_tree_model_get (GTK_TREE_MODEL (model),
           &tmp_iter, EMPATHY_CONTACT_LIST_STORE_COL_CONTACT,
           &tmp_contact, -1);
       if (tmp_contact == NULL)
@@ -129,7 +146,8 @@ contact_selector_remove_blank_contact (EmpathyContactSelector *selector)
   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
   GtkTreeIter blank_iter;
 
-  if (contact_selector_get_iter_for_blank_contact (priv->model, &blank_iter))
+  if (contact_selector_get_iter_for_blank_contact
+      (GTK_TREE_STORE (priv->store), &blank_iter))
     gtk_tree_store_remove (GTK_TREE_STORE (priv->store), &blank_iter);
 }
 
@@ -184,7 +202,7 @@ contact_selector_constructor (GType type,
   GtkCellLayout *cell_layout;
   GtkCellRenderer *renderer;
 
-  object = G_OBJECT_CLASS (empathy_contact_selector_parent_class)->constructor 
+  object = G_OBJECT_CLASS (empathy_contact_selector_parent_class)->constructor
     (type, n_construct_params, construct_params);
   priv = GET_PRIV (object);
   contact_selector = EMPATHY_CONTACT_SELECTOR (object);
@@ -193,7 +211,7 @@ contact_selector_constructor (GType type,
   priv->store = empathy_contact_list_store_new (priv->contact_list);
 
   g_object_set (priv->store, "is-compact", TRUE, "show-avatars", FALSE,
-      "show-offline", FALSE, "show-groups", FALSE,
+      "show-offline", FALSE, "show-groups", FALSE, "show-protocols", FALSE,
       "sort-criterium", EMPATHY_CONTACT_LIST_STORE_SORT_NAME, NULL);
 
   g_signal_connect_swapped (priv->store, "row-changed",
@@ -214,7 +232,7 @@ contact_selector_constructor (GType type,
   renderer = gtk_cell_renderer_pixbuf_new ();
   gtk_cell_layout_pack_start (cell_layout, renderer, FALSE);
   gtk_cell_layout_set_attributes (cell_layout, renderer,
-      "icon-name", EMPATHY_CONTACT_LIST_STORE_COL_ICON_STATUS, NULL);
+      "pixbuf", EMPATHY_CONTACT_LIST_STORE_COL_ICON_STATUS, NULL);
 
   renderer = gtk_cell_renderer_text_new ();
   gtk_cell_layout_pack_start (cell_layout, renderer, TRUE);
@@ -319,14 +337,27 @@ empathy_contact_selector_class_init (EmpathyContactSelectorClass *klass)
   object_class->get_property = contact_selector_get_property;
   g_type_class_add_private (klass, sizeof (EmpathyContactSelectorPriv));
 
+  /**
+   * EmpathyContactSelector:contact-list:
+   *
+   * An #EmpathyContactList containing the contacts for the
+   * #EmpathyContactSelector.
+   */
   g_object_class_install_property (object_class, PROP_CONTACT_LIST,
       g_param_spec_object ("contact-list", "contact list", "contact list",
       EMPATHY_TYPE_CONTACT_LIST, G_PARAM_CONSTRUCT_ONLY |
       G_PARAM_READWRITE | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 }
 
-/* public methods */
-
+/**
+ * empathy_contact_selector_new:
+ * @contact_list: an #EmpathyContactList containing the contacts to list in
+ * the contact selector
+ *
+ * Creates a new #EmpathyContactSelector.
+ *
+ * Return value: A new #EmpathyContactSelector
+ */
 GtkWidget *
 empathy_contact_selector_new (EmpathyContactList *contact_list)
 {
@@ -336,6 +367,16 @@ empathy_contact_selector_new (EmpathyContactList *contact_list)
       "contact-list", contact_list, NULL));
 }
 
+/**
+ * empathy_contact_selector_dup_selected:
+ * @selector: An #EmpathyContactSelector
+ *
+ * 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.
+ *
+ * Return value: A new reference to the contact currently selected, or %NULL
+ */
 EmpathyContact *
 empathy_contact_selector_dup_selected (EmpathyContactSelector *selector)
 {
@@ -381,7 +422,7 @@ contact_selector_filter_visible_func (GtkTreeModel *model,
 
   if (contact != NULL)
     {
-      visible = data->func(contact, data->user_data);
+      visible = data->func (contact, data->user_data);
 
       g_object_unref (contact);
     }
@@ -389,6 +430,19 @@ contact_selector_filter_visible_func (GtkTreeModel *model,
   return visible;
 }
 
+/**
+ * empathy_contact_selector_set_visible:
+ * @selector: an #EmpathyContactSelector
+ * @func: an #EmpathyContactSelectorFilterFunc to filter the contacts
+ * @user_data: data to pass to @func or %NULL
+ *
+ * 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
+ */
 void
 empathy_contact_selector_set_visible (EmpathyContactSelector *selector,
                                       EmpathyContactSelectorFilterFunc func,
@@ -406,3 +460,14 @@ empathy_contact_selector_set_visible (EmpathyContactSelector *selector,
 
   gtk_tree_model_filter_refilter (GTK_TREE_MODEL_FILTER (priv->model));
 }
+
+/**
+ * EmpathyContactSelectorFilterFunc:
+ * @contact: an #EmpathyContact
+ * @user_data: user data or %NULL
+ *
+ * A function which decides whether the contact indicated by @contact
+ * is visible.
+ *
+ * Return value: whether @contact is visible
+ */