Class Documentation

Name:TextEditor
Version:1.0
ID:ID_TEXTEDITOR
Status:In Development
Category:Tool
Date:August 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2001. All rights reserved.
Short:  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.
Action:Clear
Short: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.

 

Action:DataChannel
Short: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.

Result
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.

 

Method:AddLine()
Short:Adds a new line to any row position in a TextEditor.
Arguments:
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.

Result
ERR_Okay  Success.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  The memory required to add the text string to the list was unavailable.

 

Method:DeleteLine()
Short:Deletes any line number from a TextEditor.
Arguments:
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.

Result
ERR_Okay  The line was deleted.
ERR_Args  The Line value was out of the valid range.

 

Method:FindText()
Short:Searches for keywords within a TextEditor object.
Arguments:
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:

FlagDescription
FTF_BACKWARDSStart the search from the end of the text and work back to the beginning.
FTF_CONTINUEContinue the search from the position of the last keyword that was found.
FTF_CASEUse case sensitivity when looking for the keyword.
FTF_FROMCURSORStart the search from the current cursor position.
FTF_HIGHLIGHTThis flag is used to highlight the keyword when it is found.
FTF_MOVECURSORMove the cursor to the end of the keyword position when it is found.
FTF_SELECTIONSearch 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.

Result
ERR_Okay  The keyword was found.
ERR_Args  Invalid arguments were specified.
ERR_Search  The keyword was not found.

 

Method:GetLine()
Short:Returns the string content of any given line.
Arguments:
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).

Result
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.

 

Method:ReplaceLine()
Short:Replaces the content of any line within a TextEditor.
Arguments:
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.

Result
ERR_Okay  Success.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  The memory required to add the text string to the list was unavailable.

 

Method:ReplaceText()
Short:Searches for and replaces keywords within a TextEditor.
Arguments:
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:

FlagDescription
FTF_CASEUse case sensitivity when looking for the keyword.
FTF_FROMCURSORStart the search from the current cursor position.
FTF_MOVECURSORMove the cursor to the position of the keyword that was found last.
FTF_SELECTIONSearch only within the current text selection. If no text has been selected, do not perform the replace operation.
Result
ERR_Okay  The keyword was found and replaced.
ERR_Args  Invalid arguments were specified.
ERR_Search  The keyword was not found.

 

Method:SelectTextArea()
Short:Forces a user selection over a specific text area.
Arguments:
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.

Result
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:

FlagDescription
EDITBy default, user text editing is turned off. You need to enable it by setting the EDIT flag.
OVERWRITEThis flag forces overwrite mode when the user enters information through the keyboard. If the flag is not set, then insert mode is used.
AREASELECTEDThis 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.