In computer programming variables contain data that can be accessed and changed. In fact, every piece of information used by your program is stored in a variable. In Python all variables contain objects, so every Python variable has a number of properties and/or member functions. So when do you need variables? In essence, every time you need to store some information you need to create a variable. For example, if you ask nControl whether a traffic light is red or green, you store the result in a variable so you can use it later in your program.

Imagine that you have a layout with two track switches that you want to link: if you change one of the switches the other one follows automatically. We have seen that with the self keyword¹ you can access the tile you're working in. But how do you access another tile? You create a variable that contains the object representing the tile you want to manipulate. You can easily do this with the .getTile() function. The project below has a small layout with 2 track switches: Switch-1 and Switch-2. Start by downloading the project using the link below and opening it in nControl.


When you open this project you should see a train layout with two track switch tiles:

Open the Edit Track Switch Properties dialog box of Switch 1 by doubling clicking on the tile. Next, check the Use a custom action check box and click the Code button to open the Code Editor.
As the custom script completely redefines the behavior of the track switch, the first thing we have to do it making sure the switch flips when we click the tile. This can be done by calling the .flipSwitch() function of the tile.

self.flipSwitch()

Now we have to make sure Switch 2 changes as well. The first step is to create a variable so we can access Switch 2. This can be done with the following line of code:

switch2 = self.getTile('Switch 2')

Let's analyze this line of code in detail. We're working in Switch 1 so we can use the self keyword¹ to access the object of that tile.

self

Every tile in nControl has a .getTile() function that creates a variable to access the requested tile. The requested tile is specified by it's label and has to be passed to the .getTile() function as an argument. As the argument is a string (text) we have to put the label of the requested tile between quotes. So our line of code becomes:

self.getTile('Switch 2')

This function will return the object of Switch 2. But if we want to do something with that object we need to store it in a variable. We'll give that variable the name switch2 and we will use it to store the value returned by the .getTile() function. Which gives use the following line of code:

switch2 = self.getTile('Switch 2')

So now, switch2 is a variable that contains the object of the Switch 2 tile. That object has all the functions each track switch tile has, so it also has a .flipSwitch() functions. That means that we can flip Switch 2 simply by calling the .flipSwitch() function of the object stored in the variable we just created or:

switch2.flipSwitch()

So our full Python program to link switch 2 with switch 1 becomes:

self.flipSwitch()
switch2 = self.getTile('Switch 2')
switch2.flipSwitch()

You can now close the code editor and return to the main application.

You can now test your program. Start by saving it and then switch to simulation mode. When you click the Switch 1 tile you'll see that both switches change. When you click the Switch 2 tile, the first switch doesn't follow. That's because we only programmed Switch 1 to flip Switch 2 as well, we haven't reprogrammed Switch 2 yet.

Switch 1 can be linked to Switch 2 in an identical way. Go to configuration mode and open the code editor of Switch 2. Our script starts with changing the state of switch 2. This can be done in the same way as for switch 1:

self.flipSwitch()

Next, it needs to change the state of switch 1. To achieve that we first need a variable that gives us access to switch 1.

switch1 = self.getTile('Switch 1')

With this variable we can change the position of switch 1.

switch1.flipSwitch()

So the full Python program to link switch 1 with switch 2 becomes:

self.flipSwitch()
switch1 = self.getTile('Switch 1')
switch1.flipSwitch()

After writing your code, you can close the code editor, return to the main application and go to Simulation Mode to test the program. The switches are now linked correctly.

So far we have called self a keyword but that's actually not the case... In programming languages keywords are reserved words that have a special meaning and cannot be used to define variables, functions, etc. In Python self is not a reserved keyword. However, it's a virtually universal convention that self is used as the name of the variable that points to the object you're working in. nControl is programmed based on that convention, so to be correct: self is a predefined variable not a keyword. Although self is, technically spoken, not a keyword you should treat it like one. Because if you would ever overwrite self, you will no longer have access to the member functions of the object (tile) you're working in!

---

¹Technically speaking self is not a reserved keyword in Python; it's a convention. You can use any name to point to the instance of the class, however, it's strongly advised to use self for that and not for anything else. nControl has been implemented using self, so in nControl you have to use self to point to the object you're working in.