Metadata-Version: 2.1
Name: system_hotkey310
Version: 1.0.5
Summary: System wide hotkeys
Home-page: https://github.com/hhannine/system_hotkey310
Author: Henri Hänninen
Author-email: henri.j.hanninen@gmail.com
License: BSD3
Keywords: hotkeys python3 shortcutkeys shortuct x11 windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
License-File: LICENSE
License-File: AUTHORS.rst

System Hotkey 310
=================

Multi platform system wide hotkeys for Python 3.10+

Currently no mac support but pull requests or collaboration is very welcome!

Note: currently this fork of system_hotkey exists just to fix Python 3.10 compatibility.


Installation
------------

the old

.. code-block:: bash

  pip3 install system_hotkey310

should do the trick

Windows
^^^^^^^
install pywin32

Linux
^^^^^
For x11 you should use `xcffib <https://github.com/tych0/xcffib>`_  (bsd license),

If for some reason you have to use the python xlib bindings (gpl license), a few fixes need be added first. See `here <https://github.com/timeyyy/system_hotkey/issues/6#issuecomment-265410255>`_


Usage
------

**Input Keysyms**

System hotkeys uses the keysym names from xlib for everything besides modifiers.(although case insensitive)
grep for vk_codes for a list of available chars.
If you are unable to bind to a certain key please let us know.

You can bind directly to symbols such as ["',. etc
Numpad keys can be binded by prefixing with kp\_.

Supported modifiers include:

- control
- shift
- super (windows key)
- alt

InvalidKeyError will be raised if a key was not understood

.. code-block:: python

    from system_hotkey import SystemHotkey
    hk = SystemHotkey()
    hk.register(('control', 'shift', 'h'), callback=lambda x: print("Easy!"))

A SystemRegisterError will be raised if a hotkey is already in use.

To unregister a hotkey

.. code-block:: python

    hk.unregister(('control', 'shift', 'h'))

A KeyError will be raised if the combination is not already grabbed.

A UnregisterError will be raised if unregistering failed for any other reason.

If you want you can pass in a custom consumer:

.. code-block:: python

    def some_func(self, event, hotkey, args):
        pass

    hk = SystemHotkey(consumer=some_func)
    hk.register(hotkey, arg1, arg2, arg3)

So you have a master function that receives all hotkey presses and can delegate as desired.

**Note**
Modifier keys are independent of order i.e control + alt + del  is the same as alt + control + del

Features
--------
- Support for up to 3 modifiers and a key

Limitations
-----------
- I have only mapped most common keys, i have not experimented with Unicode/Japanese characters etc. It's only a matter of mapping a name to the keysym on Linux and virtual key code on windows.

- binding to kp_left (key pad left) will also bind to kp_4, there is a flag (unite_kp) to toggle this behaviour but it is experimental

- Requires an xserver (x11)...



To be done
==========

Mac support

eta > 8 months


Version Release Notes
=====================
1.0.5
-----
* Python 3.10 compatibility

1.0.4
-----
* Exceptions are now run in main

1.0.3
-----
* Documented the fact that xlib shouldn't really be used

1.0.2
-----
* Fixed a linux bug where spurious events got passed through

1.0.0
-----
* calls to the unregister and register are now thread safe
* kp keys work properly
* kp_unite option

0.1.4
-----
* Bug fix on linux where pressing numlock would crash us..

0.1.3
-----

* Custom args can now be passed to a custom consumer




Authors and Contributors
========================

Timothy Eichler, Original Author of the system_hotkey package
Henri Hänninen
