CtcText objects in TCL

CTC windows can display text messages using ctc.drawMessage (). There are times that this simple mechanism becomes restrictive. For example what if your script might display reports of problems to the operator. Suppose you might wish to report that a particular train has lost contact, or that a train has failed to get to the next section of track is a reasonable time, or that a section not in use has detected current drawn. There could be dozens or even hundreds of possible messages so each one cannot have a space in the CTC window dedicated to a chance of a problem. Nor can you use a single space because several problems can happen at once. You can start at the top of a CTC window and add each message one row down. What happens when you reach the bottom of the window? What happens when a problem goes away - how do you remove that message and reuse the window space?

CtcText are objects that can hold and display several lines of text. Lines of text can be added with the add() method, and can be removed automatically, or with the remove() method. A CtcText object can be displayed on a CTC window using $Draw Message as if it were a regular string.

Each line of text can have a string key, or tag associated with it. All keys must be unique. If a new line is added with the same key as an existing line then it replaces the existing line. This can use useful if an error might be detected several times and only one line of display should show it. Also giving a line a key means you don't have to save the sequence number returned by adding the line - when an error goes away you can specify which line to remove using the key.

Each line of text has a priority. Lines of the same priority are displayed in the order they are added. Lines of higher priority are listed above lines of lower priority. This allows messages of higher importance (such as show-stopping errors) to be displayed higher up and so demand urgent attention. The priority defaults to lowest priority of 1.

Also each line can have a retention time and new priority. If the retention time is specified (in seconds) then the message is removed from its current priority position and re-inserted at the new priority. The new priority defaults to zero which means the line is removed and discarded. This mechanism allows important messages to be displayed with high priority for a few seconds, and then perhaps demoted to join 'ordinary' messages.

The following methods exist in each CtcText object:

Method name	Description
seq=add (string {, key})	Adds a string at priority 1 (the lowest priority). All add () methods return a sequence number which can be used to reference the string later on. If a string key is given then it is saved with the line displayed.
add (string {, key}, pri) add (string {, key}, pri, retentionTime) add (string, pri, retentionTime, newPriority)	Add a string at the specified priority. Add a string that will be removed when retentionTime expires. Add a string at specified priority and then change priority after retentionTime
remove (seq-or-key, ...)	Remove one or more strings added earlier. The seq (sequence) parameter is the value returned when the string was first added. Alternatively a string key can be given to find which line to remove.
removeAll ()	Clear the whole CtcText object.
s=getText (seq-or-key)	Returns the text stored against the specified sequence number or key-string.
s=getLine (lineNo)	Returns the text currently displayed at the given line number. The top line is line 1. Returns zero if line does not exist.
change (seq, string) change (seq, string, pri) change (seq, string, pri, retentionTime) change (seq, string, pri, retention, newPriority)	Change the string stored in the given message. Change the string unless the empty string ("") and the priority. Change string, priority (unless 0) and retention time. Change string, priority, retention time, and new priority.
setMaxLines	Set the maximum number of lines that may be displayed. If too many lines are added the lowest priority lines are discarded. MaxLines defaults to 20.

Simple case of displaying a few messages:

CtcText:   ct
Actions:
WHEN initialising DO $Draw Message(1,3,3)=ct
WHEN x>10 DO ct.add ("Error. x is too large: @x")
WHEN x>0, x<10 DO ct.add ("Debug: x=@x", 1, 5) { 5 second display only }

The size of the text displayed defaults to any size previously used in the cell, or can be specified in the draw message as usual:

CtcText:   ct
Variables: seq
Actions:
{ size 64 is small, 128 is medium, 256 is large }
WHEN initialising DO $Draw Message(1,3,3)=ct SIZE 64
WHEN x>10 DO seq=ct.add ("Error. x is too large: @x")
WHEN x<10 DO ct.remove (seq) {problem has been fixed, remove message}

A single CtcText may be displayed in several places, but they will all share the same size attribute.

The whole CtcText may be hidden by using $Erase Message. This removes the whole block of messages from the screen, but they are still in the CtcText object which can still be manipulated as required, and perhaps put back on the screen when required.

Last updated 20 Dec 2009