d45b80dc52
Package xkbgroup as "thirdparty", because it was slightly patched for python2.x compatibility. see #177
243 lines
8.9 KiB
ReStructuredText
243 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.
|