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