PySide Decorators for Unity-like Context Menus

posted in: Uncategorized | 0

Today I wanted to share a recipe I’ve cooked up for creating menus in PySide. Having worked within the QWidgets framework of Qt for a while, I’ve always found the process of creating context menus and menu bars needlessly complex and error-prone. During my struggles trying to get hotkeys to work correctly and nested menus to build in the right order, I found myself reminiscing about Unity — in particular, its many intelligent API design choices made to aid with editor extensions. Fed up with the time I was spending on each new tool to get menu systems working correctly, I decided to develop a reusable library that would make me feel right at home.

The core problems I struggle with in PySide’s menu system are:

  • Creating hotkeys that actually fire QActions regardless of the state of the QMenu or QMenuItem
  • Building and managing nested QMenus
  • Flexibly specifying QMenuItem order in a QMenu
  • Creating callbacks for each QAction’s triggered signal

In PySide, I wanted to be able to do something like this Unity C# snippet:

// Add a new menu item with hotkey CTRL-A
[MenuItem("Tools/Create Actor %a")]
private static void CreateActor()
    // Do stuff...

And I ended up with this in:

# Adds a new menu item with hotkey CTRL-A
@AppContextMenu.register_action("Tools/Create Actor", shortcut="Ctrl+A")
def create_actor():
    # Do Stuff...

# App-specific code
class DemoMenuApp(QtGui.QMainWindow):
    def __init__(self, parent=None):
        super(DemoMenuApp, self).__init__(parent=parent)
        # Connect the context menu to tree_view_widget's right click

Not bad, eh? For reference, in PySide the context menu appears like:


A more complex example of a context menu created with this system.

What It Does

The register_action decorator handles building all QMenus and sub menus by parsing out /’s in your action name. It correctly hooks up QActions to fire when keyboard shortcuts are fired. It allows you to specify manual order with automatically placed separators by specifying a priority value. And lastly, it allows certain items to be enabled or disabled based by providing a validator callable.

The full source with the implementation of the BaseContextMenuTree class can be found on my GitHub. I’ve also included a mini PySide app to show different uses and demo its full feature set.


Implementing Unity’s API for creating menus was a neat exploration. In the process, I’ve come to terms with some of its design limitations. In both Unity’s and my implementation, it is not possible to pass arbitrary arguments into the decorated functions. Unity provides the user with some flexibility to unbox a generic “context object” into a specific type based on the context of the menu item. My system could be extended to do similar, but this relies on specific conventions and predetermined contexts. The system works best when functions are defined to operate on “static” objects and methods or where all the arguments required in the menu item’s action can be acquired from external systems.

Because Python evaluates its decorators as soon as the module is imported, all instances of my BaseContextMenuTree class must be declared in code as well. It is not possible to create new menu trees during runtime. However, it is possible to disable and enable certain menu items based on the “validator” parameter in the decorator. The validator is any callable that returns a boolean value. The callable is called each time the context menu is about to present itself. This allows for dynamic control of individual menu items. Validators offer more than enough freedom, so the limitation of not being able to create¬†new menu trees becomes much easier to cope with.

For further reading,¬†Unity’s documentation on its Menu Items system can be found here:

Leave a Reply