src/ibustext.h

   1 /* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
   2 /* vim:set et sts=4: */
   3 /* IBus - The Input Bus
   4  * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
   5  * Copyright (C) 2008-2010 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library 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 GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
  20  * USA
  21  */
  22
  23 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
  24 #error "Only <ibus.h> can be included directly"
  25 #endif
  26
  27 /**
  28  * SECTION: ibustext
  29  * @short_description: Text with decorating information.
  30  * @see_also: #IBusAttribute
  31  *
  32  * An IBusText is the main text object in IBus.
  33  * The text is decorated according to associated IBusAttribute,
  34  * e.g. the foreground/background color, underline, and
  35  * applied scope.
  36  */
  37
  38 #ifndef __IBUS_TEXT_H_
  39 #define __IBUS_TEXT_H_
  40
  41 #include "ibusserializable.h"
  42 #include "ibusattrlist.h"
  43
  44 /*
  45  * Type macros.
  46  */
  47 /* define IBusText macros */
  48 #define IBUS_TYPE_TEXT             \
  49     (ibus_text_get_type ())
  50 #define IBUS_TEXT(obj)             \
  51     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_TEXT, IBusText))
  52 #define IBUS_TEXT_CLASS(klass)     \
  53     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_TEXT, IBusTextClass))
  54 #define IBUS_IS_TEXT(obj)          \
  55     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_TEXT))
  56 #define IBUS_IS_TEXT_CLASS(klass)  \
  57     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_TEXT))
  58 #define IBUS_TEXT_GET_CLASS(obj)   \
  59     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_TEXT, IBusTextClass))
  60
  61 G_BEGIN_DECLS
  62
  63 typedef struct _IBusText IBusText;
  64 typedef struct _IBusTextClass IBusTextClass;
  65
  66 /**
  67  * IBusText:
  68  * @is_static: Whether @text is static, i.e., no need and will not be freed. Only TRUE if IBusText is newed from ibus_text_new_from_static_string().
  69  * @text: The string content of IBusText in UTF-8.
  70  * @attrs: Associated IBusAttributes.
  71  *
  72  * A text object in IBus.
  73  */
  74 struct _IBusText {
  75     IBusSerializable parent;
  76
  77     /* members */
  78     /*< public >*/
  79     gboolean is_static;
  80     gchar  *text;
  81     IBusAttrList *attrs;
  82 };
  83
  84 struct _IBusTextClass {
  85     IBusSerializableClass parent;
  86 };
  87
  88 GType            ibus_text_get_type                 (void);
  89
  90 /**
  91  * ibus_text_new_from_string:
  92  * @str: An text string to be set.
  93  * @returns: A newly allocated IBusText.
  94  *
  95  * New an IBusText from a string.
  96  *
  97  * @str will be duplicated in IBusText, so feel free to free @str after this function.
  98  */
  99 IBusText        *ibus_text_new_from_string          (const gchar    *str);
 100
 101 /**
 102  * ibus_text_new_from_ucs4:
 103  * @str: An text string to be set.
 104  * @returns: A newly allocated IBusText.
 105  *
 106  * New an IBusText from an UCS-4 encoded string.
 107  *
 108  * @str will be duplicated in IBusText, so feel free to free @str after this function.
 109  */
 110 IBusText        *ibus_text_new_from_ucs4            (const gunichar *str);
 111
 112 /**
 113  * ibus_text_new_from_static_string: (skip)
 114  * @str: An text string to be set.
 115  * @returns: A newly allocated IBusText.
 116  *
 117  * New an IBusText from a static string.
 118  *
 119  * Since @str is a static string which won't be freed.
 120  * This function will NOT duplicate @str.
 121  */
 122 IBusText        *ibus_text_new_from_static_string   (const gchar    *str);
 123
 124 /**
 125  * ibus_text_new_from_printf:
 126  * @fmt: printf format string.
 127  * @...: arguments for @fmt.
 128  * @returns: A newly allocated IBusText.
 129  *
 130  * New an IBusText from a printf expression.
 131  *
 132  * The result of printf expression is stored in the new IBusText instance.
 133  */
 134 IBusText        *ibus_text_new_from_printf          (const gchar    *fmt,
 135                                                      ...) G_GNUC_PRINTF (1, 2);
 136
 137 /**
 138  * ibus_text_new_from_unichar:
 139  * @c: A single UCS4-encoded character.
 140  * @returns: A newly allocated IBusText.
 141  *
 142  * New an IBusText from a single UCS4-encoded character.
 143  */
 144 IBusText        *ibus_text_new_from_unichar         (gunichar        c);
 145
 146 /**
 147  * ibus_text_append_attribute:
 148  * @text: an IBusText
 149  * @type: IBusAttributeType for @text.
 150  * @value: Value for the type.
 151  * @start_index: The starting index, inclusive.
 152  * @end_index: The ending index, exclusive.
 153  *
 154  * Append an IBusAttribute for IBusText.
 155  */
 156 void             ibus_text_append_attribute         (IBusText       *text,
 157                                                      guint           type,
 158                                                      guint           value,
 159                                                      guint           start_index,
 160                                                      gint            end_index);
 161 /**
 162  * ibus_text_get_length:
 163  * @text: An IBusText.
 164  * @returns: Number of character in @text, not counted by bytes.
 165  *
 166  * Return number of characters in an IBusText.
 167  * This function is based on g_utf8_strlen(), so unlike strlen(),
 168  * it does not count by bytes but characters instead.
 169  */
 170 guint            ibus_text_get_length               (IBusText       *text);
 171
 172 /**
 173  * ibus_text_get_is_static: (skip)
 174  * @text: An IBusText.
 175  * @returns: the is_static in @text.
 176  *
 177  * Return the is_static in an IBusText.
 178  */
 179 gboolean         ibus_text_get_is_static            (IBusText       *text);
 180
 181 /**
 182  * ibus_text_get_text:
 183  * @text: An IBusText.
 184  * @returns: the text in @text.
 185  *
 186  * Return the text in an IBusText. Should not be freed.
 187  */
 188 const gchar *    ibus_text_get_text                 (IBusText       *text);
 189
 190 /**
 191  * ibus_text_get_attributes:
 192  * @text: An IBusText.
 193  * @returns: (transfer none): the attrs in @text.
 194  *
 195  * Return the attributes in an IBusText. Should not be freed.
 196  */
 197 IBusAttrList *   ibus_text_get_attributes           (IBusText       *text);
 198
 199 /**
 200  * ibus_text_set_attributes:
 201  * @text: An IBusText.
 202  * @attrs: An IBusAttrList
 203  */
 204 void             ibus_text_set_attributes           (IBusText       *text,
 205                                                      IBusAttrList   *attrs);
 206
 207
 208 G_END_DECLS
 209 #endif
 210