Commands and Command Lists
PBCommandList
Opaque object handle: A list of commands to be displayed in a pop-up menu, toolbar or similar.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBCommandListRetain; to decrement the reference count, call PBCommandListRelease. These functions are thread-safe.
PBCommandID
Enumeration/bitset of type int64_t: An identifier used to represent a command. Negative values are reserved by the system. You should keep the command IDs stable across versions of your application, since accessibility and automation tools may remember specific IDs. Within a window, each ID can only be used once. Generally, APIs that take a command ID will silently ignore unregistered IDs.
Constants
PBCommandID_SELECT_ALL
PBCommandID_SELECT_ALL = 0xFFFFFFFFFFFFF000
Select all the items or data in the focused element. See PBElementSetCapturedCommandDisabled.
PBCommandID_CUT
PBCommandID_CUT = 0xFFFFFFFFFFFFF001
Copy the selection in the focused element to PBClipboardID_PRIMARY and delete it from the original container. See PBElementSetCapturedCommandDisabled.
PBCommandID_COPY
PBCommandID_COPY = 0xFFFFFFFFFFFFF002
Copy the selection in the focused element to PBClipboardID_PRIMARY. See PBElementSetCapturedCommandDisabled.
PBCommandID_PASTE
PBCommandID_PASTE = 0xFFFFFFFFFFFFF003
Paste the contents of PBClipboardID_PRIMARY into the focused container. See PBElementSetCapturedCommandDisabled.
PBCommandID_CLOSE_WINDOW
PBCommandID_CLOSE_WINDOW = 0xFFFFFFFFFFFFF004
Requests the window to close. This is equivalent to the user clicking the window's close button.
PBCommandID_DELETE
PBCommandID_DELETE = 0xFFFFFFFFFFFFF005
Delete the selection in the focused element. See PBElementSetCapturedCommandDisabled.
PBCommandID_MAXIMIZE_WINDOW
PBCommandID_MAXIMIZE_WINDOW = 0xFFFFFFFFFFFFF006
Maximizes the window.
PBCommandID_MINIMIZE_WINDOW
PBCommandID_MINIMIZE_WINDOW = 0xFFFFFFFFFFFFF007
Minimizes the window.
PBCommandID_RESTORE_WINDOW
PBCommandID_RESTORE_WINDOW = 0xFFFFFFFFFFFFF008
Restores the window from the maximized or minimized states.
PBCommandID_MOVE_WINDOW_LEFT
PBCommandID_MOVE_WINDOW_LEFT = 0xFFFFFFFFFFFFF009
Moves the window to the left.
PBCommandID_MOVE_WINDOW_RIGHT
PBCommandID_MOVE_WINDOW_RIGHT = 0xFFFFFFFFFFFFF00A
Moves the window to the right.
PBCommandID_CLOSE_ALL_WINDOWS
PBCommandID_CLOSE_ALL_WINDOWS = 0xFFFFFFFFFFFFF00B
Request all open windows to close.
PBCommandID_NEW
PBCommandID_NEW = 0xFFFFFFFFFFFFF00C
Create a new file for editing. See PBWindowUseAsFileEditor.
PBCommandID_OPEN
PBCommandID_OPEN = 0xFFFFFFFFFFFFF00D
Open a file for editing. See PBWindowUseAsFileEditor.
PBCommandID_SAVE
PBCommandID_SAVE = 0xFFFFFFFFFFFFF00E
Save a modified file. See PBWindowUseAsFileEditor.
PBCommandID_SAVE_AS
PBCommandID_SAVE_AS = 0xFFFFFFFFFFFFF00F
Save modified changes to a different file, and start editing that file. See PBWindowUseAsFileEditor.
PBCommandID_REVEAL_FILE
PBCommandID_REVEAL_FILE = 0xFFFFFFFFFFFFF010
Reveal the file being edited in the file manager.
PBCommandID_COMMAND_PALETTE
PBCommandID_COMMAND_PALETTE = 0xFFFFFFFFFFFFF011
Toggle the window's command palette.
PBCommandID_UNDO
PBCommandID_UNDO = 0xFFFFFFFFFFFFF012
Undo the most recent action.
PBCommandID_REDO
PBCommandID_REDO = 0xFFFFFFFFFFFFF013
Redo the last action that was undone.
PBCommandFlags
Enumeration/bitset of type uint32_t: Flags controlling the behavior of a command.
Constants
PBCommand_DISABLED
PBCommand_DISABLED = 1<<0
Indicates the command is not available and prevents it from being invoked. If this flag is not set, the command is enabled. This can be later modified with PBWindowSetCommandDisabled.
PBCommand_CHECKED
PBCommand_CHECKED = 1<<1
Requires PBCommand_IS_CHECKABLE. Indicates the command is checked. The user will likely expect invoking the command to toggle its check, which can be done with PBWindowSetCommandChecked.
PBCommand_IS_CHECKABLE
PBCommand_IS_CHECKABLE = 1<<2
The command represents a toggleable state, which is given by PBCommand_CHECKED.
PBCommandListItemFlags
Enumeration/bitset of type uint32_t: Flags controlling the behavior of an item added to a specific command list. Some command list representations (pop-up menus, toolbars, etc) will only support some of these flags.
Constants
PBCommandListItem_SHOW_IF_ALT_HELD
PBCommandListItem_SHOW_IF_ALT_HELD = 1<<0
The item is only to be shown if the user is holding the alt modifier key.
PBCommandListItem_HIDE_IF_ALT_HELD
PBCommandListItem_HIDE_IF_ALT_HELD = 1<<1
The item is only to be shown if the user is not holding the alt modifier key.
PBCommandListItem_ALIGN_AT
PBCommandListItem_ALIGN_AT = 1<<2
See PBPopUpMenu_AT_ITEM.
PBCommandListItem_ICON_ONLY
PBCommandListItem_ICON_ONLY = 1<<3
Only show the icon registered for the command rather than its label. Supported in toolbars.
PBCommandPickerFlags
Enumeration/bitset of type int32_t:
Constants
(none)
PBActionHandler
Callback: Instructs the application to invoke an action.
Syntax (C/C++)
void PBActionHandler(PBWindowRef window, PBModifierKeys modifiers,
PBUserContext context);
You can create a callback of this type from a function pointer with the above signature using PBActionHandler_Make
.
Syntax (Python)
ActionHandler(window, modifiers, context)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the action is registered.
[in] modifiers (PBModifierKeys): If the action was triggered by a mouse click (or similar), then this contains the bitset of modifier keys that were held at the time of the click. If the action was triggered by some other method (such as a keyboard shortcut), then this is 0.
[in] context (PBUserContext): The context associated with the action, as passed to PBWindowRegisterAction or similar.
See Also
PBSubMenuHandler
Callback: Instructs the application to show a sub pop-up menu.
Syntax (C/C++)
PBCommandListPtr _Nullable PBSubMenuHandler(PBUserContext context);
You can create a callback of this type from a function pointer with the above signature using PBSubMenuHandler_Make
.
Syntax (Python)
SubMenuHandler(context) -> (commandList)
Parameters and Return Values
[in] context (PBUserContext): The context associated with the sub menu, as passed to PBCommandListAddSubMenu.
[out] commandList (nullable owned PBCommandList): The command list for the sub menu, or null if it could not be created.
PBCommandListCreate
Function: Create an empty command list.
Syntax (C/C++)
PBCommandListPtr _Nullable PBCommandListCreate(PBWindowRef window);
Syntax (Python)
CommandListCreate(window) -> (commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window from which the commands are taken. This determines how the PBCommandID values are interpreted when passed to PBCommandListAddCommand and similar.
[out] commandList (nullable owned PBCommandList): An empty command list, or null if there was insufficient available memory.
See Also
- PBCommandListAddCommand
- PBCommandListAddAction
- PBWindowPopUpMenu
- PBWindowSetToolbar
- PBWindowSetMenuBarItems
PBCommandListCreateEditMenu
Function: Create a copy of the standard Edit menu.
Syntax (C/C++)
PBCommandListPtr _Nullable PBCommandListCreateEditMenu(PBWindowRef window);
Syntax (Python)
CommandListCreateEditMenu(window) -> (commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window from which the commands are taken.
[out] commandList (nullable owned PBCommandList): The new copy of the Edit menu, or null if there was insufficient available memory.
See Also
PBCommandListCreateWindowMenu
Function: Create a copy of the standard Window menu.
Syntax (C/C++)
PBCommandListPtr _Nullable PBCommandListCreateWindowMenu(PBWindowRef window);
Syntax (Python)
CommandListCreateWindowMenu(window) -> (commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window from which the commands are taken.
[out] commandList (nullable owned PBCommandList): The new copy of the Window menu, or null if there was insufficient available memory.
See Also
PBCommandListAddCommand
Function: Append a command to a command list.
Syntax (C/C++)
void PBCommandListAddCommand(PBCommandListRef commandList,
PBCommandListItemFlags itemFlags, PBCommandID id);
Syntax (Python)
CommandListAddCommand(commandList, itemFlags, id)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
[in] itemFlags (PBCommandListItemFlags): Flags bitwise OR-ed together controlling the item.
[in] id (PBCommandID): The ID of the command, as registered in the command list's attached window with PBWindowRegisterAction.
Example (C/C++)
PBCommandListAddCommand(list, 0, PBCommandID_CUT);
PBCommandListAddCommand(list, 0, PBCommandID_COPY);
PBCommandListAddCommand(list, 0, COMMAND_RENAME);
See Also
PBCommandListRemoveCommand
Function: Remove a command from a command list.
Syntax (C/C++)
void PBCommandListRemoveCommand(PBCommandListRef commandList, PBCommandID id);
Syntax (Python)
CommandListRemoveCommand(commandList, id)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
[in] id (PBCommandID): The ID of the command, as registered in the command list's attached window with PBWindowRegisterAction.
See Also
PBCommandListRemoveAll
Function: Remove all the entries from a command list.
Syntax (C/C++)
void PBCommandListRemoveAll(PBCommandListRef commandList);
Syntax (Python)
CommandListRemoveAll(commandList)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
See Also
PBCommandListAddAction
Function: Append an action command to a command list without registering it in the window.
Syntax (C/C++)
void PBCommandListAddAction(PBCommandListRef commandList,
PBCommandListItemFlags itemFlags, PBCommandFlags commandFlags, ConstStr name,
PBActionHandler callback, PBUserContext context);
Syntax (Python)
CommandListAddAction(commandList, itemFlags, commandFlags, name, callback, context)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
[in] itemFlags (PBCommandListItemFlags): Flags bitwise OR-ed together controlling the list item.
[in] commandFlags (PBCommandFlags): Flags bitwise OR-ed together controlling the action command.
[in] name (referenced string): The human-readable name of the action, as will be displayed when the command list is presented to the user.
[in] callback (PBActionHandler): The callback to run when the user selects the action.
[in] context (PBUserContext): The context value passed to the callback.
Discussion
This is roughly equivalent to calling PBWindowRegisterAction and then PBCommandListAddCommand, however it does not require picking a PBCommandID, which can be useful for "temporary" actions e.g. ones that only make sense during the lifetime of a single pop-up menu.
Example (C/C++)
PBCommandListAddAction(list, 0, 0, PB_STR("Start"),
PBActionHandler_Make(StartAction), UC_INT(0));
See Also
PBCommandListAddSeparator
Function: Append a separator item to a command list.
Syntax (C/C++)
void PBCommandListAddSeparator(PBCommandListRef commandList);
Syntax (Python)
CommandListAddSeparator(commandList)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
Discussion
Separators at the start and end of a list are not displayed. Separators preceeded by another separator are not displayed.
See Also
PBCommandListAddColumn
Function: Start a new column in a command list.
Syntax (C/C++)
void PBCommandListAddColumn(PBCommandListRef commandList);
Syntax (Python)
CommandListAddColumn(commandList)
Parameters and Return Values
[in] commandList (referenced PBCommandList): The command list to modify.
Discussion
Items subsequently added to the command list will appear in a new column in representations that support columns (such as pop-up menus).
See Also
PBCommandListAddHeading
Function:
Syntax (C/C++)
void PBCommandListAddHeading(PBCommandListRef commandList, ConstStr headingText);
Syntax (Python)
CommandListAddHeading(commandList, headingText)
Parameters and Return Values
[in] commandList (referenced PBCommandList):
[in] headingText (referenced string):
PBCommandListAddSubMenu
Function:
Syntax (C/C++)
void PBCommandListAddSubMenu(PBCommandListRef commandList,
PBCommandListItemFlags flags, ConstStr name, PBSubMenuHandler callback,
PBUserContext context);
Syntax (Python)
CommandListAddSubMenu(commandList, flags, name, callback, context)
Parameters and Return Values
[in] commandList (referenced PBCommandList):
[in] flags (PBCommandListItemFlags):
[in] name (referenced string):
[in] callback (PBSubMenuHandler):
[in] context (PBUserContext):
See Also
PBCommandListIsEmpty
Function:
Syntax (C/C++)
bool PBCommandListIsEmpty(PBCommandListRef commandList);
Syntax (Python)
CommandListIsEmpty(commandList) -> (isEmpty)
Parameters and Return Values
[in] commandList (referenced PBCommandList):
[out] isEmpty (bool
):
Discussion
Returns true if no items or only separators have been added.
PBWindowRegisterAction
Function: Register an action command in a window.
Syntax (C/C++)
void PBWindowRegisterAction(PBWindowRef window, PBCommandFlags flags,
PBCommandID id, ConstStr name, PBActionHandler callback, PBUserContext context);
Syntax (Python)
WindowRegisterAction(window, flags, id, name, callback, context)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command will be registered.
[in] flags (PBCommandFlags): Flags bitwise OR-ed together controlling the action command.
[in] id (PBCommandID): The ID of the command to use to refer to it. This must be a non-negative integer.
[in] name (referenced string): The human-readable name of the action, as will be displayed when the command is presented to the user.
[in] callback (PBActionHandler): The callback to run when the action is invoked.
[in] context (PBUserContext): The context value passed to the callback.
Example (C/C++)
PBWindowRegisterAction(window, 0, COMMAND_GO_TO, PB_STR("Go to Folder…"),
PBActionHandler_Make(CommandGoTo), UC_INT(0));
See Also
- PBWindowSetCommandDisabled
- PBWindowSetCommandChecked
- PBWindowSetCommandName
- PBWindowRegisterKeyboardShortcut
- PBWindowInvokeCommand
PBWindowSetActionCallback
Function:
Syntax (C/C++)
void PBWindowSetActionCallback(PBWindowRef window, PBCommandID id,
PBActionHandler callback, PBUserContext context);
Syntax (Python)
WindowSetActionCallback(window, id, callback, context)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command is registered.
[in] id (PBCommandID): The ID of the command that refers to the registered action.
[in] callback (PBActionHandler): The callback to run when the action is invoked.
[in] context (PBUserContext): The context value passed to the callback.
PBWindowRegisterKeyboardShortcut
Function: Bind a command to a keyboard shortcut.
Syntax (C/C++)
void PBWindowRegisterKeyboardShortcut(PBWindowRef window, PBCommandID commandID,
PBModifierKeys modifiers, PBKeyCode mainKey);
Syntax (Python)
WindowRegisterKeyboardShortcut(window, commandID, modifiers, mainKey)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command is be registered and in which the keyboard shortcut will be active.
[in] commandID (PBCommandID): The ID of the command.
[in] modifiers (PBModifierKeys): The exact set of modifier keys to be held in order to invoke the shortcut.
[in] mainKey (PBKeyCode): The key to press.
Discussion
If the command is disabled when the keyboard shortcut is invoked, then nothing will happen.
Example (C/C++)
PBWindowRegisterKeyboardShortcut(window, COMMAND_GO_TO,
PBModifier_CMD | PBModifier_SHIFT, PBKey_G);
See Also
PBWindowSetCommandName
Function: Change the user-visible name of a command after registering it.
Syntax (C/C++)
void PBWindowSetCommandName(PBWindowRef window, PBCommandID commandID,
ConstStr newName);
Syntax (Python)
WindowSetCommandName(window, commandID, newName)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] commandID (PBCommandID): The identifier of the command.
[in] newName (referenced string): The new user-visible name of the command. The system maintains a copy of this string.
Discussion
All the UI elements that correspond to this command (such as buttons in a toolbar or menu items in a menu) will be updated automatically.
See Also
PBWindowSetCommandDisabled
Function: Set whether a command is disabled or enabled.
Syntax (C/C++)
void PBWindowSetCommandDisabled(PBWindowRef window, PBCommandID id,
bool disabled);
Syntax (Python)
WindowSetCommandDisabled(window, id, disabled)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[in] disabled (bool
): True to disable the command, or false to enable it.
Discussion
This cannot be used for standard commands; it can only be used for command you have registered yourself. Some standard commands are intended for capture by the focused element, such as PBCommandID_COPY. See PBElementSetCapturedCommandDisabled.
Disabled commands cannot be invoked; PBWindowInvokeCommand checks the command is enabled before calling its assigned callback.
If the command is being displayed in an UI element (such as a menu item or toolbar button) then the element will automatically be disabled or enabled to keep it synchronized with the command's state.
See Also
PBWindowIsCommandDisabled
Function: Get whether a command is disabled or enabled.
Syntax (C/C++)
bool PBWindowIsCommandDisabled(PBWindowRef window, PBCommandID id);
Syntax (Python)
WindowIsCommandDisabled(window, id) -> (disabled)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[out] disabled (bool
): True if the command is disabled, or false if it is enabled.
Discussion
This always returns true for an unregistered command identifier. Note that this will be the case if there was insufficient memory to register a command.
Note that comands are implicitely disabled when their window contains a modal alert.
See Also
PBWindowSetCommandChecked
Function: Check or uncheck a command.
Syntax (C/C++)
void PBWindowSetCommandChecked(PBWindowRef window, PBCommandID id, bool checked);
Syntax (Python)
WindowSetCommandChecked(window, id, checked)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[in] checked (bool
): True to check the command, false to uncheck it.
Discussion
The command must be checkable for this to succeed.
See Also
PBWindowIsCommandChecked
Function: Get whether a command is checked or unchecked.
Syntax (C/C++)
bool PBWindowIsCommandChecked(PBWindowRef window, PBCommandID id);
Syntax (Python)
WindowIsCommandChecked(window, id) -> (checked)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[out] checked (bool
): True if the command is checked, or false if it is unchecked.
Discussion
This always returns false for an unregistered command identifier. Note that this will be the case if there was insufficient memory to register a command.
See Also
PBWindowSetCommandIcon
Function:
Syntax (C/C++)
void PBWindowSetCommandIcon(PBWindowRef window, PBCommandID id, PBImageRef icon);
Syntax (Python)
WindowSetCommandIcon(window, id, icon)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[in] icon (referenced PBImage): The new icon for the command.
PBWindowInvokeCommand
Function: Programmatically run an action command.
Syntax (C/C++)
void PBWindowInvokeCommand(PBWindowRef window, PBCommandID id,
PBModifierKeys modifiers);
Syntax (Python)
WindowInvokeCommand(window, id, modifiers)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which the command was registered.
[in] id (PBCommandID): The ID of the command.
[in] modifiers (PBModifierKeys): The keyboard modifiers parameter to pass to the PBActionHandler.
Discussion
The command must be enabled with PBWIndowSetCommandDisabled or this will do nothing. This function can still invoke commands on windows containing a modal alert.
See Also
PBWindowSetToolbar
Function: Replace the window's toolbar.
Syntax (C/C++)
void PBWindowSetToolbar(PBWindowRef window, PBToolbarFlags flags,
PBCommandListRef commandList);
Syntax (Python)
WindowSetToolbar(window, flags, commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window in which to set the toolbar.
[in] flags (PBToolbarFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the toolbar.
[in] commandList (referenced PBCommandList): The command list containing the items to display in the toolbar.
Discussion
The toolbar buttons will automatically update to stay synchronized with the disabled and checked state of the command to which they correspond. Clicking an enabled toolbar button will invoke its command.
Example (C/C++)
PBCommandList *toolbar = PBCommandListCreate(window);
PBAssert(toolbar); // Will fail if low on memory.
PBCommandListAddCommand(toolbar, 0, COMMAND_START);
PBCommandListAddCommand(toolbar, 0, COMMAND_STOP);
PBWindowSetToolbar(window, 0, toolbar);
PBCommandListRelease(toolbar);
See Also
PBWindowGetToolbar
Function: Get the current toolbar in the window.
Syntax (C/C++)
PBCommandListPtr _Nullable PBWindowGetToolbar(PBWindowRef window);
Syntax (Python)
WindowGetToolbar(window) -> (commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window from which to get the toolbar.
[out] commandList (nullable owned PBCommandList): The command list containing the items to display in the toolbar.
PBWindowSetMenuBar
Function: Set the items shown in the menu bar when the window is active to the contents of a PBCommandList.
Syntax (C/C++)
void PBWindowSetMenuBar(PBWindowRef window, PBCommandListRef commandList);
Syntax (Python)
WindowSetMenuBar(window, commandList)
Parameters and Return Values
[in] window (referenced PBWindow): The window.
[in] commandList (referenced PBCommandList): The items in this command list specify the items in the menu bar.
Discussion
Only sub menus items are allowed in the command list.
PBWindowSetMenuBarItems
Function: Set the items shown in the menu bar when the window is active to an array of command lists.
Syntax (C/C++)
void PBWindowSetMenuBarItems(PBWindowRef window,
const PBMenuBarItem *_Nullable items, size_t itemsCount);
Syntax (Python)
WindowSetMenuBarItems(window, items)
Parameters and Return Values
[in] window (referenced PBWindow): The window.
[in] items (referenced array of PBMenuBarItem): An array of menu items. The system makes a copy of this array, and maintains its own references to the command lists within.
Discussion
Most application should add, at minimum, an edit menu (see PBCommandListCreateEditMenu) and a window menu (see PBCommandListCreateWindowMenu).
Example (C/C++)
PBCommandList *menu1 = PBCommandListCreate(window);
PBAssert(menu1); // May fail if low on memory.
PBCommandListAddCommand(menu1, 0, COMMAND1);
PBCommandListAddCommand(menu1, 0, COMMAND2);
PBCommandListAddCommand(menu1, 0, COMMAND3);
PBCommandList *menu2 = PBCommandListCreate(window);
PBAssert(menu2); // May fail if low on memory.
PBCommandListAddCommand(menu2, 0, COMMAND4);
PBCommandListAddCommand(menu2, 0, COMMAND5);
PBCommandListAddCommand(menu2, 0, COMMAND6);
PBMenuBarItem menus[] = { { menu1, PB_STR("Menu 1") },
{ menu2, PB_STR("Menu 2") } };
PBWindowSetMenuBarItems(instance->window, &menus[0], 2);
PBCommandListRelease(menu1);
PBCommandListRelease(menu2);
See Also
PBWindowPopUpMenu
Function: Show and attach a popup menu to a window.
Syntax (C/C++)
void PBWindowPopUpMenu(PBWindowRef window, PBPopUpMenuFlags flags,
PBCommandListRef commandList, PBElementRef _Nullable owningElement,
int32_t originX, int32_t originY);
Syntax (Python)
WindowPopUpMenu(window, flags, commandList, owningElement, originX, originY)
Parameters and Return Values
[in] window (referenced PBWindow): The PBWindow object to which the menu will be attached.
[in] flags (PBPopUpMenuFlags): Flags bitwise OR-ed together controlling the behavior of the menu.
[in] commandList (referenced PBCommandList): The list of commands that will be displayed in the menu.
[in] owningElement (nullable referenced PBElement): The element in the window from where the menu opened, or null.
[in] originX (int32_t
): The relative offset on the x-axis for the left side of the menu.
[in] originY (int32_t
): The relative offset on the y-axis for the top side of the menu.
Discussion
If the owning element is non-null, it will appear in the pushed theme state until the menu is closed. If the specified element already owns a menu, then this call will be ignored.
The initial position of the menu is determined by adding the specified origin offset to the top-left corner of the owning element, and then adjusting the menu so it will fit entirely on a screen without going off-screen. If the owning element is null, the offset is relative to the top-left of the window instead. Note that the flags PBPopUpMenu_AT_CURSOR and PBPopUpMenu_AT_ITEM will change the relative point.
Only one menu (and its chain of submenus) can be displayed at a time. When opening a new menu with a menu already open, the old menu will be closed.
The menu retains its own reference to the command list until it is closed.
This function returns immediately; it does not wait for the menu to be closed.
Example (C/C++)
PBCommandList *commandList = PBCommandListCreate(window);
PBCommandListAddCommand(commandList, 0, PBCommandID_COPY);
PBCommandListAddCommand(commandList, 0, PBCommandID_PASTE);
PBWindowPopUpMenu(window, PBPopUpMenu_AT_CURSOR, commandList, NULL, 0, 0);
PBCommandListRelease(commandList);
See Also
PBWindowClosePopUpMenus
Function: Close all popup menus attached to a window.
Syntax (C/C++)
bool PBWindowClosePopUpMenus(PBWindowRef window);
Syntax (Python)
WindowClosePopUpMenus(window) -> (anyClosed)
Parameters and Return Values
[in] window (referenced PBWindow): The PBWindow object.
[out] anyClosed (bool
): True if there was a menu attached to the window from PBWindowPopUpMenu that was closed; otherwise, false.
See Also
PBWindowInMenuMode
Function: Test if there are open menus attached to a window.
Syntax (C/C++)
bool PBWindowInMenuMode(PBWindowRef window);
Syntax (Python)
WindowInMenuMode(window) -> (anyMenus)
Parameters and Return Values
[in] window (referenced PBWindow): The PBWindow object.
[out] anyMenus (bool
): True if there is a menu attached to the window from PBWindowPopUpMenu; otherwise, false.
See Also
PBWindowShowPicker
Function:
Syntax (C/C++)
void PBWindowShowPicker(PBWindowRef _Nullable window, PBCommandPickerFlags flags,
PBCommandListRef _Nullable commandList, PBRunAsEventCallback onClose);
Syntax (Python)
WindowShowPicker(window, flags, commandList, onClose)
Parameters and Return Values
[in] window (nullable referenced PBWindow): The PBWindow object to which the command picker will be attached.
[in] flags (PBCommandPickerFlags):
[in] commandList (nullable referenced PBCommandList): The list of commands that will be displayed in the menu.
[in] onClose (PBRunAsEventCallback):
PBCommandListAddSubMenuDirect
Function:
Syntax (C/C++)
void PBCommandListAddSubMenuDirect(PBCommandListRef commandList,
PBCommandListItemFlags flags, ConstStr name, PBCommandListRef subMenu);
Syntax (Python)
CommandListAddSubMenuDirect(commandList, flags, name, subMenu)
Parameters and Return Values
[in] commandList (referenced PBCommandList):
[in] flags (PBCommandListItemFlags):
[in] name (referenced string):
[in] subMenu (referenced PBCommandList):