pidgin/pidgincontactcompletion.h

   1 /* pidgin
   2  *
   3  * Pidgin is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PIDGIN_CONTACT_COMPLETION_H
  23 #define PIDGIN_CONTACT_COMPLETION_H
  24
  25 /**
  26  * SECTION:pidgincontactcompletion
  27  * @section_id: pidgin-contact-completion
  28  * @short_description: A GtkEntryCompletion for contacts
  29  * @title: Contact Name Completion
  30  *
  31  * #PidginContactCompletion should be treated like a normal
  32  * #GtkEntryCompletion, except it already does all of the setup for the
  33  * completion.  You can also filter by a #PurpleAccount to limit what's shown.
  34  *
  35  * |[<!-- language="C" -->
  36  * GtkWidget *entry = gtk_entry_new();
  37  * GtkEntryCompletion *completion = pidgin_contact_completion_new();
  38  *
  39  * gtk_entry_set_completion(GTK_ENTRY(entry), completion);
  40  * pidgin_contact_completion_set_account(PIDGIN_CONTACT_COMPLETION(completion), account);
  41  * g_object_unref(completion);
  42  * ]|
  43  */
  44
  45 #include <gtk/gtk.h>
  46
  47 #include <purple.h>
  48
  49 G_BEGIN_DECLS
  50
  51 #define PIDGIN_TYPE_CONTACT_COMPLETION  pidgin_contact_completion_get_type()
  52
  53 G_DECLARE_FINAL_TYPE(PidginContactCompletion, pidgin_contact_completion, PIDGIN,
  54                 CONTACT_COMPLETION, GtkEntryCompletion)
  55
  56 /**
  57  * pidgin_contact_completion_new:
  58  *
  59  * Creates a new #GtkEntryCompletion for looking up contacts.
  60  *
  61  * Returns: (transfer full): The new #GtkEntryCompletion instance.
  62  *
  63  * Since: 3.0.0
  64  */
  65 GtkEntryCompletion *pidgin_contact_completion_new(void);
  66
  67 /**
  68  * pidgin_contact_completion_get_account:
  69  * @completion: The #PidginContactCompletion instance.
  70  *
  71  * Gets the account that @completion is filtering for.  If no filtering is set
  72  * %NULL will be returned.
  73  *
  74  * Returns: (transfer full) (nullable): The #PurpleAccount that's being
  75  *          filtered for.
  76  *
  77  * Since: 3.0.0
  78  */
  79 PurpleAccount *pidgin_contact_completion_get_account(PidginContactCompletion *completion);
  80
  81 /**
  82  * pidgin_contact_completion_set_account:
  83  * @completion: The #PidginContactCompletion instance.
  84  * @account: (nullable): The #PurpleAccount to filter for or %NULL.
  85  *
  86  * Set the #PurpleAccount that @completion should filter for.  If @account is
  87  * %NULL, all filtering will be disabled.
  88  *
  89  * Since: 3.0.0
  90  */
  91 void pidgin_contact_completion_set_account(PidginContactCompletion *completion, PurpleAccount *account);
  92
  93 G_END_DECLS
  94
  95 #endif /* PIDGIN_CONTACT_COMPLETION_H */