XklEngine 3 LIBXKLAVIER Library
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,
                                                             guint flags);
    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-new-device"                                   : Run Last
      "X-state-changed"                                : Run Last
      "new-toplevel-window"                            : Run Last

## Description

## Details

### XklEnginePrivate

    typedef struct _XklEnginePrivate XklEnginePrivate;

XklEnginePrivate

### enum XklEngineStateChange

    	typedef enum {
    		GROUP_CHANGED,
    		INDICATORS_CHANGED
    	} XklEngineStateChange;

XklEngineStateChange

### enum XklEngineFeatures

    	typedef enum {
    		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;

XklEngineFeatures

### XklState

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

XklState

### XklEngine

    typedef struct _XklEngine 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_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_backend_name

### 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_features

### 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.

xkl_engine_get_max_num_groups

### enum XklEngineListenModes

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

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_start_listen

### xkl_engine_stop_listen ()

    gint                xkl_engine_stop_listen              (XklEngine *engine,
                                                             guint flags);

Stops listening for XKB-related events

engine :

  the engine

flags :

  any combination of XKLL_* constants

Returns :

  0

xkl_engine_stop_listen

### 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_pause_listen

### xkl_engine_resume_listen ()

    gint                xkl_engine_resume_listen            (XklEngine *engine);

Resumes listening for XKB-related events

engine :

  the engine

Returns :

  0

xkl_engine_resume_listen

### 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_grab_key

### 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_ungrab_key

### 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_filter_events

### 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_allow_one_switch_to_secondary_group

### xkl_engine_get_current_window ()

    Window              xkl_engine_get_current_window       (XklEngine *engine);

engine :

  the engine

Returns :

  currently focused window

xkl_engine_get_current_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_current_state

### 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_window_title

### 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_get_state

### 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_delete_state

### 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_save_state

### 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_set_window_transparent

### 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_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_is_window_from_same_toplevel_window

### 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_num_groups

### 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_groups_names

### 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_indicators_names

### 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_next_group

### 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_prev_group

### 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_get_current_window_group

### 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_lock_group

### 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_set_group_per_toplevel_window

### 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_is_group_per_toplevel_window

### 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_set_indicators_handling

### 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_get_indicators_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_set_secondary_groups_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_get_secondary_groups_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_set_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

xkl_engine_get_default_group

## Property Details

### The `"backendName"` property

      "backendName"              gchar*                : Read

Backend name.

Default value: NULL

XklEngine:backendName

### The `"default-group"` property

      "default-group"            guint                 : Read

Default group.

Allowed values: <= 256

Default value: 0

XklEngine:default-group

### The `"display"` property

      "display"                  gpointer              : Read / Write / Construct Only

X Display pointer.

XklEngine:display

### The `"features"` property

      "features"                 XklEngineFeatures     : Read

Backend features.

XklEngine:features

### The `"indicators-handling"` property

      "indicators-handling"      gboolean              : Read

Whether engine should handle indicators.

Default value: FALSE

XklEngine:indicators-handling

### The `"max-num-groups"` property

      "max-num-groups"           guint                 : Read

Max number of groups.

Allowed values: <= 256

Default value: 0

XklEngine:max-num-groups

### The `"num-groups"` property

      "num-groups"               guint                 : Read

Current number of groups.

Allowed values: <= 256

Default value: 0

XklEngine:num-groups

### The `"secondary-groups-mask"` property

      "secondary-groups-mask"    guint                 : Read

Secondary groups mask.

Allowed values: <= 256

Default value: 0

XklEngine:secondary-groups-mask

## 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.

XklEngine::X-config-changed

### The `"X-new-device"` 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.

XklEngine::X-new-device

### 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.

XklEngine::X-state-changed

### 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 :

XklEngine::new-toplevel-window