diff options
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 13 | ||||
-rw-r--r-- | docs/source/techspecs/layout_script.rst | 93 |
2 files changed, 101 insertions, 5 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst index d9976faf00d..297521bf945 100644 --- a/docs/source/techspecs/layout_files.rst +++ b/docs/source/techspecs/layout_files.rst @@ -1188,7 +1188,7 @@ Clickable items If a view item (``element`` or ``screen`` element) has ``inputtag`` and ``inputmask`` attribute values that correspond to a digital switch field in the emulated system, clicking the element will activate the switch. The switch -will remain active as long as the mouse button is held down and the pointer is +will remain active as long as the primary button is held down and the pointer is within the item’s current bounds. (Note that the bounds may change depending on the item’s animation state, see :ref:`layfile-interact-itemanim`). @@ -1197,6 +1197,12 @@ device that caused the layout file to be loaded. The ``inputmask`` attribute must be an integer specifying the bits of the I/O port field that the item should activate. This sample shows instantiation of clickable buttons: +The ``clickthrough`` attribute controls whether clicks can pass through the view +item to other view items drawn above it. The ``clickthrough`` attribute must be +``yes`` or ``no`` if present. The default is ``no`` (clicks do not pass +through) for view items with ``inputtag`` and ``inputmask`` attributes, and +``yes`` (clicks pass through) for other view items. + .. code-block:: XML <element ref="btn_3" inputtag="X2" inputmask="0x10"> @@ -1209,9 +1215,8 @@ should activate. This sample shows instantiation of clickable buttons: <bounds x="1.775" y="5.375" width="1.0" height="1.0" /> </element> -When handling mouse input, MAME treats all layout elements as being rectangular, -and only activates the first clickable item whose area includes the location of -the mouse pointer. +When handling pointer input, MAME treats all layout elements as being +rectangular. .. _layfile-interact-elemstate: diff --git a/docs/source/techspecs/layout_script.rst b/docs/source/techspecs/layout_script.rst index be6166a7146..7e5b7419bb7 100644 --- a/docs/source/techspecs/layout_script.rst +++ b/docs/source/techspecs/layout_script.rst @@ -563,6 +563,96 @@ Dimensions recomputed The callback function has no return value and takes no parameters. Call with ``nil`` as the argument to remove the event handler. +Pointer updated + ``view:set_pointer_updated_callback(cb)`` + + Called when a pointer enters, moves or changes button state over the view. + + The callback function is passed nine arguments: + + * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch`` + or ``unknown``, and will not change for the lifetime of a pointer. + * The pointer ID. This will be a non-negative integer that will not change + for the lifetime of a pointer. Pointer ID values are recycled + aggressively. + * The device ID. This will be a non-negative integer that can be used to + group pointers for recognising multi-touch gestures. + * The horizontal position of the pointer in layout coordinates. + * The vertical position of the pointer in layout coordinates. + * A bit mask representing the currently pressed buttons. The primary button + is the least significant bit. + * A bit mask representing the buttons that were pressed in this update. The + primary button is the least significant bit. + * A bit mask representing the buttons that were released in this update. + The primary button is the least significant bit. + * The click count. This is positive for multi-click actions, or negative if + a click is turned into a hold or drag. This only applies to the primary + button. + + The callback function has no return value. Call with ``nil`` as the + argument to remove the event handler. +Pointer left + ``view:set_pointer_left_callback(cb)`` + + Called when a pointer leaves the view normally. After receiving this event, + the pointer ID may be reused for a new pointer. + + The callback function is passed seven arguments: + + * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch`` + or ``unknown``, and will not change for the lifetime of a pointer. + * The pointer ID. This will be a non-negative integer that will not change + for the lifetime of a pointer. Pointer ID values are recycled + aggressively. + * The device ID. This will be a non-negative integer that can be used to + group pointers for recognising multi-touch gestures. + * The horizontal position of the pointer in layout coordinates. + * The vertical position of the pointer in layout coordinates. + * A bit mask representing the buttons that were released in this update. + The primary button is the least significant bit. + * The click count. This is positive for multi-click actions, or negative if + a click is turned into a hold or drag. This only applies to the primary + button. + + The callback function has no return value. Call with ``nil`` as the + argument to remove the event handler. +Pointer aborted + ``view:set_pointer_aborted_callback(cb)`` + + Called when a pointer leaves the view abnormally. After receiving this + event, the pointer ID may be reused for a new pointer. + + The callback function is passed seven arguments: + + * The pointer type as a string. This will be ``mouse``, ``pen``, ``touch`` + or ``unknown``, and will not change for the lifetime of a pointer. + * The pointer ID. This will be a non-negative integer that will not change + for the lifetime of a pointer. Pointer ID values are recycled + aggressively. + * The device ID. This will be a non-negative integer that can be used to + group pointers for recognising multi-touch gestures. + * The horizontal position of the pointer in layout coordinates. + * The vertical position of the pointer in layout coordinates. + * A bit mask representing the buttons that were released in this update. + The primary button is the least significant bit. + * The click count. This is positive for multi-click actions, or negative if + a click is turned into a hold or drag. This only applies to the primary + button. + + The callback function has no return value. Call with ``nil`` as the + argument to remove the event handler. +Forget pointers + ``view:set_forget_pointers_callback(cb)`` + + Called when the view should stop processing pointer input. This can happen + in a number of situations, including: + + * The user activated a menu. + * The view configuration will change. + * The view will be deactivated. + + The callback function has no return value and takes no parameters. Call + with ``nil`` as the argument to remove the event handler. .. _layscript-events-item: @@ -692,4 +782,5 @@ Draw The callback is passed two arguments: the element state (an integer) and the 32-bit ARGB bitmap at the required size. The callback must not attempt to - resize the bitmap. + resize the bitmap. Call with ``nil`` as the argument to remove the event + handler. |