BYU Home pageBRIGHAM YOUNG UNIVERSITY
  Humanities Technology and Research Support Center
Back     CHum Revolution Gateway

Computers & the Humanities 210

Scripts in Revolution

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 Revolution that allows us to transform our media into hypermedia.

As you may have divined already, all objects in Revolution 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 Revolution 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 Revolution command to go to another card?
  6. What is the meaning of the term "tick" in the Revolution scripting language?
  7. How do you indicate a comment in a handler? Why might you use comments?

Definitions and Tools

Script

The script of a button is where you put the commands to specify what the button does. To edit a button's script:

The Revolution Scripting Language (Transcript)

Note: In mid-2006 Runtime Revolution officially dropped the name Transcript. The scripting language is now also called Revolution. From time to time you will still encounter the name Transcript in these pages. The name is also still commonly used in the Revolution developer community. (Old habits die hard!)

The commands are written in Revolution'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 Revolution environment.

Message Handlers

A message handler is a series of Revolution 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, Revolution's script editor provides 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 (Revolution 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 Revolution'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 Transcript command immediately. This capability is provided with the Message Box.

Some Common Revolution 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 Revolution 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: 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 Revolution 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 Revolution. Examine the Transcript 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.

Hide/Show

The hide and show commands allow you to make fields, buttons, and other Revolution 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.

Put

The put command is used to place text into a field. 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. 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.

Beep

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 Revolution. 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 Revolution designer will do the same.

Comments

Comments serve to document your scripting. Despite the fact that Transcript 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. Revolution 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. Revolution recognizes either symbol as a comment, even though you may have selected one or the other as default. For example:

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.

Scripts Exercise

Back     CHum Revolution Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University