libpurple/smiley-list.h

   1 /* purple
   2  *
   3  * Purple 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 PURPLE_SMILEY_LIST_H
  23 #define PURPLE_SMILEY_LIST_H
  24
  25 /**
  26  * SECTION:smiley-list
  27  * @include:smiley-list.h
  28  * @section_id: libpurple-smiley-list
  29  * @short_description: a collection of smileys
  30  * @title: Smiley lists
  31  *
  32  * A #PurpleSmileyList is a handy storage for a set of #PurpleSmiley's.
  33  * It holds structures needed for parsing, accessing them by a shortcut, or
  34  * listing (either all, or by unique image).
  35  */
  36
  37 #include <glib-object.h>
  38
  39 #include "smiley.h"
  40 #include "trie.h"
  41
  42 G_BEGIN_DECLS
  43
  44 #define PURPLE_TYPE_SMILEY_LIST  purple_smiley_list_get_type()
  45
  46 /**
  47  * purple_smiley_list_get_type:
  48  *
  49  * Returns: the #GType for a smiley list.
  50  */
  51 G_DECLARE_FINAL_TYPE(PurpleSmileyList, purple_smiley_list, PURPLE,
  52                 SMILEY_LIST, GObject)
  53
  54 /**
  55  * purple_smiley_list_new:
  56  *
  57  * Creates new #PurpleSmileyList. You might prefer using existing lists, like
  58  * #purple_smiley_custom_get_list or #purple_conversation_get_remote_smileys
  59  * (the latter is read-only, accessed with
  60  * #purple_conversation_add_remote_smiley and
  61  * #purple_conversation_get_remote_smiley).
  62  *
  63  * Returns: newly created #PurpleSmileyList.
  64  */
  65 PurpleSmileyList *purple_smiley_list_new(void);
  66
  67 /**
  68  * purple_smiley_list_add:
  69  * @list: the smiley list.
  70  * @smiley: the smiley to be added.
  71  *
  72  * Adds the @smiley to the @list. A particular @smiley can only be added to
  73  * a single @list. Also, a @list can not contain multiple @smiley's with
  74  * the same shortcut.
  75  *
  76  * It increases the reference count of @smiley, if needed.
  77  *
  78  * Returns: %TRUE if the @smiley was successfully added to the list.
  79  */
  80 gboolean purple_smiley_list_add(PurpleSmileyList *list, PurpleSmiley *smiley);
  81
  82 /**
  83  * purple_smiley_list_remove:
  84  * @list: the smiley list.
  85  * @smiley: the smiley to be removed.
  86  *
  87  * Removes a @smiley from the @list. If @smiley's reference count drops to zero,
  88  * it's destroyed.
  89  */
  90 void purple_smiley_list_remove(PurpleSmileyList *list, PurpleSmiley *smiley);
  91
  92 /**
  93  * purple_smiley_list_is_empty:
  94  * @list: the smiley list.
  95  *
  96  * Checks, if the smiley @list is empty.
  97  *
  98  * Returns: %TRUE if the @list is empty, %FALSE otherwise.
  99  */
 100 gboolean purple_smiley_list_is_empty(PurpleSmileyList *list);
 101
 102 /**
 103  * purple_smiley_list_get_by_shortcut:
 104  * @list: the smiley list.
 105  * @shortcut: the textual representation of smiley to lookup.
 106  *
 107  * Retrieves a smiley with the specified @shortcut from the @list.
 108  *
 109  * Returns: (transfer none): A #PurpleSmiley if the smiley was found, %NULL
 110  *          otherwise.
 111  */
 112 PurpleSmiley *purple_smiley_list_get_by_shortcut(PurpleSmileyList *list, const gchar *shortcut);
 113
 114 /**
 115  * purple_smiley_list_get_trie:
 116  * @list: the smiley list.
 117  *
 118  * Returns the #PurpleTrie for searching of #PurpleSmiley's being kept
 119  * in the @list. It holds markup escaped shortcuts, so if you want to search
 120  * in plain message, you have to escape it first. If you don't do this, it won't
 121  * find smileys containing special characters.
 122  *
 123  * Returns: (transfer none): a #PurpleTrie for contained smileys.
 124  */
 125 PurpleTrie *purple_smiley_list_get_trie(PurpleSmileyList *list);
 126
 127 /**
 128  * purple_smiley_list_get_unique:
 129  * @list_: the smiley list.
 130  *
 131  * Returns the list of smileys with unique image file paths.
 132  *
 133  * Returns: (element-type PurpleSmiley) (transfer container): the list of unique smileys.
 134  */
 135 GList *purple_smiley_list_get_unique(PurpleSmileyList *list_);
 136
 137 /**
 138  * purple_smiley_list_get_all:
 139  * @list_: the smiley list.
 140  *
 141  * Returns the list of all smileys added to the @list_.
 142  *
 143  * Returns: (element-type PurpleSmiley) (transfer container): the list of smileys.
 144  */
 145 GList *purple_smiley_list_get_all(PurpleSmileyList *list_);
 146
 147 G_END_DECLS
 148
 149 #endif /* PURPLE_SMILEY_LIST_H */