Joystick to keyboard mapping and secondary BBC joystick support

.gitignore

@@ -1,4 +1,5 @@
 *.user
+.vs
 Src/.vs
 Src/BeebEm.aps
 Src/BeebEm.VC.db

Documents/JoystickMap.txt

@@ -0,0 +1,70 @@
+*** BeebEm Joystick Map ***
+
+# Joystick map file begins with special marker line as above.
+# All empty lines and lines starting with '#' are ignored.
+
+# Remaining lines must consist of two or three tokens separated with
+# whitespace.
+# All names are case insensitive except for the marker in the first line.
+
+# Two-token lines are:
+# <Joystick input>  <BBC Key>
+# Three-token lines are:
+# <Joystick input>  <BBC Key for unshifted> <BBC Key for shifted>
+
+# These two lines define the same mapping:
+# Joy1Up   A
+# Joy1Up   A   SH+A
+
+# BBC Key names prefixed with 'SH+' indicate shifted key press.
+# In the two-token lines, the 'SH+' prefix is allowed, but ignored.
+
+# Special BBC key names are:
+# LEFT, RIGHT, UP, DOWN, BREAK, COPY, DELETE, CAPS-LOCK, TAB, CTRL
+# SPACE, RETURN, ESCAPE, SHIFT, SHIFT-LOCK
+# Allowed aliases:
+# DEL, CAPS, CAPSLOCK, CONTROL, ESC, SHIFTLOCK
+
+# All other BBC keys are named by their unshifted character (i.e. 'SH+[' not '{')
+# Function keys are named, as one would expect, 'F0' to 'F9'
+
+# Joystick inputs have the form Joy[X][Act] where [X] is the joystick number
+# and [Act] is the action name. Axis and button assignments differ between
+# joystick or gamepad models.
+
+# Xbox 360 controller has following assignments
+# (with DIJOYSTATE2 fields in the middle column):
+# Left, Right, Up, Down             - lX, lY     - Left Analog Left, Right, Up, Down
+# Z+,Z-                             - lZ         - Left Trigger, Right Trigger
+# RLeft, RRight, RUp, RDown         - lRx, lRy   - Right Analog Left, Right, Up, Down
+# HatLeft, HatRight, HatUp, HatDown - rgdwPOV[0] - Hat Up, Down, Left, Right
+# Btn1-4                                         - A, B, X, Y
+# Btn5,6                                         - Left Shoulder, Right Shoulder
+# Btn7,8                                         - Back, Start
+# Btn9,10                                        - Left Thumbstick, Right Thumbstick
+
+# Other common layout:
+# Left, Right, Up, Down             - lX, lY     - Left Analog Left, Right, Up, Down
+# RLeft, RRight, RUp, RDown         - lZ, lRz    - Right Analog Left, Right, Up, Down
+# HatLeft, HatRight, HatUp, HatDown - rgdwPOV[0] - Hat Up, Down, Left, Right
+# Btn1-4                                         - Y, B, A, X
+# Btn5,6                                         - Left Shoulder, Right Shoulder
+# Btn7,8                                         - Left Trigger, Right Trigger
+# Btn9,10                                        - Select/Back, Start
+# Btn11,12                                       - Left Thumbstick, Right Thumbstick
+# Btn13                                          - Home
+
+# Sample mapping for Chuckie Egg
+
+Joy1Up        A
+Joy1Down      Z
+Joy1Left      ,
+Joy1Right     .
+Joy1HatUp     A
+Joy1HatDown   Z
+Joy1HatLeft   ,
+Joy1HatRight  .
+Joy1Btn1      SPACE
+Joy1Btn6      RETURN
+Joy1Btn7      1
+Joy1Btn8      S

Help/keyboard.html

@@ -10,7 +10,7 @@
   <table width="100%" border="0" cellpadding="2" cellspacing="2">
     <tr>
       <td width="100">
-        <p align="center"><img src="beeb.gif" name="BeebEm" alt="BBC Micro" 
+        <p align="center"><img src="beeb.gif" name="BeebEm" alt="BBC Micro"
                                align="middle" width="48" height="48" border="0" /></p>
       </td>
 
@@ -204,7 +204,7 @@ <h2>Custom Key Mappings</h2>
 <ol>
 <li>If you are in full screen mode then switch back to Windowed mode.</li>
 
-<li>Select menu item "Options -> Define User Key Mapping".  A graphic
+<li>Select menu item "Options &rarr; Define User Key Mapping".  A graphic
     showing the BBC keyboard layout will appear within the BeebEm
     interface.</li>
 
@@ -228,16 +228,104 @@ <h2>Custom Key Mappings</h2>
 
 <li>Repeat from step 3 for other keys you want to map.</li>
 
-<li>Save your mapping using menu item "Options -> Save User Key Mapping".
+<li>Save your mapping using menu item "Options &rarr; Save User Key Mapping".
     You can write over the default user key mapping file (DefaultUser.kmap)
     or save a new file.</li>
 
-<li>Select your mapping using menu item "Options -> User Defined Mapping".
+<li>Select your mapping using menu item "Options &rarr; User Defined Mapping".
 	You can also use the "Save Preferences" option to save the default user
 	key mapping file that gets loaded when BeebEm starts up.</li>
 </ol>
 
-      <!-- End of content -->
+<h2>Mapping PC Joystick to BBC Keys</h2>
+
+<p>To enable translating PC joystick actions to BBC keys, use menu item
+   "Options &rarr; Joystick To Keyboard &rarr; Enable Joystick To Keyboard".
+   BeemEm supports mapping up to four joysticks or gamepads to BBC keys,
+   with each joystick actions (button presses or stick movements)
+   mapped separately.</p>
+
+<p>Creating mapping of PC joystick movements and buttons to BBC keys is
+   similar to creating custom key mappings:</p>
+
+<ol>
+<li>If you are in full screen mode then switch back to Windowed mode.</li>
+
+<li>Select menu item "Options &rarr; Joystick To Keyboard &rarr; Define Joystick Mapping".
+    A graphic showing the BBC keyboard layout will appear within the BeebEm
+    interface. BBC keys which already have assigned joystick actions will be
+    highlighted with light blue colour.</li>
+
+<li>Use your mouse pointer to click once on the BBC key that you are
+    attempting to map to your joystick or gamepad.</li>
+
+<li>Press the joystick button or move the joystick in the direction that you want
+    to map to the unshifted BBC key press, or click "OK" to skip that part.
+    If you want to map shifted joystick action to unshifted BBC key press, enable
+    the "Shift" checkbox before moving the joystick.</li>
+
+<li>Press the joystick button or move the joystick in the direction that you want
+    to map to the shifted BBC key press, or click "OK" to skip that part.
+    If you want to map unshifted joystick action to shifted BBC key press, disable
+    the "Shift" checkbox before moving the joystick.</li>
+
+<li>Repeat from step 3 for other keys you want to map.</li>
+
+<li>Save your mapping using menu item
+    "Options &rarr; Joystick To Keyboard &rarr; Save Joystick Mapping...".
+    You can save your mapping as the default user joystick mapping file
+    (DefaultUser.jmap) or save to a different file. If you are creating
+    a game-specific joystick mapping, save the mapping in the same
+    directory and with the same name as your game disk image, with extension
+    changed to ".jmap". This will make BeebEm automatically use the joystick
+    mapping for that disk image, if that is enabled with menu item
+    "Options &rarr; Joystick To Keyboard &rarr; Autoload Joystick Mapping".</li>
+</ol>
+
+<p>As with PC keys, you can map joystick actions to BBC keys in shifted and
+   unshifted state separately.  The most common scenario is to assign a
+   joystick action to the same BBC key in both shifted and unshifted state.
+   To do that, just click on the BBC key that you want to map, and move
+   joystick or press button twice - once for unshifted and second time for
+   shifted state.</p>
+
+<p>Additionally, you can assign one or more joystick buttons to the SHIFT key.
+   This can be used to assign one joystick button as a modifier for
+   other joystick actions, which can be useful for games that have a lot of
+   keyboard contols.</p>
+
+<p>PC joystick to BBC keyboard mapping is independent from enabling PC joystick
+   acting as BBC joystick.  If you enable both, primary PC joystick axes
+   (primary stick up, down, left and right) and first two buttons are mapped
+   to BBC joystick.  You can map other axes and buttons to BBC keys. You can
+   map those axes and buttons which are acting as BBC joystick to BBC
+   keys as well. In that case, the PC joystick action will be seen as both BBC
+   joystick action and BBC key press.</p>
+
+<p>To remove mapping from previously mapped joystick action, click on the
+   'Unassign' button.  It will display small window and wait for the
+   joystick action.  Press the joystick button or move the joystick in the
+   direction that you want to unmap.  The same window will be displayed again,
+   giving you the opportunity to unmap the joystick action in both unshifted
+   and shifted state at one go.  You can press the "OK" button to skip the
+   second unassignment.</p>
+
+<p>At start up BeebEm loads DefaultUser.jmap from the User Data Folder, if such
+   file was created by user. If this file is not present, all joystick actions
+   start unassigned.</p>
+
+<p>Menu item "Options &rarr; Joystick To Keyboard &rarr; Autoload Joystick Mapping"
+   toggles Autoload Joystick Mapping option. If this option is enabled, BeebEm
+   will automatically look for joystick mapping file based on name of image
+   file started from "File &rarr; Run Disc.." or "File &rarr; Load Tape..." menu item,
+   or from command-line. The sought mapping file has the same name and
+   directory as loaded image, but extension changed to ".jmap". If no such
+   file is found, joystick mapping is reset to default - either empty, or that
+   from "DefaultUser.jmap" file. If the Autoload Joystick Mapping option is
+   enabled, the "Save Joystick Mapping..." dialog will automatically suggest
+   correct file name for currently loaded image file.</p>
+
+         <!-- End of content -->
       </td>
 
       <td width="10%"></td>