src/ibusproperty.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 #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  */
  48 G_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  */
  78 typedef 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  */
 108 typedef enum {
 109     PROP_STATE_UNCHECKED = 0,
 110     PROP_STATE_CHECKED = 1,
 111     PROP_STATE_INCONSISTENT = 2,
 112 } IBusPropState;
 113
 114
 115 typedef struct _IBusProperty IBusProperty;
 116 typedef struct _IBusPropertyClass IBusPropertyClass;
 117 typedef struct _IBusPropertyPrivate IBusPropertyPrivate;
 118
 119 #ifndef __PROPLIST_DEFINED
 120 #define __PROPLIST_DEFINED
 121 typedef struct _IBusPropList IBusPropList;
 122 typedef struct _IBusPropListClass IBusPropListClass;
 123 #endif
 124
 125 /**
 126  * IBusProperty:
 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.
 138  *
 139  * UI component for input method engine property.
 140  */
 141 struct _IBusProperty {
 142     /*< private >*/
 143     IBusSerializable parent;
 144     IBusPropertyPrivate *priv;
 145
 146     gpointer pdummy[7];
 147 };
 148
 149 struct _IBusPropertyClass {
 150     IBusSerializableClass parent;
 151 };
 152
 153 GType            ibus_property_get_type     ();
 154
 155 /**
 156  * ibus_property_new:
 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.
 167  *
 168  * New a #IBusProperty.
 169  */
 170 IBusProperty    *ibus_property_new          (const gchar    *key,
 171                                              IBusPropType    type,
 172                                              IBusText       *label,
 173                                              const gchar    *icon,
 174                                              IBusText       *tooltip,
 175                                              gboolean        sensitive,
 176                                              gboolean        visible,
 177                                              IBusPropState   state,
 178                                              IBusPropList   *prop_list);
 179
 180 /**
 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.
 184  *
 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)
 189  */
 190 IBusProperty    *ibus_property_new_varargs  (const gchar    *first_property_name,
 191                                                              ...);
 192
 193 /**
 194  * ibus_property_get_key:
 195  * @prop: An #IBusProperty.
 196  * @returns: the key of #IBusProperty. Should not be freed.
 197  *
 198  * Get the key of #IBusProperty.
 199  */
 200 const gchar *    ibus_property_get_key      (IBusProperty   *prop);
 201
 202 /**
 203  * ibus_property_get_label:
 204  * @prop: An #IBusProperty.
 205  * @returns: (transfer none): the label of #IBusProperty. Should not be freed.
 206  *
 207  * Get the label of #IBusProperty.
 208  */
 209 IBusText *       ibus_property_get_label    (IBusProperty   *prop);
 210
 211 /**
 212  * ibus_property_set_label:
 213  * @prop: An #IBusProperty.
 214  * @label: Text shown in UI.
 215  *
 216  * Set the label of #IBusProperty.
 217  */
 218 void             ibus_property_set_label    (IBusProperty   *prop,
 219                                              IBusText       *label);
 220
 221 /**
 222  * ibus_property_get_symbol:
 223  * @prop: An #IBusProperty.
 224  * @returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
 225  *
 226  * Get the symbol of #IBusProperty.
 227  */
 228 IBusText *       ibus_property_get_symbol   (IBusProperty   *prop);
 229
 230 /**
 231  * ibus_property_set_symbol:
 232  * @prop: An #IBusProperty.
 233  * @symbol: Text shown in UI.
 234  *
 235  * Set the symbol of #IBusProperty.
 236  */
 237 void             ibus_property_set_symbol   (IBusProperty   *prop,
 238                                              IBusText       *symbol);
 239
 240 /**
 241  * ibus_property_get_icon:
 242  * @prop: An #IBusProperty.
 243  * @returns: the icon of #IBusProperty. Should not be freed.
 244  *
 245  * Get the icon of #IBusProperty.
 246  */
 247 const gchar *    ibus_property_get_icon     (IBusProperty   *prop);
 248
 249 /**
 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.
 253  *
 254  * Set the icon of #IBusProperty.
 255  */
 256 void             ibus_property_set_icon     (IBusProperty   *prop,
 257                                              const gchar    *icon);
 258
 259 /**
 260  * ibus_property_get_tooltip:
 261  * @prop: An #IBusProperty.
 262  * @returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
 263  *
 264  * Get the tooltip of #IBusProperty.
 265  */
 266 IBusText *       ibus_property_get_tooltip  (IBusProperty   *prop);
 267
 268 /**
 269  * ibus_property_set_tooltip:
 270  * @prop: An #IBusProperty.
 271  * @tooltip: Text of the tooltip.
 272  *
 273  * Set the tooltip of #IBusProperty.
 274  */
 275 void             ibus_property_set_tooltip  (IBusProperty   *prop,
 276                                              IBusText       *tooltip);
 277
 278 /**
 279  * ibus_property_get_sensitive:
 280  * @prop: An #IBusProperty.
 281  * @returns: the sensitive of #IBusProperty.
 282  *
 283  * Get the sensitive of #IBusProperty.
 284  */
 285 gboolean         ibus_property_get_sensitive(IBusProperty   *prop);
 286
 287 /**
 288  * ibus_property_set_sensitive:
 289  * @prop: An #IBusProperty.
 290  * @sensitive: Whether the #IBusProperty is sensitive.
 291  *
 292  * Set whether the #IBusProperty is sensitive.
 293  */
 294 void             ibus_property_set_sensitive(IBusProperty   *prop,
 295                                              gboolean        sensitive);
 296
 297 /**
 298  * ibus_property_get_visible:
 299  * @prop: An #IBusProperty.
 300  * @returns: the visible of #IBusProperty.
 301  *
 302  * Get the visible of #IBusProperty.
 303  */
 304 gboolean         ibus_property_get_visible  (IBusProperty   *prop);
 305
 306 /**
 307  * ibus_property_set_visible:
 308  * @prop: An #IBusProperty.
 309  * @visible: Whether the #IBusProperty is visible.
 310  *
 311  * Set whether the #IBusProperty is visible.
 312  */
 313 void             ibus_property_set_visible  (IBusProperty   *prop,
 314                                              gboolean        visible);
 315
 316 /**
 317  * ibus_property_get_property_type:
 318  * @prop: An #IBusProperty.
 319  * @returns: the type of #IBusProperty.
 320  *
 321  * Get the type of #IBusProperty.
 322  */
 323 IBusPropType     ibus_property_get_prop_type(IBusProperty   *prop);
 324
 325 /**
 326  * ibus_property_get_state:
 327  * @prop: An #IBusProperty.
 328  * @returns: the state of #IBusProperty.
 329  *
 330  * Get the state of #IBusProperty.
 331  */
 332 IBusPropState    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  */
 341 void             ibus_property_set_state    (IBusProperty   *prop,
 342                                              IBusPropState   state);
 343
 344 /**
 345  * ibus_property_get_sub_props:
 346  * @prop: An #IBusProperty.
 347  * @returns: (transfer none): the IBusPropList of #IBusProperty.
 348  *     Should not be freed.
 349  *
 350  * Get the IBusPropList of #IBusProperty.
 351  */
 352 IBusPropList *   ibus_property_get_sub_props(IBusProperty   *prop);
 353
 354 /**
 355  * ibus_property_set_sub_props:
 356  * @prop: An #IBusProperty.
 357  * @prop_list: #IBusPropList that contains sub IBusProperties.
 358  *
 359  * Set the sub IBusProperties.
 360  */
 361 void             ibus_property_set_sub_props(IBusProperty   *prop,
 362                                              IBusPropList   *prop_list);
 363
 364 /**
 365  * ibus_property_update:
 366  * @prop: An #IBusProperty.
 367  * @prop_update: #IBusPropList that contains sub IBusProperties.
 368  * @returns: TRUE for update suceeded; FALSE otherwise.
 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
 375 gboolean         ibus_property_update       (IBusProperty   *prop,
 376                                              IBusProperty   *prop_update);
 377
 378 G_END_DECLS
 379 #endif