Misc. gtk-doc updates, including being more explicit about refs.
[empathy.git] / libempathy-gtk / empathy-contact-selector.c
1 /*
2 *  Copyright (C) 2007 Marco Barisione <marco@barisione.org>
3 *  Copyright (C) 2008 Collabora Ltd.
4 *
5 *  This library is free software; you can redistribute it and/or
6 *  modify it under the terms of the GNU Lesser General Public
7 *  License as published by the Free Software Foundation; either
8 *  version 2.1 of the License, or (at your option) any later version.
9 *
10 *  This library is distributed in the hope that it will be useful,
11 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 *  Lesser General Public License for more details.
14 *
15 *  You should have received a copy of the GNU Lesser General Public
16 *  License along with this library; if not, write to the Free Software
17 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
18 *
19 *  Authors: Marco Barisione <marco@barisione.org>
20 *           Elliot Fairweather <elliot.fairweather@collabora.co.uk>
21 */
22
23 #include "config.h"
24
25 #include <glib/gi18n.h>
26 #include <gtk/gtk.h>
27
28 #include <libempathy/empathy-contact.h>
29 #include <libempathy-gtk/empathy-contact-list-store.h>
30 #include <libempathy/empathy-utils.h>
31
32 #include "empathy-contact-selector.h"
33
34 /**
35  * SECTION:empathy-contact-selector
36  * @title:EmpathyContactSelector
37  * @short_description: A widget used to choose from a list of contacts.
38  * @include: libempathy-gtk/empathy-contact-selector.h
39  *
40  * #EmpathyContactSelector is a widget which extends #GtkComboBox to provide
41  * a chooser of available contacts.
42  */
43
44 /**
45  * EmpathyContactSelector:
46  * @parent: parent object
47  *
48  * Widget which extends #GtkComboBox to provide a chooser of available contacts.
49  */
50
51 G_DEFINE_TYPE (EmpathyContactSelector, empathy_contact_selector,
52     GTK_TYPE_COMBO_BOX)
53
54 enum
55 {
56   PROP_0,
57   PROP_CONTACT_LIST
58 };
59
60 #define GET_PRIV(obj) EMPATHY_GET_PRIV (obj, EmpathyContactSelector)
61 typedef struct
62 {
63   EmpathyContactList *contact_list;
64   EmpathyContactListStore *store;
65   GtkTreeModel *model;
66   gboolean dispose_run;
67 } EmpathyContactSelectorPriv;
68
69 static void contact_selector_manage_blank_contact (
70     EmpathyContactSelector *selector);
71
72 static guint
73 contact_selector_get_number_online_contacts (GtkTreeModel *model)
74 {
75   GtkTreeIter tmp_iter;
76   gboolean is_online;
77   guint number_online_contacts = 0;
78   gboolean ok;
79
80   for (ok = gtk_tree_model_get_iter_first (model, &tmp_iter);
81       ok; ok = gtk_tree_model_iter_next (model, &tmp_iter))
82     {
83       gtk_tree_model_get (model,
84           &tmp_iter, EMPATHY_CONTACT_LIST_STORE_COL_IS_ONLINE,
85           &is_online, -1);
86       if (is_online)
87         number_online_contacts++;
88     }
89
90   return number_online_contacts;
91 }
92
93 static gboolean
94 contact_selector_get_iter_for_blank_contact (GtkTreeStore *model,
95                                              GtkTreeIter *blank_iter)
96 {
97   GtkTreeIter tmp_iter;
98   EmpathyContact *tmp_contact;
99   gboolean is_present = FALSE;
100   gboolean ok;
101
102   for (ok = gtk_tree_model_get_iter_first (GTK_TREE_MODEL (model), &tmp_iter);
103       ok; ok = gtk_tree_model_iter_next (GTK_TREE_MODEL (model), &tmp_iter))
104     {
105       gtk_tree_model_get (GTK_TREE_MODEL (model),
106           &tmp_iter, EMPATHY_CONTACT_LIST_STORE_COL_CONTACT,
107           &tmp_contact, -1);
108       if (tmp_contact == NULL)
109         {
110           *blank_iter = tmp_iter;
111           is_present = TRUE;
112           break;
113         }
114       g_object_unref (tmp_contact);
115     }
116
117   return is_present;
118 }
119
120 static void
121 contact_selector_add_blank_contact (EmpathyContactSelector *selector)
122 {
123   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
124   GtkTreeIter blank_iter, iter;
125
126   gtk_tree_store_insert_with_values (
127       GTK_TREE_STORE (priv->store), &blank_iter, NULL, 0,
128       EMPATHY_CONTACT_LIST_STORE_COL_CONTACT, NULL,
129       EMPATHY_CONTACT_LIST_STORE_COL_NAME, (_("Select a contact")),
130       EMPATHY_CONTACT_LIST_STORE_COL_IS_ONLINE, FALSE, -1);
131
132   /* look up blank_iter in the filter model */
133   g_return_if_fail (gtk_tree_model_filter_convert_child_iter_to_iter (
134       GTK_TREE_MODEL_FILTER (priv->model), &iter, &blank_iter));
135
136   g_signal_handlers_block_by_func (selector,
137       contact_selector_manage_blank_contact, selector);
138   gtk_combo_box_set_active_iter (GTK_COMBO_BOX (selector), &iter);
139   g_signal_handlers_unblock_by_func (selector,
140       contact_selector_manage_blank_contact, selector);
141 }
142
143 static void
144 contact_selector_remove_blank_contact (EmpathyContactSelector *selector)
145 {
146   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
147   GtkTreeIter blank_iter;
148
149   if (contact_selector_get_iter_for_blank_contact
150       (GTK_TREE_STORE (priv->store), &blank_iter))
151     gtk_tree_store_remove (GTK_TREE_STORE (priv->store), &blank_iter);
152 }
153
154 static void
155 contact_selector_manage_sensitivity (EmpathyContactSelector *selector)
156 {
157   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
158   guint number_online_contacts;
159
160   number_online_contacts = contact_selector_get_number_online_contacts (priv->model);
161
162   if (number_online_contacts != 0)
163     gtk_widget_set_sensitive (GTK_WIDGET (selector), TRUE);
164   else
165     gtk_widget_set_sensitive (GTK_WIDGET (selector), FALSE);
166 }
167
168 static void
169 contact_selector_manage_blank_contact (EmpathyContactSelector *selector)
170 {
171   gboolean is_popup_shown;
172
173   g_object_get (selector, "popup-shown", &is_popup_shown, NULL);
174
175   if (is_popup_shown)
176     {
177       contact_selector_remove_blank_contact (selector);
178     }
179   else
180     {
181       if (gtk_combo_box_get_active (GTK_COMBO_BOX (selector)) == -1)
182         {
183           contact_selector_add_blank_contact (selector);
184         }
185       else
186         {
187           contact_selector_remove_blank_contact (selector);
188         }
189     }
190
191   contact_selector_manage_sensitivity (selector);
192 }
193
194 static GObject *
195 contact_selector_constructor (GType type,
196                               guint n_construct_params,
197                               GObjectConstructParam *construct_params)
198 {
199   GObject *object;
200   EmpathyContactSelector *contact_selector;
201   EmpathyContactSelectorPriv *priv;
202   GtkCellLayout *cell_layout;
203   GtkCellRenderer *renderer;
204
205   object = G_OBJECT_CLASS (empathy_contact_selector_parent_class)->constructor 
206     (type, n_construct_params, construct_params);
207   priv = GET_PRIV (object);
208   contact_selector = EMPATHY_CONTACT_SELECTOR (object);
209   cell_layout = GTK_CELL_LAYOUT (object);
210
211   priv->store = empathy_contact_list_store_new (priv->contact_list);
212
213   g_object_set (priv->store, "is-compact", TRUE, "show-avatars", FALSE,
214       "show-offline", FALSE, "show-groups", FALSE,
215       "sort-criterium", EMPATHY_CONTACT_LIST_STORE_SORT_NAME, NULL);
216
217   g_signal_connect_swapped (priv->store, "row-changed",
218       G_CALLBACK (contact_selector_manage_sensitivity),
219       contact_selector);
220   g_signal_connect_swapped (contact_selector, "changed",
221       G_CALLBACK (contact_selector_manage_blank_contact),
222       contact_selector);
223   g_signal_connect_swapped (contact_selector, "notify::popup-shown",
224       G_CALLBACK (contact_selector_manage_blank_contact),
225       contact_selector);
226
227   priv->model = gtk_tree_model_filter_new (GTK_TREE_MODEL (priv->store), NULL);
228
229   gtk_combo_box_set_model (GTK_COMBO_BOX (contact_selector), priv->model);
230   gtk_widget_set_sensitive (GTK_WIDGET (contact_selector), FALSE);
231
232   renderer = gtk_cell_renderer_pixbuf_new ();
233   gtk_cell_layout_pack_start (cell_layout, renderer, FALSE);
234   gtk_cell_layout_set_attributes (cell_layout, renderer,
235       "icon-name", EMPATHY_CONTACT_LIST_STORE_COL_ICON_STATUS, NULL);
236
237   renderer = gtk_cell_renderer_text_new ();
238   gtk_cell_layout_pack_start (cell_layout, renderer, TRUE);
239   gtk_cell_layout_set_attributes (cell_layout, renderer,
240       "text", EMPATHY_CONTACT_LIST_STORE_COL_NAME, NULL);
241
242   contact_selector_manage_blank_contact (contact_selector);
243   contact_selector_manage_sensitivity (contact_selector);
244
245   return object;
246 }
247
248 static void
249 empathy_contact_selector_init (EmpathyContactSelector *empathy_contact_selector)
250 {
251   EmpathyContactSelectorPriv *priv =
252       G_TYPE_INSTANCE_GET_PRIVATE (empathy_contact_selector,
253       EMPATHY_TYPE_CONTACT_SELECTOR, EmpathyContactSelectorPriv);
254
255   empathy_contact_selector->priv = priv;
256
257   priv->dispose_run = FALSE;
258 }
259
260 static void
261 contact_selector_set_property (GObject *object,
262                                guint prop_id,
263                                const GValue *value,
264                                GParamSpec *pspec)
265 {
266   EmpathyContactSelectorPriv *priv = GET_PRIV (object);
267
268   switch (prop_id)
269     {
270       case PROP_CONTACT_LIST:
271         priv->contact_list = g_value_dup_object (value);
272         break;
273       default:
274         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
275         break;
276     }
277 }
278
279 static void
280 contact_selector_get_property (GObject *object,
281                                guint prop_id,
282                                GValue *value,
283                                GParamSpec *pspec)
284 {
285   EmpathyContactSelectorPriv *priv = GET_PRIV (object);
286
287   switch (prop_id)
288     {
289       case PROP_CONTACT_LIST:
290         g_value_set_object (value, priv->contact_list);
291         break;
292       default:
293         G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
294         break;
295     }
296 }
297
298 static void
299 contact_selector_dispose (GObject *object)
300 {
301   EmpathyContactSelector *selector = EMPATHY_CONTACT_SELECTOR (object);
302   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
303
304   if (priv->dispose_run)
305     return;
306
307   priv->dispose_run = TRUE;
308
309   if (priv->contact_list)
310     {
311       g_object_unref (priv->contact_list);
312       priv->contact_list = NULL;
313     }
314
315   if (priv->model)
316     {
317       g_object_unref (priv->model);
318       priv->model = NULL;
319     }
320
321   if (priv->store)
322     {
323       g_object_unref (priv->store);
324       priv->store = NULL;
325     }
326
327   (G_OBJECT_CLASS (empathy_contact_selector_parent_class)->dispose) (object);
328 }
329
330 static void
331 empathy_contact_selector_class_init (EmpathyContactSelectorClass *klass)
332 {
333   GObjectClass *object_class = G_OBJECT_CLASS (klass);
334   object_class->constructor = contact_selector_constructor;
335   object_class->dispose = contact_selector_dispose;
336   object_class->set_property = contact_selector_set_property;
337   object_class->get_property = contact_selector_get_property;
338   g_type_class_add_private (klass, sizeof (EmpathyContactSelectorPriv));
339
340   /**
341    * EmpathyContactSelector:contact-list:
342    *
343    * An #EmpathyContactList containing the contacts for the
344    * #EmpathyContactSelector.
345    */
346   g_object_class_install_property (object_class, PROP_CONTACT_LIST,
347       g_param_spec_object ("contact-list", "contact list", "contact list",
348       EMPATHY_TYPE_CONTACT_LIST, G_PARAM_CONSTRUCT_ONLY |
349       G_PARAM_READWRITE | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
350 }
351
352 /**
353  * empathy_contact_selector_new:
354  * @contact_list: an #EmpathyContactList containing the contacts to list in
355  * the contact selector
356  *
357  * Creates a new #EmpathyContactSelector.
358  *
359  * Return value: A new #EmpathyContactSelector
360  */
361 GtkWidget *
362 empathy_contact_selector_new (EmpathyContactList *contact_list)
363 {
364   g_return_val_if_fail (EMPATHY_IS_CONTACT_LIST (contact_list), NULL);
365
366   return GTK_WIDGET (g_object_new (EMPATHY_TYPE_CONTACT_SELECTOR,
367       "contact-list", contact_list, NULL));
368 }
369
370 /**
371  * empathy_contact_selector_dup_selected:
372  * @selector: An #EmpathyContactSelector
373  *
374  * Returns a new reference to the contact which is currently selected in
375  * @selector, or %NULL if there is no contact selected. The returned contact
376  * should be unrefed with g_object_unref() when finished with.
377  *
378  * Return value: A new reference to the contact currently selected, or %NULL
379  */
380 EmpathyContact *
381 empathy_contact_selector_dup_selected (EmpathyContactSelector *selector)
382 {
383   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
384   EmpathyContact *contact = NULL;
385   GtkTreeIter iter;
386
387   g_return_val_if_fail (EMPATHY_IS_CONTACT_SELECTOR (selector), NULL);
388
389   if (!gtk_combo_box_get_active_iter (GTK_COMBO_BOX (selector), &iter))
390     return NULL;
391
392   gtk_tree_model_get (priv->model, &iter,
393       EMPATHY_CONTACT_LIST_STORE_COL_CONTACT, &contact, -1);
394
395   return contact;
396 }
397
398 typedef struct
399 {
400   EmpathyContactSelectorFilterFunc func;
401   gpointer user_data;
402 } FilterData;
403
404 static void
405 filter_data_free (gpointer data)
406 {
407   g_slice_free (FilterData, data);
408 }
409
410 static gboolean
411 contact_selector_filter_visible_func (GtkTreeModel *model,
412                                       GtkTreeIter *iter,
413                                       gpointer user_data)
414 {
415   EmpathyContact *contact;
416   gboolean visible = TRUE;
417   FilterData *data = (FilterData *) user_data;
418
419   gtk_tree_model_get (model, iter,
420       EMPATHY_CONTACT_LIST_STORE_COL_CONTACT, &contact,
421       -1);
422
423   if (contact != NULL)
424     {
425       visible = data->func(contact, data->user_data);
426
427       g_object_unref (contact);
428     }
429
430   return visible;
431 }
432
433 /**
434  * empathy_contact_selector_set_visible:
435  * @selector: an #EmpathyContactSelector
436  * @func: an #EmpathyContactSelectorFilterFunc to filter the contacts
437  * @user_data: data to pass to @func or %NULL
438  *
439  * Sets a filter on the @selector so only contacts that return %TRUE
440  * when passed into @func are visible.
441  *
442  * A typical usage for this function would be to only show contacts that
443  * can send or receive files. In this case, one could use the
444  * empathy_contact_can_send_files() function
445  */
446 void
447 empathy_contact_selector_set_visible (EmpathyContactSelector *selector,
448                                       EmpathyContactSelectorFilterFunc func,
449                                       gpointer user_data)
450 {
451   EmpathyContactSelectorPriv *priv = GET_PRIV (selector);
452   FilterData *data;
453
454   data = g_slice_new0 (FilterData);
455   data->func = func;
456   data->user_data = user_data;
457
458   gtk_tree_model_filter_set_visible_func (GTK_TREE_MODEL_FILTER (priv->model),
459       contact_selector_filter_visible_func, data, filter_data_free);
460
461   gtk_tree_model_filter_refilter (GTK_TREE_MODEL_FILTER (priv->model));
462 }
463
464 /**
465  * EmpathyContactSelectorFilterFunc:
466  * @contact: an #EmpathyContact
467  * @user_data: user data or %NULL
468  *
469  * A function which decides whether the contact indicated by @contact
470  * is visible.
471  *
472  * Return value: whether @contact is visible
473  */