1lavalauncher(1) Version 2.0.0 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>
36 Path to the configuration file.
37 -h
39 Display a helpful help message and exit.
40 -v
42 Enable verbose output.
43
45 LavaLauncher is configured with a configuration file.
46 Unless the path to a configuration file has been specified,
48 LavaLauncher tries to find a configuration file at, in decending prior‐
49 ity, "./lavalauncher.conf", "$XDG_CON‐
50 FIG_HOME/lavalauncher/lavalauncher.conf", "$HOME/.con‐
51 fig/lavalauncher/lavalauncher.conf" "/usr/lo‐
52 cal/etc/lavalauncher/lavalauncher.conf" and
53 "/etc/lavalauncher/lavalauncher.conf"
54 You can find an example configuration at the end of this section.
56 STRUCTURE
58 The configuration file has a simple structure. It consists of contexts
59 and assignments.
60 Assignments are always inside contexts and consist of three parts: The
62 variable to be changed, followed by the new value for the variable, and
63 finally a semicolon (';'). The value string must be separated from the
64 variable name by whitespace and may be quoted, causing LavaLauncher to
65 use it as is, including all whitespace that would otherwise be stripped
66 from the final string.
67 A context consist of at least three parts: The context name, followed
69 by an opening bracket, optionally contents, and finally a closing
70 bracket. All these must be separated by whitespace. Some Contexts must
71 be nested as contents of other contexts.
72 Comments start with an octothorpe ('#').
74 GLOBAL SETTINGS
76 Global settings can be configured int the "global-settings" context.
77 The assignments which can be made in this context are as follows.
78 watch-config-file
80 Automatically reload when a change in the configuration file is de‐
81 tected. Can be "true" or "false". The default is "false". Behold:
82 If the configuration file contains an error upon reload,
83 LavaLauncher will exit.
84 BAR
86 Every "bar" context will add a bar. The assignments possible in this
87 context are as follows.
88 alignment
90 Alignment of the buttons / bar. Can be "start", "center" or "end".
91 The default is "center".
92 background-colour
94 The background colour of the bar. The default is "#000000".
95 border
97 The border size. Expects either one integer, to set the size of all
98 borders, or four integers, to set the individual sizes for the top,
99 left, right and bottom border. The default border size is 1.
100 condition-resolution
102 The resolution proportions an output must have for the bar to be
103 displayed on it. Can be either "all", "wider-than-high" or "higher-
104 than-wide". The default is "all".
105 condition-scale
107 The scale an output must have for the bar to be displayed on it.
108 Can be either an integer greater than zero or "all". The default is
109 "all".
110 condition-transform
112 The rotation an output must have for the bar to be displayed on it.
113 Can be "all", 0, 1, 2 or 3. The numerical values represent rota‐
114 tions of 0, 90, 180 and 270 degrees, with the exact correspondence
115 depending on the compositor. The default is "all".
116 cursor-name
118 Name of the cursor displayed when hovering the pointer over the
119 bar. The default cursor is "pointer". Behold: What cursors are
120 available depends on your cursor theme.
121 exclusive-zone
123 Exclusive zone of the surface. Can be "true", "false" or "station‐
124 ary". If "true", the compositor is informed that it should not ob‐
125 struct the surface of LavaLauncher with other surfaces. If "false",
126 the compositor is informed that it can place other surfaces over or
127 under the surface of LavaLauncher. If "stationary", the compositor
128 is informed that the surface of LavaLauncher should not be moved to
129 accommodate other layer shell surfaces and that it can freely place
130 other surfaces over or under the surface of LavaLauncher. The de‐
131 fault is "true". The exact implementation is compositor dependant;
132 A compositor may choose to ignore the requested exclusive zone of
133 surfaces.
134 icon-padding
136 Padding around the icons. The default 4.
137 indicator-active-colour
139 The colour of the indicator for icons being activated. The default
140 is "#606060".
141 indicator-hover-colour
143 The colour of the indicator for icons over which the cursor hovers.
144 The default is "#404040".
145 indicator-padding
147 Padding around the icon indicator. The default 0.
148 indicator-style
150 Style of the icon indicator. Can be "rectangle", "rounded-rectan‐
151 gle" and "circle". The default is "rounded-rectangle". The corner
152 radia for "rounded-rectangle" are the same as the ones of the bar
153 itself.
154 layer
156 Layer of the bar surface. Can be "overlay", "top", "bottom" or
157 "background". Typically, "bottom" and "background" will be under‐
158 neath regular windows, while "top" and "overlay" will be above
159 them, however the exact placement on the z axis depends on the im‐
160 plementation of the compositor. The default layer is "bottom".
161 margin
163 The margin of the surface. Expects either one integer, to set the
164 margin in all directions, or four integers, to set the individual
165 top-, left-, right- and bottom-margins. The default margin is 0.
166 mode
168 The display mode of the bar. Can be "default", "full" or "simple".
169 In "default" mode, the bar is sized just large enough to house all
170 the buttons. Logically, the default mode is "default". In "full"
171 mode, the bar spans the entire length of the edge it is docked to.
172 "simple" mode is usually visually identical to "normal" mode, how‐
173 ever the surface of the bar is sized and anchored less aggres‐
174 sively, which may (or may not, depending on the implementation of
175 the compositor) improve how well LavaLauncher geometrically inte‐
176 grates and fits onto the desktop (and also will use less memory).
177 It gives the compositor a lot more leeway regarding the exact
178 placement of the bar. Behold: In "simple" mode, some compositors
179 may not respect margins parallel to the bar or the exclusive zone,
180 possibly even depending on the alignment. This is not a bug in
181 LavaLauncher but a limitation of your compositor.
182 namespace
184 The namespace of the layershell surface of the bar. Some composi‐
185 tors may treat layershell surfaces differently based on their name‐
186 space. The default is "LavaLauncher".
187 output
189 Name of the output on which the bar should be displayed. Output
190 names are compositor dependant. If set to "all" or "*",
191 LavaLauncher will display the bar on all outputs, which is the de‐
192 fault behaviour.
193 position
195 Position of the bar. Can be "top", "right", "bottom", "left". The
196 bar will dock to that edge of the output(s). The default position
197 is "bottom".
198 radius
200 The radius of the corners. Expects either one integer, to set the
201 radius of all corners, or four integers, to set the individual
202 radii for the top-left, top-right, bottom-left and bottom-right
203 corner. The default radius is 5. Set to 0 to disable corner round‐
204 ness.
205 size
207 Size of the bar. The default size is 60.
208 BAR COPY
210 Every "bar-copy" context will add a bar. This new bar has the same con‐
211 figuration and items as the previous bar. You can change the configura‐
212 tion and define additional items as usual. The assignments possible in
213 this context are the same as for the "bar" context.
214 BUTTON
216 Every "button" context will add a button to a bar. As such, this con‐
217 text is a nested inside the "bar" or "bar-copy" context. The assign‐
218 ments possible in this context are as follows.
219 command
221 Sets the shell command for left-, right-, middle-click and touch
222 interactions.
223 image-path
225 The path to an image file, which will be used as the icon of the
226 button.
227 left-click-command
229 The shell command executed when the user left-clicks on the button.
230 right-click-command
232 The shell command executed when the user right-clicks on the but‐
233 ton.
234 middle-click-command
236 The shell command executed when the user middle-clicks on the but‐
237 ton.
238 scroll-down-command
240 The shell command executed when the user scrolls down on the but‐
241 ton.
242 scroll-up-command
244 The shell command executed when the user scrolls up on the button.
245 touch-command
247 The shell command executed when the user touches the button.
248 SPACER
250 Every "spacer" context will add a spacer to a bar. As such, this con‐
251 text is a nested inside the "bar" or "bar-copy" context. The assign‐
252 ments possible in this context are as follows.
253 length
255 Length of the spacer.
256 COMMANDS
258 Commands are executed using sh(1).
259 LavaLauncher understands typical backslash escape sequences.
261 If the command is "exit", LavaLauncher will exit, if it is "reload",
263 LavaLauncher will reload.
264 LavaLauncher sets some environmental variables for the processes it
266 launches. Since all commands are executed via a shell, they can be used
267 as arguments for the commands. These variables are as follows.
268 $LAVALAUNCHER_OUTPUT_NAME
270 The name of the output the button has been clicked on.
271 $LAVALAUNCHER_OUTPUT_SCALE
273 The scale of the output the button has been clicked on.
274 COLOURS
276 LavaLauncher can parse hex code colours and read RGB values directly.
277 The supported formats are "#RRGGBB", "#RRGGBBAA", "0xRRGGBB" and "0xR‐
279 RGGBBAA" for hex code colours and "rgb(rrr,ggg,bbb)" and
280 "rgba(rrr,ggg,bbb,aaa)" for RGB colours.
281 CONDITIONS
283 Conditions are (re-)evaluated and bars created and destroyed accord‐
284 ingly whenever an outputs parameters are updated.
285 You can use conditions in combinations with the "bar-copy" feature to
287 create multiple versions of a bar for different conditions.
288 IMAGES
290 LavaLauncher support PNG images and, if enabled at compile time, SVG
291 images. It is recommended to use square images.
292 EXAMPLE CONFIGURATION
294 This is an example configuration which defines two bars.
295 global-settings
297 {
298 watch-config-file true;
299 }
300 bar # this is the first bar
302 {
303 output eDP-1;
304 position bottom;
305 background-colour "#202020";
306 button
308 {
309 image-path /path/to/image.png;
310 command useful-script.sh;
311 }
312 button
314 {
315 image-path "/path/to/another/image.png";
316 command "another-useful-script.sh";
317 }
318 }
319 bar # this is the second bar
321 {
322 output all;
323 button
325 {
326 image-path "/path/to/a/third/image.png";
327 command "do-something"
328 }
329 }
330
332 Probably.
333 Please report all bugs you find with an explanation how to reproduce
335 them.
336
338 You can send bug reports, patches and feedback to the mailinglist.
339 <~leon_plickat/lavalauncher@lists.sr.ht>
341
343 This project is developed using git. You can find the repository by
344 visiting the following URL.
345 <https://git.sr.ht/~leon_plickat/lavalauncher>
347
349 Leon Henrik Plickat <leonhenrik.plickat@stud.uni-goettingen.de>
350Version 2.0.0 2021-01-26 lavalauncher(1)