1 e573cb09 2020-09-27 op .\" Copyright (c) 2020 Omar Polo <op@omarpolo.com>
3 e573cb09 2020-09-27 op .\" Permission to use, copy, modify, and distribute this software for any
4 e573cb09 2020-09-27 op .\" purpose with or without fee is hereby granted, provided that the above
5 e573cb09 2020-09-27 op .\" copyright notice and this permission notice appear in all copies.
7 e573cb09 2020-09-27 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 e573cb09 2020-09-27 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 e573cb09 2020-09-27 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 e573cb09 2020-09-27 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 e573cb09 2020-09-27 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 e573cb09 2020-09-27 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 e573cb09 2020-09-27 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 e573cb09 2020-09-27 op .Dd $Mdocdate: September 27 2020$
15 e573cb09 2020-09-27 op .Dt STAR-PLATINUM.CONF 5
18 e573cb09 2020-09-27 op .Nm star-platinum.conf
19 e573cb09 2020-09-27 op .Nd star-platinum configuration file
20 e573cb09 2020-09-27 op .Sh DESCRIPTION
22 e573cb09 2020-09-27 op is the configuration file for the
23 e573cb09 2020-09-27 op .Xr star-platinum 1
26 e573cb09 2020-09-27 op Empty lines are ignored, and comments too.
27 08932492 2020-10-01 op Comments starts with a # sign and continue until the end of the line.
28 08932492 2020-10-01 op Comments can be placed everywhere, not only at the start of the line.
30 e573cb09 2020-09-27 op The configuration file is made of blocks.
31 e573cb09 2020-09-27 op Every block starts with one or more
33 e573cb09 2020-09-27 op directives and continues with several keybinding directives.
34 e573cb09 2020-09-27 op If more than a single
36 e573cb09 2020-09-27 op directive is given, the keybinding will be used if at least one of the
38 08932492 2020-10-01 op directives matches the focused window.
40 e573cb09 2020-09-27 op A keybinding directive is made of the
42 e573cb09 2020-09-27 op keyword followed by a keybinding, followed by the
44 e573cb09 2020-09-27 op keyword and an action.
45 e573cb09 2020-09-27 op The action can be another keybinding, or a special internal command.
47 08932492 2020-10-01 op Special attention must be payed to quoting, as there are two different
48 08932492 2020-10-01 op types of quoting with different behaviors:
51 08932492 2020-10-01 op double quotes are used for keybindings.
52 08932492 2020-10-01 op So, for instance, "C-a" is a valid keybinding, but 'C-a' is not.
54 08932492 2020-10-01 op single quotes are used to denote strings.
55 08932492 2020-10-01 op Strings can include any character, except the literal single quote,
56 08932492 2020-10-01 op and are kept verbatim: no special interpretation of character is made.
58 08932492 2020-10-01 op .Sh MATCHING WINDOWS
61 08932492 2020-10-01 op keyword is used to match on windows.
63 08932492 2020-10-01 op can either accept the special keyword
65 08932492 2020-10-01 op or match on a predicate.
68 08932492 2020-10-01 op matches all windows, even the root window.
70 08932492 2020-10-01 op The only predicate supported as of now is the
74 08932492 2020-10-01 op takes a string and matches only windows whose class is equal to the
79 08932492 2020-10-01 op directives are not alone: any sequence of contiguous match are joined,
80 08932492 2020-10-01 op so that the same key bindings can defined for more window.
81 08932492 2020-10-01 op This joining is extensive, and not reductive.
82 08932492 2020-10-01 op .Sh KEY BINDINGS
83 e573cb09 2020-09-27 op The syntax for the keybindings is inspired
85 e573cb09 2020-09-27 op A keybindings is written within double quotes and is made of modifiers
86 e573cb09 2020-09-27 op followed by the key.
87 e573cb09 2020-09-27 op Modifiers follows the
89 e573cb09 2020-09-27 op notation of using C- to mean control, S- for shift, M- for alt (mod1)
90 e573cb09 2020-09-27 op and s- for super (mod4).
91 e573cb09 2020-09-27 op The key can be either a plain letter (e.g. x) or the name of the key
92 e573cb09 2020-09-27 op written within angular brackets (e.g. <Down>).
94 08932492 2020-10-01 op .Pa /usr/X11R6/include/X11/keysymdef.h
96 08932492 2020-10-01 op .Xr XStringToKeysym 3
97 08932492 2020-10-01 op for more information on the names allowed inside the angular brackets.
99 08932492 2020-10-01 op The only exceptions are a couple of keys that are available under a
100 08932492 2020-10-01 op special syntax:
101 08932492 2020-10-01 op .Bl -tag -indent keyword
103 08932492 2020-10-01 op is a short-hand for
106 08932492 2020-10-01 op is a short-hand for
109 08932492 2020-10-01 op is a short-hand for
110 08932492 2020-10-01 op .Ic <parenleft>
112 08932492 2020-10-01 op is a short-hand for
113 08932492 2020-10-01 op .Ic <parenright>
116 08932492 2020-10-01 op When a key bindings is matched against a specific window, the
117 08932492 2020-10-01 op appropriate action is executed.
118 08932492 2020-10-01 op There are different types of possible actions:
119 08932492 2020-10-01 op .Bl -tag -width 10m
121 08932492 2020-10-01 op send the specified key to the focused window
122 08932492 2020-10-01 op .It Ic exec Ql cmd
125 08932492 2020-10-01 op using the user shell'
128 08932492 2020-10-01 op .It Ic ignore
130 08932492 2020-10-01 op It does nothing, but prevents the focused window from seeing that key.
132 08932492 2020-10-01 op .Sh ENVIRONMENT
133 08932492 2020-10-01 op .Bl -tag -width keyword
134 08932492 2020-10-01 op .\" XXX: keep in sync with star-platinum.1
136 08932492 2020-10-01 op The user preferred shell.
137 08932492 2020-10-01 op If not provided
140 08932492 2020-10-01 op This executable must accept a
142 08932492 2020-10-01 op flag to execute a string.
145 e573cb09 2020-09-27 op The following is an example of configuration file that binds some
146 e573cb09 2020-09-27 op .Xr emacs 1 Ns -esque keys for both Firefox and Chromium:
147 e573cb09 2020-09-27 op .Bd -literal -offset indent
148 08932492 2020-10-01 op # a global binding
150 08932492 2020-10-01 op on "C-<F5>" do exec 'notify-send "hello world"'
152 08932492 2020-10-01 op match class 'Firefox' # matching firefox OR
153 08932492 2020-10-01 op match class 'Chromium-browser' # matching chromium
154 e573cb09 2020-09-27 op on "C-s" do "C-f"
157 e573cb09 2020-09-27 op on "C-w" do "C-x"
158 e573cb09 2020-09-27 op on "M-w" do "C-c"
159 e573cb09 2020-09-27 op on "C-y" do "C-v"
162 e573cb09 2020-09-27 op on "C-n" do "<Down>"
163 e573cb09 2020-09-27 op on "C-p" do "<Up>"
164 e573cb09 2020-09-27 op on "C-f" do "<Right>"
165 e573cb09 2020-09-27 op on "C-b" do "<Left>"
167 e573cb09 2020-09-27 op on "C-(" do ignore