AppleTextField - UBogun/Xojo-iosLib GitHub Wiki
Inherits from AppleControl
Memory leak check: not yet done.
Status: completed. (with the exception of TextInputProtocol)
This is an implementation of UITextField, better known to you as iOSTextField. It would be wrong to translate a TextField as "a view for text values". In fact, it contains many, partly optional subviews, a border and several more options than its Xojo representation.
The DrawRect, LayoutSubviews and WillMoveToWindow events of UIView are not available here.
General information
UIVIew Basics
The textfield is, like stated above, a container for several optional subviews: One on the left and one on the right side of the control. You can get the NSRects for these views (and the views themselves, or replace them) and use them for displaying icons or additional information. By replacing the views, you can even change their size and easily create a custom control like in this animation:
SwitchTextField
With the help of a resizable AppleImage, you can create your own custom controls by using the BackgroundImage and DiasbaledBackgroundimage properties.
Xojo integration
Many of the properties and methods built into AppleTextField are forwarded transparently and converted to Xojo classes by the iOSTextFieldExtension of iOSLib that integrates into each Xojo iOSTextField. See the remarks about integration in the AppleView class too.
For full access to events too, use the iOSLibTextField custom control.
Constructors
Constructor (aFrame As FoundationFramework.NSRect: Creates a TextField with the specified dimensions.
Properties
AdjustsFontSizeToFitWidth As Boolean: Whether the font size should be reduced in order to fit the text string into the text field’s bounding rectangle.
AllowsEditingTextAttributes As Boolean: Whether the user may edit the attributes of the text in the text field.
AttributedCaption As AppleAttributedString: The styled text displayed by the text field.
AttributedPlaceholder As AppleAttributedString: The styled string that is displayed when there is no other text in the text field.
AutoCapitalizationType As UITextAutocapitalizationType: The auto-capitalization style for the text object.
UITextAutocapitalizationType
| Value | Description |
|---|---|
| None | No autocapitalization |
| Words | Each word’s beginning character is capitalized |
| Sentences | The beginning of each sentence is capitalized |
| AllCharacters | All in capitals |
AutoCorrectionType As UITextAutoCorrectionType: The autocorrection style for the text object.
UITextAutoCorrectionType
| Value | Description |
|---|---|
| Default | Like system setting |
| No | No correction |
| Yes | Correction on |
BackgroundImage As AppleImage: The image that represents the background appearance of the text field when it is enabled.
BorderRect As FoundationFramework.NSRect (read-only): The receiver’s border rectangle. A shortcut for BorderRectForBounds (Bounds).
BorderStyle As UITextFieldBorderStyle: The border style used by the text field.
UITextFieldBorderStyle
| Value | Description |
|---|---|
| None | No border |
| Line |  |
| Bezel |  |
| RoundedRect |  |
Caption As Text: The text displayed by the text field.
ClearButtonMode As UITextFieldViewMode: When the standard clear button appears in the text field.
UITextFieldViewMode
| Value | Description |
|---|---|
| Never | View is never shown. |
| WhileEditing | View is shown when cursor is inside TextField. |
| UnlessEditing | View is shown unless cursor is inside TextField. |
| Always | View is permanently displayed. |
ClearButtonRect As FoundationFRamework.NSRect (read-only): The drawing rectangle for the built-in clear button. Shortcut for ClearButtonRectForBounds (Bounds).
ClearsOnEditBegin As Boolean: Whether the text field removes old text when editing begins.
ClearsOnInsertion As Boolean: Whether inserting text replaces the previous contents.
DefaultTextAttributes As AppleDictionary: The default attributes to apply to the text.
Delegate_ As AppleObject: The delegate for event handling, in this custom class the textfield itself.
DiasabledBackgroundImage As AppleImage: The image that represents the background appearance of the text field when it is not enabled.
Editing As Boolean (read-only): Whether the text field is currently in edit mode.
EditingRect As FoundationFRamework.NSRect (read-only): The control’s rectangle for editable text. Shortcut for EditingRectForBounds (Bounds).
EnablesReturnKeyAutomatically As Boolean: Whether the Return key is automatically enabled when the user is entering text.
Font As AppleFont: The font of the text.
KeyboardAppearance As UIKeyboardAppearance: The appearance style of the keyboard that is associated with the text object.
KeyboardType As UIKeyboardType: The keyboard style associated with the text object.
LeftView As AppleView: The overlay view displayed on the left (or leading) side of the text field.
LeftViewMode As UITextFieldViewMode: When the left overlay view appears in the text field.
LeftViewRect As FoundationFRamework.NSRect (read-only): The drawing rectangle of the control’s left overlay view. Shortcut for LeftViewRectForBounds (Bounds).
MinimumFontSize As Double: The size of the smallest permissible font with which to draw the text field’s text.
Placeholder As Text: The string that is displayed when there is no other text in the text field.
PlaceholderRect As FoundationFRamework.NSRect (read-only): The drawing rectangle for the text field’s placeholder text. Shortcut for PlaceholderRectForBounds (Bounds).
ReturnKeyType As UIReturnKeyType: The visible title of the Return key.
RightView As AppleView: The overlay view displayed on the right (or trailing) side of the text field.
RightViewMode As UITextFieldViewMode: When the left overlay view appears in the text field.
RightViewRect As FoundationFRamework.NSRect (read-only): The drawing location of the field's right overlay view. Shortcut for RightViewRectForBounds (Bounds).
Secure As Boolean: Identifies whether the text object should hide the text being entered.
SpellcheckingType As UITextSpellCheckingType: The spell-checking style for the text object.
TextAlignment As NSTextAlignment: The technique to use for aligning the text.
TextColor As AppleColor: The Color of the text.
TextRect As FoundationFramework.NSRect (read-only): The drawing rectangle for the text field’s text. Shortcut for TextRectForBounds (Bounds).
TypingAttributes As AppleDictionary: The attributes to apply to new text being entered by the user.
Methods
BorderRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the control’s border rectangle.
ClearButtonRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the drawing rectangle for the built-in clear button.
DrawText (Rect as Foundationframework.NSRect): Draws the field's text in the specified rectangle (if a context exists).
EditingRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the rectangle in which editable text can be displayed.
LeftViewRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the drawing rectangle of the field's left overlay view.
PlaceholderRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the drawing rectangle for the text field’s placeholder text.
RightViewRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: Returns the drawing rectangle of the field's right overlay view.
TextRectForBounds (Bounds As FoundationFramework.NSRect) As FoundationFramework.NSRect: The drawing rectangle for the text field’s text.
Events
DidBeginEditing(): The user has started an editing session, in other words, tapped on the textfield to enter or change text content.
DidEndEditing(): The user has finished modifying the text content.
ShouldBeginEditing() As Boolean: Use this event in cases where you want to avoid user modifications to the text. Return True to NOT start editing.
ShouldChangeCharactersInRange (Start as UInteger, Length as UInteger, Replacement as Text) As Boolean: The user wants to replace the text at position/length of the textfield with Replacement. Return True if you want to deny this.
ShouldClear() As Boolean: Return True if the text should not be cleared.
ShouldEndEditing() As Boolean: Return true if you do not want the editing session to end.
ShouldReturn() As Boolean: Return true if you want to suppress a hit on the Return button.