Keyboard And Documentation update (#469)

* changed action names * updated settings for new action key * updated keyboard input guide * updated readme top * updated appveyor link * fixed qml issue and some formatting * updated screenshots * updated documentation portion of readme * fix qml issues
2020-06-06 14:18:21 -05:00
parent 3857c2ac2f
commit 88a1c002c4
20 changed files with 194 additions and 93 deletions
@@ -1,55 +1,128 @@
-## Sending keypresses from VR to the desktop
+# Keyboard Input Guide

-The `Keyboard Shortcut One`, `Keyboard Shortcut Two` and `Keyboard Shortcut Three` actions under the `misc` tab will send the currently configured key sequence to the operating system.
+## Capabilities
+ We provide two distinct types of functionality, `Keyboard Shortcut`'s [macros] and `Key Press`'s [individual key press]
+ 
+### Keyboard Shortcuts
+ 
+- Sends One or Many keys to the OS like a macro.
+- Cannot `hold` keys down
+  - Except in the case of Modifiers (alt, ctrl, etc.)

-The default keybinding for all three actions is `Ctrl+Shift+M`, which mutes your microphone in Discord (unless you've changed it).
-This sequence can be changed to anything you want, as described in the [spec](specs/Keyboard_Manager-Parser_Spec.md).
-An easier to read version of the spec can be found below.
+### Key Press

-The hotkeys can for example be configured to run an AutoHotKey script or mute VOIP applications.
+- Sends One and only One key to the OS.
+ - Extra Keys Will be Ignored
+- Mirrors button state on controller
+  - If you hold down `a` on a controller the `key` will be held down
+  - If you release `a` on a controller the `key` will be released
+- `Key Press System`
+  - This Action will ALWAYS be use-able while OVRAS is running
+- `Key Press Misc.`
+  - This Action MAY not always be use-able depending on other Settings/Binds*
+    - Pending a future update.

-### Changing the key sequences
+## How To Set

-Currently, the only way to change which sequences are run when the bindings are activated is directly through the settings file.
+- Go to the Settings File
+  - Windows: `%Appdata%\AdvancedSettings-Team` (`C:\Users\<username>\AppData\Roaming\AdvancedSettings-Team`)
+  - Linux: `~/.config/AdvancedSettings-Team/`
+- open `OVR Advanced Settings.ini` with a text editor
+- Go to `[keyboardShortcuts]`
+- Add your sequence right after the `=` for the action you want.
+  - By Default Keyboard's are set to ctrl+shift+m `^>m`
+  - By Default Key Press's are set to F9 `F9`
+  - Example for ctrl+alt+delete for keyboardOne Action
+    - `keyboardOne=^*DEL`
+  - Example for Key Press System for a`
+    - `keyPressSystem=a`
+	
+## Supported Keys

-On Windows the settings file can be found in `%APPDATA%\AdvancedSettings-Team` (copy paste this into Explorer or the Run command).
+### Modifier symbols

-On Linux the settings file can be found in `~/.config/AdvancedSettings-Team/`.
+| Modifier | Symbol |
+|---|---|
+| Ctrl | `^` |
+| Alt | `*` |
+| Shift | `>` |
+| Super (Windows) | `#` |

-The `OpenVRAdvancedSettings.ini` file will contain a heading like
-```
-[keyboardShortcuts]
-keyboardOne=^>m
-keyboardTwo=^>m
-keyboardThree=^>m
-```
-The character _after_ the `=` will be run when the related binding is activated.
-The above key sequence for all bindings is `^>m` (`Ctrl+Shift+M`).
-An empty binding (no input will be run) would be `keyboardOne=`.
+### Literal symbols

-### Simple Configuration
+| Key | Symbol |
+|---|---|
+| A to Z | The letter in lowercase. `a`, `b`, `c`, ... |
+| Number Row 0-9 | The number. `0`, `1`, `2`, ... |
+| Function keys F1-F9 | Capital F followed by number. `F1`, `F2`, `F3`, ... |
+| Backspace | `BACKSPACE` |
+| Space | `SPACE` |
+| Tab | `TAB` |
+| Escape | `ESC` |
+| Insert | `INS` |
+| Delete | `DEL` |
+| End | `END` |
+| Page Down | `PGDN` |
+| Page Up | `PGUP` |
+| Caps Lock | `CAPS` |
+| Print Screen | `PRNSCRN` |
+| Pause/Break | `PAUSE` |
+| Scroll Lock | `SCRLOCK` |
+| Left Arrow | `LEFTARROW` |
+| Right Arrow | `RIGHTARROW` |
+| Up Arrow | `UPARROW` |
+| Down Arrow | `DOWNARROW` |
+| Keypad Slash | `KPSLASH` |
+| Keypad Asterisk | `KPSTAR` |
+| Keypad Minus | `KPMINUS` |
+| Keypad Plus | `KPPLUS` |
+| Enter | `ENTER` |

-Simply changing the last key of the default bindings should be enough for most people.
-Remember that you will also need to set up the application (Discord, Mumble, TeamSpeak, etc.) to respond to the key sequence.
-Single characters _must_ be lower case.
-If you enter them as uppercase it will be treated as an error, and only correct keys up to the error point will be sent to the OS.

-The default configuration is `^>m` for all bindings. Change the letter (`m`) to the character you want.
-For example, if you want Keyboard Shortcut Two to be `Ctrl+Shift+X` you would write `keyboardTwo=^>x`.
-If you just want it to be `Ctrl+X` you would remove the `>` symbol and just write `keyboardTwo=^m`.
+### Misc symbols
+| Action | Symbol |
+|---|---|
+| Release Held Keys | ` ` (literal space or end of string) |

-Notice that all pressed keys are released again when the sequence is over. 
-It is not possible to hold down keys.

-### Advanced Configuration
+## Examples

-Look at the key table [spec](specs/Keyboard_Manager-Parser_Spec.md) and find the keys that you want to press.
+### Keyboard Examples

-Notice that single characters (a, b, c, etc.) are lower case, while buttons are uppercase (ENTER, END, ESC, etc.). 
-If you enter single letters as upper case it will not work.
-Buttons are pressed and released immediately, modifiers are held until there's a space in the sequence or the sequence ends.
+| Sequence | String | Key Representation |
+|---|---|---|
+| Ctrl + H | `^h` | Ctrl+, h+, h-, Ctrl- |
+| Ctrl + H + H | `^hh` | Ctrl+, h+, h-, h+, h-, Ctrl- |
+| Ctrl + H twice | `^h ^h` | Ctrl+, h+, h-, Ctrl-, Ctrl+, h+, h-, Ctrl- |
+| Ctrl + Alt + Delete | `^*DEL` | Ctrl+, Alt+, DEL+, DEL-, Ctrl-, Alt- |
+| Alt + Enter | `*ENTER` | Alt+, ENTER+, ENTER-, Alt- |
+| H + E + L + P | `help` | h+, h-, e+, e-, l+, l-, p+, p- |
+| E + N + D | `end` | e+, e-, n+, n-, d+, d- |
+| END Button | `END` | END+, END- |
+| Alt + Shift + ENTER | `*>ENTER` | Alt+, Shift+, ENTER+, ENTER-, Alt-, Shift- |
+| Alt + Tab + G + G + ENTER + Alt + Tab | `*TAB gg ENTER *TAB` | Alt+, Tab+, Tab-, Alt-, g+, g-, g+, g-, ENTER+, ENTER-, Alt+, Tab+, Tab-, Alt- |

-The modifier keys should come before the "real" button inputs.
-`^m` (`Ctrl+M` (Ctrl is held down, M is pressed and released, Ctrl is released)) is _not_ the same as `m^` (`M+Ctrl` (M is pressed and released, Ctrl is pressed and released)).

-Spaces mean that all currently held modifier keys are released and that a new sequence is ready to be parsed. For example `^a ^a` would press `Ctrl+A` two times.
+### Key Press Examples
+
+| Sequence | String | Key Rep On Press | Key Rep on Release
+|---|---|---|---|
+| Ctrl | `^` | Ctrl+ | Ctrl- |
+| H | `h` | h+ | h- |
+| Ctrl + H | `^h` | Ctrl+ | Ctrl- |
+
+
+## Common Issues
+
+### Case Sensative
+- basic characters are all LOWER case, while keys such as ENTER are all UPPER case.
+
+### Focus Issues
+- we deliver the keypress to the OS, depending on your set-up and program you may have to have the window "in-focus"
+
+### Multiple Key Events
+- you must separate multiple events with a space (` `)
+ - alt + tab, alt + F4 = `*TAB *F4`
+
+## Parser Spec
+(Parser Spec)[https://github.com/OpenVR-Advanced-Settings/OpenVR-AdvancedSettings/blob/master/docs/specs/Keyboard_Manager-Parser_Spec.md]