Class Documentation
TextList |
1.0 |
ID_TEXTLIST |
Beta |
GUI |
August 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. All rights reserved. |
Draws multiple lines of text as a list. |
Description
The TextList class is used for listing one or more lines of text in a
vertical arrangement. Its purposes are wide-spread, and is commonly used for
creating user-selectable lists of items, viewing text documents, creating
combo boxes and is even used to create file dialog boxes.
Scrollbars can be attached to a TextList object via the HScroll and VScroll
fields. You also have full control over the font details and positioning
of the graphic. The following DML example illustrates these features and
is suitable for viewing a text file:
<render x="50" y="70" width="400" height="400" colour="#ffffff">
<scrollbar name="vsb" xoffset="0" y="0" width="16" yoffset="0"
direction="vertical"/>
<textlist src="athene:myfile.txt" x="3" y="3" vscroll="vsb_scroll"
face="courier"/>
</render>
The TextList draws its graphics to the foreground only, so you have the
choice of defining your own background to be placed behind the text. In
the above case we cleared the Render object to white, but you may want
to use Gradients, Boxes, Images or other graphical objects in the
background. To change the attributes of a TextList graphic, you need to
access the Font field to set the Font attributes prior to
initialisation. By doing so, you can set the face of the Font, as well
as its colour, size and extra effects.
Actions
The TextList class supports the following actions:
Activate | Opens the current TextList selection. |
Clear | Clears the contents of a TextList object. |
DataChannel | Text data can be sent to a TextList object via data channels. |
Focus | Call this action to focus on a TextList object. |
SaveToObject | Use this action to save TextList information as a text file. |
Scroll | Scrolls a TextList 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 TextList class implements the following methods:
AddLine | Adds a new line to any row position in a TextList. |
DeleteLine | Deletes any line number from a TextList. |
GetLine | Returns the string content of any given line. |
ReplaceLine | Replaces the content of any line within a TextList. |
Structure
The TextList object consists of the following public fields:
AmtLines | Indicates the total amount of lines in a TextList. |
Drawable | Defines the drawable area for TextList graphics. |
Flags | Special flags that affect TextList behaviour. |
Focus | Refers to the object that will be monitored for user focussing. |
Font | Points to a Font that controls the drawing of text for a TextList object. |
HScroll | If scrolling is required, use this field to refer to a horizontal scroll bar. |
Height | A calculated field that indicates the height of a TextList in pixels. |
Highlight | String-based field for defining the colour to use when text is highlighted. |
Input | Refers to the Keyboard object that input should be read from. |
Location | Identifies the location of a text file to load. |
Selection | Readable field that reflects the data of the currently selected string. |
SelectionIndex | Indicates the current line that the user has selected. |
String | Text information can be written directly to a TextList object through this field. |
TabFocus | Allows the user to hit the tab key to focus on other GUI objects. |
VScroll | If scrolling is required, use this field to refer to a vertical scroll bar. |
VSpacing | The amount of white space between each line of text. |
Width | Readable field that returns the pixel width of the longest line. |
XCoord | Defines the horizontal position of a TextList graphic. |
YCoord | Defines the vertical position of a TextList graphic. |
Activate |
Opens the current TextList selection. |
Calling the Activate action will cause a TextList object to send Activate
messages to the child objects that have been initialised to it. This is
particularly useful for responding to user selections (enabled when the
MULTISELECT and SINGLESELECT Flags have been used).
When building an interface that utilises an interactive TextList, you will
need to create a user input object, such as an OnClick or Keypress, that
calls the Activate action for the purposes of user interaction. If you would
rather use a shortcut, an alternative option is to set the DOUBLECLICK option
in the Flags field.
ERR_Okay | The selection was successfully opened. |
ERR_Failed | Indicates that the user has not made a valid selection from the TextList. |
ERR_NoData | The selected line does not contain any data. |
ERR_ListChildren | A list of child objects could not be obtained from ListChildren(). |
|
|
Clear |
Clears the contents of a TextList object. |
You can delete all of the text information from a TextList object by calling
the Clear action. All of the text data will be deleted from the object and
the graphics will be updated as a result of calling this action.
|
|
DataChannel |
Text data can be sent to a TextList object via data channels. |
One of the easiest ways to send text information to a TextList object is
to do it via data channels. The TextList class currently supports the
DATA_TEXT type for this purpose. If the text contains return codes, the
data will be split into multiple lines.
The drawable that is associated with the TextList object will be redrawn
as a result of calling this action.
ERR_Okay | Success. |
ERR_Args | Invalid arguments were specified. |
ERR_AllocMemory | The TextList's memory buffer could not be expanded. |
ERR_Mismatch | The data type that was passed to the action is not supported by the TextList class. |
|
|
AddLine() |
Adds a new line to any row position in a TextList. |
STRING Text | The text that you want to add. |
LONG Line | The number of the line at which the text should be inserted. |
LONG Length | The length of the Text string. |
|
Lines can be added or inserted into a TextList object by using the AddLine()
method. You need to provide the Text string that you want to add, 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 TextList. 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 TextList'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 from a TextList. |
LONG Line | The line number that you want to delete. If negative, the last line will be deleted. |
|
This method deletes lines from a TextList object. Just specify the line
number and the method will delete it. If the line number does not exist,
then the call will fail. The TextList 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. |
|
|
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 line within a TextList. |
STRING Text | The text data that you want to use in replacing the line. |
LONG Line | The line number that will be replaced. |
LONG Length | The length of the Text string. |
|
Any line within a TextList can be replaced with new information by using the
ReplaceLine() method. All you need to provide is the text string that you
wish to use, the number of the line that will be replaced, and the length of
the text string.
If you set the Text argument to NULL, then an empty string will replace
the line number. If the Length is NULL, then the length of the new string
will be calculated by counting the amount of characters in the Text
argument.
If the new line content is visible within the TextList'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. |
|
|
Field: | AmtLines |
Short: | Indicates the total amount of lines in a TextList. |
Type: | LONG |
Status: | Read |
The total amount of lines in a TextList can be read from this field. If
there are no lines in the list then a value of zero will be returned.
|
|
Field: | Drawable |
Short: | Defines the drawable area for TextList graphics. |
Type: | OBJECTID |
Status: | Read/Write |
In most cases, when you create a TextList object it should be contained by
a drawable area, such as a Render object. If you do this correctly then
the TextList 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 TextList object to a non-graphical container. If this is the
case then you must set the Drawable field to point to a valid drawable
area, such as a Render object.
|
|
Field: | Flags |
Short: | Special flags that affect TextList behaviour. |
Type: | LONG/FLAGS |
Prefix: | TLF |
Status: | Read/Set |
Special flags that apply to the TextList are as follows:
DOUBLECLICK | If this flag is set then the TextList object will respond to double clicks by automatically calling the Activate action on itself. This is useful for creating an interactive TextList without the hassle of setting up a user object that manages TextList interaction. |
MULTISELECT | Set this flag if you want the user to be able to select multiple lines from a TextList. |
SINGLESELECT | Set this flag if you want the user to be able to select single lines from the list. When a line is selected, the SelectionIndex field is immediately updated to reflect the current line number. |
|
|
Field: | Focus |
Short: | Refers to the object that will be monitored for user focussing. |
Type: | OBJECTID |
Status: | Read/Init |
By default, a TextList 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 TextList becomes active when some other
object receives the focus, refer to that object by writing its ID to this
field.
|
|
Field: | Font |
Short: | Points to a Font that controls the drawing of text for a TextList object. |
Type: | struct Font * |
Status: | Read |
To set the face, colour and other attributes of a TextList's graphics,
you need to read the Font field and write your settings to the Font object
prior to initialisation. For a list of all the fields that can be set, please
refer to the documentation for the Font class.
You are strongly discouraged from writing information to a Font object
after the initialistion of a TextList, although you may read information from
the Font after initialisation.
|
|
Field: | HScroll |
Short: | If scrolling is required, use this field to refer to a horizontal scroll bar. |
Type: | OBJECTID |
Status: | Read/Set |
If you want to attach a horizontal scrollbar to a TextList object, set
this field to an object belonging to the Scroll class. So long as the Scroll
object is set up to provide full scrollbar functionality, the user will be
able to scroll the text display along the horizontal axis.
|
|
Field: | Height |
Short: | A calculated field that indicates the height of a TextList in pixels. |
Type: | FLOAT |
Status: | Get |
The exact height of a TextList can be read from this field. The value
that is returned is a total that includes the height of each individual line,
and compensates for vertical and gutter spacing.
|
|
Field: | Highlight |
Short: | String-based field for defining the colour to use when text is highlighted. |
Type: | STRING |
Status: | Set |
If the SINGLESELECT or MULTISELECT flags have been used, you may want to
define the colour that is used to highlight selected lines. You can do that
by writing a standard string-based colour to this field.
|
|
Field: | Input |
Short: | Refers to the Keyboard object that input should be read from. |
Type: | OBJECTID |
Status: | Read/Init |
By default a TextList object will read information from the SystemKeyboard
for the purpose of receiving keyboard based user input. If you would like
a TextList object to receive its keyboard input from elsewhere, write the ID
of that input object to this field.
|
|
Field: | Location |
Synonyms: | Src |
Short: | Identifies the location of a text file to load. |
Type: | STRING |
Status: | Get/Set |
If the data for a TextList comes from a file, the easiest way to load
it into the TextEditor is to set the Location field and have the TextList load
the data for you. The alternative is to load the data manually and then
set the String field with a data pointer.
|
|
Field: | Selection |
Short: | Readable field that reflects the data of the currently selected string. |
Type: | STRING |
Status: | Read |
This field can be read at any time to get the string of the currently
selected line. If no line has been selected, or if the selected line is a
zero length string, then an error code will be returned.
|
|
Field: | SelectionIndex |
Short: | Indicates the current line that the user has selected. |
Type: | LONG |
Status: | Read |
If you need to find out what line is currently highlighted, you can read
the SelectionIndex field to get the line index. If no item is highlighted
then the SelectionIndex will be set to -1. In all other cases it will be a
number greater or equal to 0.
|
|
Field: | String |
Short: | Text information can be written directly to a TextList object through this field. |
Type: | STRING |
Status: | Get/Set |
You can update the data of a TextList by passing text information to the
String field. Updating a TextList in this fashion causes it to analyse the
string information for return codes, so you can still split the string data
into lines. If any data is in a TextList when you set this field, it 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 the focus to that other object (technically this causes
the focus to be set to that object, and the TextList 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 when using the keyboard.
|
|
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 TextList 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: | VSpacing |
Short: | The amount of white space between each line of text. |
Type: | LONG |
Status: | Read/Init |
This field defines the total amount of white space (measured in pixels)
between each line of text. If you do not set this field on initialisation,
the default amount of spacing will be acquired from the font that is being
used. It is recommended that a value between 2 and 10 is set in this
field.
|
|
Field: | Width |
Short: | Readable field that returns the pixel width of the longest line. |
Type: | LONG |
Status: | Get |
If you need to find out the width of a TextList then you can read it
from this field. The width that is returned is that of the longest line
in the TextList. Note that the longest line does not necesarily have the
most characters, unless the font is of a fixed size (a line of 30 'w'
characters will typically be longer than a line of 50 'i' characters
because of the difference in character width).
|
|
Field: | XCoord |
Short: | Defines the horizontal position of a TextList graphic. |
Type: | FLOAT |
Status: | Get/Set |
This field defines the horizontal position of a TextList graphic from
the top of its container. The value can be set as a fixed pixel coordinate,
or as a percentage if the FD_PERCENT field is used.
|
|
Field: | YCoord |
Short: | Defines the vertical position of a TextList graphic. |
Type: | FLOAT |
Status: | Get/Set |
This field defines the vertical position of a TextList 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.
|
|