v0.8.0
⌘P
Go-to Page: ⌘G

Guide

All UI Elements
App Bundles
libplaybit API Conventions
Standard UI Layout
Text Controls
Text Styling

API Reference

Accessibility and Automation
Alerts
Buttons
Checkboxes
Clipboard
Colors
Commands and Command Lists
Common Definitions
Configuration
Data Streams
Display Screens
Drag and Drop
Drawing
Element Hierarchy
Element Interaction
Element Layout and Painting
Element Messaging
Element Properties
Element User Data
Event Loop
File Editors
File Pickers
Handoff
Image Displays
Images
Input Devices
Layout Columns and Rows
Layout Grids
Layout Wraps
Log Views
Notifications
Pop-Up Buttons
Progress Indicators
Radio Button Groups
Rectangles
Render Surfaces
Resizable Panels
Run-time Helpers
Scrolling
Shared Nodes
Size Constraint Panels
Sliders
Styling
Table Views
Text Displays
Text Documents
Text Input Fields
Text Plans
Text Styles
Tool Tips
Transition Panels
Value Stores
Virtual Text Views
Windows
Workspace IPC

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.

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

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):

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

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.

PBWindowSetMenuBarItems

Function: Set the items shown in the menu bar when the window is active.

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):