Scripting Command Documentation

Intro­duc­tion

Sports­code and Stu­diocode have a set of script­ing com­mands avail­able in code and sta­tis­ti­cal win­dows. The script­ing com­mands are based on a lan­guage spe­cif­ic to Sports­code and Stu­diocode. These com­mands work very much the same as the for­mu­las and func­tions found in Excel or Num­bers. Infor­ma­tion that is stored in a time­line, but­ton, or sta­tis­ti­cal win­dow can be called on in a script to gen­er­ate pow­er­ful results. The com­mands offer a wide vari­ety of fea­tures rang­ing from sim­ple instance and label count­ing to sophis­ti­cat­ed con­di­tion­al but­ton renam­ing and col­or changes. There are even com­mands that can push but­tons down or up to help auto­mate coding!

This doc­u­men­ta­tion pro­vides the def­i­n­i­tions of these com­mands and some basic exam­ples on how to use them.

Require­ments

This doc­u­men­ta­tion applies to:

  • Sports­code Elite and Pro ver­sions 9.0 and above
  • Stu­diocode ver­sions 5.0 and above

Get­ting Started

Like any lan­guage, learn­ing to script requires a bit of study and a lot of tri­al and error. It takes time to learn and get com­fort­able with the array of com­mands at your dis­pos­al, the syn­tax required to make them work prop­er­ly, and the data they return. If you have nev­er script­ed before, don’t wor­ry, it is real­ly easy to achieve some sim­ple, yet effec­tive results.

The most sim­ple com­mand and one you will use quite fre­quent­ly is the SHOW com­mand. SHOW does exact­ly what it’s name implies, it shows some­thing you tell it to show. Let’s go through this com­mand using a most famous exam­ple Hel­lo World!” and a few oth­er fun cal­cu­la­tor scripts.

We will do this work in a Code win­dow, so open up a new code win­dow by choos­ing File > New > Code win­dow from the main menu along the top of the screen. These scripts can be cre­at­ed in the Sta­tis­ti­cal win­dow also.

We rec­om­mend adding the Exe­cute but­ton to the Code win­dow tool­bar to make life eas­i­er when writ­ing your scripts. To do this, right click on the tool­bar and choose Cus­tomize Tool­bar… from the menu, then click and drag the Exe­cute but­ton into posi­tion on the tool­bar. Now let’s write some scripts.

  • Add a new but­ton to the code win­dow by click­ing and drag­ging from the but­ton icon in the toolbar.
  • Dou­ble click on the but­ton to open the Inspector.
  • Select the Appear­ance pan­el in the Inspector.
  • Tick the Show out­put option. A ques­tion mark will like­ly appear in the but­ton below its name. This where the script out­put will appear when the script is exe­cut­ed. You might, also, want to resize the but­ton now to make your out­put appear in the bounds of the button.
  • Select the Script Edi­tor pan­el in the Inspector.
  • In the Script pan­el, type show Hel­lo World!”
  • Hit the Exe­cute but­ton in the toolbar!

If you fol­lowed the steps cor­rect­ly, you will see Hel­lo World! in the but­ton. Pret­ty sim­ple, huh? Note that com­mands are not case sen­si­tive, you can use SHOW or show. It is all a mat­ter of style and what you think is more readable.

An impor­tant aspect to under­stand in the script above is that the text Hel­lo World!” fol­low­ing the com­mand is what is known as a string. A string is a type of data that con­tains a sequence of alphanu­mer­ic char­ac­ters. Don’t for­get to include the quotes around strings, oth­er­wise you will get an error.

Anoth­er type of data is a num­ber, there are var­i­ous types of num­bers, but for pur­pos­es of this doc­u­men­ta­tion, we will stick with just call­ing them num­bers. Num­bers can be used in var­i­ous oper­a­tions such as addi­tion, sub­trac­tion, mul­ti­pli­ca­tion and divi­sion. Let’s see how num­bers work with the show com­mand using the same but­ton as in the exam­ple above.

  • Remove all the text in the Script Edi­tor in the Inspector.
  • Type show 22
  • Hit the Exe­cute but­ton in the toolbar!

Again if you fol­lowed the steps cor­rect­ly, you should see 4 in the but­ton. Look at that, a sim­ple cal­cu­la­tor! More oper­a­tors can be includ­ed in the com­mand, so you could have show 10 — 8 * 2 / 2, but make sure to only use num­bers. If you mix types incor­rect­ly you will get an error.

Now, let’s get a lit­tle fanci­er and put togeth­er a sen­tence using both strings and num­bers to pro­vide some nice mean­ing­ful out­put. We will do this using what is known as con­ca­ten­ta­tion. Again, using the same but­ton as above.

  • Clear the Script Editor
  • Type show Cal­cu­lat­ed results = ” + (10 — 8 * 22)
  • Hit the Exe­cute but­ton in the toolbar!

The but­ton will show Cal­cu­lat­ed results = 2 string. Let’s exam­ine this script as it intro­duces a cou­ple of new things.

The first one is the plus sym­bol fol­low­ing the Cal­cu­lat­ed results = “. The plus sym­bol is how we con­ca­ten­tate strings togeth­er. A sim­ple exam­ple of this is show I am ” + enjoy­ing learn­ing ” + script­ing.”. You will find this to be very valu­able when you want to insert vari­ables into the mid­dle of a sentence.

The sec­ond is the use of paren­the­ses around the math­emet­i­cal expres­sion (10 — 8 * 2 / 2), the paren­the­ses encap­su­late the expres­sion, so it is cal­cu­lat­ed, returned as a string, then con­cate­nat­ed. If these were not there, the script would fail to work.

Now that you have good idea on how the show com­mand works, take a look at all the oth­er com­mands and dive into scripting!