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 typedef struct _PurpleSmileyList PurpleSmileyList;
  43 typedef struct _PurpleSmileyListClass PurpleSmileyListClass;
  44
  45 #define PURPLE_TYPE_SMILEY_LIST            (purple_smiley_list_get_type())
  46 #define PURPLE_SMILEY_LIST(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_SMILEY_LIST, PurpleSmileyList))
  47 #define PURPLE_SMILEY_LIST_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_SMILEY_LIST, PurpleSmileyListClass))
  48 #define PURPLE_IS_SMILEY_LIST(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_SMILEY_LIST))
  49 #define PURPLE_IS_SMILEY_LIST_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_SMILEY_LIST))
  50 #define PURPLE_SMILEY_LIST_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_SMILEY_LIST, PurpleSmileyListClass))
  51
  52 /**
  53  * PurpleSmileyList:
  54  *
  55  * A container for #PurpleSmiley's.
  56  */
  57 struct _PurpleSmileyList {
  58         /*< private >*/
  59         GObject parent;
  60 };
  61
  62 struct _PurpleSmileyListClass {
  63         /*< private >*/
  64         GObjectClass parent_class;
  65
  66         void (*purple_reserved1)(void);
  67         void (*purple_reserved2)(void);
  68         void (*purple_reserved3)(void);
  69         void (*purple_reserved4)(void);
  70 };
  71
  72 G_BEGIN_DECLS
  73
  74 /**
  75  * purple_smiley_list_get_type:
  76  *
  77  * Returns: the #GType for a smiley list.
  78  */
  79 GType purple_smiley_list_get_type(void);
  80
  81 /**
  82  * purple_smiley_list_new:
  83  *
  84  * Creates new #PurpleSmileyList. You might prefer using existing lists, like
  85  * #purple_smiley_custom_get_list or #purple_conversation_get_remote_smileys
  86  * (the latter is read-only, accessed with
  87  * #purple_conversation_add_remote_smiley and
  88  * #purple_conversation_get_remote_smiley).
  89  *
  90  * Returns: newly created #PurpleSmileyList.
  91  */
  92 PurpleSmileyList *purple_smiley_list_new(void);
  93
  94 /**
  95  * purple_smiley_list_add:
  96  * @list: the smiley list.
  97  * @smiley: the smiley to be added.
  98  *
  99  * Adds the @smiley to the @list. A particular @smiley can only be added to
 100  * a single @list. Also, a @list can not contain multiple @smiley's with
 101  * the same shortcut.
 102  *
 103  * It increases the reference count of @smiley, if needed.
 104  *
 105  * Returns: %TRUE if the @smiley was successfully added to the list.
 106  */
 107 gboolean purple_smiley_list_add(PurpleSmileyList *list, PurpleSmiley *smiley);
 108
 109 /**
 110  * purple_smiley_list_remove:
 111  * @list: the smiley list.
 112  * @smiley: the smiley to be removed.
 113  *
 114  * Removes a @smiley from the @list. If @smiley's reference count drops to zero,
 115  * it's destroyed.
 116  */
 117 void purple_smiley_list_remove(PurpleSmileyList *list, PurpleSmiley *smiley);
 118
 119 /**
 120  * purple_smiley_list_is_empty:
 121  * @list: the smiley list.
 122  *
 123  * Checks, if the smiley @list is empty.
 124  *
 125  * Returns: %TRUE if the @list is empty, %FALSE otherwise.
 126  */
 127 gboolean purple_smiley_list_is_empty(const PurpleSmileyList *list);
 128
 129 /**
 130  * purple_smiley_list_get_by_shortcut:
 131  * @list: the smiley list.
 132  * @shortcut: the textual representation of smiley to lookup.
 133  *
 134  * Retrieves a smiley with the specified @shortcut from the @list.
 135  *
 136  * Returns: a #PurpleSmiley if the smiley was found, %NULL otherwise.
 137  */
 138 PurpleSmiley *purple_smiley_list_get_by_shortcut(PurpleSmileyList *list, const gchar *shortcut);
 139
 140 /**
 141  * purple_smiley_list_get_trie:
 142  * @list: the smiley list.
 143  *
 144  * Returns the #PurpleTrie for searching of #PurpleSmiley's being kept
 145  * in the @list. It holds markup escaped shortcuts, so if you want to search
 146  * in plain message, you have to escape it first. If you don't do this, it won't
 147  * find smileys containing special characters.
 148  *
 149  * Returns: (transfer none): a #PurpleTrie for contained smileys.
 150  */
 151 PurpleTrie *purple_smiley_list_get_trie(PurpleSmileyList *list);
 152
 153 /**
 154  * purple_smiley_list_get_unique:
 155  * @list_: the smiley list.
 156  *
 157  * Returns the list of smileys with unique image file paths.
 158  *
 159  * Returns: (element-type PurpleSmiley) (transfer container): the list of unique smileys.
 160  */
 161 GList *purple_smiley_list_get_unique(PurpleSmileyList *list_);
 162
 163 /**
 164  * purple_smiley_list_get_all:
 165  * @list_: the smiley list.
 166  *
 167  * Returns the list of all smileys added to the @list_.
 168  *
 169  * Returns: (element-type PurpleSmiley) (transfer container): the list of smileys.
 170  */
 171 GList *purple_smiley_list_get_all(PurpleSmileyList *list_);
 172
 173 G_END_DECLS
 174
 175 #endif /* PURPLE_SMILEY_LIST_H */