SyMenu Class Reference

< Previous | | Manuals Home | Boris FX | Next >

SyMenu Class Reference

The SyMenu class represents a menu, including the main top menu, any of the top-level menus such as "File", "Track", "Help", etc, or any submenu below that. See also Menu Operations in the SyLevel Class Reference.

WARNING: Python menu objects are represented as a list of submenu operations, for example: start at the top, go into" Script", then go into "Script bar". The menu is searched upon each use. This is a good approach since menus are frequently rebuilt and the physical menu storage may change even if it is apparently the same menu. The representation is problematic when a submenu name changes or if there are multiple submenus with the same name. In that case you can recreate the object, or build it with SubMenuByPos originally.

The menu operations are designed to work with SynthEyes existing menu operations. SynthEyes can rebuild menus at any time; if you aren't careful your new submenus or menu items will be deleted as part of a rebuild, or worse, your additions may compromise SynthEyes's ability to locate the standard items, resulting in malfunction.

Never delete, check, or gray a submenu or menu item you didn't create!

Do not try to check or disable existing SynthEyes menu items, or try to click grayed-out menu items. Attempting to do so will nearly always create problems (which may not be immediately obvious) and will not work as expected. Use Click operations instead, which emulate valid user actions.

For example, you might have something like this:

nu = hlev.MainMenu().AddSubMenu(hlev.MainMenu().Count()+1, "Shotgun") nu.AddMenuItem(0, "Test1", 997)

nu.AddMenuItem(1, "Test2", 998)

nu.AddMenuItem(2, "Test3", 999)

To be usable, the example command identifiers 997-999 must be replaced with live numbers taken from other menu items, for example those assigned to some dummy script entries buried deep in the script menu.

Count() The number of items in the menu

SubMenuByName(nm) This menu's submenu with the given name, as evaluated

at the time of use (more robust).

SubMenuByPos(idx) This menu's submenu at the given index, as evaluated at

the time of use (if needed).

Exists() Returns true if this submenu actually exists at present.

HasSubMenu(idx) Returns true if there is a submenu at this index within the

menu.

AddSubMenu(idx, nm) Add the named submenu at the given index. Extreme care

must be taken to avoid interfering with SynthEyes's dynamic menu-building activities.

AddMenuItem(idx, nm, cmdid) Add the named menu item to the submenu at the given

index. Extreme care must be taken to avoid interfering with SynthEyes's dynamic menu-building activities. When clicked, the menu item will trigger the action determined by

the given cmdid, which must almost always be obtained by reading it from some existing menu item!

DeleteByID(nm) Delete the item with this command ID.

DeleteByPos(idx) Delete the item/submenu at this index.

PosByName(nm) Return the index of the item with the given name in this menu, or -1.

IDByName(nm) Return the command ID of the menu item with this name.

IDByPos(idx) Return the command ID of the menu item at this index. NameByPos(idx) Return the item or submenu name at the given index. NameByID(cmdid) Return the name of the item with the given command id. SetNameByPos(idx, nm) Sets the item or submenu name at the given index.

SetNameByID(cmdid, nm) Sets the name of the item with the given command id.

IsCheckedByPos(idx) Returns true if the item at this index is checked.

IsCheckedByID(cmdid) Returns true if the item with this command id is checked.

SetCheckedByPos(idx, v) If v is nonzero, check the menu item at this index. Change

only your own menu items, never SynthEyes's!

SetCheckedByID(cmdid, v) If v is nonzero, check the menu item with this command id.

Change only your own menu items, never SynthEyes's!

IsGrayedByPos(idx) Returns true if the item at this index is grayed, ie

unclickable. Don't click grayed items!

IsGrayedByID(cmdid) Returns true if the item with this command id is grayed, ie

unclickable. Don't click grayed items!

SetGrayedByPos(idx, v) If v is nonzero, gray (disable0 the menu item at this index.

Change only your own menu items, never SynthEyes's!

SetGrayedByID(cmdid, v) If v is nonzero, gray (disable) the menu item with this

command id. Change only your own menu items, never SynthEyes's!


©2023 Boris FX, Inc. — UNOFFICIAL — Converted from original PDF.