Text Displays
PBTextDisplay
Opaque object handle: A static UI Element that displays a text document or label.
This is a subclass of PBElement. You can safely cast from PBTextDisplay to PBElement. To cast from PBElement to PBTextDisplay, call PBTextDisplayCast; 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.
PBTextDisplayFlags
Enumeration/bitset of type uint32_t: Flags controlling the behavior and appearance of a text display.
Constants
PBTextDisplay_PREFORMATTED
PBTextDisplay_PREFORMATTED = 1<<0
Prevents trimming of trailing/leading/duplicate whitespace.
PBTextDisplay_ONE_LINE
PBTextDisplay_ONE_LINE = 1<<1
A single line of text will be displayed. If the text does not fit, it will be truncated with an ellipsis. If not set, the text will be allowed to wrap into multiple lines.
PBTextDisplay_INHERIT_COLORS
PBTextDisplay_INHERIT_COLORS = 1<<2
PBTextDisplay_RIGHT_ALIGN_TEXT
PBTextDisplay_RIGHT_ALIGN_TEXT = 1<<4
Right align the entire body of text horizontally within the bounds of the text display. This is useful for single line labels. Paragraphs with multiple lines of text should use PBTextAttribute_ALIGNMENT, which aligns each line individually.
PBTextDisplay_CENTER_TEXT
PBTextDisplay_CENTER_TEXT = 1<<5
Center the entire body of text horizontally within the bounds of the text display. This is useful for single line labels. Paragraphs with multiple lines of text should use PBTextAttribute_ALIGNMENT, which centers each line individually.
PBTextDisplay_SHOW_SELECTION_WHEN_UNFOCUSED
PBTextDisplay_SHOW_SELECTION_WHEN_UNFOCUSED = 1<<6
By default, the text selection is only shown if the text display has keyboard focus (see PBElementFocus). If this flag is set, then it will also be shown when the display is unfocused, in a similar manner to PBInputField. This flag is meaningless if the PBTextDisplay_ALLOW_SELECTION flag is not also set.
PBTextDisplay_ALLOW_SELECTION
PBTextDisplay_ALLOW_SELECTION = 1<<7
When set, the user will be able to select text and copy in the display.
Or any of the values from PBElementFlags.
PBMessageHyperlinkClicked
Structure: A message sent when a hyperlink is clicked in a non-disabled PBTextDisplay.
Fields
[in] url (referenced string): The URL specified in the corresponding PBTextAttribute_HYPERLINK attribute.
modifiers (PBModifierKeys): The modifier keys held when the hyperlink was clicked.
PBMessageGetImage
Structure: A message sent when a PBTextDocument is loaded into a PBTextDisplay that contains embedded images.
Fields
[in] sourceReference (referenced string): The reference string specified in the corresponding call to PBTextDocumentBuilderAppendImage.
image (nullable owned PBImage): The image to display.
PBTextDisplayCreateLabel
Function: Create a single-line text display for use as a label.
Syntax (C/C++)
PBTextDisplayPtr _Nullable PBTextDisplayCreateLabel(PBElementRef parent,
PBTextDisplayFlags flags, ConstStr contents);
Syntax (Python)
TextDisplayCreateLabel(parent, flags, contents) -> (display)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBTextDisplayFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] contents (referenced string): The initial text to display. The element maintains its own copy of this string.
[out] display (nullable owned PBTextDisplay): The text display element, or null on failure.
Discussion
Text displays created with function will have the style set so that their height matches other common UI controls, such as buttons, checkboxes and text input fields. Currently, this means that labels will be given non-zero vertical insets.
See PBElementCreate for a more detailed description of element creation.
Example (C/C++)
PBTextDisplay *display = PBTextDisplayCreateLabel(parent, 0, PB_STR("Enter your name:"));
PBAssert(display); /* may fail if low on memory */
PBElementRelease((PBElement *) display);
See Also
PBTextDisplayCreate
Function: Create a text display element.
Syntax (C/C++)
PBTextDisplayPtr _Nullable PBTextDisplayCreate(PBElementRef parent,
PBTextDisplayFlags flags, ConstStr contents, PBNamedTextStyle styleID);
Syntax (Python)
TextDisplayCreate(parent, flags, contents, styleID) -> (display)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBTextDisplayFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] contents (referenced string): The text string. The system makes a copy of this string.
[in] styleID (PBNamedTextStyle): The text style to apply.
[out] display (nullable owned PBTextDisplay): The text display element, or null on failure.
Discussion
See PBElementCreate for a more detailed description of element creation.
See Also
- PBTextDisplayCreateWithPositionedAttributes
- PBTextDisplayCreateLabel
- PBTextDisplayCreateWithDocument
- PBTextDisplaySetContents
- PBTextDisplaySetContentsWithPositionedAttributes
PBTextDisplayCreateWithPositionedAttributes
Function: Create a text display element with an array of positioned text attributes.
Syntax (C/C++)
PBTextDisplayPtr _Nullable PBTextDisplayCreateWithPositionedAttributes(
PBElementRef parent, PBTextDisplayFlags flags, ConstStr contents,
const PBPositionedTextAttribute *_Nullable attributes, size_t attributesCount);
Syntax (Python)
TextDisplayCreateWithPositionedAttributes(parent, flags, contents, attributes) -> (display)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBTextDisplayFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] contents (referenced string): The text string. The system makes a copy of this string.
[in] attributes (referenced array of PBPositionedTextAttribute): The array of text attributes. This array must be sorted by the start bytes in ascending order. Each attribute must start before the end of the text string.
[out] display (nullable owned PBTextDisplay): The text display element, or null on failure.
Discussion
See PBElementCreate for a more detailed description of element creation.
See Also
- PBTextDisplayCreate
- PBTextDisplayCreateLabel
- PBTextDisplayCreateWithDocument
- PBTextDisplaySetContentsWithPositionedAttributes
PBTextDisplayCreateWithRangedAttributes
Function: Create a text display element with an array of ranged text attributes.
Syntax (C/C++)
PBTextDisplayPtr _Nullable PBTextDisplayCreateWithRangedAttributes(
PBElementRef parent, PBTextDisplayFlags flags, ConstStr contents,
const PBRangedTextAttribute *_Nullable attributes, size_t attributesCount);
Syntax (Python)
TextDisplayCreateWithRangedAttributes(parent, flags, contents, attributes) -> (display)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBTextDisplayFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] contents (referenced string): The text string. The system makes a copy of this string.
[in] attributes (referenced array of PBRangedTextAttribute): The array of text attributes. Each attribute must start and end within the bounds of the text string.
[out] display (nullable owned PBTextDisplay): The text display element, or null on failure.
Discussion
See PBElementCreate for a more detailed description of element creation.
See Also
- PBTextDisplayCreate
- PBTextDisplayCreateLabel
- PBTextDisplayCreateWithDocument
- PBTextDisplaySetContentsWithRangedAttributes
PBTextDisplayCreateWithDocument
Function: Create a text display element displaying a text document.
Syntax (C/C++)
PBTextDisplayPtr _Nullable PBTextDisplayCreateWithDocument(PBElementRef parent,
PBTextDisplayFlags flags, PBTextDocumentRef _Nullable document);
Syntax (Python)
TextDisplayCreateWithDocument(parent, flags, document) -> (display)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBTextDisplayFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] document (nullable referenced PBTextDocument): The text document. The system keeps an internal reference to this as necessary.
[out] display (nullable owned PBTextDisplay): The text display element, or null on failure.
Discussion
See PBElementCreate for a more detailed description of element creation.
See Also
PBTextDisplaySetRoleMappings
Function: Set the assignments that map text roles (PBTextRoleID) to text styles (PBTextStyle).
Syntax (C/C++)
void PBTextDisplaySetRoleMappings(PBTextDisplayRef display,
const PBTextRoleMapping *_Nullable mappings, size_t mappingsCount);
Syntax (Python)
TextDisplaySetRoleMappings(display, mappings)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display element.
[in] mappings (referenced array of PBTextRoleMapping): The new array of mappings.
See Also
PBTextDisplaySetRoleMappingsForBody
Function: Map text roles (PBTextRoleID) to the text styles (PBTextStyle) suitable for body text.
Syntax (C/C++)
void PBTextDisplaySetRoleMappingsForBody(PBTextDisplayRef display);
Syntax (Python)
TextDisplaySetRoleMappingsForBody(display)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display element.
See Also
PBTextDisplaySetAdditionalScaleFactor
Function: Set an additional scale factor to change the text size.
Syntax (C/C++)
void PBTextDisplaySetAdditionalScaleFactor(PBTextDisplayRef display,
float additionalScaleFactor);
Syntax (Python)
TextDisplaySetAdditionalScaleFactor(display, additionalScaleFactor)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display element.
[in] additionalScaleFactor (float): The new additional scale factor. The default value is 1.0, corresponding to 100% (no change). This should be greater than 0.
Discussion
The text is automatically scaled by the monitor's scale factor; the additional scale factor will further change the size of the text and the document's spacing.
Changing this value dynamically can be slow because the text layout must be recalculated.
See Also
PBTextDisplaySetContents
Function: Replace the contents of a text display with a new string.
Syntax (C/C++)
void PBTextDisplaySetContents(PBTextDisplayRef display, ConstStr contents,
PBNamedTextStyle styleID);
Syntax (Python)
TextDisplaySetContents(display, contents, styleID)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] contents (referenced string): The new contents.
[in] styleID (PBNamedTextStyle): One of the system text styles.
Discussion
This is a convenience function that is equivalent to calling PBTextDisplaySetContentsWithPositionedAttributes with a single attribute for the text style.
The system will make an internal copy of the new string. The text display will automatically be redrawn at the end of the event.
Example (C/C++)
PBTextDisplaySetContents(display, PB_STR(playing ? "Playing" : "Paused"));
See Also
PBTextDisplaySetLabel
Function: Replace the contents of a text display with a new label.
Syntax (C/C++)
void PBTextDisplaySetLabel(PBTextDisplayRef display, ConstStr contents);
Syntax (Python)
TextDisplaySetLabel(display, contents)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] contents (referenced string): The new contents.
Discussion
This is a convenience function that is equivalent to calling PBTextDisplaySetContents with the PBNamedTextStyle_CONTROL_DEFAULT style.
The system will make an internal copy of the new string. The text display will automatically be redrawn at the end of the event.
Example (C/C++)
PBTextDisplaySetContents(display, PB_STR(playing ? "Playing" : "Paused"));
See Also
PBTextDisplaySetContentsWithPositionedAttributes
Function: Replace the contents of a text display.
Syntax (C/C++)
void PBTextDisplaySetContentsWithPositionedAttributes(PBTextDisplayRef display,
ConstStr contents,
const PBPositionedTextAttribute *_Nullable attributes, size_t attributesCount);
Syntax (Python)
TextDisplaySetContentsWithPositionedAttributes(display, contents, attributes)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] contents (referenced string): The new content string.
[in] attributes (referenced array of PBPositionedTextAttribute): The array of text attributes. This array must be sorted by the start bytes in ascending order. Each attribute must start before the end of the text string.
Discussion
The system will make an internal copy of the new string. The text display will automatically be redrawn at the end of the event.
Example (C/C++)
PBStrSlice string = PB_STR("hello world");
PBPositionedTextAttribute attribute = {};
attribute.start = 6 /* before the start of "world" */;
attribute.attribute.type = PBTextAttribute_WEIGHT;
attribute.attribute.f32 = 700.0f /* bold */;
PBTextDisplaySetContentsWithPositionedAttributes(display, string, &attribute, 1);
See Also
PBTextDisplaySetContentsWithRangedAttributes
Function: Replace the contents of a text display.
Syntax (C/C++)
void PBTextDisplaySetContentsWithRangedAttributes(PBTextDisplayRef display,
ConstStr contents,
const PBRangedTextAttribute *_Nullable attributes, size_t attributesCount);
Syntax (Python)
TextDisplaySetContentsWithRangedAttributes(display, contents, attributes)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] contents (referenced string): The new content string.
[in] attributes (referenced array of PBRangedTextAttribute): The array of text attributes. Each attribute must start and end within the bounds of the text string.
Discussion
The system will make an internal copy of the new string. The text display will automatically be redrawn at the end of the event.
See Also
PBTextDisplaySetDocument
Function: Set the text document to display in a text display element.
Syntax (C/C++)
void PBTextDisplaySetDocument(PBTextDisplayRef display,
PBTextDocumentRef document);
Syntax (Python)
TextDisplaySetDocument(display, document)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] document (referenced PBTextDocument): The text document to display.
Discussion
The system keeps an internal reference to the document as necessary. The text display will automatically be redrawn at the end of the event.
Example (C/C++)
PBTextDisplaySetDocument(display, document);
See Also
PBTextDisplaySelect
Function: Set the range of selected text.
Syntax (C/C++)
void PBTextDisplaySelect(PBTextDisplayRef display, uintptr_t anchor,
uintptr_t caret, PBEnsureVisibleMode ensureVisibleMode);
Syntax (Python)
TextDisplaySelect(display, anchor, caret, ensureVisibleMode)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] anchor (uintptr_t): The position of the selection anchor, in bytes from the start of the document.
[in] caret (uintptr_t): The position of the selection caret, in bytes from the start of the document.
[in] ensureVisibleMode (PBEnsureVisibleMode): Scroll any ancestor scroll views if necessary to ensure that the new selection is visible in the window.
Discussion
For text displays in which a PBTextDocument is loaded, the offsets are the interpreted the same as in PBTextDocumentCopyTextToBuffer and PBTextDocumentFindText. The offsets are automatically clamped to the range of the document.
If the display does not have the PBTextDisplay_ALLOW_SELECTION flag, this function does nothing.
Note that by default the text selection is not displayed unless the PBTextDisplay is focused; see PBElementFocus.
See Also
PBTextDisplayGetSelection
Function: Get the range of selected text.
Syntax (C/C++)
void PBTextDisplayGetSelection(PBTextDisplayRef display,
/* output */ uintptr_t * __restrict anchor,
/* output */ uintptr_t * __restrict caret);
Syntax (Python)
TextDisplayGetSelection(display) -> (anchor, caret)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[out] anchor (uintptr_t): The position of the selection anchor, in bytes from the start of the document.
[out] caret (uintptr_t): The position of the selection caret, in bytes from the start of the document.
Discussion
For text displays in which a PBTextDocument is loaded, the offsets are to be interpreted the same as in PBTextDocumentCopyTextToBuffer and PBTextDocumentFindText.
See Also
PBTextDisplayEnsureNodeVisible
Function:
Syntax (C/C++)
void PBTextDisplayEnsureNodeVisible(PBTextDisplayRef display,
PBTextDocumentRef node, PBEnsureVisibleMode mode);
Syntax (Python)
TextDisplayEnsureNodeVisible(display, node, mode)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] node (referenced PBTextDocument): The document node, obtained from PBTextDocumentGetChildNode.
[in] mode (PBEnsureVisibleMode): The mode to use to determine how much to scroll by.
Discussion
The text display must be showing a document loaded with PBTextDisplaySetDocument, and the provided node must be a descendent of the loaded document.
Scroll view ancestors of the display will be updated as necessary to scroll the node into view.
PBTextDisplayFindTextNodeAtTopOfRectangle
Function:
Syntax (C/C++)
PBTextDocumentPtr _Nullable PBTextDisplayFindTextNodeAtTopOfRectangle(
PBTextDisplayRef display, PBRectangle rectangle);
Syntax (Python)
TextDisplayFindTextNodeAtTopOfRectangle(display, rectangle) -> (node)
Parameters and Return Values
[in] display (referenced PBTextDisplay): The text display object.
[in] rectangle (PBRectangle): A rectangle relative to the top-left corner of the window, using pixels. Only the top coordinate is used by this function.
[out] node (nullable owned PBTextDocument): A reference to the node at the top of the viewport, or NULL if one was not found.
Discussion
The text display must be showing a document loaded with PBTextDisplaySetDocument.