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
- PBElementIsFocused
- PBMsg_UPDATE_STATE
- PBElementSetDisabled
- PBElementSetHidden
- PBWindowRequestActivation
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.