ui, docs: Added menus to fill a couple of gaps, improved consistency. (…

…#9915)

Added menus for controlling toggle inputs, and showing recognised input
devices and control state.  Moved input menu options off main menu to a
submenu, as there are a lot of them now.

Moved menu heading drawing into base class, added headings to more
menus, and made headings more consistent with the menu items used to
reach them.  Also made terminology more consistent.

Changed the default names for buttons and hat switches/D-pads to use
1-based numbering.  DirectInput still returns 0-based button numbers for
some devices.

Removed local copy of MinGW xaudio2.h as it’s now included in the MSYS2
package.  Also fixed building the DirectSound sound output module with
the SDL OSD on Windows - the Windows headers are sensitive to include
order.

Started adding documentation for menus, to hopefully help people find
menus they remember seeing but can't recall how to access.

For translators, this makes terminology more consistent.  In particular:
* "Settings" is preferred over "configuration" in a number of places, as
  the latter can be construed as referring specifically to settings
  stored in .cfg files in the cfg_directory folder.  Also, references to
  saving machine configuration could be interpreted as relating to the
  settings on the "Machine Configuration" menu.
* The controls on host input devices (e.g. keys, buttons, joystick axes)
  are referred to as "controls", while emulated inputs are referred to
  as "inputs".
* The menus for assigning host controls to emulated inputs are called
  "input assignments" menus to distinguish them from other input
  settings menus.
* Combinations of controls that can be assigned to emulated inputs are
  referred to as "combinations" rather than "sequences".
* The potentially confusing term "ROM set" has been removed altogether.
  Use "short name" to refer to a device or system's identifier.
* "System" is used in almost places to refer to a complete, runnable
  system rather than "Machine".
* "Driver" is now only used to refer to source files where systems or
  devices are defined - it is no longer used to refer to individual
  systems.
* A few more menus have message context for the messages.  This makes it
  a bit easier to guess where the messages are used.  It also means you
  can use different translations in different places if necessary (e.g.
  if the same English text should be translated differently as an item
  in one menu and as a heading in another).

COPYING

@@ -1,4 +1,5 @@
-MAME is a registered trademark of Gregory Ember.
+MAME is a registered trademark of Gregory Ember.  Other trademarks are
+property of their respective owners.
 
 MAME as a whole is made available under the terms of the GNU General
 Public License.  Individual source files may be made available under

docs/source/advanced/ctrlr_config.rst

@@ -41,8 +41,9 @@ Basic structure
 
 Controller configuration files follow a similar format to the system
 configuration files that MAME uses to save things like input settings and
-bookkeeping data.  This example shows the overall structure of a controller
-configuration file:
+bookkeeping data (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`).  This example
+shows the overall structure of a controller configuration file:
 
 .. code-block:: XML
 
@@ -127,21 +128,21 @@ left and right arrows will be replaced with the numeric 8, 2, 4 and 6 keys on
 the numeric keypad, respectively.
 
 Note that substitutions specified using ``remap`` elements only apply to inputs
-that use MAME’s default assignment for the control type.  That is, they only
-apply to default assignments for control types set in the “Inputs (general)”
-menu.  They *do not* apply to default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+that use MAME’s default assignment for the input type.  That is, they only apply
+to default assignments for control types set in the “Input Assignments
+(general)” menus.  They *do not* apply to default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
 
 MAME applies ``remap`` elements found inside any applicable ``system`` element.
 
 
 .. _ctrlrcfg-typeoverride:
 
-Overriding defaults by control type
------------------------------------
+Overriding defaults by input type
+---------------------------------
 
 Use ``port`` elements with ``type`` attributes but without ``tag`` attributes to
-override the default host input assignments for a controls:
+override the default control assignments for emulated inputs by type:
 
 .. code-block:: XML
 
@@ -183,33 +184,33 @@ P1 Button 4 (Player 1 Controls)
     X key, or joystick 1 button 4
 
 Note that this will only apply for inputs that use MAME’s default assignment for
-the control type.  That is, ``port`` elements without ``tag`` attributes only
-override default assignments for control types set in the “Inputs (general)”
-menu.  They *do not* override default input assignments set in driver/device I/O
-port definitions (using the ``PORT_CODE`` macro).
+the input type.  That is, ``port`` elements without ``tag`` attributes only
+override default assignments for control types set in the “Input Assignments
+(general)” menus.  They *do not* override default control assignments set in
+driver/device I/O port definitions (using the ``PORT_CODE`` macro).
 
 MAME applies ``port`` elements without ``tag`` attributes found inside any
 applicable ``system`` element.
 
 
 .. _ctrlrcfg-ctrloverride:
 
-Overriding defaults for specific controls
------------------------------------------
+Overriding defaults for specific inputs
+---------------------------------------
 
 Use ``port`` elements with ``tag``, ``type``, ``mask`` and ``defvalue``
-attributes to override defaults for specific controls.  These ``port`` elements
+attributes to override defaults for specific inputs.  These ``port`` elements
 should only occur inside ``system`` elements that apply to particular systems or
 source files (i.e. they should not occur inside ``system`` elements where the
-``name`` attribute has the value ``default``).  The default host input
-assignments can be overridden, as well as the toggle setting for digital
-controls.
+``name`` attribute has the value ``default``).  The default control assignments
+can be overridden, as well as the toggle setting for digital inputs.
 
 The ``tag``, ``type``, ``mask`` and ``defvalue`` are used to identify the
 affected input.  You can find out the values to use for a particular input by
-changing its assigned host input, exiting MAME, and checking the values in the
-system configuration file.  Note that these values are not guaranteed to be
-stable, and may change between MAME versions.
+changing its control assignment, exiting MAME, and checking the values in the
+system configuration file (created in the folder specified using the
+:ref:`cfg_directory option <mame-commandline-cfgdirectory>`).  Note that these
+values are not guaranteed to be stable, and may change between MAME versions.
 
 Here’s an example that overrides defaults for 280-ZZZAP:
 
@@ -225,5 +226,5 @@ Here’s an example that overrides defaults for 280-ZZZAP:
         </input>
     </system>
 
-This sets the host inputs to steer left and right to the K and J keys,
+This sets the controls to steer left and right to the K and J keys,
 respectively, and disables the toggle setting for the gear shift input.

docs/source/conf.py

@@ -63,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.244'
+version = '0.245'
 # The full version, including alpha/beta/rc tags.
-release = '0.244'
+release = '0.245'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/debugger/general.rst

@@ -546,6 +546,21 @@ Examples:
 Back to :ref:`debugger-general-list`
 
 
+.. _debugger-command-time:
+
+time
+----
+
+Prints the total elapsed emulated time to the debugger console.
+
+Examples:
+
+``time``
+    Prints the elapsed emulated time.
+
+Back to :ref:`debugger-general-list`
+
+
 .. _debugger-command-quit:
 
 quit

docs/source/plugins/autofire.rst

@@ -50,9 +50,9 @@ Button 1* or the equivalent for another player, but it might have have a
 different name.  On Konami’s Gradius games, *P1 Button 2* is the primary fire
 button.
 
-Select **Hotkey** to set the input combination you’ll use to activate the
-autofire button.  This can be any combination that MAME supports for activating
-a digital input.
+Select **Hotkey** to set the control (or combination of controls) you’ll use to
+activate the autofire button.  This can be any combination that MAME supports
+for activating a digital input.
 
 **On frames** and **Off frames** are the number of consecutive emulated video
 frames that the emulated button will be held and released for, respectively.
@@ -81,10 +81,10 @@ immediately.
 Notes and potential pitfalls
 ----------------------------
 
-Autofire buttons act as if they’re wired in parallel with MAME’s regular inputs.
-This means that if you set the activation hotkey for an autofire button to a
-button or key that’s also assigned to one of the emulated inputs directly, you
-may get unexpected results.  Using Gradius as an example:
+Autofire buttons act as if they’re wired in parallel with MAME’s regular
+controls.  This means that if you set the activation hotkey for an autofire
+button to a button or key that’s also assigned to one of the emulated inputs
+directly, you may get unexpected results.  Using Gradius as an example:
 
 * Suppose you set button 1 on your controller to fire, and set an autofire
   hotkey to button 1 as well.  Holding the button down to shoot will not trigger
@@ -97,8 +97,8 @@ may get unexpected results.  Using Gradius as an example:
   powerup because the powerup button is also being held down along with the
   autofire button.
 
-It is suggested you choose input combinations for autofire hotkeys that are not
-assigned to any other emulated inputs in the system.
+It is recommended that you choose control combinations for autofire hotkeys that
+are not assigned to any other emulated inputs in the system.
 
 Autofire is not necessarily desirable in all situations.  For example using
 autofire in Super-X with the blue “lightning” weapon equipped at high power

docs/source/plugins/inputmacro.rst

@@ -57,10 +57,10 @@ whole:
   press the UI Clear key to type a new name.  Press the UI Select key before
   moving to another menu item to save the new name; press the UI Cancel key
   (Escape/Esc on the keyboard by default) to change discard the new name.
-* Select **Activation sequence** to set the key or button combination you want
-  to use to activate the macro.  Keep in mind that regular input settings still
-  apply, so you probably want to use a combination that isn’t being used for any
-  other emulated input in the system.
+* Select **Activation combination** to set the control (or combination of
+  controls) you want to use to activate the macro.  Keep in mind that regular
+  input assignments still apply, so you will probably want to use a combination
+  that isn’t being used for any other emulated input in the system.
 * Set **On release** to specify what should happen if the activation sequence is
   released before the macro completes.  When set to *Stop immediately*, any
   emulated inputs activated by the macro will be released immediately, and no
@@ -133,7 +133,7 @@ thing could be achieved using the :ref:`plugins-autofire`, but this demonstrates
 a simple looping macro:
 
 * **Name**: P1 Autofire
-* **Activation sequence**: Kbd Space
+* **Activation combination**: Kbd Space
 * **On release**: Stop immediately
 * **When held**: Loop to step 2
 * **Step 1**:
@@ -159,7 +159,7 @@ This allows you to run in Konami Track & Field by holding a single button.  This
 takes most of the skill (and fun) out of the game:
 
 * **Name**: P1 Sprint
-* **Activation sequence**: Kbd Shift
+* **Activation combination**: Kbd Shift
 * **On release**: Stop immediately
 * **When held**: Loop to step 2
 * **Step 1**:
@@ -188,7 +188,7 @@ This macro allows you to perform a right-facing Shōryūken (Dragon Punch) by
 pressing a single key:
 
 * **Name**: 1P Shoryuken LP
-* **Activation sequence**: Kbd M
+* **Activation combination**: Kbd M
 * **On release**: Complete macro
 * **When held**: Prolong step 6
 * **Step 1**:

docs/source/techspecs/memory.rst

@@ -126,7 +126,8 @@ A memory share can be created if it doesn’t exist in a memory map
 through that creator class.  If it already exists it is just
 retrieved.  That class behaves like a pointer but also has the
 ``target()``, ``length()``, ``bytes()``, ``endianness()``,
-``bitwidth()`` and ``bytewidth()`` methods for share information.
+``bitwidth()`` and ``bytewidth()`` methods for share information.  The
+desired size is specified in bytes.
 
 .. code-block:: C++
 
@@ -154,12 +155,17 @@ A memory bank is a named memory zone indirection that can be mapped in
 address spaces.  It points to ``nullptr`` when created.
 ``configure_entry`` associates an entry number and a base pointer.
 ``configure_entries`` does the same for multiple consecutive entries
-spanning a memory zone.  Alternatively ``set_base`` sets the base for
-entry 0 and selects it.
+spanning a memory zone.
 
-``set_entry`` allows to dynamically and efficiently select the current
-active entry, ``entry()`` gets that selection back, and ``base()`` gets
-the associated base pointer.
+``set_base`` sets the base address for the active entry.  If there are
+no entries, entry 0 (zero) is automatically created and selected.  Use
+of ``set_base`` should be avoided in favour of pre-configured entries
+unless there are an impractically large number of possible base
+addresses.
+
+``set_entry`` dynamically and efficiently selects the active entry,
+``entry()`` returns the active entry number, and ``base()`` gets the
+associated base pointer.
 
 .. code-block:: C++
 

docs/source/usingmame/commonissues.rst

@@ -309,7 +309,7 @@ You can try changing the
 :ref:`lightgunprovider <mame-commandline-lightgunprovider>` setting (depending
 on which kind of device you’re having issues with) from ``rawinput`` to one of
 the other options such as ``dinput`` or ``win32``.  See
-:ref:`osd-commandline-options` for details on input provider options
+:ref:`mame-commandline-osdoptions` for details on input provider options
 
 
 .. _ExternalOPL:

docs/source/usingmame/defaultkeys.rst

@@ -63,7 +63,8 @@ and saving/loading save states.
     Highlight first or last UI menu option.
 **[** **]**
     Move to previous or next group in UI menus that support it (e.g. move to the
-    inputs for the previous or next device in the Input (this Machine) menu).
+    inputs for the previous or next device in the **Input Assignments (this
+    System)** menu).
 **Enter**/**Joystick 1 Button 1**
     Select currently highlighted UI menu option.
 **Space**
@@ -706,8 +707,8 @@ All the keys below are fully configurable in the user interface. This list shows
 the standard keyboard configuration.
 
 Note that controls can vary widely by computer type, so not all keys are shown
-here. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+here. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.
 
 
 **Tab**
@@ -742,5 +743,5 @@ All the keys are fully configurable in the user interface.
 
 Note that controls can vary widely by machine type, so default keys are not
 shown here and defaults will vary considerably based on the manufacturer and
-style. See the “Input (this Machine)” section of MAME’s configuration menu for
-details for the machine you are currently using.
+style. See the **Input Assignments (this system)** section of MAME’s Input
+Settings menu for details for the machine you are currently using.