Traditionally CTC windows have been manipulated using reserved words beginning with a dollar sign, such as $Draw message and $switch. Rather than extend this system new features will be added using the objects that many other features enjoy.
The CtcWindow objects take the name specified in the declarations part of the script, as with any variables. This name has no bearing upon the name (or title) of the displayed window. CTC windows default to having a title of 'CTC' followed by its window number but this can be changed either by editing the ctc file, or by using the ctcSetTitle method described below, or even the System.windowSetTitle method which can be used on almost any Tcc window.
A CtcWindow object has the following methods currently implemented:
|
setSize (cols, rows) |
Sets the current viewable area in terms of CTC cells. Note that cell size is constant so window size varies with number of cells displayed. |
|
setCellSize (colWidth, rowHeight) |
Sets the size of each cell in the window. Note that the window size is unchanged so the number of cells displayed will change. |
|
panTo (col, row) |
Set the offset to the cell displayed in the top left corner. panTo (0,0) restores the normal view. |
|
Set the colour of the track in this specified cell. |
|
|
Set the colour of the whole block containing the specified cell. 'from' and 'to' are percentages that default to 0 and 100 that specify how much of the block to colour. Note that the cells in the ctc file must be in sequence for fractional colouring to make sense. |
|
|
setTrackAspect (cellId, aspect) |
Select the aspect used to display the track segment specified. This replaces the $switch action. |
|
setTrackLines (cellId, lines, lines, ...) |
Set the pattern of track segments shown for the specified cell. The first 'lines' parameter is the default pattern, subsequent parameters (up to eight in all) specify other aspects. Each lines value is a number in the range 0 (blank) to 255 (a star symbol). |
|
popup (cellId, menu items, ...) |
Display a popup menu in the specified cell. See below for allowed formats of the cellId parameter. The popup is populated from the list of menu items. Each parameter can be a single menu item, a list of menu items, or even a database query to populate a sub-menu. See below for more details of cellId parameter formats and for menu item formats. |
|
popupName () |
Returns the name of the item last selected from a popup. |
|
popupSubName () |
Returns the name of the sub menu the last selection was from, or a null string is the last selection was from the main menu. |
|
ctcSetTitle (name) |
Set the title of the window. The title defaults to 'CTC<n>' where <n> is the CTC number, or to a string edited into the project/ctc.? File. |
|
drawMessage (cellId, message, [size], [position], [colour], [background]) |
Draw the message starting at the specified cell. The last four parameters are all optional and any may be omitted by leaving blank, for example drawMessage (1,1,"X",,4) skips the size, sets position to 4 and omits colour and background. See setMessageSize and setMessagePos below for accepted values for these parameters. See below for more details of cellId parameter formats. |
|
setMessageSize (cellId, size) |
Set the size of the message already drawn in the specified cell. Permitted sizes are: 1=small, 2=medium, 3=large |
|
setMessagePos (cellId, pos) |
Set the position of the message already drawn in the specified cell. Permitted values are as per the cell track line bitmap: 0=centre, 1=top-left, 2=top centre, 3=top right, 4=right, 5=bottom right, 6=bottom, 7=bottom left, 8=left |
|
Set the colour of the text, and optionally the background colour of the text in the specified cell. Foreground colour can be omitted by using two commas, for example colourMessage (1,1,,red) |
|
|
eraseMessage (cellId) |
Erase the message from the specified cell. See below for more details of cellId parameter formats. |
|
ctcFront () |
Bring this window to the front if it is open. This is the same as System.windowFront (ctc Number) |
|
ctcBack () |
Take this window to the back, behind other windows. |
|
ctcMetaName (cellId) |
Returns the META name given to the specified cell, or undefined (value 0) otherwise. |
|
ctcMetaData (cellid) |
Returns the META value given to the specified cell, or undefined (value 0) if no meta data has been assigned. The returned value could be a numeric value, or a string dependant upon what has been assigned. |
|
ctcSetMeta (cellId, name, value) |
Assign META data to a cell. If "name" exist anywhere already, it is deleted before the new entry is added. Value may be a string or a numeric value. If a string that is a valid numeric value, such as "123" the numeric value is stored. |
|
x=drawImage (cellId, filename, width, height) x=drawSprite (cellId, filename, width, height) |
Draw a new image loaded from file <filename> (a string parameter) at the specified cell (see below for allowed formats of cellId). If not specified height defaults to the same as width, and width defaults to 1. Images are associated with CTC cells (only one per cell), are aligned to cell boundaries, can be moved by specifying the cell (see moveImage) and are drawn behind the track lines. Sprites are independent of CTC cells (though are positioned using the same coordinates), can be drawn offset from cell boundaries and are drawn in front of track lines. Sprites cannot be moved by specifying the cell they are in. |
|
addAspect (cellIdNum, fileName) |
Add another aspect to an existing image. The initially drawn image becomes aspect 1, and subsequently added aspects are number 2, 3 and so on. The displayed aspect is selected using setImageAspect (). This mechanism is more efficient than loading images repeatedly by cycling around several drawImage calls which can eventually lose memory. |
|
Modify first aspect, or add another aspect where each aspect is a re-coloured version of the basic image originally drawn. Any number of oldColour, newColour pairs may be specified and pixels which match or are close to the oldColour are replaced with newColour. See below for a definition of colours being close. |
|
|
setImageAspect (cellIdNum, aspect) |
Select which aspect of a multi-aspect image to display. Values out of the range 1..<number of aspects> cause the image to be hidden until a valid aspect number is given. |
|
moveImage (CellIdFormat, newCellid) moveImageND (ditto) |
Move an existing image. The first parameter (or two) specifies the image to manipulate and can be any cellId format described below, or can be a value returned by drawImage. The second cellId optionally specifies where to move the image to. See "Drawing images and sprites" below for moveImageND. |
|
moveSprite (imageNumber, newCellId, xFraction, yFraction) moveSpriteND (ditto) |
Move an existing sprite. The first parameter is a value returned by drawSprite. The cellId specifies where to move the sprite to. The optional fraction parameters cause the image to be drawn off-grid by the specified percentage of cell size. If xFraction is 50 the left edge of the image is positioned 50% of the way across the specified cell. yFraction moves downwards. The fraction parameters are not restricted to the range 0..100. |
|
setOffset (cellIdNum, x, y) setOffsetND (ditto) |
Define the point within the image to be treated as the origin of the image. These values are percentages so 0,0 is the top left of the image, 100,0 is top right. If not specified they default to 50,50 which is the centre of the image. Note these are fractions of the drawn image size, not the cell size. |
|
rotateImage (cellIdNum, rotation, x, y) rotateImageND (ditto) rotateSprite (imageNumber, rotation, x, y) rotateSpriteND (ditto) |
Rotate an existing image or sprite to the specified rotation value (in degrees). Rotation is not limited to the range 0..360. The optional x and y parameters specify the point within the image to use as the centre of rotation. These values are percentages so 0,0 is the top left of the image, 100,0 is top right. If not specified they default to 50,50 which is the centre of the image. Note these are fractions of the drawn image size, not the cell size. See "Drawing images and sprites" below for rotateImageND. |
|
scaleImage (cellIdNum, scaleX, scaleY, fill) scaleImageND (ditto) scaleSprite (imageNumber, scaleX, scaleY, fill) scaleSpriteND (ditto) |
Scale an existing image to the size specified as a count of columns and rows. scaleY defaults to the same as scaleX. fill defaults to 0. If fill is zero the image is scaled proportionally until either width or height is the size specified. If fill is 1 then the image is scaled unequally so the specified number of cells are completely filled (if the image is not rotated). See "Drawing images and sprites" below for scaleImageND. |
|
flipImage (cellIdNum, flipX, flipY) flipImageND (ditto) flipSprite (imageNumber, flipX, flipY) flipSpriteND (ditto) |
If flipX is non-zero the image is reflected horizontally, if flipY is non-zero the image is reflected vertically. |
|
hideImage (cellIdNum) hideSprite (imageNumber) |
Make the specified image (or sprite) invisible. It is still in the cell or location it was previously but it is simply not drawn. |
|
showImage (cellIdNum) showSprite (imageNumber) |
Make the specified image visible again after being hidden. |
Other methods are expected to duplicate the set of CTC image functions and add support for textual images and sprites (foreground images) as well as background images.
The methods taking a CTC cell address (cellId) as a parameter will accept the following formats:
|
col, row |
Actually two parameters - two numbers or variables or expressions evaluating to two numbers which give column number (starting from 1) and row number (starting from 1) |
|
[col, row] or [col, row, windowId] |
A bracketed set of two or three constant integers. This format is a single parameter and the row and column (and optionally the CTC window number) is encoded into a single value. This format is more normally used to store a cellId in a regular variable. Any window number is ignored by CtcWindow objects as that is naturally inferred by the use of a CtcWindow object. |
|
variable |
A variable that has either an XYZ value ([col, row] or [col, row, window]) or a meta name string in it. |
|
"name" |
A meta name that should exist in the ctc file. Such names need to be manually edited into the ctc file. Meta names have the advantage that if the CTC diagram is edited, perhaps by inserting or deleting rows or columns (using the <^> tool in the pallette) the script doesn't need editing to keep cell Ids in line with the ctc file. |
In addition to the above, cellIdNum parameters can be a value returned from a previous drawImage call.
Images are pictures that are drawn behind track lines, as a backdrop. Sprites are pictures drawn in front, perhaps to illustrate a train moving on a track.
Both kinds may be manipulated by using the appropriate move, rotate and scale methods.
The methods ending ND (such as rotateImageND), meaning No-Draw, do not trigger a screen redraw, so if you need to move, rescale and rotate an image in one go, use all three methods, but use ND for all but the last one. This should reduce the likelihood of unwanted temporary images appearing on the screen.
Images can hold multiple aspects (several graphical pictures in a single CTC cell). Only a single aspect is visible at once and this can be selected using setImageAspect (). Selecting between multiple aspects (a signal for example) is more efficient than repeatedly loading images as the latter mechanism would eventually run out of memory.
When images are re-coloured using addAspect (imageid, oldColour, newColour) the following procedure is followed: If this is the first re-colouring of the image then the image is first converted to a 256 colour pallette to reduce the potential number of colours in the image. This pallette is formed using a 6/6/6 colour cube with the remainder of the space filled with grey scale. This means there are 6 levels of red, six of blue and six of green making 216 colours (plus the grey scale levels). A pixel matches oldColour if the sum of the three colour level deltas is less than 60. This means either the colours match exactly (within the 6/6/6 cube) or two (of red, green and blue) match and the third is off by one slot. The exact mechanism might change if some other comparison seems to work better across a range of images.
An example of how to use re-colouring is to load an image of a signal, with ALL coloured aspects showing at once:
CtcWindows: Signals
Actions:
WHEN init=0 DO
sig=Signals.drawImage (2,4,"images/sig3.jpg",1,2),wait 2
Signals.addAspect (sig,yellow,gray,green,gray), { convert the image to red aspect only }
Signals.addAspect (sig,red,gray,green,gray), { Add a yellow aspect }
Signals.addAspect (sig,red,gray,yellow,gray),cycle=1
WHILE cycle=1 DO
Signals.setImageAspect (sig,1), wait 1, { select red aspect }
Signals.setImageAspect (sig,2), wait 1,
Signals.setImageAspect (sig,3), wait 1,
|
The first statement load the image called "images/sig3.jpg" which is a 3 aspect signal with the three aspects already coloured red, yellow and green. The image is loaded into square 2,4 at two cells high. The wait 2 allows the image loading to complete before recolouring is attempted. Then the red aspect is created by turning both yellow and green into gray. Similarly the yellow and green aspects are created by converting the other two aspects (of the ORIGINAL) image to gray. In this example the signal is simply animated slowly between red, yellow and green.
If you want to create a four aspect signal which has two yellow aspects then perhaps the second yellow should be created blue. Then the blue converted to gray or yellow as appropriate.
The following colours are pre-defined in TCL, and are an adaptation of the colours defined at http://cloford.com/resources/colours/500col.htm
Black Gray20 LtGray Gray40 Gray Gray60 DkGray Gray80 White |
RGB_000000 (or simply RGB_0) RGB_333333 RGB_404040 RGB_666666 RGB_7F7F7F RGB_999999 RGB_C0C0C0 RGB_CCCCCC RGB_FFFFFF |
transparent |
RGB_00000000 (note more than 6 digits gives alpha) |
Brown Brown1 Brown2 RosyBrown Maroon DkGoldenRod Red Red2 OrangeRed VioletRed BurlyWood Pink HotPink LtSalmon Sienna IndianRed LtPink Orange Orange1 DkOrange CadmiumYellow YellowGreen Gold |
RGB_004890 RGB_3333FF RGB_3333CC RGB_9999CC RGB_9933CC RGB_006699 RGB_0000FF (or simply RGB_FF) RGB_0000CC RGB_0033CC RGB_9933FF RGB_99CCFF RGB_CCCCFF RGB_CC66FF RGB_6699FF RGB_3366CC RGB_6666CC RGB_666699 RGB_0080FF RGB_0099FF RGB_0066CC RGB_0099FF RGB_33CC99 RGB_00CCFF |
DkPlum Plum Magenta Orchid |
RGB_996699 RGB_CC99CC RGB_CC00CC RGB_CC66CC |
Chartreuse Green DkSeaGreen SpringGreen SpringGreen1 PaleGreen DkGreen DkOliveGreen MintGreen LimeGreen Aquamarine |
RGB_00CC66 RGB_00FF00 RGB_99CC99 RGB_99FF00 RGB_66CC00 RGB_99FF99 RGB_006600 RGB_66FFCC RGB_CCFFCC RGB_33CC33 RGB_99CC66 |
Yellow LemonChiffon |
RGB_00FFFF RGB_99CCCC |
LtBlue Turquoise CadetBlue |
RGB_CCCC99 RGB_CCCC00 RGB_FFFF99 |
Blue MedBlue DkBlue SkyBlue DkSkyBlue DeepSkyBlue CornFlowerBlue SteelBlue RoyalBlue Peacock SlateBlue Purple Purple1 MedPurple DkOrchid |
RGB_FF0000 RGB_CC0000 RGB_990000 RGB_CC9966 RGB_996600 RGB_CC9900 RGB_FF9966 RGB_996633 RGB_CC6633 RGB_CC9933 RGB_CC6666 RGB_FF0080 RGB_FF3399 RGB_CC6699 RGB_CC3399 |
The following transformations are applied to an image in its progress from disk to screen:
|
Scale to initial size |
The source files used can be images of wildly varying sizes and using the final scaling algorithm to render a large image into a small cell creates a very poor image, so the image is scaled to size using an advanced algorithm, but only once on initial loading. |
|
Flip the image |
Reflect the image left-right and/or top-bottom if required. This is done in such a way that the reflected image is at the same location as the original image. |
|
Apply offset |
Translate (shift left-right and/or up-down) so that the desired point on the image is at the location specified for drawing on the screen. Not that the offset applies after flipping. |
|
Scale to size |
Scale the image to the number of rows and columns specified (possibly expanding one dimension for a FILL operation). |
|
Rotate about some centre. |
Rotate any amount about some specified centre of rotation. A centre of rotation of 0, 0 refers to the offset location so any non-zero rotation centre causes a rotation away from the offset location. |
|
Translate to desired cell |
Shift the image to the required place on the screen. The origin (offset position) of an image is placed at the top-left of the specified cell. Sprites are drawn with the image origin at the specified fractional position in the cell. |
In addition to the methods a CTC object has the following elements:
|
numRows |
The number of rows currently displayed. |
|
numCols |
The number of columns currently displayed. |
|
panRow |
The row currently panned to. |
|
panCol |
The column currently panned to. |
|
popIndex |
The index into the main popup menu that was last selected. Indexes start from 1. This value is set to zero when a popup menu is displayed. |
|
popSubIndex |
The index into a submenu that was last selected. Indexes start from 1. This is set to zero when a popup menu is displayed and if the selection is not from a submenu then it is left at zero. |
The popup () method will accept any number of parameters specifying menu contents, and each of which can hold any number of menu specifiers, comma separated.
A single menu specifier consists of up to three items:
|
Menu item name |
The string to be displayed in the menu. This can contain spaces, or any characters except comma, ampersand or vertical bar. Such a name normally makes a regular menu item (unless an ampersand follows). |
|
& name of database query |
If an ampersand is present the the text after it (to the end of the item, the next comma, or the next vertical bar) is taken to be the name of a database query object. Name makes a sub menu (instead of a regular menu item) and the database query contents populate the sub-menu. The first column of query should contain the strings to populate the sub-menu and a second column (if present) should contain a list of image filenames to use as icons. |
|
| icon filename |
If a vertical bar is present then the text after it (to the end of the item or comma) is taken to be the name of a file containing an image to be displayed alongside the menu item name. Such files can be any format supported by $Draw Image and might be used perhaps to show an item of rolling stock. |
Presently there is no means of creating sub-menus without using a database query, nor can a database query populate the main popup.
Last updated 22 Feb 2011
© Howard Amos 2008-2011