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