Class Documentation

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

Result
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().

 

Action:Clear
Short: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.

 

Action:DataChannel
Short: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.

Result
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.

 

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

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 from a TextList.
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 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.

Result
ERR_Okay  The line was deleted.
ERR_Args  The Line value was out of the valid range.

 

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 line within a TextList.
Arguments:
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.

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.

 

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:

FlagDescription
DOUBLECLICKIf 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.
MULTISELECTSet 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.