Office of Digital Humanities

Digital Humanities & Technology 210

Scripts in LiveCode

Up to this point, we have focused on the latter half of 'hypermedia'—how to display the various bits of information that we wish to share. We will now turn to that portion of LiveCode that allows us to transform our media into hypermedia.

As you may have divined already, all objects in LiveCode possess a script, whether that script is populated with handlers or not. However, for the purposes of this lecture, the discussion will initially be limited to scripts for buttons (as most of the scripting you will do will be for buttons anyway). Keep in mind that most (if not all) of the concepts presented here, though applied to buttons, may apply to any other object.

Objectives

By the end of this reading you should be able to answer the following questions:

1. Which types of LiveCode objects have scripts?
2. What is handler and how is it different from a script?
3. What is an event? A messsage?
4. What is the message box for?
5. What is the LiveCode command to go to another card?
6. What is the meaning of the term "tick" in the LiveCode scripting language?
7. How do you indicate a comment in a handler? Why might you use comments?

Definitions and Tools

Script

• With the object selected, click the Script icon in the button bar.
• With the object selected, click the selection menu (square w/triangle inside it) in the properties inspector and select Edit Script.
• With the object selected, choose Object menu > Object Script.
• Press the Command (⌘)+option (Mac) or Control+alt (Windows) keys and click once on the object while in edit mode (it works in browse mode, but the object executes all applicable handlers.)
• Select the object and press ⌘+E (Mac) or Control+E (Windows).

The LiveCode Scripting Language

Commands are written in LiveCode's scripting language which has the general functionality of a stand-alone programming language like BASIC, Pascal or C, plus specific functionality to control the LiveCode environment.

Message Handlers

A message handler is a series of LiveCode commands, roughly equivalent to a program or subroutine in traditional programming languages. A handler specifies the commands to "handle" a particular event (often mouse events). It always starts with on eventName and ends with end eventName, with the commands listed between the two. All these statements together comprise a handler. Handlers are written in the following form:

on messageName
  do this
  do this
  do that
end messageName

Where messageName is any message such as mouseUp, mouseDown, openCard, etc.

Fortunately, LiveCode's script editor provides some auto-completion helps that speed up the scripting process:

• After you select or type the message name and press return, the "end" part of the statement is automatically entered for you, and the cursor is placed between the two waiting for the commands to be entered.
• Similarly, when you enter the beginning of a repeat or switch control structure (both are types of conditional statements,) the end statement is automatically generated for you, and the cursor is places between the beginning and ending statement, ready for you to add commands.

Note: Sometimes the distinction between script and handler blurs in casual conversation. Strictly speaking, a handler is proper term for the individual routines contained within a script, while script is the container where all handlers are defined and reside, i.e., a script can contain several handlers. Speaking metaphorically, a handler is a recipe and the script of an object is a cookbook.

Events and Messages

Events are actions or occurences usually instigated by the user. For buttons, the most common event is a mouseUp. This is defined as when the mouse button goes up while the cursor is located over the button. Events generate messages that are then sent to the appropriate object and cause that object to do something. By clicking on a button (a MouseUp event), a MouseUp message is generated and sent to the button. If the button possesses a MouseUp handler in its script, it then executes the commands contained within the handler, and the button is then seen as "doing something." There are many events and messages which can be used to write handlers. In addition to mouseUp, commonly used event messages are mouseDown, openCard (sent when arriving on a card,) and closeCard (sent when leaving a card.) We will learn about many more event messages in a future lesson.

Perhaps this process could be seen more clearly by extending the cookbook metaphor. A patron arrives at a restaurant and orders biscuits and gravy (the event). The waiter delivers the order (the message) to the cook (the object) who checks his mental cookbook (the script) and finds the appropriate recipe for that order (the handler). The cook then proceeds to make the biscuits and gravy to order (LiveCode commands in the handler). Strictly speaking, the cook's actions are instigated by the patron's request, much like a button acts at the user's request.

Script Editor

• Basic text processing: type/select, cut/copy/paste, undo, etc.
• Find and replace capabilities similar to those found in text processors.
• Print can be useful for documenting handlers.
• Exit by clicking the close box or choosing Close from the File menu.
• Some simple shortcuts:
  • Enter = compile (save) changes
  • Enter when no changes to compile = close the script editor
  • Tab key = format the current handler
  • Command/Control + S = Compile script and save stack
  • To look up a specific word in the LiveCode dictionary, right click on the word and choose > Find in Docs.

Some of the more useful and commonly used features of the Script Editor are:

• The script editor has its own menubar, differing from the regular LiveCode menubar and providing tools for helping you edit the script.
• The bottom section of the script editor contains several utilities: Find and Replace, Errors, variable contents, and debugging breakpoints.
• Use Edit menu > Comment and Uncomment to insert or remove hyphens or pound (#) signs (depending on what the comment character is set to.)
• Lines are automatically indented to show logical structure.
• Use a backslash ( \ ) to continue a statement on the next line. Lines may be split anywhere between words except:
  • within a literal text string (i.e. inside quotes)
  • within a comment (i.e. after double hyphen or pound sign)

Message Box

While the script editor is useful for writing "permanent" handlers for buttons, it is often handy to be able to execute a LiveCode command immediately. This capability is provided with the Message Box.

• Choose Message from the Tools menu. Command (⌘)-M (Mac) or Control-M (Windows) is the keyboard shortcut.
• Type the command in the top field message box and press Return. If there is a result or error it will show up in the bottom field.

Some Common LiveCode Scripting Commands

Here are some of the most basic and common commands that you will be using in your scripting. See the Dictionary in the LiveCode Documentation accessed either through the appropriate icon in the icon bar or through the Help menu.

Go

The go command is used to cause another card to be displayed, i.e., to navigate between cards, either within the current stack or to another stack. To move sequentially through cards, the following commands work:

• go to next card
• go to previous card

In the preceeding commands, to and card are optional in the syntax and may be omitted with impunity. To display (or move to) a card not contiguous with the current card, you may refer to a specific card by its name or number, or by using reserved words. For example:

• go to card "map"
• go card 7
• go to first card
• go last

As before, to is optional, but card must be included in order to identify the object to which we're referring.

Visual Effect

The visual effect command specifies a visual transition for LiveCode to use as it changes the information displayed, usually when it displays (or goes to) another card. Visual effects can also be used in conjunction with hide and show as explained in the next section. The default plain visual effect causes the change to appear immediately. There are several provided in LiveCode. Examine the LiveCode Dictionary for complete details and all the options. Here are a few examples:

• visual effect dissolve
• visual iris close to black
• visual effect scroll right
• visual effect scroll left
• visual effect wipe up
• visual effect wipe down
• visual effect checkerboard
• visual effect venetian blinds
• visual effect dissolve to white
• visual effect reveal up to inverse

When navigating between cards, visual effects are used in conjunction with a go command. They do not happen when you use arrow keys or View menu commands. Here is an example script of a visual effect used properly:

on mouseUp
  visual effect push right fast
  go next card
end mouseUp

The use of visual effects should be limited to conveying information (for a very specific purpose) and not just because "it looks cool." Visual effects used indiscriminately or without purpose are a distraction rather than an enhancement.

Hide/Show

The hide and show commands allow you to make fields, buttons, and other LiveCode objects appear or disappear. This command essentially toggles the visible property for an object.

• hide field "demo field"
• show field "demo field"
• hide button "demo button"
• show group "demo group"

Hidden objects not only cannot be seen but also cannot be clicked. You can see all invisible objects by choosing Show Invisible Objects from the View menu.

As mentioned earlier, visual effects can be used in conjunction with these two commands to enhance the presentation of information. Again, the default action is to display the object immediately. The judicious use of visual effects can make this change somewhat more interesting:

on mouseUp
  show field "help" with visual effect dissolve
end mouseUp

Scripted this way, the field is "dissolved" into view, making a less abrupt appearance. In the preceeding handler, the words visual effect are optional and only enhance the handler's readability. As before, visual effects should be used to convey information and not used solely for amusement or window dressing.

Put

The put command is used to place text into a field.

• put "any text" into field "demo"
• put empty into field "demo"
• put the date into field "demo"
• put the long time
• put the long time into line 2 of field "demo"

If no field name is specified, the text goes into the message box.

Wait

The wait command causes a delay or pause in a script. It will either wait for a specific amount of time or for a particular event.

• wait 3 seconds
• wait 1 second
• wait 20 ticks
• wait 500 milliseconds
• wait until the mouseClick

A tick is 1/60^th of a second. The default time unit is ticks. Thus, wait 60 is the same as wait 1 second. A millisecond is 1/1000^th of a second. The following handler displays a pop-up field:

on mouseUp
  show card field "PopUp"
  wait 3 seconds
  hide card field "PopUp"
end mouseUp

Note: The wait command prevents the handler from completing until the time interval has ended or the condition is met. You should therefore be judicious in using wait in your handlers.

Beep

The beep command sounds the "alert" tone of the computer a specified number of times. If no number is specified it beeps once.

• beep
• beep 3

The "alert" sound is the sound used by the operating system for error or attention situations. The alert sound is set at the system level, external to LiveCode. Although the default is a beep sound, it may be customized to any sound, and often is. All applications conventionally use this sound to alert the user to an error or attention condition. A wise LiveCode designer will do the same.

Comments

Comments serve to document your scripting. Despite the fact that LiveCode reads so much like English that many statements are virtually self-documenting, you should still use comments to mark major sections and clarify anything complicated. LiveCode ignores comments, but they can sure help a human understand what's going on.

Any text following two hyphens (--) or a pound sign (#) is treated as a comment, i.e. ignored when the handler is executed. The default comment symbol can be set in the Script Editor preferences. LiveCode recognizes either symbol as a comment, even though you may have selected one or the other as default. For example:

-- a comment may document handler logic
beep 3  -- or explain a particular command
--beep 3  -- or prevent a line from executing
# beep 3 # this is also a valid comment format

It is considered good practice to document your scripting with comments. You may be surprised how easily you forget how or why you scripted the way you did, especially when you come back to the script months after the fact. Comments serve as useful and helpful reminders and may prevent many hours of weeping, wailing, and gnashing of teeth. Using comments to document your handlers is considered a best practices habit.

Another common use of comments is to deactivate sections of scripts while testing and debugging. In these cases you can either insert a comment character before each line you want to deactivate, or you can use the block comment form that begins with /* and ends with */. Here’s an example:

/* Everything between these
   two comment markers is
   ignored by LiveCode when 
   executing a handler.
*/

Scripts Exercise