1 /* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
2 /* vim:set et sts=4: */
3 /* ibus - The Input Bus
4 * Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2008-2010 Red Hat, Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
24 #error "Only <ibus.h> can be included directly"
28 * SECTION: ibusserializable
29 * @short_description: A serializable object.
32 * An #IBusSerializable is an IBus object which can be serialized, that is,
33 * to be to and from a #GVariant.
35 * This class is to be extended by other class that requires serialization.
36 * An extended class should overrides following methods:
39 * <para><function>serialize(object,iter)</function>: for serialize.</para>
42 * <para><function>deserialize(object,iter)</function>: for deserialize.</para>
45 * <para><function>copy(desc,src)</function>: for copy between IBusSerializable.</para>
48 * See IBusSerializableSerializeFunc(), IBusSerializableDeserializeFunc(), IBusSerializableCopyFunc()
49 * for function prototype.
51 #ifndef __IBUS_SERIALIZABLE_H_
52 #define __IBUS_SERIALIZABLE_H_
54 #include "ibusobject.h"
60 /* define IBusSerializable macros */
61 #define IBUS_TYPE_SERIALIZABLE \
62 (ibus_serializable_get_type ())
63 #define IBUS_SERIALIZABLE(obj) \
64 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializable))
65 #define IBUS_SERIALIZABLE_CLASS(klass) \
66 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
67 #define IBUS_IS_SERIALIZABLE(obj) \
68 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_SERIALIZABLE))
69 #define IBUS_IS_SERIALIZABLE_CLASS(klass) \
70 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_SERIALIZABLE))
71 #define IBUS_SERIALIZABLE_GET_CLASS(obj) \
72 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_SERIALIZABLE, IBusSerializableClass))
75 * ibus_serializable_set_attachment:
76 * @o: An IBusSerializable.
77 * @k: String formatted key for indexing value.
78 * @v: Value to be attached. Should be also serializable.
80 * Attach a value to an IBusSerializable.
81 * This macro is an convenient wrapper of ibus_serializable_set_qattachment().
83 #define ibus_serializable_set_attachment(o, k, v) \
84 ibus_serializable_set_qattachment (o, g_quark_from_string (k), v)
87 * ibus_serializable_get_attachment:
88 * @o: An #IBusSerializable.
89 * @k: String formatted key for indexing value.
91 * Get a value from attachment of an #IBusSerializable.
92 * This macro is an convenient wrapper of ibus_serializable_get_qattachment().
94 #define ibus_serializable_get_attachment(o, k) \
95 ibus_serializable_get_qattachment (o, g_quark_from_string (k))
98 * ibus_serializable_remove_attachment:
99 * @o: An #IBusSerializable.
100 * @k: String formatted key for indexing value.
102 * Remove a value from attachment of an #IBusSerializable.
103 * This macro is an convenient wrapper of ibus_serializable_remove_qattachment().
105 #define ibus_serializable_remove_attachment(o, k) \
106 ibus_serializable_remove_qattachment (o, g_quark_from_string (k))
110 typedef struct _IBusSerializable IBusSerializable;
111 typedef struct _IBusSerializableClass IBusSerializableClass;
112 typedef struct _IBusSerializablePrivate IBusSerializablePrivate;
117 * All the fields in the <structname>IBusSerializable</structname> structure are
118 * private to the #IBusSerializable and should never be accessed directly.
120 struct _IBusSerializable {
123 IBusSerializablePrivate *priv;
124 /* instance members */
128 * IBusSerializableSerializeFunc:
129 * @serializable: An #IBusSerializable.
130 * @builder: A #GVariantBuilder.
131 * @returns: %TRUE if succeed; %FALSE otherwise.
133 * Prototype of serialize function.
134 * Serialize function convert an #IBusSerializable to #GVariantBuilder.
135 * Returns a gboolean value which indicates whether the conversion is success.
136 * Return %TRUE if succeed.
138 typedef gboolean (* IBusSerializableSerializeFunc) (IBusSerializable *serializable,
139 GVariantBuilder *builder);
142 * IBusSerializableDeserializeFunc:
143 * @serializable: An #IBusSerializable.
144 * @variant: A #GVariant contains a tuple.
145 * @returns: The number of values in the variant(tuple) are consumed.
147 * Prototype of deserialize function.
148 * Deserialize function convert a #GVariant to #IBusSerializable.
149 * Returns an integer value which indicates how many values in
150 * the variant(tuple) are consumed.
152 typedef gint (* IBusSerializableDeserializeFunc) (IBusSerializable *serializable,
156 * IBusSerializableCopyFunc:
157 * @dest: The destination #IBusSerializable.
158 * @src: A source #IBusSerializable.
159 * @returns: %TRUE if succeed; %FALSE otherwise.
161 * Prototype of copy function.
162 * Copy function copy from source #IBusSerializable to the destination one.
163 * Returns a gboolean value which indicates whether the copying is success.
165 typedef gboolean (* IBusSerializableCopyFunc) (IBusSerializable *dest,
166 const IBusSerializable *src);
167 struct _IBusSerializableClass {
169 IBusObjectClass parent;
172 gboolean (* serialize) (IBusSerializable *object,
173 GVariantBuilder *builder);
174 gint (* deserialize) (IBusSerializable *object,
176 gboolean (* copy) (IBusSerializable *dest,
177 const IBusSerializable *src);
183 GType ibus_serializable_get_type (void);
186 * ibus_serializable_new:
188 * Creates a new instance of an #IBusSerializable.
190 * Returns: a new instance of #IBusSerializable.
192 IBusSerializable *ibus_serializable_new (void);
195 * ibus_serializable_set_qattachment:
196 * @serializable: An #IBusSerializable.
197 * @key: String formatted key for indexing value.
198 * @value: Value to be attached or %NULL to remove any prevoius value.
200 * Attach a value to an #IBusSerializable. If the value is floating,
201 * the serializable will take the ownership.
203 * See also: ibus_serializable_set_attachment().
205 void ibus_serializable_set_qattachment (IBusSerializable *serializable,
210 * ibus_serializable_get_qattachment:
211 * @serializable: An #IBusSerializable.
212 * @key: String formatted key for indexing value.
213 * @returns: The attached value; or %NULL if fail to retrieve the value.
215 * Get a value from attachment of an #IBusSerializable.
216 * See also: ibus_serializable_set_attachment().
218 GVariant *ibus_serializable_get_qattachment (IBusSerializable *serializable,
222 * ibus_serializable_remove_qattachment:
223 * @serializable: An #IBusSerializable.
224 * @key: String formatted key for indexing value.
226 * Remove a value from attachment of an #IBusSerializable.
227 * See also: ibus_serializable_remove_attachment().
229 void ibus_serializable_remove_qattachment
230 (IBusSerializable *serializable,
234 * ibus_serializable_copy:
235 * @serializable: An #IBusSerializable.
236 * @returns: (transfer none): A newly allocated clone object; or %NULL
237 * if @object is not serializable.
239 * Clone an #IBusSerializable.
240 * The copy method should be implemented in extended class.
242 * See also: IBusSerializableCopyFunc().
244 IBusSerializable *ibus_serializable_copy (IBusSerializable *serializable);
247 * ibus_serializable_serialize:
248 * @serializable: An #IBusSerializable.
249 * @returns: A #GVariant.
251 * Serialize an #IBusSerializable to a #GVariant.
252 * The serialize method should be implemented in extended class.
254 * See also: IBusSerializableCopyFunc().
256 GVariant *ibus_serializable_serialize (IBusSerializable *serializable);
259 * ibus_serializable_deserialize:
260 * @variant: A #GVariant.
261 * @returns: (transfer none): The deserialized #IBusSerializable.
263 * Deserialize a #GVariant to an #IBusSerializable/
264 * The deserialize method should be implemented in extended class.
266 * See also: IBusSerializableCopyFunc().
268 IBusSerializable *ibus_serializable_deserialize (GVariant *variant);