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

Element Interaction

PBUpdateStateIndex

Enumeration/bitset of type uint32_t: The element states that when updated cause PBMsg_UPDATE_STATE messages to be sent.

Constants

PBUpdateState_HOVERED

PBUpdateState_HOVERED = 1

Whether the mouse is hovering over the element's bounds. See PBElementIsHovered and PBElementFindByPoint.

PBUpdateState_PRESSED

PBUpdateState_PRESSED = 2

Whether a mouse button is being held, and the mouse press occurred when the element was hovered.

PBUpdateState_FOCUSED

PBUpdateState_FOCUSED = 3

Whether the element has keyboard focus. See PBElementFocus and PBElementIsFocused.

PBUpdateState_DISABLED

PBUpdateState_DISABLED = 4

Whether the element is disabled. See PBElementSetDisabled and PBElementIsDisabled.

PBElementFocusFlags

Enumeration/bitset of type uint32_t: Flags controlling how to make an element focused. These flags are propagated to the PBMsg_UPDATE_STATE messages sent to the previously and newly focused elements.

Constants

PBElementFocus_ENSURE_VISIBLE

PBElementFocus_ENSURE_VISIBLE = 1<<0

The system will ensure the newly focused element is visible, adjusting scroll views as necessary. See PBElementEnsureVisible.

PBElementFocus_FROM_KEYBOARD

PBElementFocus_FROM_KEYBOARD = 1<<1

The focus change request was caused by keyboard input, such as pressing PBKey_TAB.

PBElementFocus_ONLY_IF_NO_FOCUSED_ELEMENT

PBElementFocus_ONLY_IF_NO_FOCUSED_ELEMENT = 1<<2

The focus change request should be ignored if there is already a focused element.

PBElementFocus_FROM_FORWARD_TAB_TRAVERSAL

PBElementFocus_FROM_FORWARD_TAB_TRAVERSAL = 1<<3

The element was focused by pressing tab.

PBElementFocus_FROM_REVERSE_TAB_TRAVERSAL

PBElementFocus_FROM_REVERSE_TAB_TRAVERSAL = 1<<4

The element was focused by pressing shift-tab.

PBMessageUpdateState

Structure: Contains information about what element state was updated.

Fields

[in] index (PBUpdateStateIndex): The state that changed.

[in] focusFlags (PBElementFocusFlags): For PBUpdateState_FOCUSED, this contains the flags passed to PBElementFocus.

PBMessageTabTraverse

Structure:

Fields

[in] reverse (bool):

element (nullable owned PBElement):

PBElementFindByPoint

Function: Find the top-most element under a point.

Syntax (C/C++)

PBElementPtr _Nullable PBElementFindByPoint(PBElementRef element, int32_t x, 
    int32_t y);

Syntax (Python)

ElementFindByPoint(element, x, y) -> (descendent)

Parameters and Return Values

[in] element (referenced PBElement): The element to search within. This could be a PBWindow.

[in] x (int32_t): The x-coordinate of the point, relative to the left side of the window containing the element.

[in] y (int32_t): The y-coordinate of the point, relative to the top side of the window containing the element.

[out] descendent (nullable owned PBElement): The found element. Release with PBElementRelease. Returns NULL if no element was found (but see the discussion below).

Discussion

This will not return elements with the PBElement_INPUT_MOUSE_NONE flag.

This will not search descendent element with the PBElement_HIDDEN flag. If an element has the PBElement_CLIP_LAYER flag and its does not contain the point, then its descendents will not be searched.

An element is considered to contain the point if the point is within its layout bounds (see PBRectangleContains and PBElementGetBounds) and sending the element the PBMsg_CONTAINS_POINT message gives a positive result.

This function returns the top-most elements under the point. The descendents of an element are considered to be above it. Sibling elements are also ordered; see PBElementChangeOrdering.

The rules of this function match how mouse input is directed to the correct element. The depth stacking rules also match how the element hierarchy is drawn.

If no element contains the point, the root element being searched is returned, unless it has the PBElement_INPUT_MOUSE_NONE flag, in which case NULL is returned.

See Also

PBElementFocus

Function: Assign a window's keyboard focus to an element.

Syntax (C/C++)

void PBElementFocus(PBElementRef element, PBElementFocusFlags flags);

Syntax (Python)

ElementFocus(element, flags)

Parameters and Return Values

[in] element (referenced PBElement): The element to focus. The window containing it will have its focused element modified.

[in] flags (PBElementFocusFlags): Flags bitwise OR-ed together controlling the operation.

Discussion

Each window has a focused element, the element that receives keyboard input when the window is active. Only one element can be focused within a window. This function does not affect the active window. It only affects the focused element of the given window. See PBWindowRequestActivation.

If the element is disabled or hidden, or has a disabled or hidden ancestor, then the request to focus it is ignored, since disabled elements and hidden elements cannot be focused. Furthermore, if the element or one of its ancestors is disabled or hidden later (with PBElementSetDisabled or PBElementSetHidden respectively) then the element will no longer be focused. This focus state is not automatically restored when the elements is later eligible for focusing.

On calling this function, this element as well as the previously focused element will be sent PBMsg_UPDATE_STATE messages with the PBUpdateState_FOCUSED bit set.

You can test if an element is the focused element of its window using PBElementIsFocused.

Example (C/C++)

PBInputField *field = PBInputFieldCreateSingleLine(parent, 0, 0, NULL);
PBAssert(field); // May fail if low on memory.
PBElementFocus((PBElement *) field, 0); // Focus the input field.
PBInputFieldRelease(field);

See Also

PBElementIsDisabled

Function: Test if an element has the PBElement_DISABLED flag set.

Syntax (C/C++)

bool PBElementIsDisabled(PBElementRef element);

Syntax (Python)

ElementIsDisabled(element) -> (isDisabled)

Parameters and Return Values

[in] element (referenced PBElement): The element.

[out] isDisabled (bool): True if PBElement_DISABLED is set, otherwise false.

Discussion

Although descendents of a disabled element behave as if there were disabled in some cases, for this function they are not considered disabled.

This is equivalent to calling PBElementGetFlags and testing for the PBElement_DISABLED flag.

Example (C/C++)

PBElementSetDisabled(element, true);
PBAssert(PBElementIsDisabled(element));
PBElementSetDisabled(element, false);
PBAssert(!PBElementIsDisabled(element));

See Also

PBElementIsFocused

Function: Test if an element is the singular focused element in its window.

Syntax (C/C++)

bool PBElementIsFocused(PBElementRef element, bool forDrawing);

Syntax (Python)

ElementIsFocused(element, forDrawing) -> (isFocused)

Parameters and Return Values

[in] element (referenced PBElement): The element to test.

[in] forDrawing (bool): When drawing an element, some additional logic is applied to decide whether the element should appear focused for the purposes of its PBAppearance. For example, only the focused element in the active window will actually appear focused. By setting this parameter to true, this function will replicate this logic.

[out] isFocused (bool): True if the element is focused; otherwise, false.

Example (C/C++)

if (PBElementIsFocused(element, false)) {
    // If the element is focused, then capture the copy command.
    PBElementSetCapturedCommandDisabled(element, PBCommandID_COPY, false);
}

See Also

PBElementIsHot

Function: Test if the element is hot.

Syntax (C/C++)

bool PBElementIsHot(PBElementRef element, bool orAncestorOfHotElement);

Syntax (Python)

ElementIsHot(element, orAncestorOfHotElement) -> (isHot)

Parameters and Return Values

[in] element (referenced PBElement): The element.

[in] orAncestorOfHotElement (bool): If true, the function will additionally return true if the element is an ancestor of the hot element.

[out] isHot (bool): True if the element is hot; otherwise, false.

Discussion

The hot element is: the pressed element if it exists; otherwise, the hovered element. There is only a pressed element when a mouse button is being held down; if so, the pressed element will be the element that was hovered when the mouse button was pressed. See PBElementIsHovered for a description of how the hovered element is determined.

PBElementIsHovered

Function: Test if the mouse pointer is hovering over an element.

Syntax (C/C++)

bool PBElementIsHovered(PBElementRef element, bool orAncestorOfHoveredElement);

Syntax (Python)

ElementIsHovered(element, orAncestorOfHoveredElement) -> (isHovered)

Parameters and Return Values

[in] element (referenced PBElement): The element to test.

[in] orAncestorOfHoveredElement (bool): If true, then this function will also return true if the element is an ancestor of the hovered element.

[out] isHovered (bool): True if this is the hovered element.

Discussion

If there is no pressed element, the hovered element is found using PBElementFindByPoint. If there is a pressed element, then the hovered element is either the pressed element or NULL (when the pointer moves outside the pressed element's input region).

If the given element is disabled, then this function will return false.

See Also

PBElementIsPressed

Function: Test if the element is pressed.

Syntax (C/C++)

bool PBElementIsPressed(PBElementRef element, bool orAncestorOfPressedElement, 
    /* output */ PBMouseButton * _Nullable __restrict pressedWith, 
    /* output */ bool * _Nullable __restrict passedDragMovementThreshold);

Syntax (Python)

ElementIsPressed(element, orAncestorOfPressedElement) -> (isPressed, pressedWith, passedDragMovementThreshold)

Parameters and Return Values

[in] element (referenced PBElement): The element.

[in] orAncestorOfPressedElement (bool): If true, the function will additionally return true if the element is an ancestor of the pressed element.

[out] isPressed (bool): True if the element is pressed; otherwise, false.

[optional-out] pressedWith (PBMouseButton): The mouse button that is pressed the element.

[optional-out] passedDragMovementThreshold (bool): The drag movement threshold has been exceeded; see PBMouseInput_PASSED_DRAG_MOVEMENT_THRESHOLD.

PBElementSetDisabled

Function: Enable or disable an element.

Syntax (C/C++)

void PBElementSetDisabled(PBElementRef element, bool disabled);

Syntax (Python)

ElementSetDisabled(element, disabled)

Parameters and Return Values

[in] element (referenced PBElement): The element.

[in] disabled (bool): True to disable the enable, false to enable it.

Discussion

This does nothing if it won't change the disabled state.

Since elements with a disabled ancestors cannot be hovered, pressed or focused, this function will remove these interaction states as necessary.

The element will be sent a PBMsg_UPDATE_STATE message with the PBUpdateState_DISABLED bit set.

PBElementSimulateMousePress

Function:

Syntax (C/C++)

void PBElementSimulateMousePress(PBElementRef element, PBMouseButton button, 
    bool pressed);

Syntax (Python)

ElementSimulateMousePress(element, button, pressed)

Parameters and Return Values

[in] element (referenced PBElement):

[in] button (PBMouseButton):

[in] pressed (bool):

PBElementTransferMousePress

Function:

Syntax (C/C++)

bool PBElementTransferMousePress(PBElementRef element, PBElementRef newPressed);

Syntax (Python)

ElementTransferMousePress(element, newPressed) -> (success)

Parameters and Return Values

[in] element (referenced PBElement):

[in] newPressed (referenced PBElement):

[out] success (bool):

PBElementAnimateClick

Function: Briefly animate an element to appear as if it were clicked.

Syntax (C/C++)

void PBElementAnimateClick(PBElementRef element);

Syntax (Python)

ElementAnimateClick(element)

Parameters and Return Values

[in] element (referenced PBElement): The UI element.