summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/luascript/ref-input.rst
blob: f146d6c78ffca48d5159556459903bdc6af41bff (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
.. _luascript-ref-input:

Lua Input System Classes
========================

Allows scripts to get input from the user, and access I/O ports in the emulated
system.

.. contents::
    :local:
    :depth: 1


.. _luascript-ref-ioportman:

I/O port manager
----------------

Wraps MAME’s ``ioport_manager`` class, which provides access to emulated I/O
ports and handles input configuration.

Instantiation
~~~~~~~~~~~~~

manager.machine.ioport
    Gets the global I/O port manager instance for the emulated machine.

Methods
~~~~~~~

ioport:count_players()
    Returns the number of player controllers in the system.
ioport:type_pressed(type, [player])
    Returns a Boolean indicating whether the specified input is currently
    pressed.  The input type may be an enumerated value or an
    :ref:`input type <luascript-ref-inputtype>` entry.  If the input type is an
    enumerated value, the player number may be supplied as a zero-based index;
    if the player number is not supplied, it is assumed to be zero.  If the
    input type is an input type entry, the player number may not be supplied
    separately.
ioport:type_name(type, [player])
    Returns the display name for the specified input type and player number.
    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.
ioport:type_group(type, player)
    Returns the input group for the specified input type and player number.  The
    input type is an enumerated value.  The player number is a zero-based index.
    Returns an integer giving the grouping for the input.  If the player number
    is not supplied, it is assumed to be zero.

    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 :ref:`input sequence <luascript-ref-inputseq>` for the
    specified input type, player number and sequence type.  The input type may
    be an enumerated value or an
    :ref:`input type <luascript-ref-inputtype>` entry.  If the input type is an
    enumerated value, the player number may be supplied as a zero-based index;
    if the player number is not supplied, it is assumed to be zero.  If the
    input type is an input type entry, the player number may not be supplied
    separately.  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 assignments.
ioport:set_type_seq(type, [player], seqtype, seq)
    Set the configured :ref:`input sequence <luascript-ref-inputseq>` for the
    specified input type, player number and sequence type.  The input type may
    be an enumerated value or an
    :ref:`input type <luascript-ref-inputtype>` entry.  If the input type is an
    enumerated value, the player number must be supplied as a zero-based index.
    If the input type is an input type entry, the player number may not be
    supplied separately.  The sequence type must be ``"standard"``,
    ``"increment"`` or ``"decrement"``.

    This allows general input assignments to be set.
ioport:token_to_input_type(string)
    Returns the input type and player number for the specified input type token
    string.
ioport:input_type_to_token(type, [player])
    Returns the token string for the specified input type and player number.  If
    the player number is not supplied, it assumed to be zero.

Properties
~~~~~~~~~~

ioport.types[] (read-only)
    Gets the supported :ref:`input types <luascript-ref-inputtype>`.  Keys are
    arbitrary indices.  All supported operations have O(1) complexity.
ioport.ports[]
    Gets the emulated :ref:`I/O ports <luascript-ref-ioport>` in the system.
    Keys are absolute tags.  The ``at`` and ``index_of`` methods have O(n)
    complexity; all other supported operations have O(1) complexity.


.. _luascript-ref-natkbdman:

Natural keyboard manager
------------------------

Wraps MAME’s ``natural_keyboard`` class, which manages emulated keyboard and
keypad inputs.

Instantiation
~~~~~~~~~~~~~

manager.machine.natkeyboard
    Gets the global natural keyboard manager instance for the emulated machine.

Methods
~~~~~~~

natkeyboard:post(text)
    Post literal text to the emulated machine.  The machine must have keyboard
    inputs with character bindings, and the correct keyboard input device must
    be enabled.
natkeyboard:post_coded(text)
    Post text to the emulated machine.  Brace-enclosed codes are interpreted in
    the text.  The machine must have keyboard inputs with character bindings,
    and the correct keyboard input device must be enabled.

    The recognised codes are ``{BACKSPACE}``, ``{BS}``, ``{BKSP}``, ``{DEL}``,
    ``{DELETE}``, ``{END}``, ``{ENTER}``, ``{ESC}``, ``{HOME}``, ``{INS}``,
    ``{INSERT}``, ``{PGDN}``, ``{PGUP}``, ``{SPACE}``, ``{TAB}``, ``{F1}``,
    ``{F2}``, ``{F3}``, ``{F4}``, ``{F5}``, ``{F6}``, ``{F7}``, ``{F8}``,
    ``{F9}``, ``{F10}``, ``{F11}``, ``{F12}``, and ``{QUOTE}``.
natkeyboard:paste()
    Post the contents of the host clipboard to the emulated machine.  The
    machine must have keyboard inputs with character bindings, and the correct
    keyboard input device must be enabled.
natkeyboard:dump()
    Returns a string with a human-readable description of the keyboard and
    keypad input devices in the system, whether they are enabled, and their
    character bindings.

Properties
~~~~~~~~~~

natkeyboard.empty (read-only)
    A Boolean indicating whether the natural keyboard manager’s input buffer is
    empty.
natkeyboard.full (read-only)
    A Boolean indicating whether the natural keyboard manager’s input buffer is
    full.
natkeyboard.can_post (read-only)
    A Boolean indicating whether the emulated system supports posting character
    data via the natural keyboard manager.
natkeyboard.is_posting (read-only)
    A Boolean indicating whether posted character data is currently being
    delivered to the emulated system.
natkeyboard.in_use (read/write)
    A Boolean indicating whether “natural keyboard” mode is enabled.  When
    “natural keyboard” mode is enabled, the natural keyboard manager translates
    host character input to emulated system keystrokes.
natkeyboard.keyboards[]
    Gets the :ref:`keyboard/keypad input devices <luascript-ref-natkbddev>` in
    the emulated system, indexed by absolute device tag.  Index get has O(n)
    complexity; all other supported operations have O(1) complexity.


.. _luascript-ref-natkbddev:

Keyboard input device
---------------------

Represents a keyboard or keypad input device managed by the
:ref:`natural keyboard manager <luascript-ref-natkbdman>`.  Note that this is
not a :ref:`device <luascript-ref-device>` class.

Instantiation
~~~~~~~~~~~~~

manager.machine.natkeyboard.keyboards[tag]
    Gets the keyboard input device with the specified tag, or ``nil`` if the tag
    does not correspond to a keyboard input device.

Properties
~~~~~~~~~~

keyboard.device (read-only)
    The underlying :ref:`device <luascript-ref-device>`.
keyboard.tag (read-only)
    The absolute tag of the underlying device.
keyboard.basetag (read-only)
    The last component of the tag of the underlying device, or ``"root"`` for
    the root machine device.
keyboard.name (read-only)
    The human-readable description of the underlying device type.
keyboard.shortname (read-only)
    The identifier for the underlying device type.
keyboard.is_keypad (read-only)
    A Boolean indicating whether the underlying device has keypad inputs but no
    keyboard inputs.  This is used when determining which keyboard input devices
    should be enabled by default.
keyboard.enabled (read/write)
    A Boolean indicating whether the device’s keyboard and/or keypad inputs are
    enabled.


.. _luascript-ref-ioport:

I/O port
--------

Wraps MAME’s ``ioport_port`` class, representing an emulated I/O port.

Instantiation
~~~~~~~~~~~~~

manager.machine.ioport.ports[tag]
    Gets an emulated I/O port by absolute tag, or ``nil`` if the tag does not
    correspond to an I/O port.
manager.machine.devices[devtag]:ioport(porttag)
    Gets an emulated I/O port by tag relative to a device, or ``nil`` if no such
    I/O port exists.

Methods
~~~~~~~

port:read()
    Read the current input value.  Returns a 32-bit integer.
port:write(value, mask)
    Write to the I/O port output fields that are set in the specified mask.  The
    value and mask must be 32-bit integers.  Note that this does not set values
    for input fields.
port:field(mask)
    Get the first :ref:`I/O port field <luascript-ref-ioportfield>`
    corresponding to the bits that are set in the specified mask, or ``nil`` if
    there is no corresponding field.

Properties
~~~~~~~~~~

port.device (read-only)
    The device that owns the I/O port.
port.tag (read-only)
    The absolute tag of the I/O port
port.active (read-only)
    A mask indicating which bits of the I/O port correspond to active fields
    (i.e. not unused or unassigned bits).
port.live (read-only)
    The live state of the I/O port.
port.fields[] (read-only)
    Gets a table of :ref:`fields <luascript-ref-ioportfield>` indexed by name.


.. _luascript-ref-ioportfield:

I/O port field
--------------

Wraps MAME’s ``ioport_field`` class, representing a field within an I/O port.

Instantiation
~~~~~~~~~~~~~

manager.machine.ioport.ports[tag]:field(mask)
    Gets a field for the given port by bit mask.
manager.machine.ioport.ports[tag].fields[name]
    Gets a field for the given port by display name.

Methods
~~~~~~~

field:set_value(value)
    Set the value of the I/O port field.  For digital fields, the value is
    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:clear_value()
    Clear programmatically overridden value and restore the field’s regular
    behaviour.
field:set_input_seq(seqtype, seq)
    Set the :ref:`input sequence <luascript-ref-inputseq>` 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 :ref:`input sequence <luascript-ref-inputseq>` 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 :ref:`input sequence <luascript-ref-inputseq>` 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 :ref:`input sequence <luascript-ref-inputseq>` for the
    specified sequence type.  If the default assignment is not overridden, this
    returns the general input assignment for the field’s input type.  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.

Properties
~~~~~~~~~~

field.device (read-only)
    The device that owns the port that the field belongs to.
field.port (read-only)
    The :ref:`I/O port <luascript-ref-ioport>` that the field belongs to.
field.live (read-only)
    The :ref:`live state <luascript-ref-ioportfieldlive>` of the field.
field.type (read-only)
    The input type of the field.  This is an enumerated value.
field.name (read-only)
    The display name for the field.
field.default_name (read-only)
    The name for the field from the emulated system’s configuration (cannot be
    overridden by scripts or plugins).
field.player (read-only)
    Zero-based player number for the field.
field.mask (read-only)
    Bits in the I/O port corresponding to this field.
field.defvalue (read-only)
    The field’s default value.
field.minvalue (read-only)
    The minimum allowed value for analog fields, or ``nil`` for digital fields.
field.maxvalue (read-only)
    The maximum allowed value for analog fields, or ``nil`` for digital fields.
field.sensitivity (read-only)
    The sensitivity or gain for analog fields, or ``nil`` for digital fields.
field.way (read-only)
    The number of directions allowed by the restrictor plate/gate for a digital
    joystick, or zero (0) for other inputs.
field.type_class (read-only)
    The type class for the input field – one of ``"keyboard"``,
    ``"controller"``, ``"config"``, ``"dipswitch"`` or ``"misc"``.
field.is_analog (read-only)
    A Boolean indicating whether the field is an analog axis or positional
    control.
field.is_digital_joystick (read-only)
    A Boolean indicating whether the field corresponds to a digital joystick
    switch.
field.enabled (read-only)
    A Boolean indicating whether the field is enabled.
field.optional (read-only)
    A Boolean indicating whether the field is optional and not required to use
    the emulated system.
field.cocktail (read-only)
    A Boolean indicating whether the field is only used when the system is
    configured for a cocktail table cabinet.
field.toggle (read-only)
    A Boolean indicating whether the field corresponds to a hardware toggle
    switch or push-on, push-off button.
field.rotated (read-only)
    A Boolean indicating whether the field corresponds to a control that is
    rotated relative its standard orientation.
field.analog_reverse (read-only)
    A Boolean indicating whether the field corresponds to an analog control that
    increases in the opposite direction to the convention (e.g. larger values
    when a pedal is released or a joystick is moved to the left).
field.analog_reset (read-only)
    A Boolean indicating whether the field corresponds to an incremental
    position input (e.g. a dial or trackball axis) that should be reset to zero
    for every video frame.
field.analog_wraps (read-only)
    A Boolean indicating whether the field corresponds to an analog input that
    wraps from one end of its range to the other (e.g. an incremental position
    input like a dial or trackball axis).
field.analog_invert (read-only)
    A Boolean indicating whether the field corresponds to an analog input that
    has its value ones-complemented.
field.impulse (read-only)
    A Boolean indicating whether the field corresponds to a digital input that
    activates for a fixed amount of time.
field.crosshair_scale (read-only)
    The scale factor for translating the field’s range to crosshair position.  A
    value of one (1) translates the field’s full range to the full width or
    height the screen.
field.crosshair_offset (read-only)
    The offset for translating the field’s range to crosshair position.
field.user_value (read/write)
    The value for DIP switch or configuration settings.
field.settings[] (read-only)
    Gets a table of the currently enabled settings for a DIP switch or
    configuration field, indexed by value.


.. _luascript-ref-ioportfieldlive:

Live I/O port field state
-------------------------

Wraps MAME’s ``ioport_field_live`` class, representing the live state of an I/O
port field.

Instantiation
~~~~~~~~~~~~~

manager.machine.ioport.ports[tag]:field(mask).live
    Gets the live state for an I/O port field.

Properties
~~~~~~~~~~

live.name
    Display name for the field.


.. _luascript-ref-inputtype:

Input type
----------

Wraps MAME’s ``input_type_entry`` class, representing an emulated input type or
emulator UI input type.  Input types are uniquely identified by the combination
of their enumerated type value and player index.

Instantiation
~~~~~~~~~~~~~

manager.machine.ioport.types[index]
    Gets a supported input type.

Properties
~~~~~~~~~~

type.type (read-only)
    An enumerated value representing the type of input.
type.group (read-only)
    An integer giving the grouping for the input type.  Should be used to
    provide canonical grouping in an input configuration UI.
type.player (read-only)
    The zero-based player number, or zero for non-player controls.
type.token (read-only)
    The token string for the input type, used in configuration files.
type.name (read-only)
    The display name for the input type.
type.is_analog (read-only)
    A Boolean indicating whether the input type is analog or digital.  Inputs
    that only have on and off states are considered digital, while all other
    inputs are considered analog, even if they can only represent discrete
    values or positions.


.. _luascript-ref-inputman:

Input manager
-------------

Wraps MAME’s ``input_manager`` class, which reads host input devices and checks
whether configured inputs are active.

Instantiation
~~~~~~~~~~~~~

manager.machine.input
    Gets the global input manager instance for the emulated system.

Methods
~~~~~~~

input:code_value(code)
    Gets the current value for the host input corresponding to the specified
    code.  Returns a signed integer value, where zero is the neutral position.
input:code_pressed(code)
    Returns a Boolean indicating whether the host input corresponding to the
    specified code has a non-zero value (i.e. it is not in the neutral
    position).
input:code_pressed_once(code)
    Returns a Boolean indicating whether the host input corresponding to the
    specified code has moved away from the neutral position since the last time
    it was checked using this function.  The input manager can track a limited
    number of inputs this way.
input:code_name(code)
    Get display name for an input code.
input:code_to_token(code)
    Get token string for an input code.  This should be used when saving
    configuration.
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 Boolean indicating whether the supplied
    :ref:`input sequence <luascript-ref-inputseq>` is currently pressed.
input:seq_clean(seq)
    Remove invalid elements from the supplied
    :ref:`input sequence <luascript-ref-inputseq>`.  Returns the new, cleaned
    input sequence.
input:seq_name(seq)
    Get display text for an :ref:`input sequence <luascript-ref-inputseq>`.
input:seq_to_tokens(seq)
    Convert an :ref:`input sequence <luascript-ref-inputseq>` to a token string.
    This should be used when saving configuration.
input:seq_from_tokens(tokens)
    Convert a token string to an
    :ref:`input sequence <luascript-ref-inputseq>`.  This should be used when
    loading configuration.
input:axis_code_poller()
    Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
    obtaining an analog host input code.
input:switch_code_poller()
    Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
    obtaining a host switch input code.
input:keyboard_code_poller()
    Returns an :ref:`input code poller <luascript-ref-inputcodepoll>` for
    obtaining a host switch input code that only considers keyboard input
    devices.
input:axis_sequence_poller()
    Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
    obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
    an analog input assignment.
input:axis_sequence_poller()
    Returns an :ref:`input sequence poller <luascript-ref-inputseqpoll>` for
    obtaining an :ref:`input sequence <luascript-ref-inputseq>` for configuring
    a digital input assignment.

Properties
~~~~~~~~~~

input.device_classes[] (read-only)
    Gets a table of host
    :ref:`input device classes <luascript-ref-inputdevclass>` indexed by name.


.. _luascript-ref-inputcodepoll:

Input code poller
-----------------

Wraps MAME’s ``input_code_poller`` class, used to poll for host inputs being
activated.

Instantiation
~~~~~~~~~~~~~

manager.machine.input:axis_code_poller()
    Returns an input code poller that polls for analog inputs being activated.
manager.machine.input:switch_code_poller()
    Returns an input code poller that polls for host switch inputs being
    activated.
manager.machine.input:keyboard_code_poller()
    Returns an input code poller that polls for host switch inputs being
    activated, only considering keyboard input devices.

Methods
~~~~~~~

poller:reset()
    Resets the polling logic.  Active switch inputs are cleared and initial
    analog input positions are set.
poller:poll()
    Returns an input code corresponding to the first relevant host input that
    has been activated since the last time the method was called.  Returns the
    invalid input code if no relevant input has been activated.


.. _luascript-ref-inputseqpoll:

Input sequence poller
---------------------

Wraps MAME’s ``input_sequence_poller`` poller class, which allows users to
assign host input combinations to emulated inputs and other actions.

Instantiation
~~~~~~~~~~~~~

manager.machine.input:axis_sequence_poller()
    Returns an input sequence poller for assigning host inputs to an analog
    input.
manager.machine.input:switch_sequence_poller()
    Returns an input sequence poller for assigning host inputs to a switch
    input.

Methods
~~~~~~~

poller:start([seq])
    Start polling.  If a sequence is supplied, it is used as a starting
    sequence: for analog inputs, the user can cycle between the full range, and
    the positive and negative portions of an axis; for switch inputs, an “or”
    code is appended and the user can add an alternate host input combination.
poller:poll()
    Polls for user input and updates the sequence if appropriate.  Returns a
    Boolean indicating whether sequence input is complete.  If this method
    returns false, you should continue polling.

Properties
~~~~~~~~~~

poller.sequence (read-only)
    The current :ref:`input sequence <luascript-ref-inputseq>`.  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.


.. _luascript-ref-inputseq:

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 <luascript-ref-inputman>` methods.  Use an
:ref:`input sequence poller <luascript-ref-inputseqpoll>` 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.


.. _luascript-ref-inputdevclass:

Host input device class
-----------------------

Wraps MAME’s ``input_class`` class, representing a category of host input
devices (e.g. keyboards or joysticks).

Instantiation
~~~~~~~~~~~~~

manager.machine.input.device_classes[name]
    Gets an input device class by name.

Properties
~~~~~~~~~~

devclass.name (read-only)
    The device class name.
devclass.enabled (read-only)
    A Boolean indicating whether the device class is enabled.
devclass.multi (read-only)
    A Boolean indicating whether the device class supports multiple devices, or
    inputs from all devices in the class are combined and treated as a single
    device.
devclass.devices[] (read-only)
    Gets a table of :ref:`host input devices <luascript-ref-inputdev>` in the
    class.  Keys are one-based indices.


.. _luascript-ref-inputdev:

Host input device
-----------------

Wraps MAME’s ``input_device`` class, representing a host input device.

Instantiation
~~~~~~~~~~~~~

manager.machine.input.device_classes[name].devices[index]
    Gets a specific host input device.

Properties
~~~~~~~~~~

inputdev.name (read-only)
    Display name for the device.  This is not guaranteed to be unique.
inputdev.id (read-only)
    Unique identifier string for the device.  This may not be human-readable.
inputdev.devindex (read-only)
    Device index within the device class.  This is not necessarily the same as
    the index in the ``devices`` property of the device class – the ``devindex``
    indices may not be contiguous.
inputdev.items (read-only)
    Gets a table of :ref:`input items <luascript-ref-inputdevitem>`, indexed
    by item ID.  The item ID is an enumerated value.


.. _luascript-ref-inputdevitem:

Host input device item
----------------------

Wraps MAME’s ``input_device_item`` class, representing a single host input (e.g.
a key, button, or axis).

Instantiation
~~~~~~~~~~~~~

manager.machine.input.device_classes[name].devices[index].items[id]
    Gets an individual host input item.  The item ID is an enumerated value.

Properties
~~~~~~~~~~

item.name (read-only)
    The display name of the input item.  Note that this is just the name of the
    item itself, and does not include the device name.  The full display name
    for the item can be obtained by calling the ``code_name`` method on the
    :ref:`input manager <luascript-ref-inputman>` with the item’s code.
item.code (read-only)
    The input item’s identification code.  This is used by several
    :ref:`input manager <luascript-ref-inputman>` methods.
item.token (read-only)
    The input item’s token string.  Note that this is a token fragment for the
    item itself, and does not include the device portion.  The full token for
    the item can be obtained by calling the ``code_to_token`` method on the
    :ref:`input manager <luascript-ref-inputman>` with the item’s code.
item.current (read-only)
    The item’s current value.  This is a signed integer where zero is the
    neutral position.


.. _luascript-ref-uiinputman:

UI input manager
----------------

Wraps MAME’s ``ui_input_manager`` class, which is used for high-level input.

Instantiation
~~~~~~~~~~~~~

manager.machine.uiinput
    Gets the global UI input manager instance for the machine.

Methods
~~~~~~~

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:pressed(type)
    Returns a Boolean indicating whether the specified UI input has been
    pressed.  The input type is an enumerated value.
uiinput:pressed_repeat(type, speed)
    Returns a Boolean indicating whether the specified UI input has been
    pressed or auto-repeat has been triggered at the specified speed.  The input
    type is an enumerated value; the speed is an interval in sixtieths of a
    second.

Properties
~~~~~~~~~~

uiinput.presses_enabled (read/write)
    Whether the UI input manager will check for UI inputs frame updates.