/pidgin/main: 8ea15abd8688: Comments: PurpleSmileyTheme

[Tomasz Wasilczyk]

Changeset: 8ea15abd868801ad2b1645244514275f884543d7
Author:	 Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date:	 2014-04-05 19:49 +0200
Branch:	 default
URL: https://hg.pidgin.im/pidgin/main/rev/8ea15abd8688

Description:

Comments: PurpleSmileyTheme

diffstat:

 doc/reference/pidgin/pidgin-docs.xml |   2 +
 libpurple/core.c                     |   2 +-
 libpurple/smiley-theme.c             |   2 +-
 libpurple/smiley-theme.h             |  55 +++++++++++++++++++++++++++++++++--
 4 files changed, 55 insertions(+), 6 deletions(-)

diffs (146 lines):

diff --git a/doc/reference/pidgin/pidgin-docs.xml b/doc/reference/pidgin/pidgin-docs.xml
--- a/doc/reference/pidgin/pidgin-docs.xml
+++ b/doc/reference/pidgin/pidgin-docs.xml
@@ -55,6 +55,8 @@
       <xi:include href="xml/gtkroomlist.xml" />
       <xi:include href="xml/gtksavedstatuses.xml" />
       <xi:include href="xml/gtkscrollbook.xml" />
+      <xi:include href="xml/gtksmiley-manager.xml" />
+      <xi:include href="xml/gtksmiley-theme.xml" />
       <xi:include href="xml/gtksound.xml" />
       <xi:include href="xml/gtkstatusbox.xml" />
       <xi:include href="xml/pidginstock.xml" />
diff --git a/libpurple/core.c b/libpurple/core.c
--- a/libpurple/core.c
+++ b/libpurple/core.c
@@ -256,7 +256,7 @@ purple_core_quit(void)
 	purple_plugins_unload(PURPLE_PLUGIN_STANDARD);
 
 	/* Save .xml files, remove signals, etc. */
-	purple_smiley_theme_uninit();
+	_purple_smiley_theme_uninit();
 	_purple_smiley_custom_uninit();
 	purple_http_uninit();
 	purple_idle_uninit();
diff --git a/libpurple/smiley-theme.c b/libpurple/smiley-theme.c
--- a/libpurple/smiley-theme.c
+++ b/libpurple/smiley-theme.c
@@ -68,7 +68,7 @@ purple_smiley_theme_get_current(void)
 }
 
 void
-purple_smiley_theme_uninit(void)
+_purple_smiley_theme_uninit(void)
 {
 	purple_smiley_theme_set_current(NULL);
 }
diff --git a/libpurple/smiley-theme.h b/libpurple/smiley-theme.h
--- a/libpurple/smiley-theme.h
+++ b/libpurple/smiley-theme.h
@@ -25,8 +25,13 @@
  * SECTION:smiley-theme
  * @include:smiley-theme.h
  * @section_id: libpurple-smiley-theme
- * @short_description: a per-protocol defined set of default smileys
+ * @short_description: a categorized set of standard smileys
  * @title: Smiley themes
+ *
+ * A smiley theme is a set of standard smileys, that may be displayed in user's
+ * message window instead of their textual representations. It may be
+ * categorized depending on the selected protocol, as in #PidginSmileyTheme, but
+ * it's up to the UI to choose behavior.
  */
 
 #include <glib-object.h>
@@ -47,7 +52,7 @@ typedef struct _PurpleSmileyThemeClass P
 /**
  * PurpleSmileyTheme:
  *
- * A list of smileys.
+ * An abstract class for smiley theme.
  */
 struct _PurpleSmileyTheme
 {
@@ -55,15 +60,27 @@ struct _PurpleSmileyTheme
 	GObject parent;
 };
 
+/**
+ * PurpleSmileyThemeClass:
+ * @get_smileys: a callback for getting smiley list based on choosen category.
+ *               The criteria for a category are being passed using the
+ *               @ui_data parameter.
+ * @activate: a callback being fired after activating the @theme. It may be used
+ *            for loading its contents before using @get_smileys callback.
+ *
+ * Base class for #PurpleSmileyTheme objects.
+ */
 struct _PurpleSmileyThemeClass
 {
 	/*< private >*/
 	GObjectClass parent_class;
 
+	/*< public >*/
 	PurpleSmileyList * (*get_smileys)(PurpleSmileyTheme *theme,
 		gpointer ui_data);
 	void (*activate)(PurpleSmileyTheme *theme);
 
+	/*< private >*/
 	void (*purple_reserved1)(void);
 	void (*purple_reserved2)(void);
 	void (*purple_reserved3)(void);
@@ -75,22 +92,52 @@ G_BEGIN_DECLS
 /**
  * purple_smiley_theme_get_type:
  *
- * Returns: The #GType for a smiley list.
+ * Returns: the #GType for a smiley list.
  */
 GType
 purple_smiley_theme_get_type(void);
 
+/**
+ * purple_smiley_theme_get_smileys:
+ * @theme: the smiley theme.
+ * @ui_data: the UI-passed criteria to choose a smiley set.
+ *
+ * Retrieves a smiley category based on UI-provided criteria.
+ *
+ * You might want to use <link linkend="libpurple-smiley-parser">smiley
+ * parser</link> instead. It's mostly for the UI, prpls shouldn't use it.
+ *
+ * Returns: (transfer none): a #PurpleSmileyList with standard smileys to use.
+ */
 PurpleSmileyList *
 purple_smiley_theme_get_smileys(PurpleSmileyTheme *theme, gpointer ui_data);
 
+/**
+ * purple_smiley_theme_set_current:
+ * @theme: the smiley theme to be set as currently used. May be %NULL.
+ *
+ * Sets the new smiley theme to be used for displaying messages.
+ */
 void
 purple_smiley_theme_set_current(PurpleSmileyTheme *theme);
 
+/**
+ * purple_smiley_theme_get_current:
+ *
+ * Returns the currently used smiley theme.
+ *
+ * Returns: the #PurpleSmileyTheme or %NULL, if none is set.
+ */
 PurpleSmileyTheme *
 purple_smiley_theme_get_current(void);
 
+/**
+ * _purple_smiley_theme_uninit: (skip)
+ *
+ * Uninitializes the smileys theme subsystem.
+ */
 void
-purple_smiley_theme_uninit(void);
+_purple_smiley_theme_uninit(void);
 
 G_END_DECLS