Skip to content

Quick start

hannes edited this page Mar 4, 2023 · 12 revisions

1. Installation

PIP install the UniMenu python module to your Python path.

pip install unimenu

2. Create menu

Once installed, you can start making menus.

💻a. from a dict

The dict is the most basic setup, and is mainly used to load configs. If you want to make a menu in code, use MenuNodes instead. Run this code sample to create a new menu from a dict : my menu/test

import unimenu
data = {"label":"my menu", "items": [{"label": "hi", "command": 'print("hi")'}]}
unimenu.setup(data)

💻b. from MenuNodes

unimenu.Node lets you build and manipulate ever part of a menu hierarchy. When ready, you can call setup() to create the menu in the app. Or maybe you don't want to make a menu, but just load the data in a custom tool with my_root_node.all_command_nodes, or just get the name node.label

import unimenu
menu = unimenu.Node(label="my menu")  # create a menu
item = unimenu.Node(label="hi", command='print("hi")')  # create a menu item
menu.items.append(item)  # add the item to the menu
menu.setup()  # setup the menu in the app, parented by default to the main menu bar

📝c. from configs

A config can be of type YAML or JSON, the load_config method will autodetect the type. unimenu.setup auto detects when you parse a config of YAML or JSON. Or load a custom config type in a dict, and create the menu from that dict.

items:
  - label: my menu
    items:
      - label: print hi
        command: print("hi")
import unimenu
unimenu.setup("path/to/config.yaml")

📂d. from a folder/python module

UniMenu can automatically create a menu from a folder with python files. Great for a folder full of tools that need launching when clicking a button. This can save time, but gives less control as a config or a menu from classes. But you could load the folder in a node-tree with unimenu.load_module() and then manipulate the nodes.

  1. Ensure the folder is importable as a module (your module should be in the sys.path & contain an __init__ file)
  2. Create a method in all submodules with the same name, e.g. def show()

The folder needs to be a python module, importable from PATH & have an __init__ file

import unimenu
# import all tools from the cool_tools folder
unimenu.setup_module("cool_tools", function_name="show"")  

menu attributes

So you now know how to make a basic menu. But what else can you do with a config or a MenuNode?

A node and a config follow the same structure. e.g.

item = unimenu.Node(label="print hi", command='print("hi")')

is the same as

- label: print hi
  command: print("hi")

accessing data is also very similar

label = item.label  # get label from a menunode
label = config.get("label")  # get label from a config dict

A node can have

  • label
  • id: a UNIQUE id
  • command
  • icon
  • tooltip
  • separator
  • parent_path: the parent to create the menu under
  • kwargs: custom data passed to the creation of the menu node in the app. e.g. to pass additional kwargs to menuItem in Maya, or QAction in Qt
  • data: custom data added to the node, e.g. for tags or categories. It's recommended to use a dict, so you can add more than 1 custom data entry. e.g.
node.data = {}
node.data["category"] = "animation"
node.data["tag"] = "3D"

TODO

[!TODO] TODO parent through parent kwarg / config

import unimenu

menu = unimenu.Node(label="my menu")  
item = unimenu.Node(label="print hi", 
                    command='print("hi")',
                    parent_path="UNIMENU_MT_my_menu")  
menu.setup()  # setup the menu
Clone this wiki locally