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