Using CTC windows

Contents:

CTC palette - creating and editing CTC windows.

Script control of CTC windows

Editing ctc files.

The CTC windows are the main man-machine interface for TCL scripts. They are useful for both input and output and are typically used to illustrate the state of your layout. The following type of information can be displayed in the CTC windows:

A track layout diagram, possibly animated using colour to show the state of each track section or where each train is. Turnouts can also be animated.

Text. This can be fixed labels, or messages from the script.

Graphics. Image files can be displayed can these could be representations of signals, trains or whatever.

A CTC window is a grid of cells and each cell can contain a segment of track, a text message, a graphic image or some combination of these. The window can be of any size (up to full screen) and have any number of cells displayed. Script controlled panning is currently supported and also several CTC windows could all be full screen and the script can control which window is at the front.

User input is in the form of mouse clicks. A click in a cell is communicated to the script to the mouse can be used to control points, despatch trains, adjust speed or anything you could write a script for.

Window basics

CTC windows can be resized like any other widow. The cells expand and contract according to the resizing you perform. If on the other hand you resize with the SHIFT key pressed then the window is resized but the cells are not - this is how to change the number of cells displayed. Another way to achieve the same objective is to edit the ctc file - under the headings CTC <number> <string> is a line starting 'size' - edit the two numbers for number of columns and rows displayed. See below on editing ctc files.

CTC windows have titles like other windows. These titles default to CTC <number> but this can be changed by editing the ctc file - in the line CTC <number> <string> - the string is the title of the window.

The background colour and grid colour can both be changed, again by editing the 'background' and 'gridColour' lines in the ctc file.

CTC windows do not have a finite number of cells in them - it is only the display that is finite. Cells may exist outside of the displayed area. This is possible if you insert extra cells (see inserting and deleting cells, in the ctc pallette description below).

Declaring CTC windows in your script

A CTC window is defined by declaring an object variable in your script. These are special variables and as such are not declared in the Variables: section. Controlling the window is done by calling methods associated with the CTC window vaiables. See CtcWindow for details.

CtcWindows: track, yard          { CTC1 is called track, CTC2 is called yard }
Actions:
WHEN … DO yard.colourTrack ("Y1", red)

CTC palette

The CTC palette (available from menu->View->Tracks) allows the CTC windows to be edited. When the palette is open coordinates are added to the CTC windows. In addition each time you click in a CTC window the click is illustrated in the program status box in the bottom left of the tcc window. These systems are to aid coordinate entry into your scripts, though the META data mechanism makes this obsolete. If you are making a new script it is much better to use META names for cells instead of co-ordinates because you may want to edit the layout later and that might change all your carefully recorded co-ordinates.

Each tool on the palette is used by clicking the tool, and then clicking in the CTC window where you want the tool to be applied. Close the palette to hide the extra coordinates.

Track segments

A track layout diagram (or other line drawing if desired) is normally made using the straight track, curved track, turnout and crossing tools from the palette. Take a little time to get used to these tools and you will find entering a track layout quite easy. Select for example the straight track tool and focus on a single cell in one CTC window. Imagine that cell is made of nine smaller cells. Clicking in any of the eight outer mini cells will cause the track you have selected to be drawn, but finishing at the position that you clicked. This allows the track to be rotated into any orientation you want on a single click (once you get used to it!). Clicking in the centre will rotate the existing track segment clockwise.

To remove a track segment use SHIFT-click while any of the track segment tools are selected.

You are not constrained to just the shapes of track in the palette. Each cell contains segments of lines that radiate out from the centre. The drawing system can draw any combination of these eight lines in each cell but a little detective work is required to understand how it works. If you look in the ctc file (assuming you have some track segments drawn in a CTC window and have exited and re-entered Tcc) for the lines beginning 'CELL' then the magic is in the hexadecimal number following the word 'LINE'. Look at the last byte of the number (two hex digits). The eight bits each control one of the mini segments in that cell. You could make three-way points, double slips, 90 degree bends etc. The upper bytes are the same except they are used to display the multiple aspects of turnouts. The script action $switch sets the state of the cell line display which selects which byte to use where byte 0 is the least significant byte, 1 is the next byte and so on. For states other than zero any segments in state 0 that are missing in the selected state are drawn in gray (so that turnouts look still look like turnouts, but the direction is clear).

Blocks

Track can be coloured using the palette, or from the script. Colouring from the script can affect single cells, or blocks of cells. Grouping cells into blocks uses the 'B' or block tool. Select the block tool and move your pointer over a CTC window - the track in all cells currently in a block turn into fatter blue lines. If the cell you are over is itself in a block it goes fat red along with the whole of its block. Cells not in any block remain narrow and in their own colour (default black). This allows quick and easy preview of the blocking of your track display. To make a new block click on a track that is not in a block - that one cell goes fat red. All cells currently displayed in fat red are in the group you are editing - in this case you have just created a new block with one cell in it. Clicking on other cells adds then to the new block (possibly removing them from other blocks if required). Clicking on a cell already in the block you are editing removes that cell from the block (it goes blue again). The cells do not have to be adjacent to be in a block though that would be normal for a track layout diagram. To finish editing that block click the block tool 'B' on the palette again. The fat red lines join the blue ones. If instead of creating a new block you click on a cell already in a block then you are editing that block (all its cells have gone fat red) and you can add or remove cells in the same way. Once again finish editing by clicking 'B'. When you click a different tool on the palette the cells are redrawn in their own colours and block editing has finished.

Naturally you can assign cells into blocks by editing the ctc file. They are simply grouped together in the file under headings 'BLOCK <name>'.

Text

Fixed text can be placed using the text tool 'abc'. This opens a text entry window containing a text entry box, three size buttons and nine position buttons. The sizes small, medium and large vary automatically as the window is resized, so the text remains roughly in proportion to the track being displayed. The nine positions are of most use for small text which can be positioned into the corners of a cell. Select size & position then enter some text and click in a cell in a CTC window. The new text is added to the window. To remove text backspace in the text entry window and then click on the cell - you are overwriting with an empty string which removes the text from the window.

Right-clicking (or shift-click) causes the text already in a cell to be loaded into the text editing window. Useful for both editing and copying to other cells.

If the script draws text in the same cell then the script text takes precedence and the fixed text disappears. Only one item of text can be placed in each cell.

Meta data

Each cell can be given a meta data name and value. This is a hidden labelling system that the script can use to address cells without knowing their x,y,z co-ordinates. This means of course that the cells can be shuffled around and the script doesn't need updating. The "Meta" tool is used to view and edit these names. It works in a similar fashion to the text editing tool. The value you can assign can be ignored for most scripts, just focus on the names. As a starting point assign a META name to each turnout and to each block. The script can then control the turnouts and colour the blocks using their name.

Colouring

Track lines and text can be coloured. Click on the colour swatch tool and then click in the required cell. If a track segment is present it will be coloured, otherwise if a text item is present it will be coloured. The text and track can be different colours by entering the text first, giving it a colour, then entering the track segment and giving it a colour. The script can override the colour selection, but the palette entered colour is restored when Tcc is started or if you press reset.

Shuffle: Inserting and deleting cells.

If your track layout is complicated then sooner or later you'll need to shuffle things around to add in a new bit of track. The '<^>' tool is used for this. The symbol represents three arrows - I couldn't figure how to easily do a down arrow too! Once you select the shuffle tool click in a cell of a CTC window:

1. Top-centre of a CTC cell then all cells below it are moved up. Think of clicking at the top to be pushing upwards.

2. Bottom centre 'pushes' down.

3. Left-centre pushes cells to the right leftwards.

4. Right-centre pushes cells to the right rightwards,

Other locations in the cell do nothing, nor do modifiers like shift.

You cannot move cells above or to the left of where you click. For example to move rows 2,3,4 up to rows 1,2,3 and thus delete row 1 and make an empty row 4 (shuffling your track upwards to make room for some more) you might click in the top centre of each cell in row 2 and then bottom centre in each cell of what is now row 4.

Be aware that shuffle actions are likely to require edits to your script as cells have moved. You can avoid this by using 'META data' names.

Script control of CTC windows

NOTE: Most of the following information is augmented in: CtcWindow

Cells are addressed by any of several methods:

This means that either one or two parameters are used to specify which cell is used.

Column and row numbers start at 1 and go as high as you need.

Cell addresses not containing variables can be manipulated like any other data, as illustrated above:

x = [1,2] { The CTC address 1,2 is stored in variable x }

ctc.colourTrack (x, red)

x = "name" { Save a META name is a variable }

ctc.colourTrack (x, green)

Track and text colouring

Track and text can be coloured using:

ctc.ColourTrack (cellId, colour) { colours the track in a single cell }

ctc.ColourBlock (cellId, colour) { colours all the cells in the same block }

ctc.ColourMessage (cellId, colour) { colours the text in that cell }

The colour can be a predefined colour such as 'red' or 'green', a colour constant such as $RGBbbggrr where bb gg and rr are hex numbers representing the relative strength of each colour. $RGB0 is black, $RGBFF is red and $RGBFFFFFF is white.

Predefined colours are taken from the standard resistor colour codes with a few extras thrown in:

Colour	Red component	Blue	Green
Black	0	0	0
Brown	144	72	0
Red	255	0	0
Orange	255	128	0
Yellow	255	255	0
Green	0	255	0
Blue	0	0	255
Purple	128	0	255
LtGray (light gray)	64	64	64
Gray	127	127	127
DkGray (dark gray)	192	192	192
White	255	255	255

Portions of a block can be addressed if desired by using:

ctc.ColourBlock (cellId, colour)

ctc.ColourBlock (cellId, colour, stroke, from, to)

from and to are numbers (or variables holding numbers) representing the proportion of the block to colour. The default is FROM 0 TO 100 but this allows for finer control without the script having to know where each cell is, or even how many cells are in the block. The cellId can refer to any cell in the block or can be the META name of the block itself.

Animating track

Track which varies its geometry such as turnouts and slips can be animated using:

$Switch (x,y,z)=state

For turnouts state 0 means left, state 1 is right and higher numbers mean unthrown (the default state on the CTC with both directions darkened).

Strictly speaking states 0, 1 etc mean 'use the second, third etc. byte of the LINE value from the ctc file'. A value higher than the number of available upper bytes means to use the first byte (lowest significant byte). This is only of interest if you want to design your own track segments.

Displaying text

Text can be added, edited or removed using:

ctc.drawMessage (cellId, message)

ctc.eraseMessage (cellId)

Where string can be a string constant such as "hello", a string variable or a regular variable pointing to a string. It can even be a normal variable holding a number in which case the number is converted into a string.

The colour, size and position of text can be set by using:

ctc.drawMessage (cellId, string, size, position, colour, background)

The values for size and position are defined for the methods setMessageSize () and setMessagePos () here.

Displaying graphics

Graphic image files can be drawn on CTC windows using:

ctc.draw image (x,y,"filename")

These graphics can be resized and rotated as they are drawn, and can be moved around the window, perhaps illustrating where your trains are. For more information on image handling functions look here.

Editing CTC files

A CTC file contains a textual description of each CTC window. The syntax used is:

CTC <number> <title> background <colour> gridcolour <colour> font <size> <style> <font name> <scale>	Introduces a new CTC window. <number> is 1..4 and <title> is window title. Optionally set background colour for window. 6 digit hex number. Optionally set colour of grid lines <size> is small|medium|large. <style> uses values from java.awt.Font. <font name> is the name of the font, such as Arial. <scale> is proportion of cell size which is defined as height plus width. The font line may be repeated for each of the three sizes.
size <num columns> <num rows>	Optionally define how many cells are displayed.
block <name>|null	Introduces a new block (group of cells for ColourBlock actions). Block null lists all cells not in a block. Block <name> lists cells in that block. Block names are not used in the script yet. Each CTC window can have any number of blocks defined.
defcolour <colour> linecolour <colour>	Default colour for text. Default colour for track lines.
cell <x,y> line <hex number> colour <colour> rotate <number> text "string" colour <colour> font <size> position top|middle|bottom left|centre|right meta <name> <number>	Define contents of a cell at position x,y (1,1 is top left). Optional: cell contains track of shape specified by number. See Track segments above. Optionally set colour of track segment. Optional: Set default image rotation for this cell. Optional: Add message text to this cell. Optional: Set colour of this text Optional: Set text size to small|medium|large. Default to medium Optional: Set text position. Optional: Assign a META name to this cell and also a meta data value. Each group can contain any number of cells.

Note that several ctc files will exist in your project directory (a directory with the same name as the tcl file you run). Look for the most recent file before editing. The test for most recent that Tcc uses is the version number in the first line of each file – the highest version is the most recent, the lowest version is the oldest and is eligible to be discarded when there are already ten files. The reason Tcc uses version numbers is to prevent accidental confusion when manually copying or backing up files. If you copy a ctc file from one project to another you might want (or need) to change the version number in the copied file.

Last Updated 12 July 2017

©Howard Amos 2008-2017