Graphical app launcher for X with few dependencies

Welcome! This is xlunch, the coolest graphical app launcher for Xorg/X11. It requires only pure Xlib and Imlib2. It allows you to run programs, commands, or simply select something out of a list using your mouse, keyboard, or both! UTF8 is fully supported meaning you can have text of all kinds. The prompt allows you to run arbitrary commands, and it works to filter your entries as well. xlunch is also highly configurable, both in functionality and style, it can even be used as a desktop! See below for more


Available Modes

  • One time launcher mode - this is default mode. There is no need to specify any commandline parameter for this mode. In this mode, xlunch opens as a fullscreen application, and offers a screen with icons to select applications to run, plus commandline which serves as a filter for the icons at the same time. Running any app or command ends the launcher. You can also cancel the launcher (by default) with the Esc key, or click with right mouse button.
  • Desktop mode - this mode is activated with -d. In this mode, xlunch sends itself to the lowest position in the window stack, so all other windows are above it. Your window manager will not have any control over it, so xlunch does not receive any input or focus and it cannot be raised to front. This emulates desktop with icons. In Desktop mode, applications start using fork (as another process) and don't terminate the launcher. xlunch in this mode cannot be terminated (except by killing it with SIGTERM).

Keep in mind that if you use desktop mode while you are running some other desktop already, you may end up with launcher running under your other desktop, thus it may be inaccessible. The desktop mode is intended only for users without another desktop (such as WM-only systems like i3). There are also some other flags that could be of interest in this mode, see below.



Commandline options:

Functional options (these changes what xlunch does, or how it does it):
-d, --desktop                     Desktop mode, always keep the launcher at background
                                  (behind other windows), and ignore ESC and right mouse
                                  click. Combined with --dontquit xlunch never exits
                                  (behaviour of --desktop from previous versions.
-v, --version                     Returns the version of xlunch
-H, --help                        Shows this help message
--name                            POSIX-esque way to specify the first part of WM_CLASS
                                  (default: environment variable RESOURCE_NAME or argv[0])
-n, --noprompt                    Hides the prompt, only allowing selection by icon
-o, --outputonly                  Do not run the selected entry, only output it to stdout
-S, --selectonly                  Only allow an actual entry and not free-typed commands
-i, --input [file]                File to read entries from, defaults to stdin if data is
                                  available otherwise it reads from
                                  ~/.config/xlunch/entries.dsv or /etc/xlunch/entries.dsv
-m, --multiple                    Allow multiple instances running
-t, --voidclickterminate          Clicking anywhere that's not an entry terminates xlunch,
                                  practical for touch screens.
-q, --dontquit                    When an option is selected, don't close xlunch. Combined
                                  with --desktop xlunch never exits (behaviour of
                                  --desktop from previous versions).
-R, --reverse                     All entries in xlunch are reversly ordered
-W, --windowed                    Start in windowed mode
-M, --clearmemory                 Set the memory of each entry to null before exiting.
                                  Used for passing sensitive information through xlunch.
Style options (these changes how xlunch looks):
-p, --prompt [text]               The prompt asking for input (default: "Run: ")
-f, --font [name]                 Font name including size after slash
                                  (default: "OpenSans-Regular/10" and  "DejaVuSans/10")
-F, --promptfont [name]           Font to use for the prompt (default: same as --font)
-G, --rootwindowbackground        Use root windows background image
-g, --background [file]           Image to set as background (jpg/png)
-I, --iconpadding [i]             Padding around icons (default: 10)
-T, --textpadding [i]             Padding around entry titles (default: 10). When
                                  --textafter is set this is the space between columns.
-c, --columns [i]                 Number of columns to show (without this the max amount
                                  possible is used)
-r, --rows [i]                    Numbers of rows to show (without this the max amount
                                  possible is used)
-b, --border [i]                  Size of the border around the icons and prompt
                                  (default: 1/10th of screen width)
-B, --sideborder [i]              Size of the border on the sides, if this is used
                                  --border will be only top and bottom
-P, --promptspacing [i]           Distance between the prompt and the icons (default: 48)
-s, --iconsize [i]                Size of the iconsĀ (default: 48)
-a, --textafter                   Draw the title to the right of the icon instead of
                                  below, this option automatically sets --columns to 1
                                  but this can be overridden.
-O, --textotherside               Draw the text on the other side of the icon from where
                                  it it normally drawn.
-u, --upsidedown                  Draw the prompt on the bottom and have icons sort from
                                  bottom to top.
--tc, --textcolor [color]         Color to use for the text on the format rrggbbaa
                                  (default: ffffffff)
--pc, --promptcolor [color]       Color to use for the prompt text (default: ffffffff)    
--bc, --backgroundcolor [color]   Color to use for the background (default: 2e3440ff)
                                  NOTE: transparent background color requires a compositor
--hc, --highlightcolor [color]    Color to use for the highlight box (default: ffffff32)

If you want to completely hide icons (to eg. use xlunch to only select between text entries like dmenu) you should set --iconsize to 0 and turn on --textafter mode. This will cause xlunch to remove the extra margin that would normally be around an icon and instead show only the text. Since the entries in xlunch are normally based on icon size and their padding this would make each entry super small, but the --textafter mode makes the size of each entry dependent on the size of the text instead. Note however that this by default sets --columns to 1, so override it with how many columns of text you would like. When --textafter mode is enabled --iconpadding is used on all sides of the entry box except the right.

There are two different border settings. If you set only --border it will be applied to all four sides. By setting --sideborder you override the border setting and this new border size will be used for the right and left border, while the regular border is used for top and bottom.

For transparent background colors you need to have a compositor installed. This will make the background of xlunch transparent. Note that the transparency is not additive, meaning that if you set background to 50% transparency and highlight to 70% transparency the highlighted areas will be 70% total transparency and not 70% of the 50%, ie. 35%. When a background image is supplied, or the --rootwindowbackground switch is used xlunch will apply a slight black tint to the image to make text more readable. By setting the background color manually this color will be used instead, including transparency, so to disable the tint simply pass a fully transparent color (this does not require a compositor).

In previous version desktop mode would by default fork of processes instead of terminating. This is now a separate option (--dontquit) so you can keep xlunch running no matter the mode.

If you want to use xlunch to for example choose a password you can use the --clearmemory mode. This will set all the data for the entries to NULL when they are destroyed (ie. xlunch closes or a new set of data is passed over stdin, see below). This is not bulletproof, all the data will still be stored in plaintext in memory while xlunch is running, but it's better than nothing.

When loading fonts xlunch will look for them in the folders: ~/.local/share/fonts, ~/.fonts, /usr/local/share/fonts, /usr/local/share/truetype, and /usr/local/share/TTF. Imlib however does not search recursively, so to load a font in for example ~/.local/share/fonts/FontFamily/FontName.ttf in size 10 we would have to pass -f "FontFamily/FontName/10".

Multi monitor setup

xlunch does not know how to detect your output monitors, it sees your monitors as a big single screen. If you run it, your window manager positions the window and makes it fullscreen, so it is up to your window manager to decide what monitor xlunch runs on. If you, however configure your WM to make xlunch floating, start xlunch in Desktop mode (which bypasses your window manager) or if you do not have any WM at all, you can customize the size and position of the window manually by providing the top/left coordinates and width/height of your monitor screen, which effectively positions xlunch on the desired place/monitor. Use the following options:

-x, --xposition [i]               The x coordinate of the launcher window
-y, --yposition [i]               The y coordinate of the launcher window
-w, --width [i]                   The width of the launcher window
-h, --height [i]                  The height of the launcher window

For example, if you have two 800x600 monitors side by side, xlunch sees it as 1600x800. You can put it to first monitor by: -x 0 -y 0 -w 800 -h 600, or to second monitor by using -x 800 -y 0 -w 800 -h 600. Remember that all these settings might be overridden by your window manager unless you start xlunch in Desktop mode. Another thing that is helpful is that xlunch sets three distinct WM_CLASS values, "xlunch-fullscreen" for it's default mode, "xlunch-desktop" for the desktop mode, and "xlunch-windowed" for it's windowed mode. This makes it easy to tell your window manager to treat each of the different kinds properly. Alternatively you can use the --name option or the environment variable RESOURCE_NAME to set the first part of WM_CLASS, note however that this value is also the program called by recur.


make test
make install
Uninstall with make remove

Entries file:

xlunch can accept entries to show either over stdin or through a file. The format used in both cases are:


title is the name of the program which will be shown, icon_path is a path to an icon to show for the entry (png or jpg), and cmd is the command to be run or returned when this entry is selected. To allow complex bash commands using semi-colons xlunch simply parses the cmd field until a new-line is encountered. By default xlunch will show a ghost icon if the icon you specified couldn't be found, if you want to not have an icon you can simply leave the icon field empty (ie. title;;cmd). If you want to run xlunch from within xlunch, for example to create a menu hierarchy, you should use a special syntax. This syntax allows xlunch to replace its old process with the new one so you only have a single instance of xlunch running and don't get any overhead from running it through bash. In order to do this simply put recur [options] as the cmd field. This will reuse the program name you originally used to call xlunch with but replace the options with anything you add after recur. If you want to run a program by the name recur, simply add a space in front of it. NOTE: recur relies on splitting the list of arguments, this is currently only done on spaces, even those inside quotes, so it's not possible to pass arguments with spaces in them when using recur (this is how previous versions of xlunch did all launching).

If a completely empty line is encountered (ie. two sequential newlines), then all entries read up until that point will be removed and only entries after this empty line will appear. This is a feature that is intended for interfacing with xlunch from other scripts. There are many programs that create this kind of output, like for example Conky, which can be piped directly to xlunch. Sometimes you want new output to appear on the top of the list instead of at the bottom, to achieve this you can use the --reverse switch. To add entries yourself you can create a named pipe and keep it open while starting xlunch. xlunch will then read from this pipe and update the entries on the fly. So you can write a script that passes entries to this pipe and they will appear in xlunch, and all entries can be removed by passing two newlines in a row. Example:

mkfifo /tmp/xlunch-input # Create a named pipe
cat > /tmp/xlunch-input & # Ensure that the pipe stays open
cat entries.dsv > /tmp/xlunch-input & # Write some initial data to the pipe
# This is neccesarry to avoid xlunch seeing the pipe as empty
cat /tmp/xlunch-input | xlunch & # Start xlunch in the background, reading from the pipe
echo "Hello;;notify-send 'Hello from xlunch'" > /tmp/xlunch-input
# This last line will add the entry "Hello" to the already running xlunch menu
echo "Xlunch is great;;notify-send 'quite great indeed'" > /tmp/xlunch-input
# This adds yet another entry
echo -e "\nAll alone;;notify-send 'where did the others go?'" > /tmp/xlunch-input
# Because of the first character being a newline xlunch will clear the other
# entries and add this one as the only entry.

During compilation, a sample entries file is created for you. By default, this entries file is installed into /etc/xlunch/entries.dsv. The file is created by reading the freedesktop "Desktop Entry Specification" files (.desktop) found in $HOME/.local/share/applications and /usr/share/applications these files are read in priority so you can override the versions installed by your package manager by putting a file with the same name in the user local directory. The file generated is static, so if you want to add new programs to the list that xlunch sees then you could run the extras/genentries script again. The output of this script is in the format expected from entries.dsv files and can be customized to your needs and to create custom menus. When xlunch starts without the --input flag, it first checks stdin to see if you have piped it any entries. If nothing is found there it tries to load your entries file from ~/.xlunch/entries.dsv. If this fails, system-wide entries is loaded from /etc/xlunch/entries.dsv. By passing --input the file specified is used instead and all other entries (including stdin) are ignored.

Example usage:

# launcher mode:
xlunch --background wp.jpg --font "OpenSans-Regular.ttf/10" --input sample_entries.dsv

# desktop mode:
xlunch --background wp.jpg --font "OpenSans-Regular.ttf/10" --input sample_entries.dsv --desktop --multiple --noprompt --dontquit

Tips and tricks:

If you wish to run xlunch as app launcher, best practice is to set up a keyboard shortcut to start xlunch, such as Alt+F2. Or you can put a button in a taskbar to run it.

For example, to start xlunch on Alt+F2 in i3wm, add this line to ~/.i3/config:

bindsym $mod+F2 exec /usr/bin/xlunch

To have xlunch running as a desktop with icons in i3wm, add this to ~/.i3/config:

exec /usr/bin/xlunch --desktop --multiple --noprompt --dontquit

Note that you can also use the position flags from the multi-monitor section to display multiple menus on your desktop.

xlunch is a perfect dmenu replacement, or rofi replacement.

© 2016, 2017, Tomas Matejicek - tomas [at] slax [dot] org

Business vector designed by Freepik