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#ifndef __IBUS_PROPERTY_H_
28#define __IBUS_PROPERTY_H_
29
30#include "ibusserializable.h"
31#include "ibustext.h"
32
33/**
34 * SECTION: ibusproperty
35 * @short_description: UI component for input method engine property.
36 * @title: IBusProperty
37 * @stability: Stable
38 *
39 * An IBusProperty is an UI component like a button or a menu item
40 * which shows the status of corresponding input method engine property.
41 * End user can operate and see the current status of IME through these components.
42 * For example, ibus-chewing users change the English/Chinese input mode by
43 * pressing ctrl-space or click on the Eng/Chi switch button.
44 * And the IBusProperty shows the change correspondingly.
45 *
46 * see_also: #IBusPropList, #IBusEngine
47 */
48G_BEGIN_DECLS
49
50/*
51 * Type macros.
52 */
53/* define IBusProperty macros */
54#define IBUS_TYPE_PROPERTY \
55 (ibus_property_get_type ())
56#define IBUS_PROPERTY(obj) \
57 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROPERTY, IBusProperty))
58#define IBUS_PROPERTY_CLASS(klass) \
59 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROPERTY, IBusPropertyClass))
60#define IBUS_IS_PROPERTY(obj) \
61 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROPERTY))
62#define IBUS_IS_PROPERTY_CLASS(klass) \
63 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROPERTY))
64#define IBUS_PROPERTY_GET_CLASS(obj) \
65 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROPERTY, IBusPropertyClass))
66
67/**
68 * IBusPropType:
69 * @PROP_TYPE_NORMAL: Property is shown as normal text.
70 * @PROP_TYPE_TOGGLE: Property is shown as a toggle button.
71 * @PROP_TYPE_RADIO: Property is shown as a radio selection option.
72 * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu
73 * items.
74 * @PROP_TYPE_SEPARATOR: A separator for menu.
75 *
76 * Type enumeration of IBusProperty.
77 */
78typedef enum {
79 PROP_TYPE_NORMAL = 0,
80 PROP_TYPE_TOGGLE = 1,
81 PROP_TYPE_RADIO = 2,
82 PROP_TYPE_MENU = 3,
83 PROP_TYPE_SEPARATOR = 4,
84} IBusPropType;
85
86/**
87 * IBusPropState:
88 * @PROP_STATE_UNCHECKED: Property option is unchecked.
89 * @PROP_STATE_CHECKED: Property option is checked.
90 * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME
91 * property.
92 *
93 * State of #IBusProperty. The actual effect depends on #IBusPropType of the
94 * IBusProperty.
95 *
96 * <variablelist>
97 * <varlistentry>
98 * <term>PROP_TYPE_TOGGLE</term>
99 * <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
100 * </varlistentry>
101 * <varlistentry>
102 * <term>PROP_TYPE_RADIO</term>
103 * <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
104 * </varlistentry>
105 * </variablelist>
106 * No effect on other types.
107 */
108typedef enum {
109 PROP_STATE_UNCHECKED = 0,
110 PROP_STATE_CHECKED = 1,
111 PROP_STATE_INCONSISTENT = 2,
112} IBusPropState;
113
114
115typedef struct _IBusProperty IBusProperty;
116typedef struct _IBusPropertyClass IBusPropertyClass;
117typedef struct _IBusPropertyPrivate IBusPropertyPrivate;
118
119#ifndef __PROPLIST_DEFINED
120#define __PROPLIST_DEFINED
121typedef struct _IBusPropList IBusPropList;
122typedef struct _IBusPropListClass IBusPropListClass;
123#endif
124
125/**
126 * IBusProperty:
127 * UI component for input method engine property.
128 */
129struct _IBusProperty {
130 /*< private >*/
131 IBusSerializable parent;
132 IBusPropertyPrivate *priv;
133
134 gpointer pdummy[7];
135};
136
137struct _IBusPropertyClass {
138 IBusSerializableClass parent;
139};
140
141GType ibus_property_get_type ();
142
143/**
144 * ibus_property_new:
145 * @key: Unique Identity for the #IBusProperty.
146 * @type: #IBusPropType of #IBusProperty.
147 * @label: Text shown in UI.
148 * @icon: (allow-none): Icon file for the #IBusProperty.
149 * @tooltip: Message shown if mouse hovered the #IBusProperty.
150 * @sensitive: Whether the #IBusProperty is sensitive to keyboard and mouse event.
151 * @visible: Whether the #IBusProperty is visible.
152 * @state: IBusPropState of #IBusProperty.
153 * @prop_list: (allow-none): #IBusPropList that contains sub IBusProperties.
154 *
155 * Creates a new #IBusProperty.
156 *
157 * Returns: A newly allocated #IBusProperty.
158 */
159IBusProperty *ibus_property_new (const gchar *key,
160 IBusPropType type,
161 IBusText *label,
162 const gchar *icon,
163 IBusText *tooltip,
164 gboolean sensitive,
165 gboolean visible,
166 IBusPropState state,
167 IBusPropList *prop_list);
168
169/**
170 * ibus_property_new_varargs:
171 * @first_property_name: Name of the first property.
172 * @...: the NULL-terminated arguments of the properties and values.
173 *
174 * Creates a new #IBusProperty.
175 * ibus_property_new_varargs() supports the va_list format.
176 * name property is required. e.g.
177 * ibus_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)
178 *
179 * Returns: A newly allocated #IBusProperty.
180 */
181IBusProperty *ibus_property_new_varargs (const gchar *first_property_name,
182 ...);
183
184/**
185 * ibus_property_get_key:
186 * @prop: An #IBusProperty.
187 *
188 * Get the key of #IBusProperty.
189 *
190 * Returns: the key of #IBusProperty. Should not be freed.
191 */
192const gchar * ibus_property_get_key (IBusProperty *prop);
193
194/**
195 * ibus_property_get_label:
196 * @prop: An #IBusProperty.
197 *
198 * Get the label of #IBusProperty.
199 *
200 * Returns: (transfer none): the label of #IBusProperty. Should not be freed.
201 */
202IBusText * ibus_property_get_label (IBusProperty *prop);
203
204/**
205 * ibus_property_set_label:
206 * @prop: An #IBusProperty.
207 * @label: Text shown in UI.
208 *
209 * Set the label of #IBusProperty.
210 */
211void ibus_property_set_label (IBusProperty *prop,
212 IBusText *label);
213
214/**
215 * ibus_property_get_symbol:
216 * @prop: An #IBusProperty.
217 *
218 * Get the symbol of #IBusProperty.
219 *
220 * Returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
221 */
222IBusText * ibus_property_get_symbol (IBusProperty *prop);
223
224/**
225 * ibus_property_set_symbol:
226 * @prop: An #IBusProperty.
227 * @symbol: Text shown in UI.
228 *
229 * Set the symbol of #IBusProperty.
230 */
231void ibus_property_set_symbol (IBusProperty *prop,
232 IBusText *symbol);
233
234/**
235 * ibus_property_get_icon:
236 * @prop: An #IBusProperty.
237 *
238 * Get the icon of #IBusProperty.
239 *
240 * Returns: the icon of #IBusProperty. Should not be freed.
241 */
242const gchar * ibus_property_get_icon (IBusProperty *prop);
243
244/**
245 * ibus_property_set_icon:
246 * @prop: An #IBusProperty.
247 * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name.
248 *
249 * Set the icon of #IBusProperty.
250 */
251void ibus_property_set_icon (IBusProperty *prop,
252 const gchar *icon);
253
254/**
255 * ibus_property_get_tooltip:
256 * @prop: An #IBusProperty.
257 *
258 * Get the tooltip of #IBusProperty.
259 *
260 * Returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
261 */
262IBusText * ibus_property_get_tooltip (IBusProperty *prop);
263
264/**
265 * ibus_property_set_tooltip:
266 * @prop: An #IBusProperty.
267 * @tooltip: Text of the tooltip.
268 *
269 * Set the tooltip of #IBusProperty.
270 */
271void ibus_property_set_tooltip (IBusProperty *prop,
272 IBusText *tooltip);
273
274/**
275 * ibus_property_get_sensitive:
276 * @prop: An #IBusProperty.
277 *
278 * Get the sensitive of #IBusProperty.
279 *
280 * Returns: the sensitive of #IBusProperty.
281 */
282gboolean ibus_property_get_sensitive(IBusProperty *prop);
283
284/**
285 * ibus_property_set_sensitive:
286 * @prop: An #IBusProperty.
287 * @sensitive: Whether the #IBusProperty is sensitive.
288 *
289 * Set whether the #IBusProperty is sensitive.
290 */
291void ibus_property_set_sensitive(IBusProperty *prop,
292 gboolean sensitive);
293
294/**
295 * ibus_property_get_visible:
296 * @prop: An #IBusProperty.
297 *
298 * Get the visible of #IBusProperty.
299 *
300 * Returns: the visible of #IBusProperty.
301 */
302gboolean ibus_property_get_visible (IBusProperty *prop);
303
304/**
305 * ibus_property_set_visible:
306 * @prop: An #IBusProperty.
307 * @visible: Whether the #IBusProperty is visible.
308 *
309 * Set whether the #IBusProperty is visible.
310 */
311void ibus_property_set_visible (IBusProperty *prop,
312 gboolean visible);
313
314/**
315 * ibus_property_get_property_type:
316 * @prop: An #IBusProperty.
317 *
318 * Get the type of #IBusProperty.
319 *
320 * Returns: the type of #IBusProperty.
321 */
322IBusPropType ibus_property_get_prop_type(IBusProperty *prop);
323
324/**
325 * ibus_property_get_state:
326 * @prop: An #IBusProperty.
327 *
328 * Get the state of #IBusProperty.
329 *
330 * Returns: the state of #IBusProperty.
331 */
332IBusPropState ibus_property_get_state (IBusProperty *prop);
333
334/**
335 * ibus_property_set_state:
336 * @prop: An #IBusProperty.
337 * @state: The state of the #IBusProperty.
338 *
339 * Set the state of the #IBusProperty.
340 */
341void ibus_property_set_state (IBusProperty *prop,
342 IBusPropState state);
343
344/**
345 * ibus_property_get_sub_props:
346 * @prop: An #IBusProperty.
347 *
348 * Get the IBusPropList of #IBusProperty.
349 *
350 * Returns: (transfer none): the IBusPropList of #IBusProperty.
351 * Should not be freed.
352 */
353IBusPropList * ibus_property_get_sub_props(IBusProperty *prop);
354
355/**
356 * ibus_property_set_sub_props:
357 * @prop: An #IBusProperty.
358 * @prop_list: #IBusPropList that contains sub IBusProperties.
359 *
360 * Set the sub IBusProperties.
361 */
362void ibus_property_set_sub_props(IBusProperty *prop,
363 IBusPropList *prop_list);
364
365/**
366 * ibus_property_update:
367 * @prop: An #IBusProperty.
368 * @prop_update: #IBusPropList that contains sub IBusProperties.
369 *
370 * Update the content of an #IBusProperty.
371 * #IBusProperty @prop_update can either be sub-property of @prop,
372 * or holds new values for @prop.
373 *
374 * Returns: TRUE if update succeeded; FALSE otherwise.
375 */
376
377gboolean ibus_property_update (IBusProperty *prop,
378 IBusProperty *prop_update);
379
380G_END_DECLS
381#endif
382