diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | doc/dome-key-mappings.7 | 406 | ||||
| -rw-r--r-- | doc/dome-key-mappings.7.txt | 253 |
3 files changed, 663 insertions, 1 deletions
@@ -89,7 +89,7 @@ run: build # Documentation .PHONY: doc -doc: doc/dome-key.1 +doc: doc/dome-key.1 doc/dome-key-mappings.7 .PHONY: clean-doc doc-clean: doc/dome-key.1.intermediate.txt @@ -102,6 +102,9 @@ doc/dome-key.1.intermediate.txt: doc/dome-key.1.txt $(LAUNCHD_PLIST) sed 's/^/ /' $(LAUNCHD_PLIST) | \ perl -0777 -pe '$$plist = <STDIN>; s/\$$\{PLIST}\n/$${plist}/' $< > $@ +doc/dome-key-mappings.7: doc/dome-key-mappings.7.txt + a2x --no-xmllint --format manpage $< + # Distribution diff --git a/doc/dome-key-mappings.7 b/doc/dome-key-mappings.7 new file mode 100644 index 0000000..06c84a3 --- /dev/null +++ b/doc/dome-key-mappings.7 @@ -0,0 +1,406 @@ +'\" t +.\" Title: dome-key-mappings +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> +.\" Date: 11/15/2018 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "DOME\-KEY\-MAPPINGS" "7" "11/15/2018" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dome-key-mappings \- Mapping definition syntax for dome\-key +.SH "SYNOPSIS" +.sp +Describes dome\-key\(cqs mapping syntax +.SH "DESCRIPTION" +.sp +The mappings file lives at \fI~/\&.config/dome\-key/mappings\&.dkmap\fR\&. All mappings should be written there\&. Three types of mappings can be defined: maps, commands, and modes\&. +.sp +Maps are used to simulate keyboard keys\&. Commands run shell commands\&. Modes, when activated, enable you to define multiple actions for the same headphone buttons\&. +.SH "SYNTAX" +.sp +Map and command mappings are composed of three parts, each separated by whitespace (one or more spaces or tabs): +.sp +.if n \{\ +.RS 4 +.\} +.nf +MAP_TYPE TRIGGER ACTION +.fi +.if n \{\ +.RE +.\} +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +MAP_TYPE is the kind of action (\fBmap\fR +or +\fBcmd\fR)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TRIGGER is one or more headphone keys (\fB<Up>\fR, +\fB<Play>\fR, +\fB<Down>\fR)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ACTION defines what to do when the headphone keys from TRIGGER are pressed\&. +.RE +.sp +Mappings must be written on a single line\&. No line continuation operator is available\&. +.sp +Comment lines are prefixed with a \(oq#\(cq and must appear on their own line\&. They are not permitted on the same line as mapping definitions\&. +.SS "Map" +.sp +ACTION corresponds to a sequence of keyboard keys that will be pressed virtually\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +map <Up> Hello<Enter> +.fi +.if n \{\ +.RE +.\} +.sp +will type "Hello" with a newline at the end\&. Simulated keys are pressed in succession as quickly as possible\&. There is no way to wait or sleep between keys\&. +.SS "Command" +.sp +ACTION must be a shell command\&. In: +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmd <Down> say "Good morning" +.fi +.if n \{\ +.RE +.\} +.sp +the \fB/usr/bin/say\fR command will be executed, playing "Good morning" in audible speech\&. +.sp +This map type is useful for running arbitrary code that can\(cqt be expressed by simulating keyboard keys with a \fBmap\fR\&. +.sp +Commands are executed with \fB$SHELL \-c ACTION\fR\&. If \fB$SHELL\fR isn\(cqt set, \fB/bin/sh\fR is used instead\&. +.SS "Mode" +.sp +You can think of modes like Vim modes\&. They enable you to map the same trigger more than once\&. Let\(cqs look at an example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmd <Play> open \-a Firefox +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +mode <Up> { + map <Play> <Space> +} +.fi +.if n \{\ +.RE +.\} +.sp +Here, the \fB<Play>\fR headphone button will open Firefox\&. But when the mode is active, pressing \fB<Play>\fR instead simulates the Space key\&. +.sp +Modes are both activated and deactivated by pressing the TRIGGER sequence written after the \fBmode\fR keyword\&. The trigger functions as a toggle\&. In our example, pressing \fB<Up>\fR activates the mode\&. If the mode is active, pressing \fB<Up>\fR will deactivate the mode, causing top\-level mappings to become available again\&. +.sp +Any number of maps and commands can be defined inside a mode\&. These are enclosed by curly braces\&. Mode mappings should not use the same trigger as the mode\(cqs\&. Mappings with the same trigger are ignored: +.sp +.if n \{\ +.RS 4 +.\} +.nf +mode <Play> { + # The following mapping is ignored: + map <Play> Hello +} +.fi +.if n \{\ +.RE +.\} +.sp +Modes cannot be nested\&. +.SS "Special Keys" +.sp +Special keys are enclosed in \(oq<\(cq \(oq>\(cq brackets (e\&.g\&. \fB<Play>\fR)\&. These are used in \fBmap\fR actions to simulate a key press\&. +.PP +Nop +.RS 4 +Unmaps a trigger\&. Used to remove the default behaviour of a trigger button without remapping it\&. +.RE +.PP +F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12 +.RS 4 +Function keys +.RE +.PP +Up, Down, Left, Right +.RS 4 +Arrow keys +.RE +.sp +Home, End, PageUp, PageDown +.PP +Return, Enter, CR +.RS 4 +Synonyms for the Return key +.RE +.PP +Del +.RS 4 +Forward delete +.RE +.PP +BS +.RS 4 +Backspace +.RE +.PP +Esc +.RS 4 +Escape +.RE +.sp +CapsLock, NumLock +.sp +Tab, Space +.PP +VolumeUp, VolumeDown, Mute +.RS 4 +Volume keys +.RE +.sp +BrightnessUp, BrightnessDown, ContrastUp, ContrastDown +.sp +Help +.sp +Power, Eject +.PP +VidMirror +.RS 4 +Mirror displays +.RE +.PP +Play, Next, Previous, Fast, Rewind +.RS 4 +Media keys +.RE +.PP +IlluminationUp, IlluminationDown, IlluminationToggle +.RS 4 +Keyboard backlight +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBEscaping\fR +.RS 4 +.sp +To simulate a literal \(oq<\(cq character, it must be escaped with a backslash\&. Because backslash is used as an escape prefix, literal backslashes must also be escaped with a backslash\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\(oq<\(cq becomes \(oq\e<\(cq +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\(oq\e\(cq becomes \(oq\e\e\(cq +.RE +.RE +.SS "Modifiers" +.sp +Modifiers can be applied to any key used in \fBmap\fR actions\&. Modifiers can also be chained\&. Modifiers must be prefixed to the key they\(cqre modifying, both of which are surrounded by \(oq<\(cq \(oq>\(cq brackets\&. +.PP +D\- +.RS 4 +Apple/Command key +.RE +.PP +A\- +.RS 4 +Option key +.RE +.PP +C\- +.RS 4 +Control key +.RE +.PP +S\- +.RS 4 +Shift key +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBExamples\fR +.RS 4 +.PP +<C\-c> +.RS 4 +Control\-c +.RE +.PP +<C\-S\-c> +.RS 4 +Control\-Shift\-c +.RE +.PP +<D\-A\-C\-S\-f> +.RS 4 +Apple\-Option\-Control\-Shift\-f +.RE +.PP +<A\-VolumeDown> +.RS 4 +Option\-VolumeDown +.RE +.PP +<D\-A\-Eject> +.RS 4 +Apple\-Option\-Eject +.RE +.RE +.SH "EXAMPLES" +.sp +Video controls: +.sp +.if n \{\ +.RS 4 +.\} +.nf +map <Up> <Left> +map <Play> <Space> +map <Down> <Right> +.fi +.if n \{\ +.RE +.\} +.sp +Don\(cqt launch iTunes when pressing the middle button: +.sp +.if n \{\ +.RS 4 +.\} +.nf +map <Play> <Nop> +.fi +.if n \{\ +.RE +.\} +.sp +Let volume buttons function normally, and activate video controls when pressing \fB<Play>\fR twice: +.sp +.if n \{\ +.RS 4 +.\} +.nf +mode <Play><Play> { + map <Up> <Left> + map <Play> <Space> + map <Down> <Right> +} +.fi +.if n \{\ +.RE +.\} +.sp +Open frequently used applications: +.sp +.if n \{\ +.RS 4 +.\} +.nf +cmd <Up> open \-a Terminal +cmd <Play> open \-a Xcode +cmd <Down> open \-a Firefox +cmd <Up><Play> open \-a Dictionary +.fi +.if n \{\ +.RE +.\} +.sp +Compile code in Vim: +.sp +.if n \{\ +.RS 4 +.\} +.nf +map <Play> <Esc>:make<CR> +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.sp +dome\-key(1)\&. diff --git a/doc/dome-key-mappings.7.txt b/doc/dome-key-mappings.7.txt new file mode 100644 index 0000000..004aa22 --- /dev/null +++ b/doc/dome-key-mappings.7.txt @@ -0,0 +1,253 @@ +dome-key-mappings(7) +==================== + +NAME +---- +dome-key-mappings - Mapping definition syntax for dome-key + +SYNOPSIS +-------- +Describes dome-key’s mapping syntax + +DESCRIPTION +----------- +The mappings file lives at '~/.config/dome-key/mappings.dkmap'. All +mappings should be written there. Three types of mappings can be defined: +maps, commands, and modes. + +Maps are used to simulate keyboard keys. Commands run shell commands. +Modes, when activated, enable you to define multiple actions for the same +headphone buttons. + +SYNTAX +------ +Map and command mappings are composed of three parts, each separated by +whitespace (one or more spaces or tabs): + + MAP_TYPE TRIGGER ACTION + +* MAP_TYPE is the kind of action (*map* or *cmd*). +* TRIGGER is one or more headphone keys (*<Up>*, *<Play>*, *<Down>*). +* ACTION defines what to do when the headphone keys from TRIGGER are + pressed. + +Mappings must be written on a single line. No line continuation operator +is available. + +Comment lines are prefixed with a ‘#’ and must appear on their own line. +They are not permitted on the same line as mapping definitions. + +Map +~~~ +ACTION corresponds to a sequence of keyboard keys that will be pressed +virtually. For example, + + map <Up> Hello<Enter> + +will type "Hello" with a newline at the end. Simulated keys are pressed in +succession as quickly as possible. There is no way to wait or sleep +between keys. + +Command +~~~~~~~ +ACTION must be a shell command. In: + + cmd <Down> say "Good morning" + +the */usr/bin/say* command will be executed, playing "Good morning" in +audible speech. + +This map type is useful for running arbitrary code that can’t be expressed +by simulating keyboard keys with a *map*. + +Commands are executed with *$SHELL -c ACTION*. If *$SHELL* isn’t set, +*/bin/sh* is used instead. + +Mode +~~~~ +You can think of modes like Vim modes. They enable you to map the same +trigger more than once. Let’s look at an example: + + cmd <Play> open -a Firefox + + mode <Up> { + map <Play> <Space> + } + +Here, the *<Play>* headphone button will open Firefox. But when the mode +is active, pressing *<Play>* instead simulates the Space key. + +Modes are both activated and deactivated by pressing the TRIGGER sequence +written after the *mode* keyword. The trigger functions as a toggle. In +our example, pressing *<Up>* activates the mode. If the mode is active, +pressing *<Up>* will deactivate the mode, causing top-level mappings to +become available again. + +Any number of maps and commands can be defined inside a mode. These are +enclosed by curly braces. Mode mappings should not use the same trigger +as the mode’s. Mappings with the same trigger are ignored: + + mode <Play> { + # The following mapping is ignored: + map <Play> Hello + } + +Modes cannot be nested. + +Special Keys +~~~~~~~~~~~~ +Special keys are enclosed in ‘<’ ‘>’ brackets (e.g. *<Play>*). These are +used in *map* actions to simulate a key press. + +Nop:: + Unmaps a trigger. Used to remove the default behaviour of a trigger + button without remapping it. + +F1:: +F2:: +F3:: +F4:: +F5:: +F6:: +F7:: +F8:: +F9:: +F10:: +F11:: +F12:: + Function keys + +Up:: +Down:: +Left:: +Right:: + Arrow keys + +Home, End, PageUp, PageDown + +Return:: +Enter:: +CR:: + Synonyms for the Return key + +Del:: + Forward delete + +BS:: + Backspace + +Esc:: + Escape + +CapsLock, NumLock + +Tab, Space + +VolumeUp:: +VolumeDown:: +Mute:: + Volume keys + +BrightnessUp, BrightnessDown, ContrastUp, ContrastDown + +Help + +Power, Eject + +VidMirror:: + Mirror displays + +Play:: +Next:: +Previous:: +Fast:: +Rewind:: + Media keys + +IlluminationUp:: +IlluminationDown:: +IlluminationToggle:: + Keyboard backlight + +Escaping +^^^^^^^^ +To simulate a literal ‘<’ character, it must be escaped with a backslash. +Because backslash is used as an escape prefix, literal backslashes must +also be escaped with a backslash. + +* ‘<’ becomes ‘\<’ +* ‘\’ becomes ‘\\’ + +Modifiers +~~~~~~~~~ +Modifiers can be applied to any key used in *map* actions. Modifiers can +also be chained. Modifiers must be prefixed to the key they’re modifying, +both of which are surrounded by ‘<’ ‘>’ brackets. + +D-:: + Apple/Command key + +A-:: + Option key + +C-:: + Control key + +S-:: + Shift key + +Examples +^^^^^^^^ + +<C-c>:: + Control-c + +<C-S-c>:: + Control-Shift-c + +<D-A-C-S-f>:: + Apple-Option-Control-Shift-f + +<A-VolumeDown>:: + Option-VolumeDown + +<D-A-Eject>:: + Apple-Option-Eject + +EXAMPLES +-------- + +Video controls: + + map <Up> <Left> + map <Play> <Space> + map <Down> <Right> + +Don’t launch iTunes when pressing the middle button: + + map <Play> <Nop> + +Let volume buttons function normally, and activate video controls when +pressing *<Play>* twice: + + mode <Play><Play> { + map <Up> <Left> + map <Play> <Space> + map <Down> <Right> + } + +Open frequently used applications: + + cmd <Up> open -a Terminal + cmd <Play> open -a Xcode + cmd <Down> open -a Firefox + cmd <Up><Play> open -a Dictionary + +Compile code in Vim: + + map <Play> <Esc>:make<CR> + +SEE ALSO +-------- + +dome-key(1). |