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 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: 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  */
  98 struct _IBusEngineDesc {
  99     IBusSerializable parent;
 100     /* instance members */
 101
 102     /*< public >*/
 103     /*< private >*/
 104     IBusEngineDescPrivate *priv;
 105 };
 106
 107 struct _IBusEngineDescClass {
 108     IBusSerializableClass parent;
 109     /* class members */
 110 };
 111
 112 GType            ibus_engine_desc_get_type      (void);
 113
 114 /**
 115  * ibus_engine_desc_new:
 116  * @name: Name of the engine.
 117  * @longname: Long name of the input method engine.
 118  * @description: Input method engine description.
 119  * @language: Language (e.g. zh, jp) supported by this input method engine.
 120  * @license: License of the input method engine.
 121  * @author: Author of the input method engine.
 122  * @icon: Icon file of this engine.
 123  * @layout: Keyboard layout
 124  * @returns: A newly allocated IBusEngineDesc.
 125  *
 126  * New a IBusEngineDesc.
 127  */
 128 IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
 129                                                  const gchar    *longname,
 130                                                  const gchar    *description,
 131                                                  const gchar    *language,
 132                                                  const gchar    *license,
 133                                                  const gchar    *author,
 134                                                  const gchar    *icon,
 135                                                  const gchar    *layout);
 136
 137 /**
 138  * ibus_engine_desc_new_varargs:
 139  * @first_property_name: Name of the first property.
 140  * @Varargs: the NULL-terminated arguments of the properties and values.
 141  *
 142  * New a IBusEngineDesc.
 143  * ibus_engine_desc_new_varargs() supports the va_list format.
 144  * name property is required. e.g.
 145  * ibus_engine_desc_new_varargs("name", "ibus-foo", "language", "us", NULL)
 146  */
 147 IBusEngineDesc  *ibus_engine_desc_new_varargs   (const gchar *first_property_name,
 148                                                  ...);
 149
 150
 151 /**
 152  * ibus_engine_desc_new_from_xml_node:
 153  * @node: An XML node
 154  * @returns: A newly allocated IBusEngineDesc that contains description from
 155  * @node.
 156  *
 157  * New a IBusEngineDesc from an XML node.
 158  * <note><para>This function is called by ibus_component_new_from_file(),
 159  *  so developers normally do not need to call it directly.
 160  * </para></note>
 161  */
 162 IBusEngineDesc  *ibus_engine_desc_new_from_xml_node
 163                                                 (XMLNode        *node);
 164 /**
 165  * ibus_engine_desc_get_name:
 166  * @info: An IBusEngineDesc
 167  * @returns: name property in IBusEngineDesc
 168  *
 169  * Return the name property in IBusEngineDesc. It should not be freed.
 170  */
 171 const gchar     *ibus_engine_desc_get_name      (IBusEngineDesc *info);
 172
 173 /**
 174  * ibus_engine_desc_get_longname:
 175  * @info: An IBusEngineDesc
 176  * @returns: longname property in IBusEngineDesc
 177  *
 178  * Return the longname property in IBusEngineDesc. It should not be freed.
 179  */
 180 const gchar     *ibus_engine_desc_get_longname  (IBusEngineDesc *info);
 181
 182 /**
 183  * ibus_engine_desc_get_description:
 184  * @info: An IBusEngineDesc
 185  * @returns: description property in IBusEngineDesc
 186  *
 187  * Return the description property in IBusEngineDesc. It should not be freed.
 188  */
 189 const gchar     *ibus_engine_desc_get_description
 190                                                 (IBusEngineDesc *info);
 191
 192 /**
 193  * ibus_engine_desc_get_language:
 194  * @info: An IBusEngineDesc
 195  * @returns: language property in IBusEngineDesc
 196  *
 197  * Return the language property in IBusEngineDesc. It should not be freed.
 198  */
 199 const gchar     *ibus_engine_desc_get_language  (IBusEngineDesc *info);
 200
 201 /**
 202  * ibus_engine_desc_get_license:
 203  * @info: An IBusEngineDesc
 204  * @returns: license property in IBusEngineDesc
 205  *
 206  * Return the license property in IBusEngineDesc. It should not be freed.
 207  */
 208 const gchar     *ibus_engine_desc_get_license   (IBusEngineDesc *info);
 209
 210 /**
 211  * ibus_engine_desc_get_author:
 212  * @info: An IBusEngineDesc
 213  * @returns: author property in IBusEngineDesc
 214  *
 215  * Return the author property in IBusEngineDesc. It should not be freed.
 216  */
 217 const gchar     *ibus_engine_desc_get_author    (IBusEngineDesc *info);
 218
 219 /**
 220  * ibus_engine_desc_get_icon:
 221  * @info: An IBusEngineDesc
 222  * @returns: icon property in IBusEngineDesc
 223  *
 224  * Return the icon property in IBusEngineDesc. It should not be freed.
 225  */
 226 const gchar     *ibus_engine_desc_get_icon      (IBusEngineDesc *info);
 227
 228 /**
 229  * ibus_engine_desc_get_layout:
 230  * @info: An IBusEngineDesc
 231  * @returns: layout property in IBusEngineDesc
 232  *
 233  * Return the layout property in IBusEngineDesc. It should not be freed.
 234  */
 235 const gchar     *ibus_engine_desc_get_layout    (IBusEngineDesc *info);
 236
 237 /**
 238  * ibus_engine_desc_get_layout_variant:
 239  * @info: An IBusEngineDesc
 240  * @returns: keyboard variant property in IBusEngineDesc
 241  *
 242  * Return the keyboard variant property in IBusEngineDesc. It should not be freed.
 243  */
 244 const gchar     *ibus_engine_desc_get_layout_variant
 245                                                 (IBusEngineDesc *info);
 246
 247 /**
 248  * ibus_engine_desc_get_layout_option:
 249  * @info: An IBusEngineDesc
 250  * @returns: keyboard option property in IBusEngineDesc
 251  *
 252  * Return the keyboard option property in IBusEngineDesc. It should not be freed.
 253  */
 254 const gchar     *ibus_engine_desc_get_layout_option
 255                                                 (IBusEngineDesc *info);
 256
 257 /**
 258  * ibus_engine_desc_get_rank:
 259  * @info: An IBusEngineDesc
 260  * @returns: rank property in IBusEngineDesc
 261  *
 262  * Return the rank property in IBusEngineDesc.
 263  */
 264 guint            ibus_engine_desc_get_rank      (IBusEngineDesc *info);
 265
 266 /**
 267  * ibus_engine_desc_get_hotkeys:
 268  * @info: An IBusEngineDesc
 269  * @returns: hotkeys property in IBusEngineDesc
 270  *
 271  * Return the hotkeys property in IBusEngineDesc. It should not be freed.
 272  */
 273 const gchar     *ibus_engine_desc_get_hotkeys   (IBusEngineDesc *info);
 274
 275 /**
 276  * ibus_engine_desc_get_symbol:
 277  * @info: An IBusEngineDesc
 278  * @returns: symbol property in IBusEngineDesc
 279  *
 280  * Return the symbol property in IBusEngineDesc. It should not be freed.
 281  */
 282 const gchar     *ibus_engine_desc_get_symbol    (IBusEngineDesc *info);
 283
 284 /**
 285  * ibus_engine_desc_get_setup:
 286  * @info: An IBusEngineDesc
 287  * @returns: setup property in IBusEngineDesc
 288  *
 289  * Return the setup property in IBusEngineDesc. It should not be freed.
 290  */
 291 const gchar     *ibus_engine_desc_get_setup     (IBusEngineDesc *info);
 292
 293 /**
 294  * ibus_engine_desc_get_version:
 295  * @info: An IBusEngineDesc
 296  * @returns: version in IBusEngineDesc
 297  *
 298  * Return the version property in IBusEngineDesc. It should not be freed.
 299  */
 300 const gchar     *ibus_engine_desc_get_version   (IBusEngineDesc *info);
 301
 302 /**
 303  * ibus_engine_desc_output:
 304  * @info: An IBusEngineDesc
 305  * @output: XML-formatted Input method engine description.
 306  * @indent: Number of indent (showed as 4 spaces).
 307  *
 308  * Output XML-formatted input method engine description.
 309  * The result will be append to GString specified in @output.
 310  */
 311 void             ibus_engine_desc_output        (IBusEngineDesc *info,
 312                                                  GString        *output,
 313                                                  gint            indent);
 314 G_END_DECLS
 315 #endif