Class Documentation
TextEditor |
1.0 |
ID_TEXTEDITOR |
In Development |
Tool |
August 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2001. All rights reserved. |
Provides text editing facilities. |
Description
The TextEditor class provides a complete text editing service for raw
text documents. While it can be used in text editor applications, it can
also serve as a text entry area for receiving user input in general.
Scrollbars can be attached to a TextEditor object via the HScroll and VScroll
fields. You also have full control over the font details and positioning
of the line graphics. To see a TextEditor object being used in a fully
featured text editing application, refer to the script file located at
"tools:text/editor/main.dml".
The TextEditor draws its graphics to the foreground only, so you have the
choice of defining your own background to be placed behind the text. To
change the attributes of the font used by a TextEditor, you need to access the
Font field to set the font attributes prior to
initialisation. By doing so, you can set the face of the font, as well as its
colour, size and extra effects.
By default the TextEditor class supports text highlighting for cut, copy
and paste operations. If you want to design an interface that responds to
clipboard related keypresses (such as CTRL-C, CTRL-V and CTRL-X), then
you will need to use the Keypress class to create
a response mechanism for the keyboard. Full clipboard support is provided
by the TextEditor and it is recommended that you use the SystemClipboard
object for storing and retrieving data.
Actions
The TextEditor class supports the following actions:
Clear | Clears the contents of a TextEditor object. |
Clipboard | Full support for clipboard activity is provided through this action. |
DataChannel | Text data can be sent to a TextEditor object via data channels. |
Focus | Call this action to focus on a TextEditor object. |
SaveToObject | Use this action to save TextEditor information as a text file. |
Scroll | Scrolls a TextEditor's graphical content. |
UserClick | Supported for responding to user clicks (authentic or faked). |
UserClickRelease | Supported for the purpose of responding to user click releases. |
UserMovement | Supported for the purpose of responding to user movement. |
Methods
The TextEditor class implements the following methods:
AddLine | Adds a new line to any row position in a TextEditor. |
DeleteLine | Deletes any line number from a TextEditor. |
FindText | Searches for keywords within a TextEditor object. |
GetLine | Returns the string content of any given line. |
ReplaceLine | Replaces the content of any line within a TextEditor. |
ReplaceText | Searches for and replaces keywords within a TextEditor. |
SelectTextArea | Forces a user selection over a specific text area. |
Structure
The TextEditor object consists of the following public fields:
AmtLines | Indicates the total amount of lines in a TextEditor. |
CursorColumn | Indicates the current column position of the cursor. |
CursorRow | Indicates the current line position of the cursor. |
Drawable | Defines the drawable area for TextEditor graphics. |
Flags | Special flags that affect TextEditor behaviour. |
Focus | Refers to the object that will be monitored for user focussing. |
Font | Points to a Font that controls the drawing of text for a TextEditor object. |
HScroll | If scrolling is required, use this field to refer to a horizontal scroll bar. |
Height | A calculated field that indicates the height of a TextEditor in pixels. |
Highlight | String-based field for defining the colour to use when text is highlighted. |
Input | Refers to the Keyboard object that input should be read from. |
Location | Identifies the location of a text file to load. |
Origin | Refers to the location of a text file, but does not update TextEditor content if set. |
SelectColumn | Indicates the column position of a selection's beginning. |
SelectRow | Indicates the line position of a selection's beginning. |
String | Text information can be written directly to a TextEditor object through this field. |
VScroll | If scrolling is required, use this field to refer to a vertical scroll bar. |
Width | Readable field that returns the pixel width of the longest line. |
XCoord | Defines the horizontal position of a TextEditor graphic. |
YCoord | Defines the vertical position of a TextEditor graphic. |
Clear |
Clears the contents of a TextEditor object. |
You can delete all of the text information from a TextEditor object by calling
the Clear action. All of the text data will be deleted from the object and
the graphics will be updated as a result of calling this action.
|
|
DataChannel |
Text data can be sent to a TextEditor object via data channels. |
One of the easiest ways to send text information to a TextEditor object is
to do so via data channels. The TextEditor class currently supports the
DATA_TEXT type for this purpose. If the text contains return codes, the
data will be split into multiple lines.
The drawable that is associated with the TextEditor object will be redrawn
as a result of calling this action.
ERR_Okay | Success. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | The TextEditor's memory buffer could not be expanded. |
ERR_Mismatch | The data type that was passed to the action is not supported by the TextEditor class. |
|
|
AddLine() |
Adds a new line to any row position in a TextEditor. |
STRING Text | The text that you want to add. |
LONG Line | The number of the line at which the text should be inserted. |
LONG Length | The length of the Text string. |
|
Lines can be added or inserted into a TextEditor object by using the AddLine()
method. All you need to provide is the text string that you wish to use,
the line number that the text will be inserted into, and the length of the
text string.
If you set the Text argument to NULL, then an empty string will be
inserted into the line number. If the Line argument is less than zero,
then the string will be added to the end of the TextEditor. If the Length is
set to -1, then the length will be calculated by counting the amount of
characters in the Text argument.
If the new line is visible within the TextEditor's associated drawable, that
region of the drawable will be redrawn so that the new line is displayed.
ERR_Okay | Success. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | The memory required to add the text string to the list was unavailable. |
|
|
DeleteLine() |
Deletes any line number from a TextEditor. |
LONG Line | The line number that you want to delete. If negative, the last line will be deleted. |
|
This method deletes lines from a TextEditor object. Just specify the line
number and the method will delete it. If the line number does not exist,
then the call will fail. The TextEditor graphic will be updated as a result
of calling this method.
ERR_Okay | The line was deleted. |
ERR_Args | The Line value was out of the valid range. |
|
|
FindText() |
Searches for keywords within a TextEditor object. |
STRING Text | The keyword that you want to search for. |
LONG Flags | Optional flags. |
LONG Row | This parameter will be updated to reflect the row at which the keyword was found. |
LONG Column | This parameter will be updated to reflect the column at which the keyword was found. |
|
This method is used to search for keywords within TextEditor objects. It is
possible to call this function once to find the first instance of the keyword,
or repeatedly if multiple keywords need to be found.
A large number of optional flags are available to refine the type of search
that is performed, as listed in the following table:
FTF_BACKWARDS | Start the search from the end of the text and work back to the beginning. |
FTF_CONTINUE | Continue the search from the position of the last keyword that was found. |
FTF_CASE | Use case sensitivity when looking for the keyword. |
FTF_FROMCURSOR | Start the search from the current cursor position. |
FTF_HIGHLIGHT | This flag is used to highlight the keyword when it is found. |
FTF_MOVECURSOR | Move the cursor to the end of the keyword position when it is found. |
FTF_SELECTION | Search only within the current text selection. If no text has been selected, do not perform the search. |
If the keyword is found, the Row and Column parameters will be updated
to reflect the location of the keyword and ERR_Okay will be returned. In all
other cases, the Row and Column parameters will be driven to zero and
ERR_Search will be returned to indicate that the keyword was not found.
ERR_Okay | The keyword was found. |
ERR_Args | Invalid arguments were specified. |
ERR_Search | The keyword was not found. |
|
|
GetLine() |
Returns the string content of any given line. |
LONG Line | The line number that you want to retrieve. Must be zero or greater. |
STRING Buffer | Point this argument to a buffer space for the string result, or set to NULL if a buffer should be allocated by the method. |
LONG Length | Set this argument to the length of the buffer that you have provided, or set to NULL if a buffer is to be allocated. |
|
This method can be used to get the string associated with any given line
number. You may choose to provide a buffer space for the method to output the
string data to, or you may set the Buffer argument to NULL to have the
method allocate a memory block containing the string. If you are providing
a buffer, make sure that the Length argument is set to the correct buffer
size. In the case of allocated buffers, the Length argument will
be updated to reflect the length of the allocation (including the NULL
byte).
ERR_Okay | The method executed successfully. |
ERR_Args | Invalid arguments detected. |
ERR_OutOfRange | The line number that you specified was outside of the valid range of line numbers. |
ERR_AllocMemory | The necessary amount of buffer space could not be allocated. |
|
|
ReplaceLine() |
Replaces the content of any line within a TextEditor. |
STRING Text | The text data that you want to use in replacing the line. |
LONG Line | The line number that will be replaced. |
LONG Length | The length of the Text string. |
|
Any line within a TextEditor can be replaced with new information by using
the ReplaceLine() method. All you need to provide is the text string that you
wish to use, the number of the line that will be replaced, and the length of
the text string.
If you set the Text argument to NULL, then an empty string will replace
the line number. If the Length is NULL, then the length of the new string
will be calculated by counting the amount of characters in the Text
argument.
If the new line content is visible within the TextEditor's associated
drawable, that region of the drawable will be redrawn so that the new line
content is displayed.
ERR_Okay | Success. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | The memory required to add the text string to the list was unavailable. |
|
|
ReplaceText() |
Searches for and replaces keywords within a TextEditor. |
STRING Find | The keyword that you want to search for. |
STRING Replace | The text that will replace the keyword. If NULL, all instances of the keyword will be deleted. |
LONG Flags | Optional flags. |
|
This method is used to replace matching keywords within a TextEditor object
in a single function call. It is suitable only for mass replacement
of keywords. If single keyword replacement is required, you should combine
use of the FindText() method and DataChannel action instead of using the
ReplaceText() method.
Optional flags that alter the behaviour of this method are listed in the
following table:
FTF_CASE | Use case sensitivity when looking for the keyword. |
FTF_FROMCURSOR | Start the search from the current cursor position. |
FTF_MOVECURSOR | Move the cursor to the position of the keyword that was found last. |
FTF_SELECTION | Search only within the current text selection. If no text has been selected, do not perform the replace operation. |
ERR_Okay | The keyword was found and replaced. |
ERR_Args | Invalid arguments were specified. |
ERR_Search | The keyword was not found. |
|
|
SelectTextArea() |
Forces a user selection over a specific text area. |
LONG Row | The row from which the selection will start. |
LONG Column | The column from which the selection will start. |
LONG EndRow | The number of the row that will terminate the selection. |
LONG EndColumn | The number of the column that will terminate the selection. |
|
If you would like to force a user selection over a specific text area,
use this method. Normally, user selections occur when the user moves a
pointing device over a TextEditor object to highlight an area of text. By
using this method, you will bypass that procedure by highlighting an area
manually.
The area that you specify will be highlighted as if the user had selected
that area him or herself. The selection can be cancelled if the user performs
an activity that causes the selection to be removed.
ERR_Okay | The area has been selected successfully. |
ERR_Args | Invalid arguments were specified. |
|
|
Field: | AmtLines |
Short: | Indicates the total amount of lines in a TextEditor. |
Type: | LONG |
Status: | Read |
The total amount of lines in a TextEditor can be read from this field. If
there are no lines in the TextEditor then a value of zero will be returned.
|
|
Field: | CursorColumn |
Short: | Indicates the current column position of the cursor. |
Type: | LONG |
Status: | Read/Set |
If you need to query the current position of the cursor within an editable
TextEditor object, read this field to obtain the column value. You can also
write to this field if you wish to forcibly alter the current position of the
cursor.
|
|
Field: | CursorRow |
Short: | Indicates the current line position of the cursor. |
Type: | LONG |
Status: | Read/Set |
If you need to query the current position of the cursor within an editable
TextEditor object, read this field to obtain the row value. You can also
write to this field if you wish to forcibly alter the current position of the
cursor.
|
|
Field: | Drawable |
Short: | Defines the drawable area for TextEditor graphics. |
Type: | OBJECTID |
Status: | Read/Write |
In most cases, when you create a TextEditor object it should be contained by
a drawable area, such as a Render object. If you do this correctly then
the TextEditor will detect the drawable area and set the Drawable field to the
correct object. However, there may be occasions where you want to
initialise a TextEditor object to a non-graphical container. If this is the
case then you must set the Drawable field to point to a valid drawable
area, such as a Render object.
|
|
Field: | Flags |
Short: | Special flags that affect TextEditor behaviour. |
Type: | LONG/FLAGS |
Prefix: | TLF |
Status: | Read/Set |
Special flags that apply to the TextEditor class are listed in the following
table:
EDIT | By default, user text editing is turned off. You need to enable it by setting the EDIT flag. |
OVERWRITE | This flag forces overwrite mode when the user enters information through the keyboard. If the flag is not set, then insert mode is used. |
AREASELECTED | This read-only flag is set automatically when the user has selected an area of text. |
|
|
Field: | Focus |
Short: | Refers to the object that will be monitored for user focussing. |
Type: | OBJECTID |
Status: | Read/Init |
By default, a TextEditor object will become active (i.e. capable of
receiving keyboard input) when its drawable container receives the focus. If
you would like to change this so that a TextEditor becomes active when some
other object receives the focus, refer to that object by writing its ID to
this field.
|
|
Field: | Font |
Short: | Points to a Font that controls the drawing of text for a TextEditor object. |
Type: | struct Font * |
Status: | Read |
To set the face, colour and other attributes of a TextEditor's graphics,
you need to read the Font field and write your settings to the Font object
prior to initialisation. For a list of all the fields that can be set, please
refer to the documentation for the Font class.
You are strongly discouraged from writing information to a Font object
after the initialistion of a TextEditor, although you may read information
from the Font after initialisation.
|
|
Field: | HScroll |
Short: | If scrolling is required, use this field to refer to a horizontal scroll bar. |
Type: | OBJECTID |
Status: | Read/Set |
If you want to attach a horizontal scrollbar to a TextEditor object, set
this field to an object belonging to the Scroll class. So long as the Scroll
object is set up to provide full scrollbar functionality, the user will be
able to scroll the text display along the horizontal axis.
|
|
Field: | Height |
Short: | A calculated field that indicates the height of a TextEditor in pixels. |
Type: | FLOAT |
Status: | Get |
The exact height of a TextEditor can be read from this field. The value
that is returned is a total that includes the height of each individual line,
and compensates for vertical and gutter spacing.
|
|
Field: | Highlight |
Short: | String-based field for defining the colour to use when text is highlighted. |
Type: | STRING |
Status: | Set |
The colour that you set through the Highlight field will determine the
colour that is used in highlighting selected text. If you do not set this
field, the default colour will be used.
|
|
Field: | Input |
Short: | Refers to the Keyboard object that input should be read from. |
Type: | OBJECTID |
Status: | Read/Init |
By default a TextEditor object will read information from the
SystemKeyboard for the purpose of receiving keyboard based user input. If
you would like a TextEditor object to receive its keyboard input from
elsewhere, write the ID of that input object to this field.
|
|
Field: | Location |
Synonyms: | Src |
Short: | Identifies the location of a text file to load. |
Type: | STRING |
Status: | Get/Set |
If the data for a TextEditor comes from a file, the easiest way to load
it into the object is to set the Location field and have the TextEditor load
the data for you. The alternative is to load the data manually and then
set the String field with a data pointer.
Note that if you set the Location field after initialisation, the
TextEditor will automatically clear its data and reload information from the
location that you specify.
|
|
Field: | Origin |
Short: | Refers to the location of a text file, but does not update TextEditor content if set. |
Type: | STRING |
Status: | Get/Set |
This field is identical to the Location field, with the exception that it
does not update the content of a TextEditor if you set it after
initialisation. Altering the Origin of a TextEditor is useful if you want
to record a change to a file's location without causing a load operation.
|
|
Field: | SelectColumn |
Short: | Indicates the column position of a selection's beginning. |
Type: | LONG |
Status: | Read |
If the user has selected an area of text, the starting column of that
area will be indicated by this field. If an area has not been selected, the
value of the SelectColumn field is undefined.
You can check whether or not an area has been selected by testing the
AREASELECTED bit in the Flags field.
|
|
Field: | SelectRow |
Short: | Indicates the line position of a selection's beginning. |
Type: | LONG |
Status: | Read |
If the user has selected an area of text, the starting row of that
area will be indicated by this field. If an area has not been selected, the
value of the SelectRow field is undefined.
You can check whether or not an area has been selected by testing the
AREASELECTED bit in the Flags field.
|
|
Field: | String |
Short: | Text information can be written directly to a TextEditor object through this field. |
Type: | STRING |
Status: | Get/Set |
You can update the data of a TextEditor by passing text information to the
String field. Updating a TextEditor in this fashion causes it to analyse the
string information for return codes, so you can still split the string data
into lines. Any data that is in the TextEditor when you set this field will be
deleted automatically. The graphics will also be redrawn and any attached
Scroll objects will be recalculated.
|
|
Field: | VScroll |
Short: | If scrolling is required, use this field to refer to a vertical scroll bar. |
Type: | OBJECTID |
Status: | Read/Set |
If you want to attach a vertical scrollbar to a TextEditor object, set this
field to an object belonging to the Scroll class. So long as the Scroll
object is set up to provide full scrollbar functionality, the user will be
able to scroll the text display along the vertical axis.
|
|
Field: | Width |
Short: | Readable field that returns the pixel width of the longest line. |
Type: | LONG |
Status: | Get |
If you need to find out the width of a TextEditor then you can read it
from this field. The width that is returned is that of the longest line
in the TextEditor. Note that the longest line does not necesarily have the
most characters, unless the font is of a fixed size (a line of 30 'w'
characters will typically be longer than a line of 50 'i' characters
because of the difference in character width).
|
|
Field: | XCoord |
Short: | Defines the horizontal position of a TextEditor graphic. |
Type: | FLOAT |
Status: | Get/Set |
This field defines the horizontal position of a TextEditor graphic from
the top of its container. The value can be set as a fixed pixel coordinate,
or as a percentage if the FD_PERCENT field is used.
|
|
Field: | YCoord |
Short: | Defines the vertical position of a TextEditor graphic. |
Type: | FLOAT |
Status: | Get/Set |
This field defines the vertical position of a TextEditor graphic from
the top of its container. The value can be set as a fixed pixel coordinate,
or as a percentage if the FD_PERCENT field is used.
|
|