IBusSerializable

## IBusSerializable IBusSerializable — A serializable object. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #define             ibus_serializable_set_attachment    (o,
                                                             k,
                                                             v)
    #define             ibus_serializable_get_attachment    (o,
                                                             k)
    #define             ibus_serializable_remove_attachment (o,
                                                             k)
    struct              IBusSerializable;
    gboolean            (*IBusSerializableSerializeFunc)    (IBusSerializable *serializable,
                                                             GVariantBuilder *builder);
    gint                (*IBusSerializableDeserializeFunc)  (IBusSerializable *serializable,
                                                             GVariant *variant);
    gboolean            (*IBusSerializableCopyFunc)         (IBusSerializable *dest,
                                                             const IBusSerializable *src);
    struct              IBusSerializableClass;
    IBusSerializable *  ibus_serializable_new               (void);
    void                ibus_serializable_set_qattachment   (IBusSerializable *serializable,
                                                             GQuark key,
                                                             GVariant *value);
    GVariant *          ibus_serializable_get_qattachment   (IBusSerializable *serializable,
                                                             GQuark key);
    void                ibus_serializable_remove_qattachment
                                                            (IBusSerializable *serializable,
                                                             GQuark key);
    IBusSerializable *  ibus_serializable_copy              (IBusSerializable *serializable);
    GVariant *          ibus_serializable_serialize         (IBusSerializable *serializable);
    IBusSerializable *  ibus_serializable_deserialize       (GVariant *variant);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----IBusObject
                   +----IBusSerializable
                         +----IBusHotkeyProfile
                         +----IBusText
                         +----IBusAttribute
                         +----IBusAttrList
                         +----IBusEngineDesc
                         +----IBusLookupTable
                         +----IBusComponent
                         +----IBusProperty
                         +----IBusPropList
                         +----IBusObservedPath
                         +----IBusRegistry

## Description

An IBusSerializable is an IBus object which can be serialized, that is, to be to and from a GVariant.

This class is to be extended by other class that requires serialization. An extended class should overrides following methods:

- `serialize(object,iter)`: for serialize.

- `deserialize(object,iter)`: for deserialize.

- `copy(desc,src)`: for copy between IBusSerializable.

See `IBusSerializableSerializeFunc()`, `IBusSerializableDeserializeFunc()`, `IBusSerializableCopyFunc()` for function prototype.

## Details

### ibus_serializable_set_attachment()

    #define             ibus_serializable_set_attachment(o, k, v)

Attach a value to an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_set_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.
`v` : | Value to be attached. Should be also serializable.

### ibus_serializable_get_attachment()

    #define             ibus_serializable_get_attachment(o, k)

Get a value from attachment of an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_get_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.

### ibus_serializable_remove_attachment()

    #define             ibus_serializable_remove_attachment(o, k)

Remove a value from attachment of an IBusSerializable. This macro is an convenient wrapper of `ibus_serializable_remove_qattachment()`.

`o` : | An IBusSerializable.
`k` : | String formatted key for indexing value.

### struct IBusSerializable

    struct IBusSerializable;

All the fields in the IBusSerializable structure are private to the IBusSerializable and should never be accessed directly.

### IBusSerializableSerializeFunc ()

    gboolean            (*IBusSerializableSerializeFunc)    (IBusSerializable *serializable,
                                                             GVariantBuilder *builder);

Prototype of serialize function. Serialize function convert an IBusSerializable to GVariantBuilder. Returns a gboolean value which indicates whether the conversion is success. Return `TRUE` if succeed.

`serializable` : | An IBusSerializable.
`builder` : | A GVariantBuilder.
Returns : | `TRUE` if succeed; `FALSE` otherwise.

### IBusSerializableDeserializeFunc ()

    gint                (*IBusSerializableDeserializeFunc)  (IBusSerializable *serializable,
                                                             GVariant *variant);

Prototype of deserialize function. Deserialize function convert a GVariant to IBusSerializable. Returns an integer value which indicates how many values in the variant(tuple) are consumed.

`serializable` : | An IBusSerializable.
`variant` : | A GVariant contains a tuple.
Returns : | The number of values in the variant(tuple) are consumed.

### IBusSerializableCopyFunc ()

    gboolean            (*IBusSerializableCopyFunc)         (IBusSerializable *dest,
                                                             const IBusSerializable *src);

Prototype of copy function. Copy function copy from source IBusSerializable to the destination one. Returns a gboolean value which indicates whether the copying is success.

`dest` : | The destination IBusSerializable.
`src` : | A source IBusSerializable.
Returns : | `TRUE` if succeed; `FALSE` otherwise.

### struct IBusSerializableClass

    struct IBusSerializableClass {
    };

### ibus_serializable_new ()

    IBusSerializable *  ibus_serializable_new               (void);

Creates a new instance of an IBusSerializable.

Returns : | a new instance of IBusSerializable.

### ibus_serializable_set_qattachment ()

    void                ibus_serializable_set_qattachment   (IBusSerializable *serializable,
                                                             GQuark key,
                                                             GVariant *value);

Attach a value to an IBusSerializable. If the value is floating, the serializable will take the ownership.

See also: `ibus_serializable_set_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.
`value` : | Value to be attached or `NULL` to remove any prevoius value.

### ibus_serializable_get_qattachment ()

    GVariant *          ibus_serializable_get_qattachment   (IBusSerializable *serializable,
                                                             GQuark key);

Get a value from attachment of an IBusSerializable. See also: `ibus_serializable_set_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.
Returns : | The attached value; or `NULL` if fail to retrieve the value.

### ibus_serializable_remove_qattachment ()

    void                ibus_serializable_remove_qattachment
                                                            (IBusSerializable *serializable,
                                                             GQuark key);

Remove a value from attachment of an IBusSerializable. See also: `ibus_serializable_remove_attachment()`.

`serializable` : | An IBusSerializable.
`key` : | String formatted key for indexing value.

### ibus_serializable_copy ()

    IBusSerializable *  ibus_serializable_copy              (IBusSerializable *serializable);

Clone an IBusSerializable. The copy method should be implemented in extended class.

See also: `IBusSerializableCopyFunc()`.

`serializable` : | An IBusSerializable.
Returns : | A newly allocated clone object; or `NULL` if `object` is not serializable. [transfer none]

### ibus_serializable_serialize ()

    GVariant *          ibus_serializable_serialize         (IBusSerializable *serializable);

Serialize an IBusSerializable to a GVariant. The serialize method should be implemented in extended class.

See also: `IBusSerializableCopyFunc()`.

`serializable` : | An IBusSerializable.
Returns : | A GVariant.

### ibus_serializable_deserialize ()

    IBusSerializable *  ibus_serializable_deserialize       (GVariant *variant);

Deserialize a GVariant to an IBusSerializable/ The deserialize method should be implemented in extended class.

See also: `IBusSerializableCopyFunc()`.

`variant` : | A GVariant.
Returns : | The deserialized IBusSerializable. [transfer none]