xdmenu package

Package main definition.

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

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

Bases: object

An extensible dmenu wrapper.

Parameters:
  • dmenu (str) – dmenu executable to use.
  • proc_runner (Callable[[list, list], str]) – a function that calls dmenu as a subprocess and returns the output. This defaults to a simple call to subprocess.Popen.
  • **kwargs – See xdmenu.BaseMenu.configure()
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']
configure(**kwargs)[source]

Set a value to any of the supported argument added.

Parameters:**kwargs – Keywords are mapped to the name of the argument, and the value is kept for a future call to dmenu.
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', '-> ']
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
version(dmenu=None)[source]

Return dmenu version string.

Parameters:dmenu (str) – dmenu executable to use. Defaults to the one configured in self.
Returns:The configured dmenu’s version string
Return type:str
class xdmenu.Dmenu(proc_runner=None, **kwargs)[source]

Bases: xdmenu.BaseMenu

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.
class xdmenu.Dmenu2(proc_runner=None, **kwargs)[source]

Bases: xdmenu.Dmenu

A wrapper for dmenu2.

This wrapper also supports all of xdmenu.Dmenu arguments in addition to the ones below.

Parameters:
  • dmenu (str) – See xdmenu.BaseMenu()
  • proc_runner (Callable[[list, list], str]) – See xdmenu.BaseMenu()
  • filter (bool) – activates filter mode. All matching items currently shown in the list will be selected, starting with the item that is highlighted and wrapping around to the beginning of the list. Equivalent for the -r command line option of dmenu2.
  • fuzzy (bool) – dmenu uses fuzzy matching. It matches items that have all characters entered, in sequence they are entered, but there may be any number of characters between matched characters. For example it takes txt makes it to *t*x*t glob pattern and checks if it matches. Equivalent for the -z command line option of dmenu2.
  • token (bool) – dmenu uses space-separated tokens to match menu items. Using this overrides fuzzy option. Equivalent for the -t command line option of dmenu2.
  • mask (bool) – dmenu masks input with asterisk characters (*). Equivalent for the -mask command line option of dmenu2.
  • screen (int) – dmenu apears on the specified screen number. Number given corresponds to screen number in X configuration. Equivalent for the -s command line option of dmenu2.
  • window_name (str) – defines window name for dmenu. Defaults to “dmenu”. Equivalent for the -name command line option of dmenu2.
  • window_class (str) – defines window class for dmenu. Defaults to “Dmenu”. Equivalent for the -class command line option of dmenu2.
  • opacity (float) – defines window opacity for dmenu. Defaults to 1.0. Equivalent for the -o command line option of dmenu2.
  • dim (float) – enables screen dimming when dmenu appers. Takes dim opacity as argument. Equivalent for the -dim command line option of dmenu2.
  • dim_color (str) – defines color of screen dimming. Active only when -dim in effect. Defautls to black (#000000). Equivalent for the -dc command line option of dmenu2.
  • height (int) – defines the height of the bar in pixels. Equivalent for the -h command line option of dmenu2.
  • xoffset (int) – defines the offset from the left border of the screen. Equivalent for the -x command line option of dmenu2.
  • yoffset (int) – defines the offset from the top border of the screen. Equivalent for the -y command line option of dmenu2.
  • width (int) – defines the desired menu window width. Equivalent for the -w command line option of dmenu2.
exception xdmenu.DmenuError(args, stderr)[source]

Bases: Exception

Something went wrong with dmenu.

exception xdmenu.DmenuUsageError(args, stderr)[source]

Bases: xdmenu.DmenuError

Some arguments to dmenu where invalid.