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.
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 of the License, or (at your option) any later version.
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.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
24 #error "Only <ibus.h> can be included directly"
27 #ifndef __IBUS_PROPERTY_H_
28 #define __IBUS_PROPERTY_H_
30 #include "ibusserializable.h"
34 * SECTION: ibusproperty
35 * @short_description: UI component for input method engine property.
36 * @title: IBusProperty
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.
46 * see_also: #IBusPropList, #IBusEngine
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))
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
74 * @PROP_TYPE_SEPARATOR: A separator for menu.
76 * Type enumeration of IBusProperty.
83 PROP_TYPE_SEPARATOR = 4,
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
93 * State of #IBusProperty. The actual effect depends on #IBusPropType of the
98 * <term>PROP_TYPE_TOGGLE</term>
99 * <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
102 * <term>PROP_TYPE_RADIO</term>
103 * <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
106 * No effect on other types.
109 PROP_STATE_UNCHECKED = 0,
110 PROP_STATE_CHECKED = 1,
111 PROP_STATE_INCONSISTENT = 2,
115 typedef struct _IBusProperty IBusProperty;
116 typedef struct _IBusPropertyClass IBusPropertyClass;
117 typedef struct _IBusPropertyPrivate IBusPropertyPrivate;
119 #ifndef __PROPLIST_DEFINED
120 #define __PROPLIST_DEFINED
121 typedef struct _IBusPropList IBusPropList;
122 typedef struct _IBusPropListClass IBusPropListClass;
127 * key: Unique Identity for the IBusProperty.
128 * icon: Icon file for the IBusProperty.
129 * label: Text shown in UI.
130 * symbol: A symbol char showned on a button or status icon for IBusProperty.
131 * tooltip: Message shown if mouse hovered the IBusProperty.
132 * sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event.
133 * visible: Whether the IBusProperty is visible.
134 * type: IBusPropType of IBusProperty.
135 * state: IBusPropState of IBusProperty.
136 * sub_props: IBusPropList that contains sub IBusProperties. These IBusProperties are usually
137 * shown as sub menu item.
139 * UI component for input method engine property.
141 struct _IBusProperty {
143 IBusSerializable parent;
144 IBusPropertyPrivate *priv;
149 struct _IBusPropertyClass {
150 IBusSerializableClass parent;
153 GType ibus_property_get_type ();
157 * @key: Unique Identity for the #IBusProperty.
158 * @type: #IBusPropType of #IBusProperty.
159 * @label: Text shown in UI.
160 * @icon: (allow-none): Icon file for the #IBusProperty.
161 * @tooltip: Message shown if mouse hovered the #IBusProperty.
162 * @sensitive: Whether the #IBusProperty is sensitive to keyboard and mouse event.
163 * @visible: Whether the #IBusProperty is visible.
164 * @state: IBusPropState of #IBusProperty.
165 * @prop_list: (allow-none): #IBusPropList that contains sub IBusProperties.
166 * @returns: A newly allocated #IBusProperty.
168 * New a #IBusProperty.
170 IBusProperty *ibus_property_new (const gchar *key,
178 IBusPropList *prop_list);
181 * ibus_property_new_varargs:
182 * @first_property_name: Name of the first property.
183 * @Varargs: the NULL-terminated arguments of the properties and values.
185 * New a #IBusProperty.
186 * ibus_property_new_varargs() supports the va_list format.
187 * name property is required. e.g.
188 * ibus_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)
190 IBusProperty *ibus_property_new_varargs (const gchar *first_property_name,
194 * ibus_property_get_key:
195 * @prop: An #IBusProperty.
196 * @returns: the key of #IBusProperty. Should not be freed.
198 * Get the key of #IBusProperty.
200 const gchar * ibus_property_get_key (IBusProperty *prop);
203 * ibus_property_get_label:
204 * @prop: An #IBusProperty.
205 * @returns: (transfer none): the label of #IBusProperty. Should not be freed.
207 * Get the label of #IBusProperty.
209 IBusText * ibus_property_get_label (IBusProperty *prop);
212 * ibus_property_set_label:
213 * @prop: An #IBusProperty.
214 * @label: Text shown in UI.
216 * Set the label of #IBusProperty.
218 void ibus_property_set_label (IBusProperty *prop,
222 * ibus_property_get_symbol:
223 * @prop: An #IBusProperty.
224 * @returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
226 * Get the symbol of #IBusProperty.
228 IBusText * ibus_property_get_symbol (IBusProperty *prop);
231 * ibus_property_set_symbol:
232 * @prop: An #IBusProperty.
233 * @symbol: Text shown in UI.
235 * Set the symbol of #IBusProperty.
237 void ibus_property_set_symbol (IBusProperty *prop,
241 * ibus_property_get_icon:
242 * @prop: An #IBusProperty.
243 * @returns: the icon of #IBusProperty. Should not be freed.
245 * Get the icon of #IBusProperty.
247 const gchar * ibus_property_get_icon (IBusProperty *prop);
250 * ibus_property_set_icon:
251 * @prop: An #IBusProperty.
252 * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name.
254 * Set the icon of #IBusProperty.
256 void ibus_property_set_icon (IBusProperty *prop,
260 * ibus_property_get_tooltip:
261 * @prop: An #IBusProperty.
262 * @returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
264 * Get the tooltip of #IBusProperty.
266 IBusText * ibus_property_get_tooltip (IBusProperty *prop);
269 * ibus_property_set_tooltip:
270 * @prop: An #IBusProperty.
271 * @tooltip: Text of the tooltip.
273 * Set the tooltip of #IBusProperty.
275 void ibus_property_set_tooltip (IBusProperty *prop,
279 * ibus_property_get_sensitive:
280 * @prop: An #IBusProperty.
281 * @returns: the sensitive of #IBusProperty.
283 * Get the sensitive of #IBusProperty.
285 gboolean ibus_property_get_sensitive(IBusProperty *prop);
288 * ibus_property_set_sensitive:
289 * @prop: An #IBusProperty.
290 * @sensitive: Whether the #IBusProperty is sensitive.
292 * Set whether the #IBusProperty is sensitive.
294 void ibus_property_set_sensitive(IBusProperty *prop,
298 * ibus_property_get_visible:
299 * @prop: An #IBusProperty.
300 * @returns: the visible of #IBusProperty.
302 * Get the visible of #IBusProperty.
304 gboolean ibus_property_get_visible (IBusProperty *prop);
307 * ibus_property_set_visible:
308 * @prop: An #IBusProperty.
309 * @visible: Whether the #IBusProperty is visible.
311 * Set whether the #IBusProperty is visible.
313 void ibus_property_set_visible (IBusProperty *prop,
317 * ibus_property_get_property_type:
318 * @prop: An #IBusProperty.
319 * @returns: the type of #IBusProperty.
321 * Get the type of #IBusProperty.
323 IBusPropType ibus_property_get_prop_type(IBusProperty *prop);
326 * ibus_property_get_state:
327 * @prop: An #IBusProperty.
328 * @returns: the state of #IBusProperty.
330 * Get the state of #IBusProperty.
332 IBusPropState ibus_property_get_state (IBusProperty *prop);
335 * ibus_property_set_state:
336 * @prop: An #IBusProperty.
337 * @state: The state of the #IBusProperty.
339 * Set the state of the #IBusProperty.
341 void ibus_property_set_state (IBusProperty *prop,
342 IBusPropState state);
345 * ibus_property_get_sub_props:
346 * @prop: An #IBusProperty.
347 * @returns: (transfer none): the IBusPropList of #IBusProperty.
348 * Should not be freed.
350 * Get the IBusPropList of #IBusProperty.
352 IBusPropList * ibus_property_get_sub_props(IBusProperty *prop);
355 * ibus_property_set_sub_props:
356 * @prop: An #IBusProperty.
357 * @prop_list: #IBusPropList that contains sub IBusProperties.
359 * Set the sub IBusProperties.
361 void ibus_property_set_sub_props(IBusProperty *prop,
362 IBusPropList *prop_list);
365 * ibus_property_update:
366 * @prop: An #IBusProperty.
367 * @prop_update: #IBusPropList that contains sub IBusProperties.
368 * @returns: TRUE for update suceeded; FALSE otherwise.
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.
375 gboolean ibus_property_update (IBusProperty *prop,
376 IBusProperty *prop_update);