j4-dmenu-desktop - Man Page

fast desktop menu

Synopsis

j4-dmenu-desktop[OPTIONS]

Description

j4-dmenu-desktop is a faster replacement for i3-dmenu-desktop.

It's purpose is to find .desktop files and offer you a menu to start an application using dmenu.

The arguments are as follows:

-b, --display-binary

Display binary name after each entry (off by default).

-f, --display-binary-base

Display basename of binary name after each entry (off by default).

-d, --dmenu command

Determines the command used to invoke dmenu. Executed with your shell ($SHELL) or /bin/sh.

--no-exec

Do not execute selected command, send to stdout instead.

--no-generic

Do not include the generic name of desktop entries.

-t, --term command

Sets the terminal emulator used to start terminal apps.

--term-mode mode

Instruct j4-dmenu-desktop on how it should execute terminal emulator. This flag also changes the default value of --term flag.

Possible values are: default | xterm | alacritty | kitty | terminator | gnome-terminal | custom

See Term Mode for more info.

--usage-log file

Must point to a read-writeable file (will create if not exists). In this mode entries are sorted by usage frequency.

--prune-bad-usage-log-entries

Remove names marked in usage log for which j4-dmenu-desktop was unable to find a desktop file. This can happen when an app marked in usage log no longer exists because it was uninstalled.

-x, --use-xdg-de

Enables reading $XDG_CURRENT_DESKTOP to determine the desktop environment.

--wait-on path

Must point to a path where a file can be created. In this mode no menu will be shown. Instead the program waits for path to be written to (use ‘echo > path’). Every time this happens a menu will be shown. Desktop files are parsed ahead of time. Performing ‘echo -n q > path’ will exit the program.

--wrapper wrapper

A wrapper binary. Useful in case you want to wrap into 'i3 exec'.

-I, --i3-ipc

Execute desktop entries through i3 IPC or Sway IPC. Requires either i3 or Sway to be running.

--skip-i3-exec-check

Disable the check for --wrapper "i3 exec" or --wrapper "sway exec". j4-dmenu-desktop has direct support for i3/Sway through the -I flag which should be used instead of the --wrapper option. j4-dmenu-desktop detects this and exits. This flag overrides this behaviour.

-i, --case-insensitive

Sort applications case insensitively

-v

Be more verbose. When specified once, INFO is used, when twice, DEBUG is used. See Log Levels.

--log-level ERROR | WARNING | INFO | DEBUG

A more explicit version of -v. This flag takes precedence over -v.

--log-file file

Specify a log file. file will be truncated. By default, the INFO loglevel is used.

--log-file-level ERROR | WARNING | INFO | DEBUG

Set file log level.

--version

Display program version.

-h, --help

Display help message.

Log Levels

Some arguments support setting the log level. j4-dmenu-desktop uses the following log levels: ERROR, WARNING, INFO and DEBUG. The WARNING (and ERROR) loglevels are displayed by default. Lower loglevels automatically enable higher ones.

Term Mode

There are several modes available for the --term-mode flag:

default

The default mode. A temporary shell script is created containing the chosen command. The script deletes itself upon execution, j4-dmenu-desktop never deletes it itself. It sets the title of terminal emulator using OSC escape sequences (see console_codes(4)). Terminal emulator is executed as follows:

[terminal emulator] -e [generated temporary script]

Other modes should be preferred. This approach is universal but fragile.

Default value of --term is i3-sensible-terminal.

xterm

Use xterm calling convention:

[terminal emulator] -title [desktop app Name] -e [command line]

Default value of --term is xterm. Other compatible terminal emulators include: rxvt-unicode.

alacritty

Use alacritty calling convention:

[terminal emulator] -T [desktop app Name] -e [command line]

Default value of --term is alacritty. Other compatible terminal emulators include: st, foot.

kitty

Use kitty calling convention:

[terminal emulator] -T [desktop app Name] [command line]

Default value of --term is kitty. Other compatible terminal emulators include: foot.

terminator

Use terminator calling convention:

[terminal emulator] -T [desktop app Name] -x [command line]

Default value of --term is terminator. Other compatible terminal emulators include: xfce4-terminal.

gnome-terminal

Use gnome-terminal calling convention:

[terminal emulator] --title [desktop app Name] -- [command line]

Default value of --term is gnome-terminal.

custom

Allow for completely custom handling of --term. When --term-mode custom is passed, an alternative system for handling --term is used. It is handled as a list of arguments separated by space ( ). No other whitespace characters act as an argument separator (this behavior differs from the shell).

Multiple consecutive space characters will be treated as a single space (except for escaped spaces). Leading and trailing spaces in --term will be ignored. This means that it is not possible to pass zero-length arguments to --term.

The following placeholders are recognised:

{name}

Name of desktop app. Useful for setting the title.

{cmdline@}

Command line to be executed expanded as separate arguments. This must be an independent argument; ‘j4-dmenu-desktop --term-mode custom --term "-e={cmdline@}"’ is invalid.

{cmdline*}

Command line to be executed expanded as a single argument. {cmdline@} should be preferred. Arguments will be escaped; Contents of {cmdline*} can be passed to /bin/sh -c safely.

{script}

Filename of a script generated by j4-dmenu-desktop. This is the same script used by --term-mode default. The script will be generated only if this placeholder is specified at least once in --term. The script sets terminal title itself, it souldn't be necessary to set it manually.

{cmdline@} and {cmdline*} should be preferred over {script}.

The following escape sequences are recognised:

\\

Literal \ character.

\{

Literal { character.

\ 

(backslash with space) Do not handle the following space as an argument separator.

Undefined escape sequences and placeholders will result in an error message and program termination.

Default value of --term is same as of default term mode.

This is how other modes look when written using custom mode:

default

‘j4-dmenu-desktop --term-mode custom --term "i3-sensible-terminal -e {script}"’

xterm

‘j4-dmenu-desktop --term-mode custom --term "xterm -title {name} -e {cmdline@}"’

alacritty

‘j4-dmenu-desktop --term-mode custom --term "alacritty -T {name} -e {cmdline@}"’

kitty

‘j4-dmenu-desktop --term-mode custom --term "kitty -T {name} {cmdline@}"’

terminator

‘j4-dmenu-desktop --term-mode custom --term "terminator -T {name} -x {cmdline@}"’

gnome-terminal

‘j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} -- {cmdline@}"’

This is how the deprecated -e flag of gnome-terminal could be used:

j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} -e {cmdline*}"

This is how placeholders can be escaped:

j4-dmenu-desktop --term-mode custom --term "echo \{name}\ \{cmdline*}"

--term receives two arguments: ‘echo’ and ‘{name} {cmdline*}’, no placeholders are replaced. j4-dmenu-desktop would see three arguments instead of two if the second \ had not been passed.

Environment

I3SOCK

This variable overwrites the i3/Sway IPC socket path.

XDG_DATA_HOME

Primary directory containing desktop files.

XDG_DATA_DIRS

Additional directories containing desktop files.

XDG_CURRENT_DESKTOP

Current desktop environment used for enabling/disabling desktop environemnt dependent desktop files. Must be enabled by --use-xdg-de.

Standard environmental variables for locales are acknowledged in addition to those listed above. The exact environmental variables used are implementation-dependent, but setting LC_MESSAGES, LC_ALL or LANG should generally work.

See Also

https://github.com/enkore/j4-dmenu-desktop

Info

January 10, 2024