src/ibushotkey.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: ibushotkey
  29  * @short_description: Hotkeys and associated events.
  30  * @stability: Stable
  31  *
  32  * An IBusHotkeyProfile associates a hotkey and an event.
  33  */
  34 #ifndef __IBUS_HOTKEY_H_
  35 #define __IBUS_HOTKEY_H_
  36
  37 #include "ibusserializable.h"
  38
  39 /*
  40  * Type macros.
  41  */
  42 /* define IBusHotkeyProfile macros */
  43 #define IBUS_TYPE_HOTKEY_PROFILE             \
  44     (ibus_hotkey_profile_get_type ())
  45 #define IBUS_HOTKEY_PROFILE(obj)             \
  46     (G_TYPE_CHECK_INSTANCE_CAST ((obj), IBUS_TYPE_HOTKEY_PROFILE, IBusHotkeyProfile))
  47 #define IBUS_HOTKEY_PROFILE_CLASS(klass)     \
  48     (G_TYPE_CHECK_CLASS_CAST ((klass), IBUS_TYPE_HOTKEY_PROFILE, IBusHotkeyProfileClass))
  49 #define IBUS_IS_HOTKEY_PROFILE(obj)          \
  50     (G_TYPE_CHECK_INSTANCE_TYPE ((obj), IBUS_TYPE_HOTKEY_PROFILE))
  51 #define IBUS_IS_HOTKEY_PROFILE_CLASS(klass)  \
  52     (G_TYPE_CHECK_CLASS_TYPE ((klass), IBUS_TYPE_HOTKEY_PROFILE))
  53 #define IBUS_HOTKEY_PROFILE_GET_CLASS(obj)   \
  54     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_HOTKEY_PROFILE, IBusHotkeyProfileClass))
  55
  56 G_BEGIN_DECLS
  57
  58 typedef struct _IBusHotkeyProfile IBusHotkeyProfile;
  59 typedef struct _IBusHotkeyProfileClass IBusHotkeyProfileClass;
  60
  61 /**
  62  * IBusHotkeyProfile:
  63  *
  64  * An opaque data type representing an IBusHotkeyProfile.
  65  */
  66 struct _IBusHotkeyProfile {
  67     IBusSerializable parent;
  68
  69     /* members */
  70 };
  71
  72 struct _IBusHotkeyProfileClass {
  73     IBusSerializableClass parent;
  74
  75     void (* trigger) (IBusHotkeyProfile *profile,
  76                       GQuark             event,
  77                       gpointer           user_data);
  78 };
  79
  80 /* hotkey profile functions */
  81 GType            ibus_hotkey_profile_get_type   (void);
  82 /**
  83  * ibus_hotkey_profile_new:
  84  * @returns: A newly allocated IBusHotkeyProfile.
  85  *
  86  * New an IBusHotkeyProfile.
  87  */
  88 IBusHotkeyProfile
  89                 *ibus_hotkey_profile_new        (void);
  90
  91 /**
  92  * ibus_hotkey_profile_add_hotkey :
  93  * @profile: An IBusHotkeyProfile.
  94  * @keyval: Keycode of the hotkey.
  95  * @modifiers: Modifiers of the hotkey.
  96  * @event: The event to be associated.
  97  * @returns: Always TRUE.
  98  *
  99  * Add a hotkey and its associated event to an IBusHotkeyProfile.
 100  */
 101 gboolean         ibus_hotkey_profile_add_hotkey (IBusHotkeyProfile  *profile,
 102                                                  guint               keyval,
 103                                                  guint               modifiers,
 104                                                  GQuark              event);
 105
 106 /**
 107  * ibus_hotkey_profile_add_hotkey_from_string:
 108  * @profile: An IBusHotkeyProfile.
 109  * @str: Key in string representation.  '+' is the separator.
 110  * @event: The event to be associated.
 111  * @returns: FALSE if @str contains invalid symbol; TRUE otherwise.
 112  *
 113  * Add a hotkey and its associated event to an IBusHotkeyProfile.
 114  * The hotkey is in string format, such like <constant>Control+Shift+A</constant>.
 115  */
 116 gboolean         ibus_hotkey_profile_add_hotkey_from_string
 117                                                 (IBusHotkeyProfile  *profile,
 118                                                  const gchar        *str,
 119                                                  GQuark              event);
 120
 121 /**
 122  * ibus_hotkey_profile_remove_hotkey:
 123  * @profile: An IBusHotkeyProfile.
 124  * @keyval: Keycode of the hotkey.
 125  * @modifiers: Modifiers of the hotkey.
 126  * @returns: FALSE if the key is not in @profile, TRUE otherwise.
 127  *
 128  * Remove the hotkey for an IBusHotkeyProfile.
 129  */
 130 gboolean         ibus_hotkey_profile_remove_hotkey
 131                                                 (IBusHotkeyProfile  *profile,
 132                                                  guint               keyval,
 133                                                  guint               modifiers);
 134
 135 /**
 136  * ibus_hotkey_profile_remove_hotkey_by_event:
 137  * @profile: An IBusHotkeyProfile.
 138  * @event: The associated event.
 139  * @returns: FALSE if no such event in @profile, TRUE otherwise.
 140  *
 141  * Remove the hotkey for an IBusHotkeyProfile by event.
 142  */
 143 gboolean         ibus_hotkey_profile_remove_hotkey_by_event
 144                                                 (IBusHotkeyProfile  *profile,
 145                                                  GQuark              event);
 146
 147 /**
 148  * ibus_hotkey_profile_filter_key_event:
 149  * @profile: An IBusHotkeyProfile.
 150  * @keyval: Keycode of the hotkey.
 151  * @modifiers: Modifiers of the hotkey.
 152  * @prev_keyval: Keycode of the hotkey.
 153  * @prev_modifiers: Modifiers of the hotkey.
 154  * @user_data: user data for signal "trigger".
 155  * @returns: 0 if releasing a hotkey and the hotkey is not in the profile ; an associated event otherwise.
 156  *
 157  * Emit a <constant>::trigger</constant> signal when a hotkey is in a profile.
 158  *
 159  * See also: ::trigger
 160  */
 161 GQuark           ibus_hotkey_profile_filter_key_event
 162                                                 (IBusHotkeyProfile  *profile,
 163                                                  guint               keyval,
 164                                                  guint               modifiers,
 165                                                  guint               prev_keyval,
 166                                                  guint               prev_modifiers,
 167                                                  gpointer            user_data);
 168
 169 /**
 170  * ibus_hotkey_profile_lookup_hotkey:
 171  * @profile: An IBusHotkeyProfile.
 172  * @keyval: Keycode of the hotkey.
 173  * @modifiers: Modifiers of the hotkey.
 174  * @returns: The event associated to the hotkey or 0 if the hotkey is not in the
 175  * profile.
 176  */
 177 GQuark           ibus_hotkey_profile_lookup_hotkey
 178                                                 (IBusHotkeyProfile  *profile,
 179                                                  guint               keyval,
 180                                                  guint               modifiers);
 181
 182 G_END_DECLS
 183 #endif