Skip to content

Commit

Permalink
Modernize docs regarding game controllers (#645)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ragnar-F
Ragnar-F committed May 25, 2023
1 parent 7f8cac9 commit 0911f34
Show file tree
Hide file tree
Showing 19 changed files with 283 additions and 250 deletions.
12 changes: 6 additions & 6 deletions docs/Hotkeys.htm
View file
Expand Up @@ -11,7 +11,7 @@
</head>
<body>

<h1>Hotkeys <span class="headnote">(Mouse, Joystick and Keyboard Shortcuts)</span></h1>
<h1>Hotkeys <span class="headnote">(Mouse, Controller and Keyboard Shortcuts)</span></h1>


<h2 id="toc">Table of Contents</h2>
Expand Down Expand Up @@ -126,14 +126,14 @@ <h2 id="Symbols">Hotkey Modifier Symbols</h2>
*LWin Up::Send {LControl up}
</pre>
<p>"Up" can also be used with normal hotkeys as in this example: <code>^!r Up::MsgBox You pressed and released Ctrl+Alt+R</code>. It also works with <a href="#combo">combination hotkeys</a> (e.g. <code>F1 &amp; e Up::</code>)</p>
<p>Limitations: 1) "Up" does not work with <a href="KeyList.htm">joystick buttons</a>; and 2) An "Up" hotkey without a normal/down counterpart hotkey will completely take over that key to prevent it from getting stuck down. One way to prevent this is to add a <a href="#Tilde">tilde prefix</a> (e.g. <code>~LControl up::</code>)</p>
<p>Limitations: 1) "Up" does not work with <a href="KeyList.htm#Controller">controller buttons</a>; and 2) An "Up" hotkey without a normal/down counterpart hotkey will completely take over that key to prevent it from getting stuck down. One way to prevent this is to add a <a href="#Tilde">tilde prefix</a> (e.g. <code>~LControl up::</code>)</p>
<p>"Up" hotkeys and their key-down counterparts (if any) always use the keyboard hook.</p>
<p>On a related note, a technique similar to the above is to make a hotkey into a prefix key. The advantage is that although the hotkey will fire upon release, it will do so only if you did not press any other key while it was held down. For example:</p>
<pre>LControl &amp; F1::return <em>; Make left-control a prefix by using it in front of "&amp;" at least once.</em>
LControl::MsgBox You released LControl without having used it to modify any other key.</pre></td>
</tr>
</table>
<p class="note"><strong>Note</strong>: See the <a href="KeyList.htm">Key List</a> for a complete list of keyboard keys and mouse/joystick buttons.</p>
<p class="note"><strong>Note</strong>: See the <a href="KeyList.htm">Key List</a> for a complete list of keyboard keys and mouse/controller buttons.</p>
<p>Multiple hotkeys can be stacked vertically to have them perform the same action. For example:</p>
<pre>^Numpad0::
^Numpad1::
Expand All @@ -158,7 +158,7 @@ <h2 id="Context">Context-sensitive Hotkeys</h2>

<h2 id="combo">Custom Combinations</h2>
<p>Normally shortcut key combinations consist of optional prefix/modifier keys (Ctrl, Alt, Shift and LWin/RWin) and a single suffix key. The standard modifier keys are designed to be used in this manner, so normally have no immediate effect when pressed down.</p>
<p>A custom combination of two keys (including mouse but not joystick buttons) can be defined by using " &amp; " between them. Because they are intended for use with prefix keys that are not normally used as such, custom combinations have the following special behavior:</p>
<p>A custom combination of two keys (including mouse but not controller buttons) can be defined by using " &amp; " between them. Because they are intended for use with prefix keys that are not normally used as such, custom combinations have the following special behavior:</p>
<ul>
<li>The prefix key loses its native function, unless it is a standard modifier key or toggleable key such as <kbd>CapsLock</kbd>.</li>
<li>If the prefix key is also used as a suffix in another hotkey, by default that hotkey is fired upon release, and is not fired at all if it was used to activate a custom combination. <span class="ver">[v1.1.14+]:</span> If there is both a key-down hotkey and a <a href="#keyup">key-up</a> hotkey, both hotkeys are fired at once. The fire-on-release effect is disabled if the <a href="#Tilde">tilde prefix</a> is applied to the prefix key in at least one active custom combination or the suffix hotkey itself.</li>
Expand Down Expand Up @@ -229,11 +229,11 @@ <h2 id="Remarks">Hotkey Tips and Remarks</h2>
RButton &amp; WheelUp::MsgBox You turned the mouse wheel up while holding down the right button.</pre>
<p>The <a href="lib/Suspend.htm">Suspend</a> command can temporarily disable all hotkeys except for ones you make exempt. For greater selectivity, use <a href="lib/_IfWinActive.htm">#IfWinActive/Exist</a>.</p>
<p>By means of the <a href="lib/Hotkey.htm">Hotkey</a> command, hotkeys can be created dynamically while the script is running. The Hotkey command can also modify, disable, or enable the script's existing hotkeys individually.</p>
<p>Joystick hotkeys do not currently support modifier prefixes such as ^ (Ctrl) and # (Win). However, you can use <a href="lib/GetKeyState.htm#function">GetKeyState</a> to mimic this effect as shown in the following example:</p>
<p>Controller hotkeys do not currently support modifier prefixes such as ^ (Ctrl) and # (Win). However, you can use <a href="lib/GetKeyState.htm#function">GetKeyState</a> to mimic this effect as shown in the following example:</p>
<pre>Joy2::
if not GetKeyState("Control") <em>; Neither the left nor right Control key is down.</em>
return <em>; i.e. Do nothing.</em>
MsgBox You pressed the first joystick's second button while holding down the Control key.
MsgBox You pressed the first controller's second button while holding down the Control key.
return</pre>
<p>There may be times when a hotkey should wait for its own modifier keys to be released before continuing. Consider the following example:</p>
<pre>^!s::Send {Delete}</pre>
Expand Down
41 changes: 22 additions & 19 deletions docs/KeyList.htm
View file
@@ -1,16 +1,16 @@
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>List of Keys (Keyboard, Mouse and Joystick) | AutoHotkey</title>
<meta name="description" content="This page lists all mouse buttons, keyboard keys and joystick buttons which can be used for hotkeys and key-specific commands/functions." />
<meta name="keywords" content="keyboard,keys,key,mouse,buttons,button,joystick,create,hotkeys,hotkey,macros">
<title>List of Keys (Keyboard, Mouse and Controller) | AutoHotkey</title>
<meta name="description" content="This page lists all mouse buttons, keyboard keys and controller buttons which can be used for hotkeys and key-specific commands/functions." />
<meta name="keywords" content="keyboard,keys,key,mouse,buttons,button,controller,gamepad,joystick,create,hotkeys,hotkey,macros">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="static/theme.css" rel="stylesheet" type="text/css" />
<script src="static/content.js" type="text/javascript"></script>
</head>
<body>
<h1>List of Keys <span class="headnote">(Keyboard, Mouse and Joystick)</span></h1>
<h1>List of Keys <span class="headnote">(Keyboard, Mouse and Controller)</span></h1>
<h2 id="toc">Table of Contents</h2>
<ul>
<li><a href="#mouse">Mouse</a>
Expand All @@ -31,7 +31,7 @@ <h2 id="toc">Table of Contents</h2>
<li><a href="#other">Other Keys</a></li>
</ul>
</li>
<li><a href="#Joystick">Joystick</a></li>
<li><a href="#Controller">Game Controller (Gamepad, Joystick, etc.)</a></li>
<li><a href="#remote">Hand-held Remote Controls</a></li>
<li><a href="#SpecialKeys">Special Keys</a></li>
<li><a href="#IME">CapsLock and IME</a></li>
Expand Down Expand Up @@ -444,25 +444,28 @@ <h3 id="other">Other Keys</h3>
</td>
</tr>
</table>
<h2 id="Joystick">Joystick</h2>
<p><strong>Joy1 through Joy32</strong>: The buttons of the joystick. To help determine the button numbers for your joystick, use this <a href="scripts/index.htm#JoystickTest">test script</a>. Note that <a href="Hotkeys.htm">hotkey prefix symbols</a> such as ^ (control) and + (shift) are not supported (though <a href="lib/GetKeyState.htm#function">GetKeyState()</a> can be used as a substitute). Also note that the pressing of joystick buttons always "passes through" to the active window if that window is designed to detect the pressing of joystick buttons.</p>
<p>Although the following Joystick control names cannot be used as hotkeys, they can be used with <a href="lib/GetKeyState.htm#function">GetKeyState()</a>:</p>
<a id="Joystick"></a>
<h2 id="Controller">Game Controller (Gamepad, Joystick, etc.)</h2>
<p class="note"><strong>Note:</strong> For historical reasons, the following button and control names begin with <code>Joy</code>, which stands for joystick. However, they usually also work for other game controllers such as gamepads or steering wheels.</p>
<p><strong>Joy1 through Joy32</strong>: The buttons of the controller. To help determine the button numbers for your controller, use this <a href="scripts/index.htm#ControllerTest">test script</a>. Note that <a href="Hotkeys.htm">hotkey prefix symbols</a> such as ^ (control) and + (shift) are not supported (though <a href="lib/GetKeyState.htm#function">GetKeyState()</a> can be used as a substitute). Also note that the pressing of controller buttons always "passes through" to the active window if that window is designed to detect the pressing of controller buttons.</p>
<p>Although the following control names cannot be used as hotkeys, they can be used with <a href="lib/GetKeyState.htm#function">GetKeyState()</a>:</p>
<ul>
<li><strong>JoyX, JoyY, and JoyZ</strong>: The X (horizontal), Y (vertical), and Z (altitude/depth) axes of the joystick.</li>
<li><strong>JoyR</strong>: The rudder or 4th axis of the joystick.</li>
<li><strong>JoyU and JoyV</strong>: The 5th and 6th axes of the joystick.</li>
<li><strong>JoyX, JoyY, and JoyZ</strong>: The X (horizontal), Y (vertical), and Z (altitude/depth) axes of the controller.</li>
<li><strong>JoyR</strong>: The rudder or 4th axis of the controller.</li>
<li><strong>JoyU and JoyV</strong>: The 5th and 6th axes of the controller.</li>
<li><strong>JoyPOV</strong>: The point-of-view (hat) control.</li>
<li><strong>JoyName</strong>: The name of the joystick or its driver.</li>
<li><strong>JoyButtons</strong>: The number of buttons supported by the joystick (not always accurate).</li>
<li><strong>JoyAxes</strong>: The number of axes supported by the joystick.</li>
<li><strong>JoyInfo</strong>: Provides a string consisting of zero or more of the following letters to indicate the joystick's capabilities: <strong>Z</strong> (has Z axis), <strong>R</strong> (has R axis), <strong>U</strong> (has U axis), <strong>V</strong> (has V axis), <strong>P</strong> (has POV control), <strong>D</strong> (the POV control has a limited number of discrete/distinct settings), <strong>C</strong> (the POV control is continuous/fine). Example string: ZRUVPD</li>
<li><strong>JoyName</strong>: The name of the controller or its driver.</li>
<li><strong>JoyButtons</strong>: The number of buttons supported by the controller (not always accurate).</li>
<li><strong>JoyAxes</strong>: The number of axes supported by the controller.</li>
<li><strong>JoyInfo</strong>: Provides a string consisting of zero or more of the following letters to indicate the controller's capabilities: <strong>Z</strong> (has Z axis), <strong>R</strong> (has R axis), <strong>U</strong> (has U axis), <strong>V</strong> (has V axis), <strong>P</strong> (has POV control), <strong>D</strong> (the POV control has a limited number of discrete/distinct settings), <strong>C</strong> (the POV control is continuous/fine). Example string: ZRUVPD</li>
</ul>
<p><strong>Multiple Joysticks</strong>: If the computer has more than one joystick and you want to use one beyond the first, include the joystick number (max 16) in front of the control name. For example, 2joy1 is the second joystick's first button.</p>
<p class="note"><strong>Note</strong>: If you have trouble getting a script to recognize your joystick, one person reported needing to specify a joystick number other than 1 even though only a single joystick was present. It is unclear how this situation arises or whether it is normal, but experimenting with the joystick number in the <a href="scripts/index.htm#JoystickTest">joystick test script</a> can help determine if this applies to your system.</p>
<p>For example, when using Xbox Wireless/360 controllers, JoyX/JoyY is the left stick, JoyR/JoyU the right stick, JoyZ the left and right triggers, and JoyPOV the directional pad (D-pad).</p>
<p><strong>Multiple controllers</strong>: If the computer has more than one controller and you want to use one beyond the first, include the controller number (max 16) in front of the control name. For example, 2joy1 is the second controller's first button.</p>
<p class="note"><strong>Note</strong>: If you have trouble getting a script to recognize your controller, specify a controller number other than 1 even though only a single controller is present. It is unclear how this situation arises or whether it is normal, but experimenting with the controller number in the <a href="scripts/index.htm#ControllerTest">controller test script</a> can help determine if this applies to your system.</p>
<p><strong>See Also</strong>:</p>
<ul>
<li><a href="misc/RemapJoystick.htm">Joystick remapping:</a> Methods of sending keystrokes and mouse clicks with a joystick.</li>
<li><a href="scripts/index.htm#JoystickMouse">Joystick-To-Mouse script</a>: Using a joystick as a mouse.</li>
<li><a href="misc/RemapController.htm">Controller remapping:</a> Methods of sending keystrokes and mouse clicks with a controller.</li>
<li><a href="scripts/index.htm#ControllerMouse">Controller-To-Mouse script</a>: Using a controller as a mouse.</li>
</ul>

<h2 id="remote">Hand-held Remote Controls</h2>
Expand Down
4 changes: 2 additions & 2 deletions docs/Tutorial.htm
View file
Expand Up @@ -200,8 +200,8 @@ <h3 id="s21">a. Keys and their mysterious symbols</h3>
</tr>
</table>
<p><strong>(For the full list of symbols, see the <a href="Hotkeys.htm">Hotkey</a> page)</strong></p>
<p>Additionally, for a list of all/most hotkey names that can be used on the <b>left</b> side of a hotkey's double-colon, see <a href="KeyList.htm">List of Keys, Mouse Buttons, and Joystick Controls</a>.</p>
<p>You can define a custom combination of two (and only two) keys (except joystick buttons) by using <code> &amp; </code> between them. In the example below, you would hold down Numpad0 then press Numpad1 or Numpad2 to trigger one of the hotkeys:</p>
<p>Additionally, for a list of all/most hotkey names that can be used on the <b>left</b> side of a hotkey's double-colon, see <a href="KeyList.htm">List of Keys, Mouse Buttons, and Controller Controls</a>.</p>
<p>You can define a custom combination of two (and only two) keys (except controller buttons) by using <code> &amp; </code> between them. In the example below, you would hold down Numpad0 then press Numpad1 or Numpad2 to trigger one of the hotkeys:</p>

<pre>Numpad0 &amp; Numpad1::
MsgBox, You pressed Numpad1 while holding down Numpad0.
Expand Down
4 changes: 2 additions & 2 deletions docs/index.htm
View file
Expand Up @@ -38,10 +38,10 @@ <h2 id="Quick_Reference">Quick Reference</h2>
</ul>
<p>Keyboard and mouse:</p>
<ul>
<li><a href="Hotkeys.htm">Hotkeys (mouse, joystick and keyboard shortcuts)</a></li>
<li><a href="Hotkeys.htm">Hotkeys (mouse, controller and keyboard shortcuts)</a></li>
<li><a href="Hotstrings.htm">Hotstrings and auto-replace</a></li>
<li><a href="misc/Remap.htm">Remapping keys and buttons</a></li>
<li><a href="KeyList.htm">List of keys, mouse buttons and joystick controls</a></li>
<li><a href="KeyList.htm">List of keys, mouse buttons and controller controls</a></li>
</ul>
<p>Other:</p>
<ul>
Expand Down

0 comments on commit 0911f34

Please sign in to comment.