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-2013 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2008-2013 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#ifndef __IBUS_TEXT_H_
28#define __IBUS_TEXT_H_
29
30/**
31 * SECTION: ibustext
32 * @short_description: Text with decorating information.
33 *
34 * An IBusText is the main text object in IBus.
35 * The text is decorated according to associated IBusAttribute,
36 * e.g. the foreground/background color, underline, and
37 * applied scope.
38 *
39 * see_also: #IBusAttribute
40 */
41
42#include "ibusserializable.h"
43#include "ibusattrlist.h"
44
45/*
46 * Type macros.
47 */
48/* define IBusText macros */
49#define IBUS_TYPE_TEXT \
50 (ibus_text_get_type ())
51#define IBUS_TEXT(obj) \
52 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_TEXT, IBusText))
53#define IBUS_TEXT_CLASS(klass) \
54 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_TEXT, IBusTextClass))
55#define IBUS_IS_TEXT(obj) \
56 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_TEXT))
57#define IBUS_IS_TEXT_CLASS(klass) \
58 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_TEXT))
59#define IBUS_TEXT_GET_CLASS(obj) \
60 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_TEXT, IBusTextClass))
61
62G_BEGIN_DECLS
63
64typedef struct _IBusText IBusText;
65typedef struct _IBusTextClass IBusTextClass;
66
67/**
68 * IBusText:
69 * @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().
70 * @text: The string content of IBusText in UTF-8.
71 * @attrs: Associated IBusAttributes.
72 *
73 * A text object in IBus.
74 */
75struct _IBusText {
76 IBusSerializable parent;
77
78 /* members */
79 /*< public >*/
80 gboolean is_static;
81 gchar *text;
82 IBusAttrList *attrs;
83};
84
85struct _IBusTextClass {
86 IBusSerializableClass parent;
87};
88
89GType ibus_text_get_type (void);
90
91/**
92 * ibus_text_new_from_string:
93 * @str: An text string to be set.
94 *
95 * Creates a new #IBusText from a string.
96 * @str will be duplicated in #IBusText, so feel free to free @str after this
97 * function.
98 *
99 * Returns: A newly allocated #IBusText.
100 */
101IBusText *ibus_text_new_from_string (const gchar *str);
102
103/**
104 * ibus_text_new_from_ucs4:
105 * @str: An text string to be set.
106 *
107 * Creates a new #IBusText from an UCS-4 encoded string.
108 * @str will be duplicated in IBusText, so feel free to free @str after this
109 * function.
110 *
111 * Returns: A newly allocated #IBusText.
112 */
113IBusText *ibus_text_new_from_ucs4 (const gunichar *str);
114
115/**
116 * ibus_text_new_from_static_string: (skip)
117 * @str: An text string to be set.
118 *
119 * Creates a new #IBusText from a static string.
120 *
121 * Since @str is a static string which won't be freed.
122 * This function will NOT duplicate @str.
123 *
124 * Returns: A newly allocated #IBusText.
125 */
126IBusText *ibus_text_new_from_static_string (const gchar *str);
127
128/**
129 * ibus_text_new_from_printf:
130 * @fmt: printf format string.
131 * @...: arguments for @fmt.
132 *
133 * Creates a new #IBusText from a printf expression.
134 *
135 * The result of printf expression is stored in the new IBusText instance.
136 *
137 * Returns: A newly allocated #IBusText.
138 */
139IBusText *ibus_text_new_from_printf (const gchar *fmt,
140 ...) G_GNUC_PRINTF (1, 2);
141
142/**
143 * ibus_text_new_from_unichar:
144 * @c: A single UCS4-encoded character.
145 *
146 * Creates a new #IBusText from a single UCS4-encoded character.
147 *
148 * Returns: A newly allocated #IBusText.
149 */
150IBusText *ibus_text_new_from_unichar (gunichar c);
151
152/**
153 * ibus_text_append_attribute:
154 * @text: an IBusText
155 * @type: IBusAttributeType for @text.
156 * @value: Value for the type.
157 * @start_index: The starting index, inclusive.
158 * @end_index: The ending index, exclusive.
159 *
160 * Append an IBusAttribute for IBusText.
161 */
162void ibus_text_append_attribute (IBusText *text,
163 guint type,
164 guint value,
165 guint start_index,
166 gint end_index);
167/**
168 * ibus_text_get_length:
169 * @text: An #IBusText.
170 *
171 * Return number of characters in an #IBusText.
172 * This function is based on g_utf8_strlen(), so unlike strlen(),
173 * it does not count by bytes but characters instead.
174 *
175 * Returns: Number of character in @text, not counted by bytes.
176 */
177guint ibus_text_get_length (IBusText *text);
178
179/**
180 * ibus_text_get_is_static: (skip)
181 * @text: An #IBusText.
182 *
183 * Return the is_static in an #IBusText.
184 *
185 * Returns: the is_static in @text.
186 */
187gboolean ibus_text_get_is_static (IBusText *text);
188
189/**
190 * ibus_text_get_text:
191 * @text: An #IBusText.
192 *
193 * Return the text in an #IBusText. Should not be freed.
194 *
195 * Returns: the text in @text.
196 */
197const gchar * ibus_text_get_text (IBusText *text);
198
199/**
200 * ibus_text_get_attributes:
201 * @text: An #IBusText.
202 *
203 * Return the attributes in an #IBusText. Should not be freed.
204 *
205 * Returns: (transfer none): the attrs in @text.
206 */
207IBusAttrList * ibus_text_get_attributes (IBusText *text);
208
209/**
210 * ibus_text_set_attributes:
211 * @text: An IBusText.
212 * @attrs: An IBusAttrList
213 */
214void ibus_text_set_attributes (IBusText *text,
215 IBusAttrList *attrs);
216
217
218G_END_DECLS
219#endif
220
221