beyondtray 0.2.0

beyondtray - displaying a custom menu in the desktop system tray

BeyondTray

BeyondTray is an app for displaying a custom menu in the system tray, for example to have a bunch of easily accessed launchers.

Example menu

BeyondTray shows a system tray icon with a dynamic, customizable menu.

For example, when running beyondtray sample1.menu, BeyondTray will show this menu:

given this menu description in file sample1.menu:

title = "Sample"

[[e]]
title = "The &first menu entry"
command = 'xmessage "the first entry was selected"'

[[e]]
title = "&Another entry"
command = 'echo "the second entry was selected" >> ~/foobar.txt'

[[e]]
title = "This is a disabled entry (no command associated)"

[[e]]
separator = true

[[e]]
title = "The above dashes are a separator"

[[e]]
title = "This is a &checkable entry"
command = 'echo "the checkbox was checked" >> ~/foobar.txt'
checkable = true

[[e]]
checked = false
title = "This is a checkable entry (but it's disabled)"

[[e]]
checked = true
title = "This is a checked &entry"
command = 'echo "the checkbox was unchecked" >> ~/foobar.txt'

[[e]]
separator = true

[[e]]
title = "A &sub-menu"

[[e.e]]
title = "an entry in the sub-menu"
command = 'xmessage "submenu was selected"'

[[e]]
separator = true
title = "This is a separator with a title"

[[e]]
title = "A last entry that opens &Gitlab.com"
command = "firefox https://gitlab.com"

The entries that are not disabled (grayed out) can be clicked on, and the associated command will be run when clicked.

Dynamic

The menu content is dynamic because the menu description is read just when the context menu is about to be shown. The menu description can be read from:

• a static file (that can be edited by an external program)
• a custom command that dynamically generates the menu description on stdout
• a template file, containing static entries and conditions

Furthermore, the menu description is re-read/re-generated every time the user right-clicks on the tray icon. Optionally, the menu can also be re-generated when a watched file is modified, periodically, or when receiving SIGUSR1. This can be useful to change the tray icon depending on some external event.

Syntax

The menu description follows the TOML syntax.

Simple entries

A simple menu entry is just (e is for "entry"):

[[e]]
title = "Run xclock"

but the entry will be disabled because there is no command associated yet. Setting one is just specifying the command below:

[[e]]
title = "Run xclock"
command = "xclock"

Clicking the entry will run the associated command.

& can be used before any letter of an entry title. The letter will be underlined in the menu, and that letter will be the shortcut key to trigger the menu entry.

[[e]]
title = "Run &xclock"
command = "xclock"

In this example, pressing x while the menu is shown will run xclock.

Icons

A menu entry can have an icon:

[[e]]
title = "this will have the gimp icon"
icon = "gimp"
# the icon will typically be found at /usr/share/icons/hicolor/<something>/apps/gimp.png

[[e]]
title = "and a custom icon"
icon = "~/my-icon.png"

An icon can be "colorized" differently:

[[e]]
title = "this will have a red gimp icon"
icon = "gimp"
colorize_icon = "red"

The tray icon can also be set, by having before all [[e]] entries:

icon = "gimp"
# also supports colorize_icon

Checkboxes

Menu entries can be checkable (purely for display, its state is not stored), like this:

[[e]]
title = "entry is unchecked"
checked = false

[[e]]
title = "entry is checked"
checked = true

Separators

A simple separator can be added in a menu:

[[e]]
separator = true

A title can be added to the separator to make a menu section:

[[e]]
separator = true
title = "Separator title"

Submenus

Making submenus is very similar except the depth is indicated by multiple dot-separated es:

[[e]]
title = "a submenu"

[[e.e]]
title = "a sub-entry"
command = "a command"

[[e.e]]
title = "a checkbox"
checked = false
command = "another command"

Comments, quotes

Being TOML, the menu description can contain comments, supports different quote styles:

[[e]]
# this is a comment
title = """This entry contains "double quotes" and 'single quotes'"""
icon = 'vlc'
command = "vlc"

Using templating for dynamic content

Templating is useful for dynamic content, for example changing the label of an entry, or making a checkbox really dynamic. The syntax uses Jinja.

File: dynamic.menu.jinja

[[e]]
title = "date is now: {{ read("date '+%Y-%m-%d %T'") }}"

[[e]]
separator = true

[[e]]
{% if sh("pgrep xscreensaver | grep -q .") %}
title = "XScreenSaver is running"
checked = true
{% else %}
title = "XScreenSaver is not running!"
checked = false
command = "xscreensaver"
{% endif %}

Run with beyondtray --template dynamic.menu.jinja.

See the jinja manual for complete description of templating.

Using a command for dynamic content

File: dynamic.sh

#!/bin/sh -e

cat << EOF
[[e]]
title = "date is now: $(date '+%Y-%m-%d %T')"
[[e]]
separator = true
EOF

echo '[[e]]'
if pgrep xscreensaver | grep -q .
then
    echo 'title = "XScreenSaver is running"'
    echo checked = true
else
    echo "title = 'XScreenSaver is not running!'"
    echo checked = false
    echo "command = 'xscreensaver'"
fi

Run with beyondtray --command dynamic.sh.