src/ibusfactory.h

   1 /* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
   2 /* vim:set et sts=4: */
   3 /* ibus - 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: ibusfactory
  29  * @short_description: Factory for creating engine instances.
  30  * @title: IBusFactory
  31  * @stability: Stable
  32  *
  33  * An IBusFactory is an #IBusService that creates input method engine (IME) instance.
  34  * It provides CreateEngine remote method, which creates an IME instance by name,
  35  * and returns the D-Bus object path to IBus daemon.
  36  *
  37  * @see_also: #IBusEngine
  38  *
  39  */
  40 #ifndef __IBUS_FACTORY_H_
  41 #define __IBUS_FACTORY_H_
  42
  43 #include "ibusservice.h"
  44 #include "ibusserializable.h"
  45 #include "ibusengine.h"
  46
  47 G_BEGIN_DECLS
  48
  49 /*
  50  * Type macros.
  51  */
  52
  53 /* define GOBJECT macros */
  54 /**
  55  * IBUS_TYPE_FACTORY:
  56  *
  57  * Return GType of IBus factory.
  58  */
  59 #define IBUS_TYPE_FACTORY               \
  60     (ibus_factory_get_type ())
  61
  62 /**
  63  * IBUS_FACTORY:
  64  * @obj: An object which is subject to casting.
  65  *
  66  * Casts an IBUS_FACTORY or derived pointer into a (IBusFactory*) pointer.
  67  * Depending on the current debugging level, this function may invoke
  68  * certain runtime checks to identify invalid casts.
  69  */
  70 #define IBUS_FACTORY(obj)               \
  71     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_FACTORY, IBusFactory))
  72
  73 /**
  74  * IBUS_FACTORY_CLASS:
  75  * @klass: A class to be casted.
  76  *
  77  * Casts a derived IBusFactoryClass structure into a IBusFactoryClass structure.
  78  */
  79 #define IBUS_FACTORY_CLASS(klass)       \
  80     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_FACTORY, IBusFactoryClass))
  81
  82 /**
  83  * IBUS_IS_FACTORY:
  84  * @obj: Instance to check for being a IBUS_FACTORY.
  85  *
  86  * Checks whether a valid GTypeInstance pointer is of type IBUS_FACTORY.
  87  */
  88 #define IBUS_IS_FACTORY(obj)            \
  89     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_FACTORY))
  90
  91 /**
  92  * IBUS_IS_FACTORY_CLASS:
  93  * @klass: A class to be checked.
  94  *
  95  * Checks whether class "is a" valid IBusFactoryClass structure of type IBUS_FACTORY or derived.
  96  */
  97 #define IBUS_IS_FACTORY_CLASS(klass)    \
  98     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_FACTORY))
  99
 100 /**
 101  * IBUS_FACTORY_GET_CLASS:
 102  * @obj: An object.
 103  *
 104  * Get the class of a given object and cast the class to IBusFactoryClass.
 105  */
 106 #define IBUS_FACTORY_GET_CLASS(obj)     \
 107     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_FACTORY, IBusFactoryClass))
 108
 109 typedef struct _IBusFactory IBusFactory;
 110 typedef struct _IBusFactoryClass IBusFactoryClass;
 111 typedef struct _IBusFactoryPrivate IBusFactoryPrivate;
 112
 113 /**
 114  * IBusFactory:
 115  *
 116  * An opaque data type representing an IBusFactory.
 117  */
 118 struct _IBusFactory {
 119     /*< private >*/
 120     IBusService parent;
 121     IBusFactoryPrivate *priv;
 122
 123     /* instance members */
 124 };
 125
 126 struct _IBusFactoryClass {
 127     /*< private >*/
 128     IBusServiceClass parent;
 129
 130     /*< public >*/
 131     /* signals */
 132     IBusEngine *
 133                 (* create_engine)
 134                                     (IBusFactory    *factory,
 135                                      const gchar    *engine_name);
 136
 137     /*< private >*/
 138     /* padding */
 139     gpointer pdummy[7];
 140 };
 141
 142 /**
 143  * ibus_factory_info_get_type:
 144  * @returns: GType of IBus factory information.
 145  *
 146  * Return GType of IBus factory information.
 147  */
 148 GType            ibus_factory_get_type          (void);
 149
 150 /**
 151  * ibus_factory_new:
 152  * @connection: An GDBusConnection.
 153  * @returns: A newly allocated IBusFactory.
 154  *
 155  * New an IBusFactory.
 156  */
 157 IBusFactory     *ibus_factory_new               (GDBusConnection *connection);
 158
 159 /**
 160  * ibus_factory_add_engine:
 161  * @factory: An IBusFactory.
 162  * @engine_name: Name of an engine.
 163  * @engine_type: GType of an engine.
 164  *
 165  * Add an engine to the factory.
 166  */
 167 void             ibus_factory_add_engine        (IBusFactory    *factory,
 168                                                  const gchar    *engine_name,
 169                                                  GType           engine_type);
 170
 171 /**
 172  * ibus_factory_create_engine:
 173  * @factory: An #IBusFactory.
 174  * @engine_name: Name of an engine.
 175  * @returns: (transfer full): #IBusEngine with @engine_name.
 176  *
 177  * Create an #IBusEngine with @engine_name.
 178  */
 179 IBusEngine      *ibus_factory_create_engine     (IBusFactory    *factory,
 180                                                  const gchar    *engine_name);
 181
 182 G_END_DECLS
 183 #endif
 184