diff options
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 57 | ||||
-rw-r--r-- | docs/source/techspecs/layout_script.rst | 64 | ||||
-rw-r--r-- | docs/source/techspecs/luareference.rst | 76 |
3 files changed, 178 insertions, 19 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst index be4965a9e95..c43a7df8e1b 100644 --- a/docs/source/techspecs/layout_files.rst +++ b/docs/source/techspecs/layout_files.rst @@ -406,8 +406,8 @@ usually comes from an I/O port field or an emulated output (see :ref:`layfile-interact-elemstate` for information on connecting an element to an emulated I/O port or output). Any component of an element may be restricted to only drawing when the element’s state is a particular value. Some components -(e.g. multi-segment displays and reels) use the state directly to determine -their appearance. +(e.g. multi-segment displays) use the state directly to determine their +appearance. Each element has its own internal coordinate system. The bounds of the element’s coordinate system are computed as the union of the bounds of the @@ -591,10 +591,6 @@ simplecounter to set text alignment. If present, the ``align`` attribute must be an integer, where 0 (zero) means centred, 1 (one) means left-aligned, and 2 (two) means right-aligned; if absent, the text will be centred. -reel - Used for drawing slot machine reels. Supported attributes include - ``symbollist``, ``stateoffset``, ``numsymbolsvisible``, ``reelreversed``, - and ``beltreel``. An example element that draws a static left-aligned text string: @@ -839,6 +835,48 @@ have their colour and position/size animated by supplying multiple ``color`` and/or ``bounds`` child elements with ``state`` attributes. See :ref:`layfile-interact-itemanim` for details. +Layout elements (``element`` elements) may be configured to show only part of +the element’s width or height using ``xscroll`` and/or ``yscroll`` child +elements. This can be used for devices like slot machine reels. The +``xscroll`` and ``yscroll`` elements support the same attributes: + +size + The size of the horizontal or vertical scroll window, as a proportion of the + element’s width or height, respectively. Must be in the range 0.01 to 1.0, + inclusive, if present (1% of the width/height to the full width/height). By + default, the entire width and height of the element is shown. +wrap + Whether the element should wrap horizontally or vertically. Must be either + ``yes`` or ``no`` if present. By default, items do not wrap horizontally or + vertically. +inputtag + If present, the horizontal or vertical scroll position will be taken from + the value of the corresponding I/O port. Specifies the tag path of an I/O + port relative to the device that caused the layout file to be loaded. The + raw value from the input port is used, active-low switch values are not + normalised. +name + If present, the horizontal or vertical scroll position will be taken from + the correspondingly named output. +mask + If present, the horizontal or vertical scroll position will be masked with + the value and shifted to the right to remove trailing zeroes (for example a + mask of 0x05 will result in no shift, while a mask of 0x68 will result in + the value being shifted three bits to the right). Note that this applies to + output values (specified with the ``name`` attribute) as well as input port + values (specified with the ``inputtag`` attribute). Must be an integer + value if present. If not present, it is equivalent to all 32 bits being + set. +min + Minimum horizontal or vertical scroll position value. When the horizontal + or vertical scroll position has this value, the left or top edge or the + scroll window will be aligned with the left or top edge of the element. + Must be an integer value if present. Defaults to zero. +max + Maximum horizontal or vertical scroll position value. Must be an integer + value if present. Defaults to the ``mask`` value shifted to the right to + remove trailing zeroes. + .. _layfile-parts-collections: @@ -1149,9 +1187,8 @@ Clickable items item will activate the emulated switch. State-dependent components Some components will be drawn differently depending on the containing - element’s state. These include the dot matrix, multi-segment LED display, - simple counter and reel elements. See :ref:`layfile-parts-elements` for - details. + element’s state. These include the dot matrix, multi-segment LED display + and simple counter elements. See :ref:`layfile-parts-elements` for details. Conditionally-drawn components Components may be conditionally drawn or hidden depending on the containing element’s state by supplying ``state`` and/or ``statemask`` attributes. See @@ -1298,7 +1335,7 @@ If the ``animate`` child element has a ``mask`` attribute, the item’s animatio state will be masked with the ``mask`` value and shifted to the right to remove trailing zeroes (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). -Note that the ``mask`` attribute applies to output value (specified with the +Note that the ``mask`` attribute applies to output values (specified with the ``name`` attribute) as well as input port values (specified with the ``inputtag`` attribute). If the ``mask`` attribute is present, it must be an integer value. If the ``mask`` attribute is not present, it is equivalent to diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst index 7602de6f7f4..f2b8ef1cbc3 100644 --- a/docs/source/techspecs/layout_script.rst +++ b/docs/source/techspecs/layout_script.rst @@ -259,7 +259,7 @@ Here’s our layout file: <bounds x="0" y="0" width="0.1" height="0.1" /> <color alpha="0" /> </rect> - <!-- draw the outlined of a square --> + <!-- draw the outline of a square --> <rect><bounds x="0.02" y="0.02" width="0.06" height="0.01" /></rect> <rect><bounds x="0.02" y="0.07" width="0.06" height="0.01" /></rect> <rect><bounds x="0.02" y="0.02" width="0.01" height="0.06" /></rect> @@ -289,7 +289,7 @@ Here’s our layout file: <element id="vertical" ref="line"> <!-- element draws a vertical line, no need to rotate it --> <orientation rotate="0" /> - <!-- centre it in the square horizotnally, using the full height --> + <!-- centre it in the square horizontally, using the full height --> <bounds x="4.55" y="1.9" width="0.1" height="1" /> </element> @@ -301,7 +301,7 @@ Here’s our layout file: <bounds x="4.1" y="2.35" width="1" height="0.1" /> </element> - <!-- draw a small box at the intersection of the vertical and horiztonal lines --> + <!-- draw a small box at the intersection of the vertical and horizontal lines --> <element id="box" ref="box"> <bounds x="4.55" y="2.35" width="0.1" height="0.1" /> </element> @@ -595,7 +595,7 @@ Get item bounds argument to restore the default bounds handler (based on the item’s animation state and ``bounds`` child elements). Get item colour - ``item::set_color_callback(cb)`` + ``item:set_color_callback(cb)`` Set callback for getting the item’s colour (the element texture’s colours multiplied by this colour). Do not attempt to access the item’s ``color`` @@ -605,3 +605,59 @@ Get item colour ARGB colour (usually created by calling ``emu.render_color``), and takes no parameters. Call with ``nil`` as the argument to restore the default colour handler (based on the item’s animation state and ``color`` child elements). +Get item horizontal scroll window size + ``item:set_scroll_size_x_callback(cb)`` + + Set callback for getting the item’s horizontal scroll window size. This + allows the script to control how much of the element is displayed by the + item. Do not attempt to access the item’s ``scroll_size_x`` property from + the callback, as it will result in infinite recursion. + + The callback function must return a floating-point number representing the + horizontal window size as a proportion of the associated element’s width, + and takes no parameters. A value of 1.0 will display the entire width of + the element; smaller values will display proportionally smaller parts of the + element. Call with ``nil`` as the argument to to restore the default + horizontal scroll window size handler (based on the ``xscroll`` child + element). +Get item vertical scroll window size + ``item:set_scroll_size_y_callback(cb)`` + + Set callback for getting the item’s vertical scroll window size. This + allows the script to control how much of the element is displayed by the + item. Do not attempt to access the item’s ``scroll_size_y`` property from + the callback, as it will result in infinite recursion. + + The callback function must return a floating-point number representing the + vertical window size as a proportion of the associated element’s height, and + takes no parameters. A value of 1.0 will display the entire height of the + element; smaller values will display proportionally smaller parts of the + element. Call with ``nil`` as the argument to to restore the default + vertical scroll window size handler (based on the ``xscroll`` child + element). +Get item horizontal scroll position + ``item:set_scroll_pos_x_callback(cb)`` + + Set callback for getting the item’s horizontal scroll position. This allows + the script to control which part of the element is displayed by the item. + Do not attempt to access the item’s ``scroll_pos_x`` property from the + callback, as this will result in infinite recursion. + + The callback must return a floating-point number, and takes no parameters. + A value of 0.0 aligns the left edge of the element with the left edge of the + item; larger values pan right. Call with ``nil`` as the argument to restore + the default horizontal scroll position handler (based on bindings in the + ``xscroll`` child element). +Get item vertical scroll position + ``item:set_scroll_pos_y_callback(cb)`` + + Set callback for getting the item’s vertical scroll position. This allows + the script to control which part of the element is displayed by the item. + Do not attempt to access the item’s ``scroll_pos_y`` property from the + callback, as this will result in infinite recursion. + + The callback must return a floating-point number, and takes no parameters. + A value of 0.0 aligns the top edge of the element with the top edge of the + item; larger values pan down. Call with ``nil`` as the argument to restore + the default vertical scroll position handler (based on bindings in the + ``yscroll`` child element). diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst index 3cea683f547..85c7ea8cb8a 100644 --- a/docs/source/techspecs/luareference.rst +++ b/docs/source/techspecs/luareference.rst @@ -2815,7 +2815,7 @@ view.has_art Layout view item ~~~~~~~~~~~~~~~~ -Wraps MAME’s ``layout_view::item`` class, representing an item in a view. An +Wraps MAME’s ``layout_view_item`` class, representing an item in a view. An item is drawn as a rectangular textured surface. The texture is supplied by an emulated screen or a layout element. @@ -2832,7 +2832,7 @@ Methods item:set_state(state) Set the value used as the element state and animation state in the absence of bindings. The argument must be an integer. -item.set_element_state_callback(cb) +item:set_element_state_callback(cb) Set a function to call to obtain the element state for the item. The function must accept no arguments and return an integer. Call with ``nil`` to restore the default element state callback (based on bindings in the XML @@ -2844,7 +2844,7 @@ item.set_element_state_callback(cb) This callback will not be used to obtain the animation state for the item, even if the item lacks explicit animation state bindings in the XML layout file. -item.set_animation_state_callback(cb) +item:set_animation_state_callback(cb) Set a function to call to obtain the animation state for the item. The function must accept no arguments and return an integer. Call with ``nil`` to restore the default animation state callback (based on bindings in the @@ -2852,7 +2852,7 @@ item.set_animation_state_callback(cb) Note that the function must not access the item’s ``animation_state`` property, as this will result in infinite recursion. -item.set_bounds_callback(cb) +item:set_bounds_callback(cb) Set a function to call to obtain the bounds for the item. The function must accept no arguments and return a :ref:`render bounds <luareference-render-bounds>` object in render target @@ -2862,7 +2862,7 @@ item.set_bounds_callback(cb) Note that the function must not access the item’s ``bounds`` property, as this will result in infinite recursion. -item.set_color_callback(cb) +item:set_color_callback(cb) Set a function to call to obtain the multiplier colour for the item. The function must accept no arguments and return a :ref:`render colour <luareference-render-color>` object. Call with ``nil`` @@ -2871,6 +2871,50 @@ item.set_color_callback(cb) Note that the function must not access the item’s ``color`` property, as this will result in infinite recursion. +item:set_scroll_size_x_callback(cb) + Set a function to call to obtain the size of the horizontal scroll window as + a proportion of the associated element’s width. The function must accept no + arguments and return a floating-point value. Call with ``nil`` to restore + the default horizontal scroll window size callback (based on the ``xscroll`` + child element in the XML layout file). + + Note that the function must not access the item’s ``scroll_size_x`` + property, as this will result in infinite recursion. +item:set_scroll_size_y_callback(cb) + Set a function to call to obtain the size of the vertical scroll window as a + proportion of the associated element’s height. The function must accept no + arguments and return a floating-point value. Call with ``nil`` to restore + the default vertical scroll window size callback (based on the ``yscroll`` + child element in the XML layout file). + + Note that the function must not access the item’s ``scroll_size_y`` + property, as this will result in infinite recursion. +item:set_scroll_pos_x_callback(cb) + Set a function to call to obtain the horizontal scroll position. A value of + zero places the horizontal scroll window at the left edge of the associated + element. If the item does not wrap horizontally, a value of 1.0 places the + horizontal scroll window at the right edge of the associated element; if the + item wraps horizontally, a value of 1.0 corresponds to wrapping back to the + left edge of the associated element. The function must accept no arguments + and return a floating-point value. Call with ``nil`` to restore the default + horizontal scroll position callback (based on bindings in the ``xscroll`` + child element in the XML layout file). + + Note that the function must not access the item’s ``scroll_pos_x`` property, + as this will result in infinite recursion. +item:set_scroll_pos_y_callback(cb) + Set a function to call to obtain the vertical scroll position. A value of + zero places the vertical scroll window at the top edge of the associated + element. If the item does not wrap vertically, a value of 1.0 places the + vertical scroll window at the bottom edge of the associated element; if the + item wraps vertically, a value of 1.0 corresponds to wrapping back to the + left edge of the associated element. The function must accept no arguments + and return a floating-point value. Call with ``nil`` to restore the default + vertical scroll position callback (based on bindings in the ``yscroll`` + child element in the XML layout file). + + Note that the function must not access the item’s ``scroll_pos_y`` property, + as this will result in infinite recursion. Properties ^^^^^^^^^^ @@ -2892,6 +2936,28 @@ item.color (read-only) The item’s colour for the current state. The colour of the screen or element texture is multiplied by this colour. This is a :ref:`render colour <luareference-render-color>` object. +item.scroll_wrap_x (read-only) + A Boolean indicating whether the item wraps horizontally. +item.scroll_wrap_y (read-only) + A Boolean indicating whether the item wraps vertically. +item.scroll_size_x (read/write) + Get the item’s horizontal scroll window size for the current state, or set + the horizontal scroll window size to use in the absence of bindings. This + is a floating-point value representing a proportion of the associated + element’s width. +item.scroll_size_y (read/write) + Get the item’s vertical scroll window size for the current state, or set the + vertical scroll window size to use in the absence of bindings. This is a + floating-point value representing a proportion of the associated element’s + height. +item.scroll_pos_x (read/write) + Get the item’s horizontal scroll position for the current state, or set the + horizontal scroll position size to use in the absence of bindings. This is + a floating-point value. +item.scroll_pos_y (read/write) + Get the item’s vertical scroll position for the current state, or set the + vertical position size to use in the absence of bindings. This is a + floating-point value. item.blend_mode (read-only) Get the item’s blend mode. This is an integer value, where 0 means no blending, 1 means alpha blending, 2 means RGB multiplication, 3 means |