src/ibuscomponent.h

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