Text Controls

You can display text in your applications either manually with PBDrawText in a custom element, or by using a standard text control.

There are 4 standard text controls provided by libplaybit: PBTextDisplay, PBInputField, PBVirtualTextView and PBLogView.

PBTextDisplay displays formatted text. The user cannot edit the text, but can select and copy it (unless text selection is disabled for that control). The text can either be word-wrapped or truncated to fit the size of the control. The contents of the display can be set from a string containing the text, and an array containing the formatting attributes. Alternatively, the contents can be directly set with a PBTextDocument. Text documents can contain a wide array of formatting features, such as bulleted lists and embedded images, all of which are supported.

PBInputField displays editable text. Currently, it only supports a single line of non-formatted text. It may be extended in the future to support multiple lines as well as formatted text. It must be wrapped inside a PBScrollView, which allows the user to horizontally scroll the text.

PBVirtualTextView efficiently displays monospaced text with minimal formatting and no word-wrapping. The user cannot edit the text, but can select and copy it. Only some formatting features are supported, such as changing the text color and weight. The application supplies the text contents to the control with an on demand callback, on a per-line basis.

PBLogView is designed for inspecting debugging logs as they are produced. The application can efficiently append text or clear the contents. Internally, it uses a circular buffer to store the most recent text added to it. Only minimal formatting is supported.

Using PBTextDisplay

To create a PBTextDisplay, use PBTextDisplayCreate. Pass PBTextDisplay_PREFORMATTED to preserve whitespace. Pass PBTextDisplay_ONE_LINE to prevent word-wrapping and instead use line truncation with an ellipsis. Pass PBTextDisplay_ALLOW_SELECTION to allow the user to select text.

Alternatively, it can be created with PBTextDisplayCreateLabel. This enables various features for "text labels" that work well with other UI elements. The contents of a label should be changed with PBTextDisplaySetLabel. Labels do not support text formatting.

The contents of a text display can be set in various ways. See PBTextDisplaySetContents, PBTextDisplaySetContentsWithPositionedAttributes, PBTextDisplaySetContentsWithRangedAttributes and PBTextDisplaySetDocument.

For text displays that are wrapped in a scroll view and are displaying complex text documents, the scroll position can be managed with PBTextDisplayEnsureNodeVisible and PBTextDisplayFindTextNodeAtTopOfRectangle.

For text displays where text selection is enabled, the selection can be managed with PBTextDisplaySelect and PBTextDisplayGetSelection.

For text displays where the document uses role-based text styling, the roles can be mapped to actual text styles using PBTextDisplaySetRoleMappings.

The entire contents of a text display can be scaled using PBTextDisplaySetAdditionalScaleFactor.

Hyperlinks can be displayed using PBTextAttribute_HYPERLINK. When a hyperlink is clicked, the text display is sent a PBMsg_HYPERLINK_CLICKED message, which can be handled by the application using PBElementSetUserMessageHandler.

If a text document is loaded that contains image references, the text display is sent PBMsg_GET_IMAGE messages to resolve them to PBImage objects. These messages can be handled by the application using PBElementSetUserMessageHandler.

Using PBInputField

An input field and its wrapping scroll view can be created with the single function PBInputFieldCreateSingleLine. The second argument contains the flags for the scroll view; this is where you should pass flags like PBElement_H_FILL. The third argument contains the flags for the input field; this is where you should pass flags like PBInputField_SELECT_ALL_ON_FOCUS. If you want to destroy the input field, you should pass the wrapping scroll view to PBElementDestroy; if the input field itself is passed, then an empty scroll view will be leftover. The scroll view has an appropriate graphical border to indicate the function of the input field to the user.

When the user modifies the text in the input field, a PBMsg_VALUE_CHANGED message is sent to the field (not the wrapping scroll view). This message can be handled by the application using PBElementSetUserMessageHandler.

The text in the input field can be retrieved with PBInputFieldGetContents and modified with PBInputFieldSetContents. The returned string from PBInputFieldGetContents should be freed with PBHeapFree. The system keeps its own copy of the string passed to PBInputFieldSetContents, so the application need not worry about keeping it in memory.

The application can insert text at the caret or replace the selected text using the PBInputFieldReplace function. This function can optionally send the PBMsg_VALUE_CHANGED message.

The text selection and caret position can be modified with PBInputFieldSelect, PBInputFieldSelectAll and PBInputFieldMoveCaretToEnd.

A hint indicating the purpose of the input field can be displayed when the field is empty. The text of this hint is set by the application with PBInputFieldSetPlaceholderHint.

Using PBVirtualTextView

The API for PBVirtualTextView has not been finalized and as such it is not yet discussed here.

Using PBLogView

To create a log view, first the application must create a scroll view to wrap it using PBScrollViewCreate. Then the log view may be created with PBLogViewCreate. Pass PBLogView_ALLOW_SELECTION to make the text inside the control selectable.

After any batch of changes to the contents of the log view, you must call PBLogViewRefresh.

Data can be appended to the log view with PBLogViewAppend. The passed PBLogViewAttribute determines the weight and color of the character. The low 3 bits give the color. For a multi-byte UTF-8 encoded value, this function must be called multiple times.

The contents of the log view can be cleared with PBLogViewClear or retrieved with PBLogViewGetContents.

You can insert a large amount of input data with PBLogViewProcessInput. Pass PBLogViewProcessInput_PARSE_ANSI_ESCAPE_SEQUENCES to automatically determine the color of the inserted text using ANSI control sequences.

The style of the text in the log view can be retrieved and modified with PBLogViewGetTextStyle and PBLogViewSetTextStyle respectively. Due to the limiting text formatting capabilities of the log view, the main use of these functions are for changing the size of the text. The weight and color of the text are always overridden.

Each line in the log view is assigned a unique identifier. These identifiers are not reused even when a line is removed from the log view's buffer to make room for a new line. The identifier of the most recently inserted line can be obtained with PBLogViewGetCurrentRowIndex. To scroll a particular line into view, use PBLogViewScrollToRowByIndex, passing its identifier.