WMALAUNCHER(1)

NAME
wmalauncher - A dockapp application launcher.

SYNOPSIS
wmalauncher --help
wmalauncher --fonts-info [<PATH>[:<PATH>...]]
wmalauncher --config <FILE> [--prefix <PREFIX>] [OPTION]...
wmalauncher --command <CMD> --icon <ICON> [OPTION]...
wmalauncher --desktop-file <FILE>[:<FILE>...] [OPTION]... [OPTION] can be :
  [--run-in-terminal] [--preferred-terminals <TERM>[:<TERM>...]]
  [--window-size <SIZE>] [--icon-padding <SIZE>] [--border-size <SIZE>]
  [--background-color <COLOR|GRADIENT>] [--hover-background-color <COLOR|GRADIENT>]
  [--border-color <COLOR|GRADIENT>] [--hover-border-color <COLOR|GRADIENT>]
  [--icon-search-path <PATH>[:<PATH>...]]
  [--desktop-file-search-path <PATH>[:<PATH>...]]
  [--font-search-path <PATH>[:<PATH>...]]
  [--tooltip-text <TEXT>] [--tooltip-font <FONT/SIZE>]
  [--tooltip-background-color <COLOR|GRADIENT>]
  [--tooltip-foreground-color <COLOR>]
  [--tooltip-border-size <SIZE>] [--tooltip-text-padding <SIZE>]
  [--tooltip-show-delay <DELAY>] [--tooltip-hide-delay <DELAY>]
  [--icon-grayscale] [--hover-icon-grayscale]
  [--frame <HICOLOR>/<HOVER_HICOLOR>:<LOCOLOR>/<HOVER_LOCOLOR
  [--icon-brightness <VALUE>] [--hover-icon-brightness <VALUE>]
  [--icon-contrast <VALUE>] [--hover-icon-contrast <VALUE>]
  [--icon-gamma <VALUE>] [--hover-icon-gamma <VALUE>]
  [--double-click [<DELAY>]] [--display <NAME>] [--broken-wm]

DESCRIPTION
wmalauncher is an easy to use and highly configurable application launcher especially designed for fluxbox, but which also works well under blackbox, openbox, windowmaker. wmalauncher supports XPM, PNG, SVG icons, .desktop files, true-type fonts (for tooltip text), allows to configure, among others, the brightness, contrast and gamma correction of icons, allows to draw a frame around the button, etc...

OPTION

-h|--help
    Prints this help page.

-f|--fonts-info [<PATH>[:<PATH>...]]
    Prints information on (default) supported fonts and on fonts accessible from the given path(s), if any.

-C|--config <FILE> [-p|--prefix <PREFIX>]
    Loads the configuration from the file <FILE>, then updates the settings for which there are entries with the prefix <PREFIX>, if any. see section CONFIGURATION FILE FORMAT for more about configuration files.

-c|--command <CMD> -i|--icon <ICON>
    Sets the command to execute to <CMD> and the icon to display to <ICON>. <ICON> can be an absolute pathanme, or a simple name (with or without extension) in which case wmalauncher will use the first icon that matches <ICON> found in the icon search paths. See option --icon-search-path for more about icon search paths.

-d|--desktop-file <FILE>[:<FILE>...]
    Loads the 1st .desktop file that matches any of the specified (path)names, then setups the command to execute, the icon to display and the tooltip text accordingly. <FILE> can be an absolute pathanme, or a simple name (with or without extension) in which case wmalauncher will use the first .desktop file that matches <FILE> found in the 'desktop file search paths'. See option --desktop-file-search-path for more about 'desktop file search paths'.

-T|--run-in-terminal
    Activates execution of the command/application in a terminal window (see option --preferred-terminals).

-P|--preferred-terminals <TERM>[:<TERM>...]
    Sets the list of preferred terminal emulators. The 1st available terminal in this list is used to run the command/application when (1) the option --run-in-terminal is passed in argument, (2) the desktop file passed to option --desktop-file includes an entry 'Terminal=true'. By default, the list of preferred terminal emulators is set to : /usr/bin/xterm:/usr/bin/rxvt:/usr/bin/xfce4-terminal:/usr/bin/konsole

-w|--window-size <SIZE>
    Sets the window size to <SIZE> x <SIZE>. Default to 64.

-g|--icon-padding <SIZE>
    Sets the padding size around the icon to <SIZE>. Default to 3.

-z|--border-size <SIZE>
    Sets the window border size to <SIZE>. Default to 4.

-k|--background-color <COLOR|GRADIENT>
    Sets the background color to the plain color <COLOR> or to the color gradient <GRADIENT>. Default to the plain color Black. See sections COLORS and GRADIENTS for informations about supported colors and gradients.

-K|--hover-background-color <COLOR|GRADIENT>
    Sets the background color on mouse hovers to the plain color <COLOR> or to the color gradient <GRADIENT>. Default to the plain color Black. See sections COLORS and GRADIENTS for informations about supported colors and gradients.

-b|--border-color <COLOR|GRADIENT>
    Sets the window border color to the plain color <COLOR> or to the color gradient <GRADIENT> . Default to the plain color White. See sections COLORS and GRADIENTS for informations about supported colors and gradients.

-B|--hover-border-color <COLOR|GRADIENT>
    Sets the window border color on mouse hovers to the plain color <COLOR> or to the color gradient <GRADIENT>. Default to the plain color White. See sections COLORS and GRADIENTS for informations about supported colors and gradients.

-a|--icon-search-path <PATH>[:<PATH>...]
    Prepends the given path(s) to the icons search path, which is initially set to :
      ~/.icons:/usr/share/icons/Adwaita/scalable:/usr/share/icons/Adwaita/48x48:/usr/share/icons/hicolor/scalable:/usr/share/icons/hicolor/48x48:/usr/share/pixmaps:/usr/share/icons

    Any path given in arguments which is not absolute is assumed to be relative to the root path: /usr/share/icons

-A|--desktop-file-search-path <PATH>[:<PATH>...]
    Prepends the given path(s) to the "desktop files" search path, which is initially set to :
     ~/.local/share/applications:/usr/share/applications

-n|--font-search-path <PATH>[:<PATH>...]
    Prepends the given path(s) to the fonts search path, which is initially set to :
      ~/.fonts:/usr/share/fonts/TTF:/usr/share/fonts/truetype:/usr/share/fonts/truetype/dejavu:/usr/share/fonts/truetype/liberation:/usr/share/fonts/dejavu:/usr/share/fonts/liberation

-t|--tooltip-text <TEXT>
    Sets the tooltip text to <TEXT>.

-F|--tooltip-font <FONT/SIZE>
    Sets the tooltip font to <FONT> with a size of <SIZE>. Default to "DejaVuSans/11"

-o|--tooltip-background-color <COLOR|GRADIENT>
    Sets the tooltip background color to the plain color <COLOR> or to the color gradient <GRADIENT>. Default to the plain color White. See sections COLORS and GRADIENTS for informations about supported colors and gradients.

-O|--tooltip-foreground-color <COLOR>
    Sets the tooltip foreground color to <COLOR>. Default to Black. See section COLORS for informations about supported colors.

-Z|--tooltip-border-size <SIZE>
      Sets the tooltip border size to <SIZE>. Default to 1.

-G|--tooltip-text-padding <SIZE>
    Sets the padding size around the tooltip text to <SIZE>. Default to 3.

-l|--tooltip-show-delay <DELAY>
    Sets the tooltip show timing delay to <DELAY> ms. Default to 1000 ms.

-L|--tooltip-hide-delay <DELAY>
    Sets the tooltip hide timing delay to <DELAY> ms. Default to 5000 ms.

-y|--icon-grayscale
    Displays the icon in grayscale mode.

-Y|--hover-icon-grayscale
    Displays the icon in grayscale mode on mouse hovers.

-E|--frame <HICOLOR>/<HOVER_HICOLOR>:<LOCOLOR>/<HOVER_LOCOLOR>[:SIZE]
    Draws a frame with a thickness of <SIZE> pixels around the icon. The top and left borders are painted using color <HICOLOR>, while the bottom and right borders are painted using color <LOCOLOR>. On mouse hovers, the colors <HOVER_HICOLOR> and <HOVER_LOCOLOR> are used instead. When the left mouse button is pressed, the HI/LO colors are swapped, unless when option -2|--double-click is used. Default to: White/White:Black/Black:1 See section COLORS for informations about supported colors.

-r|--icon-brightness <VALUE>
    Sets the icon brightness to <VALUE>. Default to 0.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about brightness values.

-R|--hover-icon-brightness <VALUE>
    Sets the icon brightness on mouse hovers to <VALUE>. Default to 0.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about brightness values.

-s|--icon-contrast <VALUE>
    Sets the icon contrast to <VALUE>. Default to 1.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about contrast values.

-S|--hover-icon-contrast <VALUE>
    Sets the icon contrast on mouse hovers to <VALUE>. Default to 1.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about contrast values.

-m|--icon-gamma <VALUE>
    Sets the icon gamma to <VALUE>. Default to 1.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about gamma values.

-M|--hover-icon-gamma <VALUE>
    Sets the icon gamma on mouse hovers to <VALUE>. Default to 1.000000. See section ICON BRIGHTNESS/CONTRAST/GAMMA for more about gamma values.

-2|--double-click [<DELAY>]
    Enables option "double-click to run the command" and sets the double-click timing delay to <DELAY> (Default to 450 ms), if any.

-D|--display <NAME>
    Sets the display to use to <NAME>.

-W|--broken-wm
    Enables fix for "broken" window managers.

CONFIGURATION FILE FORMAT
The file passed in argument to option -C|--config must be to plain text format with entries to the format :
  [prefix.]key=value Commented lines, i.e. which start with a # - preceded or not by space(s) -, are ignored. Spaces at both side of loaded values are automatically removed. When there are more than one occurence of a given [prefix.]key, only the first value is loaded. The other values are ignored. key can be the name, without the dashes, of any of the supported options, with exception to help, fonts-info, display, and, broken-wm :
    Key | Type
    command | String
    icon | String
    desktop-file | String
    run-in-terminal | Boolean (1)
    preferred-terminals | String
    window-size | Integer
    icon-padding | Integer
    border-size | Integer
    background-color | String (2,3)
    hover-background-color | String (2,3)
    border-color | String (2,3)
    hover-border-color | String (2,3)
    icon-search-path | String
    desktop-file-search-path | String
    font-search-path | String
    tooltip-text | String
    tooltip-font | String
    tooltip-background-color | String (2,3)
    tooltip-foreground-color | String (2)
    tooltip-border-size | Integer
    tooltip-text-padding | Integer
    tooltip-show-delay | Integer
    tooltip-hide-delay | Integer
    icon-grayscale | Boolean (1)
    hover-icon-grayscale | Boolean (1)
    frame | String (2)
    icon-brightness | Float
    hover-icon-brightness | Float
    icon-contrast | Float
    hover-icon-contrast | Float
    icon-gamma | Float
    hover-icon-gamma | Float
    double-click | Integer
(1) Valid boolean values are: 1, true, on, yes, 0, false, off, no. (2) See section COLORS for informations about supported colors. (3) See section GRADIENTS for informations about supported gradients. prefix can be any string. When running the command 'wmalauncher --config F --prefix P', the value of each unprefixed key found in F is loaded first, then the value of each key with prefix P. This allows to have configurations files with a global section for visual settings, and multiple prefixed sections for the applications. Example :

  # Visual settings (global section)
  #
  window-size = 72
  icon-padding = 8
  border-size = 4
  background-color = Azure
  hover-background-color = Azure
  border-color = Dodger Blue
  hover-border-color = Deep Sky Blue
  icon-grayscale = on
  hover-icon-grayscale = off
  tooltip-show-delay = 250
  tooltip-hide-delay = 30000
  hover-icon-brightness = 0.25

  # section dedicated to firefox (prefix=firefox)
  #
  firefox.desktop-file = mozilla-firefox.desktop
  # section dedicated to thunderbird (prefix=thunderbird)
  #
  thunderbird.desktop-file = mozilla-thunderbird.desktop

  # section dedicated to htop (prefix=htop)
  #
  # this section does not make use of the .desktop file for
  # htop only to show how to manually configure wmalauncher in
  # case of application that require to be run in a terminal
  # window.
  #
  htop.command = /usr/bin/htop
  htop.icon = htop
  htop.run-in-terminal = true
  htop.preferred-terminals = /usr/bin/xfce4-terminal:/usr/bin/xterm
  htop.tooltip-text = Interactive Process Viewer

The configuration file above can be used to start 3 instances of wmalauncher respectively dedicated to launch the internet browser firefox, the mail client Thunderbird, and the process viewer Htop. Example :
  $ wmalauncher --config F --prefix firefox &
  $ wmalauncher --config F --prefix thunderbird &
  $ wmalauncher --config F --prefix htop &

COLORS
Any argument of type COLOR can be an X11 color name or an hex triplet to the format #rrggbb. For a list of X11 color names, see :
  https://en.wikipedia.org/wiki/X11_color_names

GRADIENTS
wmalauncher supports horizontal, vertical, and, diagonal gradients between two or more colors. Any color gradient must be specified by a string to the format :
    <TYPE>:<COLOR_1>,<COLOR_2>[,<COLOR_i> ...]

<TYPE> can be one of the following :
    • HGRAD : horizontal gradient from left to right.
    • VGRAD : vertical gradient from top to bottom.
    • DGRAD : diagonal gradient from top-left to bottom-right.
<COLOR_i> can be any of the supported colors. See section COLORS for more about supported colors. Examples:
    • HGRAD:Black,White
        Defines an horizontal gradient between Black and White colors.
    • VGRAD:Black,Red,White
        Defines a vertical gradient between Black and Red colors, then between Red and White colors.
    • DGRAD:Green,Blue
        Defines a diagonal gradient between Green and Blue colors.

ICON BRIGHTNESS/CONTRAST/GAMMA
As stated in Imlib2 documentation :
    • brightness values of 0 do not affect anything. -1.0 will make things completely black and 1.0 will make things all white. Values in-between vary brightness linearly.
    • Contrast of 1.0 does nothing. 0.0 will merge to gray, 2.0 will double contrast etc.
    • A gamma of 1.0 is normal linear, 2.0 brightens and 0.5 darkens etc. Negative values are not allowed.

AUTHORS
Sébastien Ballet <slacker6896@gmail.com>