244 lines
8.9 KiB
ReStructuredText
244 lines
8.9 KiB
ReStructuredText
|
========
|
|||
|
|
xkbgroup
|
|||
|
|
========
|
|||
|
|
|
|||
|
|
.. image:: https://img.shields.io/badge/python-3.2+-blue.svg
|
|||
|
|
|
|||
|
|
.. image:: https://img.shields.io/pypi/v/xkbgroup.svg
|
|||
|
|
:target: https://pypi.python.org/pypi/xkbgroup
|
|||
|
|
|
|||
|
|
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
|
|||
|
|
:target: https://github.com/hcpl/xkbgroup/blob/master/LICENSE
|
|||
|
|
|
|||
|
|
Use this library to change the keyboard layout through XKB extension (subsystem)
|
|||
|
|
of the X server system. Both library and command line script included.
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. contents:: **Table of Contents**
|
|||
|
|
|
|||
|
|
|
|||
|
|
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__
|
|||
|
|
++++++++++++++++++++++++++++
|
|||
|
|
|
|||
|
|
__ https://pypi.python.org/pypi/xkbgroup
|
|||
|
|
|
|||
|
|
.. code-block:: sh
|
|||
|
|
|
|||
|
|
pip install xkbgroup
|
|||
|
|
|
|||
|
|
|
|||
|
|
Library usage
|
|||
|
|
-------------
|
|||
|
|
|
|||
|
|
.. code-block:: sh
|
|||
|
|
|
|||
|
|
# Assume we have the following configuration
|
|||
|
|
$ setxkbmap -layout us,ru,ua,fr
|
|||
|
|
# Change layout once before calling python
|
|||
|
|
$ python
|
|||
|
|
|
|||
|
|
.. code-block:: 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=''), GroupData(num=1, name=
|
|||
|
|
'Russian', symbol='ru', variant=''), GroupData(num=2, name='Ukrainian', symbol='ua', va
|
|||
|
|
riant=''), GroupData(num=3, name='French', symbol='fr', variant='')]
|
|||
|
|
>>> xkb.format('{num} => {symbol}')
|
|||
|
|
'0 => us'
|
|||
|
|
>>> xkb.group_num = 1
|
|||
|
|
>>> xkb.format('{num} => {symbol}')
|
|||
|
|
'1 => ru'
|
|||
|
|
>>> xkb.group_num = 3
|
|||
|
|
>>> xkb.format('{num}: {symbol} - {name} "{variant}"')
|
|||
|
|
'3: fr - French ""'
|
|||
|
|
>>> xkb.format('{count}')
|
|||
|
|
'4'
|
|||
|
|
>>> xkb.format('{names}')
|
|||
|
|
"['English (US)', 'Russian', 'Ukrainian', 'French']"
|
|||
|
|
>>> xkb.format('{names::}')
|
|||
|
|
'English (US)RussianUkrainianFrench'
|
|||
|
|
>>> xkb.format('{names:: - }')
|
|||
|
|
'English (US) - Russian - Ukrainian - French'
|
|||
|
|
>>> xkb.format('{symbols:: - }')
|
|||
|
|
'us - ru - ua - fr'
|
|||
|
|
>>> xkb.format('{symbols:s: - }')
|
|||
|
|
'us - ru - ua - fr'
|
|||
|
|
>>> xkb.format('{all_data}')
|
|||
|
|
"[GroupData(num=0, name='English (US)', symbol='us', variant=''), GroupData(num=1, name
|
|||
|
|
='Russian', symbol='ru', variant=''), GroupData(num=2, name='Ukrainian', symbol='ua', v
|
|||
|
|
ariant=''), GroupData(num=3, name='French', symbol='fr', variant='')]"
|
|||
|
|
>>> xkb.format('{all_data:{{num}}}')
|
|||
|
|
"['0', '1', '2', '3']"
|
|||
|
|
>>> xkb.format('{all_data:/* {{name}} */}')
|
|||
|
|
"['/* English (US) */', '/* Russian */', '/* Ukrainian */', '/* French */']"
|
|||
|
|
>>> xkb.format('{all_data:{{symbol}}:\n}')
|
|||
|
|
'us\nru\nua\nfr'
|
|||
|
|
>>> print(xkb.format('{all_data:{{symbol}}:\n}'))
|
|||
|
|
us
|
|||
|
|
ru
|
|||
|
|
ua
|
|||
|
|
fr
|
|||
|
|
>>> print(xkb.format('{all_data:{{num}}\\: {{symbol}} - {{name}} - "{{variant}}":\n}'))
|
|||
|
|
0: us - English (US) - ""
|
|||
|
|
1: ru - Russian - ""
|
|||
|
|
2: ua - Ukrainian - ""
|
|||
|
|
3: fr - French - ""
|
|||
|
|
>>>
|
|||
|
|
|
|||
|
|
|
|||
|
|
Command line features mapping
|
|||
|
|
-----------------------------
|
|||
|
|
|
|||
|
|
+----------+-------------------------------------+--------------------------------------+
|
|||
|
|
| Category | Library | Command line |
|
|||
|
|
+==========+=====================================+======================================+
|
|||
|
|
| Get | ``xkb.group_num`` | ``xkbgroup get num`` |
|
|||
|
|
| +-------------------------------------+--------------------------------------+
|
|||
|
|
| | ``xkb.group_name`` | ``xkbgroup get name`` |
|
|||
|
|
| +-------------------------------------+--------------------------------------+
|
|||
|
|
| | ``xkb.group_symbol`` | ``xkbgroup get symbol`` |
|
|||
|
|
| +-------------------------------------+--------------------------------------+
|
|||
|
|
| | ``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`` |
|
|||
|
|
+----------+-------------------------------------+--------------------------------------+
|
|||
|
|
| Set | ``xkb.group_num = 2`` | ``xkbgroup set num 2`` |
|
|||
|
|
| +-------------------------------------+--------------------------------------+
|
|||
|
|
| | ``xkb.group_name = 'English (US)'`` | ``xkbgroup set name 'English (US)'`` |
|
|||
|
|
| +-------------------------------------+--------------------------------------+
|
|||
|
|
| | ``xkb.group_symbol = 'fr'`` | ``xkbgroup set symbol fr`` |
|
|||
|
|
+----------+-------------------------------------+--------------------------------------+
|
|||
|
|
| Format | ``xkb.format('{format_str}')`` | ``xkbgroup format '{format_str}'`` |
|
|||
|
|
+----------+-------------------------------------+--------------------------------------+
|
|||
|
|
|
|||
|
|
|
|||
|
|
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_``.
|
|||
|
|
|
|||
|
|
__ https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Keycode_translation
|
|||
|
|
|
|||
|
|
|
|||
|
|
Classes
|
|||
|
|
-------
|
|||
|
|
|
|||
|
|
These all reside in ``xkbgroup/core.py``:
|
|||
|
|
|
|||
|
|
* ``XKeyboard`` — the main class:
|
|||
|
|
|
|||
|
|
- ``__init__(self, auto_open=True, non_symbols=None)``:
|
|||
|
|
|
|||
|
|
+ ``auto_open`` — if ``True`` then automatically call ``open_display()``
|
|||
|
|
on initialization.
|
|||
|
|
+ ``non_symbols`` — either iterable of string non-symbol names or None to
|
|||
|
|
use the default set of non-symbol names.
|
|||
|
|
- ``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.
|
|||
|
|
|
|||
|
|
- ``format()`` — obtain a formatted output, see `<docs/formatting.rst>`_
|
|||
|
|
for details.
|
|||
|
|
|
|||
|
|
* ``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.
|