Text Plans
PBTextPlan
Opaque object handle: An object for performing the layout of text paragraphs. To draw text, one must create a text plan, call PBTextPlanLayout and then pass it to PBDrawText. The bounding box of the text can be modified multiple times after creating the text plan, but the underlying text document cannot be changed.
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 PBTextPlanRetain; to decrement the reference count, call PBTextPlanRelease. These functions are thread-safe.
See Also
PBTextPlanLayoutFlags
Enumeration/bitset of type uint32_t: Flags controlling the behavior of text layout.
Constants
PBTextPlanLayout_PREFORMATTED
PBTextPlanLayout_PREFORMATTED = 1<<0
Prevents trimming of trailing/leading/duplicate whitespace.
PBTextPlanLayout_ONE_LINE
PBTextPlanLayout_ONE_LINE = 1<<1
When set: the text will be placed on a single line; newline characters are ignored; and PBTextPlanLayout_ALWAYS_SET_HEIGHT is implied. When clear, the text will be wrapped to multiple lines as necessary.
PBTextPlanLayout_ALWAYS_SET_HEIGHT
PBTextPlanLayout_ALWAYS_SET_HEIGHT = 1<<2
Implied by PBTextPlanLayout_ONE_LINE. The computed height (see PBTextPlanGetSize) will be set to the height of the single line, even if the input text is an empty string.
See Also
PBTextPlanCreate
Function: Create a text plan from a string and array of text attributes.
Syntax (C/C++)
PBTextPlanPtr _Nullable PBTextPlanCreate(ConstStr contents,
const PBPositionedTextAttribute *_Nullable attributes, size_t attributesCount,
PBWindowRef _Nullable window);
Syntax (Python)
TextPlanCreate(contents, attributes, window) -> (textPlan)
Parameters and Return Values
[in] contents (referenced string): The text string. The system makes a copy of this string for the lifetime of the text plan.
[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.
[in] window (nullable referenced PBWindow): If non-null, this is used to determine the scale factor of the text. Otherwise, a scale factor of 100% is assumed. You should set this to the window into which the text will be drawn.
[out] textPlan (nullable owned PBTextPlan): The constructed text plan, or null if low on memory. This must be released with PBTextPlanRelease.
Discussion
You need to layout the text plan with PBTextPlanLayout before you can use it.
Example (C/C++)
PBPositionedTextAttribute attribute = {};
attribute.start = 6;
attribute.attribute.type = PBTextAttribute_WEIGHT;
attribute.attribute.f32 = 700.0f /* bold */;
PBTextPlan *plan = PBTextPlanCreate(PB_STR("hello world"),
&attribute, 1, window);
if (!plan) { return; }
PBTextPlanLayout(plan, 0, width, height);
PBDrawText(painter, plan, 0, 0, NULL);
PBTextPlanRelease(plan);
See Also
PBTextPlanSetRoleMappings
Function: Set the assignments that map text roles (PBTextRoleID) to text styles (PBTextStyle).
Syntax (C/C++)
void PBTextPlanSetRoleMappings(PBTextPlanRef textPlan,
const PBTextRoleMapping *_Nullable mappings, size_t mappingsCount);
Syntax (Python)
TextPlanSetRoleMappings(textPlan, mappings)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] mappings (referenced array of PBTextRoleMapping): The new array of mappings.
Discussion
You must call PBTextPlanLayout again after modifying the style lookup table.
If a role is used that is not in the mapping list, then the default style for that role is used.
PBTextPlanGetAdditionalScaleFactor
Function: Get the additional scale factor.
Syntax (C/C++)
float PBTextPlanGetAdditionalScaleFactor(PBTextPlanRef plan);
Syntax (Python)
TextPlanGetAdditionalScaleFactor(plan) -> (additionalScaleFactor)
Parameters and Return Values
[in] plan (referenced PBTextPlan): The text plan object.
[out] additionalScaleFactor (float):
Discussion
See PBTextPlanSetAdditionalScaleFactor.
PBTextPlanSetAdditionalScaleFactor
Function: Set an additional scale factor to change the text size.
Syntax (C/C++)
void PBTextPlanSetAdditionalScaleFactor(PBTextPlanRef plan,
float additionalScaleFactor);
Syntax (Python)
TextPlanSetAdditionalScaleFactor(plan, additionalScaleFactor)
Parameters and Return Values
[in] plan (referenced PBTextPlan): The text plan object.
[in] additionalScaleFactor (float): The additional scale factor. The default value is 1, corresponding to 100%.
Discussion
You must call PBTextPlanLayout again after modifying the additional scale factor.
PBTextPlanSetTabSize
Function: Set the distance between tab stops.
Syntax (C/C++)
void PBTextPlanSetTabSize(PBTextPlanRef plan, float tabSizeInDps);
Syntax (Python)
TextPlanSetTabSize(plan, tabSizeInDps)
Parameters and Return Values
[in] plan (referenced PBTextPlan): The text plan.
[in] tabSizeInDps (float): The distance between two adjacent tab stops in dps.
Discussion
You must call PBTextPlanLayout again after modifying the tab size.
PBTextPlanLayout
Function: Layout a text document into a rectangular bounding box.
Syntax (C/C++)
void PBTextPlanLayout(PBTextPlanRef textPlan, PBTextPlanLayoutFlags flags,
int32_t availableWidthPx, int32_t availableHeightPx);
Syntax (Python)
TextPlanLayout(textPlan, flags, availableWidthPx, availableHeightPx)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan to contain the resulting layout.
[in] flags (PBTextPlanLayoutFlags): Flags bitwise OR-ed together controlling the text layout operation.
[in] availableWidthPx (int32_t): The width of the rectangular bounding box in pixels. Set to 0 for infinite space (and thus preventing line wrapping or truncation).
[in] availableHeightPx (int32_t): The height of the rectangular bounding box in pixels. Set to 0 for infinite space.
Discussion
If the system detects that the new bounding box will not affect the existing layout in the text plan, this function will do nothing.
This function performs text shaping and then places the resulting glyphs into lines. If a line were to go off the right side of the box, it will either be truncated with an ellipsis character or wrap to a new line, depending on whether PBTextPlanLayout_ONE_LINE is set.
Once this function has been called, you can use the other text plan functions and PBDrawText.
See Also
PBTextPlanGetLineCount
Function: Get the number of lines in a text plan's layout.
Syntax (C/C++)
int32_t PBTextPlanGetLineCount(PBTextPlanRef textPlan);
Syntax (Python)
TextPlanGetLineCount(textPlan) -> (lineCount)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[out] lineCount (int32_t): The number of lines which the text document uses in this layout.
Discussion
You must call PBTextPlanLayout before calling this function.
Example (C/C++)
int32_t lineCount = PBTextPlanGetLineCount(plan);
See Also
PBTextPlanGetSize
Function: Get the size of a text plan's layout.
Syntax (C/C++)
PBSize PBTextPlanGetSize(PBTextPlanRef textPlan);
Syntax (Python)
TextPlanGetSize(textPlan) -> (size)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[out] size (PBSize): The returned width is the width of the widest line in the plan in pixels. The returned height is the distance from the top of the first line to the bottom of the last line in pixels.
Discussion
This function gives no information about where text glyphs may actually be drawn. Glyphs can extend outside the boundaries of the line on which they are placed. If you need to get a bounding box in which all glyphs fit, use PBTextPlanGetPaintBounds.
You must call PBTextPlanLayout before calling this function.
Example (C/C++)
PBSize size = PBTextPlanGetSize(plan);
See Also
PBTextPlanGetPaintBounds
Function: Get the bounding box containing all glyphs in a text plan.
Syntax (C/C++)
PBRectangle PBTextPlanGetPaintBounds(PBTextPlanRef textPlan, int32_t originX,
int32_t originY);
Syntax (Python)
TextPlanGetPaintBounds(textPlan, originX, originY) -> (rectangle)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] originX (int32_t): The x-coordinate of the origin that will be passed to PBDrawText when the text is drawn.
[in] originY (int32_t): The y-coordinate of the origin that will be passed to PBDrawText when the text is drawn.
[out] rectangle (PBRectangle): The bounding box, in pixels, into which glyphs will be drawn with PBDrawText.
Discussion
To obtain the size of the text plan in terms of layout metrics, use PBTextPlanGetSize.
You must call PBTextPlanLayout before calling this function.
Example (C/C++)
if (message->type == PBMsg_GET_PAINT_BOUNDS) {
PBRectangle bounds = PBElementGetBounds(element);
// Layout the text within the element.
PBTextPlanLayout(display->plan, layoutFlags, PB_RECT_WIDTH(bounds), PB_RECT_HEIGHT(bounds));
// Center the text.
PBSize textPlanSize = PBTextPlanGetSize(display->plan);
int32_t cx = element->bounds.l + (PB_RECT_HEIGHT(element->bounds) - textPlanSize.width) / 2;
int32_t cy = element->bounds.t + (PB_RECT_HEIGHT(element->bounds) - textPlanSize.height) / 2;
// Get the paint bounds.
message->getPaintBounds.bounds = PBTextPlanGetPaintBounds(display->plan, cx, cy);
}
See Also
PBTextPlanGetCaretBounds
Function: Get the bounds of a caret at the specified offset into the text.
Syntax (C/C++)
PBRectangle PBTextPlanGetCaretBounds(PBTextPlanRef textPlan, int32_t originX,
int32_t originY, uintptr_t caretTextIndex, float caretWidth);
Syntax (Python)
TextPlanGetCaretBounds(textPlan, originX, originY, caretTextIndex, caretWidth) -> (caretBounds)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] originX (int32_t): The x-coordinate of the origin that will be passed to PBDrawText when the text is drawn.
[in] originY (int32_t): The y-coordinate of the origin that will be passed to PBDrawText when the text is drawn.
[in] caretTextIndex (uintptr_t): The offset, in bytes, into the text document giving the caret's position.
[in] caretWidth (float): The width of the caret, in dps. See PBSystemProperty_CARET_THICKNESS.
[out] caretBounds (PBRectangle): The bounding box, in pixels, of the caret.
Discussion
You must call PBTextPlanLayout before calling this function.
See Also
PBTextPlanGetLineIndexFromOffset
Function: Get the index of the line containing the glyph with given byte offset.
Syntax (C/C++)
uintptr_t PBTextPlanGetLineIndexFromOffset(PBTextPlanRef textPlan,
uintptr_t textOffset);
Syntax (Python)
TextPlanGetLineIndexFromOffset(textPlan, textOffset) -> (lineIndex)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] textOffset (uintptr_t): The offset, in bytes, into the text document.
[out] lineIndex (uintptr_t): The index of the line, starting from 0, that contains the glyph found at the textOffset. If the textOffset is equal to the length of the document in bytes, then the lineIndex returned is the index of the last line in the plan.
Discussion
You must call PBTextPlanLayout before calling this function.
PBTextPlanGetOffsetFromLineIndex
Function: Get the byte offset at the start of the line for the given line index.
Syntax (C/C++)
uintptr_t PBTextPlanGetOffsetFromLineIndex(PBTextPlanRef textPlan,
uintptr_t lineIndex);
Syntax (Python)
TextPlanGetOffsetFromLineIndex(textPlan, lineIndex) -> (textOffset)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] lineIndex (uintptr_t): The index of the line. The first line in the plan has index 0.
[out] textOffset (uintptr_t): The offset, in bytes, into the text document for the first glyph on the line.
Discussion
You must call PBTextPlanLayout before calling this function.
PBTextPlanHitTest
Function: Find the byte offset of the nearest grapheme at a point in a text plan.
Syntax (C/C++)
uintptr_t PBTextPlanHitTest(PBTextPlanRef textPlan, int32_t x, int32_t y);
Syntax (Python)
TextPlanHitTest(textPlan, x, y) -> (index)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] x (int32_t): The x-coordinate of the point at which to look.
[in] y (int32_t): The y-coordinate of the point at which to look.
[out] index (uintptr_t): The nearest index to the position. This may be equal to the length of the string if the point is past the end of the last line.
Discussion
The result of this function is intended for repositioning a text caret when the mouse clicks in a text field.
You must call PBTextPlanLayout before calling this function.
Example (C/C++)
uintptr_t index = PBTextPlanHitTest(plan, message->mouse.x, message->mouse.y);
See Also
PBTextPlanGetLineBounds
Function: Get the vertical region that contains a specific line within the plan.
Syntax (C/C++)
void PBTextPlanGetLineBounds(PBTextPlanRef textPlan, uintptr_t lineIndex,
/* output */ int32_t * _Nullable __restrict yFrom,
/* output */ int32_t * _Nullable __restrict yBaseline,
/* output */ int32_t * _Nullable __restrict yTo);
Syntax (Python)
TextPlanGetLineBounds(textPlan, lineIndex) -> (yFrom, yBaseline, yTo)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[in] lineIndex (uintptr_t): The line index.
[optional-out] yFrom (int32_t): The top of the line, in pixels, from the top of the plan.
[optional-out] yBaseline (int32_t): The baseline of the line, in pixels, from the top of the plan.
[optional-out] yTo (int32_t): The bottom of the line, in pixels, from the top of the plan.
Discussion
You must call PBTextPlanLayout before calling this function.
Typically, yFrom <= yBaseline <= yTo, although depending on the font used unexpected values may occur.
PBTextPlanIsTruncated
Function: Test if some of the text was truncated with an ellipsis or similar.
Syntax (C/C++)
bool PBTextPlanIsTruncated(PBTextPlanRef textPlan);
Syntax (Python)
TextPlanIsTruncated(textPlan) -> (isTruncated)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[out] isTruncated (bool): True if the text was truncated; otherwise, false.
Discussion
You must call PBTextPlanLayout before calling this function.
See Also
PBTextPlanGetDocument
Function: Get the underlying text document that was used to create the text plan.
Syntax (C/C++)
PBTextDocumentPtr PBTextPlanGetDocument(PBTextPlanRef textPlan);
Syntax (Python)
TextPlanGetDocument(textPlan) -> (textDocument)
Parameters and Return Values
[in] textPlan (referenced PBTextPlan): The text plan object.
[out] textDocument (owned PBTextDocument): The text document.
Discussion
You must release the returned text document with PBTextDocumentRelease when you have finished using it.