xlunchWelcome! 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).
+--config [file] Reads configuration options from a file. The
+ options are the same as the long options
+ specified here. Options that take a value must
+ have a colon (':') before it's option. It is
+ also possible to pass the entries along with the
+ configuration file by using "entries:"
+ followed by a newline and the regular contents
+ of an input file
+-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. Nice for scripting.
+-i, --input [file] File to read entries from, defaults to stdin
+ if data is available otherwise it reads from
+ $HOME/.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.
+--focuslostterminate When the window loses focus xlunch will quit,
+ practical for menus
+-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 as 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.
+-U, --shortcuts [shortcuts] Sets shortcuts for the entries, 'shortcuts' is a
+ string of UTF-8 characters to use sequentially
+ for the entries provided.
+-A, --button [button] Adds a button to the window. The argument
+ "button" is a semicolon-separated list on the
+ form ";;,;"
+ If x or y is negative positioning is relative
+ to the other side of the screen.
+--noscroll Disable scroll in xlunch. Ignore entries
+ that can't fit the screen.
+ -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)
+--bgfill Makes the background keep aspect ratio
+ while stretching
+-L, --highlight [file] Image set as highlighting under selected icon
+ (jpg/png)
+-I, --iconpadding [i] Padding around icons (default: 10)
+ --iconvpadding [i] Padding around icons (default: Same as --iconpadding)
+-T, --textpadding [i] Padding around entry titles (default: 10)
+-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)
+ This can also be set to 'auto' in order to
+ automatically calculate a border taking into
+ account the margin settings and the
+ configured columns and rows. You can also specify
+ border in terms of percentage of screen width by
+ appending a % sign to the value
+-B, --sideborder [i] Size of the border on the sides, if this is used
+ --border will be only top and bottom. Similarily
+ this can be set to 'auto' or a percentage but
+ then only side borders are calculated
+--borderratio [i] The ratio of the border to apply above the
+ content. 0 is no top border, only bottom. 100 is
+ only top border, no bottom
+--sideborderratio [i] The ratio of the side border to apply to the
+ left of the content. 0 is no left border, only
+ right. 100 is only left border, no right
+-C, --center Center entries when there are fewer entries on a
+ row than the maximum
+-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 is normally drawn.
+-u, --upsidedown Draw the prompt on the bottom and have icons
+ sort from bottom to top.
+-X, --paddingswap Icon padding and text padding swaps order
+ around text.
+-l, --leastmargin [i] Adds a margin to the calculation of
+ application sizes.
+-V, --leastvmargin [i] Adds a vertical margin to the calculation of
+ application sizes.
+-e, --hidemissing Hide entries with missing or broken icon images
+--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)
+This list of options might seem a bit daunting at first. But you don't have to pass them
+all on the command-line. If you specify a configuration file with --config
+xlunch will read these options from a configuration file instead. The options have the same
+name as their long versions do, but when passed through a configuration file options with
+an argument must be split by a colon. If you only have a few entries to pass to xlunch (in
+case of a menu for example) they can be passed through the configuration file as well. An
+example showing configuration file usage with entries can be seen here:
+textafter
+columns: 3
+rows: 5
+iconsize: 64
+outputonly
+entries:
+ Pidgin;extra/pidgin.png;pidgin
+ Xterm;extra/terminal.png;xterm
+ Firefox;extra/firefox.png;firefox
--config option the ones in the file will
+override them, and conversely any option following the --config option will
+override those in the file. Where the above file to be used like so xlunch --rows 10
+ --config file.cfg --columns 2 it would lead to xlunch using 5 rows and 2 columns.
+Since all the options are the same you can also use the config option in a configuration
+file. This means that you can have one config file with your system style of colors and
+fonts, and multiple other files loading that file before setting other options like buttons
+and entries. Just make sure not to load the same configuration file within that file as it
+would lead to an infinite loop.
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.
When using xlunch to create menus of a set of options it might be practical to have shortcuts for
+the options. With the --shortcuts option this is achievable. Since this captures
+keypresses it might not be very useful without --noprompt but it is all the same
+possible (perhaps using the number keys to hotkey the first 10 entries while being able to search
+for the rest). As an example usage passing --shortcuts "atf" will apply 'a' as a shortcut
+to the first entry, 't' as a shortcut to the second, and 'f' as a shortcut to the third.
To extend the possibilities of xlunch you can also add buttons anywhere in the window with the
+--button option. It takes an argument that's a semicolon-separated list on the form:
+icon;highlight icon (optional);x,y;command. Note that the highlight icon is optional
+and will be used instead of the main icon when you hover over it. If no highlight icon is specified it
+will just show the regular icon on hover. So for example the command
+--button "./extra/firefox.png;;100,100;firefox" would put the Firefox icon from the extras
+folder at the position 100,100 without a highlight icon and run "firefox" when it's pressed (note that
+these buttons also adheres to switches like --outputonly). If you use a negative x or y
+value the icon will be placed relative to the other side of the screen. So the command
+--button "./extra/firefox.png;;-100,-100;firefox" will put the same icon in the bottom
+right corner.
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.
Compile:
+ +make
+make test
+make install
+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;icon_path;cmd
+title;icon_path;cmd
+title;icon_path;cmd
+title;icon_path;cmd
+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
+use the internal recur command by putting :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).
+
+The :recur command shown above is a special class of commands called an "internal
+command". All exec fields, both in entries, buttons, and otherwise that starts with a colon is
+treated as an internal command (if you wish to avoid this simply add a space in front of the colon).
+Apart from :recur the internal commands are:
+
+:scroll Scroll to the given position. pos can be "top", "bottom", the row number,
+ or a number starting with + or - which is parsed as a relative scroll.
+:hover Set the entry as hovered and scroll to it. entry cas be "start", "end",
+ the entry number (1 indexed, 0 for no entry), or +/- like scroll.
+:exec Runs the given command, even when outputonly is enabled
+:print Prints a string to stdout
+:quit Quits out of xlunch
+ :scroll +3 :print "Scrolled!". For
+print and exec the argument needs to be enclosed in double-quotes if you want to
+chain them, otherwise they will exec/print everything that follows. Because of this quit
+can be put in front of a statement and wont quit until after all commands are run. So
+:quit :exec myProgram --help will run myProgram with it's help flag, then quit. The same
+can also be achieved with double quotes :exec "myProgram --help" :quit.
+NOTE: Scroll is not completely implemented yet, bottom doesn't do anything and you are
+able to scroll past the top and bottom of the list. This will not be possible in the future.
+
+
+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 & Peter Munch-Ellingsen - peterme [at] peterme [dot] net
+
+ Business vector designed by Freepik
+
+
+