v0.8.0
⌘P
Go-to Page: ⌘G

Guide

All UI Elements
App Bundles
libplaybit API Conventions
Standard UI Layout
Text Controls
Text Styling

API Reference

Accessibility and Automation
Alerts
Buttons
Checkboxes
Clipboard
Colors
Commands and Command Lists
Common Definitions
Configuration
Data Streams
Display Screens
Drag and Drop
Drawing
Element Hierarchy
Element Interaction
Element Layout and Painting
Element Messaging
Element Properties
Element User Data
Event Loop
File Editors
File Pickers
Handoff
Image Displays
Images
Input Devices
Layout Columns and Rows
Layout Grids
Layout Wraps
Log Views
Notifications
Pop-Up Buttons
Progress Indicators
Radio Button Groups
Rectangles
Render Surfaces
Resizable Panels
Run-time Helpers
Scrolling
Shared Nodes
Size Constraint Panels
Sliders
Styling
Table Views
Text Displays
Text Documents
Text Input Fields
Text Plans
Text Styles
Tool Tips
Transition Panels
Value Stores
Virtual Text Views
Windows
Workspace IPC

Text Input Fields

PBInputField

Opaque object handle: An element in which the user can edit a line of text. When the user modifies the text in the field, a PBMsg_VALUE_CHANGED message is sent to it.

This is a subclass of PBElement. You can safely cast from PBInputField to PBElement. To cast from PBElement to PBInputField, call PBInputFieldCast; 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.

PBInputFieldFlags

Enumeration/bitset of type uint32_t: Flags controlling the behavior and appearance of a text input field.

Constants

PBInputField_READ_ONLY

PBInputField_READ_ONLY = 1<<0

The text in the field cannot be modified by the user. The application can still modify it using the API calls. The user can still select and copy the text.

PBInputField_SELECT_ALL_ON_FOCUS

PBInputField_SELECT_ALL_ON_FOCUS = 1<<1

When the input field element takes keyboard focus, it should select all the text inside it automatically.

PBInputField_MULTI_LINE

PBInputField_MULTI_LINE = 1<<2

Allow multiple lines of text in the field.

PBInputField_SHOW_SELECTION_WHEN_UNFOCUSED

PBInputField_SHOW_SELECTION_WHEN_UNFOCUSED = 1<<3

By default, the text selection is only shown when the input field has keyboard focus. Setting this flag will cause the selection to always be shown, regardless of whether it has focus.

PBInputField_NO_UNDO

PBInputField_NO_UNDO = 1<<4

Do not process undo and redo within the input field.

Or any of the values from PBElementFlags.

PBMessageInputFieldProposeChange

Structure: A proposed change to the content's of the field.

Fields

[in] textToInsert (referenced string): The text that will be inserted at the caret, after deleting the selected text.

[in] valueChangedMessageCanBeSent (bool): Whether a PBMsg_VALUE_CHANGED message can be sent after the change is made. If the change is not made (for example, if the system is low on memory), then the PBMsg_VALUE_CHANGED message will not be sent, even if this field is set to true. Regardless, a PBMsg_VALUE_CHANGED message, if it is sent, will always be preceeded by a PBMsg_INPUT_FIELD_PROPOSE_CHANGE message.

allow (bool): Set to whether the change should be processed. Defaults to true.

See Also

PBInputFieldCreate

Function: Reserved.

Syntax (C/C++)

PBInputFieldPtr _Nullable PBInputFieldCreate(PBScrollViewRef parent, 
    PBInputFieldFlags flags);

Syntax (Python)

InputFieldCreate(parent, flags) -> (inputField)

Parameters and Return Values

[in] parent (referenced PBScrollView):

[in] flags (PBInputFieldFlags):

[out] inputField (nullable owned PBInputField):

Discussion

Use PBInputFieldCreateSingleLine instead.

PBInputFieldCreateSingleLine

Function: Create a text input field and wrapping scroll view for editing a single line of text.

Syntax (C/C++)

PBInputFieldPtr _Nullable PBInputFieldCreateSingleLine(PBElementRef parent, 
    PBScrollViewFlags scrollViewFlags, PBInputFieldFlags inputFieldFlags, 
    /* output */ PBScrollViewPtr _Nullable * _Nullable __restrict scrollView);

Syntax (Python)

InputFieldCreateSingleLine(parent, scrollViewFlags, inputFieldFlags) -> (inputField, scrollView)

Parameters and Return Values

[in] parent (referenced PBElement): The parent element to which the scroll view will be added.

[in] scrollViewFlags (PBScrollViewFlags): The element flags for the scroll view.

[in] inputFieldFlags (PBInputFieldFlags): The element flags for the input field, which is added to the scroll view.

[out] inputField (nullable owned PBInputField): The created input field. Its parent is the scroll view.

[optional-out] scrollView (nullable owned PBScrollView): The created scroll view. Its parent is the passed parent element parameter.

Discussion

This function creates two elements in one call. A scroll view is created and added to the given parent element parameter. Then, an input field is created and added to the scroll view as the scrolled content.

The scroll view is given an appropriate bordered appearance for the provided flags. In particular, the flag PBInputField_READ_ONLY gives a different appearance.

Since two elements are created by this call, the developer must take care to use the correct element in each situation. For example, to remove the input field from the window, the containing scroll view should be passed to PBElementDestroy. This will destroy both elements. If the input field were passed, then the scroll view would not be destroyed. On the other hand, all the input field specific operations like PBInputFieldGetContents will take the pointer to the input field element.

The input field begins with no text in it.

See Also

PBInputFieldCreateSingleLineReadOnly

Function: Create a read-only text input field and wrapping scroll view for a single line of text.

Syntax (C/C++)

PBInputFieldPtr _Nullable PBInputFieldCreateSingleLineReadOnly(
    PBElementRef parent, PBScrollViewFlags scrollViewFlags, 
    PBInputFieldFlags inputFieldFlags, ConstStr contents, 
    /* output */ PBScrollViewPtr _Nullable * _Nullable __restrict scrollView);

Syntax (Python)

InputFieldCreateSingleLineReadOnly(parent, scrollViewFlags, inputFieldFlags, contents) -> (inputField, scrollView)

Parameters and Return Values

[in] parent (referenced PBElement): The parent element to which the scroll view will be added.

[in] scrollViewFlags (PBScrollViewFlags): The element flags for the scroll view.

[in] inputFieldFlags (PBInputFieldFlags): The element flags for the input field, which is added to the scroll view.

[in] contents (referenced string): A string giving the initial text contents of the field.

[out] inputField (nullable owned PBInputField): The created input field. Its parent is the scroll view.

[optional-out] scrollView (nullable owned PBScrollView): The created scroll view. Its parent is the passed parent element parameter.

Discussion

This is a convenience function that uses PBInputFieldCreateSingleLine to create a read-only input field and set its initial contents. Both flags PBInputField_READ_ONLY and PBInputField_SELECT_ALL_ON_FOCUS are set.

See Also

PBInputFieldGetContents

Function: Get the text contents of an input field.

Syntax (C/C++)

MutStr PBInputFieldGetContents(PBInputFieldRef inputField);

Syntax (Python)

InputFieldGetContents(inputField) -> (string)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[out] string (owned string): A copy of the field's contents.

Discussion

As the input field is modified further, the returned string will not change.

The returned string must be freed with PBHeapFree when it is no longer needed.

The returned string is in UTF-8 and is not zero-terminated.

See Also

PBInputFieldIsEmpty

Function:

Syntax (C/C++)

bool PBInputFieldIsEmpty(PBInputFieldRef inputField);

Syntax (Python)

InputFieldIsEmpty(inputField) -> (isEmpty)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[out] isEmpty (bool): True if the input field is empty, i.e. its contents has a length of 0 bytes.

See Also

PBInputFieldSetContents

Function: Set the contents of the input field, removing the old contents.

Syntax (C/C++)

void PBInputFieldSetContents(PBInputFieldRef inputField, ConstStr string, 
    bool sendValueChangedMessage);

Syntax (Python)

InputFieldSetContents(inputField, string, sendValueChangedMessage)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[in] string (referenced string): A UTF-8 string giving the new contents of the field.

[in] sendValueChangedMessage (bool): If true, a PBMsg_VALUE_CHANGED message will be sent to the field after the contents have been updated.

Discussion

Any text selection is removed and the text caret is moved to the start of the field.

The system keeps its own copy of the field's contents.

If this is a single-line input field, then any newline characters will be stripped from the input string.

This clears the undo stack.

See Also

PBInputFieldReplace

Function: Delete the selected text (if any), and insert a new string at the caret's position.

Syntax (C/C++)

void PBInputFieldReplace(PBInputFieldRef inputField, ConstStr string, 
    bool sendValueChangedMessage);

Syntax (Python)

InputFieldReplace(inputField, string, sendValueChangedMessage)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[in] string (referenced string): The string to insert after removing the selected text.

[in] sendValueChangedMessage (bool): If true, a PBMsg_VALUE_CHANGED message will be sent to the field after the contents have been updated.

Discussion

If there is selected text, that text is deleted. Then the provided string is inserted. If no text was selected, then no text is deleted and the provided string is inserted.

The caret is moved to the end of the inserted text.

If this is a single-line input field, then any newline characters will be stripped from the input string.

This pushes a new entry on the undo stack.

See Also

PBInputFieldSelectAll

Function: Select all the text in the input field.

Syntax (C/C++)

void PBInputFieldSelectAll(PBInputFieldRef inputField);

Syntax (Python)

InputFieldSelectAll(inputField)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

See Also

PBInputFieldMoveCaretToEnd

Function: Move the caret to the end of the input field.

Syntax (C/C++)

void PBInputFieldMoveCaretToEnd(PBInputFieldRef inputField);

Syntax (Python)

InputFieldMoveCaretToEnd(inputField)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

Discussion

This clears any previous selection.

See Also

PBInputFieldSelect

Function: Set the selected range of text in the input field.

Syntax (C/C++)

void PBInputFieldSelect(PBInputFieldRef inputField, uintptr_t from, uintptr_t to);

Syntax (Python)

InputFieldSelect(inputField, from, to)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[in] from (uintptr_t): The position of the new selection's anchor, in bytes from the start of the contents.

[in] to (uintptr_t): The position of the new selection's caret, in bytes from the start of the contents.

See Also

PBInputFieldSetPlaceholderHint

Function: Set a hint that will be displayed when the input field is empty.

Syntax (C/C++)

void PBInputFieldSetPlaceholderHint(PBInputFieldRef inputField, ConstStr string);

Syntax (Python)

InputFieldSetPlaceholderHint(inputField, string)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[in] string (referenced string): The hint to be displayed.

Discussion

The hint will be displayed in a different text style than the input field's contents, to indicate to the user that it is not the actual contents.

See Also

PBInputFieldGetSelection

Function: Get the selected range of text in the input field.

Syntax (C/C++)

void PBInputFieldGetSelection(PBInputFieldRef inputField, 
    /* output */ uintptr_t * _Nullable __restrict anchor, 
    /* output */ uintptr_t * _Nullable __restrict caret);

Syntax (Python)

InputFieldGetSelection(inputField) -> (anchor, caret)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field element.

[optional-out] anchor (uintptr_t): The position of theselection anchor, in bytes from the start of the text. All the bytes between the selection anchor and the caret are selected.

[optional-out] caret (uintptr_t): The position of the caret, in bytes from the start of the text. This is where the vertical insertion point line is drawn in the text.

PBInputFieldSetTextStyle

Function: Sets the style of text displayed in the input field.

Syntax (C/C++)

void PBInputFieldSetTextStyle(PBInputFieldRef inputField, 
    PBTextStyleRef textStyle);

Syntax (Python)

InputFieldSetTextStyle(inputField, textStyle)

Parameters and Return Values

[in] inputField (referenced PBInputField): The input field object.

[in] textStyle (referenced PBTextStyle): The new text style to use. The text style's color is ignored; see the discussion.

Discussion

The input field is automatically redrawn after changing the text style. The input field maintains its own reference to the text style, which will be automatically freed when the input field is destroyed.

The appearance of the input field determines the color of its text. Therefore, regardless of the text color specified in the text style, the input field's colors will be unchanged.

PBInputFieldSetTabSize

Function: Set the distance between tab stops.

Syntax (C/C++)

void PBInputFieldSetTabSize(PBInputFieldRef field, float tabSizeInDps);

Syntax (Python)

InputFieldSetTabSize(field, tabSizeInDps)

Parameters and Return Values

[in] field (referenced PBInputField): The input field.

[in] tabSizeInDps (float): The distance between two adjacent tab stops in dps.