Element Layout and Painting
PBMessageLayoutFlags
Enumeration/bitset of type uint32_t: Flags indicating why the layout message was sent.
Constants
PBMessageLayout_RESIZED
PBMessageLayout_RESIZED = 1<<0
The size of the element's bounding box was modified by the parent element.
PBMessageLayout_REQUESTED
PBMessageLayout_REQUESTED = 1<<1
A layout of the element was requested by a call to PBElementContentsChanged.
PBElementHideFlags
Enumeration/bitset of type uint32_t:
Constants
PBElementHide_SKIP_RELAYOUT
PBElementHide_SKIP_RELAYOUT = 1<<1
PBContainsPointSource
Enumeration/bitset of type uint16_t: An enumeration indicating from where the bounds test came.
Constants
PBContainsPointSource_OTHER
PBContainsPointSource_OTHER = 0
The general case.
PBContainsPointSource_DND
PBContainsPointSource_DND = 1
The message was sent while looking for an element to be the drag-and-drop target.
PBContainsPointSource_FIND_BY_POINT
PBContainsPointSource_FIND_BY_POINT = 2
The message was sent while processing a call to PBElementFindByPoint.
PBContainsPointSource_HOVERING
PBContainsPointSource_HOVERING = 3
The message was sent while looking for an element to be the hovered element (see PBElementIsHovered).
PBMessageGetChildStability
Structure:
Fields
[in] child (referenced PBElement):
stableAxes (PBAxis):
PBMessageLayout
Structure: Associated data for a layout message.
Fields
[in] flags (PBMessageLayoutFlags): Flags bitwise OR-ed together describing the type of layout.
See Also
PBMessageMeasure
Structure:
Fields
[in] axis (PBAxis): The axis on which to measure. Either PBAxis_H for the width or PBAxis_V for the height.
[in] otherDimensionSize (int64_t): The available space on the other axis, in pixels. This is 0 if unknown.
measuredSize (int64_t): The measured size on the request axis, in pixels.
PBMessageScreenResolutionChanged
Structure:
Fields
screenID (PBScreenID):
PBMessageGetCursor
Structure: Associated data for a request to get an element's cursor.
Fields
cursorID (PBCursorID): The cursor that will display while the mouse is hovering over the element or pressing it.
See Also
PBMessageContainsPoint
Structure:
Fields
[in] x (int32_t):
[in] y (int32_t):
result (bool):
source (PBContainsPointSource):
PBMessageScaleFactorChanged
Structure:
Fields
[in] newScaleFactor (uint32_t):
PBMessageColorSpaceChanged
Structure:
Fields
[in] newColorSpace (PBColorSpaceID):
PBMessageGetVirtualChildCount
Structure:
Fields
count (uint64_t):
PBMessageGetVirtualChild
Structure:
Fields
[in] index (uint64_t):
child (nullable owned PBElement):
PBMessageGetIndexOfVirtualChild
Structure:
Fields
[in] child (referenced PBElement):
index (uint64_t):
PBElementContentsChanged
Function: Inform the system that the contents of an element has changed.
Syntax (C/C++)
void PBElementContentsChanged(PBElementRef element, PBAxis measurementsChanged);
Syntax (Python)
ElementContentsChanged(element, measurementsChanged)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] measurementsChanged (PBAxis): Values bitwise OR-ed together to indicate on which axes the dimensions of the element may have changed. This will cause the ancestor of the element to relayout.
Discussion
Later in the event cycle, the system will relayout all the affected elements. The element passed to this function will always have its layout updated. Depending on the value of measurementsChanged, its ancestors may update their layout. If during its layout, the element resizes some of its child elements, then they will also update their layout.
Only elements with the PBElement_CUSTOM_LAYOUT flag will be sent the PBMsg_LAYOUT message during their layout. Other elements will have the standard layout algorithm applied by the system.
You must call this function any time your element may have changeed how it responds to the PBMsg_MEASURE message.
See Also
PBElementEnsureVisible
Function: Request ancestors of an element make it visible, by adjusting scroll positions or otherwise.
Syntax (C/C++)
void PBElementEnsureVisible(PBElementRef element);
Syntax (Python)
ElementEnsureVisible(element)
Parameters and Return Values
[in] element (referenced PBElement): The element to make visible.
Discussion
Later in the event cycle, after a preliminary relayout has been performed, the system will send PBMsg_ENSURE_VISIBLE messages to each of the ancestors (with the PBElement_CUSTOM_LAYOUT flag) of the element in turn, starting from its parent. This gives them an opportunity to adjust their scroll positions and other data to ensure the descendent will be visible. Then, a secondary relayout pass will be performed so that the element will actually be moved into its new position.
This is a convenience function wrapping PBElementEnsureVisible2 using the PBEnsureVisibleMode_MINIMIZE_SCROLL_DISTANCE mode.
See Also
PBElementEnsureVisible2
Function: Request ancestors of an element make it visible, by adjusting scroll positions or otherwise.
Syntax (C/C++)
void PBElementEnsureVisible2(PBElementRef element, PBEnsureVisibleMode mode);
Syntax (Python)
ElementEnsureVisible2(element, mode)
Parameters and Return Values
[in] element (referenced PBElement): The element to make visible.
[in] mode (PBEnsureVisibleMode): The mode determining where the element should be positioned in the viewport.
Discussion
Later in the event cycle, after a preliminary relayout has been performed, the system will send PBMsg_ENSURE_VISIBLE messages to each of the ancestors (with the PBElement_CUSTOM_LAYOUT flag) of the element in turn, starting from its parent. This gives them an opportunity to adjust their scroll positions and other data to ensure the descendent will be visible. Then, a secondary relayout pass will be performed so that the element will actually be moved into its new position.
See Also
PBElementGetBounds
Function: Get the bounding box an element with 32-bit coordinates.
Syntax (C/C++)
PBRectangle PBElementGetBounds(PBElementRef element);
Syntax (Python)
ElementGetBounds(element) -> (bounds)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[out] bounds (PBRectangle): Its bounding box for layout. The coordinates are in pixels, and are relative to the top-left corner of the window's content area.
Discussion
The layout bounding box of an element may not be exactly the same as the region in which it can draw (see PBMsg_GET_PAINT_BOUNDS and PBAppearanceCompile), and may not be the same as the region in which the element can be accessed by the user (see PBElementFindByPoint).
This function is equivalent to PBElementGetBounds64 except it clamps coordinates to 32-bit integers. Unless your element needs to support layouting of very large amounts of content, this function is preferred.
Example (C/C++)
if (message->type == PBMsg_LAYOUT) {
PBElementMove(child, PBElementGetBounds(element));
}
See Also
PBElementGetBounds64
Function: Get the bounding box an element with 64-bit coordinates.
Syntax (C/C++)
PBRectangle64 PBElementGetBounds64(PBElementRef element);
Syntax (Python)
ElementGetBounds64(element) -> (bounds)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[out] bounds (PBRectangle64): Its bounding box for layout. The coordinates are in pixels, and are relative to the top-left corner of the window's content area.
Discussion
See PBElementGetBounds for a description of this function.
See Also
PBElementGetClippedBounds
Function:
Syntax (C/C++)
PBRectangle PBElementGetClippedBounds(PBElementRef element);
Syntax (Python)
ElementGetClippedBounds(element) -> (clippedBounds)
Parameters and Return Values
[in] element (referenced PBElement):
[out] clippedBounds (PBRectangle):
PBElementGetScaleFactor
Function:
Syntax (C/C++)
uint32_t PBElementGetScaleFactor(PBElementRef element);
Syntax (Python)
ElementGetScaleFactor(element) -> (scaleFactor)
Parameters and Return Values
[in] element (referenced PBElement):
[out] scaleFactor (uint32_t):
PBElementGetSize
Function: Get the current size of an element's bounding box.
Syntax (C/C++)
PBSize PBElementGetSize(PBElementRef element);
Syntax (Python)
ElementGetSize(element) -> (size)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[out] size (PBSize): The size of the rectangle returned by PBElementGetBounds, in pixels.
Discussion
This may not be the element's preferred size; you may use PBElementMeasure to ask it for the size it would like to have.
See Also
PBElementIsHidden
Function: Test if an element is hidden or shown.
Syntax (C/C++)
bool PBElementIsHidden(PBElementRef element, bool orAncestor);
Syntax (Python)
ElementIsHidden(element, orAncestor) -> (isHidden)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] orAncestor (bool): If true, the system additionally checks if any of the element's ancestors are hidden. This is useful because an element that has a hidden ancestor will behave much as if it were hidden itself.
[out] isHidden (bool): True if the element is hidden.
See Also
PBElementMeasure
Function: Ask an element for its preferred size on the horizontal or vertical axis.
Syntax (C/C++)
int64_t PBElementMeasure(PBElementRef element, PBAxis axis,
int64_t otherDimensionSizePx);
Syntax (Python)
ElementMeasure(element, axis, otherDimensionSizePx) -> (measuredSizePx)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] axis (PBAxis): The axis on which to get the dimension. Either PBAxis_H or PBAxis_V for the width or height respectively.
[in] otherDimensionSizePx (int64_t): The available space on the other axis not specified as the axis, in pixels. If the space is unknown, set this parameter to 0. This parameter is useful, for example, when measuring the height of a text display which contains word-wrapped text. This parameter should be set to the desired width of the text layout, and then the function will return the height corresponding to the number of lines that are needed for such a layout.
[out] measuredSizePx (int64_t): The measured size on the requested axis, in pixels.
Discussion
If the element's layout metrics give a fixed size on the specified axis, then that size is returned (after converting from dp to px). If the metrics give a fixed size on the other axis, the value of otherDimensionSizePx is ignored and is instead set to this fixed size.
If the element has the PBElement_CUSTOM_LAYOUT flag, it will be sent a PBMsg_MEASURE message in order to complete the measurement request.
If the element does not have the PBElement_CUSTOM_LAYOUT flag, the standard layout algorithm is applied to determine the requested size. For example, with a vertical column, the measured height is the sum of the heights of the child elements and the necessary gaps/insets. These child heights are determined recursively with PBElementMeasure, passing the otherDimensionSizePx minus the horizontal insets. Measuring the width of the vertical column will return the maximum width among all child elements, added to the horizontal insets.
Example (C/C++)
// Here we obtain the measurements of a text display.
int64_t widthOfUnwrappedText = PBElementMeasure(textDisplay, PBAxis_H, 0);
int64_t heightOfOneLine = PBElementMeasure(textDisplay, PBAxis_V, 0);
int64_t heightOfWrappedText = PBElementMeasure(textDisplay, PBAxis_V, 300 /* px */);
See Also
PBElementMove
Function: Set the layout bounds of an element in response to a PBMsg_LAYOUT message.
Syntax (C/C++)
void PBElementMove(PBElementRef element, PBRectangle bounds);
Syntax (Python)
ElementMove(element, bounds)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] bounds (PBRectangle): Its new bounding rectangle, in pixels.
Discussion
This should only be called in response to a PBMsg_LAYOUT message. Each element with the PBElement_CUSTOM_LAYOUT flag is responsible for positioning its children (and its children only) when it receives the PBMsg_LAYOUT message. If you need to relayout an element's children, call PBElementContentsChanged, and the element will receive a PBMsg_LAYOUT message at the correct point in the event cycle.
On changing an element's bounds, it will relayout its children as necessary. If the moved element does not have the PBElement_CUSTOM_LAYOUT flag, it will apply the standard layout algorithm to do so.
See Also
PBElementMove64
Function: Set the layout bounds of an element with 64-bit coordinates.
Syntax (C/C++)
void PBElementMove64(PBElementRef element, PBRectangle64 bounds);
Syntax (Python)
ElementMove64(element, bounds)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] bounds (PBRectangle64): Its new bounding rectangle, in pixels.
Discussion
This function is equivalent to PBElementMove, but takes 64-bit coordinates. This is only necessary when dealing with very large scrolling lists.
See Also
PBElementNeedsVirtualChild
Function:
Syntax (C/C++)
bool PBElementNeedsVirtualChild(PBElementRef element, PBElementRef child);
Syntax (Python)
ElementNeedsVirtualChild(element, child) -> (isNeeded)
Parameters and Return Values
[in] element (referenced PBElement):
[in] child (referenced PBElement):
[out] isNeeded (bool):
PBElementRepaintAll
Function: Request an element to be repainted.
Syntax (C/C++)
void PBElementRepaintAll(PBElementRef element);
Syntax (Python)
ElementRepaintAll(element)
Parameters and Return Values
[in] element (referenced PBElement): The element to repaint.
Discussion
The entire element will be redrawn at the end of the event cycle. This function will use the paint bounds of the element at the end of the event cycle.
If the element is hidden, the request is ignored.
Elements visually behind or in front of this element may also be repainted as necessary. For instance, if this element is partially translucent, then portions of the elements behind may need repainting.
See Also
PBElementRepaintPartial
Function: Request a partial region of an element to be repainted.
Syntax (C/C++)
void PBElementRepaintPartial(PBElementRef element, PBRectangle region);
Syntax (Python)
ElementRepaintPartial(element, region)
Parameters and Return Values
[in] element (referenced PBElement): The element to partially repaint.
[in] region (PBRectangle): The region of the element to repaint. The coordinates are in pixels, and are relative to the top-left corner of the window's content area.
Discussion
This function is only useful for elements with the PBElement_CUSTOM_PAINT flag. Use PBElementRepaintAll otherwise.
The given region will be intersected with the element's paint bounds (see PBMsg_GET_PAINT_BOUNDS), and the layout bounds of any ancestor with the PBElement_CLIP_LAYER clip.
See Also
PBElementScaleI32
Function: Scale a int32_t by the scaling factor of the window that contains this element.
Syntax (C/C++)
int32_t PBElementScaleI32(PBElementRef element, int32_t x);
Syntax (Python)
ElementScaleI32(element, x) -> (y)
Parameters and Return Values
[in] element (referenced PBElement): The element from which to obtain the scale factor.
[in] x (int32_t): The value to scale.
[out] y (int32_t): The scaled value.
Discussion
This handles rounding and negative values consistently with automatically scaling performed by the system.
See Also
PBElementScaleRectangle
Function: Scale each value in a PBRectangle by the scaling factor of the window that contains this element.
Syntax (C/C++)
PBRectangle PBElementScaleRectangle(PBElementRef element, PBRectangle x);
Syntax (Python)
ElementScaleRectangle(element, x) -> (y)
Parameters and Return Values
[in] element (referenced PBElement): The element from which to obtain the scale factor.
[in] x (PBRectangle): The rectangle to scale.
[out] y (PBRectangle): The scaled rectangle.
Discussion
This handles rounding and negative values consistently with automatically scaling performed by the system.
See Also
PBElementSetHidden
Function: Show or hide an element.
Syntax (C/C++)
void PBElementSetHidden(PBElementRef element, bool hidden,
PBElementHideFlags flags);
Syntax (Python)
ElementSetHidden(element, hidden, flags)
Parameters and Return Values
[in] element (referenced PBElement): The element.
[in] hidden (bool): True to hide the element; false to show it.
[in] flags (PBElementHideFlags): Flags bitwise OR-ed together controlling the operation.
Discussion
This does nothing if the hidden state of the element is already the requested one.
See PBElement_HIDDEN for a description of what an element being hidden affects.
When making a focused element hidden, its focus will be removed and no element will be focused. It is recommended to move the focus to sensible element with PBElementFocus.
See Also
PBElementRequestAnimationFrame
Function:
Syntax (C/C++)
bool PBElementRequestAnimationFrame(PBElementRef element);
Syntax (Python)
ElementRequestAnimationFrame(element) -> (success)
Parameters and Return Values
[in] element (referenced PBElement):
[out] success (bool):