DOCS/man/input.rst: clarify shift modifier behavior

When shift modifier is used with text key names, it is usually
silently ignored, except for ASCII key names, which can be
confusing. Document it clearly.
This commit is contained in:
nanahi authored and Dudemanguy committed 2024-12-20 14:54:35 +00:00
1 parent f8a5df56cc
commit 4711e40814
1 file changed
+18 -5
+18 -5
View File
@@ -97,11 +97,24 @@ All key names can be combined with the modifiers ``Shift``, ``Ctrl``, ``Alt``,
``Meta``. They must be prefixed to the actual key name, where each modifier
is followed by a ``+`` (for example ``ctrl+q``).
The ``Shift`` modifier requires some attention. For instance ``Shift+2`` should
usually be specified as key-name ``@`` at ``input.conf``, and similarly the
combination ``Alt+Shift+2`` is usually ``Alt+@``, etc. Special key names like
``Shift+LEFT`` work as expected. If in doubt - use ``--input-test`` to check
how a key/combination is seen by mpv.
.. note::
The ``Shift`` modifier requires some attention. In general, when the
``Shift`` modifier is combined with a key which produces text, the actual
produced text key name when shift is pressed should be used.
For instance, on the US keyboard layout, ``Shift+2`` should usually be
specified as key-name ``@`` at ``input.conf``, and similarly the
combination ``Alt+Shift+2`` is usually ``Alt+@``, etc.
In general, the ``Shift`` modifier, when specified with text key names,
is ignored: for instance, mpv interprets ``Shift+2`` as ``2``.
The only exceptions are ASCII letters, which are normalized by mpv.
For example, ``Shift+a`` is interpreted as ``A``.
Special key names like ``Shift+LEFT`` work as expected.
If in doubt - use ``--input-test`` to check how a key/combination is seen
by mpv.
Symbolic key names and modifier names are case-insensitive. Unicode key names
are case-sensitive because input bindings typically respect the shift key.