AN1007 – Creating Functions in SHIP
Functions in SHIP
Functions are a staple concept of writing compact stable code. They allow repetitive use of a set of steps sometimes with different inputs to obtain different outputs. In SHIPTide, this will result in smaller scripts thus reducing the size of your cargo files. A SHIPTide function is actually a SHIPTide script, but is located in the resource area outside of the project layout node tree.
A SHIPTide function can be created either under the script category, or under the Misc. category of the Project Resources area. SHIPTide functions utilize variables as inputs and outputs to the function instead of passing in arguments and returning results. Function variables can either reside under the Variable or the Misc. categories within the Project Resources area.
Function Variables for Arguments and Returns
Create a variable in the Project Resource area under the Variable group as the input argument for the function. In this example, a byte type variable is created under the Variable group named “vSelection”.
Create a variable in the Project Resource area under the Variable group as the output result for the function. In this example, a string type variable is created under the Variable group named “vTextToDisplay”.
Function Body
Create a script in the Project Resource area under the Script group named “FindName”. This script will represent the function used for this example.
For the newly created function script from the previous step, the following SHIPTSail code is added. This can be entered by double clicking on the function script name “FindName” and typing in the SHIPSail code as shown below.
/***
* Function example using SHIPSail scripting language.
*
* This function returns a text string to the output
* variable based on the selection type input variable.
*
* Input variable: vSelection
* Output variable: cTextToDisplay
*/
switch (vSelection) {
case 0:
vTextToDisplay = "Good afternoon";
break;
case 1:
vTextToDisplay = "Hello";
break;
default:
vTextToDisplay = "Welcome";
break;
} 
For this example, the function FindName takes in the value of the input variable “vSelection” and determines the output text to assign to the output variable “vTextToDisplay” based on a simple case statement.
Calling the Function
For this example, in order to call the function script created in the previous step, SHIPSail code needs to be added to the calling script. In this example, the script used for this is under the pageState listener as shown highlighted below.
In this script, the SHIPSail code calling the FindName function has been added below the stateful page as shown below by the example code.
/**
* The SHIPSail code below added to this script, sets up the input variable
* vSelection, calls the function script FindName(), and uses the output variable
* vTextToDisplay to assign the value to the text variable
* d0.pSplash.TextFrame.t.value.
*/
// Setup the input variable vSelection
vSelection = 1;
// Call the function script
FindName();
// Assign the output value to d0.pSplash.TextFrame.t
d0.pSplash.TextFrame.t.value = vTextToDisplay; 
Grouping Resources
For clarity and convenience, one other thing that could be done is to group the function script and variables together. As shown below, both the input and output variables, vSelection and vTextToDisplay, along with the function script FindName have moved under the newly created group titled “Strings” in the Project Resources area under the Misc. group. This was not implemented in this example.
Summary
This example of a SHIPTide function uses a default SIM basic SHIPTide project. The script d0.pSplash.pageState.pageUpdate script calls a SHIPTIde function from the Project Resources area to determine the text to display in the child text frame within the pSplash page using a numbered selection as an input. Note also for this example, the textframe and text under the pSplash page were renamed to help in this example.
First the value of the variable vSelection is set to 3. Then, the FindName function is called. The FindName returns the assigned string value of “Hello” to the output variable vTextToDisplay (see the switch sttement example in section Function Switch Statement). The value of the variable vTextToDisplay is then assigned to the text value d0.pSplash.TextFrame.t.value, replacing the original text of “Welcome” with “Hello”.
Therefore, during run time operation of the GUI, each successive call of the ChangeName function, based on the value assigned as the input variable vSelection, will yield a different string value assigned to the output variable vTestToDisplay. Although this example is simplistic in nature, it demonstrates how the function script FindName could be called from several different scripts to obtain a desired string value to display on the GUI.
Resource grouping was not implemented but should be in larger projects for clarity and convenience.
