LiveCode Interactive Tutorials

Way back in April 2015 I made a small prototype of how an interactive tutorial system might work in LiveCode. Here’s how it looked:

It worked reasonably well – well enough to demonstrate the feasibility of such a system. It was generally agreed that it was something we would like to develop. However the prototype was almost completely hard-coded, meaning changing the tutorial would be difficult, and there was no capacity for having multiple different tutorials in the IDE. As there was still plenty of work to do on the IDE for 8.0, the tutorial was put on hold for a while (albeit returned to periodically to make sure it still vaguely worked, and to make some of the generalisations it needed).

Cut to almost a year later, and we found some time to bring the tutorial system up to date with all the IDE changes, and make it look much nicer!

(short animated gif displaying a section of the interactive welcome inside the LiveCode 8 IDE)

The new version is also much more general than the prototype. The tutorial script is a written in a domain-specific language which is interpreted by the tutorial system as the set of instructions for the tutorial, rather than having all its steps hard-coded.

How a tutorial is written

The tutorial language has been designed to be as simple as possible, and so that tutorials can be written without any need to understand the underlying principles that make it work (although if you are interested I will describe these later on).

Each part of a tutorial is called a step. A step usually consists of some text to display, and some actions. The most basic type of step is an interlude, which displays the text, and goes on to the next step when the user clicks on the ‘Got It’ button.

step "Step One"
	Here is some information in an interlude step. Click 'Got It' to
	continue.
action
	interlude
	go to step "Step Two"
end step

Steps can also wait for specific user actions to be completed before continuing. Such steps usually have a highlight action, which among other things tells the tutorial stack what to point at to prompt the user.

step "Open Property Inspector"
	Click on the Inspector icon on the toolbar to open the property
	inspector.
action
	-- Highlight the appropriate toolbar icon
	highlight toolbar "Inspector"
	-- Wait until the user has performed the action
	wait until there is an inspector for stack "Mainstack"
	go to step "Set Stack Title"
end step

In this example, the tutorial stack points at the Object menu, and disables all menu items except for Card Script. Once this menu item is selected, the tutorial continues.

Various different things can be highlighted:

• Menu items
• IDE stacks
• Individual tools on the tools palette
• Menubar icons
• Property inspector controllers
• Script lines
• The apply button, and the tabbed panes in the script editor
• Stacks created in the tutorial, and objects on those stacks

The tutorial uses a tagging system to enable the tutorial author to refer to the objects that have been created. This is done using a capture action, for example:

step "Create Stack"
	Click on the File menu, and select 'New Stack' → 'Default Size'.
action
	-- Highlight the appropriate menu item
	highlight menu item "Default Size" of menu item "New Stack" of menu "File"
	-- Tag the stack for reference later on
	capture the next new stack as "Mainstack"
	-- Wait until the user has performed the action
	wait until there is a stack "Mainstack"
	go to step "Set Stack Properties"
end step

Subsequent objects created on stack “Main Stack” can then be tagged. For example:

capture the next new widget of stack "Main Stack" as "Header"

The tutorial finishes when a step is completed that doesn’t contain a go to step action.

The ‘Interactive Welcome’ tutorial which is accessible from the start center in 8.0 DP 16 onwards, has of course been written in the tutorial language. You can look at the full text of the tutorial on GitHub. A more formal specification of the language can be found here.

How it works

The tutorial works by parsing the tutorial text into an array of steps, and when the tutorial is started the stack enters the execution loop, as depicted below:

The tutorial execution loop works by storing data about what it is waiting for, and subscribing to the corresponding IDE message. When a user action triggers a message, the tutorial checks to see if the objects are in the desired state, and if so, continues execution.

The user prompt for each step is a stack (in fact the ‘revTutorial’ stack itself). The stack creates an appropriately shaped image to fulfil the requirements of the step’s message and highlighting properties, and has its windowShape property set to the id of the image.

The main text content of the tutorial step is placed in the main message field. If the step has a script, it is placed in a separate field and the IDE’s internal script colorisation command is used to display the code as it would be in the script editor.

The highlight action contains information about which object on the user stack or which element of the IDE the user is required to act on to fulfil the wait condition of the current step. When the highlighted element is an element of another IDE stack, the tutorial system notifies the relevant stack via the IDE library, and requests the rect of any target object in order to position itself appropriately. The tutorial system also attempts to sandbox the IDE during a tutorial by disabling everything except any highlighted elements.

The tutorial system makes extensive use of the IDE’s new publish/subscribe messaging model to function. It doesn’t need to be inserted as a frontscript. For example, if the wait condition is for a new stack, the tutorial system will subscribe to ideNewStack. If it is for a property to be set on an object, it will subscribe to idePropertyChanged for that object.

By working this way, the tutorial system does not need to actually execute wait with messages or implement any kind of polling loop while waiting for the user to complete the action to go on to the next step.

Plans for the system

Eventually we hope to expand the range and number of tutorials available in the IDE, and provide a reasonable interface for general courses in learning LiveCode, perhaps something like this:

Other possibilities include creating a plugin to help with authoring tutorials, and providing a way for user-authored tutorials or courses to be downloaded and run by anyone.

The ‘interactive welcome’ tutorial is included in LiveCode 8.0 DP 16, available here. Please give it a go! All feedback on the content of the tutorial or how it functions is much appreciated.