Basic Usage¶

A menu from with pymenu is made of two things:

The root menu entry: Menu entries are trees where each branch is a submenu and each leaf is an item.
Prompt: pymenu needs to know how to display the menu to the user. This is what a prompt is used to.

A silly command line file manager¶

Given the following directory structure:

.
├── demo.py
├── folder
│   ├── deepfile
│   └── subfolder
│       └── deeperfile
└── some_file

2 directories, 4 files

Here is a simple script that makes a file manager for browsing folder and printing the chosen file name.

#!/usr/bin/python

from pymenu import Menu, FileSystemMenuEntry, SimpleCommandPrompt

menu_entry = FileSystemMenuEntry('.')
prompt = SimpleCommandPrompt()

my_menu = Menu(menu_entry, prompt)

choice = my_menu.choose_value()
print(choice)

You can see it in action in the following animated gif.

Leveraging xdmenu¶

pymenu provides a simple API for building menus. It leverages xdmenu (must be installed) for delegating the display to an implementation of dmenu.

Lets change the above silly example in order to browse our files using dmenu.

#!/usr/bin/python

from pymenu import Menu, FileSystemMenuEntry
from pymenu.ext.xdmenu import DmenuPrompt

menu_entry = FileSystemMenuEntry('.')
prompt = DmenuPrompt()

my_menu = Menu(menu_entry, prompt)

choice = my_menu.choose_value()
print(choice)

Changes are emphasized. Simple enough, right?

Leveraging XDG¶

pymenu ships with an extension providing support for XDG menu definitons. This can be useful when using a simple window manager that is not XDG-compliant, such as Qtile and still wanting a XDG-based applications menu.

Here is a simple script for launching an application based on XDG menu definitons.

#!/usr/bin/python

from pymenu import Menu
from pymenu.ext.xdmenu import DmenuPrompt
from pymenu.ext.pyxdg import make_xdg_menu_entry, launch_xdg_menu_entry

menu_entry = make_xdg_menu_entry()
prompt = DmenuPrompt()

my_menu = Menu(menu_entry, prompt)

choice = my_menu.choose_value()
launch_xdg_menu_entry(choice)

Note

pymenu has all you need for launching default applications as per the XDG specification. Do not rely on this API, because it may (will) be moved to another package!

Performance Issues¶

pymenu do not implement lazy loading of menu entries. This means that a menu can use up a lot of RAM. Also, Creating a menu may take some time, especially when using XDG because of all the heavy XML files that needs parsing in the process.

Please help! See Contributing for more informations.