The menu plugin contains a set of menu items organized in a tree. The root node of the tree has no visual appearance, all other nodes are menu items, potentially visible.
Every menu item
At most one menu item is always selected, "no selection" is represented by the root node being selected (i.e. exactly one node in the tree is always selected). The selected menu item is marked by a yellow border, its ancestors by a darkened yellow border. The children of the selected item, or it and its siblings if it has no children, appear enlarged.
A menu item is visible iff it is not hidden and
Clicking on an enabled item (outside of the disclosure triangle, if any)
By consequence, these invariants hold if there are no individually expandable containers, and the SetSelected procedure is never called:
To visually group menu items, separators can be inserted. Separators are menu items too and have all the properties that ordinary menu items have, although most of them are meaningless.
The menu plugin has a string-valued property Partner, and every menu item has such a property too that is set to the plugin-wide partner at the time of its creation. Using the Cmd.RemovePartnerless procedure, all menu items whose partner is not a prefix of the current global partner can be removed.
To every tree node (every menu item as well as the root node), arbitrary user data can be attached in the form of INCO variables that live in the node's INCO folder. See the Cmd.CreateUserData and Cmd.DestroyUserData procedures.
If enabled, new items can be created and/or existing items modified by dragging-and-dropping INIX commands (in particular, variable assignments and procedure calls, e.g. from the INCO explorer) or stream and Python files onto the menu. Such items are editable by default. Applications can react to this using the OnItemDropped event action.
The sub-items of every tree node are numbered by a one-based index in the order in which they were added to the menu (which may be different from the order in which they are displayed). This index stays valid for the whole lifetime of the item, it is not renumbered when other items are added or removed. Using these indices, every node can be uniquely identified by its index path, a string that lists the indices of the item and all its ancestors. The index path of the root node is "i". The index path of the first top-level item is "i_1". The index path of the third subitem of the second subitem of the tenth top-level item is "i_10_2_3", etc. (The purpose of the "i" is to make the index path of the root node non-empty and therefore usable as an INCO item name.)
In addition, nodes can be referred to by their title path, which is the concatenation of the titles of the item and all its ancestors, separated by ".". The title path of the root node is "", the title path of a top-level item is equal to its title, the title path of subitem "B" of top-level item "A" is "A.B", etc. Because titles need not be unique, and may contain "." themselves, title paths are not unique in general.
In places where both index paths and title paths are accepted, the interpretation as an index path prevails. An attempt to interpret the given path as a title path is only made if it is not a valid index path.
Add a new menu item to Parent with the given Title and Action. Parent is either a title path or an index path. Position determines where to insert the new item. Positive values count from the beginning: 1 means "insert before the first item", 2 means "insert between the first and second item", etc. Zero and negative values count from the end: 0 means "append after the last item", -1 means "insert between the next-to-last and last item", etc. Container (bit 0 of Flags) determines whether the new item is a container. Non-container items are automatically changed to (non-expandable) containers when they get their first child attached, so this argument is only strictly necessary for distinguishing between non-containers and empty containers. Expandable (bit 1 of Flags) makes the item individually expandable (implies Container). Expanded (bit 2 of Flags) makes the item initially expanded (implies Container and Expandable). Bits 3, 7, 8, 9 of Flags are ignored, all further ones are reserved and should be kept at zero, for bits 4 to 6, 10 see below: AcceptsDroppedChildren, AcceptsDroppedReplacement, Editable, Hidden.
Returns the index of the new menu item on success or 4294967295 = 0xFFFFFFFF if the parent item was not found.
Add a separator item to Parent (index path or title path) at Position (interpreted as described above for AddMenu).
Returns the index of the new separator item on success or 4294967295 = 0xFFFFFFFF if the parent item was not found.
Create a user data variable in the folder corresponding to the given item (index path or title path). InitialValue is the string representation of the initial value and as such determines the type of the created variable (e.g. 3:l creates a uint32 variable with initial value 3). An empty string is accepted as a shorthand for "" to create an empty string variable. Properties of the variable (characteristics, combo list data etc.) are adjustable using PutVariable.
Variable names Title, Action, etc., described below, are not available for user data because they are already in use. Variable names OnExpand, KeyboardEquivalent, BackgroundColor, and Picture have a special meaning; such variables can be created, but should not be used for generic user data.
Return values: 0 = success, 1 = item not found, 2 = variable already exists, 3 = invalid variable name, 4 = invalid initial value.
Remove the given user data variable of the given item (index path or title path).
Return values: 0 = success, 1 = item not found, 2 = variable not found.
Enable (Enabled != 0) or disable (Enabled = 0) the menu item with the given index path or title path and all its sub-items. To enable or disable a menu item without affecting its sub-items, use the Enabled property.
Return values: 0 = success, 1 = item not found.
If an item is selected for editing, remove that selection. Events.OnCancelEdit will be called unless NoEvent is non-zero.
Return values: 0 = success, 1 = no item is being edited.
Find the item with the given title in the given parent item (index path or title path) and return its index. Returns 0 if not found.
Return the ComponentNo-th component (1-based) of the index path of the given item (index path or title path). If no item with the given path exists, or if ComponentNo is 0 or greater than the level of the item, returns 0. Example: Cmd.GetIndexPathComponent("i_2_5", 2:l) returns 5 (a contrived example, of course, as the procedure is typically used with title paths, not index paths).
Return the number of ancestors (depth in the menu tree, number of components of the index path) of the given item (index path or title path), or 0 if not found.
Return the number of sub-items of the given item (index path or title path), or 0 if not found.
Return the index of the first sub-item of the given item (index path or title path), or 0 if there is no such item or it has no sub-items. First here means in the order in which the items are displayed, not the order in which they were added. Used together with GetNextSiblingIndex() to iterate over the sub-items of a given item.
Return the index of the next sibling item of the given item (index path or title path) in the order in which they are displayed, or 0 if there is no such item or it is the last item in its parent. Used together with GetFirstSubmenuIndex() to iterate over the sub-items of a given item.
Return the position of the given item (index path or title path) in its parent in the order in which items are displayed, starting at 1, or 0 if there is no such item. Use this as the Position argument to AddMenu to insert a new item before the item given by Path, add 1 to insert the new item after it.
Pop up a contextual menu containing a representation of the menu hierarchy rooted at Path (index path or title path). This will call the OnExpand event action of non-expanded container items in an attempt to also reach dynamically built parts of the menu. If you need this, make sure that your OnExpand action is synchronous.
Return values: 0 = success, 1 = item not found, 2 = item has no sub-items.
Remove all menu items whose partner is not a prefix of the current partner (Prop.Partner).
Remove the menu item with the given index path or title path.
Return values: 0 = success, 1 = item not found.
Remove all menu items.
Remove all sub-items of the menu item with the given index path or title path.
Return values: 0 = success, 1 = item not found.
Equivalent to a click on the menu item with the given index path or title path: invokes its action if it has one, and makes it selected unless it is not a container and Prop.NonContainersSelectable is 1.
Return values: 0 = success, 1 = item not found.
Makes the menu item with the given index path or title path selected (unless it is not a container and Prop.NonContainersSelectable is 1), but does not invoke its action.
Return values: 0 = success, 1 = item not found.
The current partner.
The title path of the selected menu item (read-only).
The index path of the selected menu item (read-only).
Determines whether non-containers are selectable.
This event action is invoked when an editable item is selected for editing. Special constant #{ITEM_PATH} is expanded to the index path of the item.
This event action is invoked when an editable item returns from edit state, either because of a click anywhere on the menu or because of a call to Cmd.CancelEdit. Special constant #{ITEM_PATH} is expanded to the index path of the item.
This event action is invoked after a new item has been created or an item has been replaced using drag-and-drop. Special constant #{ITEM_PATH} is expanded to the index path of the item and #{REPLACED} to 0 for creation and 1 for replacement.
A folder that contains another folder for each menu item, named by its index path.
A folder that contains properties of the respective menu item.
The title of the menu item.
The action of the menu item (a <command with placeholders> as defined in the INIX syntax spec). Relative INCO paths in the action are resolved relative to the menu item's folder, so that you can refer e.g. to the item's title by ${.Title}, to the folder name (index path) by #{PLUGIN_NAME} (which may look a bit misleading in this context), or to a property of the menu plugin by ${<.<.Prop.Selected}.
The value of Prop.Partner at the time of creation of this item was copied into this variable. Used by Cmd.RemovePartnerless.
Specifies what kind of check mark, if any, is displayed by the menu item. Values: 0 = no mark, 1 = check mark, 2 = dash.
Whether the menu item is a container. See Overview.
Whether the menu item is individually expandable. See Overview.
Whether the menu item stays expanded even when it is not selected (or an ancestor of the selected item). See Overview.
Determines whether the menu item reacts to the mouse. To set this for several items at once, use Cmd.Enable().
If this flag is set, text and files can be dragged between the sub-items of the menu item to create new sub-items that perform INCO variable assignments or procedure calls or execute stream files or Python scripts.
If this flag is set, text and files can be dragged onto the menu item to replace its title and action by the same ones as a new dropped item would use. Other properties stay unmodified. Set by default for items created by drag-and-drop (see AcceptsDroppedChildren), unset for all others.
Marks the item as editable (see Overview). Set by default for items created by drag-and-drop (see AcceptsDroppedChildren), unset for all others.
If this flag is set, the item is never shown.
Indicates whether this item is a separator or an ordinary menu item (read-only).
If this flag is set, the keyboard equivalents are always visible.
Indicates whether this item is a container and is currently expanded, or would be, if it was visible (read-only). Reasons for being expanded include:
This variable is not present by default, it must be created using Cmd.CreateUserData() if needed. This action (a <command with placeholders> as defined in the INIX syntax spec) is performed whenever the menu item changes from collapsed to expanded (specifically, on rising edges of ActuallyExpanded). Relative INCO paths in the action are resolved relative to the menu item's folder (see Action for examples). Special constant #{REASON} is set to a string explaining the reason for the call. Possible values are "select" (manual selection, action will be invoked), "setselected" (programmatic selection, without action), "disclosure" (disclosure triangle clicked), "inco" (Items.<i>.Expanded set in INCO tree), "popup" (part of Cmd.PopUpMenu). This action may also be called by Cmd.PopUpMenu().
This variable is not present by default, it must be created using Cmd.CreateUserData() if needed. This string is displayed on the menu item whenever the Ctrl or Alt keys are pressed. If the string starts with "global ", this prefix is removed and the rest of the string is shown in a different color.
This is solely a display feature, the functionality of keyboard equivalents is to be obtained from the HotKey service plugin.
This variable is not present by default, it must be created using Cmd.CreateUserData() if needed. If present, the menu item, in idle state, is drawn in the color specified here instead of the default color. Syntax is 0xBBGGRR (same as Prop.Look.BackColor).
This variable is not present by default, it must be created using Cmd.CreateUserData() if needed. Specify an image file here to be displayed on the menu item, either as an absolute path or as a path relative to the _Pictures_ folder of the plugin's IGD location. Grayscale images without alpha channel are adapted to the text color of the menu item, with white converted to foreground and black to background.
User data for the respective item.
1.8.8