J4-DMENU-DESKTOP(1)

NAME
j4-dmenu-desktop - 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

COPYRIGHT
Copyright (C) 2013 enkore < public+j4-dmenu-desktop@enkore.de >

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see < http://www.gnu.org/licenses/ >.