Before we go further there's one preference I suggest we change.

By default the message box will disappear if you open the scripting editor. Conversely if it is not visible, and you show it while you are editing it will disappear when you close the script editor. I find this behavior very confusing and annoying. Fortunately you can stop this by opening Revolution Preferences, Script Editor tab and unchecking "Hide Message Box" (1). You need to uncheck the "Hide Palettes" option too - the reason for this is otherwise, when the palettes hide and show, they will take the focus away from the message box, making it very difficult to work with when using the message box and the debugger.

Now that we've got this configuration issue out of the way, let's continue...

To show the message box, type command + m (Mac) or Control + m (windows), or select "Show Message Box" from the Tools menu.

The message box contains a button row used to access various features. The first two buttons (1) access the message box command line in single command or multi-line script command modes. Since these are what you will probably use the most, we'll start with the command line.

The remaining buttons (2) access other Revolution properties and settings and are covered further below in the section Exploring the Message Bar

The message box allows you to execute transcript command and view the results. It also contains some screens for reviewing other types of information (5) which are covered below in the section "Exploring the Message box"

To show the message box type cmd + m or select "Message Box" from the tools menu.

Type the command you wish to execute at (1), the results are displayed at (2). If the command you are executing relates to a particular stack, the defaultstack is displayed at (3) (e.g. "put the short name of this stack" would in this example return "application").

To show or hide the message box options, cick the toggle at (4).

A couple of useful tips for advanced users:

Control + a: shifts insert point to start of line
Control + n: shifts insert point to end of line

You can execute multiple commands (by separating each command with the semi-colon character, e.g.
beep ; answer "hello"

The message box keeps a history of all commands you execute. Click on the message box command area and click the up or down arrows to cycle through the available commands you have previously executed.

The second tab (1) allows you to execute multi-line commands. Type your commands into the message box - pressing return while you type will not execute your command. Resize the divider bar (2) if you need more space. When you are ready, press Enter to execute the script.

One reason why I generally don't use the multi-line mode is that it doesn't keep a history of past events. Given that most of the time you just want to execute one line commands. For those other situations where you do need say two lines you can use the ";" to concatinate two commands together, e.g. beep ; answer "hello" So, while it is handy if you want to copy and paste a script into the message box and execute it there, for the most part, you'll probably be better to use single line command mode.

Advanced tips:
In multi-line message box mode Control + Up or Down key: shifts insert point between the command editing area (top) and results area (bottom)

During development it is helpful to be able to check program logic or access features in a non-standard way. The message box makes this easy.

This tutorial reviews how you can use the message box to interact with objects, stacks, and how to use it while debugging.

Let's start by taking a look at how the message box works with your stacks.

In this example I have three stacks open "application", "Untitled 1" and "program". You will often have scripts in the card or stack script of stack that you might want to call for testing purposes.

The name of the stack which will receive commands executed by the message box appears at (3) - at the moment this is the "application" stack (1). Normally this target stack will change automatically as you swap between stack windows, unless you engage the lock (4), as I have here. Then you can swap to another stack (e.g. the Untitled stack (2) but the message box will still target the Application stack. Notice that the "Untitled 1" stack (2) is in the foreground, but the message box is still targeting the "application" stack, because I have locked the target.

So if I execute the command "test", it would be sent to the default "application" stack (3). To be precise, the message will be first sent to the card script, then if it's not handled it perculates up to the stack script.

If you have locked the message box target and you wish to target a different stack, you can manually change the target by clicking on (3) and a dropdown menu of available stacks will appear (as illustrated above).

A couple of particularly useful transcript commands when working with stacks in the message box are:

topstack - the topmost stack, in this example (2)
defaultstack - the stack which receives message by default, in this example (1).
mousestack - the stack which the mouse is positioned over

Often you will want to access properties or scripts stored in Revolution objects (buttons, fields, groups etc). The message box provides a special feature called command intelligence designed to help you.

On the right side of the message box command bar window are two options. Option (1) is "Intelligence acts on mousecontrol", option (2) is "intelligence acts on selectedobject".

Let's see how these work.

If you were to turn on "intelligence acts on mousecontrol", position the mouse over say a button, type "name" in the message box, and press return...

... the message box will substitute the command "put the name of the mouseControl"

You can also use this approach to access any custom properties of the object you have set.

The second way you can use command intelligence is to call handlers in an object.

For example I have added the following handler to the script of the "Fred" button:

on helloworld
answer "hello"
end helloworld

If I position the cursor over the Fred button and press return in the message box, and because intelligence acts on mousecontrol is on, the "helloworld" command (2) is sent to the "Fred" button and the the script executes displaying the dialog box (3).

If the object you wish to access is not easily selectable (for example it's hidden, or buried inside a complex group) you might find it useful to use the dispatch command in the message box, one advantage of this approach is that if you need to send the command again, you can retrieve it from the message box history.

- You can also include a parameter list with the dispatch command, in this case I am passing in a global variable called gLove
- putting it at the end will return "handled" if the dispatch command was successful.

If you prefer you could also execute this in single line mode by using the concatinate semi-colon char:

put "flowers" into thePeaceMode; dispatch "startworldpeace" to button "peace" with thePeaceMode ; put it

Here are some transcript words you may find useful when using the message box:

This command would set the location of whatever object you have selected (the selobj) to 500,500
set the loc of the selobj to 500,500

This command can be useful when you have a behavior script which you wish to apply to an object. First select the behavior script button, type the command in the message box (don't press return), position your mouse over the object you wish to apply the behavior to, and press return:"
set the behavior of the mousecontrol to the selobj

Select a stack file, open it:
answer file a;go it

Sometimes you may not be able to see a stack because it is offscreen. Us
set the loc of the topstack to the mouseloc

Sometimes you will have a palette window you want to edit, but you don't know what it is called. In this example we have a palette called References to Review. Type "toplevel the mousestack", position the mouse over the paletted stack, and click return.

You could also execute "edit the script of the mouseStack" to edit the script of a stack, even if it is in palette mode.

Remember that you can use the message box even while the debugger is running.

To illustrate let's look at the following script which I have placed in a button.

on mouseUp
prepareForWorldPeace
dispatchHippies
end mouseUp

local sPeaceMode

on prepareForWorldPeace
put "flowers" into sPeaceMode
breakpoint
end prepareForWorldPeace

on dispatchHippies
answer "Peace mode:"&& sPeaceMode
end dispatchHippies

Here we see the script executing, stopped at the point where it has put "flowers" into the local script variable "sPeaceMode"

Because we are in debug mode we won't be able to interact with objects using functions like mousecontrol, so instead let's send an event to the script using dispatch. The result is illustrated above.

Advanced tip:
If you ever get stuck with an unresponsive script, type command + . (period)

Now that we've covered the message box features related to the command line, let's take a look at some of the other information screens the message box offers.

The third tab allows you to view global properties. Revolution stores a wide variety of default properties.

Illustrated is the "explictVariables" property, which controls whether Revolution requires variables names to be declared before they are used. Some properties (like explicitVariables) have a shorter form (explictVars) which will also be listed.

You may also view the value of a property via a command, e.g.
put the explictVars
... in this case would return: false

Tab 4 displays a list of all global variables. This includes default global vars, as $HOME, which are always prefixed with "$".

If the variable you are viewing happens to be an array (in this case the array gEditingA (1) which I have created), then the keys of the array will be displayed in the second column (2). Click on a key to view the value (3).

The fifth tab shows pending messages in Revolution.

Advanced Tips:
Some plugins (such as glx2Inspector) generate a huge number of these events, so this tab may not be terribly easy to view as it will constantly update. In this case you might find it easier just to execute the command:
put the pendingmessages

If you use send messages a lot, you might like to install the Pending Message Manager plugin <http://www.troz.net/rev/stacks/Pending.rev> which optionally filters out all glx messages as well as rev ones.

Tab 6 shows any Frontscripts you have installed. These are scripts which are inserted in front of the message passing heirarchy.

Frontscripts and backscripts are usually only used for specialised reasons such as implementing an authoring environment. If you are new to Revolution you can safely ignore tabs 6 and 7.

Tab 7 shows the backscripts you have installed (if any). These are scripts which are inserted at the bottom of the message passing hierarchy.

Tab 8 shows the stacks which are using (the librarystacks, or the stacksinuse)

You may add, remove or edit a script of a library stack from here. If you are editing a stack script, if you make changes to the script remember you still need to save changes to the stack.

As a slight digression, you can also access library stacks from the Application Browser window (Tools menu -> Application Browser). Right click (Mac: Control click) on a stack in the list to access a context menu. You can access a variety of commonly used features from this menu.

Advanced users may find the following message box plugin useful:

"This utility reorganizes the message history and puts the messages into chronological order, deletes any doubles and installs in the message box a drop-down menu that can be completely personalized and that makes it possible to bring up or to send a message with one mouse click. Bilingual utility (installer and uninstaller.) Help stack is included. Identical appearance on all platforms."
Click here for website or here to download

After installation of the plugin, notice the script icon is added to the message box. Click this for a drop down list of commands you have issued from the message box.