src/ibusshare.h

   1 /* vim:set et sts=4: */
   2 /* ibus - The Input Bus
   3  * Copyright (C) 2008-2009 Peng Huang <shawn.p.huang@gmail.com>
   4  * Copyright (C) 2008-2009 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21 /**
  22  * SECTION: ibusshare
  23  * @short_description: Shared utility functions and definition.
  24  * @stability: Stable
  25  *
  26  * This file defines some utility functions and definition
  27  * which are shared among ibus component and services.
  28  */
  29
  30 #ifndef __IBUS_SHARE_H_
  31 #define __IBUS_SHARE_H_
  32
  33 #include <glib.h>
  34
  35 /**
  36  * IBUS_SERVICE_IBUS:
  37  *
  38  * Address of IBus service.
  39  */
  40 #define IBUS_SERVICE_IBUS       "org.freedesktop.IBus"
  41
  42 /**
  43  * IBUS_SERVICE_PANEL:
  44  *
  45  * Address of IBus panel service.
  46  */
  47 #define IBUS_SERVICE_PANEL      "org.freedesktop.IBus.Panel"
  48
  49 /**
  50  * IBUS_SERVICE_CONFIG:
  51  *
  52  * Address of IBus config service.
  53  */
  54 #define IBUS_SERVICE_CONFIG     "org.freedesktop.IBus.Config"
  55
  56 /**
  57  * IBUS_SERVICE_NOTIFICATIONS:
  58  *
  59  * Address of IBus notification service.
  60  */
  61 #define IBUS_SERVICE_NOTIFICATIONS    "org.freedesktop.IBus.Notifications"
  62
  63 /**
  64  * IBUS_PATH_IBUS:
  65  *
  66  * D-Bus path for IBus
  67  */
  68 #define IBUS_PATH_IBUS          "/org/freedesktop/IBus"
  69
  70 /**
  71  * IBUS_PATH_FACTORY:
  72  *
  73  * D-Bus path for IBus factory.
  74  */
  75 #define IBUS_PATH_FACTORY       "/org/freedesktop/IBus/Factory"
  76
  77 /**
  78  * IBUS_PATH_PANEL:
  79  *
  80  * D-Bus path for IBus panel.
  81  */
  82 #define IBUS_PATH_PANEL         "/org/freedesktop/IBus/Panel"
  83
  84 /**
  85  * IBUS_PATH_CONFIG:
  86  *
  87  * D-Bus path for IBus config.
  88  */
  89 #define IBUS_PATH_CONFIG        "/org/freedesktop/IBus/Config"
  90
  91 /**
  92  * IBUS_PATH_NOTIFICATIONS:
  93  *
  94  * D-Bus path for IBus notifications.
  95  */
  96 #define IBUS_PATH_NOTIFICATIONS "/org/freedesktop/IBus/Notifications"
  97
  98 /**
  99  * IBUS_PATH_INPUT_CONTEXT:
 100  *
 101  * Template of D-Bus path for IBus input context.
 102  */
 103 #define IBUS_PATH_INPUT_CONTEXT "/org/freedesktop/IBus/InputContext_%d"
 104
 105 /**
 106  * IBUS_INTERFACE_IBUS:
 107  *
 108  * D-Bus interface for IBus.
 109  */
 110 #define IBUS_INTERFACE_IBUS     "org.freedesktop.IBus"
 111
 112 /**
 113  * IBUS_INTERFACE_INPUT_CONTEXT:
 114  *
 115  * D-Bus interface for IBus input context.
 116  */
 117 #define IBUS_INTERFACE_INPUT_CONTEXT \
 118                                 "org.freedesktop.IBus.InputContext"
 119
 120 /**
 121  * IBUS_INTERFACE_FACTORY:
 122  *
 123  * D-Bus interface for IBus factory.
 124  */
 125 #define IBUS_INTERFACE_FACTORY  "org.freedesktop.IBus.Factory"
 126
 127 /**
 128  * IBUS_INTERFACE_ENGINE:
 129  *
 130  * D-Bus interface for IBus engine.
 131  */
 132 #define IBUS_INTERFACE_ENGINE   "org.freedesktop.IBus.Engine"
 133
 134 /**
 135  * IBUS_INTERFACE_PANEL:
 136  *
 137  * D-Bus interface for IBus panel.
 138  */
 139 #define IBUS_INTERFACE_PANEL    "org.freedesktop.IBus.Panel"
 140
 141 /**
 142  * IBUS_INTERFACE_CONFIG:
 143  *
 144  * D-Bus interface for IBus config.
 145  */
 146 #define IBUS_INTERFACE_CONFIG   "org.freedesktop.IBus.Config"
 147
 148 /**
 149  * IBUS_INTERFACE_NOTIFICATIONS:
 150  *
 151  * D-Bus interface for IBus notifications.
 152  */
 153 #define IBUS_INTERFACE_NOTIFICATIONS    "org.freedesktop.IBus.Notifications"
 154
 155 G_BEGIN_DECLS
 156
 157 /**
 158  * ibus_get_local_machine_id:
 159  * @returns: A newly allocated string that shows the UUID of the machine.
 160  *
 161  * Obtains the machine UUID of the machine this process is running on.
 162  */
 163 const gchar     *ibus_get_local_machine_id
 164                                         (void);
 165
 166 /**
 167  * ibus_set_display:
 168  * @display: Display address, as in DISPLAY environment for X.
 169  *
 170  * Set the display address.
 171  */
 172 void             ibus_set_display       (const gchar    *display);
 173
 174 /**
 175  * ibus_get_address:
 176  * @returns: D-Bus address of IBus. %NULL for not found.
 177  *
 178  * Return the D-Bus address of IBus.
 179  * It will find the address from following source:
 180  * <orderedlist>
 181  *    <listitem><para>Environment variable IBUS_ADDRESS</para></listitem>
 182  *    <listitem><para>Socket file under ~/.config/ibus/bus/</para></listitem>
 183  * </orderedlist>
 184  *
 185  * @see_also: ibus_write_address().
 186  */
 187 const gchar     *ibus_get_address       (void);
 188
 189 /**
 190  * ibus_write_address:
 191  * @address: D-Bus address of IBus.
 192  *
 193  * Write D-Bus address to socket file.
 194  *
 195  * @see_also: ibus_get_address().
 196  */
 197 void             ibus_write_address     (const gchar    *address);
 198
 199 /**
 200  * ibus_get_user_name:
 201  * @returns: A newly allocated string that stores current user name.
 202  *
 203  * Get the current user name.
 204  * It is determined by:
 205  * <orderedlist>
 206  *    <listitem><para>getlogin()</para></listitem>
 207  *    <listitem><para>Environment variable SUDO_USER</para></listitem>
 208  *    <listitem><para>Environment variable USERHELPER_UID</para></listitem>
 209  *    <listitem><para>Environment variable USERNAME</para></listitem>
 210  *    <listitem><para>Environment variable LOGNAME</para></listitem>
 211  *    <listitem><para>Environment variable USER</para></listitem>
 212  *    <listitem><para>Environment variable LNAME</para></listitem>
 213  * </orderedlist>
 214  */
 215 const gchar     *ibus_get_user_name     (void);
 216
 217 /**
 218  * ibus_get_daemon_uid:
 219  * @returns: UID of ibus-daemon; or 0 if UID is not available.
 220  *
 221  * Get UID of ibus-daemon.
 222  */
 223 glong            ibus_get_daemon_uid    (void);
 224
 225 /**
 226  * ibus_get_socket_path:
 227  * @returns: A newly allocated string that stores the path of socket file.
 228  *
 229  * Get the path of socket file.
 230  */
 231 const gchar     *ibus_get_socket_path   (void);
 232
 233 /**
 234  * ibus_keyval_name:
 235  * @keyval: Key symbol.
 236  * @returns: Corresponding key name. %NULL if no such key symbol.
 237  *
 238  * Return the name of a key symbol.
 239  *
 240  * Note that the returned string is used internally, so don't free it.
 241  */
 242 const gchar     *ibus_keyval_name       (guint           keyval);
 243
 244 /**
 245  * ibus_keyval_from_name:
 246  * @keyval_name: Key name in #gdk_keys_by_name.
 247  * @returns: Corresponding key symbol.
 248  *
 249  * Return the key symbol that associate with the key name.
 250  */
 251 guint            ibus_keyval_from_name  (const gchar    *keyval_name);
 252
 253 /**
 254  * ibus_free_strv:
 255  * @strv: List of strings.
 256  *
 257  * Free a list of strings.
 258  */
 259 void             ibus_free_strv         (gchar          **strv);
 260
 261 /**
 262  * ibus_key_event_to_string:
 263  * @keyval: Key symbol.
 264  * @modifiers: Modifiers such as Ctrl or Shift.
 265  * @returns: The name of a key symbol and modifier.
 266  *
 267  * Return the name of a key symbol and modifiers.
 268  *
 269  * For example, if press ctrl, shift, and enter, then this function returns:
 270  * Shift+Control+enter.
 271  */
 272 const gchar     *ibus_key_event_to_string
 273                                         (guint           keyval,
 274                                          guint           modifiers);
 275
 276 /**
 277  * ibus_key_event_from_string:
 278  * @string: Key event string.
 279  * @keyval: Variable that hold key symbol result.
 280  * @modifiers: Variable that hold modifiers result.
 281  * @returns: TRUE for succeed; FALSE if failed.
 282  *
 283  * Parse key event string and return key symbol and modifiers.
 284  */
 285 gboolean         ibus_key_event_from_string
 286                                         (const gchar    *string,
 287                                          guint          *keyval,
 288                                          guint          *modifiers);
 289
 290 /**
 291  * ibus_init:
 292  *
 293  * Init the ibus types.
 294  *
 295  * It is actually a wrapper of g_type_init().
 296  */
 297 void             ibus_init              (void);
 298
 299 /**
 300  * ibus_main:
 301  *
 302  * Runs an IBus main loop until ibus_quit() is called in the loop.
 303  *
 304  * @see_also: ibus_quit().
 305  */
 306 void             ibus_main              (void);
 307
 308 /**
 309  * ibus_quit:
 310  *
 311  * Stops an IBus from running.
 312  *
 313  * Any calls to ibus_quit() for the loop will return.
 314  * @see_also: ibus_main().
 315  */
 316 void             ibus_quit              (void);
 317
 318 G_END_DECLS
 319 #endif