Class Documentation
Text |
2.0 |
ID_TEXT |
Stable |
GUI |
pandora/graphics/text.h |
January 2004 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2004. All rights reserved. |
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. |
Activate |
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.
|
|
Clear |
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.
|
|
DataChannel |
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.
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. |
|
|
AddLine() |
Adds a new line to any row position in a text object. |
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.
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. |
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.
ERR_Okay | The line was deleted. |
ERR_Args | The Line value was out of the valid range. |
|
|
FindText() |
Searches for keywords. |
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:
FTF_BACKWARDS | Start the search from the end of the text and work back to the beginning. |
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. |
FTF_RESTART | Restart 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.
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 text line. |
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.
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. |
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:
FTF_CASE | Use case sensitivity when looking for the keyword. |
FTF_FROMCURSOR | Start the search from the current cursor position and stop at the end of the text data. |
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 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.
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:
FADE | This effect uses alpha blending techniques to cross-fade the text into the display. |
FLASH | This effect flashes the all of the text to white, then drops down to the colour pre-assigned to the text object's font. |
TYPIST | This 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:
AREASELECTED | This read-only flag is set automatically when the user has selected an area of text. |
AUTOCLEAR | This flag will cause the text object to clear the entered text when the enter key is pressed. |
BACKGROUND | This flag is automatically set if the Background field is written. You can turn off the background colour at any time by disabling this flag. |
COMMANDLINE | Provided for convenience, this flag can be set on initialisation to enable the following options: AUTOCLEAR, ENTERACTIVATE, HISTORY and EDIT. |
DISABLED | This read-only flag is set if the object has been disabled through the Disable action. |
DOUBLECLICK | If enabled, double clicking on any line will cause all child objects to be activated. |
EDIT | By default, user text editing is turned off. You need to enable it by setting the EDIT flag. |
EFFECTLOOP | If special effects are in use, setting the EFFECTLOOP flag allows the effect to repeat itself continuously when in an animation loop. |
ENTERACTIVATE | When 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. |
FORCECAPS | This flag forces the capitalisation of all text that is entered into the object. |
GLOBALEDITING | Keeps the text object in edit mode regardless of where the user focus might be. |
HISTORY | Enables historical browsing when the up/down cursor keys are used. The number of historical lines stored can be set in the HistorySize field. |
MULTISELECT | Allows the user to select/highlight multiple lines by holding the Ctrl key. |
NOFXDRAW | When in special effect mode, redrawing normally takes place automatically. You can turn off this behaviour by setting this 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. |
SECRET | The 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. |
SINGLESELECT | Enables text selection (with or without edit mode). If in line mode, a single click will allow the user to highlight any line. |
SYSKEYS | This 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. |
TABENTRY | If set, pressing the tab key has the same effect as pressing the enter key. |
WORDWRAP | If you want the words to wrap around when the text string reaches the width of its container, set this flag. |
VARIABLE | This 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.
|
|