"Fossies" - the Fresh Open Source Software Archive

Member "key-scripter-2.1/README" (11 May 2020, 19590 Bytes) of package /linux/privat/key-scripter-2.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 2.0_vs_2.1.

    1 Key Scripter 2.1
    2 Copyright (c) 2020 Crolix Software
    3 
    4 
    5 DESCRIPTION
    6 
    7 Key Scripter listens to key press/release events from a keyboard or a mouse and allows to generate automated events. Supports gaming keypads, such as Nostromo SpeedPad. Allows the creation and usage of complicated key scripts for games and other applications.
    8 
    9 
   10 INSTALLATION
   11 
   12 On Windows:
   13 
   14 If you downloaded the binary package of Key Scripter, simply extract the archive to your 'C:\Program Files' directory and append 'C:\Program Files\Key Scripter' to the PATH environment variable.
   15 
   16 If you choose to compile the source files on Windows, you first need to install the latest release of MinGW (see http://mingw.org/). After MinGW is installed on your system, append the path to the MinGW 'bin' directory to the PATH environment variable. For example, if your MinGW environment is installed in C:\MinGW, you need to append 'C:\MinGW\bin' to the PATH variable. Finally, unpack the Key Scripter source files to a directory of your choice and type the following command in the unpacked directory:
   17 
   18   windows-build
   19 
   20 After the program has been compiled, copy the key-scripter.exe and key-scripter.dll files to the 'C:\Program Files\Key Scripter' directory and append 'C:\Program Files\Key Scripter' to the PATH environment variable.
   21 
   22 On Linux:
   23 
   24 Unpack the files to a directory of your choice and type the following commands in the unpacked directory:
   25 
   26   ./configure
   27   make
   28 
   29 This will compile the package. After the program has been compiled, type the following command as root to install Key Scripter:
   30 
   31   make install
   32 
   33 To uninstall Key Scripter, type the following command:
   34 
   35   make uninstall
   36 
   37 
   38 SETUP
   39 
   40 Note: this chapter is for Linux users only. Windows users can skip it and go directly to Usage.
   41 
   42 In order to listen to key events, Key Scripter reads raw data from one or more device files. You can use the following command to determine which device corresponds to your keyboard, mouse or keypad:
   43 
   44   cat /proc/bus/input/devices
   45 
   46 Key Scripter allows you to specify the value of the listed 'N: Name' or 'P: Phys' property instead of the actual device file name. However, it is easy to determine which device file to use by looking at the 'H: Handlers' property. For example, 'H: Handlers=kbd event2' means that you can specify /dev/input/event2 as the source file for Key Scripter:
   47 
   48   key-scripter -i=/dev/input/event2
   49 
   50 Because device files are dynamically created, they are not guaranteed to stay the same after a system reboot. Therefore, when starting Key Scripter from a script, it may be better to specify the input device by its name (using the value from the 'N: Name' property), instead of specifying the actual device file. Key Scripter will then automatically determine which device file it must use in order to read from the device. For example, the following line instructs Key Scripter to read from two devices with the specified names:
   51 
   52   key-scripter -in="AT Set 2 keyboard" -in="PS/2 Logitech Mouse"
   53 
   54 You should also be aware that normally only root can read /dev/input/event* files. This means that Key Scripter won't work if run by a regular user. You can avoid running Key Scripter as root by changing access permissions of the device file. Of course, you also need to make sure that you don't make your device file accessible to anyone.
   55 
   56 One way to do that is to use the 'input' group, which is created during installation of Key Scripter. The install script also adds the key-scripter executable to the 'input' group and enables the 'set group ID on execution' file mode on it. All that is left for you to do after installing Key Scripter is to execute the following line, which will enable anyone in the 'input' group to read device files:
   57 
   58   chown :input /dev/input/event* && chmod g+r /dev/input/event*
   59 
   60 Of course, since device files are recreated each time the system is rebooted, you need to perform the above step on each system start-up. The easiest way to do that is to add the above line to one of your system start-up scripts.
   61 
   62 
   63 USAGE
   64 
   65 Key Scripter supports the following command-line parameters:
   66 
   67   -i or --input-from-device                         - reads real events from the mouse and keyboard instead of the standard input (Windows only)
   68   -i={file} or --input-device={file}                - the device file or the number of the event file to read from (Linux only)
   69   -in={name} or --input-device-name={name}          - the name of the device to read from (value of 'N: Name') (Linux only)
   70   -ia={address} or --input-device-address={address} - the physical address of the device to read from (value of 'P: Phys') (Linux only)
   71   -c={file} or --configuration={file}               - the configuration file
   72   -o or --output-to-display                         - sends generated events to the current display instead of the standard output
   73   -o={display} or --output-display={display}        - the name of the display to send generated events to (Linux only)
   74   -w or --enable-workaround                         - use this if generated events (option -o) don't work (Linux only)
   75   -d or --debug-messages                            - prints debug messages to the standard error output
   76   -v or --version                                   - displays Key Scripter's version
   77   -h or --help                                      - displays this information and exits
   78 
   79 Any values specified on the command line, not equal to the supported parameters, are interpreted as configuration commands. This makes it possible to specify a configuration directly on the command line without using a file.
   80 
   81 If no input is specified, Key Scripter will read from the standard input. This allows piping key press/release events from another program or script, instead of letting Key Scripter read directly from a device. Data read from the standard input is handled differently than raw data from a device. While a device file can only supply a press or a release event, data from the standard input may contain several more command types. Each command starts with a character identifying it, is usually followed by one or more parameters such as a positive number, and is terminated by a new-line character. The following types of commands are supported (values between {} represent a positive number):
   82 
   83   p{scancode} - a key press event with the specified scan code
   84   r{scancode} - a key release event with the specified scan code
   85   t{scancode} - a key press event followed by a pause of 1 millisecond and then a key release event
   86   tU{hex} - a key press event of the specified unicode character followed by a pause of 1 millisecond and then a key release event
   87   mp{number} - a mouse button press event with the specified button number
   88   mr{number} - a mouse button release event with the specified button number
   89   mc{number} - a mouse button press event followed by a pause of 1 millisecond and then a mouse button release event
   90   mwf{clicks} - a forward rotation event of the mouse wheel with the specified number of clicks
   91   mwb{clicks} - a backward rotation event of the mouse wheel with the specified number of clicks
   92   s{milliseconds} - tells Key Scripter to wait for the specified number of milliseconds before doing anything else
   93   q or quit - stops Key Scripter
   94 
   95 A t{scancode} command is handled exactly as the following three commands one after another: p{scancode}, s1, r{scancode}. Mouse button numbers start with 1, with 2 being the right mouse button and 3 the middle. An mc{number} command is handled exactly as the following three commands one after another: mp{number}, s1, mr{number}. Key and mouse event commands also support the following notation: p{scancode}/{milliseconds}, which is handled exactly as the following two commands one after another: s{milliseconds}, p{scancode}.
   96 
   97 For example, the following line instructs Key Scripter to type 'hi!' on the current display:
   98 
   99   echo t43 t31 tU0021 q | key-scripter -o
  100 
  101 When no output is specified, Key Scripter will print key events that it would otherwise send to a display, to the standard output. Here again the same format is used as when reading from the standard input. However, only key and mouse event commands are generated.
  102 
  103 For example, the following line instructs Key Scripter to listen to an input device and print received key events to the standard output:
  104 
  105   On Linux:   key-scripter -i=/dev/input/event2
  106   On Windows: key-scripter -i
  107 
  108 When no configuration file is specified, Key Scripter will pass each received key event as is, either to the specified display or, when no display is specified, to the standard output. With a configuration file available, Key Scripter will only react to those key events that are specified in the configuration. See Creating scripts to find out how to write configuration files.
  109 
  110 
  111 CREATING SCRIPTS
  112 
  113 Many games support key scripting functionality, notably fist-person shooters. However, typically only key press events are supported while key release events are ignored. Key Scripter removes this limitation by providing support for both key event types.
  114 
  115 When no configuration file is specified, Key Scripter simply sends a copy of each received key event to the target display or, when no display is specified, prints a command representing the event to the standard output. With a configuration however, Key Scripter checks whether an action is bound to the received key event. When a bound action is found, it is executed, otherwise the event is ignored. A configuration file can be specified using the -c command-line option (see Usage for a list of available command-line options).
  116 
  117 Note that when Key Scripter is reading from a device, it does not consume events produced by the device. They are still processed by the system, as is the case when Key Scripter is not running. Any fake key events generated by Key Scripter will be processed by the system in addition to the real key events.
  118 
  119 A configuration may contain bind commands, named action declarations, comments and include statements. A semicolon may be used to separate commands for better readability. A single-line comment is text starting with a '#' character or double slash '//', while a multi-line comment is a section of text starting with '/*' and ending with '*/' characters.
  120 
  121 A bind command is specified by the word 'bind' followed by either a key event or a mouse event specification, and ends with a specification of an action. A key event starts with either a 'p' or an 'r' character, depending on whether it represents a press or a release event respectively, and ends with the scan code of the key. Similarly, a mouse event starts with either 'mp' or 'mr' characters, representing a press or a release event respectively, and ends with the button number. Mouse button numbers start with 1, with 2 being the right mouse button and 3 the middle. Mouse wheel events are specified with either mwf or mwb, representing a forward or a backward rotation event respectively. The following example instructs Key Scripter to press the 'p' key for 1 second when the 'q' key is released:
  122 
  123   bind p24 { /* ignored */ }
  124   bind r24 { p33; s1000; r33 } // press 'p' for 1 second when 'q' is released
  125 
  126 Bind commands also support a wildcard notation, such as bind p* or bind r*. Such binds will catch events not currently bound to an action.
  127 
  128 An action may either contain a single command, contain multiple commands to be executed one after another, or be empty. An empty action or an action containing multiple commands must be surrounded by curly brackets. The brackets may be omitted for an action with a single command, such as shown in the following example:
  129 
  130   bind p24 p33 // press 'p' when 'q' is pressed
  131   bind r24 r33 // release 'p' when 'q' is released
  132 
  133 Named actions are declared with the set command. A set command is specified by the word 'set' followed by the name of a new or an existing action and ends with a specification of an action. The name of an action may contain the following characters: a-z, A-Z, 0-9, _, -, +. A named action can be executed from within another action by specifying its name with a '$' character prepended to it:
  134 
  135   bind r24 $press_p // execute the 'press_p' action when 'q' is released
  136   set press_p { p33; s1000; r33; $something_else } // press 'p' for 1 second and then execute the 'something_else' action
  137   set something_else { /* does nothing */ } // executed by the 'press_p' action
  138 
  139 Actions may span multiple lines and include an arbitrary number of spaces:
  140 
  141   set example_action
  142   {
  143       p24 // press 'q'
  144       s50 // wait for 50 milliseconds
  145       r24 // release 'q'
  146 
  147       set example_action // modifies itself
  148       {
  149           p33 // press 'p'
  150           s50 // wait for 50 milliseconds
  151           r33 // release 'p'
  152       }
  153   }
  154 
  155 Both the set and the bind commands can be used to dynamically declare an action or bind an action to a key during execution of Key Scripter. This allows creation of complicated scripts that can modify current key bindings or action declarations while processing received events.
  156 
  157 When a set command is followed by the word 'true' or 'false' instead of an action, it sets a boolean variable with the specified name to either a true or a false value:
  158 
  159   bind p37 { set left_ctrl_is_pressed true }
  160   bind r37 { set left_ctrl_is_pressed false }
  161   bind p50 { set left_shift_is_pressed true }
  162   bind r50 { set left_shift_is_pressed false }
  163 
  164 Such boolean variables may then be used in an if command:
  165 
  166   bind p33 { if left_ctrl_is_pressed and left_shift_is_pressed { /* do something on ctrl+shift+p */ } }
  167 
  168 The initial value of a boolean variable is false. Boolean variables may be chained together with an 'and' or an 'or' word to create a condition containing multiple variables. If a boolean variable is preceded by an '!' character, its value is inverted. An if statement may optionally be followed by an else statement.
  169 
  170 The set {name} {true|false} command also support the following notation: set {name} {true|false}/{milliseconds}. When this notation is used, the value of the boolean variable will be automatically inverted after the specified number of milliseconds. This notation is useful for detecting keystrokes pressed one after another:
  171 
  172   bind r37 set ctrl_released_within_last_second true/1000      // when 'ctrl' is released, set the flag to true for one second
  173   bind p38 if ctrl_released_within_last_second $process-ctrl-a // when 'a' is pressed after ctrl, execute the specified action
  174 
  175 More command types are supported when specified within an action. The following is a list of all supported commands:
  176 
  177   bind p{scancode} {action} - binds an action to a key press event with the specified scan code
  178   bind r{scancode} {action} - binds an action to a key release event with the specified scan code
  179   bind mp{number} {action} - binds an action to a mouse button press event with the specified button number
  180   bind mr{number} {action} - binds an action to a mouse button release event with the specified button number
  181   bind mwf {action} - binds an action to a forward rotation event of the mouse wheel
  182   bind mwb {action} - binds an action to a backward rotation event of the mouse wheel
  183   unbind p{scancode} - binds an empty action to the specified key press event
  184   unbind r{scancode} - binds an empty action to the specified key release event
  185   unbind mp{number} - binds an empty action to the specified mouse button press event
  186   unbind mr{number} - binds an empty action to the specified mouse button release event
  187   unbind mwf - binds an empty action to a forward rotation event of the mouse wheel
  188   unbind mwb - binds an empty action to a backward rotation event of the mouse wheel
  189   set {name} {action} - assigns the specified action to a new or an existing action with the specified name
  190   clear {name} - assigns an empty action to a new or an existing action with the specified name
  191   set {name} {true|false} - assigns a true or a false value to a boolean variable with the specified name
  192   set {name} {true|false}/{milliseconds} - assigns a true or a false value to a boolean variable with the specified name for the specified number of milliseconds
  193   toggle {name} - inverts the value of a boolean variable with the specified name
  194   if {condition} {action} - executes the specified action if the specified condition is true
  195   if {condition} {action A} else {action B} - executes action A if the specified condition is true, otherwise executes action B
  196   p{scancode} - generates a key press event with the specified scan code
  197   r{scancode} - generates a key release event with the specified scan code
  198   t{scancode} - generates a key press event, waits for 1 millisecond and then generates a key release event
  199   tU{hex} - generates a key press event of the specified unicode character, waits for 1 millisecond and then generates a key release event
  200   mp{number} - generates a mouse button press event with the specified button number
  201   mr{number} - generates a mouse button release event with the specified button number
  202   mc{number} - generates a mouse button press event, waits for 1 millisecond and then generates a mouse button release event
  203   mwf{clicks} - generates a forward rotation event of the mouse wheel with the specified number of clicks
  204   mwb{clicks} - generates a backward rotation event of the mouse wheel with the specified number of clicks
  205   s{milliseconds} - waits for the specified number of milliseconds before doing anything else
  206   debug "{message}" - prints the specified debug message to the standard error output
  207   disable - disables event generation; incoming events are still processed
  208   enable - enables event generation
  209   quit - stops Key Scripter
  210 
  211 A t{scancode} command is handled exactly as the following three commands one after another: p{scancode}, s1, r{scancode}. An mc{number} command is handled exactly as the following three commands one after another: mp{number}, s1, mr{number}. Key and mouse event commands also support the following notation: p{scancode}/{milliseconds}, which is handled exactly as the following two commands one after another: s{milliseconds}, p{scancode}.
  212 
  213 If a configuration file becomes too long, it may be better to split it into several smaller files. These smaller files can then be combined into a single configuration by specifying all or some of them in a master configuration file using include statements. Creating a special configuration per application becomes easier this way, because such a configuration doesn't need to contain a full copy of each script, it can simply point to the file the script is defined in.
  214 
  215 An include statement is specified by the word 'include' followed by the name of the configuration file surrounded by double quotes. If the file name contains a relative path or doesn't specify any path at all, it is considered relative to the parent configuration file. The following is an example of an include statement:
  216 
  217   include "file name"
  218 
  219 When loading a configuration file, Key Scripter stops if a syntax error is encountered. The line and column number of the invalid content is printed to the standard error output. However, even when loaded successfully, a complex configuration file may still contain errors that are only visible during execution of Key Scripter. In order to simplify searching for such hard-to-find errors, Key Scripter provides the -d command-line option (see Usage for a list of available command-line options). When this option is enabled, Key Scripter prints debug messages to the standard error output, describing each executed command and informing when each executed named action begins or ends.