Metadata-Version: 2.1
Name: PyHotKey
Version: 1.4.1
Summary: A cross-platform hotkey module.
Home-page: https://github.com/Xpp521/PyHotKey
Author: Xpp
Author-email: xpp233@foxmail.com
License: LGPLv3
Project-URL: Documentation, https://github.com/Xpp521/PyHotKey
Project-URL: Source, https://github.com/Xpp521/PyHotKey
Project-URL: Tracker, https://github.com/Xpp521/PyHotKey/issues
Description: # PyHotKey
        PyHotKey is a **cross-platform** hotkey module for Python. Based on "pynput".
        
        ## Usage
        ***Note***: To get the best experience of this module, you must run your application with the highest privileges.
        - Windows: run your application as administrator.
        - Linux: run your application as root or use "sudo" command to launch your application.
        - Mac OS: same as Linux or whitelist your application: open "System Preferences -> Security & Privacy -> Privacy -> Accessibility (on the left)", click the lock to make changes (at the bottom), check your application on the right.
        
        #### Install
        ```
        pip install PyHotKey
        ```
        
        #### Import:
        ```python
        from PyHotKey import Key, keyboard_manager as manager
        ```
        
        #### Register hotkey:
        ```python
        # Register a hotkey (multiple keys)
        id1 = manager.register_hotkey([Key.ctrl_l, Key.alt_l, 'z'], None,
                                      func, func_arg1, func_arg2=1)
        
        if -1 == id1:
            print('Already registered!')
        elif 0 == id1:
            print('Invalid parameters!')
        else:
            print('Hotkey id: {}'.format(id1))
        
        # Register a hotkey (single key)
        # 2 means tap twice to trigger the hotkey
        id2 = manager.register_hotkey([Key.caps_lock], 2, func,
                                      func_arg1, func_arg2, func_arg3=3)
        
        # Unregister hotkey by key list
        r1 = manager.unregister_hotkey_by_keys([Key.ctrl_l, Key.alt_l, 'z'])
        
        # Unregister hotkey by hotkey id
        r2 = manager.unregister_hotkey_by_id(id2)
        
        # Unregister all hotkeys
        r3 = manager.unregister_all_hotkeys()
        ```
        
        #### Record hotkey:
        ```python
        # The callback function for recording hotkey
        # You can use "key_list" to register hotkey later
        def callback(key_list):
            print(key_list)
        
        # Start recording a hotkey with multiple keys
        manager.start_recording_hotkey_multiple(callback)
        
        # Start recording a hotkey with single key
        manager.start_recording_hotkey_single(callback)
        
        # Stop recording hotkey
        manager.stop_recording()
        ```
        ***PS***: More usage check examples on [GitHub](https://github.com/Xpp521/PyHotKey/tree/master/examples).
        
        #### Control keyboard
        ```python
        # Press
        manager.press(Key.space)
        
        # Release
        manager.release('z')
        
        # Tap (press and release)
        manager.tap('x')
        
        # Do something while holding down certain keys
        with manager.pressed(Key.ctrl, Key.shift) as r:
            if r:
                do_something()
        
        # Type a string
        manager.type('Xpp521')
        ```
        ***PS***: If you're recording hotkey, these apis won't work.
        
        #### Other APIs
        ```python
        # Print all hotkeys
        print(manager.hotkeys)
        
        # Print the currently pressed keys
        print(manager.pressed_keys)
        
        # Check whether a key is pressed
        if 'z' in manager.pressed_keys:
            print("'z' is pressed.")
        
        # Print recording state
        print(manager.recording)
        
        # Strict mode (for hotkeys with multiple keys)
        # The pressed keys must be strictly equal to the hotkey
        manager.strict_mode = False
        
        # TTL: time to live (for hotkeys with multiple keys)
        # When a key is pressed for more than TTL seconds,
        # it will be removed from the currently pressed keys
        # in the next key press/release event.
        manager.ttl = 7
        
        # Interval: the max interval time between each press (for hotkeys with single key)
        manager.interval = 0.5
        ```
        
        #### Keyboard Listener
        ```python
        # Print keyboard listener's running state
        print(manager.running)
        
        # Stop keyboard listener
        # When stopped, hotkey related functions won't work
        manager.stop()
        
        # Start keyboard listener
        # You can restart the listener after stopping it
        manager.start()
        ```
        ***PS***: Generally, you may not use these apis.
        
        #### Logger:
        ```python
        # Turn on the logger
        manager.logger = True
        
        # Set a file for logging ("append" mode)
        manager.set_log_file('Loggggggg.log', 'a')
        ```
        
        ## TODO:
        - [ ] Detect conflicts with system hotkeys.
        - [ ] Suppress the last key after triggering a hotkey.
        - [ ] Support to trigger hotkeys on pressed or on released.# Release Note
        ## v1.4.1
        - Add api: "unregister_all_hotkeys".
        - Change the parameter order of "register_hotkey".
        - Now you can use "pressed_keys" to check whether a key is pressed.
        ___
        ## v1.4.0 - 2022 Reborn
        After 3 years I'm back with the new "PyHotKey".
        
        Changes:
        - Fixed a lot of bugs.
        - Now you can record hotkey and control keyboard.
        - Real cross platform this time.
        - And more convenient apis...
        
        Check "README.md".
        ___
        ## v1.3.3
        #### Bug Fixes
        - Combination hot key: Fix the keystroke value error of combination hot key.
        #### Refactor
        - Simplify README.md.
        ___
        ## v1.3.2
        #### Bug Fixes
        - Log path: fix the default log path overwrites the custom log path when setting "manager.logger = True".
        #### Refactor
        - Adjust code structure.
        - Rewrite README.md.
        ___
        ## v1.3.1
        - Delete a deprecated class.
        - Replace root logger with a separate logger.
        - Rename property "hot_keys" to "hotKeyList".
        - Change documents and some code comments.
        ___
        ## v1.3.0
        - Currently, users can customize the log path.
        - Optimize code.
        ___
        ## v1.2.0
        - Add logger.
        - Optimize code.
        - Attempt to fix a potential bug.
        ___
        ## v1.1.1
        - Remove log message.
        ___
        ## v1.1.0
        - Currently, the trigger function supports arguments.
        - No longer need to call manager.start() manually.
        - Fix multiple type hot key bug.
        ___
        ## v1.0
        - The first version.
Keywords: hotkey,keyboard,hot+key
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows NT/2000
Classifier: Operating System :: POSIX
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Description-Content-Type: text/markdown
