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.