.TH Aq_binding 5 "" "Aq_binding @PROJECT_VERSION@" .SH NAME Aq_binding \- Key Binding Configuration for \fBAq\fP(1) .SH DESCRIPTION The "\fBkeys\fP" configuration is a JSON object whose keys are strings representing input events, and whose values are strings representing what to do when that set of input events occurs. A value of `null` or an empty string does nothing; it can be used to disable a default key binding. .SS Key Strings The key string starts with modifiers, separated from the rest with a plus sign (\fB+\fP) or minus sign (\fB-\fP). The modifier names are case-insensitive. Currently supported raw modifiers are: .RS .B LSHIFT RSHIFT LCTRL RCTRL LALT RALT LGUI RGUI .RE It is currently not possible to require both L and R be pressed at once. Instead, setting both L and R means that *either* L or R may be pressed. Aliases exist to set both: .RS .B SHIFT CTRL ALT GUI .RE To ignore a modifier, prefix it with an exclamation point (\fB!\fP). Otherwise, the modifier set must match the given modifiers exactly. For example, the following matches Ctrl-C, whether or not alt or shift is pressed, but not if GUI is pressed: .RS .B Ctrl-!Shift-!Alt-C .RE These names may not correspond to your actual modifier keys. Since SDL provides renames for them, the following aliases exist: .RS GUI: .B LWIN RWIN WIN LCMD RCMD CMD .br ALT: .B LOPT ROPT OPT .RE The following SDL modifiers are always ignored, as they are traditionally switches rather than temporary key-presses: .RS .B NUM CAPS MODE SCROLL .RE However, the low-level key codes returned by the OS are generally affected by NUM and MODE, and special considerations are made internally by Aq for ASCII alphabetic characters if CAPS is set. Following the optional modifiers is a set of non-modifier keys or game controller events. These are separated by commas; all must be active simultaneously in order for the action to take place. Binding an action to multiple events does not disable the binding of each individual event, if such a binding exists. Key names are parsed by `\fBSDL_GetScancodeFromName\fP`. As you might expect, they can include the separators (\fB+\fP, \fB-\fP, or \fB,\fP) and modifiers (although the modifier keys also affect modifiers, so you might have to give it twice; e.g. \fB!lshift-Left Shift\fP). Hopefully most names are intuitive enough to figure out, but if there is a parse error, the key is ignored (and a message printed to standard error), and you will have to dive further into the SDL documentation to figure out why. Controller events are prefixed by `GP`, followed by a controller number, followed by an underscore. See the \fBControllers\fP section below for information on what those numbers map to. \fBGP\fP is matched without regard to case. Controller button presses are given by just the SDL button name (case- insensitive, but usually lower-case). The following buttons are known to be supported (it depends on the version of SDL you are using): .RS .B a b x y back guide start leftstick rightstick leftshoulder rightshoulder .br .B dpup dpdown dpleft dpright .br .B misc1 paddle1 paddle2 paddle3 paddle4 touchpad .RE Axes are given by an optional direction (\fB+\fP or \fB-\fP), followed by the case-insensitive (but usually lower-case) SDL axis name (again, the supported names depend on which version of SDL you are using): .RS .B leftx lefty rightx righty lefttrigger righttrigger .RE For example, the following are all equivalent: .RS .B gp1_righty .br .B GP1_RightY .br .B Gp1_+RIGHTY .RE How these button and axis names map to your controller(s) is managed by SDL. See e.g. .UR https://github.com/gabomdq/SDL_GameControllerDB .B The Community Controller Database .UE . .SS Actions The action string is either blank/null (ignore), a sequence of Aquarius keys and/or game controller events, or a hotkey name. The sequence of keys and/or events is separated by comma (\fB,\fP), minus (\fB-\fP), or plus (\fB+\fP); all of the specified keys and controller events will occur as if pressed simultaneously. Aquarius keys should always ignore shift and ctrl modifiers, since they are mapped to the Aquarius SHIFT and CTL keys, respectively. In addition, shifted symbols are automatically mapped to a key plus SHIFT, and control keys are automatically mapped to a key plus CTL. The following ASCII key names are supported (case-insensitive, but usually upper-case): .RS .B 1234567890-= !"#$%^'()?_+ .br .B QWERTYUIOP/ ^\e .br .B ASDFGHJKL:; @* .br .B ZXCVBNM,. <> .RE And the following non-ASCII key names: .RS .B CTL SHIFT SPACE RTN <- .RE Note that an upper-case letter does not imply shift; this must be explicitly given as e.g. \fBSHIFT-A\fP. Also, the \fBRST\fP key is not mappable, since it isn't really a key; instead, use the \fBRESET\fP (or \fBAq/RESET\fP) action. Aquarius game controller events are prefixed by \fBJ\fP, followed by the controller number (\fB1\fP/\fBA\fP/\fBL\fP or \fB2\fP/\fBB\fP/\fBR\fP), followed by an underscore (\fB_\fP), followed by either a button name (\fB1\fP .. \fB6\fP) or a direction (\fBN\fP, \fBS\fP, \fBE\fP, \fBW\fP, \fBNE\fP, \fBNW\fP, \fBSE\fP, \fBSW\fP, \fBNNE\fP, \fBENE\fP, \fBNNW\fP, \fBWNW\fP, \fBSSE\fP, \fBESE\fP, \fBSSW\fP, \fBWSW\fP), where \fBN\fP means up and \fBE\fP means right. If a direction is mapped to an axis, the inverse of the axis is automatically mapped to the opposite direction. If more than one direction is applied simultaneously, they are averaged. If analog, they are weighted by the analog intensity. Thus, the default mapping of \fBGP1_+leftx\fP to \fBJ1_E\fP and \fBGP1_lefty\fP to \fBJ1_S\fP will push the first dial in the direction of the left analog stick, selecting all 16 directions in a natural way. Actions consist of the menu item name, optionally prefixed by the menu name, separated by a slash. Only alphanumeric characters and slashes are matched, without regard to case. There are also a few non-menu actions which can be bound. Toggle-able actions may optionally be prefixed with a \fB+\fP or \fB-\fP to always turn the option on or off, respectively, instead of toggling. If both \fB+\fP and \fB-\fP are specified, the flag will respect the first character on press, and the second on release (e.g. \fB"+-Turbo Toggle"\fP will enable turbo when pressed, and disable when released). The following actions are currently supported (\fB+-\fP indicates toggle): .B General: .RS 3 .TP .B Aq/RESET Reset emulator. .PP .TP +-\fBUse Extended BASIC\fP Toggle use of Extended BASIC on next RESET. .PP .TP +-\fBTurbo Toggle\fP Toggle keyboard turbo mode. .PP .TP +-\fBToggle Fullscreen\fP Toggle desktop full-screen mode. .PP .TP .B Volume Up Decrease internal volume attenuation. .PP .TP .B Volume Down Increase internal volume attenuation. .PP .TP +-\fBMute Toggle\fP Toggle maximum internal volume attenuation (restores current Up/Down setting on unmute). .PP .TP +-\fBKeyboard Mode Toggle\fP Toggle auto-inserted keyboard event mode between scan (+) and timer (-). This only affects auto-typing ("Load BASIC" or -b). It is saved in the preference file, so it is technically a non-GUI flag. .PP .TP +-\fBSwap Joysticks\fP Swap bindings for left and right sticks. .PP .RE .B GUI only: .RS 3 .TP .B Aq/About Pop up About dialog. .PP .TP .B Aq/Load BASIC... Request file and type contents in trubo mode. .PP .TP .B Aq/Change ROMs... Change one or more ROM files. Automatically resets upon change. .PP .TP .B Tape/Set Tape File... Request file to use for subsequent tape operations. .PP .TP +-\fBTape/Auto Ask on Save\fP Toggle automatic file request popup whenever a new save is detected. .PP .TP +-\fBTape/Auto Ask at End\fP Toggle automatic file request whenever a load occurs at the end of a tape. .PP .TP +-\fBTape/Auto Ask at Load\fP Toggle automatic file request whenever a new load is detected. .PP .TP +-\fBGUI/Show Menu\fP Toggle menu bar. .PP .TP .B Aq/Bind Keys Pop up key bonding dialog. .PP .TP .B Set Cartridge... Request file name for expansion cartridge; loaded at next RESET. .PP .TP .B Set BASIC ROM... Request file name for main emulator ROM; loaded at next RESET. .PP .TP .B Set Character ROM... Request file name for character ROM; loaded at next RESET. .PP .TP .B Set Extended BASIC ROM... Request file name for special Extended BASIC ROM to be loaded (if enabled) at next RESET. .PP .SS Controllers Rather than requiring controller specification on every such event, controllers are assigned to numbers. Controllers are only detected at program startup (i.e., hot plugging is not supported). Any detected controllers not explicitly assigned to a number are assigned to numbers not currently assigned to any explicit controller, in order. In general, when multiple controllers apply, they are sorted first by player index, and then by detection order. A controller may only be assigned to one number. A number may map to multiple controllers, though. In the latter case, buttons will be merged, and axes will come from the first assigned controller which is not considered inactive (centered sticks or unpressed triggers). It is also possible for an index to be empty, although as stated above, it will be auto-filled if there are enough controllers in the system, even if a specific (but non-matching) pattern was assigned. To explicitly assign a controller to a number, use the \fB"controllers"\fP configuration key. The value is an array of arrays. Each top-level array index corresponds to the controler number, starting at 1. If an element is an empty array, no explicit controllers are assigned. Otherwise, the element must be an array of string patterns: .IP \(bu 2 Blank: all controllers. For example: .RS \fB"" // All detected controllers\fP .RE .PP .IP \(bu 2 A string which must exactly match the controller's identifier name, without regard to case. For example: .RS \fB"Microsoft X-Box 360 pad" // An X-Box gamepad\fP .RE .PP .IP \(bu 2 A string which must exactly match the controller's SDL GUID, without regard to case. For example: .RS \fB"030000004c050000cc0900000081000" // A DualShock 4 gamepad\fP .RE .IP \(bu 2 A POSIX extended regular expression to match either of the above two. This is matched without regard to case, and must match the entire name or GUID. The first and last characters must be \fB^\fP and \fB$\fP, respectively. .RS \fB"^$" // An actual blank name\fP .br \fB"^.*PS.*$" // Any game pads with PS in the name\fP .RE .IP "" 2 The first and last character are a hint that the pattern must match the entire name or GUID, but are not actually included in the pattern. This means that, for example, no parentheses are required to apply these acnhors to all branches of the \fB|\fP operator: .RS \fB"^pat1|pat2$" // Matches pat1 or pat2, anchored to full string\fP .br \fB"^(pat1|pat2)$" // Same, but now a valid regex\fP .br \fB"^pat1$|^pat2$" // Same, but now a valid regex\fP .RE .PP .IP \(bu 2 Any of the above, suffixed with \fB#\fP\fIn\fP, where \fIn\fP indicates the \fIn\fPth match. By default, all matches are included. Using star (\fB*\fP) as the index requests the first as-yet-unassigned match. For example: .RS \fB"#2" // The 2nd detected controller\fP .br \fB"Microsoft X-Box 360 pad#1" // The 2nd XBOX gamepad\fP .br \fB"030000004c050000cc0900000081000#1" // The 1st DualShock 4\fP .br \fB"^$#1" // The 1st actual blank name\fP .br \fB"^.*PS.*$#3" // The 3rd pad with PS in the name\fP .br \fB"#*" // The next unassigned controller\fP .RE .IP \(bu 2 A single vertical bar (\fB|\fP). This is ignored, except to indicate that if subsequent strings match multiple controllers, only the first match is taken. This includes strings which match multiple controllers themselves, so the following two are equivalent: .RS \fB[ "^.*X.*Box.*$#1" ]\fP .br \fB[ "|", "^.*X.*Box.*$" ]\fP .RE .IP "" 2 For example, the following selects a specific controller, but falls back to any if not found: .RS \fB[ "|", "^.*Aquarius.*$", "#*" ]\fP .RE .PP Explicit matches are assigned in index order. If a controller matches multiple indices, it is only assigned to the first index which matches. Thus, the following will not work as planned: .RS \fB[ ["^.*X.*Box.*$"] ["^.*X.*Box.*$"] ]\fP .RE Instead of assigning the first X-Box controller to 1, and the second to 2, all X-Box controllers will be assigned to 1. The following two work as intended: .RS \fB[ ["^.*X.*Box.*$#1"] ["^.*X.*Box.*$#2"] ]\fP .br \fB[ ["^.*X.*Box.*$#*"] ["^.*X.*Box.*$#*"] ]\fP .RE Enable the I/O log to see a list of detected controllers, what index they map to and what patterns they matched, as well as a list of unmatched patterns. .SH "SEE ALSO" \fBAq\fP(1) .PP