TheText 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
-
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
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
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)
A TimeDate component monitors the system time and date; also, it can change
the system time and date.
TimeDate Properties
Standard Properties: class, parent, proto, version.
-
systemClock long
-
This read-only property is a count of the number of milliseconds since the
system last rebooted; it "wraps around" about once every 49 hours. It is
useful for conducting timing tests.
-
timeInterest integer (0-60)
-
This property determines how often the component will generate a
_timeChanged( ) event.
If this property is zero, then no such events will be generated. If this
property is greater than zero, then a _timeChanged( ) event will
be generated at midnight and every timeInterest minutes later. Thus,
if timeInterest is one, then _timeChanged( ) events will
occur every minute; if timeInterest is sixty, then
_timeChanged( ) events will occur every hour.
TimeDate Events
_dateChanged( )
_dateChanged( self AS timedate )
This event is generated whenever the date changes; either the system date
has been changed or time has passed.
Pass:
-
self timedate
The component experiencing the event.
_timeChanged( )
_timeChanged( self AS timedate )
This event is generated whenever the time changes; either the system time
has somehow been reset, or else an event generated thanks to the
timeInterest.
Pass:
-
self timedate
-
The component experiencing the event.
TimeDate Actions
GetDate( )
GetDate( ) AS STRUCT Date
This action returns the current date. The returned structure has the following
fields:
STRUCT Date
DIM year AS integer
DIM month AS integer REM 1 = January ... 12 = December
DIM day AS integer
END STRUCT
GetDayOfWeek( )
GetDayOfWeek( year AS integer, month AS integer, day AS integer )
AS integer
This action returns the day of the week for a given day of the month in a
given year. A return value of 1 means Sunday, 2 means Monday, ... and 7 means
Saturday.
Pass:
-
year integer (1901-2099)
-
The year.
-
month integer (1-12)
-
The month. 1 means January, 2 means February, ... 12 means December.
-
day integer (1-31)
-
The day of month.
GetDaysInMonth( )
GetDaysInMonth( year AS integer, month AS integer )
This action computes the number of days in a month in a given year.
Pass:
-
year integer (1901-2099)
-
The year. (This is necessary for computing the length of February in leap
year.)
-
month integer (1-12)
-
The month. 1 means January, 2 means February, ... 12 means December.
GetTime( )
GetTime ( ) AS STRUCT TimeOfDay
This action returns the current time. The returned structure has the following
fields:
STRUCT TimeOfDay
DIM hour AS integer REM 0 - 23
DIM minute AS integer
DIM second AS integer
END STRUCT
SetDate( )
SetDate( newDate AS STRUCT Date )
This action sets the current date. The passed structure has the following
fields:
STRUCT Date
DIM year AS integer
DIM month AS integer REM 1 = January ... 12 = December
DIM day AS integer
END STRUCT
SetTime( )
SetTime ( newTime AS STRUCT TimeOfDay )
This action sets the current time. The passed structure has the following
fields:
STRUCT TimeOfDay
DIM hour AS integer REM 0 - 23
DIM minute AS integer
DIM second AS integer
END STRUCT
A Timer component monitors elapsed time.
Timer Properties
Standard Properties: class, enabled, parent, proto, version.
-
enabled:
-
Setting this property to 1 starts the timer; Setting it to zero stops it.
-
interval integer (1-...)
-
The amount of time between _ring( ) events, in 1/60 second intervals.
For example, to receive notification once every 1/10 of second, use an
interval of 6.
Timer Events
_ring( )
_ring( self AS timer )
This event is generated when the timer is enabled every time the
interval is reached. If the system is too slow to handle all the
_ring( ) events generated, some _ring( ) events may
be dropped.
Pass:
-
self timer
-
The component experiencing the event.
Timer Actions
None.
A Toggle acts as a simple on-off switch or check-box.
Toggle Looks
All toggles look like checkboxes.
Toggle Properties
Standard Properties: caption, class, enabled, graphic, height, left,
look, parent, proto, sizeHControl, sizeVControl, top, version, visible, width.
-
status integer (0-1)
-
This property reflects the Toggle's state: if status is 1, then the
Toggle is on; if status is 0, then the Toggle is off.
Toggle Events
_changed( )
_changed( self AS component )
This event is generated when the user clicks on the Toggle and turns it on
or off.
Pass:
-
self component
-
The Toggle experiencing the event.
Toggle Actions
None.