IBusProperty

## IBusProperty IBusProperty — UI component for input method engine property. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    enum                IBusPropType;
    enum                IBusPropState;
                        IBusProperty;
                        IBusPropertyClass;
                        IBusPropList;
                        IBusPropListClass;
    IBusProperty *      ibus_property_new                   (const gchar *key,
                                                             IBusPropType type,
                                                             IBusText *label,
                                                             const gchar *icon,
                                                             IBusText *tooltip,
                                                             gboolean sensitive,
                                                             gboolean visible,
                                                             IBusPropState state,
                                                             IBusPropList *prop_list);
    void                ibus_property_set_label             (IBusProperty *prop,
                                                             IBusText *label);
    void                ibus_property_set_icon              (IBusProperty *prop,
                                                             const gchar *icon);
    void                ibus_property_set_tooltip           (IBusProperty *prop,
                                                             IBusText *tooltip);
    void                ibus_property_set_sensitive         (IBusProperty *prop,
                                                             gboolean sensitive);
    void                ibus_property_set_visible           (IBusProperty *prop,
                                                             gboolean visible);
    void                ibus_property_set_state             (IBusProperty *prop,
                                                             IBusPropState state);
    void                ibus_property_set_sub_props         (IBusProperty *prop,
                                                             IBusPropList *prop_list);
    gboolean            ibus_property_update                (IBusProperty *prop,
                                                             IBusProperty *prop_update);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusSerializable
                         +----IBusProperty

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusSerializable
                         +----IBusPropList

## Description

An IBusProperty is an UI component like a button or a menu item which shows the status of corresponding input method engine property. End user can operate and see the current status of IME through these components. For example, ibus-chewing users change the English/Chinese input mode by pressing ctrl-space or click on the Eng/Chi switch button. And the IBusProperty shows the change correspondingly.

`see_also`: IBusPropList, IBusEngine

## Details

### enum IBusPropType

    typedef enum {
        PROP_TYPE_NORMAL = 0,
        PROP_TYPE_TOGGLE = 1,
        PROP_TYPE_RADIO = 2,
        PROP_TYPE_MENU = 3,
        PROP_TYPE_SEPARATOR = 4,
    } IBusPropType;

Type enumeration of IBusProperty.

`PROP_TYPE_NORMAL` | Property is shown as normal text.
`PROP_TYPE_TOGGLE` | Property is shown as a toggle button.
`PROP_TYPE_RADIO` | Property is shown as a radio selection option.
`PROP_TYPE_MENU` | Property is shown as a menu, usually imply it has sub menu items.
`PROP_TYPE_SEPARATOR` | A separator for menu.

### enum IBusPropState

    typedef enum {
        PROP_STATE_UNCHECKED = 0,
        PROP_STATE_CHECKED = 1,
        PROP_STATE_INCONSISTENT = 2,
    } IBusPropState;

State of IBusProperty. The actual effect depends on IBusPropType of the IBusProperty.

PROP_TYPE_TOGGLE | Emphasized if PROP_STATE_CHECKED, normal otherwise.
PROP_TYPE_RADIO | Option checked if PROP_STATE_CHECKED, unchecked otherwise.

No effect on other types.

`PROP_STATE_UNCHECKED` | Property option is unchecked.
`PROP_STATE_CHECKED` | Property option is checked.
`PROP_STATE_INCONSISTENT` | The state is inconsistent with the associated IME property.

### IBusProperty

    typedef struct {
        gchar    *key;
        gchar    *icon;
        IBusText *label;
        IBusText *tooltip;

        gboolean sensitive;
        gboolean visible;
        guint type;
        guint state;

        IBusPropList *sub_props;
    } IBusProperty;

UI component for input method engine property.

gchar *`key`; | Unique Identity for the IBusProperty.
gchar *`icon`; | Icon file for the IBusProperty.
IBusText *`label`; | Text shown in UI.
IBusText *`tooltip`; | Message shown if mouse hovered the IBusProperty.
gboolean `sensitive`; | Whether the IBusProperty is sensitive to keyboard and mouse event.
gboolean `visible`; | Whether the IBusProperty is visible.
guint `type`; | IBusPropType of IBusProperty.
guint `state`; | IBusPropState of IBusProperty.
IBusPropList *`sub_props`; | IBusPropList that contains sub IBusProperties. These IBusProperties are usually shown as sub menu item.

### IBusPropertyClass

    typedef struct {
        IBusSerializableClass parent;
    } IBusPropertyClass;

### IBusPropList

    typedef struct {
        GArray *properties;
    } IBusPropList;

An array of IBusProperties.

### IBusPropListClass

    typedef struct {
        IBusSerializableClass parent;
    } IBusPropListClass;

### ibus_property_new ()

    IBusProperty *      ibus_property_new                   (const gchar *key,
                                                             IBusPropType type,
                                                             IBusText *label,
                                                             const gchar *icon,
                                                             IBusText *tooltip,
                                                             gboolean sensitive,
                                                             gboolean visible,
                                                             IBusPropState state,
                                                             IBusPropList *prop_list);

New a IBusProperty.

`key` : | Unique Identity for the IBusProperty.
`type` : | IBusPropType of IBusProperty.
`label` : | Text shown in UI.
`icon` : | Icon file for the IBusProperty.
`tooltip` : | Message shown if mouse hovered the IBusProperty.
`sensitive` : | Whether the IBusProperty is sensitive to keyboard and mouse event.
`visible` : | Whether the IBusProperty is visible.
`state` : | IBusPropState of IBusProperty.
`prop_list` : | IBusPropList that contains sub IBusProperties.
Returns : | A newly allocated IBusProperty.

### ibus_property_set_label ()

    void                ibus_property_set_label             (IBusProperty *prop,
                                                             IBusText *label);

Set the label of IBusProperty.

`prop` : | An IBusProperty.
`label` : | Text shown in UI.

### ibus_property_set_icon ()

    void                ibus_property_set_icon              (IBusProperty *prop,
                                                             const gchar *icon);

Set the icon of IBusProperty.

`prop` : | An IBusProperty.
`icon` : | Icon shown in UI. It could be a full path of an icon file or an icon name.

### ibus_property_set_tooltip ()

    void                ibus_property_set_tooltip           (IBusProperty *prop,
                                                             IBusText *tooltip);

Set the tooltip of IBusProperty.

`prop` : | An IBusProperty.
`tooltip` : | Text of the tooltip.

### ibus_property_set_sensitive ()

    void                ibus_property_set_sensitive         (IBusProperty *prop,
                                                             gboolean sensitive);

Set whether the IBusProperty is sensitive.

`prop` : | An IBusProperty.
`sensitive` : | Whether the IBusProperty is sensitive.

### ibus_property_set_visible ()

    void                ibus_property_set_visible           (IBusProperty *prop,
                                                             gboolean visible);

Set whether the IBusProperty is visible.

`prop` : | An IBusProperty.
`visible` : | Whether the IBusProperty is visible.

### ibus_property_set_state ()

    void                ibus_property_set_state             (IBusProperty *prop,
                                                             IBusPropState state);

Set the state of the IBusProperty.

`prop` : | An IBusProperty.
`state` : | The state of the IBusProperty.

### ibus_property_set_sub_props ()

    void                ibus_property_set_sub_props         (IBusProperty *prop,
                                                             IBusPropList *prop_list);

Set the sub IBusProperties.

`prop` : | An IBusProperty.
`prop_list` : | IBusPropList that contains sub IBusProperties.

### ibus_property_update ()

    gboolean            ibus_property_update                (IBusProperty *prop,
                                                             IBusProperty *prop_update);

Update the content of an IBusProperty. IBusProperty `prop_update` can either be sub-property of `prop`, or holds new values for `prop`.

`prop` : | An IBusProperty.
`prop_update` : | IBusPropList that contains sub IBusProperties.
Returns : | TRUE for update suceeded; FALSE otherwise.