Office of Digital Humanities
Back     BYU LiveCode Lessons Gateway

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.


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


The script of an object, such as a button, is where you put the commands to specify what that button does. To open a button's (or any object's) script editor:

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 userClicksMouse
  do this
  do this
  do that
end userClicksMouse

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

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

The script editor is LiveCode's special built-in word processor for editing scripts.

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

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.

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.


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:

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:

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:

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.


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.

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.


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

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


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.

A tick is 1/60th of a second. The default time unit is ticks. Thus, wait 60 is the same as wait 1 second. A millisecond is 1/1000th 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.


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

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 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

Back     BYU LiveCode Lessons Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University