Usage

xdmenu is a wrapper API for dmenu. The original use case of xdmenu was to ease the integration of dmenu with Qtile, a window manager written in Python.

The simplest possible usage of this wrapper is through the xdmenu.dmenu() function. Here is an example usage:

>>> from xdmenu import dmenu
>>> dmenu(['foo', 'bar'])  # shows a menu window with choices on one line
['bar']                    # the user picked 'bar'
>>> dmenu(['foo', 'bar'], lines=2)  # shows a menu window with two lines
['foo']                             # the user picked 'foo'
xdmenu.dmenu(choices, dmenu=None, **kwargs)[source]

Run dmenu with configuration provided in **kwargs.

Parameters:
Returns:

All the choices made by the user.
Return type:

list

See also

xdmenu.BaseMenu.run()

The xdmenu package also provides the xdmenu.Dmenu class. This class can be provided with default configuration values to customize the behavior of dmenu.

class xdmenu.Dmenu(proc_runner=None, **kwargs)[source]

An extensible dmenu wrapper that already supports all usual arguments.

Parameters:
  • dmenu (str) – See xdmenu.BaseMenu()
  • proc_runner (Callable[[list, list], str]) – See xdmenu.BaseMenu()
  • bottom (bool) – dmenu appears at the bottom of the screen. Equivalent for the -b command line option of dmenu.
  • grab (bool) – dmenu grabs the keyboard before reading stdin. This is faster, but will lock up X until stdin reaches end-of-file. Equivalent for the -f command line option of dmenu.
  • insensitive (bool) – dmenu matches menu items case insensitively. Equivalent for the -i command line option of dmenu.
  • lines (int) – dmenu lists items vertically, with the given number of lines. Equivalent for the -l command line option of dmenu.
  • monitor (int) – dmenu is displayed on the monitor number supplied. Monitor numbers are starting from 0. Equivalent for the -m command line option of dmenu.
  • prompt (str) – defines the prompt to be displayed to the left of the input field. Equivalent for the -p command line option of dmenu.
  • font (str) – defines the font or font set used. Equivalent for the -fn command line option of dmenu.
  • normal_bg_color (str) – defines the normal background color. #RGB, #RRGGBB, and X color names are supported. Equivalent for the -nb command line option of dmenu.
  • normal_fg_color (str) – defines the normal foreground color. Equivalent for the -nf command line option of dmenu.
  • selected_bg_color (str) – defines the selected background color. Equivalent for the -sb command line option of dmenu.
  • selected_fg_color (str) – defines the selected foreground color. Equivalent for the -sf command line option of dmenu.
  • windowid (str) – embed into windowid.

Run dmenu using xdmenu.BaseMenu.run() which all child class should have.

BaseMenu.run(choices, **kwargs)[source]
Parameters:
  • choices (list) – Choices to put in menu
  • **kwargs – See xdmenu.BaseMenu.configure(), except that values are no kept for a later call to dmenu

Examples

>>> # We mock the _run_dmenu_process function for this example
>>> # to be runnable even if dmenu is not installed
>>> # The mock mimics a user choosing the first choice
>>> m = Dmenu(proc_runner=_mock_dmenu_process)
>>> m.run(['foo', 'bar'])
['foo']
Returns:All the choices made by the user. In order to have multiple results, a custom build of dmenu may be required since the original version may not support selecting many items.
Return type:list

If you only want to get the command line arguments, simply use xdmenu.BaseMenu.make_cmd()

BaseMenu.make_cmd(**kwargs)[source]

Build the list of command line arguments to dmenu.

Parameters:**kwargs – See xdmenu.BaseMenu.configure(), except that values are no kept for a later call to dmenu
Returns:
List of command parts ready to sead to
subprocess.Popen
Return type:list

Examples

>>> menu = Dmenu()
>>> menu.make_cmd()
['dmenu']
>>> menu.make_cmd(bottom=True)
['dmenu', '-b']
>>> menu.make_cmd(lines=2, prompt='-> ',)
['dmenu', '-l', '2', '-p', '-> ']

Since xdmenu is intended to be extensible, you can add supported options using xdmenu.BaseMenu.add_arg()

BaseMenu.add_arg(name, converter, default=None)[source]

Extend this wrapper by registering a new dmenu argument.

You can also use this to change the behavior of existing arguments.

Parameters:
  • name (str) – The name of the supported keyword argument for this wrapper.
  • converter (Callable[[Any], Iterable]) – A function that converts the configured value to a list of command line arguments to dmenu.
  • default (Optional[Any]) – The default configured value.

Examples

Let’s wrap the usage of a -foo argument that a dmenu fork could possibly support.

>>> def to_bottom(arg):
...     return ['-foo'] if arg else []
>>> menu = Dmenu()
>>> menu.add_arg('foo', to_bottom, default=False)
>>> menu.make_cmd()
['dmenu']
>>> menu.make_cmd(foo=True)
['dmenu', '-foo']

xdmenu also provides a wrapper for dmenu2. See xdmenu.Dmenu2.