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_COMPONENT_H_
28#define __IBUS_COMPONENT_H_
29
30/**
31 * SECTION: ibuscomponent
32 * @short_description: Component (executable) specification.
33 * @title: IBusComponent
34 * @stability: Stable
35 *
36 * An IBusComponent is an executable program.
37 * It provides services such as user interface, configuration,
38 * and input method engine (IME).
39 *
40 * It is recommended that IME developers provide
41 * a component XML file and
42 * load the XML file by ibus_component_new_from_file().
43 *
44 * The format of a component XML file is described at
45 * <ulink url="https://github.com/ibus/ibus/wiki/DevXML">https://github.com/ibus/ibus/wiki/DevXML</ulink>
46 */
47
48#include "ibusserializable.h"
49#include "ibusobservedpath.h"
50#include "ibusenginedesc.h"
51#include "ibusxml.h"
52
53/*
54 * Type macros.
55 */
56
57/* define GOBJECT macros */
58#define IBUS_TYPE_COMPONENT \
59 (ibus_component_get_type ())
60#define IBUS_COMPONENT(obj) \
61 (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_COMPONENT, IBusComponent))
62#define IBUS_COMPONENT_CLASS(klass) \
63 (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_COMPONENT, IBusComponentClass))
64#define IBUS_IS_COMPONENT(obj) \
65 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_COMPONENT))
66#define IBUS_IS_COMPONENT_CLASS(klass) \
67 (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_COMPONENT))
68#define IBUS_COMPONENT_GET_CLASS(obj) \
69 (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_COMPONENT, IBusComponentClass))
70
71G_BEGIN_DECLS
72
73typedef struct _IBusComponent IBusComponent;
74typedef struct _IBusComponentClass IBusComponentClass;
75typedef struct _IBusComponentPrivate IBusComponentPrivate;
76
77/**
78 * IBusComponent:
79 *
80 * An IBusComponent stores component information.
81 * You can get extended values with g_object_get_properties.
82 */
83struct _IBusComponent {
84 /*< private >*/
85 IBusSerializable parent;
86 IBusComponentPrivate *priv;
87 /* instance members */
88
89 /*< public >*/
90
91 /*< private >*/
92 /* padding */
93 gpointer pdummy[7]; // We can add 7 pointers without breaking the ABI.
94};
95
96struct _IBusComponentClass {
97 IBusSerializableClass parent;
98
99 /* class members */
100};
101
102GType ibus_component_get_type (void);
103
104/**
105 * ibus_component_new:
106 * @name: Name of the component.
107 * @description: Detailed description of component.
108 * @version: Component version.
109 * @license: Distribution license of this component.
110 * @author: Author(s) of the component.
111 * @homepage: Homepage of the component.
112 * @command_line: path to component executable.
113 * @textdomain: Domain name for dgettext()
114 *
115 * Creates a new #IBusComponent.
116 *
117 * Returns: A newly allocated #IBusComponent.
118 */
119IBusComponent *ibus_component_new (const gchar *name,
120 const gchar *description,
121 const gchar *version,
122 const gchar *license,
123 const gchar *author,
124 const gchar *homepage,
125 const gchar *command_line,
126 const gchar *textdomain);
127
128/**
129 * ibus_component_new_varargs:
130 * @first_property_name: Name of the first property.
131 * @...: the NULL-terminated arguments of the properties and values.
132 *
133 * Creates a new #IBusComponent.
134 * ibus_component_new_varargs() supports the va_list format.
135 * name property is required. e.g.
136 * IBusComponent *component = ibus_component_new_varargs ("name", "ibus-foo",
137 * "command_line", "/usr/libexec/ibus-engine-foo --ibus",
138 * NULL)
139 *
140 * Returns: A newly allocated #IBusComponent.
141 */
142IBusComponent *ibus_component_new_varargs (const gchar *first_property_name,
143 ...);
144
145/**
146 * ibus_component_new_from_xml_node:
147 * @node: Root node of component XML tree.
148 *
149 * Creates a new #IBusComponent from an XML tree.
150 *
151 * Returns: A newly allocated #IBusComponent.
152 */
153IBusComponent *ibus_component_new_from_xml_node
154 (XMLNode *node);
155
156/**
157 * ibus_component_new_from_file:
158 * @filename: An XML file that contains component information.
159 *
160 * Creates a new #IBusComponent from an XML file.
161 * Note that a component file usually contains engine descriptions,
162 * if it does, ibus_engine_desc_new_from_xml_node() will be called
163 * to load the engine descriptions.
164 *
165 * Returns: A newly allocated #IBusComponent.
166 */
167IBusComponent *ibus_component_new_from_file (const gchar *filename);
168
169/**
170 * ibus_component_get_name:
171 * @component: An #IBusComponent
172 *
173 * Gets the name property in #IBusComponent. It should not be freed.
174 *
175 * Returns: name property in #IBusComponent
176 */
177const gchar *ibus_component_get_name (IBusComponent *component);
178
179/**
180 * ibus_component_get_description:
181 * @component: An #IBusComponent
182 *
183 * Gets the description property in #IBusComponent. It should not be freed.
184 *
185 * Returns: description property in #IBusComponent
186 */
187const gchar *ibus_component_get_description (IBusComponent *component);
188
189/**
190 * ibus_component_get_version:
191 * @component: An #IBusComponent
192 *
193 * Gets the version property in #IBusComponent. It should not be freed.
194 *
195 * Returns: version property in #IBusComponent
196 */
197const gchar *ibus_component_get_version (IBusComponent *component);
198
199/**
200 * ibus_component_get_license:
201 * @component: An #IBusComponent
202 *
203 * Gets the license property in #IBusComponent. It should not be freed.
204 *
205 * Returns: license property in #IBusComponent
206 */
207const gchar *ibus_component_get_license (IBusComponent *component);
208
209/**
210 * ibus_component_get_author:
211 * @component: An #IBusComponent
212 *
213 * Gets the author property in #IBusComponent. It should not be freed.
214 *
215 * Returns: author property in #IBusComponent
216 */
217const gchar *ibus_component_get_author (IBusComponent *component);
218
219/**
220 * ibus_component_get_homepage:
221 * @component: An #IBusComponent
222 *
223 * Gets the homepage property in #IBusComponent. It should not be freed.
224 *
225 * Returns: homepage property in #IBusComponent
226 */
227const gchar *ibus_component_get_homepage (IBusComponent *component);
228
229/**
230 * ibus_component_get_exec:
231 * @component: An #IBusComponent
232 *
233 * Gets the exec property in #IBusComponent. It should not be freed.
234 *
235 * Returns: exec property in #IBusComponent
236 */
237const gchar *ibus_component_get_exec (IBusComponent *component);
238
239/**
240 * ibus_component_get_textdomain:
241 * @component: An #IBusComponent
242 *
243 * Gets the textdomain property in #IBusComponent. It should not be freed.
244 *
245 * Returns: textdomain property in #IBusComponent
246 */
247const gchar *ibus_component_get_textdomain (IBusComponent *component);
248
249/**
250 * ibus_component_add_observed_path:
251 * @component: An #IBusComponent
252 * @path: Observed path to be added.
253 * @access_fs: %TRUE for filling the file status; %FALSE otherwise.
254 *
255 * Add an observed path to #IBusComponent.
256 */
257void ibus_component_add_observed_path
258 (IBusComponent *component,
259 const gchar *path,
260 gboolean access_fs);
261
262/**
263 * ibus_component_add_engine:
264 * @component: An #IBusComponent
265 * @engine: A description of an engine.
266 *
267 * Add an engine to #IBusComponent according to the description in @engine.
268 */
269void ibus_component_add_engine (IBusComponent *component,
270 IBusEngineDesc *engine);
271
272/**
273 * ibus_component_get_engines:
274 * @component: An #IBusComponent.
275 *
276 * Gets the engines of this component.
277 *
278 * Returns: (transfer container) (element-type IBusEngineDesc):
279 * A newly allocated GList that contains engines.
280 */
281GList *ibus_component_get_engines (IBusComponent *component);
282
283/**
284 * ibus_component_output:
285 * @component: An #IBusComponent.
286 * @output: GString that holds the result.
287 * @indent: level of indent.
288 *
289 * Output #IBusComponent as an XML-formatted string.
290 * The output string can be then shown on the screen or written to file.
291 */
292void ibus_component_output (IBusComponent *component,
293 GString *output,
294 gint indent);
295
296/**
297 * ibus_component_output_engines:
298 * @component: An #IBusComponent.
299 * @output: GString that holds the result.
300 * @indent: level of indent.
301 *
302 * Output engine description as an XML-formatted string.
303 * The output string can be then shown on the screen or written to file.
304 */
305void ibus_component_output_engines (IBusComponent *component,
306 GString *output,
307 gint indent);
308
309/**
310 * ibus_component_check_modification:
311 * @component: An #IBusComponent.
312 *
313 * Check whether the observed paths of component is modified.
314 *
315 * Returns: %TRUE if at least one of the observed paths is modified;
316 * %FALSE otherwise.
317 */
318gboolean ibus_component_check_modification
319 (IBusComponent *component);
320
321/**
322 * ibus_component_get_observed_paths:
323 * @component: An #IBusComponent.
324 *
325 * Gets the observed paths of this component.
326 *
327 * Returns: (transfer container) (element-type IBusObservedPath): A
328 * newly allocated GList that contains observed paths.
329 */
330GList *ibus_component_get_observed_paths
331 (IBusComponent *component);
332
333G_END_DECLS
334#endif
335
336