Mercurial > pidgin3 / file comparison

comparison: libpurple/smiley-list.h

libpurple/smiley-list.h

changeset 35777
23e6e95b45d3
parent 35774
9227a7757e92
child 38281
df274be2afa2
equal deleted inserted replaced
35776:901a94245460 35777:23e6e95b45d3
25 * SECTION:smiley-list 25 * SECTION:smiley-list
26 * @include:smiley-list.h 26 * @include:smiley-list.h
27 * @section_id: libpurple-smiley-list 27 * @section_id: libpurple-smiley-list
28 * @short_description: a collection of smileys 28 * @short_description: a collection of smileys
29 * @title: Smiley lists 29 * @title: Smiley lists
30 *
31 * A #PurpleSmileyList is a handy storage for a set of #PurpleSmiley's.
32 * It holds structures needed for parsing, accessing them by a shortcut, or
33 * listing (either all, or by unique image).
30 */ 34 */
31 35
32 #include <glib-object.h> 36 #include <glib-object.h>
33 37
34 #include "smiley.h" 38 #include "smiley.h"
45 #define PURPLE_SMILEY_LIST_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_SMILEY_LIST, PurpleSmileyListClass)) 49 #define PURPLE_SMILEY_LIST_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_SMILEY_LIST, PurpleSmileyListClass))
46 50
47 /** 51 /**
48 * PurpleSmileyList: 52 * PurpleSmileyList:
49 * 53 *
50 * A list of smileys. 54 * A container for #PurpleSmiley's.
51 */ 55 */
52 struct _PurpleSmileyList 56 struct _PurpleSmileyList
53 { 57 {
54 /*< private >*/ 58 /*< private >*/
55 GObject parent; 59 GObject parent;
56 }; 60 };
57 61
62 /**
63 * PurpleSmileyListClass:
64 *
65 * Base class for #PurpleSmileyList objects.
66 */
58 struct _PurpleSmileyListClass 67 struct _PurpleSmileyListClass
59 { 68 {
60 /*< private >*/ 69 /*< private >*/
61 GObjectClass parent_class; 70 GObjectClass parent_class;
62 71
69 G_BEGIN_DECLS 78 G_BEGIN_DECLS
70 79
71 /** 80 /**
72 * purple_smiley_list_get_type: 81 * purple_smiley_list_get_type:
73 * 82 *
74 * Returns: The #GType for a smiley list. 83 * Returns: the #GType for a smiley list.
75 */ 84 */
76 GType 85 GType
77 purple_smiley_list_get_type(void); 86 purple_smiley_list_get_type(void);
78 87
88 /**
89 * purple_smiley_list_new:
90 *
91 * Creates new #PurpleSmileyList. You might prefer using existing lists, like
92 * #purple_smiley_custom_get_list or #purple_conversation_get_remote_smileys
93 * (the latter is read-only, accessed with
94 * #purple_conversation_add_remote_smiley and
95 * #purple_conversation_get_remote_smiley).
96 *
97 * Returns: newly created #PurpleSmileyList.
98 */
79 PurpleSmileyList * 99 PurpleSmileyList *
80 purple_smiley_list_new(void); 100 purple_smiley_list_new(void);
81 101
102 /**
103 * purple_smiley_list_add:
104 * @list: the smiley list.
105 * @smiley: the smiley to be added.
106 *
107 * Adds the @smiley to the @list. A particular @smiley can only be added to
108 * a single @list. Also, a @list can not contain multiple @smiley's with
109 * the same shortcut.
110 *
111 * It increases the reference count of @smiley, if needed.
112 *
113 * Returns: %TRUE if the @smiley was successfully added to the list.
114 */
82 gboolean 115 gboolean
83 purple_smiley_list_add(PurpleSmileyList *list, PurpleSmiley *smiley); 116 purple_smiley_list_add(PurpleSmileyList *list, PurpleSmiley *smiley);
84 117
118 /**
119 * purple_smiley_list_remove:
120 * @list: the smiley list.
121 * @smiley: the smiley to be removed.
122 *
123 * Removes a @smiley from the @list. If @smiley's reference count drops to zero,
124 * it's destroyed.
125 */
85 void 126 void
86 purple_smiley_list_remove(PurpleSmileyList *list, PurpleSmiley *smiley); 127 purple_smiley_list_remove(PurpleSmileyList *list, PurpleSmiley *smiley);
87 128
129 /**
130 * purple_smiley_list_is_empty:
131 * @list: the smiley list.
132 *
133 * Checks, if the smiley @list is empty.
134 *
135 * Returns: %TRUE if the @list is empty, %FALSE otherwise.
136 */
88 gboolean 137 gboolean
89 purple_smiley_list_is_empty(PurpleSmileyList *list); 138 purple_smiley_list_is_empty(PurpleSmileyList *list);
90 139
140 /**
141 * purple_smiley_list_get_by_shortcut:
142 * @list: the smiley list.
143 * @shortcut: the textual representation of smiley to lookup.
144 *
145 * Retrieves a smiley with the specified @shortcut from the @list.
146 *
147 * Returns: a #PurpleSmiley if the smiley was found, %NULL otherwise.
148 */
91 PurpleSmiley * 149 PurpleSmiley *
92 purple_smiley_list_get_by_shortcut(PurpleSmileyList *list, 150 purple_smiley_list_get_by_shortcut(PurpleSmileyList *list,
93 const gchar *shortcut); 151 const gchar *shortcut);
94 152
95 /* keys are HTML escaped shortcuts */ 153 /**
154 * purple_smiley_list_get_trie:
155 * @list: the smiley list.
156 *
157 * Returns the #PurpleTrie for searching of #PurpleSmiley's being kept
158 * in the @list. It holds markup escaped shortcuts, so if you want to search
159 * in plain message, you have to escape it first. If you don't do this, it won't
160 * find smileys containing special characters.
161 *
162 * Returns: (transfer none): a #PurpleTrie for contained smileys.
163 */
96 PurpleTrie * 164 PurpleTrie *
97 purple_smiley_list_get_trie(PurpleSmileyList *list); 165 purple_smiley_list_get_trie(PurpleSmileyList *list);
98 166
167 /**
168 * purple_smiley_list_get_unique:
169 * @list_: the smiley list.
170 *
171 * Returns the list of smileys with unique image file paths.
172 *
173 * Returns: (transfer container): the #GList of unique smileys. Use #g_list_free
174 * when done using it.
175 */
99 GList * 176 GList *
100 purple_smiley_list_get_unique(PurpleSmileyList *list_); 177 purple_smiley_list_get_unique(PurpleSmileyList *list_);
101 178
179 /**
180 * purple_smiley_list_get_all:
181 * @list_: the smiley list.
182 *
183 * Returns the list of all smileys added to the @list_.
184 *
185 * Returns: (transfer container): the #GList of smileys. Use #g_list_free
186 * when done using it.
187 */
102 GList * 188 GList *
103 purple_smiley_list_get_all(PurpleSmileyList *list_); 189 purple_smiley_list_get_all(PurpleSmileyList *list_);
104 190
105 G_END_DECLS 191 G_END_DECLS
106 192

Mercurial Repository: pidgin3

mercurial