summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2021-11-02 07:53:18 +1100
committer Vas Crabb <vas@vastheman.com>2021-11-02 07:53:18 +1100
commit8ab63e2072f6cfe19b8f8e2acfbd29754d282c79 (patch)
tree5e05b0a71e44d3b5466a28e9232b32252a96d620 /docs
parent782359169952d8fd7bf737ff45a0c3650ca12c7e (diff)
Fix various usability issues:
frontend: Made it so you can press UI On Screen Display to hide the Analog Controls menu and see the response to your inputs without the risk of changing settings, and see more axes at once and scroll them for systems with very large number of axes. Also ensure the axis being configured is visible when the menu is visible, and made the menu behave a bit more like the system input assignments menu (including previous/next group navigation). frontend: Allow Lua to draw to the UI container - this addresses the main complaint in #7475. Note that drawing to the UI container will draw over any UI elements, including menus. Plugins can check menu_active to avoid drawing over menus. Also removed some unnecessary use of sol::overload. frontend: Improved info/image box navigation on the system/softwre selection menus, and cleaned up some leftover code that came from the copy/pasted event handling functions. frontend: Fixed sliders menu not handling Alt+Shift as intended (thanks Coverity). Fixed a couple of harmless Coverity errors, too. emu/inpttype.ipp: Made the default assignment for Save State recognise right shift. plugins: Added next/previous group navigation to input macro edit menu. docs: Added basic description of the system and software selection menus, and corrected a couple of errors in the Lua reference.
Diffstat (limited to 'docs')
-rw-r--r--docs/source/techspecs/luareference.rst121
-rw-r--r--docs/source/usingmame/ui.rst131
2 files changed, 221 insertions, 31 deletions
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index 38ae1476b3a..623d4738407 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -804,12 +804,12 @@ screen:pixels()
screen:draw_box(left, top, right, bottom, [line], [fill])
Draws an outlined rectangle with edges at the specified positions.
- Coordinates are floating-point numbers in units of screen pixels, with the
- origin at (0, 0). Note that screen pixels often aren’t square. The
- coordinate system is rotated if the screen is rotated, which is usually the
- case for vertical-format screens. Before rotation, the origin is at the top
- left, and coordinates increase to the right and downwards. Coordinates are
- limited to the screen area.
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
The fill and line colours are in alpha/red/green/blue (ARGB) format.
Channel values are in the range 0 (transparent or off) to 255 (opaque or
@@ -822,12 +822,12 @@ screen:draw_box(left, top, right, bottom, [line], [fill])
screen:draw_line(x1, y1, x2, y2, bottom, [color])
Draws a line from (x1, y1) to (x2, y2).
- Coordinates are floating-point numbers in units of screen pixels, with the
- origin at (0, 0). Note that screen pixels often aren’t square. The
- coordinate system is rotated if the screen is rotated, which is usually the
- case for vertical-format screens. Before rotation, the origin is at the top
- left, and coordinates increase to the right and downwards. Coordinates are
- limited to the screen area.
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
The line colour is in alpha/red/green/blue (ARGB) format. Channel values
are in the range 0 (transparent or off) to 255 (opaque or full intensity),
@@ -847,21 +847,21 @@ screen:draw_text(x|justify, y, text, [foreground], [background])
right-aligned at the right edge of the screen, respectively. The second
argument specifies the Y coordinate of the maximum ascent of the text.
- Coordinates are floating-point numbers in units of screen pixels, with the
- origin at (0, 0). Note that screen pixels often aren’t square. The
- coordinate system is rotated if the screen is rotated, which is usually the
- case for vertical-format screens. Before rotation, the origin is at the top
- left, and coordinates increase to the right and downwards. Coordinates are
- limited to the screen area.
-
- The foreground and background colours is in alpha/red/green/blue (ARGB)
- format. Channel values are in the range 0 (transparent or off) to 255 (opaque or full intensity),
- inclusive. Colour channel values are not pre-multiplied by the alpha value.
- The channel values must be packed into the bytes of a 32-bit unsigned
- integer, in the order alpha, red, green, blue from most-significant to
- least-significant byte. If the foreground colour is not provided, the UI
- text colour is used; if the background colour is not provided, the UI
- background colour is used.
+ Coordinates are floating-point numbers in units of emulated screen pixels,
+ with the origin at (0, 0). Note that emulated screen pixels often aren’t
+ square. The coordinate system is rotated if the screen is rotated, which is
+ usually the case for vertical-format screens. Before rotation, the origin
+ is at the top left, and coordinates increase to the right and downwards.
+ Coordinates are limited to the screen area.
+
+ The foreground and background colours are in alpha/red/green/blue (ARGB)
+ format. Channel values are in the range 0 (transparent or off) to 255
+ (opaque or full intensity), inclusive. Colour channel values are not
+ pre-multiplied by the alpha value. The channel values must be packed into
+ the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
+ from most-significant to least-significant byte. If the foreground colour
+ is not provided, the UI text colour is used; if the background colour is not
+ provided, it is fully transparent.
Properties
^^^^^^^^^^
@@ -2412,6 +2412,73 @@ manager.machine.render.ui_container
manager.machine.screens[tag].container
Gets the render container used to draw a given screen.
+Methods
+^^^^^^^
+
+container:draw_box(left, top, right, bottom, [line], [fill])
+ Draws an outlined rectangle with edges at the specified positions.
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ screen that showss the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ The fill and line colours are in alpha/red/green/blue (ARGB) format.
+ Channel values are in the range 0 (transparent or off) to 255 (opaque or
+ full intensity), inclusive. Colour channel values are not pre-multiplied by
+ the alpha value. The channel values must be packed into the bytes of a
+ 32-bit unsigned integer, in the order alpha, red, green, blue from
+ most-significant to least-significant byte. If the line colour is not
+ provided, the UI text colour is used; if the fill colour is not provided,
+ the UI background colour is used.
+container:draw_line(x1, y1, x2, y2, bottom, [color])
+ Draws a line from (x1, y1) to (x2, y2).
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ screen that showss the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ Coordinates are floating-point numbers in units of screen pixels, with the
+ origin at (0, 0). Note that screen pixels often aren’t square. The
+ coordinate system is rotated if the screen is rotated, which is usually the
+ case for vertical-format screens. Before rotation, the origin is at the top
+ left, and coordinates increase to the right and downwards. Coordinates are
+ limited to the screen area.
+
+ The line colour is in alpha/red/green/blue (ARGB) format. Channel values
+ are in the range 0 (transparent or off) to 255 (opaque or full intensity),
+ inclusive. Colour channel values are not pre-multiplied by the alpha value.
+ The channel values must be packed into the bytes of a 32-bit unsigned
+ integer, in the order alpha, red, green, blue from most-significant to
+ least-significant byte. If the line colour is not provided, the UI text
+ colour is used.
+container:draw_text(x|justify, y, text, [foreground], [background])
+ Draws text at the specified position. If the screen is rotated the text
+ will be rotated.
+
+ If the first argument is a number, the text will be left-aligned at this X
+ coordinate. If the first argument is a string, it must be ``"left"``,
+ ``"center"`` or ``"right"`` to draw the text left-aligned at the
+ left edge of the window or screen, horizontally centred in the window or
+ screen, or right-aligned at the right edge of the window or screen,
+ respectively. The second argument specifies the Y coordinate of the maximum
+ ascent of the text.
+
+ Coordinates are floating-point numbers in the range of 0 (zero) to 1 (one),
+ with (0, 0) at the top left and (1, 1) at the bottom right of the window or
+ screen that showss the user interface. Note that the aspect ratio is
+ usually not square. Coordinates are limited to the window or screen area.
+
+ The foreground and background colours are in alpha/red/green/blue (ARGB)
+ format. Channel values are in the range 0 (transparent or off) to 255
+ (opaque or full intensity), inclusive. Colour channel values are not
+ pre-multiplied by the alpha value. The channel values must be packed into
+ the bytes of a 32-bit unsigned integer, in the order alpha, red, green, blue
+ from most-significant to least-significant byte. If the foreground colour
+ is not provided, the UI text colour is used; if the background colour is not
+ provided, it is fully transparent.
+
Properties
^^^^^^^^^^
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst
index 38b0e5bc7cc..c764ef56688 100644
--- a/docs/source/usingmame/ui.rst
+++ b/docs/source/usingmame/ui.rst
@@ -61,9 +61,9 @@ Return/Enter keypad Enter (UI Select)
Forward Delete, or Fn+Delete on some compact keyboards (UI Clear)
Clear setting or reset to default value.
Escape (UI Cancel)
- Close the menu, returning to the previous menu, or returning to the
- emulated machine for the main menu (there’s usually an item at the bottom
- of the menu for the same purpose).
+ Clear the search if searching the menu, otherwise close the menu, returning
+ to the previous menu, or returning to the emulated machine for the main menu
+ (there’s usually an item at the bottom of the menu for the same purpose).
Home (UI Home)
Highlight the first menu item and scroll to the top of the menu.
End (UI End)
@@ -110,7 +110,7 @@ assign joystick buttons (or combinations of buttons) to these controls to make
full use of the system and software selection menus:
* **UI Focus Next**/**UI Focus Previous** to navigate between panes
-* **UI Add Remove favorite**, **UI Export List** and **UI Audit Media** if you
+* **UI Add/Remove favorite**, **UI Export List** and **UI Audit Media** if you
want access to these features without using a keyboard or pointing device
@@ -135,3 +135,126 @@ pointing device:
If you have enough additional mouse buttons, you may want to assign button
combinations to the **Config Menu**, **Pause** and/or **UI Cancel** inputs to
make it possible to use MAME without a keyboard.
+
+
+.. _ui-selmenu:
+
+The system and software selection menus
+---------------------------------------
+
+If you start MAME without specifying a system on the command line, the system
+selection menu will be shown (assuming the
+:ref:`ui option <mame-commandline-ui>` is set to **cabinet**). The system
+selection menu is also shown if you select **Select New Machine** from the main
+menu during emulation. Selecting a system that uses software lists shows the
+similar software selection menu.
+
+The system and software selection menus have the following parts:
+
+* The heading area at the top, showing the emulator name and version, the number
+ of systems or software items in the menu, and the current search text. The
+ software selection menu also shows the name of the selected system.
+* The toolbar immediately below the heading area. The exact toolbar buttons
+ shown depend on the menu. Hover the mouse pointer over a button to see a
+ description. Click a button to select it.
+
+ Toolbar buttons are add/remove highlighted system/software from favourites
+ (star), export displayed list to file (diskette), audit media (magnifying
+ glass), show info viewer (“i” emblazoned on blue circle), return to previous
+ menu (bent arrow on blue), and exit (cross on red).
+* The list of systems or software in the centre. For the system selection menu,
+ there are configuration options below the list of systems. Clones are shown
+ with a different text colour (grey by default). You can right-click a system
+ name as a shortcut to show the machine configuration options for the system.
+
+ Systems or software items are sorted by full name or description, keeping
+ clones immediately below their parents. This may appear confusing if your
+ filter settings cause a parent system or software item to be hidden while one
+ or more of its clones are visible.
+* The info panel at the bottom, showing summary information about the
+ highlighted system or software. The background colour changes depending on
+ the emulation status: green for working, amber for imperfectly emulated
+ features or known issues, or red for more serious issues.
+
+ A yellow star is show at the top left of the info panel if the highlighted
+ system or software is in your favourites list.
+* The collapsible list of filter options on the left. Click a filter to apply
+ it to the list of systems/software. Some filters show a menu with additional
+ options (e.g. specifying the manufacturer for the **Manufacturer** filter, or
+ specifying a file and group for the **Category** filter).
+
+ Click **Unfiltered** to display all items. Click **Custom Filter** to combine
+ multiple filters. Click the strip between the list of filters and the list of
+ systems/software to show or hide the list of filters. Be aware that filters
+ still apply when the list of filters is hidden.
+* The collapsible info viewer on the right. This has two tabs for showing
+ images and information. Click a tab to switch tabs; click the left- or
+ right-facing triangles next to the image/info title to switch between images
+ or information sources.
+
+ Emulation information is automatically shown for systems, and information from
+ the software list is shown for software items. Additional information from
+ external files can be shown using the :ref:`Data plugin <plugins-data>`.
+
+You can type to search the displayed list of systems or software. Systems are
+searched by full name, manufacturer and full name, and short name. If you are
+using localised system names, phonetic names will also be searched if present.
+Software items are searched by description, alternate titles (``alt_title``
+info elements in the software lists), and short name. **UI Cancel** (Escape by
+default) will clear the search if currently searching.
+
+
+.. _ui-selmenu-nav:
+
+Navigation controls
+~~~~~~~~~~~~~~~~~~~
+
+In addition to the usual :ref:`menu navigation controls <ui-menus>`, the system
+and software selection menus have additional configurable controls for
+navigating the multi-pane layout, and providing alternatives to toolbar buttons
+if you don’t want to use a pointing device. The default additional controls (on
+a US ANSI QWERTY keyboard), and the settings they correspond to, are:
+
+Tab (UI Focus Next)
+ Move focus to the next area. The order is system/software list,
+ configuration options (if visible), filter list (if visible), info/image
+ tabs (if visible), info/image source (if visible).
+Shift+Tab (UI Focus Previous)
+ Move focus to the previous area.
+Alt+D (UI External DAT View)
+ Show the full-size info viewer.
+Alt+F (UI Add/Remove favorite)
+ Add or remove the highlighted system or software item from the favourites
+ list.
+F1 (UI Audit Media)
+ Audit ROMs and/or disk images for systems. The results are saved for use
+ with the **Available** and **Unavailable** filters.
+
+When focus is on the filter list, you can use the menu navigation controls (up,
+down, home and end) to highlight a filter, and **UI Select** (Return/Enter by
+default) apply it.
+
+When focus is on any area besides the info/image tabs, you can change the image
+or info source with left/right. When focus is on the info/image tabs,
+left/right switch between tabs. When focus is on the image/info tabs or source,
+you can scroll the info using up, down, page up, page down, home and end.
+
+
+.. _ui-simpleselmenu:
+
+The simple system selection menu
+--------------------------------
+
+If you start MAME without specifying a system on the command line (or choose
+**Select New Machine** from the main menu during emulation) with the
+:ref:`ui option <mame-commandline-ui>` set to **simple**, the simple system
+selection menu will be shown. The simple system selection menu shows fifteen
+randomly selected systems that have ROM sets present in your configured
+:ref:`ROM folder(s) <mame-commandline-rompath>`. You can type to search for a
+system. Clearing the search causes fifteen systems to be randomly selected
+again.
+
+The info panel below the menu shows summary information about the highlighted
+system. The background colour changes depending on the emulation status: green
+for working, amber for imperfectly emulated features or known issues, or red for
+more serious issues.