pywin_hotkey2script Files

######### readme in hook_at_dll c++ subproject #################
for what:
    since some hook functions need to be in a DLL, 
    this project is here to provide such functions
    to wrap your python callback functions.
    

dependency:
    (1) python for windows
    (2) write in c++. boost.python is required. 
            
compile:
    (1) msvc is recommended:
        conflicts exist between mingw.exception and python for windows.
    (2) set the include and library path of python and boost:
        py_include   py_lib
        boost        boost_lib
    (3) define hook_at_dll_h_NUM_HOOK_FUNC in the cmdline:
        cl /Fe_python_hook.pyd /Dhook_at_dll_h_NUM_HOOK_FUNC=256 /LD /MD /EHsc hook_at_dll.cpp _set_clr_hook.cpp hook_at_dll_export.cpp User32.lib /I%py_include% /I%boost% /link /LIBPATH:%boost_lib% /LIBPATH:%py_lib%

install:
    let the output file "_python_hook.pyd" and the boost.python dll file 
    be visitable to Python
    
usage in Python:
    import _python_hook
    
    # idHook: the same arg will be passed to SetWindowsHookEx
    WH_KEYBOARD_LL = 13
    idHook = WH_KEYBOARD_LL # for example : WH_KEYBOARD_LL, WH_MOUSE_LL
    
    # callback(nCode, wParam, lParam)->not_to_call_CallNextHookEx
    def callback(nCode, wParam, lParam):
        # the same args as the c callback saw
        not_to_call_CallNextHookEx = False
        if nCode != 0: return not_to_call_CallNextHookEx
        
        # ..............
        # do your work
        # return as soon as possible
        # ..............
        return not_to_call_CallNextHookEx
    
    
    # get the marco value, the number of hooks available
    hook_at_dll_h_NUM_HOOK_FUNC = _python_hook.get_sizeof_hook_array()
    for i in range(hook_at_dll_h_NUM_HOOK_FUNC):
        if _python_hook.hook_at(i, idHook, callback):
            _python_hook.unhook_at(i)



######### readme in hotkey2script #################
hotkey2script
    pressing a key, it will call your script.

0 forever alpha
    unstable, bad-doc, not tested, no setup.py

1 hook
1.1 c_hook
    c++ project
    provides some HOOKPROC funtions in a dll to use lowlevel hook.
    require boost.python
    use the marco hook_at_dll_h_NUM_HOOK_FUNC to custom the number of functions.
    more info in 'readme.txt' under the project
    
1.2 c_callback
    there are some python callback functions indeed.
    
    they are used to send the message to more high level python callbacks.
    we only need to make one c_callback object for one type of windows hook(idHook).
    and we will have no limit on the number of hooks.

1.3 py_hook
    there are high level python hook manager.
    
    provides:
        work with c_callback to give lots of hooks.
        api use string instead of flags to ease the use.
        each hook can associate with a list of triggers, 
            like [('A', 'down'), ('B', 'up'),...] to notify it.
        each hook can associate with a level_class to reject some messages.
            such as those event generated by ourselves.
            the issubclass relationship is used.
            look at 'python_hook_framework_head.py' and 
            'event' module for more about level_class.
        each hook can associate with a match function to 
            collect the current state and make decision whether to callback
            and whether to pass the message to next hook.
            this decision should be maked quickly.
            callback is to be called in new thread by default.
            more info about the match result in 'python_hook_framework_head.py'
        
        NOTE:
            new thread for callback is not daemon.
            because the exception in the callback can't be received by python.
            you may want to print the error message in callback.
            
            custom the behavior:
                argument 'new_thread'
                handler in the match result return by match funtion.
        
    (now, only WH_KEYBOARD_LL, WH_MOUSE_LL)

1.4 threadsafe_hook
    threadsafe_hook_t, hook_with_win_msg_loop_t
    
    threadsafe_hook_t unifies the keyboard and mouse hooks.
    
    we need a thread to set the hook, call the callback, 
    and in the windows message loop.
    'hook_with_win_msg_loop_t' wrap our hook command to that thread.
    
    see also 'win_msg_loop' and 'order_the_win_msg_loop_thread' modules.
    
2 event
    what is the api argument below?
    see 4.7
2.1 device_actions
    up, wheel, move, double_click......
    
2.2 device_event
    wrap the api given to ease use.
    example:
        mouse_event_obj = mouse_event_t(api)
        mouse_event_obj.move_to(x=2**16*50//100, y=2**16*50//100) # center
        mouse_event_obj.move(0,0) # nothing happend
        
        event_obj = all_devices_event_t(api)
        event_obj.keybd_up('a')
    
2.3 device_state
    obj = get_key_state_t(api)
    obj.is_light_on('kCAPITAL')
    obj.is_down('mleft')
    
    'k'/'m' is device's prefix and short hand of device name.
    'capital'/'left' is key_name_noprefix.
    see below for the key_name and prefix.
    
2.4 device_event_short_hand
    defines lots of names binded with a given api
    
    is_down(mleft)
    k(up, k)
    m(left_click, x=-1000, y=+1000)
    
3 hotkey2script
    hook at hotkey, and callback to run scripts.
    using win32api
    
3.1 names_from_event_and_hook
    yield some names binded with a given api to use in scripts.

3.2 script_executor
    since I can't limit the power of the scripts to be run, 
    I eventually give up to use a generator scheduler.
    script takes care to run threads and processes by itself.
    
    what the generator yields is the sleep time in seconds.
    if it call time.sleep or preform some block actions, 
    all the scripts are hang up.
    
3.3 read_hotkey2script_file
3.4 script_example
    to figure out the framework, see:
    'hotkey_list.py'
    'option_<xxx>.py'
    'script_<abc>.py'
    
    'hotkey_list.py' should define quit_hotkey and hotkey2script_list
    'script_<abc>.py' should define main generatorfunction.
    
    if the subroutin needs to sleep,
    call it by 'r = yield from sub(...)'
    
4 others
4.1 prefix of device
    define in device_info
    'k' for 'keybd', 'm' for 'mouse'
    
4.2 key_name_noprefix
    define in device_info
    
    for keyboard: 
    VK_LMENU -> 'lmenu'
    see: constant.windows_virual_key_codes
    
    for mouse:
    left, middle, right
    
4.3 key_name
    define in device_info
    key_name = device_prefix + key_name_noprefix


4.4 device_name
    define in device_info
    
    'keybd'/'mouse'

4.5 win_msg_loop
4.6 order_the_win_msg_loop_thread
    establish a message loop
    talk to it
    
4.7 api argument
    api has attributes:
    api.GetKeyState
    api.mouse_event
    api.keybd_event
    
    win32api of win32 project is used in hotkey2script

4.8 see 'list.txt'

5 device_event_app
    there are games that need to hit a certain button sequences 
    to trigger more harmful attacks. this module parse the 
    sequence like '623B' into source file used in python or 
    'an-jian-jing-ling'.