diff options
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/commandline/sdlconfig.rst | 10 | ||||
-rw-r--r-- | docs/source/luascript/ref-input.rst | 10 | ||||
-rw-r--r-- | docs/source/luascript/ref-render.rst | 60 | ||||
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 13 | ||||
-rw-r--r-- | docs/source/techspecs/layout_script.rst | 93 | ||||
-rw-r--r-- | docs/source/usingmame/ui.rst | 30 |
6 files changed, 197 insertions, 19 deletions
diff --git a/docs/source/commandline/sdlconfig.rst b/docs/source/commandline/sdlconfig.rst index eea4b959e60..df04865a390 100644 --- a/docs/source/commandline/sdlconfig.rst +++ b/docs/source/commandline/sdlconfig.rst @@ -61,9 +61,17 @@ SDL Keyboard Mapping Keymap file name. Default is ``keymap.dat``. -SDL Joystick Mapping +SDL Input Options -------------------- +.. _mame-scommandline-enabletouch: + +**-enable_touch** + + Enable support for touch input. If this option is switched off, mouse input + simulated from touch devices will be used instead. Default is OFF + (**-noenable_touch**) + .. _mame-scommandline-sixaxis: **-sixaxis** diff --git a/docs/source/luascript/ref-input.rst b/docs/source/luascript/ref-input.rst index 7390d46743f..f146d6c78ff 100644 --- a/docs/source/luascript/ref-input.rst +++ b/docs/source/luascript/ref-input.rst @@ -750,16 +750,6 @@ uiinput:reset() Clears pending events and UI input states. Should be called when leaving a modal state where input is handled directly (e.g. configuring an input combination). -uiinput:find_mouse() - Returns host system mouse pointer X position, Y position, button state, and - the :ref:`render target <luascript-ref-rendertarget>` it falls in. The - position is in host pixels, where zero is at the top/left. The button state - is a Boolean indicating whether the primary mouse button is pressed. - - If the mouse pointer is not over one of MAME’s windows, this may return the - position and render target from when the mouse pointer was most recently - over one of MAME’s windows. The render target may be ``nil`` if the mouse - pointer is not over one of MAME’s windows. uiinput:pressed(type) Returns a Boolean indicating whether the specified UI input has been pressed. The input type is an enumerated value. diff --git a/docs/source/luascript/ref-render.rst b/docs/source/luascript/ref-render.rst index 265e52b5016..eee432660dd 100644 --- a/docs/source/luascript/ref-render.rst +++ b/docs/source/luascript/ref-render.rst @@ -1057,6 +1057,66 @@ view:set_recomputed_callback(cb) View coordinates are recomputed in various events, including the window being resized, entering or leaving full-screen mode, and changing the zoom to screen area setting. +view:set_pointer_updated_callback(cb) + Set a function to receive notifications when a pointer enters, moves or + changes button states over the view. The function must accept nine + arguments: + + * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``). + * The pointer ID (a non-negative integer that will not change for the + lifetime of a pointer). + * The device ID for grouping pointers to recognise multi-touch gestures + (non-negative integer). + * Horizontal position in layout coordinates. + * Vertical position in layout coordinates. + * A bit mask representing the currently pressed buttons. + * A bit mask representing the buttons that were pressed in this update. + * A bit mask representing the buttons that were released in this update. + * The click count (positive for multi-click actions, or negative if a click + is turned into a hold or drag). + + Call with ``nil`` to remove the callback. +view:set_pointer_left_callback(cb) + Set a function to receive notifications when a pointer leaves the view + normally. The function must accept seven arguments: + + * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``). + * The pointer ID (a non-negative integer that will not change for the + lifetime of a pointer). The ID may be reused for a new pointer after + receiving this notification. + * The device ID for grouping pointers to recognise multi-touch gestures + (non-negative integer). + * Horizontal position in layout coordinates. + * Vertical position in layout coordinates. + * A bit mask representing the buttons that were released in this update. + * The click count (positive for multi-click actions, or negative if a click + is turned into a hold or drag). + + Call with ``nil`` to remove the callback. +view:set_pointer_aborted_callback(cb) + Set a function to receive notifications when a pointer leaves the view + abnormally. The function must accept seven arguments: + + * The pointer type (``mouse``, ``pen``, ``touch`` or ``unknown``). + * The pointer ID (a non-negative integer that will not change for the + lifetime of a pointer). The ID may be reused for a new pointer after + receiving this notification. + * The device ID for grouping pointers to recognise multi-touch gestures + (non-negative integer). + * Horizontal position in layout coordinates. + * Vertical position in layout coordinates. + * A bit mask representing the buttons that were released in this update. + * The click count (positive for multi-click actions, or negative if a click + is turned into a hold or drag). + + Call with ``nil`` to remove the callback. +view:set_forget_pointers_callback(cb) + Set a function to receive notifications when the view should stop processing + pointer input. The function must accept no arguments. Call with ``nil`` to + remove the callback. + + This can happen in a number of situations, including the view configuration + changing or a menu taking over input handling. Properties ~~~~~~~~~~ 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. diff --git a/docs/source/usingmame/ui.rst b/docs/source/usingmame/ui.rst index 60bb55618a2..94c7eba413d 100644 --- a/docs/source/usingmame/ui.rst +++ b/docs/source/usingmame/ui.rst @@ -136,9 +136,9 @@ 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 with too many items to fit on the screen, click the upward- or - downward-pointing triangle at the top or bottom to scroll up or down by one - screen at a time. +* 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. @@ -148,6 +148,28 @@ 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 @@ -493,6 +515,8 @@ 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: |