libpurple/smiley-theme.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_THEME_H_
  23 #define _PURPLE_SMILEY_THEME_H_
  24 /**
  25  * SECTION:smiley-theme
  26  * @include:smiley-theme.h
  27  * @section_id: libpurple-smiley-theme
  28  * @short_description: a categorized set of standard smileys
  29  * @title: Smiley themes
  30  *
  31  * A smiley theme is a set of standard smileys, that may be displayed in user's
  32  * message window instead of their textual representations. It may be
  33  * categorized depending on the selected protocol, as in #PidginSmileyTheme, but
  34  * it's up to the UI to choose behavior.
  35  */
  36
  37 #include <glib-object.h>
  38
  39 #include "smiley.h"
  40 #include "smiley-list.h"
  41
  42 typedef struct _PurpleSmileyTheme PurpleSmileyTheme;
  43 typedef struct _PurpleSmileyThemeClass PurpleSmileyThemeClass;
  44
  45 #define PURPLE_TYPE_SMILEY_THEME            (purple_smiley_theme_get_type())
  46 #define PURPLE_SMILEY_THEME(smiley)         (G_TYPE_CHECK_INSTANCE_CAST((smiley), PURPLE_TYPE_SMILEY_THEME, PurpleSmileyTheme))
  47 #define PURPLE_SMILEY_THEME_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_SMILEY_THEME, PurpleSmileyThemeClass))
  48 #define PURPLE_IS_SMILEY_THEME(smiley)      (G_TYPE_CHECK_INSTANCE_TYPE((smiley), PURPLE_TYPE_SMILEY_THEME))
  49 #define PURPLE_IS_SMILEY_THEME_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_SMILEY_THEME))
  50 #define PURPLE_SMILEY_THEME_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_SMILEY_THEME, PurpleSmileyThemeClass))
  51
  52 /**
  53  * PurpleSmileyTheme:
  54  *
  55  * An abstract class for smiley theme.
  56  */
  57 struct _PurpleSmileyTheme
  58 {
  59         /*< private >*/
  60         GObject parent;
  61 };
  62
  63 /**
  64  * PurpleSmileyThemeClass:
  65  * @get_smileys: a callback for getting smiley list based on choosen category.
  66  *               The criteria for a category are being passed using the
  67  *               @ui_data parameter.
  68  * @activate: a callback being fired after activating the @theme. It may be used
  69  *            for loading its contents before using @get_smileys callback.
  70  *
  71  * Base class for #PurpleSmileyTheme objects.
  72  */
  73 struct _PurpleSmileyThemeClass
  74 {
  75         /*< private >*/
  76         GObjectClass parent_class;
  77
  78         /*< public >*/
  79         PurpleSmileyList * (*get_smileys)(PurpleSmileyTheme *theme,
  80                 gpointer ui_data);
  81         void (*activate)(PurpleSmileyTheme *theme);
  82
  83         /*< private >*/
  84         void (*purple_reserved1)(void);
  85         void (*purple_reserved2)(void);
  86         void (*purple_reserved3)(void);
  87         void (*purple_reserved4)(void);
  88 };
  89
  90 G_BEGIN_DECLS
  91
  92 /**
  93  * purple_smiley_theme_get_type:
  94  *
  95  * Returns: the #GType for a smiley list.
  96  */
  97 GType
  98 purple_smiley_theme_get_type(void);
  99
 100 /**
 101  * purple_smiley_theme_get_smileys:
 102  * @theme: the smiley theme.
 103  * @ui_data: the UI-passed criteria to choose a smiley set.
 104  *
 105  * Retrieves a smiley category based on UI-provided criteria.
 106  *
 107  * You might want to use <link linkend="libpurple-smiley-parser">smiley
 108  * parser</link> instead. It's mostly for the UI, prpls shouldn't use it.
 109  *
 110  * Returns: (transfer none): a #PurpleSmileyList with standard smileys to use.
 111  */
 112 PurpleSmileyList *
 113 purple_smiley_theme_get_smileys(PurpleSmileyTheme *theme, gpointer ui_data);
 114
 115 /**
 116  * purple_smiley_theme_set_current:
 117  * @theme: the smiley theme to be set as currently used. May be %NULL.
 118  *
 119  * Sets the new smiley theme to be used for displaying messages.
 120  */
 121 void
 122 purple_smiley_theme_set_current(PurpleSmileyTheme *theme);
 123
 124 /**
 125  * purple_smiley_theme_get_current:
 126  *
 127  * Returns the currently used smiley theme.
 128  *
 129  * Returns: the #PurpleSmileyTheme or %NULL, if none is set.
 130  */
 131 PurpleSmileyTheme *
 132 purple_smiley_theme_get_current(void);
 133
 134 /**
 135  * _purple_smiley_theme_uninit: (skip)
 136  *
 137  * Uninitializes the smileys theme subsystem.
 138  */
 139 void
 140 _purple_smiley_theme_uninit(void);
 141
 142 G_END_DECLS
 143
 144 #endif /* _PURPLE_SMILEY_THEME_H_ */