I’m by no means an expert, but perhaps this will help.
The basic form of a function definition is:
- the word
function
- the name of the function followed by parentheses (which may or may not be empty)
- a series of actions, separated by
;
, all enclosed in brackets
- optionally you can have the keyword
return
, which is the way the function passes information back to you – so you can use it in an $Attribute, for example.
-
var
simply means that you’re going to use the identified variable within the brackets – it’s temporary information which can’t be used outside the function.
So, some examples. The simplest type of function just acts on the selected notes – it doesn’t expect you to give it any more information and it won’t return
any to you.
e.g., the following just sets the selected note’s $Color to blue:
function makeNoteBlue() {
$Color = blue;
}
Notice that the brackets are empty and there’s no return
statement, because you don’t need to give the function any information and you don’t want any back in return.
You could call this function in a Stamp with the code makeNoteBlue()
: apply the stamp and the selected note will turn blue immediately.
This isn’t very useful so far, because it’s hardwired to blue. So let’s extend it so we can choose the colour when we call the stamp.
function makeNoteColour(aColour) {
$Color = aColour;
}
This can be read as colour the selected note with the colour “aColour”, which is a placeholder for the real colour I’ll tell you when I call the function.
You could call this with the stamp makeNoteColour("Red")
or makeNoteColour("Blue")
or whatever. i.e. you don’t have to change the function definition to get different colours, you just have to change the placeholder (technically known as the function’s parameters) when you use it.
(NB: it’s your job to ensure that the info you pass to the function (e.g. “Red”) is the correct type – in this case it needs a String, and you must pass it the right number of parameters. If you pass it a number, or if you only it pass it one parameter instead of two, the results may not be what’s expected…)
If you want the function to give you back information, then you’d use the return
statement. E.g. this function gives you the map coordinates of the current note in a string.
function getCoordinates() {
var coordinates = "";
coordinates = "(" + $Xpos + ", " + $Ypos + ")";
return coordinates;
}
Note, this function uses the temporary variable coordinates
to build the string which will be passed back in the return
statement.
You could then use this function to populate an attribute. For example:
$Subtitle = getCoordinates()
If you put this in the note’s $Rule, the subtitle will update to show the note’s position on the map as you move it.
If you wanted to move the note on the map, you could use the following function, which is in some way the ‘inverse’ of the last one:
function setCoordinatesTo(x, y) {
$Xpos = x;
$Ypos = y;
}
Call this with the stamp setCoordinatesTo(0, 0)
and this will move the selected note to the position 0, 0
on the current map (and the $Rule we created previously will display the new coordinates as a subtitle…).
Finally, you’ll notice that however we call a function (via Stamp or in a Rule etc) you need to include the parentheses, even if they’re empty. E.g. getCoordinates()
, not getCoordinates
.
This test project contains these functions, so you can experiment with it. Have a look at these to see how it’s put together.
-
Hints/Library
container for the functions
-
A Note’s
$Rule
- The Stamps inspector
Test functions.tbx (115.2 KB)
I’d start by changing the values of the parameters in the Stamps, then perhaps write a function which returns the $Color of the selected note, with a $Rule which uses the function to populate the attribute $MyString.
Slightly more advanced (but only using the above techniques), write a function which nudges the note one unit at a time, with the direction to be specified when you call the function. (e.g. moveNoteOneUnit(left)
).
As I said, I’m not an expert so none of this is particularly advanced – you can do a lot more! But I hope it helps get a sense of how functions work.