Text

The Text component provides a simple text editing field. This may be a single-line or multi-line text field. It may handle up to 2K characters of text.

Text Looks

The following looks are available:

0 Default Text. A plain text area.

1 PCV Edit. Carriage return characters visible.

Text Properties

Standard Properties:
class, enabled, focusState, height, left, look, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.
width, height: changing either one of these properties causes a the text to redraw.
sizeHControl, sizeVControl: Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED will be supported. SIZE_AS_NEEDED will only be partially supported: when the component becomes visible and their height or width is zero, the component will size itself to a default value.

bgColor long
Color to use when drawing the background. The following constants are available:
RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see See Color .

color long
Color to use when drawing foreground text. The following constants are available
RED, YELLOW, BLACK, WHITE, GRAY_50, LIGHT_BLUE, DARK_BLUE, LIGHT_CYAN, DARK_CYAN, LIGHT_GREEN, DARK_GREEN, LIGHT_ORANGE, DARK_ORANGE, LIGHT_PURPLE, DARK_PURPLE, LIGHT_GRAY, DARK_GRAY. For more information about colors, see See Color .
Note that if you are using a custom color that is not fully opaque, it will be treated as if it were fully opaque.

endSelect integer (startSelect-numChars)
This read-only property is the offset of the end of the range of text the user has selected, or -1 if there is no insertion point. If endSelect is the same as startSelect, then they are both the offset of the insertion point. Use the SetSelectionRange() action to change this value.

filter integer (0-)
Filter to use when accepting characters. The following filters are supported:
0 No filter
1 Custom: generate _filterChar() events.
32 Numeric characters only
36 Alphanumeric: alphabetic and numeric characters
42 Dashed alphanumeric: alphanumeric and "-"
If you assign a value to this property corresponding to a filter not supported on the platform, the value will be ignored.

firstVisibleLine integer (0-numLines-1)
The line number of the first line of text currently showing in the text object.

font string
Use " ."

fontSize integer (12)
The size of font.

fontStyle integer
The style to use when drawing text:
32 Boldface
0 Plain

lastVisibleLine integer (0-numLines-1)
The line number of the last currently-visible line of text in the text object.

maxChars integer (0-2K)
The maximum number of characters that the component will hold. If you try to set this to less than the current number of characters, the component will generate an error. You cannot use this property to truncate your component's text. If you want to truncate your text, use the DeleteRange() action instead.

maxLines integer (0-2K)
The maximum number of lines the text component can store. A value of zero means that there is no limit (other than that imposed by maxChars). Note that setting a non-zero value for this property results in slower performance for a large number of text operations, including adding new text.

numChars integer (0-2K)
The number of characters in text. This is a read-only property.

numLines integer (0-2K)
The number of lines of text stored in the text. This might be more than the number of lines currently showing.

readOnly integer (0-1)
Normally, this flag will be zero; if it is one, then the user will not be able to interact with the component. On some platforms, the user will be able to select text in the component, but not to change the text.

To change this property using NewBuild, change the Read Only option in the General area of the Component Properties box and press the Apply button.

startSelect integer (-1-numChars)
This read-only property is the offset of the start of the range of text the user has selected, or -1 if there is no insertion point. Use the SetSelectionRange() action to change this value.

text string
The string of text displayed.

wordWrap integer (0-1)
This flag is ignored; word-wrapping is not supported.

Text Events

_filterChar()

_filterChar( self AS entry, newChar AS integer, replaceStart AS integer, replaceEnd AS integer, endOfGroup AS integer ) AS integer

This event is generated when the user enters a character into the text and the filter property is 1. If the user pastes a multiple-character string into the Text, it will generate one _filterChar() event for each character in the string. The endOfGroup argument signals that this is the last character of such a multi-character string.

The event handler should return the Unicode value of the character to insert in the string, or zero to specify that no character should be inserted at this time.

Pass:

self text
The Text component experiencing the event.

newChar integer
The Unicode value of the character entered.

replaceStart integer (0-numChars)
Offset of the start of the range of characters being replaced.

replaceEnd integer (replaceStart-numChars)
Offset of the end of the range of characters being replaced. If this is the same as replaceStart, then no characters are being replaced; this is the offset of the insertion point.

endOfGroup integer (0-1)
This argument is one if this character is the last character of a multi-character insert (or the only character of a single-character insert). It is zero otherwise.

_focusChanged()

_focusChanged( self AS text, oldFocusState AS integer )

This event is generated when the Text gains or loses the focus--after its focusState property has changed.

Pass:

self entry
The Text gaining or losing the focus.

oldFocusState integer
Value of the focusState property before the event occurred. To find out the new value, check the property.

_numLinesChanged()

_numLinesChanged( self AS text )

This event is generated when the numLines property has changed. Similar to the _scrolled() event, this event should be handled by code to synchronize the state of an associated Scrollbar component.

Pass:

self text
The component experiencing the event.

_scrolled()

_scrolled( self AS text )

This event is generated when something has caused the text component to scroll its view area. Some possible causes are hitting the down arrow when the cursor is at the last visible line in the view area, setting the lastVisibleLine or firstVisibleLine property see entry object. The event might be handled to synchronize the state of an associated Scrollbar component.

Pass:

self text
The component experiencing the event.

Text Actions

AppendString()

AppendString( text AS string, ... ) AS integer

Appends a string to the end of the text. You may pass any number of strings, they will be concatenated. This action returns the number of characters successfully appended; if the component's maxLines property prevents some or all of the text from being appended, the return value will let you know how much was accepted.

For example:

text1.AppendString("Oprah")
text1.AppendString(" and" , " Gerald", "o cleanse the soil.")

Pass:

text string
The string(s) of text to append.

DeleteRange()

DeleteRange( startRange AS integer, endRange AS integer )

This action deletes a range of text.

To delete the "cd" from "abcdefg," startRange would be 2 and endRange would be 4. If endRange is less than startRange, the action will behave as if they were reversed; if startRange is less than 0, the action will behave as if startRange were 0; if endRange is greater than the number of characters in text, the action will behave as if endRange were the number of characters in the text.

Pass:

startRange integer (0-)
Offset to the start of the range of text to delete.

endRange integer (startRange-numChars)
Offset to the end of the range of text to delete.

GetLineNumber()

GetLineNumber( cursorPosition AS integer )

Returns the line number of the passed cursor position.

Pass:

cursorPosition integer (0-numChars)
The cursor position of interest.

GetString()

GetString( stringStart AS integer, stringEnd AS integer ) AS string

Returns the string of text in a given range of the Text's text. You might think of this action as a quick way to compute Mid( Text.text, stringStart, stringEnd-stringStart ).

Pass:

stringStart integer (0-numChars)
The offset of the start of the range to return.

stringEnd integer (start-numChars)
The offset of the end of the range to return.

InsertString()

InsertString( text AS string, startRange AS integer ) AS integer

Inserts a string at the given offset in the Text's text. This action returns the number of characters successfully inserted.

Pass:

text string
The string of new text to insert.

startRange integer (0-numChars)
The offset at which to insert. If this number is out of range, no text will be inserted and the action returns zero.

ReplaceString()

ReplaceString( newString AS string, startRange AS integer, endRange AS integer ) AS integer

Replaces a range of the text with a string, returning the number of characters successfully entered. (It is possible that not all the newString will be inserted--there might be too much text for the maxLines property to allow.) If endRange is less than startRange, the action will behave as if they were reversed; if startRange is less than 0, the action will behave as if startRange were 0; if endRange is greater than the number of characters in text, the action will behave as if endRange were the number of characters in the text.

Pass:

newString string
The new string to insert.

startRange integer (0-numChars)
The offset of the start of the range to replace.

endRange integer (start-numChars)
The offset of the end of the range to replace.

SetSelectionRange()

SetSelectionRange( startRange AS integer, endRange AS integer )

Selects a range of text. If endRange is less than startRange, the action will behave as if they were reversed; if startRange is less than 0, the action will behave as if startRange were 0; if endRange is greater than the number of characters in text, the action will behave as if endRange were the number of characters in the text.

Pass:

startRange integer (0-numChars)

endRange integer (startSelect-numChars)