/*
* Copyright (C) 2002-2006 Sergey V. Udaltsov <svu@gnome.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#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;
typedef struct _XklState XklState;
#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(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), XKL_TYPE_ENGINE, XklEngineClass))
/**
* XklEngineStateChange:
* @GROUP_CHANGED: Group was changed
* @INDICATORS_CHANGED: Indicators were changed
*
* The type of the keyboard state change
*/
typedef enum {
GROUP_CHANGED,
INDICATORS_CHANGED
} XklEngineStateChange;
/**
* XklEngineFeatures:
* @XKLF_CAN_TOGGLE_INDICATORS: Backend allows to toggls indicators on/off
* @XKLF_CAN_OUTPUT_CONFIG_AS_ASCII: Backend allows writing ASCII representation of the configuration
* @XKLF_CAN_OUTPUT_CONFIG_AS_BINARY: Backend allows writing binary representation of the configuration
* @XKLF_MULTIPLE_LAYOUTS_SUPPORTED: Backend supports multiple layouts
* @XKLF_REQUIRES_MANUAL_LAYOUT_MANAGEMENT: Backend requires manual configuration, some daemon should do
* xkl_start_listen(engine,XKLL_MANAGE_LAYOUTS);
* @XKLF_DEVICE_DISCOVERY: Backend supports device discovery, can notify
*
* A set of flags used to indicate the capabilities of the active backend
*
*/
typedef enum { /*< flags >*/
XKLF_CAN_TOGGLE_INDICATORS = 1 << 0,
XKLF_CAN_OUTPUT_CONFIG_AS_ASCII = 1 << 1,
XKLF_CAN_OUTPUT_CONFIG_AS_BINARY = 1 << 2,
XKLF_MULTIPLE_LAYOUTS_SUPPORTED = 1 << 3,
XKLF_REQUIRES_MANUAL_LAYOUT_MANAGEMENT = 1 << 4,
XKLF_DEVICE_DISCOVERY = 1 << 5
} XklEngineFeatures;
/**
* _XklState:
* @group: selected group
* @indicators: set of active indicators
*
* XKB state. Can be global or per-window
*/
struct _XklState {
gint32 group;
guint32 indicators;
};
#define XKL_TYPE_STATE (xkl_state_get_type())
GType xkl_state_get_type (void) G_GNUC_CONST;
/**
* _XklEngine:
* @parent: The superclass object
*
* The main Xklavier engine class
*/
struct _XklEngine {
GObject parent;
/*< private >*/
XklEnginePrivate *priv;
};
/**
* _XklEngineClass:
* @parent_class: The superclass
*
* The XklEngine class, derived from GObject
*/
struct _XklEngineClass {
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);
/**
* XklEngine::new_device_notify:
* @engine: the object on which the signal is emitted
*
* Used for notifying application of the new keyboard attached
*/
void (*new_device_notify) (XklEngine * engine);
};
/**
* 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: (transfer none): 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);
/**
* XklEngineListenModes:
* @XKLL_MANAGE_WINDOW_STATES: The listener process should handle the per-window states
* and all the related activity
* @XKLL_TRACK_KEYBOARD_STATE: Just track the state and pass it to the application above.
* @XKLL_MANAGE_LAYOUTS: The listener process should help backend to maintain the configuration
* (manually switch layouts etc).
*
* The listener action modes:
*/
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
* @flags: any combination of XKLL_* constants
*
* Stops listening for XKB-related events
* Returns: 0
*/
extern gint xkl_engine_stop_listen(XklEngine * engine,
guint flags);
/**
* 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: (skip): 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: (transfer none): 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: (transfer none): 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: (transfer none): 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_set_default_group:
* @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_set_default_group(XklEngine * engine,
gint group);
/**
* xkl_engine_get_default_group:
* @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_get_default_group(XklEngine * engine);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif