1lavalauncher(1)             General Commands Manual            lavalauncher(1)
2
3
4

NAME

6       LavaLauncher - A simple launcher panel for Wayland desktops
7

DESCRIPTION

9       LavaLauncher is a simple launcher panel for Wayland desktops.
10
11       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
16       Buttons can be activated with pointer and touch events.
17
18       A single LavaLauncher instance can provide multiple such bars, across
19       multiple outputs.
20
21       The Wayland compositor must implement the Layer-Shell and XDG-Output
22       for LavaLauncher to work.
23
24       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

OPTIONS

35       -c <path>, --config <path>
36           Path to the configuration file.
37
38       -h, --help
39           Display a helpful help message and exit.
40
41       -v, --verbose
42           Enable verbose output.
43
44       -V, --version
45           Show version.
46

CONFIGURATION

48       LavaLauncher is configured with a configuration file.
49
50       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
58       You can find an example configuration at the end of this section.
59
60   STRUCTURE
61       The configuration file has a simple structure. It consists of contexts
62       and assignments.
63
64       Assignments are always inside context and have the following form.
65
66           <variable> = <value>;
67
68       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
72       Contexts have the following form.
73
74           <context name>
75           {
76                <context content>
77           }
78
79       Some Contexts must be nested as contents of other contexts.
80
81       Comments start with an octothorpe ('#').
82
83   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
87       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
93   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
98       alignment
99           Alignment of the buttons / bar. Can be "start", "center" or "end".
100           The default is "center".
101
102       background-colour
103           The background colour of the bar. The default is "#000000".
104
105       border-colour
106           The border colour of the bar. The default is "#ffffff".
107
108       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
113       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
118       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
123       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
129       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
134       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
147       hidden-mode
148           Hidden mode of the bar. Can be "never", "always" and "river-auto".
149           Defaults to "never".
150
151           In "never" mode, the bar is never hidden.
152
153           In "always" mode, the bar is always hidden.
154
155           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
159           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
163       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
167       icon-padding
168           Padding around the icons. The default 4.
169
170       indicator-active-colour
171           The colour of the indicator for icons being activated. The default
172           is "#606060".
173
174       indicator-hover-colour
175           The colour of the indicator for icons over which the cursor hovers.
176           The default is "#404040".
177
178       indicator-padding
179           Padding around the icon indicator. The default 0.
180
181       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
187       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
194       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
199       mode
200           The display mode of the bar. Can be "default", "full" or "aggres‐
201           sive".
202
203           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
209           In "full" mode, the bar spans the entire length of the edge it is
210           docked to.
211
212           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
221       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
227       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
233       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
238       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
245       size
246           Size of the bar. The default size is 60.
247
248   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
260   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
265       command
266           Sets the shell command for left-, right-, middle-click and touch
267           interactions.
268
269       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
275           The possible interaction types are the following.
276
277mouse-{left, right, middle}
278mouse-{forward, backward}
279mouse-{mouse, side, extra, task, misc}
280mouse-{1 - 9}
281scroll-{up, down}
282touch
283
284
285           The possible modifiers are the following.
286
287alt
288capslock
289control
290logo (super)
291numlock
292shift
293
294
295           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
302       image-path
303           The path to an image file, which will be used as the icon of the
304           button.
305
306   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
311       length
312           Length of the spacer.
313
314   COMMANDS
315       Commands are executed using sh(1).
316
317       LavaLauncher understands typical backslash escape sequences.
318
319       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
323       $LAVALAUNCHER_OUTPUT_NAME
324           The name of the output the button has been clicked on.
325
326       $LAVALAUNCHER_OUTPUT_SCALE
327           The scale of the output the button has been clicked on.
328
329   COLOURS
330       LavaLauncher can parse hex code colours and read RGB values directly.
331
332       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
336   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
341   IMAGES
342       LavaLauncher support PNG images and, if enabled at compile time, SVG
343       images. It is recommended to use square images.
344
345   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
350           global-settings
351           {
352                watch-config-file = true;
353           }
354
355           bar
356           {
357                output            = eDP-1;
358                position          = bottom;
359                background-colour = "#202020";
360
361                # Condition for the default configuration set.
362                condition-resolution = wider-than-high;
363
364                config
365                {
366                     # Condition for this configuration set.
367                     condition-resolution = higher-than-wide;
368
369                     # Additional configuration sets copy the default configuration set,
370                     # but settings can be overwritten.
371                     position = left;
372                }
373
374                button
375                {
376                     image-path = /path/to/image.png;
377                     command    = useful-script.sh;
378                }
379
380                button
381                {
382                     image-path = /path/to/another/image.png;
383
384                     command[mouse-left]  = another-useful-script.sh;
385                     command[mouse-right] = another-useful-script.sh;
386
387                     command[shift+mouse-left]     = another-useful-script.sh;
388                     command[shift+alt+mouse-left] = another-useful-script.sh;
389
390                     # 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

BUGS

400       Probably.
401
402       Please report all bugs you find with an explanation how to reproduce
403       them.
404

MAILINGLIST

406       You can send bug reports, patches and feedback to the mailinglist.
407
408       <~leon_plickat/lavalauncher@lists.sr.ht>
409

GIT

411       This project is developed using git. You can find the repository by
412       visiting the following URL.
413
414       <https://git.sr.ht/~leon_plickat/lavalauncher>
415

AUTHORS

417       Leon Henrik Plickat <leonhenrik.plickat@stud.uni-goettingen.de>
418
419                                  2021-10-15                   lavalauncher(1)
Impressum