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