xkbgroup 0.1.4.1

Query and change XKB layout state

Use this library to change the keyboard layout through XKB extension (subsystem) of the X server system. Both library and command line script included.

Table of Contents

• Dependencies

• Installation

• Library usage

• Command line features mapping

• Naming convention

• Classes

• Helper files

Dependencies

• Python 3.2+

• libX11.so.6 shared library which you must have by default if you use X server

Installation

From PyPI package xkbgroup

pip install xkbgroup

Library usage

# Assume we have the following configuration
$ setxkbmap -layout us,ru,ua,fr
# Change layout once before calling python
$ python

>>> from xkbgroup import XKeyboard
>>> xkb = XKeyboard()
>>> xkb.groups_count
4
>>> xkb.group_num
1
>>> xkb.group_num = 2
>>> xkb.group_num
2
>>> xkb.group_num -= 2
>>> xkb.group_num
0
>>> xkb.groups_names
['English (US)', 'Russian', 'Ukrainian', 'French']
>>> xkb.group_name
'English (US)'
>>> xkb.group_name = 'Ukrainian'
>>> xkb.group_name
'Ukrainian'
>>> xkb.group_num
2
>>> xkb.groups_symbols
['us', 'ru', 'ua', 'fr']
>>> xkb.group_symbol
'ua'
>>> xkb.group_symbol = 'fr'
>>> xkb.group_symbol
'fr'
>>> xkb.groups_variants
['', '', '', '']
>>> xkb.group_variant
''
>>> xkb.group_num -= 3
>>> xkb.group_variant
''
>>> xkb.group_num
0
>>> xkb.group_data
GroupData(num=0, name='English (US)', symbol='us', variant='')
>>> xkb.groups_data
[GroupData(num=0, name='English (US)', symbol='us', variant=''), Gro
upData(num=1, name='Russian', symbol='ru', variant=''), GroupData(nu
m=2, name='Ukrainian', symbol='ua', variant=''), GroupData(num=3, na
me='French', symbol='fr', variant='')]
>>>

Command line features mapping

Library	Command line
xkb.group_num	xkbgroup get num
xkb.group_num = 2	xkbgroup set num 2
xkb.group_name	xkbgroup get name
xkb.group_name = 'English (US)'	xkbgroup set name 'English (US)'
xkb.group_symbol	xkbgroup get symbol
xkb.group_symbol = 'fr'	xkbgroup set symbol 'fr'
xkb.group_variant	xkbgroup get variant
xkb.group_data	xkbgroup get current_data
xkb.groups_count	xkbgroup get count
xkb.groups_names	xkbgroup get names
xkb.groups_symbols	xkbgroup get symbols
xkb.groups_variants	xkbgroup get variants
xkb.groups_data	xkbgroup get all_data

Naming convention

Throughout the whole XKB subsystem the so-called groups represent actual keyboard layouts. This library follows the same convention and names of the API methods start with group_ or groups_.

Classes

These all reside in xkbgroup/core.py:

• XKeyboard — the main class:

  • __init__(self, auto_open=True) — if auto_open is True automatically call open_display().

  • open_display() — establishes connection with X server and prepares objects necessary to retrieve and send data.

  • close_display() — closes connection with X server and cleans up objects created on open_display().

  • group_* — properties for accessing current group data:

    • group_num — get/set current group number (e.g. 0, 2, 3).

    • group_name — get/set current group full name (e.g. English (US), Russian, French).

    • group_symbol — get/set current group symbol (e.g. us, ru, fr).

    • group_variant — get (only) current group variant (e.g. `` , ``dos, latin9).

    • group_data — get (only) all data about the current group. In fact, assembles all previous group_* values.

  • groups_* — properties for querying info about all groups set by setxkbmap

    • groups_count — get number of all groups.

    • groups_names — get names of all groups.

    • groups_symbols — get symbols of all groups.

    • groups_variants — get variants of all groups.

    • groups_data — get all data about all groups by assembling all previous groups_* values.

• X11Error — an exception class, raised for errors on X server issues.

Helper files

There are also complementary files:

• generate_bindings.sh — a shell script which generates Python bindings to X server structures, functions and #define definitions by:

  • converting X11 C headers using h2xml and xml2py;

  • creating ctypes references to functions from libX11.so.6 using xml2py.

• xkbgroup/xkb.py — the output of the above script, usable for Xlib development under Python.