CTRLMENU(1)                 General Commands Manual                CTRLMENU(1)

NAME
     ctrlmenu – unified menu system for X11

SYNOPSIS
     ctrlmenu [-dit] [-a keysym] [-r keychord] [-x buttonspec] [file]

DESCRIPTION
     ctrlmenu is a launcher and menu system for X.  It reads a text file
     describing entries in a hierarchical menu, and creates input methods for
     selecting and entering those entries.  When an entry is selected, its
     respective command is run.

     If no file argument is given, or if it is a hyphen “-”, ctrlmenu reads
     from standard input.

     The options are as follows

     -a keysym
             Enable the altkey input.  The argument keysym must be the key
             symbol for the alt key (none by default).  Despite its name, this
             key can be any key.  See the section USAGE for more information
             on the alt key.

     -d      Enable the dockapp.  This option makes show a docked menu on the
             window manager's dock.  See the section USAGE for more
             information on the docked menu.

     -i      Match entries case insensitively on the runner.

     -t      Enable tornoff menus.  This option can only be used together with
             -d and/or -x.  See the section USAGE for more information on the
             tornoff menus.

     -r keychord
             The argument keychord must be the keychord to invoke the runner
             (A-space, by default).  The keychord must be a keysym, prefixed
             with C- (for Control), S- (for Shift), A- (for Alt), W- (for
             Super/Win).  See the section USAGE for more information on the
             runner.

     -x buttonspec
             Enable root menu.  This option makes ctrlmenu show the menu when
             clicking on the desktop or clicking anywhere with a given
             modifier.  The argument buttonspec must be an optional button
             number (or nothing for button 3, the right button), prefixed with
             C- (for Control), S- (for Shift), A- (for Alt), W- (for
             Super/Win), N- (for no modifier, making any press spawn the
             menu), or nothing (for no modifier, making only presses to the
             root window spawn the menu).  The button spec can be also
             suffixed with the letter P to indicate that the click to the root
             window should be passed to other clients.  See the section USAGE
             for more information on the root menu.

     Each line read from the specified file or stdin can be a separator, a
     terminal entry, a common meta-entry, or a pipe meta-entry.  Any blank
     around an entry is ignored.  The format of an entry is as follows:

           ENTRY       := SEPARATOR | TERMINAL | META | PIPE
           SEPARATOR   := "--\n"
           TERMINAL    := NAME ["--" COMMAND] "\n"
           META        := NAME "{\n" ENTRIES... "}\n"
           PIPE        := NAME "--" COMMAND "{\n" SCRIPT "}\n"

     Separator
             A separator is an anonymous, non-selectable entry in the menu.
             Separators are composed by a line with only two dashes in it.

     Terminal Entry
             A terminal entry is a line composed by a name, and an optional
             command after two dashes.  A terminal entry appears as an entry
             in the menu which, when selected, runs its command (or its name,
             if the command is not provided).  A terminal entry ends in a
             newline.

     Common Meta-Entry
             A common meta-entry is a line composed by a name followed by an
             open curly bracket, then a sequence of other entries, followed by
             a close curly bracket.  A common meta-entry appears as an entry
             in the menu which, when selected, opens a submenu.  A common
             meta-entry ends in a newline.

     Pipe Meta-Entry
             A pipe meta-entry is a line composed by a name followed two
             dashes and a command.  Then a shell script between curly braces.
             A pipe meta-entry appears as an entry in the menu which, when
             selected, runs the corresponding shell script whose output is
             read for menu entries.  Only terminal entries and separators can
             be read from the running script.  A pipe meta-entry ends in a
             newline.

     The name can end in a string between braces, which are used for
     extensions (the only extensions supported are keybinding, descriptions
     and icons).  The format of a name is as follows:

           NAME        := LABEL [ "[" LIST "]" ]
           LIST        := | EXTENSION ":" LIST
           EXTENSION   := KEYBINDING | ICON | DESCRIPTION
           ICON        := "#" PATH
           KEYBINDING  := "!" ("S-" | "C-" | "A-" | "W-") KEYSYM
           DESCRIPTION := STRING

     The LABEL is the string that will appear in the menu.  The label can
     contain a underscore (“_”) before a character to indicate that this
     character should be underlined on the menu, and that pressing the key
     corresponding to that character selecs the item.  The extension list is a
     colon-separated list of extensions between braces.

     An icon is the path to an xpm (pixmap) icon to be displayed in the menu
     before the label.  The path must be prefixed with a “#” character to
     indicate that it is the path to an icon.

     A keybinding is a sequence of modifiers and a key symbol to be bound for
     the menu entry.  The keybinding must be prefixed with a “!” character to
     indicate that it is a keybinding.  When the corresponding key is pressed
     along with the given modifiers, the respective entry is selected.  A
     keybinding has the following form.  An “S-” prefix indicates that the
     Shift key modifier is active.  An “C-” prefix indicates that the Control
     key modifier is active.  An “A-” prefix indicates that the Alt key
     modifier is active.  An “W-” prefix indicates that the Super (Also known
     as “windows key”) key modifier is active.  The keysym that forms the
     ending of the keybinding is one of the keysyms listed at the
     /usr/X11R6/include/X11/keysymdef.h file (/usr/include/X11/keysymdef.h in
     some systems.)

     The description is a comment for the item to be piped to the runner
     application.  The description has no prefix and should be the last
     extension on the extension list.

USAGE
     The following input methods are provided by ctrlmenu

     Docked Menu
             The docked menu is an always-visible dockapp window that displays
             a list of menus on the window manager's dock.  The docked menu is
             only displayed when using the -d command-line option.  The docked
             menu only works on window managers that docks dockapps, such as
             fluxbox(1).

     Root Menu
             The root menu is a menu that pops up when the user right-clicks
             the desktop.  The root menu is only displayed when using the -x
             command-line option.

     Tornoff Menu
             A tornoff menu is a menu that appears as a regular window.  A
             tornoff menu is created after selecting the dashed line at the
             top of a popped up menu.  This dashed line only appears when
             using the -t command-line option.

     Alt Key Sequences
             Each menu entry can be bound to a character.  After pressing the
             alt key (set with the -a command-line option), it is possible to
             navigate the menus by pressing the letters of entries in
             sequence.

     Accelerator key chords
             Each menu entry can be bound to a key chord.  Pressing a key
             chord enters the entry bound to it.

     Runner  The runner is an interactive filter program (like dmenu(1) or
             xprompt(1)) that lists and filters its input as the user types
             for an entry.  The runner opens ctrlmenu by pressing a key chord
             specified with the -r command-line option.

     Any menu (either the docked menu, the root menu, a tornoff menu or a
     popped up menu) can be browsed with the mouse, and each entry can then be
     clicked to be selected.  After a submenu is opened, they can be navigated
     either using the mouse or one of the following keys:

     Home    Select the first item in the menu.

     End     Select the last item in the menu.

     Down, Tab
             Cycle through the items in the regular direction.

     Up, Shift-Tab
             Cycle through the items in the reverse direction.

     Right, Enter
             Select the highlighted item.

     Left    Go to the parent menu.

     Esc     Close any open pop up menu.

RESOURCES
     ctrlmenu understands the following X resources.

     ctrlmenu.faceName
             The typeface to write text with.

     ctrlmenu.menu.background, ctrlmenu.text.background
             The colors of the background of the menu and the runner.

     ctrlmenu.menu.foreground, ctrlmenu.text.foreground
             The colors of the foreground of the menu and the runner.

     ctrlmenu.menu.selbackground, ctrlmenu.text.selbackground
             The colors of the background of the menu and the runner for
             selected entries.

     ctrlmenu.menu.selforeground, ctrlmenu.text.selforeground
             The colors of the foreground of the menu and the runner for
             selected entries.

     ctrlmenu.menu.altforeground, ctrlmenu.text.altforeground
             The colors of the foreground of the menu and the runner for
             alternate (comment) text.

     ctrlmenu.menu.altselforeground, ctrlmenu.text.altselforeground
             The colors of the foreground of the menu and the runner for
             alternate (comment) text in selected entries.

     ctrlmenu.topShadow
             The color of the top shadow around the menu

     ctrlmenu.bottomShadow
             The color of the bottom shadow around the menu.

     ctrlmenu.itemHeight
             The height in pixels of each item in the menus.  Default is 24
             pixels.

     ctrlmenu.iconSize
             The size in pixels of the icon of items.  Default is 16 pixels.

     ctrlmenu.shadowThickness
             Thickness of the 3D shadow effect.

     ctrlmenu.gap
             The gap, in pixels, between the menus.

     ctrlmenu.maxItems
             The maximum number of items to be displayed in a menu.  If a menu
             has more items than that value, the menu will feature arrow
             buttons for scrolling.

     ctrlmenu.alignment
             If set to left, center, or right, text is aligned to the left,
             center, or right of the menu, respectively.  By default, text is
             aligned to the left.

ENVIRONMENT
     The following environment variables affect the execution of ctrlmenu.

     DISPLAY
             The display to start ctrlmenu on.

     ICONPATH
             A colon-separated list of paths to look for icons.

EXAMPLE
     Consider the following script:

           #!/bin/sh

           ctrlmenu -e -x "W-3" <<EOF
           _Applications {
                   _Web Browser [#./icons/web.xpm]  -- firefox
                   _Image Editor [#./icons/web.xpm] -- gimp
           }
           _Terminals {
                   Terminal (_xterm) [!A-T] -- xterm
                   Terminal (_urxvt) [!A-U] -- urxvt
                   Terminal (_st)    [!A-S] -- st
           }
           --
           _Users -- finger "" {
                   sed 's/:.*//' /etc/passwd
           }
           _System {
                   _Shutdown  -- poweroff
                   _Reboot    -- reboot
           }
           EOF

     In this example, ctrlmenu is invoked with the -e command-line option,
     which makes the command of the selected entry to be run in sh(1).  It is
     also invoked with the -x W-3 command-line option, which makes the main
     menu pop up when right-clicking on the root window (ie', the desktop), or
     when right-clicking anywhere with the Win (Super) key.

     This example creates a menu with four entries: “Applications”,
     “Terminal”, “Users”, and “System”.  The first two entries are separated
     from the last two with a separator.

     The underline on the names of those entries indicates that pressing the
     key corresponding to the character after the underline selects the item.
     For example, pressing “S” opens the “System” submenu, and then pressing
     “R” selects the “Reboot” entry.

     On the “Applications” menu, the entries have icons specified between
     braces and after the “#” character.

     On the “Terminals” menu, the entries have keybindings specified between
     braces and after the “!” character.  That means that, for example,
     pressing Alt-T opens xterm(1).

     The “users” menu is a pipe meta-entry.  Selecting it opens a menu whose
     entries are read from the sed(1) command, which prints the user field of
     the /etc/passwd file.  Selecting an entry in this menu fingers the
     corresponding user.

OpenBSD 7.2                   September 28, 2022                   OpenBSD 7.2