Scripts: Difference between revisions

Latest revision as of 04:50, 3 March 2019

Scripts were developed for early multimedia SuperMemo courses in the 1990s. They are retained for compatibility only. The tools of incremental learning, videos, HTML, etc. may be used instead at much lower implementation cost.

Writing scripts to add life to SuperMemo elements

The script component makes it possible to use a simple script language to manipulate other components in a given element (i.e. to display components, change their position, animate them, use them in learning tests, etc.). This way you can create interactive presentations, animation, video subtitling, drag-and-drop tests, hyperlinks to the Internet, e-mail links, etc.

To create a script do the following:

create an element with contents of your choice (components, their position, their attributes, etc.)
add a script component from the Compose toolbar (i.e. click the component button)
right-click the script component and choose the Script option on the component menu
write the script program (see below) and choose OK

While writing the script, use the script editor's context menu that makes it possible to insert full command syntax into the editor (right-click the editor to open the menu).

For example, to repeatedly play music from a sound component number 3 (see below), you could write:


PLAY 3
GOTO 1

To view component number tags click 123 speed-button on the Compose toolbar, or choose Components : Component order (Shift+Ctrl+O) on the element menu. Note, that when you right-click within the element window, you will either open a component menu (if you click over a component) or the element menu (when you click an empty area within the element).

The best way to learn more about scripts is to download a free collection Advanced Tests with SuperMemo which you can inspect for some simple examples. Use Search : Other registries : Script to inspect scripts..

Important: apostrophe is reserved in scripts for delimiting string variables. If you need to include an apostrophe in a string, use a backquote instead. For example:


TEXTOUT 3 'I`m delighted to have met you'

Script commands used in SuperMemo

Execute

Execute
- To display another element of the collection use Element (Ctrl+E) with the number of the element as the argument.
  Syntax: ELEMENT <Number>
- To change the flow of script execution use Goto (Ctrl+G) with script label or script line as an argument.
  Syntax: GOTO <Label>|<Line>
- To jump to a particular label in the script you need to define the label with Label.
  Syntax: LABEL <Name>
- To display a message or warning use Message.
  Syntax: MESSAGE <Text>

Internet

Internet
- To make the users send an e-mail use MailTo.
  Syntax: MAILTO <Address> <Subject> <Body text> <Name>
- To make SuperMemo display a selected page from the world wide web, use URL.
  Syntax: URL http://<web address>

Learn

Learn
- To dismiss the currently displayed element use Dismiss.
  Syntax: DISMISS
- To simulate the learning procedure (as if the user pressed the button Learn) use Learn (Ctrl+L).
  Syntax: LEARN

Playing

Playing
- To execute a frame of an animation sequence, use Frame. The <Component> argument specifies the image component within which the animation is executed (alternatively, BACKGROUND can be used to execute animation in element entire background). <Image Registry member> indicate the image that makes up the executed frame.
  Syntax: FRAME <Component>|BACKGROUND <Image registry member>
- To play a sound, video, script or execute a binary object, use Play (Ctrl+P).
  Syntax: PLAY <Component> <Registry member>
- To play a sound or video without suspending the execution of the script use Start (Ctrl+T).
  Syntax: START <Component>
- To stop the script use Stop.
  Syntax: STOP
- To play user recorded sound in the sound component use UPlay (to display the recorder panel in sound components check Sound : Panel : Recorder on sound component menu).
  Syntax: UPLAY <Component>
- To suspend the execution of a script for a number of milliseconds use Wait (Ctrl+W).
  Syntax: WAIT <Milliseconds>
- To suspend the execution of a script until a given frame is displayed in a video sequence, or until a given position is reached in a sound track, use WaitFrame with the frame or position as an argument.
  Syntax: WAITFRAME <Component> <Frame>

Showing

Showing
- To display a given registry image in an image component use Display (Ctrl+D). Its first argument is the number of the image component in the element. Its second argument is the name of the image registry member.
  Syntax: DISPLAY <Component> <Image registry member>
- To change a font in a text, sound or spell-pad component, use Font (Ctrl+F).
  Syntax: FONT <Component> <Font registry member>
- To hide a component use Hide (Ctrl+H).
  Syntax: HIDE <Component>
- To move a component to a new location use Move.
  Syntax: MOVE <Component> <X> <Y>
- To show a hidden component, use Show (Ctrl+S).
  Syntax: SHOW <Component>
- To display a particular text in a text component use TextOut (Ctrl+X).
  Syntax: TEXTOUT <Component> '<Text>'
- To change the display status of a component (from hide to show, or from show to hide), use Toggle.
  Syntax: TOGGLE <Component>
- To translate a text component to the currently selected translation language choose Translate (see Toolkit : Options : Language for interface and collection translation options).
  Syntax: TRANSLATE <Component>

SuperMemo

SuperMemo
- To switch SuperMemo to a selected difficulty level use Level.
  Syntax: LEVEL BEGINNER|BASIC|MIDDLE|PROFESSIONAL
- To show or hide the status bar use Status.
  Syntax: STATUS ON|OFF
- To open the Question of the Day dialog box use Tips.
  Syntax: TIPS

Tests

Tests
- To start a Drag&Match exercise for multiple labels and multiple images use DragMatch (multiple).
  Syntax: DRAGMATCH [<Label List>] [<Image list>]
  For example: DRAGMATCH [1,3,4,5] [6,7,8,9]
- To start a Drag&Match exercise single image component with specified hit areas and multiple labels use DragMatch (single).
  Syntax: DRAGMATCH DRAGMATCH <Component> [<Label List>] [<Rectangle List>]
  For example: DRAGMATCH 1 [1,2] [(100,100,30,20),(150,200,50,20)]
  Hints: Use Image : Edit hit-area on the image pop-up menu to determine the positions of rectangles without complex coordinate calculations. Remember about the space between square brackets. See example
- To determine if labels erase background of the image on which they are dropped in Drag&Match exercises, use DragTextMode.
  Syntax: DRAGTEXTMODE OPAQUE|TRANSPARENT
- To design Point&Click exercises use HitTest. Use an image that displays the hit area as the first argument, and a list of points that specify the correct hit area.
  Syntax: HITTEST <Component> [<list of points: (x1,y1)(x2,y2), etc.>]
  For example: HITTEST 1 [(10,10),(100,10),(100,100),(10,100)]
  Use Image : Edit hit-area on the image pop-up menu to determine the position of the hit area without worrying about coordinates. The hit area may include no more than five points. See example
- To suspend the execution of a script until a grade is provided (e.g. in Drag&Match exercises or Point&Click exercises) use WaitGrade.
  Syntax: WAITGRADE

Comment

To insert a comment into the script, put it in a separate line and precede it with a semicolon.
Syntax: ;<Comment>

@@ Line 1: / Line 1: @@
 __TOC__
+<div class="bs-callout bs-callout-warning">
+Scripts were developed for early multimedia SuperMemo courses in the 1990s. They are retained for compatibility only. The tools of incremental learning, videos, HTML, etc. may be used instead at much lower implementation cost.
+</div>
 == Writing scripts to add life to SuperMemo elements ==
-The script component makes it possible to use a simple script language to manipulate other [[Glossary#component | components]] in a given element (i.e. to display components, change their position, animate them, use them in learning tests, etc.). This way you can create interactive presentations, animation, video subtitling, drag-and-drop tests, hyperlinks to the Internet, e-mail links, etc.
+The script [[Glossary:Component|component]] makes it possible to use a simple script language to manipulate other components in a given [[Glossary:Element|element]] (i.e. to display components, change their position, animate them, use them in learning tests, etc.). This way you can create interactive presentations, animation, video subtitling, drag-and-drop tests, hyperlinks to the Internet, e-mail links, etc.
 To create a script do the following:
-# create an [[Glossary#element | element]] with contents of your choice (components, their position, their attributes, etc.)
+# create an [[Glossary:Element|element]] with contents of your choice ([[Glossary:Component|components]], their position, their attributes, etc.)
-# add a script component from the [[Compose toolbar | '''Compose''' toolbar]] (i.e. click the component button and two locations in the element area)
+# add a script [[Glossary:Component|component]] from the [[Compose toolbar|'''Compose''' toolbar]] (i.e. click the component button)
-# right-click the script component and choose the '''Script''' option on the [[component menu]]
+# right-click the script [[Glossary:Component|component]] and choose the '''[[Component menu#Script|Script]]''' option on the [[component menu]]
 # write the script program (see below) and choose '''OK'''
 While writing the script, use the script editor's context menu that makes it possible to insert full command syntax into the editor (right-click the editor to open the menu).
-For example, to repeatedly play music from a sound component number 3 (see below), you could write:
+For example, to repeatedly play music from a sound [[Glossary:Component|component]] number 3 (see below), you could write:
 <pre>
@@ Line 23: / Line 27: @@
 </pre>
-To view component number tags click '''123''' speed-button on the [[Compose toolbar | Compose]] toolbar, or choose '''Components : Component order''' (''Shift+Ctrl+O'') on the [[element menu]]. Note, that when you right-click within the [[Glossary#element window | element window]], you will either open a [[component menu]] (if you click over a component) or the element menu (when you click an empty area within the element).
+To view component number tags click '''123''' speed-button on the [[Compose toolbar|'''Compose''' toolbar]], or choose '''[[Element menu#Components|Components]] : Component order''' (''Shift+Ctrl+O'') on the [[element menu]]. Note, that when you right-click within the [[element window]], you will either open a [[component menu]] (if you click over a [[Glossary:Component|component]]) or the [[element menu]] (when you click an empty area within the [[Glossary:Element|element]]).
-The best way to learn more about scripts is to inspect scripts in multimedia [[Glossary#collection | collections]] shipped with SuperMemo, e.g. Cross Country, Video English, Easy English, etc. Use '''[[Search menu | Search]] : Other registries : Script''' to inspect scripts. Alternatively you can download a free collection [http://sm.supermemo.org/sml/colls/advtest.htm ''Advanced Tests with SuperMemo''] from SuperMemo Library for some simple examples.
+The best way to learn more about scripts is to download a free [[Glossary:Collection|collection]] [http://sm.supermemo.org/sml/colls/advtest.htm ''Advanced Tests with SuperMemo''] which you can inspect for some simple examples. Use '''[[Search menu| Search]] : [[Search menu#Other registries|Other registries]] : Script''' to inspect scripts..
-'''Important''': apostrophe is reserved in scripts for delimiting string variables. If you need to include an apostrophe in a string, use a backquote instead. For example:
+Important: apostrophe is reserved in scripts for delimiting string variables. If you need to include an apostrophe in a string, use a backquote instead. For example:
 <pre>
@@ Line 36: / Line 40: @@
 == Script commands used in SuperMemo ==
+=== Execute ===
 * '''Execute'''
-** To display another element of the collection use '''Element''' (''Ctrl+E'') with the number of the element as the argument.<br />'''Syntax: <span style="color: red;"><span id="ELEMENT">ELEMENT</span> <Number></span>'''
+** To display another [[Glossary:Element|element]] of the [[Glossary:Collection|collection]] use '''Element''' (''Ctrl+E'') with the number of the element as the argument.<br />'''Syntax: <span style="color: red;"><span id="ELEMENT">ELEMENT</span> <Number></span>'''
 ** To change the flow of script execution use '''Goto''' (''Ctrl+G'') with script label or script line as an argument.<br />'''Syntax: <span style="color: red;"><span id="GOTO">GOTO</span> <Label>|<Line></span>'''
 ** To jump to a particular label in the script you need to define the label with '''Label'''.<br />'''Syntax: <span style="color: red;"><span id="LABEL">LABEL</span> <Name></span>'''
 ** To display a message or warning use '''Message'''.<br />'''Syntax: <span style="color: red;">MESSAGE <Text></span>'''
+=== Internet ===
 * '''Internet'''
 ** To make the users send an e-mail use '''MailTo'''.<br />'''Syntax: <span style="color: red;">MAILTO <Address> <Subject> <Body text> <Name></span>'''
 ** To make SuperMemo display a selected page from the world wide web, use '''URL'''.<br />'''Syntax: <span style="color: red;">URL <nowiki>http://</nowiki><web address></span>'''
+=== Learn ===
 * '''Learn'''
-** To dismiss the currently displayed element use '''Dismiss'''.<br />'''Syntax: <span style="color: red;">DISMISS</span>'''
+** To [[Glossary:Dismiss|dismiss]] the currently displayed [[Glossary:Element|element]] use '''Dismiss'''.<br />'''Syntax: <span style="color: red;">DISMISS</span>'''
 ** To simulate the learning procedure (as if the user pressed the button '''Learn''') use '''Learn''' (''Ctrl+L'').<br />'''Syntax: <span style="color: red;">LEARN</span>'''
+=== Playing ===
 * '''Playing'''
-** To execute a frame of an animation sequence, use '''Frame'''. The <Component> argument specifies the image component within which the animation is executed (alternatively, BACKGROUND can be used to execute animation in element entire background). <Image Registry member> indicate the image that makes up the executed frame.<br />'''Syntax: <span style="color: red;"><span id="FRAME">FRAME</span> <Component>|BACKGROUND <Image Registry member></span>'''
+** To execute a frame of an animation sequence, use '''Frame'''. The <code><Component></code> argument specifies the image [[Glossary:Component|component]] within which the animation is executed (alternatively, BACKGROUND can be used to execute animation in element entire background). <code><Image Registry member></code> indicate the image that makes up the executed frame.<br />'''Syntax: <span style="color: red;"><span id="FRAME">FRAME</span> <Component>|BACKGROUND <Image registry member></span>'''
 ** To play a sound, video, script or execute a binary object, use '''Play''' (''Ctrl+P'').<br />'''Syntax: <span style="color: red;"><span id="PLAY">PLAY</span> <Component> <Registry member></span>'''
 ** To play a sound or video without suspending the execution of the script use '''Start''' (''Ctrl+T'').<br />'''Syntax: <span style="color: red;"><span id="START">START</span> <Component></span>'''
@@ Line 56: / Line 71: @@
 ** To suspend the execution of a script for a number of milliseconds use '''Wait''' (''Ctrl+W'').<br />'''Syntax: <span style="color: red;"><span id="WAIT">WAIT</span> <Milliseconds></span>'''
 ** To suspend the execution of a script until a given frame is displayed in a video sequence, or until a given position is reached in a sound track, use '''WaitFrame''' with the frame or position as an argument.<br />'''Syntax: <span style="color: red;"><span id="WAITFRAME">WAITFRAME</span> <Component> <Frame></span>'''
+=== Showing ===
 * '''Showing'''
-**  To display a given [[Glossary#registry | registry]] image in an image component use '''Display''' (''Ctrl+D''). Its first argument is the number of the image component in the element. Its second argument is the name of the image [[Glossary#registry member | registry member]].<br />'''Syntax: <span style="color: red;"><span id="DISPLAY">DISPLAY</span> <Component> <Image registry member></span>'''
+**  To display a given registry image in an image [[Glossary:Component|component]] use '''Display''' (''Ctrl+D''). Its first argument is the number of the image component in the [[Glossary:Element|element]]. Its second argument is the name of the image [[Glossary:Registry member|registry member]].<br />'''Syntax: <span style="color: red;"><span id="DISPLAY">DISPLAY</span> <Component> <Image registry member></span>'''
-** To change a font in a text, sound or Spell-Pad component, use '''Font''' (''Ctrl+F'').<br />'''Syntax: <span style="color: red;"><span id="FONT">FONT</span> <Component> &lt;Font registry member&gt;</span>'''
+** To change a font in a text, sound or spell-pad [[Glossary:Component|component]], use '''Font''' (''Ctrl+F'').<br />'''Syntax: <span style="color: red;"><span id="FONT">FONT</span> <Component> &lt;Font registry member&gt;</span>'''
-** To hide a component use '''Hide''' (''Ctrl+H'').<br />'''Syntax: <span style="color: red;"><span id="HIDE">HIDE</span> <Component></span>'''
+** To hide a [[Glossary:Component|component]] use '''Hide''' (''Ctrl+H'').<br />'''Syntax: <span style="color: red;"><span id="HIDE">HIDE</span> <Component></span>'''
-** To move a component to a new location use '''Move'''.<br />'''Syntax: <span style="color: red;"><span id="MOVE">MOVE</span> <Component> <X> <Y></span>'''
+** To move a [[Glossary:Component|component]] to a new location use '''Move'''.<br />'''Syntax: <span style="color: red;"><span id="MOVE">MOVE</span> <Component> <X> <Y></span>'''
-** To show a hidden component, use '''Show''' (''Ctrl+S'').<br />'''Syntax: <span style="color: red;"><span id="SHOW">SHOW</span> <Component></span>'''
+** To show a hidden [[Glossary:Component|component]], use '''Show''' (''Ctrl+S'').<br />'''Syntax: <span style="color: red;"><span id="SHOW">SHOW</span> <Component></span>'''
-** To display a particular text in a text component use '''TextOut''' (''Ctrl+X'').<br />'''Syntax: <span style="color: red;"><span id="TEXTOUT">TEXTOUT</span> <Component> '<Text>'</span>'''
+** To display a particular text in a text [[Glossary:Component|component]] use '''TextOut''' (''Ctrl+X'').<br />'''Syntax: <span style="color: red;"><span id="TEXTOUT">TEXTOUT</span> <Component> '<Text>'</span>'''
-** To change the display status of a component (from hide to show, or from show to hide), use '''Toggle'''.<br />'''Syntax: <span style="color: red;"><span id="TOGGLE">TOGGLE</span> <Component></span>'''
+** To change the display status of a [[Glossary:Component|component]] (from hide to show, or from show to hide), use '''Toggle'''.<br />'''Syntax: <span style="color: red;"><span id="TOGGLE">TOGGLE</span> <Component></span>'''
-** To translate a text component to the currently selected translation language choose '''Translate''' (see '''[[Tools menu | Tools]] : [[Options]] : [[Language tab in Options | Language]]''' for interface and collection translation options).<br />'''Syntax: <span style="color: red;"><span id="TRANSLAT">TRANSLATE</span> <Component></span>'''
+** To translate a text [[Glossary:Component|component]] to the currently selected translation language choose '''Translate''' (see '''[[Toolkit menu|Toolkit]] : [[Options]] : [[Language tab in Options|Language]]''' for interface and collection translation options).<br />'''Syntax: <span style="color: red;"><span id="TRANSLAT">TRANSLATE</span> <Component></span>'''
+=== SuperMemo ===
 * '''SuperMemo'''
-** To switch SuperMemo to a selected difficulty level use '''Level'''.<br />'''Syntax: <span style="color: red;">LEVEL BEGINNER|BASIC|MIDDLE|PROFESSIONAL</span>'''
+** To switch SuperMemo to a selected difficulty [[Glossary:Level|level]] use '''Level'''.<br />'''Syntax: <span style="color: red;">LEVEL BEGINNER|BASIC|MIDDLE|PROFESSIONAL</span>'''
-** To set SuperMemo in one of its access modes (Read-Only, Learn-Only or Full Access), use '''Mode'''.<br />'''Syntax: <span style="color: red;">MODE READ|LEARN|FULL</span>'''
+** To show or hide the [[status bar]] use '''Status'''.<br />'''Syntax: <span style="color: red;">STATUS ON|OFF</span>'''
-**  To show or hide the [[Element toolbar | element navigation toolbar]] of the element window, use '''Navigation'''.<br />'''Syntax: <span style="color: red;">NAVIGATION ON|OFF</span>'''
-** To show or hide the status bar use '''Status'''.<br />'''Syntax: <span style="color: red;">STATUS ON|OFF</span>'''
 ** To open the '''[[Question of the Day]]''' dialog box use '''Tips'''.<br />'''Syntax: <span style="color: red;">TIPS</span>'''
+=== Tests ===
 * '''Tests'''
-**  To start a [[Testing elements | Drag&Match exercise]] for multiple labels and multiple images use '''DragMatch (multiple)'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGMATCH">DRAGMATCH</span> [<Label List>] [<Image list>]</span>'''<br /> For example: ''DRAGMATCH [1,3,4,5] [6,7,8,9]''
+**  To start a [[Test elements#Multiple_Drag.26Match_test|Drag&Match exercise]] for multiple labels and multiple images use '''DragMatch (multiple)'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGMATCH">DRAGMATCH</span> [<Label List>] [<Image list>]</span>'''<br /> For example: ''DRAGMATCH [1,3,4,5] [6,7,8,9]''
-**  To start a [[Testing elements | Drag&Match exercise]] single image component with specified hit areas and multiple labels use '''DragMatch (single)'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGMATCH">DRAGMATCH</span> DRAGMATCH <Component> [<Label List>] [<Rectangle List>]</span>'''<br /> For example: ''DRAGMATCH 1 [1,2] [(100,100,30,20),(150,200,50,20)]''<br /> Hints: Use '''Image : Edit hit-area''' on the image pop-up menu to determine the positions of rectangles without complex coordinate calculations. Remember about the space between square brackets. See [http://sm.supermemo.org/sml/colls/advtest.htm example]
+**  To start a [[Test elements#Single_Drag.26Match_test|Drag&Match exercise]] single image [[Glossary:Component|component]] with specified hit areas and multiple labels use '''DragMatch (single)'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGMATCH">DRAGMATCH</span> DRAGMATCH <Component> [<Label List>] [<Rectangle List>]</span>'''<br /> For example: ''DRAGMATCH 1 [1,2] [(100,100,30,20),(150,200,50,20)]''<br /> Hints: Use '''[[Component menu#Image|Image]] : Edit hit-area''' on the [[Component menu|image pop-up menu]] to determine the positions of rectangles without complex coordinate calculations. Remember about the space between square brackets. See [http://sm.supermemo.org/sml/colls/advtest.htm example]
-** To determine if labels erase background of the image on which they are dropped in Drag&Match exercises, use '''DragTextMode'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGTEXTMODE">DRAGTEXTMODE</span> OPAQUE|TRANSPARENT</span>'''
+** To determine if labels erase background of the image on which they are dropped in [[Test elements#Drag.26Match_tests|Drag&Match exercises]], use '''DragTextMode'''.<br />'''Syntax: <span style="color: red;"><span id="DRAGTEXTMODE">DRAGTEXTMODE</span> OPAQUE|TRANSPARENT</span>'''
-**  To design [[Testing elements | Point&Click exercises]] use '''HitTest'''. Use an image that displays the hit area as the first argument, and a list of points that specify the correct hit area.<br />'''Syntax: <span style="color: red;"><span id="HITTEST">HITTEST</span> <Component> [<list of points: (x1,y1)(x2,y2), etc.>]</span>'''<br /> For example: ''HITTEST 1 [(10,10),(100,10),(100,100),(10,100)]''<br /> Use '''Image : Edit hit-area''' on the image pop-up menu to determine the position of the hit area without worrying about coordinates. The hit area may include no more than five points. See [http://sm.supermemo.org/sml/colls/advtest.htm example]
+**  To design [[Test elements#Point.26Click_test|Point&Click exercises]] use '''HitTest'''. Use an image that displays the hit area as the first argument, and a list of points that specify the correct hit area.<br />'''Syntax: <span style="color: red;"><span id="HITTEST">HITTEST</span> <Component> [<list of points: (x1,y1)(x2,y2), etc.>]</span>'''<br /> For example: ''HITTEST 1 [(10,10),(100,10),(100,100),(10,100)]''<br /> Use '''[[Component menu#Image|Image]] : Edit hit-area''' on the [[Component menu|image pop-up menu]] to determine the position of the hit area without worrying about coordinates. The hit area may include no more than five points. See [http://sm.supermemo.org/sml/colls/advtest.htm example]
-**  To suspend the execution of a script until a grade is provided (e.g. in [[Testing elements | Drag&Match exercises or Point&Click exercises]]) use '''WaitGrade'''.<br />'''Syntax: <span style="color: red;"><span id="WAITGRADE">WAITGRADE</span></span>'''
+**  To suspend the execution of a script until a grade is provided (e.g. in [[Test elements#Tests_which_are_more_difficult_to_prepare|Drag&Match exercises or Point&Click exercises]]) use '''WaitGrade'''.<br />'''Syntax: <span style="color: red;"><span id="WAITGRADE">WAITGRADE</span></span>'''
+=== Comment ===
 * To insert a comment into the script, put it in a separate line and precede it with a semicolon.<br />'''Syntax: <span style="color: red;">;<Comment></span>'''