Gamepad/Joystick et al.: Improve docs, help, setup instructions.

Joystick() Reenable warning to use Gamepad() instead, but as a one-time
warning. Improve help texts for Gamepad() and HatXXX() functions.

Gamepad: On Ubuntu 20.04 LTS and later, name of the joystick xorg driver
is xserver-xorg-input-joystick, not something with hwe-20.04 etc. suffix,
as the X-Server Input abi has not changed from v24 since at least X-Server
1.19 up to and including X-Server 21.x.

Psychtoolbox/PsychHardware/PsychGamepad/Gamepad.m

@@ -36,26 +36,12 @@
 % device with multiple extra axes and buttons. You should install the optional
 % joystick driver, although the evdev driver may also work with suitable configuration.
 %
-% This joystick driver has different names, depending on the version of the Ubuntu
-% distribution you are using, and if the hardware enablement stack (HWE) is installed.
-% You can usually find out if the HWE is installed by typing: system('hwe-support-status'),
-% unless your system is weirdly configured and only partially installed the HWE,
-% in which case it matters if your X-Server is the "factory default" or the HWE
-% variant. Check in your package manager.
+% On Ubuntu 20.04 LTS or later, the following command should work:
 %
-% On Ubuntu 20.04 LTS or 22.04 LTS original installs or upgrades, ie. without the
-% optional HWE for the X-Server installed, this should work:
-%
-% "sudo apt-get install xserver-xorg-input-joystick"
-%
-% If the HWE is installed, you will need one of the following instead:
-%
-% Ubuntu 20.04-LTS: "sudo apt-get install xserver-xorg-input-joystick-hwe-20.04".
-%
-% Ubuntu 22.04-LTS: "sudo apt install xserver-xorg-input-joystick-hwe-22.04".
+% "sudo apt install xserver-xorg-input-joystick"
 %
 % You should also install a custom joystick configuration file to customize the
-% mapping  and behaviour of buttons and axis, and if the Joystick also operates
+% mapping and behaviour of buttons and axis, and if the Joystick also operates
 % as a mouse or not.
 %
 % An example configuration file with installation instructions is  available in
@@ -539,7 +525,7 @@
         case{'GETJOYSTICKNAME?', 'GETGAMEPADNAMESFROMINDICES?'}
             fprintf('Usage:\n');
             fprintf('\n');
-            fprintf('GamepadNames = Gamepad(''GetGamepadNamesFromNumbers'', gamepadIndices\n');
+            fprintf('GamepadNames = Gamepad(''GetGamepadNamesFromNumbers'', gamepadIndices)\n');
             fprintf('\n');
             fprintf('Given a vector of gamepad indices return a cell array of gamepad names.  The gamepad\n');
             fprintf('name is the same as the product field of the HID device structure returned by PsychHID,\n');
@@ -600,7 +586,7 @@
         case{'GETBUTTON?'}
             fprintf('Usage:\n');
             fprintf('\n');
-            fprintf('buttonState = Gamepad(''GetButton'',gamepadIndex, buttonIndex\n');
+            fprintf('buttonState = Gamepad(''GetButton'',gamepadIndex, buttonIndex)\n');
             fprintf('\n');
             fprintf('Given a gamepad index and a button index, return the immediate state of the\n');
             fprintf('specified button on the specified gamepad.  Use ''GetNumGamepads'' and\n');
@@ -676,7 +662,7 @@
         case{'GETHAT?'}
             fprintf('Usage:\n');
             fprintf('\n');
-            fprintf('hatState = Gamepad(''GetHat'',gamepadIndex, hatIndex\n');
+            fprintf('hatState = Gamepad(''GetHat'',gamepadIndex, hatIndex)\n');
             fprintf('\n');
             fprintf('Given a gamepad index and a hat index, return the immediate state of the\n');
             fprintf('specified hat on the specified gamepad.  Use ''GetNumGamepads'' and\n');

Psychtoolbox/PsychHardware/PsychGamepad/HatCenter.m

@@ -1,7 +1,7 @@
 function result = HatCenter
 % result = HatCenter
 % Return a constant for hat center position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 7/21/03   awi added switch and OSX condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatDown.m

@@ -1,7 +1,7 @@
 function result = HatDown
 % result = HatDown
 % Return a constant for hat down position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 7/21/03   awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatLeft.m

@@ -1,7 +1,7 @@
 function result = HatLeft
 % result = HatLeft
 % Return a constant for hat left position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 7/21/03   awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatLeftDown.m

@@ -1,7 +1,7 @@
 function result = HatLeftDown
 % result = HatLeftDown
 % Return a constant for hat left and down position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 7/21/03   awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatLeftUp.m

@@ -1,7 +1,7 @@
 function result = HatLeftUp
 % result = HatLeftUp
 % Return a constant for hat left and up position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 7/21/03   awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatRight.m

@@ -1,7 +1,7 @@
 function result = HatRight
 % result = HatRight
 % Return a constant for hat right position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 %   8/17/01   awi wrote it
 %   7/21/03   awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatRightDown.m

@@ -1,7 +1,7 @@
 function result = HatRightDown
 % result = HatRightDown
 % Return a constant for hat right and down position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 % 8/17/01   awi wrote it
 % 10/6/05   awi Note here cosmetic changes by dgp between 7/21/03 and 10/6/05

Psychtoolbox/PsychHardware/PsychGamepad/HatRightUp.m

@@ -1,7 +1,7 @@
 function result = HatRightUp
 % result = HatRightUp
 % Return a constant for hat right and up position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).
 
 %   8/17/01     awi wrote it
 %   7/21/03     awi added switch and OS X condition.

Psychtoolbox/PsychHardware/PsychGamepad/HatUp.m

@@ -1,7 +1,7 @@
 function result = HatUp
 % result = HatUp
 % Return a constant for hat up position.  To read a hat position, use:
-% JOYSTICK(joystickNumber,'GetHat',hatNumber).  
+% Gamepad('GetHat', gamepadIndex, hatIndex).  
 
 %   8/17/01     awi wrote it
 %   7/21/03     awi added switch and OS X condition.

Psychtoolbox/PsychObsolete/Joystick.m

@@ -1,5 +1,6 @@
 function result = Joystick(arg1, arg2, arg3)
-
+% Joystick() is deprecated and will call GamePad() as its replacement.
+% See 'help GamePad'.
 
 if nargin>3
     error('Too many arguments');
@@ -18,5 +19,5 @@
     result=tempResult; 
 end
 
-% warning('"Joystick has been renamed to "Gamepad".  To avoid this warning message use the new name,  "Gamepad".');
-
+warning('Psychtoolbox:Joystick', '"Joystick" has been renamed to "Gamepad". For improved performance use the new name, "Gamepad".');
+warning('off', 'Psychtoolbox:Joystick');