diff options
Diffstat (limited to 'docs/source/usingmame/ui.rst')
-rw-r--r-- | docs/source/usingmame/ui.rst | 538 |
1 files changed, 538 insertions, 0 deletions
diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst new file mode 100644 index 00000000000..94c7eba413d --- /dev/null +++ b/docs/source/usingmame/ui.rst @@ -0,0 +1,538 @@ +.. _ui: + +MAME’s User Interface +===================== + +.. contents:: :local: + + +.. _ui-intro: + +Introduction +------------ + +MAME provides a simple user interface for selecting the system and software to +run and changing settings while running an emulated system. MAME’s user +interface is designed to be usable with a keyboard, game controller, or pointing +device, but will require a keyboard for initial configuration. + +The default settings for the most important controls to know when running an +emulated system, and the settings they correspond to in case you want to change +them, are as follows: + +Scroll Lock, or Forward Delete on macOS (Toggle UI Controls) + For emulated systems with keyboard inputs, enable or disable UI controls. + (MAME starts with UI controls disabled for systems with keyboard inputs + unless the :ref:`ui_active option <mame-commandline-uiactive>` is on.) +Tab (Show/Hide Menu) + Show or hide the menu during emulation. +Escape (UI Back and UI Cancel) + Return to the system selection menu, or exit if MAME was started with a + system specified (from the command line or using an + :ref:`external front-end <frontends>`). + + +.. _ui-menus: + +Navigating menus +---------------- + +By default, MAME menus can be navigated using the keyboard cursor keys. All +the UI controls can be changed by going to the **General Inputs** menu and then +selecting **User Interface**. The default keyboard controls on a US ANSI QWERTY +layout keyboard, and the settings they correspond to, are as follows: + +Up Arrow (UI Up) + Highlight the previous menu item, or the last item if the first item is + highlighted. +Down Arrow (UI Down) + Highlight the next menu item, or the first item if the last item is + highlighted. +Left Arrow (UI Left) + For menu items that are adjustable settings, reduce the value or select the + previous setting (these menu items show left- and right-facing triangles + beside the value). +Right Arrow (UI Left) + For menu items that are adjustable settings, increase the value or select + the next setting (these menu items show left- and right-facing triangles + beside the value). +Return/Enter keypad Enter (UI Select) + Select the highlighted menu item. +Forward Delete, or Fn+Delete on some compact keyboards (UI Clear) + Clear setting or reset to default value. +Escape (UI Back and UI Cancel) + Clear the search if searching the menu, otherwise close the menu, returning + to the previous menu, or returning to the emulated system in the case of 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) + Highlight the last menu item and scroll to the bottom of the menu. +Page Up (UI Page Up) + Scroll the menu up by one screen. +Page Down (UI Page Down) + Scroll the menu down by one screen. +[ (UI Previous Group) + Move to the previous group of items (not used by all menus). +] (UI Next Group) + Move to the next group of items (not used by all menus). + + +.. _ui-menus-gamectrl: + +Using a game controller +~~~~~~~~~~~~~~~~~~~~~~~ + +MAME supports navigating menus with a game controller or joystick, but only the +most important UI controls have joystick assignments by default: + +* Move the first joystick up or down in the Y axis to highlight the previous or + next menu item. +* Move the first joystick left or right in the X axis to adjust settings. +* Press the first button on the first joystick to select the highlighted menu + item. +* If the first joystick has at least three buttons, press the second button on + the first joystick to close the menu, returning to the previous menu, or + returning to the emulated system in the case of the main menu (there’s usually + an item at the bottom of the menu for the same purpose). + +For gamepad-style controllers, the left analog thumb stick and directional pad +usually control UI navigation. Depending on the controller, the right analog +thumb stick, triggers and additional buttons may automatically be assigned to UI +inputs. Check the **User Interface** input assignments menu to see how controls +are assigned. + +If you want to be able to use MAME with a game controller without needing a +keyboard, you’ll need to assign joystick buttons (or combinations of buttons) to +these controls as well: + +* **Show/Hide Menu** to show or hide the menu during emulation +* **UI Back** to close menus +* **UI Cancel** to return to the system selection menu or exit MAME +* **UI Clear** isn’t essential for basic emulation, but it’s used to clear or + reset some settings to defaults +* **UI Home**, **UI End**, **UI Page Up**, **UI Page Down**, **UI Previous + Group** and **UI Next Group** are not essential, but make navigating some + menus easier + +If you’re not using an external front-end to launch systems in MAME, you should +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 + want access to these features without using a keyboard or pointing device + + +.. _ui-menus-mouse: + +Using a mouse or trackball +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MAME supports navigating menus using a mouse or trackball that works as a system +pointing device: + +* Click menu items to highlight them. +* Double-click menu items to select them. +* Click the left- or right-pointing triangle to adjust settings. +* For menus or text boxes with too many items or lines to fit on the screen, + press on the upward- or downward-pointing triangle at the top or bottom to + scroll up or down. +* Use vertical scrolling gestures to scroll menus or text boxes with too many + items or lines to fit on the screen. +* Click toolbar items to select them, or hover over them to see a description. + +If you have enough additional mouse buttons, you may want to assign button +combinations to the **Show/Hide Menu**, **Pause**, **UI Back** and/or +**UI Cancel** inputs to make it possible to use MAME without a keyboard. + + +.. _ui-menus-touch: + +Using a touch screen +~~~~~~~~~~~~~~~~~~~~ + +MAME has basic support for navigating menus using a touch screen: + +* Tap menu items to highlight them. +* Double-tap menu items to select them. +* Swipe left or right (horizontally) on the highlighted menu item to adjust the + setting if applicable. +* Swipe up or down (vertically) to scroll menus or text boxes with too many + items to fit on the screen. +* For menus or text boxes with too many items or lines to fit on the screen, + press on the upward- or downward-pointing triangle at the top or bottom to + scroll up or down. + +Note that for SDL-based MAME, the +:ref:`enable_touch <mame-scommandline-enabletouch>` option must be switched on +to use touch screen support. + + +.. _ui-inptcfg: + +Configuring inputs +------------------ + +MAME needs a flexible input system to support the control schemes of the vast +array of systems it emulates. In MAME, inputs that only have two distinct +states, on and off or active and inactive, are called *digital inputs*, and all +other inputs are called *analog inputs*, even if this is not strictly true (for +example multi-position switches are called analog inputs in MAME). + +To assign MAME’s user interface controls or the default inputs for all systems, +select **Input Settings** from the main menu during emulation and then select +**Input Assignments (general)** from the Input Settings menu, or select +**General Settings** from the system selection menu and then select **Input +Assignments** from the General Settings menu. From there, select a category. + +To assign inputs for the currently running system, select **Input Settings** +from the main menu during emulation and then select **Input Assignments (this +system)** from the Input Settings menu. Inputs are grouped by device and sorted +by type. You can move between devices with the next group and previous group +keys/buttons (opening/closing brackets **[** and **]** on the keyboard by +default). + +The input assignment menus show the name of the emulated input or user interface +control on the left, and the controls (or combination of controls) assigned to +it on the right. + +To adjust the sensitivity, auto-centre speed and inversion settings, or to see +how emulated analog controls react to your inputs, select **Input Settings** +from the main menu during emulation, and then select **Analog Input +Adjustments** from the Input Settings Menu (this item only appears on the Input +Settings menu for systems with analog controls). + + +.. _ui-inptcfg-digital: + +Digital input settings +~~~~~~~~~~~~~~~~~~~~~~ + +Each emulated digital input has a single assignment setting. For flexibility, +MAME can combine controls (keys, buttons and joystick axes) using logical +**and**, **not** and **or** operations. This is best illustrated with some +examples: + +Kbd 1 + In this simple case, pressing the **1** key on the keyboard activates the + emulated input or user interface control. +Kbd Down or Joy 1 Down + Pressing the down arrow on the keyboard or moving the first joystick down + activates the emulated input or user interface control. +Kbd P not Kbd Shift not Kbd Right Shift + Pressing the **P** key on the keyboard while not pressing either **Shift** + key activates the emulated input or user interface control. MAME does not + show the implicit **and** operations. +Kbd P Kbd Shift or Kbd P Kbd Right Shift + Pressing the **P** key while also pressing either of the **Shift** keys + activates the emulated input or user interface control. Once again, the + implicit **and** operations are not shown. + +(In technical terms, MAME uses Boolean sum of products logic to combine inputs.) + +When a digital input setting is highlighted, the prompt below the menu shows +whether selecting it will replace the current assignment or append an **or** +operation to it. Press **UI Left/Right** before selecting the setting to switch +between replacing the assignment or appending an **or** operation to it. Press +**UI Clear** (**Delete** or **Forward Delete** by default) to clear the +highlighted setting, or restore the default assignment if it is currently +cleared. + +When you select a digital input setting, MAME will wait for you to enter an +input or a combination of inputs for a logical **and** operation: + +* Press a key or button or move an analog control once to add it to the **and** + operation. +* Press a key or button or move an analog control twice to add a **not** item to + the **and** operation. Pressing the same key or button or moving the same + analog control additional times toggles the **not** on and off. +* Press **UI Cancel** (**Escape** by default) to leave the setting unchanged. +* The new setting is shown below the menu. Wait one second after activating an + input to accept the new setting. + +Here’s how to produce some example settings: + +Kbd 1 + Press the **1** key on the keyboard once, then wait one second to accept the + setting. +Kbd F12 Kbd Shift Keyboard Alt + Press the **F12** key on the keyboard once, press the left **Shift** key + once, press the left **Alt** key once, then wait one second to accept the + setting. +Kbd P not Kbd Shift not Kbd Right Shift + Press the **P** key on the keyboard once, press the left **Shift** key + twice, press the right **Shift** key twice, then wait one second to accept + the setting. + + +.. _ui-inptcfg-analog: + +Analog input settings +~~~~~~~~~~~~~~~~~~~~~ + +Each emulated analog input has three assignment settings: + +* Use the *axis setting* to assign an analog axis to control the emulated analog + input. The axis setting uses the name of the input with the suffix “Analog”. + For example the axis setting for the steering wheel in Ridge Racer is called + **Steering Wheel Analog**. +* Use the *increment setting* assign a control (or combination of controls) to + increase the value of the emulated analog input. The increment setting uses + the name of the input with the suffix “Analog Inc”. For example the increment + setting for the steering wheel in Ridge Racer is called **Steering Wheel + Analog Inc**. This is a digital input setting – if an analog axis is + assigned to it, MAME will not increase the emulated input value at a + proportional speed. +* Use the *decrement setting* assign a control (or combination of controls) to + decrease the value of the emulated analog input. The decrement setting uses + the name of the input with the suffix “Analog Dec”. For example the decrement + setting for the steering wheel in Ridge Racer is called **Steering Wheel + Analog Dec**. This is a digital input setting – if an analog axis is + assigned to it, MAME will not decrease the emulated input value at a + proportional speed. + +The increment and decrement settings are most useful for controlling an emulated +analog input using digital controls (for example keyboard keys, joystick +buttons, or a directional pad). They are configured in the same way as emulated +digital inputs (:ref:`see above <ui-inptcfg-digital>`). **It’s important that +you don’t assign the same control to the axis setting as well as the increment +and/or decrement settings for the same emulated input at the same time.** For +example if you assign Ridge Racer’s **Steering Wheel Analog** setting to the X +axis of the left analog stick on your controller, you *should not* assign either +the **Steering Wheel Analog Inc** or **Steering Wheel Analog Dec** setting to +the X axis of the same analog stick. + +You can assign one or more analog axes to the axis setting for an emulated +analog input. When multiple axes are assigned to an axis setting, they will be +added together, but absolute position controls will override relative position +controls. For example suppose for Arkanoid you assign the **Dial Analog** axis +setting to **Mouse X or Joy 1 LSX or Joy 1 RSX** on a mouse and Xbox-style +controller. You will be able to control the paddle with the mouse or either +analog stick, but the mouse will only take effect if both analog sticks are in +the neutral position (centred) on the X axis. If either analog stick is *not* +centred on the X axis, the mouse will have no effect, because a mouse is a +relative position control while joysticks are absolute position controls. + +For absolute position controls like joysticks and pedals, MAME allows you to +assign either the full range of an axis or the range on one side of the neutral +position (a *half axis*) to an axis setting. Assigning a half axis is usually +used for pedals or other absolute inputs where the neutral position is at one +end of the input range. For example suppose for **Ridge Racer** you assign the +**Brake Pedal Analog** setting to the portion of a vertical joystick axis below +the neutral position. If the joystick is at or above the neutral position +vertically, the brake pedal will be released; if the joystick is below the +neutral position vertically, the brake pedal will be applied proportionally. +Half axes are displayed as the name of the axis followed by a plus or minus sign +(**+** or **-**). Plus refers to the portion of the axis below or to the right +of the neutral position; minus refers to the portion of the axis above or to the +left of the neutral position. For pedal or analog trigger controls, the active +range is treated as being above the neutral position (the half axis indicated by +a minus sign). + +When keys or buttons are assigned to an axis setting, they conditionally enable +analog controls assigned to the setting. This can be used in conjunction with +an absolute position control to create a “sticky” control. + +Here are some examples of some possible axis setting assignments, assuming an +Xbox-style controller and a mouse are used: + +Joy 1 RSY + Use vertical movement of the right analog stick to control the emulated + input. +Mouse X or Joy 1 LT or Joy 1 RT Reverse + Use horizontal mouse movement, or the left and right triggers to control the + emulated input. The right trigger is reversed so it acts in the opposite + direction to the left trigger. +Joy 1 LB Joy 1 LSX + Use horizontal movement of the left analog stick to control the emulated + input, but *only* while holding the left shoulder button. If the left + shoulder button is released while the left analog stick is not centred + horizontally, the emulated input will hold its value until the left shoulder + button is pressed again (a “sticky” control). +not Joy 1 RB Joy 1 RSX or Joy 1 RB Joy 1 RSX Reverse + Use horizontal movement of the right analog stick to control the emulated + input, but invert the control if the right shoulder button is held. + +When you select an axis setting, MAME will wait for you to enter an input: + +* Move an analog control to assign it to the axis setting. +* Press a key or button (or a combination of keys or buttons) *before* moving an + analog control to conditionally enable the analog control. +* When appending to a setting, if the last assigned control is an absolute + position control, move the same control again to cycle between the full range + of the axis, the portion of the axis on either side of the neutral position, + and the full range of the axis reversed. +* When appending to a setting, if the last assigned control is a relative + position control, move the same control again to toggle reversing the + direction of the control on or off. +* When appending to a setting, move an analog control other than the last + assigned control or press a key or button to add an **or** operation. +* Pressing **UI Cancel** (**Escape** by default) leaves the setting unchanged. +* The new setting is shown below the menu. Wait one second after moving an + analog control to accept the new setting. + +To adjust sensitivity, auto-centring speed and inversion settings for emulated +analog inputs, or to see how they respond to controls with your settings, select +**Input Settings** from the main menu during emulation, and then select **Analog +Input Adjustments** from the Input Settings Menu. Settings for emulated analog +inputs are grouped by device and sorted by type. You can move between devices +with the next group and previous group keys/buttons (opening/closing brackets +**[** and **]** on the keyboard by default). The state of the emulated analog +inputs is shown below the menu, and reacts in real time. Press the **On Screen +Display** key or button (the backtick/tilde key by default on a US ANSI QWERTY +keyboard) to hide the menu to make it easier to test without changing settings. +Press the same key or button to show the menu again. + +Each emulated input has four settings on the **Analog Controls** menu: + +* The *increment/decrement speed* setting controls how fast the input value + increases or decreases in response to the controls assigned to the + increment/decrement settings. +* The *auto-centering speed* setting controls how fast the input value returns + to the neutral state when the controls assigned to the increment/decrement + settings are released. Setting it to zero (**0**) will result in the value + not automatically returning to the neutral position. +* The *reverse* setting allows the direction of the emulated input’s response + to controls to be inverted. This applies to controls assigned to the axis + setting *and* the increment/decrement settings. +* The *sensitivity* setting adjusts the input value’s response to the control + assigned to the axis setting. + + +Use the UI left/right keys or buttons to adjust the highlighted setting. +Selecting a setting or pressing the UI clear key/button (**Forward Delete** by +default) restores its default value. + +The units for the increment/decrement speed, auto-centering speed and +sensitivity settings are tied to the driver/device implementation. The +increment/decrement speed and auto-centering speed settings are also tied to the +frame rate of the first emulated screen in the system. The response to controls +assigned to the increment/decrement settings will change if the system changes +the frame rate of this screen. + + +.. _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 System** 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 System Settings menu 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 +(with 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. + +You can move focus to an area by clicking on it with the middle mouse button. + + +.. _ui-simpleselmenu: + +The simple system selection menu +-------------------------------- + +If you start MAME without specifying a system on the command line (or choose +**Select New System** 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. |