summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs')
-rw-r--r--docs/source/techspecs/luareference.rst131
1 files changed, 96 insertions, 35 deletions
diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst
index 30c5c88826d..7e8e1ea9dff 100644
--- a/docs/source/techspecs/luareference.rst
+++ b/docs/source/techspecs/luareference.rst
@@ -121,11 +121,11 @@ Properties
^^^^^^^^^^
t.is_zero (read-only)
- Whether the value represents no elapsed time.
+ A Boolean indicating whether the value represents no elapsed time.
t.is_never (read-only)
- Whether the value is greater than the maximum number of whole seconds that
- can be represented (treated as an unreachable time in the future or
- overflow).
+ A Boolean indicating whether the value is greater than the maximum number of
+ whole seconds that can be represented (treated as an unreachable time in the
+ future or overflow).
t.attoseconds (read-only)
The fraction seconds portion of the interval in attoseconds.
t.seconds (read-only)
@@ -517,7 +517,8 @@ ui:set_aggressive_input_focus(enable)
On some platforms, this controls whether MAME should accept input focus in
more situations than when its windows have UI focus.
ui:get_general_input_setting(type, [player])
- Gets a description of the configured input sequence for the specified input
+ Gets a description of the configured
+ :ref:`input sequence <luareference-input-iptseq>` for the specified input
type and player suitable for using in prompts. The input type is an
enumerated value. The player number is a zero-based index. If the player
number is not supplied, it is assumed to be zero.
@@ -1660,14 +1661,21 @@ ioport:type_group(type, player)
This should be called with values obtained from I/O port fields to provide
canonical grouping in an input configuration UI.
ioport:type_seq(type, [player], [seqtype])
- Get the configured input sequence for the specified input type, player
- number and sequence type. The input type is an enumerated value. The
- player number is a zero-based index. If the player number is not supplied,
- it is assumed to be zero. If the sequence type is supplied, it must be
- ``"standard"``, ``"increment"`` or ``"decrement"``; if it is not supplied,
- it is assumed to be ``"standard"``.
+ Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
+ specified input type, player number and sequence type. The input type is an
+ enumerated value. The player number is a zero-based index. If the player
+ number is not supplied, it is assumed to be zero. If the sequence type is
+ supplied, it must be ``"standard"``, ``"increment"`` or ``"decrement"``; if
+ it is not supplied, it is assumed to be ``"standard"``.
This provides access to general input configuration.
+ioport:set_type_seq(type, player, seqtype, seq)
+ Set the configured :ref:`input sequence <luareference-input-iptseq>` for the
+ specified input type, player number and sequence type. The input type is an
+ enumerated value. The player number is a zero-based index. The sequence
+ type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
+
+ This allows general input configuration to be set.
ioport:token_to_input_type(string)
Returns the input type and player number for the specified input type token.
ioport:input_type_to_token(type, [player])
@@ -1852,21 +1860,24 @@ field:set_value(value)
compared to zero to determine whether the field should be active; for
analog fields, the value must be right-aligned and in the correct range.
field:set_input_seq(seqtype, seq)
- Set the input sequence for the specified sequence type. This is used to
- configure per-machine input settings. The sequence type must be
- ``"standard"``, ``"increment"`` or ``"decrement"``.
+ Set the :ref:`input sequence <luareference-input-iptseq>` for the
+ specified sequence type. This is used to configure per-machine input
+ settings. The sequence type must be ``"standard"``, ``"increment"`` or
+ ``"decrement"``.
field:input_seq(seq_type)
- Get the configured input sequence for the specified sequence type. This
- gets per-machine input settings. The sequence type must be ``"standard"``,
- ``"increment"`` or ``"decrement"``.
+ Get the configured :ref:`input sequence <luareference-input-iptseq>` for the
+ specified sequence type. This gets per-machine input assignments. The
+ sequence type must be ``"standard"``, ``"increment"`` or ``"decrement"``.
field:set_default_input_seq(seq_type, seq)
- Set the default input sequence for the specified sequence type. This is
- used to configure general input settings. The sequence type must be
- ``"standard"``, ``"increment"`` or ``"decrement"``.
+ Set the default :ref:`input sequence <luareference-input-iptseq>` for the
+ specified sequence type. This overrides the default input assignment for a
+ specific input. The sequence type must be ``"standard"``, ``"increment"``
+ or ``"decrement"``.
field:default_input_seq(seq_type)
- Gets the default input sequence for the specified sequence type. This is
- gets general input settings. The sequence type must be ``"standard"``,
- ``"increment"`` or ``"decrement"``.
+ Gets the default :ref:`input sequence <luareference-input-iptseq>` for the
+ specified sequence type. If the default assignment is not overridden, this
+ gets the general input assignment. The sequence type must be
+ ``"standard"``, ``"increment"`` or ``"decrement"``.
field:keyboard_codes(shift)
Gets a table of characters corresponding to the field for the specified
shift state. The shift state is a bit mask of active shift keys.
@@ -2009,18 +2020,20 @@ input:code_from_token(token)
Convert a token string to an input code. Returns the invalid input code if
the token is not valid or belongs to an input device that is not present.
input:seq_pressed(seq)
- Returns a Boolen indicating whether the supplied input sequence is currently
- pressed.
+ Returns a Boolean indicating whether the supplied
+ :ref:`input sequence <luareference-input-iptseq>` is currently pressed.
input:seq_clean(seq)
- Remove invalid elements from the supplied input sequence. Returns the new,
- cleaned input sequence.
+ Remove invalid elements from the supplied
+ :ref:`input sequence <luareference-input-iptseq>`. Returns the new, cleaned
+ input sequence.
input:seq_name(seq)
- Get display text for an inptu sequence.
+ Get display text for an :ref:`input sequence <luareference-input-iptseq>`.
input:seq_to_tokens(seq)
- Convert an input sequence to a token string. This should be used when
- saving configuration.
+ Convert an :ref:`input sequence <luareference-input-iptseq>` to a token
+ string. This should be used when saving configuration.
input:seq_from_tokens(tokens)
- Convert a token string to an input sequence. This should be used when
+ Convert a token string to an
+ :ref:`input sequence <luareference-input-iptseq>`. This should be used when
loading configuration.
input:axis_code_poller()
Returns an :ref:`input code poller <luareference-input-codepoll>` for
@@ -2034,10 +2047,12 @@ input:keyboard_code_poller()
devices.
input:axis_sequence_poller()
Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an input sequence for configuring an analog input.
+ obtaining an :ref:`input sequence <luareference-input-iptseq>` for
+ configuring an analog input.
input:axis_sequence_poller()
Returns an :ref:`input sequence poller <luareference-input-seqpoll>` for
- obtaining an input sequence for configuring a digital input.
+ obtaining an :ref:`input sequence <luareference-input-iptseq>` for
+ configuring a digital input.
Properties
^^^^^^^^^^
@@ -2112,14 +2127,60 @@ Properties
^^^^^^^^^^
poller.sequence (read-only)
- The current input sequence. This is updated while polling. It is possible
- for the sequence to become invalid.
+ The current :ref:`input sequence <luareference-input-iptseq>`. This is
+ updated while polling. It is possible for the sequence to become invalid.
poller.valid (read-only)
A Boolean indicating whether the current input sequence is valid.
poller.modified (read-only)
A Boolean indicating whether the sequence was changed by any user input
since starting polling.
+.. _luareference-input-iptseq:
+
+Input sequence
+~~~~~~~~~~~~~~
+
+Wraps MAME’s ``input_seq`` class, representing a combination of host inputs that
+can be read or assigned to an emulated input. Input sequences can be
+manipulated using :ref:`input manager <luareference-input-inputman>` methods.
+Use an :ref:`input sequence poller <luareference-input-seqpoll>` to obtain an
+input sequence from the user.
+
+Instantiation
+^^^^^^^^^^^^^
+
+emu.input_seq()
+ Creates an empty input sequence.
+emu.input_seq(seq)
+ Creates a copy of an existing input sequence.
+
+Methods
+^^^^^^^
+
+seq:reset()
+ Clears the input sequence, removing all items.
+seq:set_default()
+ Sets the input sequence to a single item containing the metavalue specifying
+ that the default setting should be used.
+
+Properties
+^^^^^^^^^^
+
+seq.empty (read-only)
+ A Boolean indicating whether the input sequence is empty (contains no items,
+ indicating an unassigned input).
+seq.length (read-only)
+ The number of items in the input sequence.
+seq.is_valid (read-only)
+ A Boolean indicating whether the input sequence is a valid. To be valid, it
+ must contain at least one item, all items must be valid codes, all product
+ groups must contain at least one item that is not negated, and items
+ referring to absolute and relative axes must not be mixed within a product
+ group.
+seq.is_default (read-only)
+ A Boolean indicating whether the input sequence specifies that the default
+ setting should be used.
+
.. _luareference-input-devclass:
Host input device class