Class Documentation

Name:Text
Version:2.0
ID:ID_TEXT
Status:Stable
Category:GUI
Include:pandora/graphics/text.h
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2004. All rights reserved.
Short:  Provides text display and editing facilities.



Description

The Text class provides a complete text display and editing service that is suitable for almost any situation that requires effective text management. The class is most effective when applied to general text display, text editing services, command-lines and input boxes.

The Text class is closely linked to the Font class, which provides all of the code necessary for font management. If you require information on how to set font definitions such as the face and colour of the font, please refer to the documentation for the Font class. All fields in the Font class are inherited, and you will find that the Face, Colour, Bold, Point and Align fields are particularly helpful for setting font attributes.

The graphical area of a text object is defined using the standard dimension conventions (x, y, width and height). Margins (left, right, top and bottom) also allow you to offset the text from the edges of the drawable area. The Text class draws its graphics to the foreground only, so you have the choice of defining your own background to be placed behind the text. If you wish to forgo that in favour of a clear background, set the Background field to your preferred colour.

The following example shows how to create a simple string display:

   <text string="Hello World" x="5" y="10" colour="#303030"/>

If you intend to create a text object that accepts user input, there are a number of flags available to you that decide how the object will behave as the user enters text information. You may also attach child objects that can be activated when the user presses the enter key after typing in some information. This can be useful for creating a custom-built reaction to user input. Here is an example of a text object that runs a script when the enter key is pressed:

   <text flags="commandline" x="3" y="4"
     face="[gl_fonts.face]" colour="#000000">
      <script static src="myscript.dml" &string="$[owner.string]$"/>
   </text>

If the text object needs to be linked to another object, you may prefer to set the SelectionObject and SelectionField values so that they point to an external object field. This ensures that any information typed into the text object is always reflected in the field of the linked object.

For long text lists, scrollbars can be attached via the HScroll and VScroll fields. For hints on how to use a text object to build a full featured text editing application, refer to the script file located at "scripts:applications/text/editor/main.dml".

By default the Text class supports text highlighting for cut, copy and paste operations. This support is backed by system keypresses such as CTRL-C, CTRL-V and CTRL-X. If you need to send custom commands to the Text class that aren't covered by the control keys, use the Keypress class to create response mechanisms for the keyboard.

Actions

The Text class supports the following actions:

Activate  Opens the current text selection.
Clear  Clears all content from the object.
Clipboard  Full support for clipboard activity is provided through this action.
DataChannel  Text data can be sent to a text object via data channels.
Disable  Disables object functionality.
Enable  Enables object functionality.
Focus  Calling this action will activate keyboard input.
LostFocus  Calling this action will deactivate keyboard input.
SaveToObject  Use this action to save edited information as a text file.
ScrollToPoint  Scrolls a text object'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 Text class implements the following methods:

AddLine  Adds a new line to any row position in a text object.
DeleteLine  Deletes any line number.
FindText  Searches for keywords.
GetLine  Returns the string content of any given line.
ReplaceLine  Replaces the content of any text line.
ReplaceText  Searches for and replaces keywords.
SelectTextArea  Forces a user selection over a specific text area.
SetFont  Allows you to change the font face, style and size after initialisation.

Structure

The Text object consists of the following public fields:

AmtLines  Indicates the total amount of lines in a text object.
Background  String-based field for defining a background colour.
BottomMargin  Defines the amount of whitespace to leave at the bottom of the text page.
CharLimit  Limits the amount of characters allowed in a text object's string.
CursorColour  The colour used for the text cursor.
CursorColumn  Indicates the current column position of the cursor.
CursorRow  Indicates the current line position of the cursor.
Drawable  Defines the drawable area for text graphics.
Duration  Determines the duration of an active effect, measured in milliseconds.
Effect  Enables animated text effects.
EffectDelay  Sets the delay for text effects, in milliseconds.
Flags  Special flags that affect object behaviour.
Focus  Refers to the object that will be monitored for user focussing.
Font  Points to a Font object that controls the drawing of text.
Frame  Forces a text object's graphic to be drawn to a specific frame.
Frames  Determines a sequence of frames that a text graphic may be drawn to.
HScroll  If scrolling is required, use this field to refer to a horizontal scroll bar.
Height  Defines the height of a text object's drawable region.
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.
LeftMargin  Defines the amount of whitespace to leave at the left of the page.
LineLimit  Restricts the total number of lines allowed in a text object.
Location  Identifies the location of a text file to load.
Origin  Similar to the Location field, but does not automatically load content if set.
RightMargin  Defines the amount of whitespace to leave at the right side of the text page.
SelectColumn  Indicates the column position of a selection's beginning.
SelectRow  Indicates the line position of a selection's beginning.
SelectionField  This field is used in conjunction with the SelectionObject field.
SelectionObject  If the text object should send input data to another object, set this field.
String  Text information can be written directly to a text object through this field.
TabFocus  Allows the user to hit the tab key to focus on other GUI objects.
TextHeight  Indicator for the pixel height of all lines in a text object.
TextWidth  Readable field that returns the maximum width of the text string in pixels.
TopMargin  Defines the amount of whitespace to leave at the top of the text page.
VScroll  If scrolling is required, use this field to refer to a vertical scroll bar.
Visible  Indicates the visibility of a text object.
Width  Defines the width of a text object's drawable region.
XCoord  Defines the horizontal position of the drawable region.
XOffset  Defines the horziontal offset of the drawable region.
YCoord  Defines the vertical position of the drawable region.
YOffset  Defines the vertical offset of the drawable region.
Action:Activate
Short:Opens the current text selection.

Calling the Activate action on a text object will cause it to send Activate messages to the child objects that belong to the text object.


Action:Clear
Short:Clears all content from the object.

You can delete all of the text information from a text object by calling the Clear action. All of the text data will be deleted from the object and the graphics will be automatically updated as a result of calling this action.


Action:DataChannel
Short:Text data can be sent to a text object via data channels.

One of the easiest ways to send text information to a text object is to do so via data channels. The Text class currently supports the DATA_TEXT and DATA_XML types for this purpose. If the text contains return codes, the data will be split into multiple lines.

The drawable that is associated with the Text object will be redrawn as a result of calling this action.

Result
ERR_Okay  Success.
ERR_Args  Invalid arguments were specified.
ERR_AllocMemory  The Text's memory buffer could not be expanded.
ERR_Mismatch  The data type that was passed to the action is not supported by the Text class.

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

Lines can be added or inserted into a text object by using the AddLine() method. You need to provide 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 Text. 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 text object'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.
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 text object. You only need to specify the line number to have it deleted. If the line number does not exist, then the call will fail. The text 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.
Arguments:
STRING String  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 text 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_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.
FTF_RESTARTRestart the search from the beginning of the text data if the keyword is not found from the current position.

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 text line.
Arguments:
STRING String  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 String in bytes.

Any line within a text object can be replaced with new information by using the ReplaceLine() method. You need to provide 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 String argument to NULL, then an empty string will replace the line number. If the Length is set to -1, then the length of the new string will be calculated by counting the amount of characters in the String argument.

If the new line content is visible within the text object'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.
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 text 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 and stop at the end of the text data.
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 Text 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 text object.
Type:LONG
Status:Read

The total amount of lines in a text object can be read from this field. If there are no lines in the object, a value of zero will be returned.


Field:Background
Short:String-based field for defining a background colour.
Type:STRING
Status:Set

If you set the Background field then the entire text area will be cleared to the colour that you specify. The colour must be in hexadecimal or CSV format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.

The background can be switched on and off using the BACKGROUND bit in the Flags field.


Field:BottomMargin
Short:Defines the amount of whitespace to leave at the bottom of the text page.
Type:LONG
Status:Read/Init

Text is drawn as if it is on a page of paper and the BottomMargin determines the amount of whitespace that is created at the bottom of that page. This is useful in creating a layout where the text is positioned slightly away from the edge of the display area.

This value can be set as a fixed pixel coordinate only.


Field:CharLimit
Short:Limits the amount of characters allowed in a text object's string.
Type:LONG
Status:Set

Set the CharLimit field if you wish to limit the amount of characters that can appear in a text object's string. The minimum possible value is 0 for no characters.

The CharLimit field is most useful for restricting the amount of characters that a user can enter in an editable text object.


Field:CursorColour
Short:The colour used for the text cursor.
Type:STRING
Status:Set

The colour used for the text cursor may be defined through this field. The colour must be in hexadecimal or CSV format - for example to create a pure red colour, a setting of "#ff0000" or "255,0,0" would be valid.


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 text 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 text 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 text graphics.
Type:OBJECTID
Status:Read/Write

In most cases, when you create a text object it should be contained by a drawable area, such as a Render object. If you do this correctly then the text 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 text 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:Duration
Short:Determines the duration of an active effect, measured in milliseconds.
Type:LONG
Status:Read/Init

If you set the Duration field in conjunction with a text effect, the effect will last only as long as the duration that you specify. The duration is measured in milliseconds. Once the effect ends, normal activity will resume, although the effect may restart if you have used the EFFECTLOOP flag.


Field:Effect
Short:Enables animated text effects.
Type:LONG
Prefix:EFX
Status:Read/Init

Special effects are supported in the text object through the Effect field. This allows you to create text displays suitable for presentations and catching the eye of the user. The following effects are currently available:

TypeDescription
FADEThis effect uses alpha blending techniques to cross-fade the text into the display.
FLASHThis effect flashes the all of the text to white, then drops down to the colour pre-assigned to the text object's font.
TYPISTThis effect prints the text strings gradually, as if someone is typing it in real time.

An effect starts either when the EffectDelay field decrements to zero, or the first drawable frame is reached in an animation sequence (refer to the Frames field). The effect will last until either the last frame is displayed, or the duration of the effect ends, as determined by the Duration field.

When using text effects, you must preset the strings in the text object before initialisation. Note that it is generally unwise to push the limits of a text object while effects are active, as certain activity may clash with effects when they are enabled.


Field:EffectDelay
Short:Sets the delay for text effects, in milliseconds.
Type:LONG
Status:Read/Write

If you have enabled an effect, you can set the EffectDelay field to delay the start of the effect for a set number of milliseconds. If this field is not set, the effect will either start immediately or when the first drawable frame is reached in an animation sequence.


Field:Flags
Short:Special flags that affect object behaviour.
Type:LONG/FLAGS
Prefix:TXF
Status:Read/Set

Special flags that apply to the text class are listed in the following table:

FlagDescription
AREASELECTEDThis read-only flag is set automatically when the user has selected an area of text.
AUTOCLEARThis flag will cause the text object to clear the entered text when the enter key is pressed.
BACKGROUNDThis flag is automatically set if the Background field is written. You can turn off the background colour at any time by disabling this flag.
COMMANDLINEProvided for convenience, this flag can be set on initialisation to enable the following options: AUTOCLEAR, ENTERACTIVATE, HISTORY and EDIT.
DISABLEDThis read-only flag is set if the object has been disabled through the Disable action.
DOUBLECLICKIf enabled, double clicking on any line will cause all child objects to be activated.
EDITBy default, user text editing is turned off. You need to enable it by setting the EDIT flag.
EFFECTLOOPIf special effects are in use, setting the EFFECTLOOP flag allows the effect to repeat itself continuously when in an animation loop.
ENTERACTIVATEWhen this flag is set, any child objects that belong to the text object will be activated when the user hits the enter key.
FOCUSACTIVATE  If the text object loses the focus when this flag is set, the children of the text object will be activated.
FORCECAPSThis flag forces the capitalisation of all text that is entered into the object.
GLOBALEDITINGKeeps the text object in edit mode regardless of where the user focus might be.
HISTORYEnables historical browsing when the up/down cursor keys are used. The number of historical lines stored can be set in the HistorySize field.
MULTISELECTAllows the user to select/highlight multiple lines by holding the Ctrl key.
NOFXDRAWWhen in special effect mode, redrawing normally takes place automatically. You can turn off this behaviour by setting this 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.
SECRETThe SECRET flag should be used when the text that is input by the user should be hidden from the display. This option is most commonly used for password entry.
SINGLESELECTEnables text selection (with or without edit mode). If in line mode, a single click will allow the user to highlight any line.
SYSKEYSThis flag is set by default to enable system key support. System-keys provide support for common key combinations such as Ctrl-C, Ctrl-X etc.
TABENTRYIf set, pressing the tab key has the same effect as pressing the enter key.
WORDWRAPIf you want the words to wrap around when the text string reaches the width of its container, set this flag.
VARIABLEThis flag forces a text object to recalculate any variable references in its string data whenever a redraw occurs. Such references are indicated through square brackets, e.g. [systemdisplay.width]. Refer to the StrTranslate() function in the Strings module for more information.

Field:Focus
Short:Refers to the object that will be monitored for user focussing.
Type:OBJECTID
Status:Read/Init

By default, a text 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 Text 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 object that controls the drawing of text.
Type:struct Font *
Status:Read

To set the face, colour and other attributes of a text object'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.


Field:Frame
Short:Forces a text object's graphic to be drawn to a specific frame.
Type:LONG
Status:Read/Write

If this field is set to a valid frame number, the text graphic will only be drawn when the frame of the container matches the Frame number in this field. When set to 0 (the default), the text graphic will be drawn regardless of the container's frame number.


Field:Frames
Short:Determines a sequence of frames that a text graphic may be drawn to.
Type:STRING
Status:Set

For long animation sequences you can set the Frames field to determine individual frames that a text graphic should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want a text graphic to appear in frames 5, 6, 7, 8, 17 and 19, you would use this frame specification:

   5-8,17,19

Individual frame sets are separated by any non-numeric character such as a comma, and ranges can be specified through the '-' character.

Setting the Frames field will override any setting that you may have previously set in the Frame field.


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 text 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:Defines the height of a text object's drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A text object's drawing region can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


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, a default colour will be used for highlighting.


Field:Input
Short:Refers to the Keyboard object that input should be read from.
Type:OBJECTID
Status:Read/Init

By default, all text objects will receive keyboard input from the "SystemKeyboard" object (which is typically created during the boot sequence). However, you may want the text object to receive its keyboard input from a different source. If that is the case, you can refer to that object by pointing to it in this field.

The object that you specify must support data channels and be able to output data in the Keypress format. If the Input object does not meet these requirements, the text object will not be able to accept information from it.


Field:LeftMargin
Short:Defines the amount of whitespace to leave at the left of the page.
Type:LONG
Status:Read/Init

Text is drawn as if it is on a page of paper and the LeftMargin determines the amount of whitespace that is created on the left of that page. This is useful in creating a layout where the text is positioned slightly away from the edge of the display area.

This value can be set as a fixed pixel coordinate only.


Field:LineLimit
Short:Restricts the total number of lines allowed in a text object.
Type:LONG
Status:Read/Init

Set the LineLimit field if you would like to restrict the maximum number of lines allowed in a text object. It is quite common to set this field to a value of 1 for input boxes that have a limited amount of space available.


Field:Location
Synonyms:Src
Short:Identifies the location of a text file to load.
Type:STRING
Status:Get/Set

If the data for a text object needs to be read from a file, the easiest way to load it into the object is to set the Location field and have the object load the data for you. The alternative is to load the data manually and then set the String field with a data pointer, or use the DataChannel action.

Note that if you set the Location field after initialisation, the object will automatically clear its content and reload data from the location that you specify.


Field:Origin
Short:Similar to the Location field, but does not automatically load content if set.
Type:STRING
Status:Set

This field is identical to the Location field, with the exception that it does not update the content of a text object if you set it after initialisation. Altering the Origin of a text object is useful if you want to record a change to a file's location without causing a load operation.


Field:RightMargin
Short:Defines the amount of whitespace to leave at the right side of the text page.
Type:LONG
Status:Read/Init

Text is drawn as if it is on a page of paper and the RightMargin determines the amount of whitespace that is created at the right of that page. This is useful in creating a layout where the text is positioned slightly away from the edge of the display area.

This value can be set as a fixed pixel coordinate only.


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:SelectionField
Short:This field is used in conjunction with the SelectionObject field.
Type:STRING
Status:Set

This field needs to be set in conjunction with the SelectionObject field - please refer to it for more detail.


Field:SelectionObject
Short:If the text object should send input data to another object, set this field.
Type:OBJECTID
Status:Read/Write

When the user presses the enter key, you can send the entered data to the field of another object. In order to do this, you need to point to that object through the SelectionObject field and specify the destination field name by setting the SelectionField string. So long as both fields are set correctly, the destination object will always reflect the value currently entered in the text object.


Field:String
Short:Text information can be written directly to a text object through this field.
Type:STRING
Status:Get/Set

You can set the data of a text object by passing a string to this field. Updating a text object 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 text object when you set this field will be deleted automatically. The graphics will also be redrawn and any attached Scroll objects will be recalculated.


Field:TabFocus
Short:Allows the user to hit the tab key to focus on other GUI objects.
Type:OBJECTID
Status:Read/Write

If this field points to another GUI object, the user will be able to use the tab key to move to that object when entering information into the text object. (Technically this causes the focus to be set to that object, and the text object will thus lose the focus.)

When a series of objects are 'chained' via tab focussing, the user will have an easier time moving between objects through use of the keyboard.


Field:TextHeight
Short:Indicator for the pixel height of all lines in a text object.
Type:LONG
Status:Get

The total height of all lines in a text object can be measured by reading the TextHeight. The returned value compensates for vertical and gutter spacing. Wordwrap will be taken into account if the WORDWRAP bit has been set in the Flags field.


Field:TextWidth
Short:Readable field that returns the maximum width of the text string in pixels.
Type:LONG
Status:Get

If you need to find out the pixel width of a text object then you can read it from this field. The width that is returned is that of the longest line in the text object. 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).

The value includes the LeftMargin and RightMargin fields if you have set them.


Field:TopMargin
Short:Defines the amount of whitespace to leave at the top of the text page.
Type:LONG
Status:Read/Init

Text is drawn as if it is on a page of paper and the TopMargin determines the amount of whitespace that is created at the top of that page. This is useful in creating a layout where the text is positioned slightly away from the edge of the display area.

This value can be set as a fixed pixel coordinate only.


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 text 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:Visible
Short:Indicates the visibility of a text object.
Type:LONG/BOOLEAN
Status:Read

If you need to know if a text object is visible or hidden, you can read this field to find out. A TRUE value is returned if the object is visible and FALSE is returned if the object is invisible. Note that visibility is subject to the properties of the container that the text object resides in. For example, if a text object is visible but is contained within a drawable object that is invisible, the end result is that both objects are actually invisible.

Visiblity is directly affected by the Hide and Show actions if you wish to change the visiblity of a text object.


Field:Width
Short:Defines the width of a text object's drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A text object's drawing region can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:Defines the horizontal position of the drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

This field defines the horizontal position of the text drawing area from the left of its container. The value can be set as a fixed pixel coordinate, or as a percentage if the FD_PERCENT field is used. The text string will be clipped to fit inside this area, so if you were to set the TextX field to a negative value then the initial set of characters would be clipped until the left-hand border was reached.


Field:XOffset
Short:Defines the horziontal offset of the drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

You can offset the drawable region of a text graphic by setting this field. A setting of 0 would offset the drawing region against the right edge, while a setting of 10 would place it 10 pixels off from the right edge. Negative values can move the drawing region outside of the container's boundaries.

This field may also be set as a percentage if the FD_PERCENT flag is used. Use of a percentage will cause the position of the drawing region to be calculated relative to the width of the container.

Writing to this field will always turn off any previous setting in the XCoord field.


Field:YCoord
Short:Defines the vertical position of the drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

This field determines the vertical position of the text drawing region 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:YOffset
Short:Defines the vertical offset of the drawable region.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

You can offset the drawable region of a text graphic by setting this field. A setting of 0 would place the drawing region at the bottom edge, while a setting of 10 would place it 10 pixels off from the bottom edge. Negative values can move the region outside of the container's boundaries.

This field may also be set as a percentage if the FD_PERCENT flag is used. Use of a percentage will cause the position of the text to be calculated relative to the height of the container.

Writing to this field will always turn off any previous setting in the YCoord field.