Class Documentation
Text |
1.0 |
ID_TEXT |
Beta |
GUI |
August 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2001. All rights reserved. |
Draws text strings, can also accept keyboard input from the user. |
Description
The Text class is used for drawing small quantities of text to graphics areas. It is
capable of accepting user input, and is often used for basic text editing purposes.
A large number of settings are available for obtaining the results that you
require, including support for choosing all the font characteristics and the
exact positioning of the text within the drawable container.
To create a valid Text object, you do not have to set any compulsory
fields, although in most cases you will at least want to set the String field
so that something will be printed. Here is a basic example of a Text object
being created in DML:
<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 name="mytext" flags="edit|enteractivate|focusactivate" x="3"
y="4" face="[gl_fonts.face]" colour="#000000">
<script static src="myscript.dml" &string="$[mytext.string]$"/>
</text>
If the Text object is implicitly attached to another object, you may
prefer to set the Receiver and ReceiverField values to 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.
Structure
The Text object consists of the following public fields:
Align | This field allows you to align the text within its container. |
CursorPos | Indicates the current byte position of a Text object's cursor. |
Drawable | Defines the drawable area for the Text graphics. |
Flags | Special behaviour is enabled through these flags. |
Frame | Forces the text graphic to be drawn to a specific frame. |
Height | Readable field for retrieving the pixel height of the text. |
Input | An object handler for key-strokes can be specified here to accept user input. |
Lines | This field reflects the total amount of lines in the text data. |
Receiver | If the Text object should send input data to another object, set this field. |
ReceiverField | This field is used in conjunction with the Receiver object. |
String | This field must be set to the string that is to be printed |
TabFocus | Allows the user to hit the tab key to focus on other GUI objects. |
Visible | Indicates the visibility of a Text object. |
Width | Readable field that returns the maximum width of the text graphic. |
XCoord | Defines the horizontal position of the text graphic. |
XOffset | Defines the horziontal offset of the text graphic. |
YCoord | Defines the vertical position of the text graphic. |
YOffset | Defines the vertical offset of the text graphic. |
Field: | Align |
Short: | This field allows you to align the text within its container. |
Type: | LONG/FLAGS |
Prefix: | ALIGN |
Status: | Set |
If you would like to set an abstract position for the text, you can
give it an alignment. Note that setting the alignment over-rides any
settings in related coordinate fields. Valid alignment flags are as
follows:
BOTTOM
CENTER/MIDDLE
LEFT
HORIZONTAL
RIGHT
TOP
VERTICAL
|
|
Field: | CursorPos |
Short: | Indicates the current byte position of a Text object's 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 value. You can also update this
field if you wish to forcibly alter the current position of the cursor.
|
|
Field: | Drawable |
Short: | Defines the drawable area for the 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 object 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: | Flags |
Short: | Special behaviour is enabled through these flags. |
Type: | LONG/FLAGS |
Status: | Read/Set |
Special behaviour for a Text object can be activated through these
flags:
AUTOCLEAR | This flag will cause the Text object to clear the entered text when the enter key is pressed. |
EDIT | Switching on this flag allows the user to edit the text via the keyboard or whatever device is referred to in the Input field. |
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. |
OVERWRITE | Set this flag to turn on overwrite mode (if off, insert mode is enabled). |
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. |
|
|
Field: | Frame |
Short: | Forces the text 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: | Height |
Short: | Readable field for retrieving the pixel height of the text. |
Type: | LONG |
Status: | Get |
The height of the text graphic 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: | Input |
Short: | An object handler for key-strokes can be specified here to accept user input. |
Type: | OBJECTID |
Status: | Read/Write |
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 ignore anything that originates
from it.
|
|
Field: | Lines |
Short: | This field reflects the total amount of lines in the text data. |
Type: | LONG |
Status: | Get |
If you need to know how many lines have been specified in the Text String,
you can read this field to find out exactly how many there are. The minimum
number of lines is 1, unless the String field has not been set, in which
case zero will be returned.
|
|
Field: | Receiver |
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 Receiver field and specify the destination field name
by setting the ReceiverField string. So long as both fields are set correctly,
the destination object will always reflect the value currently entered
in the Text object.
|
|
Field: | ReceiverField |
Short: | This field is used in conjunction with the Receiver object. |
Type: | STRING |
Status: | Set |
This field needs to be set in conjunction with the Receiver field - please
refer to it for more detail.
|
|
Field: | String |
Short: | This field must be set to the string that is to be printed |
Type: | STRING |
Status: | Get/Set |
The text that is to be printed must be specified in this field, or no
graphics will be drawn by the Text object. The string should consist only
of printable characters, except for return-codes (character code 10) which
may be used to create line breaks.
Setting the String field automatically causes the Text object to re-draw
itself to its graphical area.
|
|
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: | 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 which is the case. 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: | Readable field that returns the maximum width of the text graphic. |
Type: | LONG |
Status: | Read |
To get the width of the text graphic at its widest point (important if
multiple lines are in use), read this field.
|
|
Field: | XCoord |
Short: | Defines the horizontal position of the text graphic. |
Type: | DOUBLE/PERCENTAGE |
Status: | Read/Write |
This field determines the horizontal position of the text graphic 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.
|
|
Field: | XOffset |
Short: | Defines the horziontal offset of the text graphic. |
Type: | DOUBLE/PERCENTAGE |
Status: | Write |
You can have the text graphic offset against the right of its container
by setting this field. A setting of 0 would place the text at the right
edge, while a setting of 10 would place it 10 pixels off from the right
edge. Negative values can move the text 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 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 text graphic. |
Type: | DOUBLE/PERCENTAGE |
Status: | Read/Write |
This field determines the vertical position of the text 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: | YOffset |
Short: | Defines the vertical offset of the text graphic. |
Type: | DOUBLE/PERCENTAGE |
Status: | Write |
You can have the text graphic offset against the bottom of its container
by setting this field. A setting of 0 would place the text at the bottom
edge, while a setting of 10 would place it 10 pixels off from the bottom
edge. Negative values can move the text 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.
|
|