1/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
2/* vim:set et sts=4: */
3/* bus - The Input Bus
4 * Copyright (C) 2008-2015 Peng Huang <shawn.p.huang@gmail.com>
5 * Copyright (C) 2008-2015 Red Hat, Inc.
6 *
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.1 of the License, or (at your option) any later version.
11 *
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.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
20 * USA
21 */
22
23#if !defined (__IBUS_H_INSIDE__) && !defined (IBUS_COMPILATION)
24#error "Only <ibus.h> can be included directly"
25#endif
26
27#ifndef __IBUS_ENGINE_DESC_H_
28#define __IBUS_ENGINE_DESC_H_
29
30/**
31 * SECTION: ibusenginedesc
32 * @short_description: Input method engine description data.
33 * @title: IBusEngineDesc
34 * @stability: Stable
35 *
36 * An IBusEngineDesc stores description data of IBusEngine.
37 * The description data can either be passed to ibus_engine_desc_new(),
38 * or loaded from an XML node through ibus_engine_desc_new_from_xml_node()
39 * to construct IBusEngineDesc.
40 *
41 * However, the recommended way to load engine description data is
42 * using ibus_component_new_from_file() to load a component file,
43 * which also includes engine description data.
44 *
45 * see_also: #IBusComponent, #IBusEngine
46 *
47 */
48
49#include "ibusserializable.h"
50#include "ibusxml.h"
51
52/*
53 * Type macros.
54 */
55
56/* define GOBJECT macros */
57#define IBUS_TYPE_ENGINE_DESC \
58 (ibus_engine_desc_get_type ())
59#define IBUS_ENGINE_DESC(obj) \
60 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_ENGINE_DESC, IBusEngineDesc))
61#define IBUS_ENGINE_DESC_CLASS(klass) \
62 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_ENGINE_DESC, IBusEngineDescClass))
63#define IBUS_IS_ENGINE_DESC(obj) \
64 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_ENGINE_DESC))
65#define IBUS_IS_ENGINE_DESC_CLASS(klass) \
66 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_ENGINE_DESC))
67#define IBUS_ENGINE_DESC_GET_CLASS(obj) \
68 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_ENGINE_DESC, IBusEngineDescClass))
69
70G_BEGIN_DECLS
71
72typedef struct _IBusEngineDesc IBusEngineDesc;
73typedef struct _IBusEngineDescPrivate IBusEngineDescPrivate;
74typedef struct _IBusEngineDescClass IBusEngineDescClass;
75
76/**
77 * IBusEngineDesc:
78 *
79 * Input method engine description data.
80 * You can get extended values with g_object_get_properties.
81 */
82struct _IBusEngineDesc {
83 IBusSerializable parent;
84 /* instance members */
85
86 /*< public >*/
87 /*< private >*/
88 IBusEngineDescPrivate *priv;
89};
90
91struct _IBusEngineDescClass {
92 IBusSerializableClass parent;
93 /* class members */
94};
95
96GType ibus_engine_desc_get_type (void);
97
98/**
99 * ibus_engine_desc_new:
100 * @name: Name of the engine.
101 * @longname: Long name of the input method engine.
102 * @description: Input method engine description.
103 * @language: Language (e.g. zh, jp) supported by this input method engine.
104 * @license: License of the input method engine.
105 * @author: Author of the input method engine.
106 * @icon: Icon file of this engine.
107 * @layout: Keyboard layout
108 *
109 * Creates a new #IBusEngineDesc.
110 *
111 * Returns: A newly allocated IBusEngineDesc.
112 */
113IBusEngineDesc *ibus_engine_desc_new (const gchar *name,
114 const gchar *longname,
115 const gchar *description,
116 const gchar *language,
117 const gchar *license,
118 const gchar *author,
119 const gchar *icon,
120 const gchar *layout);
121
122/**
123 * ibus_engine_desc_new_varargs:
124 * @first_property_name: Name of the first property.
125 * @...: the NULL-terminated arguments of the properties and values.
126 *
127 * Creates a new #IBusEngineDesc.
128 * ibus_engine_desc_new_varargs() supports the va_list format.
129 * name property is required. e.g.
130 * ibus_engine_desc_new_varargs("name", "ibus-foo", "language", "us", NULL)
131 *
132 * Returns: A newly allocated IBusEngineDesc.
133 */
134IBusEngineDesc *ibus_engine_desc_new_varargs (const gchar *first_property_name,
135 ...);
136
137
138/**
139 * ibus_engine_desc_new_from_xml_node:
140 * @node: An XML node
141 *
142 * Creates a new IBusEngineDesc from an XML node.
143 * <note><para>This function is called by ibus_component_new_from_file(),
144 * so developers normally do not need to call it directly.
145 * </para></note>
146 *
147 * Returns: A newly allocated IBusEngineDesc that contains description from
148 * @node.
149 */
150IBusEngineDesc *ibus_engine_desc_new_from_xml_node
151 (XMLNode *node);
152/**
153 * ibus_engine_desc_get_name:
154 * @info: An IBusEngineDesc
155 *
156 * Gets the name property in IBusEngineDesc. It should not be freed.
157 *
158 * Returns: name property in IBusEngineDesc
159 */
160const gchar *ibus_engine_desc_get_name (IBusEngineDesc *info);
161
162/**
163 * ibus_engine_desc_get_longname:
164 * @info: An IBusEngineDesc
165 *
166 * Gets the longname property in IBusEngineDesc. It should not be freed.
167 *
168 * Returns: longname property in IBusEngineDesc
169 */
170const gchar *ibus_engine_desc_get_longname (IBusEngineDesc *info);
171
172/**
173 * ibus_engine_desc_get_description:
174 * @info: An IBusEngineDesc
175 *
176 * Gets the description property in IBusEngineDesc. It should not be freed.
177 *
178 * Returns: description property in IBusEngineDesc
179 */
180const gchar *ibus_engine_desc_get_description
181 (IBusEngineDesc *info);
182
183/**
184 * ibus_engine_desc_get_language:
185 * @info: An IBusEngineDesc
186 *
187 * Gets the language property in IBusEngineDesc. It should not be freed.
188 *
189 * Returns: language property in IBusEngineDesc
190 */
191const gchar *ibus_engine_desc_get_language (IBusEngineDesc *info);
192
193
194/**
195 * ibus_engine_desc_get_license:
196 * @info: An IBusEngineDesc
197 *
198 * Gets the license property in IBusEngineDesc. It should not be freed.
199 *
200 * Returns: license property in IBusEngineDesc
201 */
202const gchar *ibus_engine_desc_get_license (IBusEngineDesc *info);
203
204/**
205 * ibus_engine_desc_get_author:
206 * @info: An IBusEngineDesc
207 *
208 * Gets the author property in IBusEngineDesc. It should not be freed.
209 *
210 * Returns: author property in IBusEngineDesc
211 */
212const gchar *ibus_engine_desc_get_author (IBusEngineDesc *info);
213
214/**
215 * ibus_engine_desc_get_icon:
216 * @info: An IBusEngineDesc
217 *
218 * Gets the icon property in IBusEngineDesc. It should not be freed.
219 *
220 * Returns: icon property in IBusEngineDesc
221 */
222const gchar *ibus_engine_desc_get_icon (IBusEngineDesc *info);
223
224/**
225 * ibus_engine_desc_get_layout:
226 * @info: An IBusEngineDesc
227 *
228 * Gets the layout property in IBusEngineDesc. It should not be freed.
229 *
230 * Returns: layout property in IBusEngineDesc
231 */
232const gchar *ibus_engine_desc_get_layout (IBusEngineDesc *info);
233
234/**
235 * ibus_engine_desc_get_layout_variant:
236 * @info: An IBusEngineDesc
237 *
238 * Gets the keyboard variant property in IBusEngineDesc. It should not be freed.
239 *
240 * Returns: keyboard variant property in IBusEngineDesc
241 */
242const gchar *ibus_engine_desc_get_layout_variant
243 (IBusEngineDesc *info);
244
245/**
246 * ibus_engine_desc_get_layout_option:
247 * @info: An IBusEngineDesc
248 *
249 * Gets the keyboard option property in IBusEngineDesc. It should not be freed.
250 *
251 * Returns: keyboard option property in IBusEngineDesc
252 */
253const gchar *ibus_engine_desc_get_layout_option
254 (IBusEngineDesc *info);
255
256/**
257 * ibus_engine_desc_get_rank:
258 * @info: An IBusEngineDesc
259 *
260 * Gets the rank property in IBusEngineDesc.
261 *
262 * Returns: rank property in IBusEngineDesc
263 */
264guint ibus_engine_desc_get_rank (IBusEngineDesc *info);
265
266/**
267 * ibus_engine_desc_get_hotkeys:
268 * @info: An IBusEngineDesc
269 *
270 * Gets the hotkeys property in IBusEngineDesc. It should not be freed.
271 *
272 * Returns: hotkeys property in IBusEngineDesc
273 */
274const gchar *ibus_engine_desc_get_hotkeys (IBusEngineDesc *info);
275
276/**
277 * ibus_engine_desc_get_symbol:
278 * @info: An IBusEngineDesc
279 *
280 * Gets the symbol property in IBusEngineDesc. It should not be freed.
281 *
282 * Returns: symbol property in IBusEngineDesc
283 */
284const gchar *ibus_engine_desc_get_symbol (IBusEngineDesc *info);
285
286/**
287 * ibus_engine_desc_get_setup:
288 * @info: An IBusEngineDesc
289 *
290 * Gets the setup property in IBusEngineDesc. It should not be freed.
291 *
292 * Returns: setup property in IBusEngineDesc
293 */
294const gchar *ibus_engine_desc_get_setup (IBusEngineDesc *info);
295
296/**
297 * ibus_engine_desc_get_version:
298 * @info: An IBusEngineDesc
299 *
300 * Gets the version property in IBusEngineDesc. It should not be freed.
301 *
302 * Returns: version in IBusEngineDesc
303 */
304const gchar *ibus_engine_desc_get_version (IBusEngineDesc *info);
305
306/**
307 * ibus_engine_desc_get_textdomain:
308 * @info: An IBusEngineDesc
309 *
310 * Gets the textdomain property in IBusEngineDesc. It should not be freed.
311 *
312 * Returns: textdomain in IBusEngineDesc
313 */
314const gchar *ibus_engine_desc_get_textdomain
315 (IBusEngineDesc *info);
316
317/**
318 * ibus_engine_desc_get_icon_prop_key:
319 * @info: An IBusEngineDesc
320 *
321 * Gets the key of IBusProperty to load the panel icon dynamically
322 * in IBusEngineDesc. It should not be freed.
323 *
324 * Returns: IBusProperty.key for dynamic panel icon in IBusEngineDesc
325 */
326const gchar *ibus_engine_desc_get_icon_prop_key
327 (IBusEngineDesc *info);
328
329/**
330 * ibus_engine_desc_output:
331 * @info: An IBusEngineDesc
332 * @output: XML-formatted Input method engine description.
333 * @indent: Number of indent (showed as 4 spaces).
334 *
335 * Output XML-formatted input method engine description.
336 * The result will be append to GString specified in @output.
337 */
338void ibus_engine_desc_output (IBusEngineDesc *info,
339 GString *output,
340 gint indent);
341G_END_DECLS
342#endif
343