TextArea

From Xojo Documentation
Jump to: navigation, search
For web applications, see WebTextArea.

Class (inherits from TextEdit)

A TextArea control can contain multiple lines of text and can display mixed fonts, font sizes, and styles. For single-line text fields, use the TextField control.

Events
Close GotFocus MouseUp
ConstructContextualMenu KeyDown MouseWheel
ContextualMenuAction KeyUp Open
DragEnter LostFocus SelChange
DragExit MouseDown TextChange
DragOver MouseEnter ValidationError
DropObject MouseExit
EnableMenuItems MouseMove


Properties
AcceptTabs ReadOnlyProperty.png LockLeft SelText
Active ReadOnlyProperty.png LockRight SelTextColor
Alignment LockTop SelTextFont
AutoDeactivate Mask SelTextSize
AutomaticallyCheckSpelling MouseCursor SelUnderline
BackColor MouseX ReadOnlyProperty.png Styled ReadOnlyProperty.png
Bold MouseY ReadOnlyProperty.png StyledText
Border ReadOnlyProperty.png MultiLine ReadOnlyProperty.png TabIndex
DataField Name TabStop
DataSource PanelIndex Text
Enabled Parent TextColor
Format ReadOnly TextFont
Handle ReadOnlyProperty.png Scope ReadOnlyProperty.png TextSize
Height ScrollPosition TextStyleData ReadOnlyProperty.png
HelpTag ScrollbarHorizontal ReadOnlyProperty.png TextUnit
HideSelection ScrollbarVertical ReadOnlyProperty.png Top
Index ReadOnlyProperty.png SelAlignment TrueWindow ReadOnlyProperty.png
Italic SelBold Underline
Left SelItalic UseFocusRing
LimitText SelLength Visible
LineHeight SelLength Width
LineSpacing SelPlain Window ReadOnlyProperty.png
LiveUpdate SelStart
LockBottom SelStart


Methods
AcceptFileDrop DrawInto ScrollPositionX
AcceptPictureDrop InsertionPosAtXY SelectAll
AcceptRawDataDrop Invalidate SetFocus
AcceptTextDrop LineNumAtCharPos SetString
AppendText Open SetTextAndStyle
CharPosAtLineNum Paste StyledTextPrinter
CharPosAtXY Refresh ToggleSelectionBold
Close RefreshRect ToggleSelectionItalic
Copy Save ToggleSelectionUnderline

Notes

Styled text can be printed using the StyledTextPrinter class. Styled text can also be managed independently of a TextArea using the StyledText class (see below for more information).

TextArea inherits from TextEdit, the base class for both TextArea and TextField. TextField is the single-line text control. TextEdit is an abstract class and it is not intended to be instantiated.

Working With Styled Text in TextAreas

In order to display styled text in a TextArea, the TextArea's Styled property must be True. Cocoa and Windows ignore the Styled property and allow styled text regardless of whether it is True or False.

The SelBold, SelTextColor, SelItalic, and SelUnderline properties can be used to both set the style of the selected text and get the style of the selected text These properties are set automatically at runtime when text is selected in a TextArea. 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 TextArea1, use this syntax<ref>On Carbon, if Styled is False, then SelBold sets everything to bold.</ref><ref>On Linux, if Styled is False, then SelBold does nothing.</ref>:

TextArea1.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 TextArea1.SelBold Then
Beep
End If

The SelBold, SelItalic, and SelUnderline properties 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 a TextArea contains more than one style, font, or font size 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 TextArea, 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 TextArea1.SelTextColor = White Then
TextArea1.SelTextColor = Black
End If

To print styled text in a TextArea, 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.

Execution order of MenuHandlers

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

Using the StyledText Class

With the StyledText class, you can manage styled text independently of a TextArea. 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.

When you create a StyledText object from the contents of a TextArea, the object that is returned is an alias, not a copy of the text. Therefore, subsequent changes to the StyledText object affect the contents of the TextArea. Consider the following example:

Dim t As StyledText
t = TextArea1.StyledText
t.Text = "This is the new TextArea text."
t.Bold(0, 4) = True

The assignment statement changes the contents of the TextArea and the last line sets the first word in the new text to Bold.

To display the styled text, you can assign the styled text object to the TextArea's StyledText property. Any programmatic changes to style attributes that you make while the styled text is displayed will update immediately.

Since the TextArea 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 TextArea.

For more information, see the StyledText class.

Masks

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
# The single digit placeholder. Entry optional. If this position is left blank in the mask, it will be rendered as a space. Plus and minus signs are allowed.

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', '?' (and so on) characters in the mask. The escapted character is treated as a literal (formatting) character.

& Character or space placeholder.

Valid values are the ASCII characters 32-126 and the non-ASCII characters 128-255.

C Character or space placeholder, where entry is optional. It operates like the '&' placeholder.
> 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 alphanumeric characters.

a Alphanumeric character placeholder, where entry is optional.
0 Any single digit between 0 and 9. Entry is required.
9 Digit or space where entry is optional.
? Alphabetic placeholder. Entry is optional.
L Alphabetic placeholder. Entry is required.
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:

TextArea1.Mask = "###-##-####" //US Social Security number
TextArea1.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:

TextArea1.Mask = ""

Adding Text to a TextArea

When appending text to a TextArea, you may notice some flicker as the TextArea is redrawn to show the new text. This will happen if you appended the Text property of the TextArea like this:

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

This occurs because the entire contents of the TextArea has to be redrawn. To avoid this flicker, call the AppendText method instead. Simply pass it the text to be appended. For example, this code reads an external text file into a TextArea using the Read method of the Readable class interface. The text is read in groups of 1000 characters until the end-of-file is reached.

Dim f As FolderItem
Dim i As Integer
Dim stream As BinaryStream
f = GetOpenFolderItem(FileTypes1.Text) // file type defined in File type set
If f <> Nil Then
stream = BinaryStream.Open(f, False)
Do
TextArea1.AppendText(stream.Read(1000, Encodings.UTF8))
Loop Until stream.EOF
stream.Close
End If

Text Encoding

TextAreas 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 TextArea 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 a TextArea. The Action event is passed an index parameter that indicates which control was clicked.

Sub Action (Index As Integer)
Select Case Index
Case 0
TextArea1.Alignment = TextArea.AlignDefault
Case 1
TextArea1.Alignment = TextArea.AlignLeft
Case 2
TextArea1.Alignment = TextArea.AlignCenter
Case 3
TextArea1.Alignment = TextArea.AlignRight
End Select

Drag and Drop

Dragging text between different TextAreas on a Window is supported automatically. Use the DragEnter, DragExit, DragOver and DropObject for more sophisticated handling of drag and drop.

Footnotes

<references />

Examples

Opening the text in a FolderItem into a TextArea.

Dim f as FolderItem
f = GetOpenFolderItem(FileTypes1.Text)
If f <> Nil Then
If Not TextArea1.Open(f) Then
MsgBox("Open failed")
End If
End If

The File Type Set defines the common file type, Text, and the GetOpenFolderItem call lets the user open the desired text document. The Open method returns a Boolean that is True if the Open operation was successful.

Saving the text in a TextArea to a FolderItem:

Dim f As FolderItem
f = GetSaveFolderItem(FileTypes1.Text, "Untitled")
If f <> Nil Then
If Not TextArea1.Save(f, False) Then
MsgBox("Save failed")
End If
End If

Saving is largely the mirror image of opening a text file. GetSaveFolderItem gets a FolderItem that's used to save the contents of the TextArea. The Save method then does the save, returning True if the save was successful. If you pass True as the second parameter of Save, then the styled text information will be saved.

See Also

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

Personal tools
Namespaces

Variants
Actions
Main
Content
Starting Out
Dig Deeper
More Help
Toolbox
About