XklEngine: Libxklavier Reference Manual

XklEngine

Functions

XklEngine *	xkl_engine_get_instance ()
const gchar *	xkl_engine_get_backend_name ()
guint	xkl_engine_get_features ()
guint	xkl_engine_get_max_num_groups ()
gint	xkl_engine_start_listen ()
gint	xkl_engine_stop_listen ()
gint	xkl_engine_pause_listen ()
gint	xkl_engine_resume_listen ()
gboolean	xkl_engine_grab_key ()
gboolean	xkl_engine_ungrab_key ()
gint	xkl_engine_filter_events ()
void	xkl_engine_allow_one_switch_to_secondary_group ()
Window	xkl_engine_get_current_window ()
XklState *	xkl_engine_get_current_state ()
gchar *	xkl_engine_get_window_title ()
gboolean	xkl_engine_get_state ()
void	xkl_engine_delete_state ()
void	xkl_engine_save_state ()
void	xkl_engine_set_window_transparent ()
gboolean	xkl_engine_is_window_transparent ()
gboolean	xkl_engine_is_window_from_same_toplevel_window ()
guint	xkl_engine_get_num_groups ()
const gchar **	xkl_engine_get_groups_names ()
const gchar **	xkl_engine_get_indicators_names ()
gint	xkl_engine_get_next_group ()
gint	xkl_engine_get_prev_group ()
gint	xkl_engine_get_current_window_group ()
void	xkl_engine_lock_group ()
void	xkl_engine_set_group_per_toplevel_window ()
gboolean	xkl_engine_is_group_per_toplevel_window ()
void	xkl_engine_set_indicators_handling ()
gboolean	xkl_engine_get_indicators_handling ()
void	xkl_engine_set_secondary_groups_mask ()
guint	xkl_engine_get_secondary_groups_mask ()
void	xkl_engine_set_default_group ()
gint	xkl_engine_get_default_group ()
GType	xkl_engine_features_get_type ()
GType	xkl_engine_listen_modes_get_type ()
GType	xkl_engine_state_change_get_type ()

Properties

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

Signals

void	X-config-changed	Run Last
void	X-new-device	Run Last
void	X-state-changed	Run Last
int	new-toplevel-window	Run Last

Types and Values

	XklEnginePrivate
enum	XklEngineStateChange
enum	XklEngineFeatures
	XklState
struct	XklEngine
enum	XklEngineListenModes

Object Hierarchy

    GObject
    ╰── XklEngine

Description

Functions

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.

Parameters

display

the X display used by the application

Returns

the singleton instance.

[transfer none]

xkl_engine_get_backend_name ()

const gchar *
xkl_engine_get_backend_name (XklEngine *engine);

What kind of backend is used

Parameters

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)

Parameters

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)

Parameters

engine

the engine

Returns

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

xkl_engine_start_listen ()

gint
xkl_engine_start_listen (XklEngine *engine,
                         guint flags);

Starts listening for XKB-related events

Parameters

engine	the engine
flags	any combination of XKLL_* constants

Returns

xkl_engine_stop_listen ()

gint
xkl_engine_stop_listen (XklEngine *engine,
                        guint flags);

Stops listening for XKB-related events

Parameters

engine	the engine
flags	any combination of XKLL_* constants

Returns

xkl_engine_pause_listen ()

gint
xkl_engine_pause_listen (XklEngine *engine);

Temporary pauses listening for XKB-related events

Parameters

engine

the engine

Returns

xkl_engine_resume_listen ()

gint
xkl_engine_resume_listen (XklEngine *engine);

Resumes listening for XKB-related events

Parameters

engine

the engine

Returns

xkl_engine_grab_key ()

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

Grabs some key

Parameters

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

Parameters

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.

Parameters

engine	the engine
evt	delivered X event.	[skip]

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

Parameters

engine

the engine

xkl_engine_get_current_window ()

Window
xkl_engine_get_current_window (XklEngine *engine);

Parameters

engine

the engine

Returns

currently focused window

xkl_engine_get_current_state ()

XklState *
xkl_engine_get_current_state (XklEngine *engine);

Parameters

engine

the engine

Returns

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

[transfer none]

xkl_engine_get_window_title ()

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

Parameters

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").

Parameters

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").

Parameters

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

Parameters

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,
                                   gboolean transparent);

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

Parameters

engine	the engine
win	window do set the flag for.
transparent	if true, the windows is transparent.

xkl_engine_is_window_transparent ()

gboolean
xkl_engine_is_window_transparent (XklEngine *engine,
                                  Window win);

Parameters

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

Parameters

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);

Parameters

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);

Parameters

engine

the engine

Returns

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

[transfer none]

xkl_engine_get_indicators_names ()

const gchar **
xkl_engine_get_indicators_names (XklEngine *engine);

Parameters

engine

the engine

Returns

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

[transfer none]

xkl_engine_get_next_group ()

gint
xkl_engine_get_next_group (XklEngine *engine);

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

Parameters

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.

Parameters

engine

the engine

Returns

prev group id

xkl_engine_get_current_window_group ()

gint
xkl_engine_get_current_window_group (XklEngine *engine);

Parameters

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

Parameters

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,
                                gboolean is_global);

Sets the configuration parameter: group per application

Parameters

engine	the engine
is_global	new parameter value

xkl_engine_is_group_per_toplevel_window ()

gboolean
xkl_engine_is_group_per_toplevel_window
                               (XklEngine *engine);

Parameters

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,
                                    gboolean whether_handle);

Sets the configuration parameter: perform indicators handling

Parameters

engine	the engine
whether_handle	new parameter value

xkl_engine_get_indicators_handling ()

gboolean
xkl_engine_get_indicators_handling (XklEngine *engine);

Parameters

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

Parameters

engine	the engine
mask	new group mask

xkl_engine_get_secondary_groups_mask ()

guint
xkl_engine_get_secondary_groups_mask (XklEngine *engine);

Parameters

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

Parameters

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

Parameters

engine

the engine

Returns

the default group

xkl_engine_features_get_type ()

GType
xkl_engine_features_get_type (void);

xkl_engine_listen_modes_get_type ()

GType
xkl_engine_listen_modes_get_type (void);

xkl_engine_state_change_get_type ()

GType
xkl_engine_state_change_get_type (void);

Types and Values

XklEnginePrivate

typedef struct _XklEnginePrivate XklEnginePrivate;

enum XklEngineStateChange

Members

GROUP_CHANGED
INDICATORS_CHANGED

enum XklEngineFeatures

Members

XKLF_CAN_TOGGLE_INDICATORS
XKLF_CAN_OUTPUT_CONFIG_AS_ASCII
XKLF_CAN_OUTPUT_CONFIG_AS_BINARY
XKLF_MULTIPLE_LAYOUTS_SUPPORTED
XKLF_REQUIRES_MANUAL_LAYOUT_MANAGEMENT
XKLF_DEVICE_DISCOVERY

XklState

typedef struct {
/**

 * selected group

 */
		gint32 group;
/**
 * set of active indicators
 */
		guint32 indicators;
} XklState;

struct XklEngine

struct XklEngine;

enum XklEngineListenModes

Members

XKLL_MANAGE_WINDOW_STATES
XKLL_TRACK_KEYBOARD_STATE
XKLL_MANAGE_LAYOUTS

Property Details

The `“backendName”` property

  “backendName”              char *

Backend name.

Owner: XklEngine

Flags: Read

Default value: NULL

The `“default-group”` property

  “default-group”            guint

Default group.

Owner: XklEngine

Flags: Read

Allowed values: <= 256

Default value: 0

The `“display”` property

  “display”                  gpointer

X Display pointer.

Owner: XklEngine

Flags: Read / Write / Construct Only

The `“features”` property

  “features”                 XklEngineFeatures

Backend features.

Owner: XklEngine

Flags: Read

The `“indicators-handling”` property

  “indicators-handling”      gboolean

Whether engine should handle indicators.

Owner: XklEngine

Flags: Read

Default value: FALSE

The `“max-num-groups”` property

  “max-num-groups”           guint

Max number of groups.

Owner: XklEngine

Flags: Read

Allowed values: <= 256

Default value: 0

The `“num-groups”` property

  “num-groups”               guint

Current number of groups.

Owner: XklEngine

Flags: Read

Allowed values: <= 256

Default value: 0

The `“secondary-groups-mask”` property

  “secondary-groups-mask”    guint

Secondary groups mask.

Owner: XklEngine

Flags: Read

Allowed values: <= 256

Default value: 0

Signal Details

The `“X-config-changed”` signal

void
user_function (XklEngine *xklengine,
               gpointer   user_data)

Flags: Run Last

The `“X-new-device”` signal

void
user_function (XklEngine *xklengine,
               gpointer   user_data)

Flags: Run Last

The `“X-state-changed”` signal

void
user_function (XklEngine           *xklengine,
               XklEngineStateChange arg1,
               int                  arg2,
               gboolean             arg3,
               gpointer             user_data)

Flags: Run Last

The `“new-toplevel-window”` signal

int
user_function (XklEngine *xklengine,
               glong      arg1,
               glong      arg2,
               gpointer   user_data)

Flags: Run Last