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 G_BEGIN_DECLS
  46
  47 #define PURPLE_TYPE_SMILEY  purple_smiley_get_type()
  48
  49 /**
  50  * purple_smiley_get_type:
  51  *
  52  * Returns: the #GType for a smiley.
  53  */
  54 G_DECLARE_FINAL_TYPE(PurpleSmiley, purple_smiley, PURPLE, SMILEY, PurpleImage)
  55
  56 /**
  57  * purple_smiley_new:
  58  * @shortcut: the smiley shortcut (unescaped).
  59  * @path: the smiley image file path.
  60  *
  61  * Creates new smiley, which is ready to display (its file exists
  62  * and is a valid image).
  63  *
  64  * Returns: the new #PurpleSmiley.
  65  */
  66 PurpleSmiley *purple_smiley_new(const gchar *shortcut, const gchar *path);
  67
  68 /**
  69  * purple_smiley_new_from_data:
  70  * @shortcut: The smiley shortcut (unescaped).
  71  * @data: The raw data of the image.
  72  * @length: The length of @data in bytes.
  73  *
  74  * Creates new smiley from @data.
  75  *
  76  * Returns: A new #PurpleSmiley.
  77  */
  78 PurpleSmiley *purple_smiley_new_from_data(const gchar *shortcut, const guint8 *data, gsize length);
  79
  80 /**
  81  * purple_smiley_new_remote:
  82  * @shortcut: the smiley shortcut (unescaped).
  83  *
  84  * Creates new remote smiley. It's not bound to any conversation, so most
  85  * probably you might want to use
  86  * #purple_conversation_add_remote_smiley instead.
  87  *
  88  * Returns: the new remote #PurpleSmiley.
  89  */
  90 PurpleSmiley *purple_smiley_new_remote(const gchar *shortcut);
  91
  92 /**
  93  * purple_smiley_get_shortcut:
  94  * @smiley: the smiley.
  95  *
  96  * Returns the @smiley's associated shortcut (e.g. <literal>(homer)</literal> or
  97  * <literal>:-)</literal>).
  98  *
  99  * Returns: the unescaped shortcut.
 100  */
 101 const gchar *purple_smiley_get_shortcut(PurpleSmiley *smiley);
 102
 103 G_END_DECLS
 104
 105 #endif /* PURPLE_SMILEY_H */