RectControl → Control → Object

EditField Class

The standard editable text field. An EditField control may contain one line of text or multiple lines of text, depending on the value of the MultiLine property.

Events
GotFocus
KeyDown
LostFocus
MouseDown
MouseUp
SelChange
TextChange
ValidationError

Properties
AcceptTabs | ReadOnly | SelText
Alignment | ScrollbarHorizontal | SelTextColor
BackColor | ScrollbarVertical | SelTextFont
Bold | ScrollPosition | SelTextSize
Border | ScrollPositionX | SelUnderline
DataField | SelAlignment | Styled
DataSource | SelBold | StyledText
Format | SelCondense | Text
Italic | SelExtend | TextColor
LimitText | SelItalic | TextFont
LiveUpdate | SelLength | TextSize
Mask | SelOutline | TextStyleData
MultiLine | SelShadow | Underline
Password | SelStart | UseFocusRing

Methods
AppendText | Paste | ToggleSelectionCondense
BindValue | SelectAll | ToggleSelectionExtend
CharPosAtLineNum | SetFocus | ToggleSelectionItalic
CharPosAtXY | SetTextAndStyle | ToggleSelectionOutline
Copy | StyledTextPrinter | ToggleSelectionShadow
LineNumAtCharPos | ToggleSelectionBold | ToggleSelectionUnderline

# Notes

Text may either be of only one font, font size, and style or mixed fonts, font sizes, and styles ("Styled Text") depending on the value of the Styled property. Styled text can be printed using the StyledTextPrinter class. Styled text can also be managed independently of an EditField using the StyledText class.

Because this is a RectControl, see the RectControl for other properties and events that are common to all RectControl objects.

## Working With Styled Text in EditFields

In order to display styled text in an EditField, the EditField's Styled property must be checked. The SelBold, SelTextColor, SelCondense, SelExtend, SelItalic, SelOutline, SelShadow and SelUnderline properties can be use to both set the style of the selected text and get the style of the selected text (The Outline, Shadow, Condense, and Extend styles are available only on Mac OS 8-9). These properties are set automatically by REALbasic at runtime when text is selected in an EditField. To set the style, simply assign True to the property. For example, if you want to add the bold style to the selected text in EditField1, use this syntax:

EditField1.SelBold= True

You can determine if the selected text is in a particular style using the same property. The following code plays a beep sound if the selected text is bold:

If EditField1.SelBold Then
Beep
End If

The SelBold, SelCondense, SelExtend, SelItalic, SelOutline, SelShadow and SelUnderline will be True if all of the selected characters are in the style being checked. Otherwise, these properties will be False.

Getting and setting the selected text font and font size work the same way using the SelTextFont and SelTextSize properties. To set the font of the selected text, set the SelTextFont property to the name of the font. If the selected text uses more than one font, SelTextFont will be an empty string. If the selected text has more than one font size, the SelTextSize property will be zero.

If the selected text has more than one style, font, or size, you can select individual characters using the SelStart and SelLength properties to determine which styles, fonts, and sizes are in use. Please note that if an EditField contains more than one style, font, or fontsize and you reassign the value of the Text property, you will lose the styled formatting of the text substrings. All the text will then be styled uniformly. To update the text in a styled EditField, it is safest to use the SelStart, SelLength, and SelText properties to update text selections.

You can also get and set the color of the selected text using the SelTextColor property. for example, the following code checks to see if the selected text is white and if it is, sets it to black:

Dim White, Black as Color
White= RGB(255,255,255)
Black= RGB(0,0,0)
If EditField1.SelTextColor=White Then
EditField1.SelTextColor=Black
End If

To print styled text in an EditField, use the StyledTextPrinter method to create a StyledTextPrinter object and then use the StyledTextPrinter's DrawBlock method. See the description of StyledTextPrinter for an example. There is also an example of styled text printing in the Tutorial lesson on styled text.

## Execution order of MenuHandlers

The intrinsic control menu handlers (such as EditField.SelectAll) are now handled after any user-defined menu handlers on the EditField subclass (if it was subclassed). This means that if you have a SelectAll handler on the Window of the EditField, it will no longer be called when the EditField has focus, because the EditField will now handle it first. In this situation, create an EditField subclass that defines its own SelectAll handler, and handle the desired behavior there.

## Mac OS "classic" Text Styles

The following styles are nonstandard and are supported only on Mac OS "classic": Outline, Shadow, Condensed, and Extended.

## Single-line EditFields

Single-line EditFields on Mac OS "classic" have a limit of 32K of text. They also support character codes above ASCII 127 and the Symbol font.

## Using the StyledText Class

With the StyledText class, you can manage styled text independently of an EditField. The styled text is contained in the Text property of the StyledText object and its style attributes can be set via its Bold, Italic, Underline, Font, Size, and TextColor methods. To display the styled text, you can assign the styled text object to the EditField's StyledText property. Any programmatic changes to style attributes that you make while the styled text is displayed will update immediately.

Since the EditField has its own properties for getting and setting style attributes for selected text, those attributes are respected by the StyledText object while it is displayed in the EditField.

For more information, see the StyledText class.

## Input Entry Filters

Use the Mask property to filter user input on a character-by-character basis and add formatting characters. For example, a mask for a Telephone number field can add parentheses, spaces, and dashes as literals, that are used for formatting, and the digit mask symbol '#' to restrict entry to numbers only.

The following table shows the characters that you can use to define a mask.

Mask Character | Description
--- | ---
# | Any single digit placeholder. The user can type only a digit character in this position.
. | Decimal placeholder. The decimal placeholder that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes.
, | Thousands separator. The thousands separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes.
: | Time separator. The time separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes.
/ | Date separator. The date separator that is actually used is specified in the user's International settings. The character is treated as a literal (formatting) character for masking purposes.
\ | Mask escape character: Treat the next character in the mask as a literal. The escape character enables you to use the '#', '&', 'A', '?' (an so on) characters in the mask. The escapted character is treated as a literal (formatting) character.
& | Character placeholder. Valid values are the ASCII characters 32-126 and the non-ASCII characters 128-255.
> | Convert all the characters that follow to uppercase. Uppercasing works beyond the ASCII range where appropriate, e.g., ü becomes Ü.
< | Convert all the characters that follow to lowercase. Lowercasing works beyond the ASCII range where appropriate, e.g., Ü becomes ü.
A | Alphanumeric character placeholder, where entry is mandatory. For example, the spec "AAA" specifies three alphabetic characters.
a | Alphanumeric character placeholder, where entry is optional.
9 | Digit placeholder where entry is optional.
C | Character or space placeholder, where entry is optional. It operates like the '&' placeholder.
? | Alphabetic placeholder.
Any literal | All other symbols are displayed as literals for formatting purposes.
~ | Reserved for future use. If you use "~" it will trigger an exception error. Use \~ instead.

Here are some examples:

EditField1.Mask="###-##-####" //US Social Security number
EditField1.Mask="(###) ###-####" //US Phone number, with area code

If the user tries to enter a character that is prohibited by the mask, a ValidationError event occurs. The character that the user attempted to enter and the character position is passed to the ValidationError event, where you can handle the keystroke as you like.

To cancel the Mask, set it to the empty string:

EditField1.Mask=""

## Adding Text to an EditField

When appending text to an EditField, you may notice some flicker as REALbasic redraws the EditField to show the new text. This will happen if you appended the Text property of the EditField like this:

EditField1.Text=EditField1.Text+"my new text"

This occurs because the entire contents of the EditField has to be redrawn. To avoid this flicker, position the cursor at the end of the EditField and append the text using the SelText property like this:

EditField1.SelStart= Len(EditField1.Text)
EditField1.SelText="my new text"

## Text Encoding

EditFields store all text internally in Unicode, which is able to represent a mixture of characters from different writing systems. When you extract the text via the Text or SelText properties, this text is returned in UTF-8.

## Using Class Constants

The following class constants are available to set paragraph alignments. Set the alignment of the entire contents of the EditField by assigning a constant to the Alignment property.

Value | Class Constant
--- | ---
0 | AlignDefault
1 | AlignLeft
2 | AlignCenter
3 | AlignRight

For example, the following code in the Action event of a control array sets the alignment of the text in an EditField. The Action event is passed an index parameter that indicates which control was clicked.

Sub Action (Index as Integer)
Select Case Index
Case 0
EditField1.Alignment=EditField.AlignDefault
Case 1
EditField1.Alignment=EditField.AlignLeft
Case 2
EditField1.Alignment=EditField.AlignCenter
Case 3
EditField1.Alignment=EditField.AlignRight
End Select

# See Also

Font, FontCount functions; Paragraph, Range, StyleRun, StyledText, StyledTextPrinter classes.