XklEngine

XklEngine

Synopsis

                    XklEnginePrivate;
enum                XklEngineStateChange;
enum                XklEngineFeatures;
                    XklState;
                    XklEngine;
XklEngine*          xkl_engine_get_instance             (Display *display);
const gchar*        xkl_engine_get_backend_name         (XklEngine *engine);
guint               xkl_engine_get_features             (XklEngine *engine);
guint               xkl_engine_get_max_num_groups       (XklEngine *engine);
enum                XklEngineListenModes;
gint                xkl_engine_start_listen             (XklEngine *engine,
                                                         guint flags);
gint                xkl_engine_stop_listen              (XklEngine *engine);
gint                xkl_engine_pause_listen             (XklEngine *engine);
gint                xkl_engine_resume_listen            (XklEngine *engine);
gboolean            xkl_engine_grab_key                 (XklEngine *engine,
                                                         gint keycode,
                                                         guint modifiers);
gboolean            xkl_engine_ungrab_key               (XklEngine *engine,
                                                         gint keycode,
                                                         guint modifiers);
gint                xkl_engine_filter_events            (XklEngine *engine,
                                                         XEvent *evt);
void                xkl_engine_allow_one_switch_to_secondary_group
                                                        (XklEngine *engine);
Window              xkl_engine_get_current_window       (XklEngine *engine);
XklState*           xkl_engine_get_current_state        (XklEngine *engine);
gchar*              xkl_engine_get_window_title         (XklEngine *engine,
                                                         Window win);
gboolean            xkl_engine_get_state                (XklEngine *engine,
                                                         Window win,
                                                         XklState *state_out);
void                xkl_engine_delete_state             (XklEngine *engine,
                                                         Window win);
void                xkl_engine_save_state               (XklEngine *engine,
                                                         Window win,
                                                         XklState *state);
void                xkl_engine_set_window_transparent   (XklEngine *engine,
                                                         Window win,
                                                         gbooleantransparent );
gboolean            xkl_engine_is_window_transparent    (XklEngine *engine,
                                                         Window win);
gboolean            xkl_engine_is_window_from_same_toplevel_window
                                                        (XklEngine *engine,
                                                         Window win1,
                                                         Window win2);
guint               xkl_engine_get_num_groups           (XklEngine *engine);
const gchar**       xkl_engine_get_groups_names         (XklEngine *engine);
const gchar**       xkl_engine_get_indicators_names     (XklEngine *engine);
gint                xkl_engine_get_next_group           (XklEngine *engine);
gint                xkl_engine_get_prev_group           (XklEngine *engine);
gint                xkl_engine_get_current_window_group (XklEngine *engine);
void                xkl_engine_lock_group               (XklEngine *engine,
                                                         gint group);
void                xkl_engine_set_group_per_toplevel_window
                                                        (XklEngine *engine,
                                                         gbooleanis_global );
gboolean            xkl_engine_is_group_per_toplevel_window
                                                        (XklEngine *engine);
void                xkl_engine_set_indicators_handling  (XklEngine *engine,
                                                         gbooleanwhether_handle );
gboolean            xkl_engine_get_indicators_handling  (XklEngine *engine);
void                xkl_engine_set_secondary_groups_mask
                                                        (XklEngine *engine,
                                                         guint mask);
guint               xkl_engine_get_secondary_groups_mask
                                                        (XklEngine *engine);
void                xkl_engine_set_default_group        (XklEngine *engine,
                                                         gint group);
gint                xkl_engine_get_default_group        (XklEngine *engine);

Object Hierarchy

  GObject
   +----XklEngine

Properties

  "backendName"              gchar*                : Read
  "default-group"            guint                 : Read
  "display"                  gpointer              : Read / Write / Construct Only
  "features"                 XklEngineFeatures     : Read
  "indicators-handling"      gboolean              : Read
  "max-num-groups"           guint                 : Read
  "num-groups"               guint                 : Read
  "secondary-groups-mask"    guint                 : Read

Signals

  "X-config-changed"                               : Run Last
  "X-state-changed"                                : Run Last
  "new-toplevel-window"                            : Run Last

Description

Details

XklEnginePrivate

typedef struct _XklEnginePrivate XklEnginePrivate;


enum XklEngineStateChange

	typedef enum {
		GROUP_CHANGED,
		INDICATORS_CHANGED
	} XklEngineStateChange;


enum XklEngineFeatures

	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;


XklState

typedef struct {
/** 
 * selected group 
 */
		gint32 group;
/**
 * set of active indicators
 */
		guint32 indicators;
} XklState;


XklEngine

typedef struct _XklEngine XklEngine;


xkl_engine_get_instance ()

XklEngine*          xkl_engine_get_instance             (Display *display);

Get the instance of the XklEngine. Within a process, there is always once instance.

display :

the X display used by the application

Returns :

the singleton instance

xkl_engine_get_backend_name ()

const gchar*        xkl_engine_get_backend_name         (XklEngine *engine);

What kind of backend is used

engine :

the engine

Returns :

some string id of the backend

xkl_engine_get_features ()

guint               xkl_engine_get_features             (XklEngine *engine);

Provides information regarding available backend features (combination of XKLF_* constants)

engine :

the engine

Returns :

ORed XKLF_* constants

xkl_engine_get_max_num_groups ()

guint               xkl_engine_get_max_num_groups       (XklEngine *engine);

Provides the information on maximum number of simultaneously supported groups (layouts)

engine :

the engine

Returns :

maximum number of the groups in configuration, 0 if no restrictions.

enum XklEngineListenModes

	typedef enum {
		XKLL_MANAGE_WINDOW_STATES = 0x01,
		XKLL_TRACK_KEYBOARD_STATE = 0x02,
		XKLL_MANAGE_LAYOUTS = 0x04
	} XklEngineListenModes;


xkl_engine_start_listen ()

gint                xkl_engine_start_listen             (XklEngine *engine,
                                                         guint flags);

Starts listening for XKB-related events

engine :

the engine

flags :

any combination of XKLL_* constants

Returns :

0

xkl_engine_stop_listen ()

gint                xkl_engine_stop_listen              (XklEngine *engine);

Stops listening for XKB-related events

engine :

the engine

Returns :

0

xkl_engine_pause_listen ()

gint                xkl_engine_pause_listen             (XklEngine *engine);

Temporary pauses listening for XKB-related events

engine :

the engine

Returns :

0

xkl_engine_resume_listen ()

gint                xkl_engine_resume_listen            (XklEngine *engine);

Resumes listening for XKB-related events

engine :

the engine

Returns :

0

xkl_engine_grab_key ()

gboolean            xkl_engine_grab_key                 (XklEngine *engine,
                                                         gint keycode,
                                                         guint modifiers);

Grabs some key

engine :

the engine

keycode :

keycode

modifiers :

bitmask of modifiers

Returns :

TRUE on success

xkl_engine_ungrab_key ()

gboolean            xkl_engine_ungrab_key               (XklEngine *engine,
                                                         gint keycode,
                                                         guint modifiers);

Ungrabs some key

engine :

the engine

keycode :

keycode

modifiers :

bitmask of modifiers

Returns :

TRUE on success

xkl_engine_filter_events ()

gint                xkl_engine_filter_events            (XklEngine *engine,
                                                         XEvent *evt);

Processes X events. Should be included into the main event cycle of an application. One of the most important functions.

engine :

the engine

evt :

delivered X event

Returns :

0 if the event it processed - 1 otherwise

xkl_engine_allow_one_switch_to_secondary_group ()

void                xkl_engine_allow_one_switch_to_secondary_group
                                                        (XklEngine *engine);

Allows to switch (once) to the secondary group

engine :

the engine

xkl_engine_get_current_window ()

Window              xkl_engine_get_current_window       (XklEngine *engine);

engine :

the engine

Returns :

currently focused window

xkl_engine_get_current_state ()

XklState*           xkl_engine_get_current_state        (XklEngine *engine);

engine :

the engine

Returns :

current state of the keyboard. Returned value is a statically allocated buffer, should not be freed.

xkl_engine_get_window_title ()

gchar*              xkl_engine_get_window_title         (XklEngine *engine,
                                                         Window win);

engine :

the engine

win :

X window

Returns :

the window title of some window or NULL. If not NULL, it should be freed with XFree

xkl_engine_get_state ()

gboolean            xkl_engine_get_state                (XklEngine *engine,
                                                         Window win,
                                                         XklState *state_out);

Finds the state for a given window (for its "App window").

engine :

the engine

win :

window to query

state_out :

structure to store the state

Returns :

TRUE on success, otherwise FALSE (the error message can be obtained using xkl_GetLastError).

xkl_engine_delete_state ()

void                xkl_engine_delete_state             (XklEngine *engine,
                                                         Window win);

Drops the state of a given window (of its "App window").

engine :

the engine

win :

target window

xkl_engine_save_state ()

void                xkl_engine_save_state               (XklEngine *engine,
                                                         Window win,
                                                         XklState *state);

Stores ths state for a given window

engine :

the engine

win :

target window

state :

new state of the window

xkl_engine_set_window_transparent ()

void                xkl_engine_set_window_transparent   (XklEngine *engine,
                                                         Window win,
                                                         gbooleantransparent );

Sets the "transparent" flag. It means focus switching onto this window will never change the state.

engine :

the engine

win :

window do set the flag for.

Param3 :


xkl_engine_is_window_transparent ()

gboolean            xkl_engine_is_window_transparent    (XklEngine *engine,
                                                         Window win);

engine :

the engine

win :

window to get the transparent flag from.

Returns :

TRUE if the window is "transparent"

xkl_engine_is_window_from_same_toplevel_window ()

gboolean            xkl_engine_is_window_from_same_toplevel_window
                                                        (XklEngine *engine,
                                                         Window win1,
                                                         Window win2);

Checks whether 2 windows have the same topmost window

engine :

the engine

win1 :

first window

win2 :

second window

Returns :

TRUE is windows are in the same application

xkl_engine_get_num_groups ()

guint               xkl_engine_get_num_groups           (XklEngine *engine);

engine :

the engine

Returns :

the total number of groups in the current configuration (keyboard)

xkl_engine_get_groups_names ()

const gchar**       xkl_engine_get_groups_names         (XklEngine *engine);

engine :

the engine

Returns :

the array of group names for the current XKB configuration (keyboard). This array is static, should not be freed

xkl_engine_get_indicators_names ()

const gchar**       xkl_engine_get_indicators_names     (XklEngine *engine);

engine :

the engine

Returns :

the array of indicator names for the current XKB configuration (keyboard). This array is static, should not be freed

xkl_engine_get_next_group ()

gint                xkl_engine_get_next_group           (XklEngine *engine);

Calculates next group id. Does not change the state of anything.

engine :

the engine

Returns :

next group id

xkl_engine_get_prev_group ()

gint                xkl_engine_get_prev_group           (XklEngine *engine);

Calculates prev group id. Does not change the state of anything.

engine :

the engine

Returns :

prev group id

xkl_engine_get_current_window_group ()

gint                xkl_engine_get_current_window_group (XklEngine *engine);

engine :

the engine

Returns :

saved group id of the current window.

xkl_engine_lock_group ()

void                xkl_engine_lock_group               (XklEngine *engine,
                                                         gint group);

Locks the group. Can be used after xkl_GetXXXGroup functions

engine :

the engine

group :

group number for locking

xkl_engine_set_group_per_toplevel_window ()

void                xkl_engine_set_group_per_toplevel_window
                                                        (XklEngine *engine,
                                                         gbooleanis_global );

Sets the configuration parameter: group per application

engine :

the engine

Param2 :


xkl_engine_is_group_per_toplevel_window ()

gboolean            xkl_engine_is_group_per_toplevel_window
                                                        (XklEngine *engine);

engine :

the engine

Returns :

the value of the parameter: group per application

xkl_engine_set_indicators_handling ()

void                xkl_engine_set_indicators_handling  (XklEngine *engine,
                                                         gbooleanwhether_handle );

Sets the configuration parameter: perform indicators handling

engine :

the engine

Param2 :


xkl_engine_get_indicators_handling ()

gboolean            xkl_engine_get_indicators_handling  (XklEngine *engine);

engine :

the engine

Returns :

the value of the parameter: perform indicator handling

xkl_engine_set_secondary_groups_mask ()

void                xkl_engine_set_secondary_groups_mask
                                                        (XklEngine *engine,
                                                         guint mask);

Sets the secondary groups (one bit per group). Secondary groups require explicit "allowance" for switching

engine :

the engine

mask :

new group mask

xkl_engine_get_secondary_groups_mask ()

guint               xkl_engine_get_secondary_groups_mask
                                                        (XklEngine *engine);

engine :

the engine

Returns :

the secondary group mask

xkl_engine_set_default_group ()

void                xkl_engine_set_default_group        (XklEngine *engine,
                                                         gint group);

Configures the default group set on window creation. If -1, no default group is used

engine :

the engine

group :

default group

xkl_engine_get_default_group ()

gint                xkl_engine_get_default_group        (XklEngine *engine);

Returns the default group set on window creation If -1, no default group is used

engine :

the engine

Returns :

the default group

Property Details

The "backendName" property

  "backendName"              gchar*                : Read

Backend name.

Default value: NULL


The "default-group" property

  "default-group"            guint                 : Read

Default group.

Allowed values: <= 256

Default value: 0


The "display" property

  "display"                  gpointer              : Read / Write / Construct Only

X Display pointer.


The "features" property

  "features"                 XklEngineFeatures     : Read

Backend features.


The "indicators-handling" property

  "indicators-handling"      gboolean              : Read

Whether engine should handle indicators.

Default value: FALSE


The "max-num-groups" property

  "max-num-groups"           guint                 : Read

Max number of groups.

Allowed values: <= 256

Default value: 0


The "num-groups" property

  "num-groups"               guint                 : Read

Current number of groups.

Allowed values: <= 256

Default value: 0


The "secondary-groups-mask" property

  "secondary-groups-mask"    guint                 : Read

Secondary groups mask.

Allowed values: <= 256

Default value: 0

Signal Details

The "X-config-changed" signal

void                user_function                      (XklEngine *xklengine,
                                                        gpointer   user_data)      : Run Last

xklengine :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "X-state-changed" signal

void                user_function                      (XklEngine               *xklengine,
                                                        XklEngineStateChangeType arg1,
                                                        gint                     arg2,
                                                        gboolean                 arg3,
                                                        gpointer                 user_data)      : Run Last

xklengine :

the object which received the signal.

arg1 :

arg2 :

arg3 :

user_data :

user data set when the signal handler was connected.

The "new-toplevel-window" signal

gint                user_function                      (XklEngine *xklengine,
                                                        glong      arg1,
                                                        glong      arg2,
                                                        gpointer   user_data)      : Run Last

xklengine :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

Returns :