Class Documentation

Name:Text
Version:1.0
ID:ID_TEXT
Status:Beta
Category:GUI
Date:August 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2001. All rights reserved.
Short:  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:

FlagDescription
AUTOCLEARThis flag will cause the Text object to clear the entered text when the enter key is pressed.
EDITSwitching on this flag allows the user to edit the text via the keyboard or whatever device is referred to in the Input field.
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.
OVERWRITESet this flag to turn on overwrite mode (if off, insert mode is enabled).
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.

 

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.