src/ibusenginedesc.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.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 /**
  28  * SECTION: ibusenginedesc
  29  * @short_description:  Input method engine description data.
  30  * @title: IBusEngineDesc
  31  * @stability: Stable
  32  *
  33  * An IBusEngineDesc stores description data of IBusEngine.
  34  * The description data can either be passed to ibus_engine_desc_new(),
  35  * or loaded from an XML node through ibus_engine_desc_new_from_xml_node()
  36  * to construct IBusEngineDesc.
  37  *
  38  * However, the recommended way to load engine description data is
  39  * using ibus_component_new_from_file() to load a component file,
  40  * which also includes engine description data.
  41  *
  42  * @see_also: #IBusComponent, #IBusEngine
  43  *
  44  */
  45
  46 #ifndef __ENGINE_DESC_H_
  47 #define __ENGINE_DESC_H_
  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
  70 G_BEGIN_DECLS
  71
  72 typedef struct _IBusEngineDesc IBusEngineDesc;
  73 typedef struct _IBusEngineDescPrivate IBusEngineDescPrivate;
  74 typedef 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  * name: Name of the engine.
  82  * longname: Long name of the input method engine.
  83  * description: Input method engine description.
  84  * language: Language (e.g. zh, jp) supported by this input method engine.
  85  * license: License of the input method engine.
  86  * author: Author of the input method engine.
  87  * icon: Icon file of this engine.
  88  * layout: Keyboard layout
  89  * layout_variant: Keyboard variant
  90  * layout_option: Keyboard option
  91  * rank: Preference rank among engines, the highest ranked IME will put in
  92  * the front.
  93  * hotkeys: One or more hotkeys for switching to this engine, separated by
  94  *  semi-colon.
  95  * setup: Exec lists of the engine setup command.
  96  * version: Version number of the input method engine.
  97  * textdomain: Domain name for dgettext()
  98  */
  99 struct _IBusEngineDesc {
 100     IBusSerializable parent;
 101     /* instance members */
 102
 103     /*< public >*/
 104     /*< private >*/
 105     IBusEngineDescPrivate *priv;
 106 };
 107
 108 struct _IBusEngineDescClass {
 109     IBusSerializableClass parent;
 110     /* class members */
 111 };
 112
 113 GType            ibus_engine_desc_get_type      (void);
 114
 115 /**
 116  * ibus_engine_desc_new:
 117  * @name: Name of the engine.
 118  * @longname: Long name of the input method engine.
 119  * @description: Input method engine description.
 120  * @language: Language (e.g. zh, jp) supported by this input method engine.
 121  * @license: License of the input method engine.
 122  * @author: Author of the input method engine.
 123  * @icon: Icon file of this engine.
 124  * @layout: Keyboard layout
 125  * @returns: A newly allocated IBusEngineDesc.
 126  *
 127  * New a IBusEngineDesc.
 128  */
 129 IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
 130                                                  const gchar    *longname,
 131                                                  const gchar    *description,
 132                                                  const gchar    *language,
 133                                                  const gchar    *license,
 134                                                  const gchar    *author,
 135                                                  const gchar    *icon,
 136                                                  const gchar    *layout);
 137
 138 /**
 139  * ibus_engine_desc_new_varargs:
 140  * @first_property_name: Name of the first property.
 141  * @Varargs: the NULL-terminated arguments of the properties and values.
 142  *
 143  * New a IBusEngineDesc.
 144  * ibus_engine_desc_new_varargs() supports the va_list format.
 145  * name property is required. e.g.
 146  * ibus_engine_desc_new_varargs("name", "ibus-foo", "language", "us", NULL)
 147  */
 148 IBusEngineDesc  *ibus_engine_desc_new_varargs   (const gchar *first_property_name,
 149                                                  ...);
 150
 151
 152 /**
 153  * ibus_engine_desc_new_from_xml_node:
 154  * @node: An XML node
 155  * @returns: A newly allocated IBusEngineDesc that contains description from
 156  * @node.
 157  *
 158  * New a IBusEngineDesc from an XML node.
 159  * <note><para>This function is called by ibus_component_new_from_file(),
 160  *  so developers normally do not need to call it directly.
 161  * </para></note>
 162  */
 163 IBusEngineDesc  *ibus_engine_desc_new_from_xml_node
 164                                                 (XMLNode        *node);
 165 /**
 166  * ibus_engine_desc_get_name:
 167  * @info: An IBusEngineDesc
 168  * @returns: name property in IBusEngineDesc
 169  *
 170  * Return the name property in IBusEngineDesc. It should not be freed.
 171  */
 172 const gchar     *ibus_engine_desc_get_name      (IBusEngineDesc *info);
 173
 174 /**
 175  * ibus_engine_desc_get_longname:
 176  * @info: An IBusEngineDesc
 177  * @returns: longname property in IBusEngineDesc
 178  *
 179  * Return the longname property in IBusEngineDesc. It should not be freed.
 180  */
 181 const gchar     *ibus_engine_desc_get_longname  (IBusEngineDesc *info);
 182
 183 /**
 184  * ibus_engine_desc_get_description:
 185  * @info: An IBusEngineDesc
 186  * @returns: description property in IBusEngineDesc
 187  *
 188  * Return the description property in IBusEngineDesc. It should not be freed.
 189  */
 190 const gchar     *ibus_engine_desc_get_description
 191                                                 (IBusEngineDesc *info);
 192
 193 /**
 194  * ibus_engine_desc_get_language:
 195  * @info: An IBusEngineDesc
 196  * @returns: language property in IBusEngineDesc
 197  *
 198  * Return the language property in IBusEngineDesc. It should not be freed.
 199  */
 200 const gchar     *ibus_engine_desc_get_language  (IBusEngineDesc *info);
 201
 202 /**
 203  * ibus_engine_desc_get_license:
 204  * @info: An IBusEngineDesc
 205  * @returns: license property in IBusEngineDesc
 206  *
 207  * Return the license property in IBusEngineDesc. It should not be freed.
 208  */
 209 const gchar     *ibus_engine_desc_get_license   (IBusEngineDesc *info);
 210
 211 /**
 212  * ibus_engine_desc_get_author:
 213  * @info: An IBusEngineDesc
 214  * @returns: author property in IBusEngineDesc
 215  *
 216  * Return the author property in IBusEngineDesc. It should not be freed.
 217  */
 218 const gchar     *ibus_engine_desc_get_author    (IBusEngineDesc *info);
 219
 220 /**
 221  * ibus_engine_desc_get_icon:
 222  * @info: An IBusEngineDesc
 223  * @returns: icon property in IBusEngineDesc
 224  *
 225  * Return the icon property in IBusEngineDesc. It should not be freed.
 226  */
 227 const gchar     *ibus_engine_desc_get_icon      (IBusEngineDesc *info);
 228
 229 /**
 230  * ibus_engine_desc_get_layout:
 231  * @info: An IBusEngineDesc
 232  * @returns: layout property in IBusEngineDesc
 233  *
 234  * Return the layout property in IBusEngineDesc. It should not be freed.
 235  */
 236 const gchar     *ibus_engine_desc_get_layout    (IBusEngineDesc *info);
 237
 238 /**
 239  * ibus_engine_desc_get_layout_variant:
 240  * @info: An IBusEngineDesc
 241  * @returns: keyboard variant property in IBusEngineDesc
 242  *
 243  * Return the keyboard variant property in IBusEngineDesc. It should not be freed.
 244  */
 245 const gchar     *ibus_engine_desc_get_layout_variant
 246                                                 (IBusEngineDesc *info);
 247
 248 /**
 249  * ibus_engine_desc_get_layout_option:
 250  * @info: An IBusEngineDesc
 251  * @returns: keyboard option property in IBusEngineDesc
 252  *
 253  * Return the keyboard option property in IBusEngineDesc. It should not be freed.
 254  */
 255 const gchar     *ibus_engine_desc_get_layout_option
 256                                                 (IBusEngineDesc *info);
 257
 258 /**
 259  * ibus_engine_desc_get_rank:
 260  * @info: An IBusEngineDesc
 261  * @returns: rank property in IBusEngineDesc
 262  *
 263  * Return the rank property in IBusEngineDesc.
 264  */
 265 guint            ibus_engine_desc_get_rank      (IBusEngineDesc *info);
 266
 267 /**
 268  * ibus_engine_desc_get_hotkeys:
 269  * @info: An IBusEngineDesc
 270  * @returns: hotkeys property in IBusEngineDesc
 271  *
 272  * Return the hotkeys property in IBusEngineDesc. It should not be freed.
 273  */
 274 const gchar     *ibus_engine_desc_get_hotkeys   (IBusEngineDesc *info);
 275
 276 /**
 277  * ibus_engine_desc_get_symbol:
 278  * @info: An IBusEngineDesc
 279  * @returns: symbol property in IBusEngineDesc
 280  *
 281  * Return the symbol property in IBusEngineDesc. It should not be freed.
 282  */
 283 const gchar     *ibus_engine_desc_get_symbol    (IBusEngineDesc *info);
 284
 285 /**
 286  * ibus_engine_desc_get_setup:
 287  * @info: An IBusEngineDesc
 288  * @returns: setup property in IBusEngineDesc
 289  *
 290  * Return the setup property in IBusEngineDesc. It should not be freed.
 291  */
 292 const gchar     *ibus_engine_desc_get_setup     (IBusEngineDesc *info);
 293
 294 /**
 295  * ibus_engine_desc_get_version:
 296  * @info: An IBusEngineDesc
 297  * @returns: version in IBusEngineDesc
 298  *
 299  * Return the version property in IBusEngineDesc. It should not be freed.
 300  */
 301 const gchar     *ibus_engine_desc_get_version   (IBusEngineDesc *info);
 302
 303 /**
 304  * ibus_engine_desc_get_textdomain:
 305  * @info: An IBusEngineDesc
 306  * @returns: textdomain in IBusEngineDesc
 307  *
 308  * Return the textdomain property in IBusEngineDesc. It should not be freed.
 309  */
 310 const gchar     *ibus_engine_desc_get_textdomain
 311                                                 (IBusEngineDesc *info);
 312
 313 /**
 314  * ibus_engine_desc_output:
 315  * @info: An IBusEngineDesc
 316  * @output: XML-formatted Input method engine description.
 317  * @indent: Number of indent (showed as 4 spaces).
 318  *
 319  * Output XML-formatted input method engine description.
 320  * The result will be append to GString specified in @output.
 321  */
 322 void             ibus_engine_desc_output        (IBusEngineDesc *info,
 323                                                  GString        *output,
 324                                                  gint            indent);
 325 G_END_DECLS
 326 #endif