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:
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.
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
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:
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 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.
Some of the more useful and commonly used features of the Script Editor are:
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.
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 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,
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
to is optional, but
card must be included in order to identify the object to which we're referring.
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
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.
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.
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.
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
tick is 1/60th of a second. The default time unit is
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
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. */