src/ibusproperty.h

   1 /* vim:set et sts=4: */
   2 /* IBus - The Input Bus
   3  * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
   4  * Copyright (C) 2008-2010 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21 /**
  22  * SECTION: ibusproperty
  23  * @short_description: UI component for input method engine property.
  24  * @stability: Stable
  25  * @see_also: #IBusEngine
  26  *
  27  * An IBusProperty is an UI component like a button or a menu item
  28  * which shows the status of corresponding input method engine property.
  29  * End user can operate and see the current status of IME through these components.
  30  * For example, ibus-chewing users change the English/Chinese input mode by
  31  * pressing ctrl-space or click on the Eng/Chi switch button.
  32  * And the IBusProperty shows the change correspondingly.
  33  */
  34 #ifndef __IBUS_PROPERTY_H_
  35 #define __IBUS_PROPERTY_H_
  36
  37 #include "ibusserializable.h"
  38 #include "ibustext.h"
  39
  40 G_BEGIN_DECLS
  41
  42 /*
  43  * Type macros.
  44  */
  45 /* define IBusProperty macros */
  46 #define IBUS_TYPE_PROPERTY             \
  47     (ibus_property_get_type ())
  48 #define IBUS_PROPERTY(obj)             \
  49     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_PROPERTY, IBusProperty))
  50 #define IBUS_PROPERTY_CLASS(klass)     \
  51     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_PROPERTY, IBusPropertyClass))
  52 #define IBUS_IS_PROPERTY(obj)          \
  53     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_PROPERTY))
  54 #define IBUS_IS_PROPERTY_CLASS(klass)  \
  55     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_PROPERTY))
  56 #define IBUS_PROPERTY_GET_CLASS(obj)   \
  57     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROPERTY, IBusPropertyClass))
  58
  59 /**
  60  * IBusPropType:
  61  * @PROP_TYPE_NORMAL: Property is shown as normal text.
  62  * @PROP_TYPE_TOGGLE: Property is shown as a toggle button.
  63  * @PROP_TYPE_RADIO: Property is shown as a radio selection option.
  64  * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu
  65  * items.
  66  * @PROP_TYPE_SEPARATOR: A separator for menu.
  67  *
  68  * Type enumeration of IBusProperty.
  69  */
  70 typedef enum {
  71     PROP_TYPE_NORMAL = 0,
  72     PROP_TYPE_TOGGLE = 1,
  73     PROP_TYPE_RADIO = 2,
  74     PROP_TYPE_MENU = 3,
  75     PROP_TYPE_SEPARATOR = 4,
  76 } IBusPropType;
  77
  78 /**
  79  * IBusPropState:
  80  * @PROP_STATE_UNCHECKED: Property option is unchecked.
  81  * @PROP_STATE_CHECKED: Property option is checked.
  82  * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME
  83  * property.
  84  *
  85  * State of IBusProperty. The actual effect depends on #IBusPropType of the
  86  * IBusProperty.
  87  *
  88  * <variablelist>
  89  *     <varlistentry>
  90  *         <term>PROP_TYPE_TOGGLE</term>
  91  *         <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
  92  *     </varlistentry>
  93  *     <varlistentry>
  94  *         <term>PROP_TYPE_RADIO</term>
  95  *         <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
  96  *     </varlistentry>
  97  * </variablelist>
  98  * No effect on other types.
  99  */
 100 typedef enum {
 101     PROP_STATE_UNCHECKED = 0,
 102     PROP_STATE_CHECKED = 1,
 103     PROP_STATE_INCONSISTENT = 2,
 104 } IBusPropState;
 105
 106
 107 typedef struct _IBusProperty IBusProperty;
 108 typedef struct _IBusPropertyClass IBusPropertyClass;
 109
 110 #ifndef __PROPLIST_DEFINED
 111 #define __PROPLIST_DEFINED
 112 typedef struct _IBusPropList IBusPropList;
 113 typedef struct _IBusPropListClass IBusPropListClass;
 114 #endif
 115
 116 /**
 117  * IBusProperty:
 118  * @key: Unique Identity for the IBusProperty.
 119  * @icon: Icon file for the IBusProperty.
 120  * @label: Text shown in UI.
 121  * @tooltip: Message shown if mouse hovered the  IBusProperty.
 122  * @sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event.
 123  * @visible: Whether the IBusProperty is visible.
 124  * @type: IBusPropType of IBusProperty.
 125  * @state: IBusPropState of IBusProperty.
 126  * @sub_props: IBusPropList that contains sub IBusProperties. These IBusProperties are usually
 127  * shown as sub menu item.
 128  *
 129  * UI component for input method engine property.
 130  */
 131 struct _IBusProperty {
 132     IBusSerializable parent;
 133
 134     /*< public >*/
 135     gchar    *key;
 136     gchar    *icon;
 137     IBusText *label;
 138     IBusText *tooltip;
 139
 140     gboolean sensitive;
 141     gboolean visible;
 142     guint type;
 143     guint state;
 144
 145     IBusPropList *sub_props;
 146 };
 147
 148 struct _IBusPropertyClass {
 149     IBusSerializableClass parent;
 150 };
 151
 152 GType            ibus_property_get_type     ();
 153
 154 /**
 155  * ibus_property_new:
 156  * @key: Unique Identity for the IBusProperty.
 157  * @type: IBusPropType of IBusProperty.
 158  * @label: Text shown in UI.
 159  * @icon: Icon file for the IBusProperty.
 160  * @tooltip: Message shown if mouse hovered the  IBusProperty.
 161  * @sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event.
 162  * @visible: Whether the IBusProperty is visible.
 163  * @state: IBusPropState of IBusProperty.
 164  * @prop_list: IBusPropList that contains sub IBusProperties.
 165  * @returns: A newly allocated IBusProperty.
 166  *
 167  * New a IBusProperty.
 168  */
 169 IBusProperty    *ibus_property_new          (const gchar    *key,
 170                                              IBusPropType    type,
 171                                              IBusText       *label,
 172                                              const gchar    *icon,
 173                                              IBusText       *tooltip,
 174                                              gboolean        sensitive,
 175                                              gboolean        visible,
 176                                              IBusPropState   state,
 177                                              IBusPropList   *prop_list);
 178
 179 /**
 180  * ibus_property_set_label:
 181  * @prop: An IBusProperty.
 182  * @label: Text shown in UI.
 183  *
 184  * Set the label of IBusProperty.
 185  */
 186 void             ibus_property_set_label    (IBusProperty   *prop,
 187                                              IBusText       *label);
 188
 189 /**
 190  * ibus_property_set_icon:
 191  * @prop: An IBusProperty.
 192  * @icon: Icon shown in UI. It could be a full path of an icon file or an icon name.
 193  *
 194  * Set the icon of IBusProperty.
 195  */
 196 void             ibus_property_set_icon     (IBusProperty   *prop,
 197                                              const gchar    *icon);
 198
 199 /**
 200  * ibus_property_set_tooltip:
 201  * @prop: An IBusProperty.
 202  * @tooltip: Text of the tooltip.
 203  *
 204  * Set the tooltip of IBusProperty.
 205  */
 206 void             ibus_property_set_tooltip  (IBusProperty   *prop,
 207                                              IBusText       *tooltip);
 208
 209 /**
 210  * ibus_property_set_sensitive:
 211  * @prop: An IBusProperty.
 212  * @sensitive: Whether the IBusProperty is sensitive.
 213  *
 214  * Set whether the IBusProperty is sensitive.
 215  */
 216 void             ibus_property_set_sensitive(IBusProperty   *prop,
 217                                              gboolean        sensitive);
 218
 219 /**
 220  * ibus_property_set_visible:
 221  * @prop: An IBusProperty.
 222  * @visible: Whether the IBusProperty is visible.
 223  *
 224  * Set whether the IBusProperty is visible.
 225  */
 226 void             ibus_property_set_visible  (IBusProperty   *prop,
 227                                              gboolean        visible);
 228
 229 /**
 230  * ibus_property_set_state:
 231  * @prop: An IBusProperty.
 232  * @state: The state of the IBusProperty.
 233  *
 234  * Set the state of the IBusProperty.
 235  */
 236 void             ibus_property_set_state    (IBusProperty   *prop,
 237                                              IBusPropState   state);
 238
 239
 240 /**
 241  * ibus_property_set_sub_props:
 242  * @prop: An IBusProperty.
 243  * @prop_list: IBusPropList that contains sub IBusProperties.
 244  *
 245  * Set the sub IBusProperties.
 246  */
 247 void             ibus_property_set_sub_props(IBusProperty   *prop,
 248                                              IBusPropList   *prop_list);
 249
 250 /**
 251  * ibus_property_update:
 252  * @prop: An IBusProperty.
 253  * @prop_update: IBusPropList that contains sub IBusProperties.
 254  * @returns: TRUE for update suceeded; FALSE otherwise.
 255  *
 256  * Update the content of an IBusProperty.
 257  * IBusProperty @prop_update can either be sub-property of @prop,
 258  * or holds new values for @prop.
 259  */
 260
 261 gboolean         ibus_property_update       (IBusProperty   *prop,
 262                                              IBusProperty   *prop_update);
 263
 264 G_END_DECLS
 265 #endif