diff options
Diffstat (limited to 'libxklavier/xkl_engine.h')
| -rw-r--r-- | libxklavier/xkl_engine.h | 547 |
1 files changed, 547 insertions, 0 deletions
diff --git a/libxklavier/xkl_engine.h b/libxklavier/xkl_engine.h new file mode 100644 index 0000000..4143059 --- /dev/null +++ b/libxklavier/xkl_engine.h @@ -0,0 +1,547 @@ +#ifndef __XKL_ENGINE_H__ +#define __XKL_ENGINE_H__ + +#include <X11/Xlib.h> + +#include <glib-object.h> + +#ifdef __cplusplus +extern "C" { +#endif + + typedef struct _XklEngine XklEngine; + typedef struct _XklEnginePrivate XklEnginePrivate; + typedef struct _XklEngineClass XklEngineClass; + +#define XKL_TYPE_ENGINE (xkl_engine_get_type ()) +#define XKL_ENGINE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), XKL_TYPE_ENGINE, XklEngine)) +#define XKL_ENGINE_CLASS(obj) (G_TYPE_CHECK_CLASS_CAST ((obj), XKL_TYPE_ENGINE, XklEngineClass)) +#define XKL_IS_ENGINE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), XKL_TYPE_ENGINE)) +#define XKL_IS_ENGINE_CLASS(obj) (G_TYPE_CHECK_CLASS_TYPE ((obj), XKL_TYPE_ENGINE)) +#define XKL_ENGINE_GET_CLASS (G_TYPE_INSTANCE_GET_CLASS ((obj), XKL_TYPE_ENGINE, XklEngineClass)) + +/** + * The type of the keyboard state change + * GroupChanged: Group was changed + * IndicatorsChanged: Indicators were changed + */ + typedef enum { + GROUP_CHANGED, + INDICATORS_CHANGED + } XklEngineStateChange; + +/** + * A set of flags used to indicate the capabilities of the active backend + * CanToggleIndicators: Backend allows to toggls indicators on/off + * CanOutputConfigAsASCII: Backend allows writing ASCII representation of the configuration + * CanOutputConfigAsBinary: Backend allows writing binary representation of the configuration + * MultipleLayoutsSupported: Backend supports multiple layouts + * RequiresManualLayoutManagement: Backend requires manual configuration, some daemon should do + * xkl_start_listen(engine,XKLL_MANAGE_LAYOUTS); + */ + typedef enum { + XKLF_CAN_TOGGLE_INDICATORS = 0x01, + XKLF_CAN_OUTPUT_CONFIG_AS_ASCII = 0x02, + XKLF_CAN_OUTPUT_CONFIG_AS_BINARY = 0x04, + XKLF_MULTIPLE_LAYOUTS_SUPPORTED = 0x08, + XKLF_REQUIRES_MANUAL_LAYOUT_MANAGEMENT = 0x10, + } XklEngineFeatures; + +/** + * XKB state. Can be global or per-window + */ + typedef struct { +/** + * selected group + */ + gint32 group; +/** + * set of active indicators + */ + guint32 indicators; + } XklState; + +/** + * The main Xklavier engine class + */ + struct _XklEngine { +/** + * The superclass object + */ + GObject parent; +/** + * Private data + */ + XklEnginePrivate *priv; + }; + +/** + * The XklEngine class, derived from GObject + */ + struct _XklEngineClass { +/** + * The superclass + */ + GObjectClass parent_class; + +/** + * XklEngine::config-notify: + * @engine: the object on which the signal is emitted + * + * Used for notifying application of the XKB configuration change. + */ + void (*config_notify) (XklEngine * engine); + +/** + * XklEngine::new_window_notify: + * @engine: the object on which the signal is emitted + * @win: new window + * @parent: new window's parent + * + * Used for notifying application of new window creation (actually, + * registration). + * + * Returns: the initial group id for the window (-1 to use the default value) + */ + gint(*new_window_notify) (XklEngine * engine, Window win, + Window parent); +/** + * XklEngine::state_notify + * @engine: the object on which the signal is emitted + * @change_type: mask of changes + * @group: new group + * @restore: whether this state is restored from + * saved state of set as new. + * + * Used for notifying application of the window state change. + */ + void (*state_notify) (XklEngine * engine, + XklEngineStateChange change_type, + gint group, gboolean restore); + + }; + + +/** + * xkl_engine_get_type: + * + * Get type info for XklEngine + * + * Returns: GType for XklEngine + */ + extern GType xkl_engine_get_type(void); + + +/** + * xkl_engine_get_instance: + * @display: the X display used by the application + * + * Get the instance of the XklEngine. Within a process, there is always once instance. + * + * Returns: the singleton instance + */ + extern XklEngine *xkl_engine_get_instance(Display * display); + + +/** + * xkl_engine_get_backend_name: + * @engine: the engine + * + * What kind of backend is used + * + * Returns: some string id of the backend + */ + extern const gchar *xkl_engine_get_backend_name(XklEngine * + engine); + +/** + * xkl_engine_get_features: + * @engine: the engine + * + * Provides information regarding available backend features + * (combination of XKLF_* constants) + * + * Returns: ORed XKLF_* constants + */ + extern guint xkl_engine_get_features(XklEngine * engine); + +/** + * xkl_engine_get_max_num_groups: + * @engine: the engine + * + * Provides the information on maximum number of simultaneously supported + * groups (layouts) + * + * Returns: maximum number of the groups in configuration, + * 0 if no restrictions. + */ + extern guint xkl_engine_get_max_num_groups(XklEngine * engine); + +/** + * The listener action modes: + * ManageWindowStates: The listener process should handle the per-window states + * and all the related activity + * TrackKeyboardState: Just track the state and pass it to the application above. + * ManageLayouts: The listener process should help backend to maintain the configuration + * (manually switch layouts etc). + */ + typedef enum { + XKLL_MANAGE_WINDOW_STATES = 0x01, + XKLL_TRACK_KEYBOARD_STATE = 0x02, + XKLL_MANAGE_LAYOUTS = 0x04 + } XklEngineListenModes; + +/** + * xkl_engine_start_listen: + * @engine: the engine + * @flags: any combination of XKLL_* constants + * + * Starts listening for XKB-related events + * + * Returns: 0 + */ + extern gint xkl_engine_start_listen(XklEngine * engine, + guint flags); + +/** + * xkl_engine_stop_listen: + * @engine: the engine + * + * Stops listening for XKB-related events + * Returns: 0 + */ + extern gint xkl_engine_stop_listen(XklEngine * engine); + +/** + * xkl_engine_pause_listen: + * @engine: the engine + * + * Temporary pauses listening for XKB-related events + * + * Returns: 0 + */ + extern gint xkl_engine_pause_listen(XklEngine * engine); + +/** + * xkl_engine_resume_listen: + * @engine: the engine + * + * Resumes listening for XKB-related events + * + * Returns: 0 + */ + extern gint xkl_engine_resume_listen(XklEngine * engine); + +/** + * xkl_engine_grab_key: + * @engine: the engine + * @keycode: keycode + * @modifiers: bitmask of modifiers + * + * Grabs some key + * + * Returns: TRUE on success + */ + extern gboolean xkl_engine_grab_key(XklEngine * engine, + gint keycode, guint modifiers); + +/** + * xkl_engine_ungrab_key: + * @engine: the engine + * @keycode: keycode + * @modifiers: bitmask of modifiers + * + * Ungrabs some key + * + * Returns: TRUE on success + */ + extern gboolean xkl_engine_ungrab_key(XklEngine * engine, + gint keycode, + guint modifiers); + +/** + * xkl_engine_filter_events: + * @engine: the engine + * @evt: delivered X event + * + * Processes X events. Should be included into the main event cycle of an + * application. One of the most important functions. + * + * Returns: 0 if the event it processed - 1 otherwise + */ + extern gint xkl_engine_filter_events(XklEngine * engine, + XEvent * evt); + +/** + * xkl_engine_allow_one_switch_to_secondary_group: + * @engine: the engine + * + * Allows to switch (once) to the secondary group + * + */ + extern void + xkl_engine_allow_one_switch_to_secondary_group(XklEngine * + engine); + +/** + * xkl_engine_get_current_window: + * @engine: the engine + * + * Returns: currently focused window + */ + extern Window xkl_engine_get_current_window(XklEngine * engine); + +/** + * xkl_engine_get_current_state: + * @engine: the engine + * + * Returns: current state of the keyboard. + * Returned value is a statically allocated buffer, should not be freed. + */ + extern XklState *xkl_engine_get_current_state(XklEngine * engine); + +/** + * xkl_engine_get_window_title: + * @engine: the engine + * @win: X window + * + * Returns: the window title of some window or NULL. + * If not NULL, it should be freed with XFree + */ + extern gchar *xkl_engine_get_window_title(XklEngine * engine, + Window win); + +/** + * xkl_engine_get_state: + * @engine: the engine + * @win: window to query + * @state_out: structure to store the state + * + * Finds the state for a given window (for its "App window"). + * + * Returns: TRUE on success, otherwise FALSE + * (the error message can be obtained using xkl_GetLastError). + */ + extern gboolean xkl_engine_get_state(XklEngine * engine, + Window win, + XklState * state_out); + +/** + * xkl_engine_delete_state: + * @engine: the engine + * @win: target window + * + * Drops the state of a given window (of its "App window"). + */ + extern void xkl_engine_delete_state(XklEngine * engine, + Window win); + +/** + * xkl_engine_save_state: + * @engine: the engine + * @win: target window + * @state: new state of the window + * + * Stores ths state for a given window + */ + extern void xkl_engine_save_state(XklEngine * engine, Window win, + XklState * state); + +/** + * xkl_engine_set_window_transparent: + * @engine: the engine + * @win: window do set the flag for. + * @transparent: if true, the windows is transparent. + * + * Sets the "transparent" flag. It means focus switching onto + * this window will never change the state. + */ + extern void xkl_engine_set_window_transparent(XklEngine * engine, + Window win, + gboolean + transparent); + +/** + * xkl_engine_is_window_transparent: + * @engine: the engine + * @win: window to get the transparent flag from. + * + * Returns: TRUE if the window is "transparent" + */ + extern gboolean xkl_engine_is_window_transparent(XklEngine * + engine, + Window win); + +/** + * xkl_engine_is_window_from_same_toplevel_window: + * @engine: the engine + * @win1: first window + * @win2: second window + * + * Checks whether 2 windows have the same topmost window + * + * Returns: TRUE is windows are in the same application + */ + extern gboolean + xkl_engine_is_window_from_same_toplevel_window(XklEngine * + engine, + Window win1, + Window win2); + +/** + * xkl_engine_get_num_groups: + * @engine: the engine + * + * Returns: the total number of groups in the current configuration + * (keyboard) + */ + extern guint xkl_engine_get_num_groups(XklEngine * engine); + +/** + * xkl_engine_get_groups_names: + * @engine: the engine + * + * Returns: the array of group names for the current XKB configuration + * (keyboard). + * This array is static, should not be freed + */ + extern const gchar **xkl_engine_get_groups_names(XklEngine * + engine); + +/** + * xkl_engine_get_indicators_names: + * @engine: the engine + * + * Returns: the array of indicator names for the current XKB configuration + * (keyboard). + * This array is static, should not be freed + */ + extern const gchar **xkl_engine_get_indicators_names(XklEngine * + engine); + +/** + * xkl_engine_get_next_group: + * @engine: the engine + * + * Calculates next group id. Does not change the state of anything. + * + * Returns: next group id + */ + extern gint xkl_engine_get_next_group(XklEngine * engine); + +/** + * xkl_engine_get_prev_group: + * @engine: the engine + * + * Calculates prev group id. Does not change the state of anything. + * + * Returns: prev group id + */ + extern gint xkl_engine_get_prev_group(XklEngine * engine); + +/** + * xkl_engine_get_current_window_group: + * @engine: the engine + * + * Returns: saved group id of the current window. + */ + extern gint xkl_engine_get_current_window_group(XklEngine * + engine); + +/** + * xkl_engine_lock_group: + * @engine: the engine + * @group: group number for locking + * + * Locks the group. Can be used after xkl_GetXXXGroup functions + */ + extern void xkl_engine_lock_group(XklEngine * engine, gint group); + +/** + * xkl_engine_set_group_per_toplevel_window: + * @engine: the engine + * @is_global: new parameter value + * + * Sets the configuration parameter: group per application + */ + extern void xkl_engine_set_group_per_toplevel_window(XklEngine * + engine, + gboolean + is_global); + +/** + * xkl_engine_is_group_per_toplevel_window: + * @engine: the engine + * + * Returns: the value of the parameter: group per application + */ + extern gboolean xkl_engine_is_group_per_toplevel_window(XklEngine * + engine); + +/** + * xkl_engine_set_indicators_handling: + * @engine: the engine + * @whether_handle: new parameter value + * + * Sets the configuration parameter: perform indicators handling + */ + extern void xkl_engine_set_indicators_handling(XklEngine * engine, + gboolean + whether_handle); + +/** + * xkl_engine_get_indicators_handling: + * @engine: the engine + * + * Returns: the value of the parameter: perform indicator handling + */ + extern gboolean xkl_engine_get_indicators_handling(XklEngine * + engine); + +/** + * xkl_engine_set_secondary_groups_mask: + * @engine: the engine + * @mask: new group mask + * + * Sets the secondary groups (one bit per group). + * Secondary groups require explicit "allowance" for switching + */ + extern void xkl_engine_set_secondary_groups_mask(XklEngine * + engine, + guint mask); + +/** + * xkl_engine_get_secondary_groups_mask: + * @engine: the engine + * + * Returns: the secondary group mask + */ + extern guint xkl_engine_get_secondary_groups_mask(XklEngine * + engine); + +/** + * xkl_engine_group_set_default: + * @engine: the engine + * @group: default group + * + * Configures the default group set on window creation. + * If -1, no default group is used + */ + extern void xkl_engine_group_set_default(XklEngine * engine, + gint group); + +/** + * xkl_engine_group_get_default: + * @engine: the engine + * + * Returns the default group set on window creation + * If -1, no default group is used + * + * Returns: the default group + */ + extern gint xkl_engine_group_get_default(XklEngine * engine); + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif |