IBusSerializable: IBus Reference Manual

## IBusSerializable IBusSerializable — A serializable object. |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | ibus_serializable_set_attachment()
#define | ibus_serializable_get_attachment()
#define | ibus_serializable_remove_attachment()
gboolean | (*IBusSerializableSerializeFunc) ()
gint | (*IBusSerializableDeserializeFunc) ()
gboolean | (*IBusSerializableCopyFunc) ()
IBusSerializable * | ibus_serializable_new ()
void | ibus_serializable_set_qattachment ()
GVariant * | ibus_serializable_get_qattachment ()
void | ibus_serializable_remove_qattachment ()
IBusSerializable * | ibus_serializable_copy ()
GVariant * | ibus_serializable_serialize ()
IBusSerializable * | ibus_serializable_deserialize ()

## Types and Values

struct | IBusSerializable

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

## Functions

### 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()`.

#### Parameters

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

#### Parameters

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

dest | The destination IBusSerializable. |
src | A source IBusSerializable. |

#### Returns

`TRUE` if succeed; `FALSE` otherwise.

### 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()`.

#### Parameters

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

Gets a value from attachment of an IBusSerializable.

#### Parameters

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

#### Returns

The attached value; or `NULL` if fail to retrieve the value.

See also: `ibus_serializable_set_attachment()`.

### 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()`.

#### Parameters

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.

#### Parameters

serializable | An IBusSerializable. |

#### Returns

A newly allocated clone object; or `NULL` if `object` is not serializable.

See also: `IBusSerializableCopyFunc()`.

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

#### Parameters

serializable | An IBusSerializable. |

#### Returns

A GVariant.

See also: `IBusSerializableCopyFunc()`.

### ibus_serializable_deserialize ()

    IBusSerializable *
    ibus_serializable_deserialize (GVariant *variant);

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

#### Parameters

variant | A GVariant. |

#### Returns

The deserialized IBusSerializable.

See also: `IBusSerializableCopyFunc()`.

[transfer none]

## Types and Values

### struct IBusSerializable

    struct IBusSerializable;

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