IBusComponent

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

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              IBusComponent;
    struct              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_varargs          (const gchar *first_property_name,
                                                             ...);
    IBusComponent *     ibus_component_new_from_xml_node    (XMLNode *node);
    IBusComponent *     ibus_component_new_from_file        (const gchar *filename);
    const gchar *       ibus_component_get_name             (IBusComponent *component);
    const gchar *       ibus_component_get_description      (IBusComponent *component);
    const gchar *       ibus_component_get_version          (IBusComponent *component);
    const gchar *       ibus_component_get_license          (IBusComponent *component);
    const gchar *       ibus_component_get_author           (IBusComponent *component);
    const gchar *       ibus_component_get_homepage         (IBusComponent *component);
    const gchar *       ibus_component_get_exec             (IBusComponent *component);
    const gchar *       ibus_component_get_textdomain       (IBusComponent *component);
    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);

## Object Hierarchy

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

## Properties

      "author"                   gchar*                : Read / Write / Construct Only
      "description"              gchar*                : Read / Write / Construct Only
      "exec"                     gchar*                : Read / Write / Construct Only
      "homepage"                 gchar*                : Read / Write / Construct Only
      "license"                  gchar*                : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct Only
      "textdomain"               gchar*                : Read / Write / Construct Only
      "version"                  gchar*                : Read / Write / Construct Only

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

### struct IBusComponent

    struct IBusComponent {
        /* padding */
        gpointer pdummy[7];  // We can add 7 pointers without breaking the ABI.
    };

An IBusComponent stores component information. You can get extended values with g_object_get_properties. 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()`

### struct IBusComponentClass

    struct IBusComponentClass {
      IBusSerializableClass parent;

      /* class members */
    };

### 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_varargs ()

    IBusComponent *     ibus_component_new_varargs          (const gchar *first_property_name,
                                                             ...);

New an IBusComponent. `ibus_component_new_varargs()` supports the va_list format. name property is required. e.g. IBusComponent *component = ibus_component_new_varargs ("name", "ibus-foo", "exec", "/usr/libexec/ibus-engine-foo --ibus", NULL)

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

### 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_get_name ()

    const gchar *       ibus_component_get_name             (IBusComponent *component);

Return the name property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | name property in IBusComponent

### ibus_component_get_description ()

    const gchar *       ibus_component_get_description      (IBusComponent *component);

Return the description property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | description property in IBusComponent

### ibus_component_get_version ()

    const gchar *       ibus_component_get_version          (IBusComponent *component);

Return the version property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | version property in IBusComponent

### ibus_component_get_license ()

    const gchar *       ibus_component_get_license          (IBusComponent *component);

Return the license property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | license property in IBusComponent

### ibus_component_get_author ()

    const gchar *       ibus_component_get_author           (IBusComponent *component);

Return the author property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | author property in IBusComponent

### ibus_component_get_homepage ()

    const gchar *       ibus_component_get_homepage         (IBusComponent *component);

Return the homepage property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | homepage property in IBusComponent

### ibus_component_get_exec ()

    const gchar *       ibus_component_get_exec             (IBusComponent *component);

Return the exec property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | exec property in IBusComponent

### ibus_component_get_textdomain ()

    const gchar *       ibus_component_get_textdomain       (IBusComponent *component);

Return the textdomain property in IBusComponent. It should not be freed.

`component` : | An IBusComponent
Returns : | textdomain property in 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 container][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.

## Property Details

### The `"author"` property

      "author"                   gchar*                : Read / Write / Construct Only

The author of component

Default value: NULL

### The `"description"` property

      "description"              gchar*                : Read / Write / Construct Only

The description of component

Default value: NULL

### The `"exec"` property

      "exec"                     gchar*                : Read / Write / Construct Only

The exec path of component

Default value: NULL

### The `"homepage"` property

      "homepage"                 gchar*                : Read / Write / Construct Only

The homepage of component

Default value: NULL

### The `"license"` property

      "license"                  gchar*                : Read / Write / Construct Only

The license of component

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The name of component

Default value: NULL

### The `"textdomain"` property

      "textdomain"               gchar*                : Read / Write / Construct Only

The textdomain of component

Default value: NULL

### The `"version"` property

      "version"                  gchar*                : Read / Write / Construct Only

The version of component

Default value: NULL