|Issue 87 March 4 2010|
Tips and Tricks with the Message Box
This article is reprinted from the lessons area of our tutorials site. If you would like to see more lessons like this please visit lessons.runrev.com!
The message box can be very useful in assisting your development efforts. This lesson covers some helpful tips and tricks for getting the most out of the message box, not all of which may be completely intuitive.
First - configure the message box options (or: "why does the message box disappear when the script editor opens?")
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...
Getting started: Open the message box
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
Message Box (MB) command line mode (tab 1)
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
You can execute multiple commands (by separating each command with the semi-colon character, e.g.
Message box - Command History
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.
MB command line multi-line (script) mode (tab 2)
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.
Why use the message box
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.
Using the message box with stacks
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)
Using the message box with objects - command intelligence
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.
Message box - using command intelligence
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...
Message box - using command intelligence to access an object's properties
... 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:
Message box - using command intelligence to access an object's script handlers
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).
Message box and dispatch
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
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
Message box command line - some useful command examples
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
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:"
Select a stack file, open it:
Sometimes you may not be able to see a stack because it is offscreen. Us
Editing palettes by pointing at them with the mouse - use the mousestack
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.
Using the message box while debugging
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.
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.
Exploring the message box settings & property tabs
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.
Exploring the MB (tab 3): Viewing global properties
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.
Exploring the MB (tab 4): Global Variables
Tab 4 displays a list of all global variables. This includes default global vars, as $HOME, which are always prefixed with "$".
Exploring the MB (tab 4): Global variables - arrays
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).
Exploring the MB (tab 5): Pending messages
The fifth tab shows pending messages in Revolution.
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.
Exploring the MB (tab 6): Frontscripts
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.
Exploring the MB (tab 7): Backscripts
Tab 7 shows the backscripts you have installed (if any). These are scripts which are inserted at the bottom of the message passing hierarchy.
Exploring the MB (tab 8): Librarystacks/ stacks in use
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.
Accessing common operations for open stacks
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.
Message box extras - Message Box Picker 1.1
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."
Message Box Picker in action
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.