summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/source/techspecs/layout_files.rst120
1 files changed, 112 insertions, 8 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index 31098111b30..976f51475ca 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -446,10 +446,11 @@ element's coordinate system are computed as the union of the bounds of the
individual components it's composed of.
Every element must have a ``name`` attribute specifying its name. Elements are
-referred to by name when instantiated in groups or views. Elements may
-optionally supply a default state value with a ``defstate`` attribute, to be
-used if not connected to an emulated output or I/O port. If present, the
-``defstate`` attribute must be a non-negative integer.
+referred to by name when instantiated in groups or views. It is an error for a
+layout file to contain multiple elements with identical ``name`` attributes.
+Elements may optionally supply a default state value with a ``defstate``
+attribute, to be used if not connected to an emulated output or I/O port. If
+present, the ``defstate`` attribute must be a non-negative integer.
Child elements of the ``element`` element instantiate components, which are
drawn in reading order from first to last (components draw on top of components
@@ -640,10 +641,13 @@ 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.
+ Sets the origin and size of the view's internal coordinate system if
+ present. See :ref:`layout-concepts-coordinates` for details. If absent,
+ the bounds of the view are computed as the union of the bounds of all
+ screens and elements within the view. It only makes sense to have one
+ ``bounds`` as a direct child of a view element. Any content outside the
+ view's bounds is cropped, and the view is scaled proportionally to fit the
+ output window or screen.
param
Defines or reassigns a value parameter in the view's scope. See
:ref:`layout-concepts-params` for details.
@@ -776,6 +780,106 @@ and only activates the frontmost element whose area includes the location of the
mouse pointer.
+.. _layout-parts-groups:
+
+Reusable groups
+~~~~~~~~~~~~~~~
+
+Groups allow an arrangement of screens and/or layout elements to be used
+multiple times in views or other groups. Groups can be beneficial even if you
+only use the arrangement once, as they can be used to encapsulate part of a
+complex layout. Groups are defined using ``group`` elements inside the
+top-level ``mamelayout`` element, and instantiated using ``group`` elements
+inside ``view`` and other ``group`` elements.
+
+Each group definition element must have a ``name`` attribute providing a unique
+identifier. It is an error if a layout file contains multiple group definitions
+with identical ``name`` attributes. The value of the ``name`` attribute is used
+when instantiating the group from a view or another group. This is an example
+opening tag for a group definition element inside the top-level ``mamelayout``
+element::
+
+ <group name="panel">
+
+This group may then be instantiated in a view or another group element using a
+group reference element, optionally supplying destination bounds, orientation,
+and/or modifier colour. The ``ref`` attribute identifies the group to
+instantiate -- in this example, destination bounds are supplied::
+
+ <group ref="panel"><bounds x="87" y="58" width="23" height="23.5" /></group>
+
+Group definition elements allow all the same child elements as views.
+Positioning and orienting screens, layout elements and nested groups works the
+same way as for views. See :ref:`layout-parts-views` for details. A group may
+instantiate other groups, but recursive loops are not permitted. It is an error
+if a group directly or indirectly instantiates itself.
+
+Groups have their own internal coordinate systems. If a group definition
+element has no ``bounds`` element as a direct child, its bounds are computed as
+the union of the bounds of all the screens, layout elements and/or nested groups
+it instantiates. A ``bounds`` child element may be used to explicitly specify
+group bounds (see :ref:`layout-concepts-coordinates` for details). Note that
+groups' bounds are only used for the purpose of calculating the coordinate
+transform when instantiating a group. A group may position screens and/or
+elements outside its bounds, and they will not be cropped.
+
+To demonstrate how bounds calculation works, consider this example::
+
+ <group name="autobounds">
+ <!-- bounds automatically calculated with origin at (5,10), width 30, and height 15 -->
+ <cpanel element="topleft"><bounds x="5" y="10" width="10" height="10" /></cpanel>
+ <cpanel element="bottomright"><bounds x="25" y="15" width="10" height="10" /></cpanel>
+ </group>
+
+ <view name="Test">
+ <!--
+ group bounds translated and scaled to fit - 2/3 scale horizontally and double vertically
+ element topleft positioned at (0,0) with width 6.67 and height 20
+ element bottomright positioned at (13.33,10) with width 6.67 and height 20
+ view bounds calculated with origin at (0,0), width 20, and height 30
+ -->
+ <group ref="autobounds"><bounds x="0" y="0" width="20" height="30" /></group>
+ </view>
+
+This is relatively straightforward, as all elements inherently fall within the
+group's automatically computed bounds. Now consider what happens if a group
+positions elements outside its explicit bounds::
+
+ <group name="periphery">
+ <!-- elements are above the top edge and to the right of the right edge of the bounds -->
+ <bounds x="10" y="10" width="20" height="25" />
+ <cpanel element="topleft"><bounds x="10" y="0" width="10" height="10" /></cpanel>
+ <cpanel element="bottomright"><bounds x="30" y="20" width="10" height="10" /></cpanel>
+ </group>
+
+ <view name="Test">
+ <!--
+ group bounds translated and scaled to fit - 3/2 scale horizontally and unity vertically
+ element topleft positioned at (5,-5) with width 15 and height 10
+ element bottomright positioned at (35,15) with width 15 and height 10
+ view bounds calculated with origin at (5,-5), width 45, and height 30
+ -->
+ <group ref="periphery"><bounds x="5" y="5" width="30" height="25" /></group>
+ </view>
+
+The group's elements are translated and scaled as necessary to distort the
+group's internal bounds to the destination bounds in the view. The group's
+content is not restricted to its bounds. The view considers the bounds of the
+actual layout elements when computing its bounds, not the destination bounds
+specified for the group.
+
+When a group is instantiated, it creates a nested parameter scope. The logical
+parent scope is the parameter scope of the view, group or repeating block where
+the group is instantiated (*not* its lexical parent, the top-level
+``mamelayout`` element). Any ``param`` elements inside the group definition
+element set parameters in the local scope for the group instantiation. Local
+parameters do not persist across multiple instantiations. See
+:ref:`layout-concepts-params` for more detail on parameters. (Note that the
+group's name is not part of its content, and any parameter references in the
+``name`` attribute itself will be substituted at the point where the group
+definition appears in the top-level ``mamelayout`` element's scope.)
+
+
.. _layout-parts-repeats:
Repeating blocks
per-frame update support to layout elements. [Ryan Ho... mooglyguy5 years saturn_cdblockAttempting to change transfer active mechanism, doesn't change anything, to b... angelosa10 years saturn_vdp_splitsegasaturn_vdp2.cpp: add m_gfxdecode device, fix startup crash. Add notes rev... angelosa3 years save-experimentsBetter handling of null/missing items. More consistent error handling. Reduce... Aaron Giles4 years save_structsUpdate voodoo code to leverage new save_registrar instead of its own temporar... Aaron Giles4 years shangha3_dropshangha3_v.cpp: proposed fix for shangha3 drawing phantom drop shadows for pl... angelosa3 years taitoair_vcotaito/tc0080vco.cpp: describe fix angelosa2 years taitowlf_zoomtaito/taitowlf.cpp: preliminary Zoom hookup angelosa23 months time-experimentsRemaining fixes Aaron Giles4 years time-experiments2Stop memsetting structures. Aaron Giles4 years vamphalf_misncrftvamphalf.cpp: move wyvernwg to own state machine, add some basic protection t... angelosa3 years voodoo_directx11Fix some vegas games not booting Ted Green5 years x86_std-exceptionscpu/i386: saner fatal error handling angelosa13 months xbox_swlisthash/xbox_hdd.xml: QA and srcclean angelosa10 months xtalfull xtal conversion Olivier Galibert43 hours ymfm-delayClean up delay implementation a bit. Move delay setting to immediately after ... Aaron Giles4 years  TagDownloadAuthorAge mame0277commit 84cb44566c... Vas Crabb2 days mame0276commit 758c8a169a... Vas Crabb5 weeks mame0275commit 455ffbbd7e... Vas Crabb2 months mame0274commit cd82a83c3d... Vas Crabb3 months mame0273commit e11cae0a15... Vas Crabb4 months mame0272commit 5d8e4cf07e... Vas Crabb5 months mame0271commit 4da96a0c4f... Vas Crabb6 months mame0270commit ef032a31e5... Vas Crabb7 months mame0269commit 6d1970f5f1... Vas Crabb8 months mame0268commit acea8712d6... Vas Crabb9 months mame0267commit 663abae071... Vas Crabb10 months mame0266commit cd7817b220... Vas Crabb11 months mame0265commit f8af5cc2cf... Vas Crabb12 months mame0264commit 5b670ad51f... Vas Crabb13 months mame0263commit 93d8318325... Vas Crabb14 months mame0262commit d48a61f921... Vas Crabb15 months mame0261commit ca50094e8d... Vas Crabb17 months mame0260commit 0a7f1fe9cf... Vas Crabb18 months mame0259commit 4ff20056c3... Vas Crabb19 months mame0258commit 2e0aa82350... Vas Crabb20 months mame0257commit f811a66c53... Vas Crabb21 months mame0256commit b41370db02... Vas Crabb22 months mame0255commit c6650dc072... Vas Crabb23 months mame0254commit bfa8d724a0... Vas Crabb2 years mame0253commit b6d9756c5e... Vas Crabb2 years mame0252commit fb98822c34... Vas Crabb2 years mame0251commit 34e6ec1ef8... Vas Crabb2 years mame0250commit b7cbe74c4b... Vas Crabb2 years mame0249commit 91c5b9ecea... Vas Crabb3 years mame0248commit 2d3d0deec8... Vas Crabb3 years mame0247commit fa2d36c634... Vas Crabb3 years mame0246commit 205b03897c... Vas Crabb3 years mame0245commit 5d31f0fc97... Vas Crabb3 years mame0244commit bcf77373a5... Vas Crabb3 years mame0243commit addbb8ab40... Vas Crabb3 years mame0242commit e8166b5274... Vas Crabb3 years mame0241commit 31f001e501... Vas Crabb3 years mame0240commit f0ab44fe1c... Vas Crabb3 years mame0239commit 80bcaea1ed... Vas Crabb3 years mame0238commit fb21b78904... Vas Crabb3 years mame0237commit 34d8357465... Vas Crabb4 years mame0236commit 5e865af540... Vas Crabb4 years mame0235commit ec9ba6fa76... Vas Crabb4 years mame0234commit 2633c19a68... Vas Crabb4 years mame0233commit 05d0cf61e7... Vas Crabb4 years mame0232commit 2b0f01bc3a... Vas Crabb4 years mame0231commit 1f22113661... Vas Crabb4 years mame0230commit 943c06cba0... Vas Crabb4 years mame0229commit 4322eaae9d... Vas Crabb4 years mame0228commit 140f446933... Vas Crabb4 years mame0227commit d85735634c... Vas Crabb4 years mame0226commit 3c56452b07... Vas Crabb5 years mame0225commit 5a1fd0cc17... Vas Crabb5 years mame0224commit 5892c78a15... Vas Crabb5 years mame0223commit c55a261d26... Vas Crabb5 years mame0222commit 6d50d60a43... Vas Crabb5 years mame0221commit e8a0e0469b... Vas Crabb5 years mame0220commit c5c5723b9d... Vas Crabb5 years mame0219commit 221f006442... Vas Crabb5 years mame0218commit 0e2a252d30... Vas Crabb5 years mame0217commit 13997a8f31... Vas Crabb5 years mame0216commit b8b7c7e232... Vas Crabb5 years mame0215commit e9ef4808dd... Vas Crabb6 years mame0214commit 24d07a12d7... Vas Crabb6 years mame0213commit f7172322a2... Vas Crabb6 years mame0212commit 1182bd9325... Vas Crabb6 years mame0211commit 1b969a8acb... Vas Crabb6 years mame0210commit ad45c9c609... Vas Crabb6 years mame0209commit 2b317bf296... Vas Crabb6 years mame0208commit 9483624864...