/pidgin/main: 9227a7757e92: Comments: PurpleSmiley
Tomasz Wasilczyk
twasilczyk at pidgin.im
Sat Apr 5 11:51:44 EDT 2014
Changeset: 9227a7757e92c821cc6340e212e178625eef419f
Author: Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date: 2014-04-05 17:51 +0200
Branch: default
URL: https://hg.pidgin.im/pidgin/main/rev/9227a7757e92
Description:
Comments: PurpleSmiley
diffstat:
doc/reference/libpurple/libpurple-docs.xml | 14 ++++-
libpurple/memorypool.h | 8 ++
libpurple/smiley-custom.h | 7 ++
libpurple/smiley-list.h | 7 ++
libpurple/smiley-parser.h | 7 ++
libpurple/smiley-remote.h | 7 ++
libpurple/smiley-theme.h | 7 ++
libpurple/smiley.c | 13 +++-
libpurple/smiley.h | 82 +++++++++++++++++++++--------
9 files changed, 124 insertions(+), 28 deletions(-)
diffs (truncated from 338 to 300 lines):
diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -77,7 +77,6 @@
<xi:include href="xml/roomlist.xml" />
<xi:include href="xml/savedstatuses.xml" />
<xi:include href="xml/server.xml" />
- <xi:include href="xml/smiley.xml" />
<xi:include href="xml/sound.xml" />
<xi:include href="xml/sslconn.xml" />
<xi:include href="xml/core.xml" />
@@ -115,6 +114,17 @@
</reference>
<reference label="b">
+ <title>Smiley APIs</title>
+
+ <xi:include href="xml/smiley.xml" />
+ <xi:include href="xml/smiley-remote.xml" />
+ <xi:include href="xml/smiley-custom.xml" />
+ <xi:include href="xml/smiley-list.xml" />
+ <xi:include href="xml/smiley-theme.xml" />
+ <xi:include href="xml/smiley-parser.xml" />
+ </reference>
+
+ <reference label="c">
<title>Media APIs</title>
<xi:include href="xml/media.xml" />
@@ -126,7 +136,7 @@
<xi:include href="xml/enum-types.xml" />
</reference>
- <reference label="c">
+ <reference label="d">
<title>D-Bus Server APIs</title>
<xi:include href="xml/dbus-bindings.xml" />
diff --git a/libpurple/memorypool.h b/libpurple/memorypool.h
--- a/libpurple/memorypool.h
+++ b/libpurple/memorypool.h
@@ -73,6 +73,12 @@ struct _PurpleMemoryPool
/**
* PurpleMemoryPoolClass:
+ * @palloc: alloates memory for a specific memory pool subclass,
+ * see #purple_memory_pool_alloc.
+ * @pfree: frees memory allocated within a pool, see #purple_memory_pool_free.
+ * May be %NULL.
+ * @cleanup: frees (or marks as unused) all memory allocated within a pool.
+ * See #purple_memory_pool_cleanup.
*
* Base class for #PurpleMemoryPool objects.
*/
@@ -81,10 +87,12 @@ struct _PurpleMemoryPoolClass
/*< private >*/
GObjectClass parent_class;
+ /*< public >*/
gpointer (*palloc)(PurpleMemoryPool *pool, gsize size, guint alignment);
gpointer (*pfree)(PurpleMemoryPool *pool, gpointer mem);
void (*cleanup)(PurpleMemoryPool *pool);
+ /*< private >*/
void (*purple_reserved1)(void);
void (*purple_reserved2)(void);
void (*purple_reserved3)(void);
diff --git a/libpurple/smiley-custom.h b/libpurple/smiley-custom.h
--- a/libpurple/smiley-custom.h
+++ b/libpurple/smiley-custom.h
@@ -21,6 +21,13 @@
#ifndef _PURPLE_SMILEY_CUSTOM_H_
#define _PURPLE_SMILEY_CUSTOM_H_
+/**
+ * SECTION:smiley-custom
+ * @include:smiley-custom.h
+ * @section_id: libpurple-smiley-custom
+ * @short_description: a persistent storage for user-defined smileys
+ * @title: Custom smileys storage
+ */
#include "smiley.h"
#include "smiley-list.h"
diff --git a/libpurple/smiley-list.h b/libpurple/smiley-list.h
--- a/libpurple/smiley-list.h
+++ b/libpurple/smiley-list.h
@@ -21,6 +21,13 @@
#ifndef _PURPLE_SMILEY_LIST_H_
#define _PURPLE_SMILEY_LIST_H_
+/**
+ * SECTION:smiley-list
+ * @include:smiley-list.h
+ * @section_id: libpurple-smiley-list
+ * @short_description: a collection of smileys
+ * @title: Smiley lists
+ */
#include <glib-object.h>
diff --git a/libpurple/smiley-parser.h b/libpurple/smiley-parser.h
--- a/libpurple/smiley-parser.h
+++ b/libpurple/smiley-parser.h
@@ -21,6 +21,13 @@
#ifndef _PURPLE_SMILEY_PARSER_H_
#define _PURPLE_SMILEY_PARSER_H_
+/**
+ * SECTION:smiley-parser
+ * @include:smiley-parser.h
+ * @section_id: libpurple-smiley-parser
+ * @short_description: a efficient smiley processor
+ * @title: Smiley parser
+ */
#include "purple.h"
diff --git a/libpurple/smiley-remote.h b/libpurple/smiley-remote.h
--- a/libpurple/smiley-remote.h
+++ b/libpurple/smiley-remote.h
@@ -21,6 +21,13 @@
#ifndef _PURPLE_REMOTE_SMILEY_H_
#define _PURPLE_REMOTE_SMILEY_H_
+/**
+ * SECTION:smiley-remote
+ * @include:smiley-remote.h
+ * @section_id: libpurple-smiley-remote
+ * @short_description: smileys sent by a remote client
+ * @title: Remote smileys
+ */
#include <glib-object.h>
diff --git a/libpurple/smiley-theme.h b/libpurple/smiley-theme.h
--- a/libpurple/smiley-theme.h
+++ b/libpurple/smiley-theme.h
@@ -21,6 +21,13 @@
#ifndef _PURPLE_SMILEY_THEME_H_
#define _PURPLE_SMILEY_THEME_H_
+/**
+ * SECTION:smiley-theme
+ * @include:smiley-theme.h
+ * @section_id: libpurple-smiley-theme
+ * @short_description: a per-protocol defined set of default smileys
+ * @title: Smiley themes
+ */
#include <glib-object.h>
diff --git a/libpurple/smiley.c b/libpurple/smiley.c
--- a/libpurple/smiley.c
+++ b/libpurple/smiley.c
@@ -233,19 +233,26 @@ purple_smiley_class_init(PurpleSmileyCla
ps_class->get_image = purple_smiley_get_image_impl;
properties[PROP_SHORTCUT] = g_param_spec_string("shortcut", "Shortcut",
- "The text-shortcut for the smiley", NULL,
+ "A non-escaped textual representation of a smiley.", NULL,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
properties[PROP_IS_READY] = g_param_spec_boolean("is-ready", "Is ready",
- "The smiley is ready to be displayed", TRUE,
+ "Determines, if a smiley is ready to be displayed.", TRUE,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS);
properties[PROP_PATH] = g_param_spec_string("path", "Path",
- "The full path to the smiley image file", NULL,
+ "The full path to the smiley image file.", NULL,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
g_object_class_install_properties(gobj_class, PROP_LAST, properties);
+ /**
+ * PurpleSmiley::ready:
+ * @smiley: a smiley that became ready.
+ *
+ * Called when a @smiley becames ready to be displayed. It's guaranteed to be
+ * fired at most once for a particular @smiley.
+ */
signals[SIG_READY] = g_signal_new("ready", G_OBJECT_CLASS_TYPE(klass),
0, 0, NULL, NULL,
g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
diff --git a/libpurple/smiley.h b/libpurple/smiley.h
--- a/libpurple/smiley.h
+++ b/libpurple/smiley.h
@@ -23,9 +23,18 @@
#define _PURPLE_SMILEY_H_
/**
* SECTION:smiley
+ * @include:smiley.h
* @section_id: libpurple-smiley
- * @short_description: <filename>smiley.h</filename>
- * @title: Smiley API
+ * @short_description: a link between emoticon image and its textual representation
+ * @title: Smileys
+ *
+ * A #PurpleSmiley is a base class for associating emoticon images and their
+ * textual representation. It's intended for various smiley-related tasks:
+ * parsing the text against them, displaying in the smiley selector, or handling
+ * remote data (using #PurpleRemoteSmiley).
+ *
+ * The #PurpleSmiley:shortcut is always unescaped, but <link linkend="libpurple-smiley-parser">smiley parser</link>
+ * may deal with special characters.
*/
#include "imgstore.h"
@@ -45,9 +54,7 @@ typedef struct _PurpleSmileyClass Purple
/**
* PurpleSmiley:
*
- * A generic smiley.
- *
- * This contains common part of things Purple will need to know about a smiley.
+ * A generic smiley. It can either be a theme smiley, or a custom smiley.
*/
struct _PurpleSmiley
{
@@ -55,13 +62,22 @@ struct _PurpleSmiley
GObject parent;
};
+/**
+ * PurpleSmileyClass:
+ * @get_image: gets image contents for a @smiley. May not require
+ * #PurpleSmiley:path being set. See #purple_smiley_get_image.
+ *
+ * Base class for #PurpleSmiley objects.
+ */
struct _PurpleSmileyClass
{
/*< private >*/
GObjectClass parent_class;
+ /*< public >*/
PurpleStoredImage * (*get_image)(PurpleSmiley *smiley);
+ /*< private >*/
void (*purple_reserved1)(void);
void (*purple_reserved2)(void);
void (*purple_reserved3)(void);
@@ -73,56 +89,76 @@ G_BEGIN_DECLS
/**
* purple_smiley_get_type:
*
- * Returns: The #GType for a smiley.
+ * Returns: the #GType for a smiley.
*/
GType
purple_smiley_get_type(void);
-/**************************************************************************/
-/* Smiley API */
-/**************************************************************************/
-
/**
* purple_smiley_new:
- * @shortcut: The smiley shortcut.
- * @path: The image file path.
+ * @shortcut: the smiley shortcut (unescaped).
+ * @path: the smiley image file path.
*
- * Creates new shortcut, which is ready to display.
+ * Creates new smiley, which is ready to display (its file exists
+ * and is a valid image).
*
- * Returns: The shortcut.
+ * Returns: the new #PurpleSmiley.
*/
PurpleSmiley *
purple_smiley_new(const gchar *shortcut, const gchar *path);
/**
* purple_smiley_get_shortcut:
- * @smiley: The smiley.
+ * @smiley: the smiley.
*
- * Returns the smiley's associated shortcut (e.g. "(homer)" or ":-)").
+ * Returns the @smiley's associated shortcut (e.g. <literal>(homer)</literal> or
+ * <literal>:-)</literal>).
*
- * Returns: The shortcut.
+ * Returns: the unescaped shortcut.
*/
const gchar *
purple_smiley_get_shortcut(const PurpleSmiley *smiley);
+/**
+ * purple_smiley_is_ready:
+ * @smiley: the smiley.
+ *
+ * Checks, if the @smiley is ready to be displayed. For #PurpleSmiley it's
+ * always %TRUE, but for deriving classes it may vary.
+ *
+ * Being ready means either its #PurpleSmiley:path is set and file exists,
+ * or its contents is available via #purple_smiley_get_image. The latter is
+ * always true, but not always efficient.
+ *
More information about the Commits
mailing list