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

Windows

PBWindow

Opaque object handle: An application window in which a graphical user interface is displayed.

This is a subclass of PBElement. You can safely cast from PBWindow to PBElement. To cast from PBElement to PBWindow, call PBWindowCast; this performs a runtime assertion to check the cast is possible. This function is thread-safe.

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 PBElementRetain; to decrement the reference count, call PBElementRelease. These functions are thread-safe.

PBWindowType

Enumeration/bitset of type uint32_t: The main type of a window.

Constants

PBWindowType_STANDARD

PBWindowType_STANDARD = 1

A standard application window, part of the workspace track. It has an opaque backing surface. It has window decorations, including a title bar and an area to resize it. It is shown on the task bar. It is accessible via alt-tab.

PBWindowType_PLAIN

PBWindowType_PLAIN = 2

A plain, undecorated window.

PBWindowType_MENU

PBWindowType_MENU = 3

A menu. Do not use this to create a menu; use PBWindowPopUpMenu instead.

See Also

PBWindowFlags

Enumeration/bitset of type uint32_t: Flags for controlling the behavior of a window.

Constants

PBWindow_NO_RESIZING

PBWindow_NO_RESIZING = 1<<0

The window cannot be resized by the user. This flag should only be used with windows of type PBWindowType_STANDARD.

PBWindow_NO_MOUSE_INPUT

PBWindow_NO_MOUSE_INPUT = 1<<1

The window does not receive mouse input. Mouse events go through to the window below.

PBWindow_CREATE_HIDDEN

PBWindow_CREATE_HIDDEN = 1<<2

The window will be created hidden. If this flag is not set when creating a window, the window will be shown automatically at the end of the event.

PBWindow_NO_CLOSE

PBWindow_NO_CLOSE = 1<<3

Do not use.

PBWindow_NO_ACTIVATE

PBWindow_NO_ACTIVATE = 1<<4

Do not activate the window when clicked. Do not use with PBWindowType_STANDARD. No mouse events are marked with PBMouseInput_ACTIVATED_WINDOW, so PBElement_ALLOW_FIRST_MOUSE is ignored.

See Also

PBToolbarFlags

Enumeration/bitset of type uint32_t:

Constants

(none)

PBPopUpMenuFlags

Enumeration/bitset of type uint32_t:

Constants

PBPopUpMenu_AT_CURSOR

PBPopUpMenu_AT_CURSOR = 1<<0

PBPopUpMenu_FOCUS

PBPopUpMenu_FOCUS = 1<<1

PBPopUpMenu_AT_ITEM

PBPopUpMenu_AT_ITEM = 1<<2

PBPopUpMenu_FROM_MENU_BAR

PBPopUpMenu_FROM_MENU_BAR = 1<<3

PBWindowDebugAction

Enumeration/bitset of type int32_t: Actions that can occur to a debugged process.

Constants

PBWindowDebugAction_PAUSED

PBWindowDebugAction_PAUSED = 1

The target process was paused and the debugger is now in control of it.

PBWindowDebugAction_RESUMED

PBWindowDebugAction_RESUMED = 2

The target process was resumed by the debugger.

See Also

PBWindowCreationOptions

Structure: The options for creating a window.

Fields

type (PBWindowType): The type of the window. See PBWindowType.

title (referenced string): The initial title of the window. This will be displayed in the title bar of the window, if it has one.

width (int32_t): The initial width of the window, in dps. If 0, the system will use PBElementMeasure to automatically determine the width of the window, and resize it when the contents changes.

height (int32_t): Similar to the width field, but for the height of the window.

flags (PBWindowFlags): Flags bitwise OR-ed together controlling the behavior of the window. See PBWindowFlags.

applicationName (referenced string): The name of the application that owns the window. This will be displayed in the main menu bar when the window is focused. It is unused for windows of type PBWindowType_MENU, since they cannot be focused. If this string is empty, the system will look for the application name of the first attached ancestor window. Failing this, it will use the window's title. If that is also empty, the system will look in the ancestor windows again.

See Also

PBMenuBarItem

Structure: An item in a menu bar.

Fields

commandList (referenced PBCommandList): The command list that will be displayed in a pop-up menu when the menu bar item is selected.

title (referenced string): The title of the item, shown in the menu bar itself.

PBMessageWindowAttachmentRemoved

Structure:

Fields

[in] previouslyAttachedWindowID (uint64_t):

PBMessageWindowAdjustAppMenu

Structure:

Fields

[in] commandList (referenced PBCommandList): The command list that will be used for the window's app menu.

PBWindowCreate

Function: Create a GUI window.

Syntax (C/C++)

PBWindowPtr _Nullable PBWindowCreate(PBWindowCreationOptions options);

Syntax (Python)

WindowCreate(options) -> (element)

Parameters and Return Values

[in] options (PBWindowCreationOptions): Options for creating the window.

[out] element (nullable owned PBWindow): The created PBWindow object, or null if the call fails. This must be released with PBElementRelease.

Discussion

You can close the window with PBElementDestroy. By default (unless the flag PBWindow_NO_CLOSE is specified), the window will call this when it receives the PBMsg_WINDOW_CLOSE message. You can use PBElementSetUserMessageHandler to handle this message manually.

The window will not be shown until the end of the current event.

The style of windows of type PBWindowType_STANDARD will be automatically set to PBStyleID_WINDOW_BACKGROUND.

The window is initialized with a default set of menus. You can change these using PBWindowSetMenuBarItems.

If the width or height of the window is specified as 0 in the creation options, then the system will automatically try to determine the size of the window on the respective axis and resize it when the window content changes.

You should add exactly one child element to the window after creating it. This element will be positioned to take up the entire available space of the window, excluding any window decorations.

Each process will keep processing its event loop while it has any open windows, even if they are hidden. When the last window is destroyed, the event loop returns. See PBEventLoop. The system maintains its own references to open windows, which will be released when the window is destroyed with PBElementDestroy.

Do not use this function with PBWindowType_MENU; instead, use PBWindowPopUpMenu.

Example (C/C++)

PBWindowCreationOptions options = { .type = PBWindowType_STANDARD,
    .title = PB_STR("My App"), .width = 400, .height = 300 };
PBWindow *window = PBWindowCreate(options);
PBElement *layoutColumn = PBLayoutColumnCreate((PBElement *) window, 0, 5, PB_RECT_1(5));
...
PBElementRelease(layoutColumn);
PBElementRelease((PBElement *) window);

See Also

PBWindowSetTitle

Function: Change the title of a window.

Syntax (C/C++)

void PBWindowSetTitle(PBWindowRef window, ConstStr newTitle);

Syntax (Python)

WindowSetTitle(window, newTitle)

Parameters and Return Values

[in] window (referenced PBWindow): The PBWindow object.

[in] newTitle (referenced string): The new title of the window.

Discussion

If the window has a title bar, it is updated to show the new title.

Any applications registered to receive window notifications with PBNotificationsSource_WINDOW_EVENTS will be sent a PBMsg_APP_NOTIFY_WINDOW_TITLE_CHANGED message to their application message handler.

Example (C/C++)

char newTitle[256];
snprintf(newTitle, sizeof(newTitle), "%s — My App", newFileName);
PBWindowSetTitle(window, PB_STR(newTitle));

PBWindowMove

Function: Move and resize a window.

Syntax (C/C++)

void PBWindowMove(PBWindowRef window, PBScreenID newScreenID, 
    PBRectangle newBounds);

Syntax (Python)

WindowMove(window, newScreenID, newBounds)

Parameters and Return Values

[in] window (referenced PBWindow): The PBWindow object.

[in] newScreenID (PBScreenID): The screen to which to move the window.

[in] newBounds (PBRectangle): The new bounding rectangle of the window, including the decorations. This is specified in pixels, relative to the top-left corner of the screen.

Discussion

If you want to ensure that the window's content area will have a specific size, use PBWindowGetDecorationInsets to check the size of the window decorations first. If you want to do this, note well that the result of PBWindowGetDecorationInsets depends on the screen containing the window.

The window may not be moved or resized immediately by the system.

Example (C/C++)

// Move the window to fill the primary screen's work area.
PBRectangle workArea = PBScreenGetWorkArea(PBScreenID_PRIMARY);
PBWindowMove(window, PBScreenID_PRIMARY, workArea);

See Also

PBWindowMakeHoveredElementPressed

Function:

Syntax (C/C++)

void PBWindowMakeHoveredElementPressed(PBWindowRef window, 
    PBElementRef _Nullable constrainWithin);

Syntax (Python)

WindowMakeHoveredElementPressed(window, constrainWithin)

Parameters and Return Values

[in] window (referenced PBWindow):

[in] constrainWithin (nullable referenced PBElement):

PBWindowGetDecorationInsets

Function: Get the size of the decorations around the window.

Syntax (C/C++)

PBRectangle PBWindowGetDecorationInsets(PBWindowRef window);

Syntax (Python)

WindowGetDecorationInsets(window) -> (insets)

Parameters and Return Values

[in] window (referenced PBWindow): The PBWindow object.

[out] insets (PBRectangle): The size of the decorations, in pixels, on each of the four sides.

Discussion

Window decorations include items like the title bar and window frame. Windows of type PB_WINDOW_POPUP do not have any system-provided decorations.

The size of the decorations is dependent on the screen containing the window, as each screen can have a different scale factor.

Example (C/C++)

PBRectangle insets = PBWindowGetDecorationInsets(window);

See Also

PBWindowReportDebugAction

Function: Report an action performed by a debugger running in a window.

Syntax (C/C++)

void PBWindowReportDebugAction(PBWindowRef window, uint64_t targetProcessID, 
    PBWindowDebugAction action);

Syntax (Python)

WindowReportDebugAction(window, targetProcessID, action)

Parameters and Return Values

[in] window (referenced PBWindow): The window, running in this process, that represents the debugger.

[in] targetProcessID (uint64_t): The kernel identifier of the process that is being debugged and for which this debug action related.

[in] action (PBWindowDebugAction): The action that occurred between the debugger and debuggee.

PBWindowRequestActivation

Function: Request a window be activated so that it receives input.

Syntax (C/C++)

void PBWindowRequestActivation(PBWindowRef window);

Syntax (Python)

WindowRequestActivation(window)

Parameters and Return Values

[in] window (referenced PBWindow): The window to activate.

Discussion

Windows can only be activated under certain limited circumstances.

Currently, windows only be activated when (1) the process is processing a PBWorkspaceRun request in a PBMsg_APP_CREATE message or (2) the calling process owns the current active window.

This function runs asynchronously. There is no way to determine whether the request was accepted.

Reporting some debug actions can change window activation; see PBWindowReportDebugAction.

See Also