IBusProperty: IBus Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

IBusProperty * | ibus_property_new ()
IBusProperty * | ibus_property_new_varargs ()
const gchar * | ibus_property_get_key ()
IBusText * | ibus_property_get_label ()
void | ibus_property_set_label ()
IBusText * | ibus_property_get_symbol ()
void | ibus_property_set_symbol ()
const gchar * | ibus_property_get_icon ()
void | ibus_property_set_icon ()
IBusText * | ibus_property_get_tooltip ()
void | ibus_property_set_tooltip ()
gboolean | ibus_property_get_sensitive ()
void | ibus_property_set_sensitive ()
gboolean | ibus_property_get_visible ()
void | ibus_property_set_visible ()
IBusPropType | ibus_property_get_prop_type ()
IBusPropState | ibus_property_get_state ()
void | ibus_property_set_state ()
IBusPropList * | ibus_property_get_sub_props ()
void | ibus_property_set_sub_props ()
gboolean | ibus_property_update ()

## Properties

char * | icon | Read / Write
char * | key | Read / Write / Construct Only
IBusText * | label | Read / Write / Construct
IBusPropType | prop-type | Read / Write / Construct Only
gboolean | sensitive | Read / Write
IBusPropState | state | Read / Write
IBusPropList * | sub-props | Read / Write
IBusText * | symbol | Read / Write / Construct
IBusText * | tooltip | Read / Write
gboolean | visible | Read / Write

## Types and Values

enum | IBusPropType
enum | IBusPropState
struct | IBusProperty
| IBusPropList
| IBusPropListClass

## Object Hierarchy

        GEnum
        ├── IBusPropState
        ╰── IBusPropType
        GObject
        ╰── GInitiallyUnowned
            ╰── IBusObject
                ╰── IBusSerializable
                    ├── IBusPropList
                    ╰── IBusProperty

## 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

## Functions

### 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);

Creates a new IBusProperty.

#### Parameters

key | Unique Identity for the IBusProperty. |
type | IBusPropType of IBusProperty. |
label | Text shown in UI. |
icon | Icon file for the IBusProperty. | [allow-none]
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. | [allow-none]

#### Returns

A newly allocated IBusProperty.

### ibus_property_new_varargs ()

    IBusProperty *
    ibus_property_new_varargs (const gchar *first_property_name,
                               ...);

Creates a new IBusProperty. `ibus_property_new_varargs()` supports the va_list format. name property is required. e.g. ibus_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)

#### Parameters

first_property_name | Name of the first property. |
... | the NULL-terminated arguments of the properties and values. |

#### Returns

A newly allocated IBusProperty.

### ibus_property_get_key ()

    const gchar *
    ibus_property_get_key (IBusProperty *prop);

Get the key of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the key of IBusProperty. Should not be freed.

### ibus_property_get_label ()

    IBusText *
    ibus_property_get_label (IBusProperty *prop);

Get the label of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the label of IBusProperty. Should not be freed.

[transfer none]

### ibus_property_set_label ()

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

Set the label of IBusProperty.

#### Parameters

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

### ibus_property_get_symbol ()

    IBusText *
    ibus_property_get_symbol (IBusProperty *prop);

Get the symbol of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the symbol of IBusProperty. Should not be freed.

[transfer none]

### ibus_property_set_symbol ()

    void
    ibus_property_set_symbol (IBusProperty *prop,
                              IBusText *symbol);

Set the symbol of IBusProperty.

#### Parameters

prop | An IBusProperty. |
symbol | Text shown in UI. |

### ibus_property_get_icon ()

    const gchar *
    ibus_property_get_icon (IBusProperty *prop);

Get the icon of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the icon of IBusProperty. Should not be freed.

### ibus_property_set_icon ()

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

Set the icon of IBusProperty.

#### Parameters

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

### ibus_property_get_tooltip ()

    IBusText *
    ibus_property_get_tooltip (IBusProperty *prop);

Get the tooltip of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the tooltip of IBusProperty. Should not be freed.

[transfer none]

### ibus_property_set_tooltip ()

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

Set the tooltip of IBusProperty.

#### Parameters

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

### ibus_property_get_sensitive ()

    gboolean
    ibus_property_get_sensitive (IBusProperty *prop);

Get the sensitive of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the sensitive of IBusProperty.

### ibus_property_set_sensitive ()

    void
    ibus_property_set_sensitive (IBusProperty *prop,
                                 gboolean sensitive);

Set whether the IBusProperty is sensitive.

#### Parameters

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

### ibus_property_get_visible ()

    gboolean
    ibus_property_get_visible (IBusProperty *prop);

Get the visible of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the visible of IBusProperty.

### ibus_property_set_visible ()

    void
    ibus_property_set_visible (IBusProperty *prop,
                               gboolean visible);

Set whether the IBusProperty is visible.

#### Parameters

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

### ibus_property_get_prop_type ()

    IBusPropType
    ibus_property_get_prop_type (IBusProperty *prop);

### ibus_property_get_state ()

    IBusPropState
    ibus_property_get_state (IBusProperty *prop);

Get the state of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the state of IBusProperty.

### ibus_property_set_state ()

    void
    ibus_property_set_state (IBusProperty *prop,
                             IBusPropState state);

Set the state of the IBusProperty.

#### Parameters

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

### ibus_property_get_sub_props ()

    IBusPropList *
    ibus_property_get_sub_props (IBusProperty *prop);

Get the IBusPropList of IBusProperty.

#### Parameters

prop | An IBusProperty. |

#### Returns

the IBusPropList of IBusProperty. Should not be freed.

[transfer none]

### ibus_property_set_sub_props ()

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

Set the sub IBusProperties.

#### Parameters

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` .

#### Parameters

prop | An IBusProperty. |
prop_update | IBusPropList that contains sub IBusProperties. |

#### Returns

TRUE if update succeeded; FALSE otherwise.

## Types and Values

### enum IBusPropType

Type enumeration of IBusProperty.

#### Members

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

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.

#### Members

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. |

### struct IBusProperty

    struct IBusProperty;

### IBusPropList

    typedef struct {
        GArray *properties;
    } IBusPropList;

An array of IBusProperties.

#### Members

GArray *`properties`; | GArray that holds IBusProperties. |

### IBusPropListClass

    typedef struct {
        IBusSerializableClass parent;
    } IBusPropListClass;

Class structure for IBusPropList.

#### Members

IBusSerializableClass `parent`; | The parent class. |

## Property Details

### The `“icon”` property

      “icon”                     char *

The icon of property.

Owner: IBusProperty

Flags: Read / Write

Default value: ""

### The `“key”` property

      “key”                      char *

The key of property.

Owner: IBusProperty

Flags: Read / Write / Construct Only

Default value: ""

### The `“label”` property

      “label”                    IBusText *

The label of property.

Owner: IBusProperty

Flags: Read / Write / Construct

### The `“prop-type”` property

      “prop-type”                IBusPropType

The type of property.

Owner: IBusProperty

Flags: Read / Write / Construct Only

Default value: PROP_TYPE_NORMAL

### The `“sensitive”` property

      “sensitive”                gboolean

The sensitive of property.

Owner: IBusProperty

Flags: Read / Write

Default value: TRUE

### The `“state”` property

      “state”                    IBusPropState

The state of property.

Owner: IBusProperty

Flags: Read / Write

Default value: PROP_STATE_UNCHECKED

### The `“sub-props”` property

      “sub-props”                IBusPropList *

The sub properties of property.

Owner: IBusProperty

Flags: Read / Write

### The `“symbol”` property

      “symbol”                   IBusText *

The symbol of property.

Owner: IBusProperty

Flags: Read / Write / Construct

### The `“tooltip”` property

      “tooltip”                  IBusText *

The tooltip of property.

Owner: IBusProperty

Flags: Read / Write

### The `“visible”` property

      “visible”                  gboolean

The visible of property.

Owner: IBusProperty

Flags: Read / Write

Default value: TRUE