IBusComponent

## IBusComponent IBusComponent — Component (executable) specification. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IBusComponent;
                        IBusComponentClass;
    IBusComponent *     ibus_component_new                  (const gchar *name,
                                                             const gchar *description,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *author,
                                                             const gchar *homepage,
                                                             const gchar *exec,
                                                             const gchar *textdomain);
    IBusComponent *     ibus_component_new_from_xml_node    (XMLNode *node);
    IBusComponent *     ibus_component_new_from_file        (const gchar *filename);
    void                ibus_component_add_observed_path    (IBusComponent *component,
                                                             const gchar *path,
                                                             gboolean access_fs);
    void                ibus_component_add_engine           (IBusComponent *component,
                                                             IBusEngineDesc *engine);
    GList *             ibus_component_get_engines          (IBusComponent *component);
    void                ibus_component_output               (IBusComponent *component,
                                                             GString *output,
                                                             gint indent);
    void                ibus_component_output_engines       (IBusComponent *component,
                                                             GString *output,
                                                             gint indent);
    gboolean            ibus_component_check_modification   (IBusComponent *component);
    gboolean            ibus_component_start                (IBusComponent *component,
                                                             gboolean verbose);
    gboolean            ibus_component_stop                 (IBusComponent *component);
    gboolean            ibus_component_is_running           (IBusComponent *component);
    IBusComponent *     ibus_component_get_from_engine      (IBusEngineDesc *engine);
    void                ibus_component_set_restart          (IBusComponent *component,
                                                             gboolean restart);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusSerializable
                         +----IBusComponent

## Description

An IBusComponent is an executable program. It provides services such as user interface, configuration, and input method engine (IME).

It is recommended that IME developers provide a component XML file and load the XML file by `ibus_component_new_from_file()`.

The format of a component XML file is described at http://code.google.com/p/ibus/wiki/DevXML

## Details

### IBusComponent

    typedef struct {
        gchar *name;
        gchar *description;
        gchar *version;
        gchar *license;
        gchar *author;
        gchar *homepage;
        gchar *exec;

        /* text domain for dgettext */
        gchar *textdomain;
    } IBusComponent;

An IBusComponent stores component information.

gchar *`name`; | Name of the component.
gchar *`description`; | Detailed description of component.
gchar *`version`; | Component version.
gchar *`license`; | Distribution license of this component.
gchar *`author`; | Author(s) of the component.
gchar *`homepage`; | Homepage of the component.
gchar *`exec`; | path to component executable.
gchar *`textdomain`; | Domain name for `dgettext()`

### IBusComponentClass

    typedef struct {
      IBusSerializableClass parent;

      /* class members */
    } IBusComponentClass;

### ibus_component_new ()

    IBusComponent *     ibus_component_new                  (const gchar *name,
                                                             const gchar *description,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *author,
                                                             const gchar *homepage,
                                                             const gchar *exec,
                                                             const gchar *textdomain);

New an IBusComponent.

`name` : | Name of the component.
`description` : | Detailed description of component.
`version` : | Component version.
`license` : | Distribution license of this component.
`author` : | Author(s) of the component.
`homepage` : | Homepage of the component.
`exec` : | path to component executable.
`textdomain` : | Domain name for `dgettext()`
Returns : | A newly allocated IBusComponent.

### ibus_component_new_from_xml_node ()

    IBusComponent *     ibus_component_new_from_xml_node    (XMLNode *node);

New an IBusComponent from an XML tree.

`node` : | Root node of component XML tree.
Returns : | A newly allocated IBusComponent.

### ibus_component_new_from_file ()

    IBusComponent *     ibus_component_new_from_file        (const gchar *filename);

New an IBusComponent from an XML file. Note that a component file usually contains engine descriptions, if it does, `ibus_engine_desc_new_from_xml_node()` will be called to load the engine descriptions.

`filename` : | An XML file that contains component information.
Returns : | A newly allocated IBusComponent.

### ibus_component_add_observed_path ()

    void                ibus_component_add_observed_path    (IBusComponent *component,
                                                             const gchar *path,
                                                             gboolean access_fs);

Add an observed path to IBusComponent.

`component` : | An IBusComponent
`path` : | Observed path to be added.
`access_fs` : | TRUE for filling the file status; FALSE otherwise.

### ibus_component_add_engine ()

    void                ibus_component_add_engine           (IBusComponent *component,
                                                             IBusEngineDesc *engine);

Add an engine to IBusComponent according to the description in `engine`.

`component` : | An IBusComponent
`engine` : | A description of an engine.

### ibus_component_get_engines ()

    GList *             ibus_component_get_engines          (IBusComponent *component);

Get the engines of this component.

`component` : | An IBusComponent.
Returns : | A newly allocated GList that contains engines. [transfer none][element-type IBusEngineDesc]

### ibus_component_output ()

    void                ibus_component_output               (IBusComponent *component,
                                                             GString *output,
                                                             gint indent);

Output IBusComponent as an XML-formatted string. The output string can be then shown on the screen or written to file.

`component` : | An IBusComponent.
`output` : | GString that holds the result.
`indent` : | level of indent.

### ibus_component_output_engines ()

    void                ibus_component_output_engines       (IBusComponent *component,
                                                             GString *output,
                                                             gint indent);

Output engine description as an XML-formatted string. The output string can be then shown on the screen or written to file.

`component` : | An IBusComponent.
`output` : | GString that holds the result.
`indent` : | level of indent.

### ibus_component_check_modification ()

    gboolean            ibus_component_check_modification   (IBusComponent *component);

Check whether the observed paths of component is modified.

`component` : | An IBusComponent.
Returns : | TRUE if at least one of the observed paths is modified; FALSE otherwise.

### ibus_component_start ()

    gboolean            ibus_component_start                (IBusComponent *component,
                                                             gboolean verbose);

Whether the IBusComponent is started.

`component` : | An IBusComponent.
`verbose` : | if FALSE, redirect the child output to /dev/null
Returns : | TRUE if the component is started; FALSE otherwise.

### ibus_component_stop ()

    gboolean            ibus_component_stop                 (IBusComponent *component);

Whether the IBusComponent is stopped.

`component` : | An IBusComponent.
Returns : | TRUE if the component is stopped; FALSE otherwise.

### ibus_component_is_running ()

    gboolean            ibus_component_is_running           (IBusComponent *component);

Whether the IBusComponent is running.

`component` : | An IBusComponent.
Returns : | TRUE if the component is running; FALSE otherwise.

### ibus_component_get_from_engine ()

    IBusComponent *     ibus_component_get_from_engine      (IBusEngineDesc *engine);

Get the IBusComponent from an engine description.

`engine` : | A description of an engine.
Returns : | An IBusComponent of the engine. [transfer none]

### ibus_component_set_restart ()

    void                ibus_component_set_restart          (IBusComponent *component,
                                                             gboolean restart);

Set whether the component needs to be restarted when it dies.

`component` : | An IBusComponent.
`restart` : | if TRUE, the component will be restartd when it dies.