libpurple/smiley.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_H_
  23 #define _PURPLE_SMILEY_H_
  24 /**
  25  * SECTION:smiley
  26  * @include:smiley.h
  27  * @section_id: libpurple-smiley
  28  * @short_description: a link between emoticon image and its textual representation
  29  * @title: Smileys
  30  *
  31  * A #PurpleSmiley is a base class for associating emoticon images and their
  32  * textual representation. It's intended for various smiley-related tasks:
  33  * parsing the text against them, displaying in the smiley selector, or handling
  34  * remote data (using #PurpleRemoteSmiley).
  35  *
  36  * The #PurpleSmiley:shortcut is always unescaped, but <link linkend="libpurple-smiley-parser">smiley parser</link>
  37  * may deal with special characters.
  38  */
  39
  40 #include "image.h"
  41
  42 #include <glib-object.h>
  43
  44 typedef struct _PurpleSmiley PurpleSmiley;
  45 typedef struct _PurpleSmileyClass PurpleSmileyClass;
  46
  47 #define PURPLE_TYPE_SMILEY            (purple_smiley_get_type())
  48 #define PURPLE_SMILEY(smiley)         (G_TYPE_CHECK_INSTANCE_CAST((smiley), PURPLE_TYPE_SMILEY, PurpleSmiley))
  49 #define PURPLE_SMILEY_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_SMILEY, PurpleSmileyClass))
  50 #define PURPLE_IS_SMILEY(smiley)      (G_TYPE_CHECK_INSTANCE_TYPE((smiley), PURPLE_TYPE_SMILEY))
  51 #define PURPLE_IS_SMILEY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_SMILEY))
  52 #define PURPLE_SMILEY_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_SMILEY, PurpleSmileyClass))
  53
  54 /**
  55  * PurpleSmiley:
  56  *
  57  * A generic smiley. It can either be a theme smiley, or a custom smiley.
  58  */
  59 struct _PurpleSmiley
  60 {
  61         /*< private >*/
  62         GObject parent;
  63 };
  64
  65 /**
  66  * PurpleSmileyClass:
  67  *
  68  * Base class for #PurpleSmiley objects.
  69  */
  70 struct _PurpleSmileyClass
  71 {
  72         /*< private >*/
  73         GObjectClass parent_class;
  74
  75         /*< private >*/
  76         void (*purple_reserved1)(void);
  77         void (*purple_reserved2)(void);
  78         void (*purple_reserved3)(void);
  79         void (*purple_reserved4)(void);
  80 };
  81
  82 G_BEGIN_DECLS
  83
  84 /**
  85  * purple_smiley_get_type:
  86  *
  87  * Returns: the #GType for a smiley.
  88  */
  89 GType
  90 purple_smiley_get_type(void);
  91
  92 /**
  93  * purple_smiley_new:
  94  * @shortcut: the smiley shortcut (unescaped).
  95  * @path: the smiley image file path.
  96  *
  97  * Creates new smiley, which is ready to display (its file exists
  98  * and is a valid image).
  99  *
 100  * Returns: the new #PurpleSmiley.
 101  */
 102 PurpleSmiley *
 103 purple_smiley_new(const gchar *shortcut, const gchar *path);
 104
 105 /**
 106  * purple_smiley_new_remote:
 107  * @shortcut: the smiley shortcut (unescaped).
 108  *
 109  * Creates new remote smiley. It's not bound to any conversation, so most
 110  * probably you might want to use
 111  * #purple_conversation_add_remote_smiley instead.
 112  *
 113  * Returns: the new remote #PurpleSmiley.
 114  */
 115 PurpleSmiley *
 116 purple_smiley_new_remote(const gchar *shortcut);
 117
 118 /**
 119  * purple_smiley_get_shortcut:
 120  * @smiley: the smiley.
 121  *
 122  * Returns the @smiley's associated shortcut (e.g. <literal>(homer)</literal> or
 123  * <literal>:-)</literal>).
 124  *
 125  * Returns: the unescaped shortcut.
 126  */
 127 const gchar *
 128 purple_smiley_get_shortcut(const PurpleSmiley *smiley);
 129
 130 /**
 131  * purple_smiley_get_image:
 132  * @smiley: the smiley.
 133  *
 134  * Returns the image contents for a @smiley. It may not be ready for remote
 135  * smileys, so check it with #purple_image_is_ready.
 136  *
 137  * If you want to save it, increase a ref count for the returned object.
 138  *
 139  * Returns: (transfer none): the image contents for a @smiley.
 140  */
 141 PurpleImage *
 142 purple_smiley_get_image(PurpleSmiley *smiley);
 143
 144 G_END_DECLS
 145
 146 #endif /* _PURPLE_SMILEY_H_ */