1lavalauncher(1) General Commands Manual lavalauncher(1)
2
6 LavaLauncher - A simple launcher panel for Wayland desktops
7
9 LavaLauncher is a simple launcher panel for Wayland desktops.
10 It displays a dynamically sized bar with user defined buttons. These
12 Buttons consist of an image, which is displayed as the button icon on
13 the bar, and at least one shell command, which is executed when the
14 user activates the button.
15 Buttons can be activated with pointer and touch events.
17 A single LavaLauncher instance can provide multiple such bars, across
19 multiple outputs.
20 The Wayland compositor must implement the Layer-Shell and XDG-Output
22 for LavaLauncher to work.
23 Beware: Unlike applications launchers which are similar in visual de‐
25 sign to LavaLauncher, which are often called "docks", LavaLauncher does
26 not care about desktop files or icon themes nor does it keep track run‐
27 ning applications. Instead, LavaLaunchers approach of manually defined
28 buttons is considerably more flexible: You could have buttons not just
29 for launching applications, but for practically anything you could do
30 in your shell, like for ejecting your optical drive, rotating your
31 screen, sending your cat an email, playing a funny sound, muting all
32 audio, toggling your lamps and a lot more. Be creative!
33
35 -c <path>, --config <path>
36 Path to the configuration file.
37 -h, --help
39 Display a helpful help message and exit.
40 -v, --verbose
42 Enable verbose output.
43 -V, --version
45 Show version.
46
48 LavaLauncher is configured with a configuration file.
49 Unless the path to a configuration file has been specified,
51 LavaLauncher tries to find a configuration file at, in descending pri‐
52 ority, "./lavalauncher.conf", "$XDG_CON‐
53 FIG_HOME/lavalauncher/lavalauncher.conf", "$HOME/.con‐
54 fig/lavalauncher/lavalauncher.conf" "/usr/lo‐
55 cal/etc/lavalauncher/lavalauncher.conf" and
56 "/etc/lavalauncher/lavalauncher.conf"
57 You can find an example configuration at the end of this section.
59 STRUCTURE
61 The configuration file has a simple structure. It consists of contexts
62 and assignments.
63 Assignments are always inside context and have the following form.
65 <variable> = <value>;
67 Note that the value may be quoted, causing LavaLauncher to use it as
69 is, including all whitespace that would otherwise be stripped from the
70 final string.
71 Contexts have the following form.
73 <context name>
75 {
76 <context content>
77 }
78 Some Contexts must be nested as contents of other contexts.
80 Comments start with an octothorpe ('#').
82 GLOBAL SETTINGS
84 Global settings can be configured in the "global-settings" context. The
85 assignments which can be made in this context are as follows.
86 watch-config-file
88 Automatically reload when a change in the configuration file is de‐
89 tected. Can be "true" or "false". The default is "false". Behold:
90 If the configuration file contains an error upon reload,
91 LavaLauncher will exit.
92 BAR
94 Every "bar" context will add a bar. The configuration changes in this
95 context make up the default configuration set of the bar. The assign‐
96 ments possible in this context are as follows.
97 alignment
99 Alignment of the buttons / bar. Can be "start", "center" or "end".
100 The default is "center".
101 background-colour
103 The background colour of the bar. The default is "#000000".
104 border-colour
106 The border colour of the bar. The default is "#ffffff".
107 border
109 The border size. Expects either one integer, to set the size of all
110 borders, or four integers, to set the individual sizes for the top,
111 left, right and bottom border. The default border size is 1.
112 condition-resolution
114 The resolution proportions an output must have for the bar to be
115 displayed on it. Can be either "all", "wider-than-high" or "higher-
116 than-wide". The default is "all".
117 condition-scale
119 The scale an output must have for the bar to be displayed on it.
120 Can be either an integer greater than zero or "all". The default is
121 "all".
122 condition-transform
124 The rotation an output must have for the bar to be displayed on it.
125 Can be "all", 0, 1, 2 or 3. The numerical values represent rota‐
126 tions of 0, 90, 180 and 270 degrees, with the exact correspondence
127 depending on the compositor. The default is "all".
128 cursor-name
130 Name of the cursor displayed when hovering the pointer over the
131 bar. The default cursor is "pointer". Behold: What cursors are
132 available depends on your cursor theme.
133 exclusive-zone
135 Exclusive zone of the surface. Can be "true", "false" or "station‐
136 ary". If "true", the compositor is informed that it should not ob‐
137 struct the surface of LavaLauncher with other surfaces. If "false",
138 the compositor is informed that it can place other surfaces over or
139 under the surface of LavaLauncher. If "stationary", the compositor
140 is informed that the surface of LavaLauncher should not be moved to
141 accommodate other Layer-Shell surfaces and that it can freely place
142 other surfaces over or under the surface of LavaLauncher. The de‐
143 fault is "true". The exact implementation is compositor dependant;
144 A compositor may choose to ignore the requested exclusive zone of
145 surfaces.
146 hidden-mode
148 Hidden mode of the bar. Can be "never", "always" and "river-auto".
149 Defaults to "never".
150 In "never" mode, the bar is never hidden.
152 In "always" mode, the bar is always hidden.
154 The "river-auto" mode works only in the river Wayland compositor.
156 In this mode, the bar is only hidden if the output is currently oc‐
157 cupied.
158 Behold: If you want a hidden bar which sits above windows on hover,
160 you need to set the layer to "top" and the exclusive zone to "off"
161 or "stationary".
162 hidden-size
164 Size of the invisible area where hovering with a pointer will un‐
165 hide the bar if it is hidden. Defaults to 10.
166 icon-padding
168 Padding around the icons. The default 4.
169 indicator-active-colour
171 The colour of the indicator for icons being activated. The default
172 is "#606060".
173 indicator-hover-colour
175 The colour of the indicator for icons over which the cursor hovers.
176 The default is "#404040".
177 indicator-padding
179 Padding around the icon indicator. The default 0.
180 indicator-style
182 Style of the icon indicator. Can be "rectangle", "rounded-rectan‐
183 gle" and "circle". The default is "rounded-rectangle". The corner
184 radii for "rounded-rectangle" are the same as the ones of the bar
185 itself.
186 layer
188 Layer of the bar surface. Can be "overlay", "top", "bottom" or
189 "background". Typically, "bottom" and "background" will be under‐
190 neath regular windows, while "top" and "overlay" will be above
191 them, however the exact placement on the z axis depends on the im‐
192 plementation of the compositor. The default layer is "bottom".
193 margin
195 The margin of the surface. Expects either one integer, to set the
196 margin in all directions, or four integers, to set the individual
197 top-, left-, right- and bottom-margins. The default margin is 0.
198 mode
200 The display mode of the bar. Can be "default", "full" or "aggres‐
201 sive".
202 In "default" mode, the bar is sized just large enough to house all
204 the buttons. In this mode, compositors may not respect margins par‐
205 allel to the bar or the exclusive zone, possibly even depending on
206 the alignment. This is not a bug in LavaLauncher but a limitation
207 of your compositor.
208 In "full" mode, the bar spans the entire length of the edge it is
210 docked to.
211 The "aggressive" mode is visually identical to "normal" mode, how‐
213 ever the surface of the bar is sized and anchored more aggres‐
214 sively. This mode is intended for compositors with faulty Layer-
215 Shell implementations. If LavaLauncher is not placed at the desired
216 location or the exclusive zone or margins parallel to the bar are
217 ignored, this mode may help. Beware however that it allows the com‐
218 positor a lot less leeway when geometrically fitting the bar onto
219 the screen.
220 namespace
222 The namespace of the Layer-Shell surface of the bar. Some composi‐
223 tors may treat Layer-Shell surfaces differently based on their
224 namespace. The default is "lhp.LavaLauncher". Note that this option
225 only takes effect once on bar creation.
226 output
228 Name of the output on which the bar should be displayed. Output
229 names are compositor dependant. If set to "all" or "*",
230 LavaLauncher will display the bar on all outputs, which is the de‐
231 fault behaviour.
232 position
234 Position of the bar. Can be "top", "right", "bottom", "left". The
235 bar will dock to that edge of the output(s). The default position
236 is "bottom".
237 radius
239 The radius of the corners. Expects either one integer, to set the
240 radius of all corners, or four integers, to set the individual
241 radii for the top-left, top-right, bottom-left and bottom-right
242 corner. The default radius is 5. Set to 0 to disable corner round‐
243 ness.
244 size
246 Size of the bar. The default size is 60.
247 CONFIG
249 Every "config" context will add an additional configuration set to a
250 bar. As such, this context is a nested inside the "bar" context. It
251 copies the values of the default configuration set, but every setting
252 can be overridden. This is useful to change bar configuration based on
253 conditionals, as LavaLauncher will automatically choose the first con‐
254 figuration set with fitting conditions. Different instances of the same
255 bar on different outputs can use different configuration sets, but a
256 bar has at most one instance per output and uses exactly one configura‐
257 tion set per instance. The assignments possible in this context are the
258 same as for the "bar" context.
259 BUTTON
261 Every "button" context will add a button to a bar. As such, this con‐
262 text is a nested inside the "bar" context. The assignments possible in
263 this context are as follows.
264 command
266 Sets the shell command for left-, right-, middle-click and touch
267 interactions.
268 command[<bind>]
270 Bind a shell command to a specific interaction plus modifier combi‐
271 nation. This combination is defined by <bind>, which is a string
272 containing an interaction name as well as optionally one or multi‐
273 ple modifier names, separated by "+".
274 The possible interaction types are the following.
276 • mouse-{left, right, middle}
278 • mouse-{forward, backward}
279 • mouse-{mouse, side, extra, task, misc}
280 • mouse-{1 - 9}
281 • scroll-{up, down}
282 • touch
283 The possible modifiers are the following.
286 • alt
288 • capslock
289 • control
290 • logo (super)
291 • numlock
292 • shift
293 Behold: Due to the way the Layer-Shells keyboard interactivity was
296 designed, LavaLauncher may only get send an updated modifier state
297 when it gains keyboard focus. In some compositors this requires you
298 to click on it, meaning that touch and scroll interactions with
299 modifiers may not work in some compositors. This is a bug in the
300 Layer-Shell protocol, not in LavaLauncher.
301 image-path
303 The path to an image file, which will be used as the icon of the
304 button.
305 SPACER
307 Every "spacer" context will add a spacer to a bar. As such, this con‐
308 text is a nested inside the "bar" context. The assignments possible in
309 this context are as follows.
310 length
312 Length of the spacer.
313 COMMANDS
315 Commands are executed using sh(1).
316 LavaLauncher understands typical backslash escape sequences.
318 LavaLauncher sets some environmental variables for the processes it
320 launches. Since all commands are executed via a shell, they can be used
321 as arguments for the commands. These variables are as follows.
322 $LAVALAUNCHER_OUTPUT_NAME
324 The name of the output the button has been clicked on.
325 $LAVALAUNCHER_OUTPUT_SCALE
327 The scale of the output the button has been clicked on.
328 COLOURS
330 LavaLauncher can parse hex code colours and read RGB values directly.
331 The supported formats are "#RRGGBB", "#RRGGBBAA", "0xRRGGBB" and "0xR‐
333 RGGBBAA" for hex code colours and "rgb(rrr,ggg,bbb)" and
334 "rgba(rrr,ggg,bbb,aaa)" for RGB colours.
335 CONDITIONS
337 Conditions are (re-)evaluated and bars created and destroyed and their
338 active configuration set chosen accordingly whenever an outputs parame‐
339 ters are updated.
340 IMAGES
342 LavaLauncher support PNG images and, if enabled at compile time, SVG
343 images. It is recommended to use square images.
344 EXAMPLE CONFIGURATION
346 This is a simple configuration example, demonstrating a bar with two
347 buttons and an additional configuration set. The second button uses ad‐
348 vanced command binds.
349 global-settings
351 {
352 watch-config-file = true;
353 }
354 bar
356 {
357 output = eDP-1;
358 position = bottom;
359 background-colour = "#202020";
360 # Condition for the default configuration set.
362 condition-resolution = wider-than-high;
363 config
365 {
366 # Condition for this configuration set.
367 condition-resolution = higher-than-wide;
368 # Additional configuration sets copy the default configuration set,
370 # but settings can be overwritten.
371 position = left;
372 }
373 button
375 {
376 image-path = /path/to/image.png;
377 command = useful-script.sh;
378 }
379 button
381 {
382 image-path = /path/to/another/image.png;
383 command[mouse-left] = another-useful-script.sh;
385 command[mouse-right] = another-useful-script.sh;
386 command[shift+mouse-left] = another-useful-script.sh;
388 command[shift+alt+mouse-left] = another-useful-script.sh;
389 # Binding commands to scroll events is nice to configure
391 # things like audio volume or screen brightness
392 command[scroll-up] = volume up;
393 command[scroll-down] = volume down;
394 command[shift+scroll-up] = volume microphone-up;
395 command[shift+scroll-down] = volume microphone-down;
396 }
397 }
398
400 Probably.
401 Please report all bugs you find with an explanation how to reproduce
403 them.
404
406 You can send bug reports, patches and feedback to the mailinglist.
407 <~leon_plickat/lavalauncher@lists.sr.ht>
409
411 This project is developed using git. You can find the repository by
412 visiting the following URL.
413 <https://git.sr.ht/~leon_plickat/lavalauncher>
415
417 Leon Henrik Plickat <leonhenrik.plickat@stud.uni-goettingen.de>
418 2023-07-20 lavalauncher(1)