diff options
author | 2018-08-02 23:11:17 +1000 | |
---|---|---|
committer | 2018-08-02 23:11:17 +1000 | |
commit | 6ea9ff90423416d630472298a14afc5526104e75 (patch) | |
tree | e9e8e7d7b86f96d3d20d3b635a5cf99bc75f04a8 /docs | |
parent | 153fa4c4f88bfc3bc6abd48700d9481b1d90321c (diff) |
(nw) Further layout work:
* Allow <orientation> and <color> to work on group references
* Fix some corner cases where group bounds could be miscalculated
* Fix a corner case where MAME could incorrectly refuse to instantiate groups
* Add more checks to complay.py
* Document more of the layout format
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst index 89ce3e54d58..31098111b30 100644 --- a/docs/source/techspecs/layout_files.rst +++ b/docs/source/techspecs/layout_files.rst @@ -601,6 +601,181 @@ An example element for a button that gives visual feedback when clicked:: </element> +.. _layout-parts-views: + +Views +~~~~~ + +A view defines an arrangement of elements and/or emulated screen images that can +be displayed in a window or on a screen. Views also connect elements to +emulated I/O ports and/or outputs. A layout file may contain multiple views. +If a view references a non-existent screen, it will be considered *unviable*. +MAME will print a warning message, skip over the unviable view, and continue to +load views from the layout file. This is particularly useful for systems where +a screen is optional, for example computer systems with front panel controls and +an optional serial terminal. + +Views are identified by name in MAME's user interface and in command-line +options. For layouts files associated with devices other than the root driver +device, view names are prefixed with the device's tag (with the initial colon +omitted) -- for example a view called "Keyboard LEDs" loaded for the device +``:tty:ie15`` will be called "tty:ie15 Keyboard LEDs" in MAME's user interface. +Views are listed in the order they are loaded. Within a layout file, views are +loaded in the order they appear, from top to bottom. + +Views are created with ``view`` elements inside the top-level ``mamelayout`` +element. Each ``view`` element must have a ``name`` attribute, supplying its +human-readable name for use in the user interface and command-line options. +This is an example of a valid opening tag for a ``view`` element:: + + <view name="Control panel"> + +A view creates a nested parameter scope inside the parameter scope of the +top-level ``mamelayout`` element. For historical reasons, ``view`` elements are +processed *after* all other child elements of the top-level ``mamelayout`` +element. This means a view can reference elements and groups that appear after +it in the file, and parameters from the enclosing scope will have their final +values from the end of the ``mamelayout`` element. + +The following child elements are allowed inside a ``view`` element: + +bounds + Sets the origin and size of the view if present. If absent, the bounds of + the view are computed as the union of the bounds of all screens and elements + within the view. See :ref:`layout-concepts-coordinates` for details. It + only makes sense to have one ``bounds`` as a direct child of a view element. +param + Defines or reassigns a value parameter in the view's scope. See + :ref:`layout-concepts-params` for details. +backdrop overlay bezel cpanel marquee + Adds an element to the relevant layer (see :ref:`layout-parts-elements` and + :ref:`layout-concepts-layers`). The name of the element to add is specified + using the required ``element`` attribute. It is an error if no element with + this name is defined in the layout file. May optionally be connected to an + emulated I/O port using ``inputtag`` and ``inputmask`` attributes, and/or an + emulated output using a ``name`` attribute. Within a layer, elements are + drawn in the order they appear in the layout file, from front to back. See + below for more details. +screen + Adds an emulated screen image to the view. The screen must be identified + using either an ``index`` attribute or a ``tag`` attribute (it is an error + for a ``screen`` element to have both ``index`` and ``tag`` attributes). + If present, the ``index`` attribute must be a non-negative integer. Screens + are numbered by the order they appear in machine configuration, starting at + zero (0). If present, the ``tag`` attribute must be the tag path to the + screen relative to the device that causes the layout to be loaded. Screens + are drawn in the order they appear in the layout file, from front to back. +group + Adds the content of the group to the view (see :ref:`layout-parts-groups`). + The name of the group to add is specified using the required ``ref`` + attribute. It is an error if no group with this name is defined in the + layout file. See below for more details on positioning. +repeat + Repeats its contents the number of times specified by the required ``count`` + attribute. The ``count`` attribute must be a positive integer. A + ``repeat`` element in a view may contain ``backdrop``, ``screen``, + ``overlay``, ``bezel``, ``cpanel``, ``marquee``, ``group``, and further + ``repeat`` elements, which function the same way they do when placed in a + view directly. See :ref:`layout-parts-repeats` for discussion on using + ``repeat`` elements. + +Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``, +``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements) +may be have their orientation altered using an ``orientation`` child element. +For screens, the orientation modifiers are applied in addition to the +orientation modifiers specified on the screen device and on the machine. The +``orientation`` element supports the following attributes, all of which are +optional: + +rotate + If present, applies clockwise rotation in ninety degree implements. Must be + an integer equal to 0, 90, 180 or 270. +swapxy + Allows the screen, element or group to be mirrored along a line at + forty-five degrees to vertical from upper left to lower right. Must be + either ``yes`` or ``no`` if present. Mirroring applies logically after + rotation. +flipx + Allows the screen, element or group to be mirrored around its vertical axis, + from left to right. Must be either ``yes`` or ``no`` if present. Mirroring + applies logically after rotation. +flipy + Allows the screen, element or group to be mirrored around its horizontal + axis, from top to bottom. Must be either ``yes`` or ``no`` if present. + Mirroring applies logically after rotation. + +Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``, +``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements) +may be positioned and sized using a ``bounds`` child element (see +:ref:`layout-concepts-coordinates` for details). In the absence of a ``bounds`` +child element, screens' and layout elements' bounds default to a unit square +(origin at 0,0 and height and width both equal to 1). In the absence of a +``bounds`` child element, groups are expanded with no translation/scaling (note +that groups may position screens/elements outside their bounds). This example +shows a view instantiating and positioning a screen, an individual layout +element, and two element groups:: + + <view name="LED Displays, Terminal and Keypad"> + <cpanel element="beige"><bounds x="320" y="0" width="172" height="372" /></cpanel> + <group ref="displays"><bounds x="0" y="0" width="320" height="132" /></group> + <group ref="keypad"><bounds x="336" y="16" width="140" height="260" /></group> + <screen index="0"><bounds x="0" y="132" width="320" height="240" /></screen> + </view> + +Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``, +``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements) +may have a ``color`` child element (see :ref:`layout-concepts-colours`) +specifying a modifier colour. The components colours of the screen or layout +element(s) are multiplied by this colour. + +If an element instantiating a layout element (``backdrop``, ``overlay``, +``bezel``, ``cpanel`` or ``marquee``) has ``inputtag`` and ``inputmask`` +attributes, clicking it is equivalent to pressing a key/button mapped to the +corresponding input(s). The ``inputtag`` specifies the tag path of an I/O port +relative to the device that caused the layout file to be loaded. The +``inputmask`` attribute must be an integer specifying the bits of the I/O port +that the element should activate. This sample is shows instantiation of +clickable buttons:: + + <cpanel element="btn_3" inputtag="X2" inputmask="0x10"> + <bounds x="2.30" y="4.325" width="1.0" height="1.0" /> + </cpanel> + <cpanel element="btn_0" inputtag="X0" inputmask="0x20"> + <bounds x="0.725" y="5.375" width="1.0" height="1.0" /></cpanel> + <cpanel element="btn_rst" inputtag="RESET" inputmask="0x01"> + <bounds x="1.775" y="5.375" width="1.0" height="1.0" /> + </cpanel> + + +If an element instantiating a layout element (``backdrop``, ``overlay``, +``bezel``, ``cpanel`` or ``marquee``) has a ``name`` attribute, it will take its +state from the value of the correspondingly named emulated output. Note that +output names are global, which can become an issue when a machine uses multiple +instances of the same type of device. See :ref:`layout-parts-elements` for +details on how an element's state affects its appearance. This example shows +how digital displays may be connected to emulated outputs:: + + <cpanel name="digit6" element="digit"><bounds x="16" y="16" width="48" height="80" /></cpanel> + <cpanel name="digit5" element="digit"><bounds x="64" y="16" width="48" height="80" /></cpanel> + <cpanel name="digit4" element="digit"><bounds x="112" y="16" width="48" height="80" /></cpanel> + <cpanel name="digit3" element="digit"><bounds x="160" y="16" width="48" height="80" /></cpanel> + <cpanel name="digit2" element="digit"><bounds x="208" y="16" width="48" height="80" /></cpanel> + <cpanel name="digit1" element="digit"><bounds x="256" y="16" width="48" height="80" /></cpanel> + +If an element instantiating a layout element has ``inputtag`` and ``inputmask`` +attributes but lacks a ``name`` attribute, it will take its state from the value +of the corresponding I/O port, masked with the ``inputmask`` value, and shifted +to the right so that the least significant one bit of the mask aligns with the +least significant bit of the value (for example a mask of 0x05 will result in no +shift, while a mask of 0xb0 will result in the value being shifted four bits to +the right). This is often used to allow clickable buttons and toggle switches +to provide visible feedback. + +When handling mouse input, MAME treats all layout elements as being rectangular, +and only activates the frontmost element whose area includes the location of the +mouse pointer. + + .. _layout-parts-repeats: Repeating blocks @@ -736,6 +911,22 @@ tiles on each iteration. Rows are connected to I/O ports ``board:IN.7`` at the top to ``board.IN.0`` at the bottom. +.. _layout-errors: + +Error handling +-------------- + +* For internal (developer-supplied) layout files, errors detected by the + ``complay.py`` script result in a build failure. +* MAME will stop loading a layout file if a syntax error is encountered. No + views from the layout will be available. Examples of syntax errors include + undefined element or group references, invalid bounds, invalid colours, + recursively nested groups, and redefined generator parameters. +* When loading a layout file, if a view references a non-existent screen, MAME + will print a warning message and continue. Views referencing non-existent + screens are considered unviable and not available to the user. + + .. _layout-autogen: Automatically-generated views |