## 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,
                                                             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;

### enum XklEngineStateChange

    	typedef enum {
    		GROUP_CHANGED,
    		INDICATORS_CHANGED
    	} 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;

### 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,
                                                             guint flags);

Stops listening for XKB-related events

`engine` : | the engine
`flags` : | any combination of XKLL_* constants
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-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.

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