Magic Cap Simulator

Magic Cap Simulator is a development version of Magic Cap that runs as a Macintosh application. It has special features that are not available in the version of Magic Cap that runs on communicators. Most of these features are available from items in the Macintosh menu bar. Others, like construction tools, are available in Magic Cap Simulator itself.

This section describes the menus and menu items found in Magic Cap Simulator.

Apple Menu

File Menu

Edit Menu

Hardware Menu

Examine Menu

Discipline Menu

Testing Menu

Log Menu

This chapter describes tools and techniques for working with objects in Magic Cap. These are called construction tools because they involve assembling and modifying the raw materials supplied by classes and static objects. Building a Magic Cap package with CodeWarrior Magic/MPW involves spending part of your development time modifying objects in Magic Cap itself.

Most of your work with Magic Cap objects will be modifying the appearance of viewable objects. This includes changing the size, placement and color of different objects, among other things.

Magic Cap offers users two basic operating modes. Most people will use the default normal mode in which the communicator behaves in the manner described by the user documentation. Magic Cap also provides construction mode, which gives the user enhanced control over objects.

Construction mode may be used by two different kinds of people. A power user can use construction mode on a communicator to personalize the environment in ways not available in normal mode. In addition, a developer can use construction mode as part of the design and testing cycle in developing packages for Magic Cap. This chapter is aimed at developers and provides an introduction to the various tools available in construction mode.

When you make software packages, you'll use the construction tools described here to build large parts of your software.

Construction mode itself is different in a Magic Cap communicator and in Magic Cap Simulator. The simulator provides additional features not found on a communicator.

The sections that follow treat the four basic tools you'll use to perform construction with Magic Cap.

Turning on Construction Mode

Here is a brief introduction in how to get started with construction mode. While construction mode is available on both the communicator and Magic Cap Simulator, you should use the version on Magic Cap Simulator since it has extra tools for developers.

First, change to construction mode by going to the control panel in the hallway. Touch general to make the general control panel appear. Then touch construction mode so that it's checked.

You'll notice that the Stamper at the bottom of the screen immediately changes to the Magic hat. This important change is one of several that occur when construction mode is turned on.

Some of the changes you'll see in construction mode include the following:

• The Magic hat replaces the Stamper at the bottom of the screen. The Magic hat is a combined catalog and storehouse of objects. In it you'll find boxes, text fields, controls and lots of coupons for modifying viewable objects on the screen. The Magic hat window also contains the original contents of the Stamper window.
• The Tool holder at the bottom of the screen contains additional construction tools.
• The ability to write Magic Script is available only in construction mode. A script is a set of instructions for an object to follow at a certain time. Magic Script is the language in which these scripts are written. Magic Cap lets you write scripts without learning any commands. As you edit a script, you simply touch on an object or on a script statement to see what the reasonable choices are for that spot in the script.

Shortcut: There is a temporary shortcut to begin construction mode. First, open the stamps window open. Then, while pressing the option key, touch the middle of the gray title bar that runs across the top of the stamps window. This shortcut only works for a single choice from Magic hat. After you make the choice and use it, Magic hat turns back into Stamper.

Magic hat

When you enable construction mode the biggest change you'll see is that the Stamper will be replaced by the Magic hat at the bottom of the screen. When you touch the Magic hat its window will appear.

The Magic hat is arranged hierarchically into eight categories. If you touch on one of the category boxes Magic Cap will redraw its window to display that category. For example, the stamps category contains the contents of the original Stamper. You can always make the Magic hat or the Stamper go away by touching the x in its top right corner.

Touch on a category box to go down one level in the Magic hat and see the items in that category. To go up one level, touch the pointing hand at the top right corner of the Magic hat. Touching Stamps displays the normal collection of stamps from the Stamper. Touching another category displays a bank of drawers containing objects of that category.

To dispense a stamp or other object from the Stamper or the Magic hat, touch the object. and the Magic hat will make a copy of the object and then go away, leaving you with the object you chose. If the object is an intangible attribute like a color, the Magic hat provides a temporary container called a coupon to hold it until you do something with it.

Once you've opened the Magic hat, you may want to dispense more than one object. To do this, hold down the option key and tap on an object. It will fall out of the Magic hat into the scene behind while the window remains. Let go of the option key and touch another item. The Magic hat will go away.

Within a category, drawers are used to select among different sub-categories of objects. Each drawer contains a screenful of objects. Touch a drawer to see the objects inside. At the bottom of the set of drawers is a choice box that lets you choose among whole banks of drawers when there are too many objects to fit in one bank. Touch one of the arrows to switch between the banks.

Coupons

Coupons hold intangible attributes from the Magic hat for applying to viewable objects. For example, to change the color of an object you would select the color in the Magic hat. This action will automatically put the color in a coupon which can then be applied an object by dropping it on the object. You can slide coupons without first getting the move tool.

A coupon has a thick dashed border around it. Each coupon is good for one change to a setting in a viewable object.

When you drag a coupon over another object, the object will highlight if it can accept the coupon. If it doesn't highlight, the object can't do anything with the coupon. For example, you can't drop a border into a stamp, so the stamp doesn't highlight when you drag a border coupon over it.

Some objects have multiple parts and you can drop coupons onto each part to perform different functions. For example, boxes have content and border parts. You can drop different color coupons into the border and content, setting them to different colors.

Text Coupons

You can create a text coupon with the keyboard.

Here's how to make a text coupon: Hold down the option key and touch the keyboard gadget at the bottom of the screen. The keyboard will appear with a label maker above it. This kind of keyboard is called the coupon maker. Once the coupon maker appears, anything you type will go into it and make a coupon.

You'll notice that when you make the coupon maker appear, the keyboard also undergoes a slight change, the switch changes to a choice box. This gives you access to the symbols and accents planes of the keyboard.

To put the coupon maker away: Tear the coupon off by touching down on it and sliding your finger across the screen or touch the coupon maker.

Stamps

The Stamper contains a collection of different stamps that you can use as clip art in the cards of your packages.

You can create your own stamps from Macintosh graphics. Just select any image from a paint application and copy it to the Macintosh clipboard. Then, start or activate Magic Cap Simulator and choose Paste Image Coupon from the Edit menu. The image will be transformed into an image coupon in Magic Cap. If the image is in color and you want to create a monochrome image coupon, hold down the Macintosh shift key while you choose Paste. You can then drag and drop the image coupon into any stamp.

general	The general drawer contains a selection of diverse decorative stamps, an animation, the sound-holding lips stamp, and a sticky note.
office	The stamps in the office drawer are designedfor marking office messages and commercial transactions.
occasions	The occasions drawer holds decorative stamps for assorted holidays and special events.
animations	Magic Cap provides a selection of animated characters that you can use to decorate your cards. If you tinker an animation with the Tinker tool described later in this chapter, you can control how fast it moves horizontally and vertically and how rapidly the animation's frames change. You can also determine whether the animation should turn when it hits the sides of its container.
local	Scenes can have their own stamps. If they do, these stamps will appear in the local drawer and the name of the local drawer will match that of the scene. Hallway is an example of a scene with its own stamps. Scenes in packages can also have their own stamps.
faces	The faces in the faces drawer are often useful when you're sending a message to someone and want to emphasize your mood visually.
symbols	The symbols drawer contains common symbols you might find useful for any message and for labeling pictures or maps you draw.
leisure	The leisure drawer includes stamps representing popular diversions and pastimes.
songs	Each song stamp contains a different tune. Place one of these stamps on a card, then touch the stamp to play.
misc.	This drawer contains miscellaneous stamps.

Components

buttons

switches

choices

Choice boxes let users choose among different options with text names. Sliders let users control continuously adjustable levels. This drawer also contains meters which let users select numeric values.

text

Text fields contain text and scribbles. Text has many characteristics that you can set: typeface, size, style, and alignment. To edit the text in a text field, tap on the text field to get an insertion point, then touch the keyboard gadget to show the keyboard, or type on the Macintosh keyboard. You can set the characteristics of a text field with the coupons in the text styles category box.

Text fields can contain many other kinds of objects, including shapes, stamps, animations, and even other text fields; objects inside are drawn clipped to the containing text field. When you create a text field by pulling it out of the Magic hat, its ability to contain other objects is turned off. To turn it on, tinker the text field with the Tinker tool and flip the can contain switch to the on position.

The text field components include three special objects named phone, time and numbers. These are simple forms processing controls. For example, the numbers text field control component only accepts numeric input.

clocks

boxes

Boxes are objects for organizing groups of other objects. They have a border and are filled with a particular color. They're different from text fields in that boxes are primarily organizational and are designed to hold heterogeneous groups of graphical objects, not text.

shapes

icons

Colors

Sounds

A sound coupon specifies a digitized or synthesized sound. You can drop sound coupons into most viewable objects. The objects will play the specified sound when they're tapped. To hear the sound in a sound coupon, tap the coupon.

If you don't specify a sound, switches and buttons will play the touch sound when tapped.

standard	The standard drawer contains the sounds used throughout Magic Cap to keep the user aware of what is happening. You can drop these coupons into an object to change the sound that object makes when activated.
instruments	The instruments drawer contains coupons representing all the synthesized musical instruments that are part of Magic Cap. These are the instruments used for making MIDI songs.
songs	The songs in the songs drawer use the instruments described above to make synthesized music.
phone	Phones make sounds and the communicator is a phone, so it knows how to make all the DTMF sounds that a phone needs to make.
more	The more drawer contains extra sounds, including the ever popular "no sound" coupon.

Borders

Use a border coupon to change the style of an object's border. Use the no border coupon to remove the border from an object. Some objects that accept borders are boxes, fields, the Inspector, and meters.

basic	The basic border drawer includes the no border coupon, which you drop on an object to rid it of an existing border.
lines	These are the simplest borders. They draw quickly and are widely used in Magic Cap.
fancy	These fancy frames might be used to set off an austere minimalist sketch.
objects	The book and clock frames in the objects drawer are useful for books and clocks.
misc.	The misc. drawer contains extra borders.

Text styles

Text style coupons come in several flavors. Probably the most useful are complete font coupons, which combine a type style and face with a size, like Book 18, which is an upright (Roman), 18-point version of the serif typeface Book.

Coupons are also available to change individual aspects of type--the face, size, or style (obliqueness and weight, underlining and outlining).

All font coupons can be dropped into text in text fields. Many objects have text labels associated with them. You can change the appearance of a label by dropping text style coupons into it.

sign	Sign is a basic sans-serif typeface. Many people find it is readable on the screen even at small sizes.
book	Book is a simple serif typeface. Many people find that the serifs on Book make the face look a little more personal and relaxed than the austere Sign. Magic Cap includes two custom-drawn bold fonts of the Book face.
styles	The styles drawer includes some sophisticated versions of the basic text styles.
misc.	Fat Caps and Jot are two special-purpose typefaces. In Magic Cap, Jot is used as a kind of proxy for handwriting, often showing information that the user added. Fat Caps is used to fit labels in tight spaces.

Shadows

Many objects are drawn with shadows to improve their appearance. You can use shadow coupons to change a shadow's appearance, or to remove a shadow. You can drop shadows into most viewable objects. The shadow style chooser includes arrows to select among its choices. To get a coupon from this dispenser, press down on the center section and drag a coupon out.

Extras

line styles		Drop a line style coupon into an object to change the appearance of the border that's drawn around it.
properties	make moveable make unmovable make copiable make uncopiable make undeletable	Many an object that you see can be modified with the view coupons you can find by tapping properties in the Magic hat. You can use these coupons to change the behavior of objects.
shape types		Shape type coupons let you change a shape's type among various styles, such as rectangle, circle, diamond, arrow. Shape type coupons can only be dropped into shape objects.
misc.	hide show contents rotate left rotate right flip vertical flip horizontal bring to front send to back put in form pull from form	The misc. drawer contains properties that control the geometric properties of a viewable object. Shapes, stamps, and animations can be rotated in 90-degree increments. You can drop orientation coupons into these objects to rotate or flip them. The put in form coupon and the pull from form coupon work with the form objects in cards.

Tool holder

Tools are modes that you can turn on and off. When a tool is on, objects do something special when you touch them. Most of the time, you only need to touch objects to make them work. But in construction mode, you can copy and stretch and manipulate objects in various ways.

To make the Tool holder appear, touch its icon at the bottom of the screen. The Tool holder window will appear and display a set of pencils. At the bottom of the Tools window is a choice box that lets you choose among the sets of tools. In construction mode, you'll be able to use the authoring and debugging tools.

Note: Once the Tool holder is open, you can turn on construction mode temporarily by holding down the option key and touching in the gray bar at the top, where the text reads Tools.

When you select a tool, the Tools window disappears and the Tool holder icon at the bottom of the screen changes to a tool indicator icon. This icon represents the current tool that will be applied to the next object you touch. If an object does not accept the tool, Magic Cap will play a sound to let you know and let you choose another object. If you don't need a tool you have chosen, tap the tool indicator icon to dismiss it.

Authoring

The authoring tools control the layout of objects. You can move, copy and stretch object. In addition, you can change an object's attributes that determine whether they can be moved, copied or stretched.

move tool

To move an object, tap the move tool, then slide the object around on the screen. Some objects can be moved simply by sliding them, without your having to tap the move tool first. But most objects require that you tap the move tool to move them. It's always worth trying an object to see if you can move it without the move tool. If you can't, try the move tool. If you still can't move the object, you might need to turn its can move switch on. Use the Tinker tool, described below, to tinker the object. Switch the appropriate switch in the open Tinker window to can move. Close the Tinker window by tapping on the wide bar along its top. You should now be able to move the object with the move tool.

When you move an object on the screen, it's drawn with a shadow to show you that it's attached solidly to your finger but not to the screen.

copy tool

You can use the copy tool to create a copy of an object. To make a copy, tap the copy tool, then slide out a new copy of an object. The original object will remain in its old location while you slide the newly created copy.

You may have to set the can copy attribute with the Tinker tool mentioned below before using the copy tool.

stretch tool

You can use the stretch tool to resize most objects. To do this, tap the stretch tool, then drag an object to its new size.

You may have to set the can stretch attribute with the Tinker tool mentioned below before using the stretch tool.

tinker tool

The Tinker tool lets you work inside an object to examine or adjust its settings. An object's settings are the qualities that affect its appearance and behavior, such as its shape, the colors that it's drawn with, how it's labeled, and what happens when you touch it. You can change an object's qualities by dropping coupons on it, by tinkering it or with some other tool.

When you tap the Tinker tool, it becomes the current tool and the Tinker tool icon appears in the bottom of the screen. When you tap another object, a window will appear with information showing the settings and parts that are inside the object.

The switches on the right control a number of properties: whether the object can be moved, copied, or stretched, where and how its label is drawn relative to the object being tinkered. The label chooser lets you select one of 15 positions for the label by tapping the position you want. There's also a data string in the bottom right corner of the window that shows how many bytes of memory the object uses.

The settings that are shown when you open an object will vary for different classes of objects. If you see coupons that you like, you can drag them out of the open window and drop them on other objects. However, you can't drop coupons into the Tinker window to change an object. Just drop the coupons on the object itself to make the changes.

You can move the Tinker window around by grabbing its title bar, and you can tap the close box to close the window.

Debugging with Inspector

The other choice box added to the tool holder in construction mode is for the Inspector. The Inspector provides information about objects in Magic Cap.

There are two ways to use the Inspector: through the Tool holder and through menus in Magic Cap Simulator.

Here's how to use the Inspector from the Tool holder. In construction mode do the following:

1. Tap on the Tool holder and the Tool holder choice box will appear.
2. Use the arrows or the tool name choice box to display the Inspector tool:

   

3. Tap on the Inspector tool so that it becomes the current tool. The Tool holder icon at the bottom of the screen will be replaced by the Inspector icon to indicate that it is the current tool.
4. Tap on some viewable object and the Inspector window will appear with information about that object.

   

Magic Script

Scripts are instructions that let you tell objects how to behave. Scripts can determine what buttons do when they're touched, what meters display, and what happens when you flip switches.

Scripts are written in a simple language called Magic Script with an interactive script editor that was designed to make scripting easy. Using Magic Script is different than using other languages. At each stage of the scripting process the Magic Script editor presents you with a series of options that are valid at that point. You build a script by selecting among these options. Along the way, the Magic Script editor helps you to find the correct Magic Script term for what you want to do so you'll never make a syntax error!

Writing scripts is often more convenient and no slower than writing the equivalent with ObjectMaker or C. With the script editor, you will write a script and then close it. To save the script for future use, you'll have to dump the contents of your package or object into a text file.

Note: The Magic Script editor is part of Magic Cap Simulator and is a programming tool for developing Magic Cap packages. While Magic Script itself is part of the Magic Cap runtime system and is reliable, the Magic Script editor is under development and can present some problems. You should only use Magic Script for simple tasks.

Writing Scripts

The following steps describe how to write a simple script. This example will demonstrate the mechanics of script development with the Magic Script editor. We will use the HelloWorld sample package and write a script that toggles the color of the box in the HelloWorld package when you tap it.

1. Turn on construction mode. Scripting is usually done while Magic Cap is in construction mode. Select the construction mode switch in the control panel's general category.
2. Display an object. Navigate through Magic Cap until the object you want to script is visible. Use the Greeter object in the HelloWorld package as an example.
3. Tap the Tinker tool. Scripting is done with the Tinker tool described earlier in this chapter. When the Tinker tool is the current tool at the bottom of the screen you are ready to begin scripting an object.
4. Option-tap the object. While holding down the option key find the object you want to script and tap it. A script editor window appears for the object whose script you want to edit. The script editor window appears with the name of the object and its runtime object ID. If the object didn't have a script before, an empty script window appears.

   

5. Tap the inkwell to insert a new Magic Script statement. Tap the inkwell whenever you want to add a new statement to a script and the Magic Script editor will insert a new statement into the script.

   

   The first statement you add to a script creates a handler. A handler is a part of a script that is associated with an event, either a user action or a message from an object. The word action is a place holder for a choice that you make.

6. Tap the word action in the on statement to present a series of choices. When you choose an underlined word or phrase in a script a choice box appears presenting a series of available options. The arrow at the bottom of the menu indicates more options to choose from.

   

7. Choose the word tap in the menu. When you make a choice in a Magic Script statement menu the word or phrase is inserted into the corresponding statement in the script. The new statement may present you with other underlined phrases which you treat in the same way as a new statement. If you want to remove a statement slide it to the trash. You can also move statements around in a script by sliding them.
8. Tap the inkwell again to insert another statement. Whenever you insert a new statement in a Magic Script, you start with a simple template that you fill out with the Magic Script editor.

   

9. Tap new statement to display its menu. The menu contains a list of different kinds of statements that a script can have.

   

10. Tap operation in the statement menu. The new statement phrase will be replaced by the operation statement. The operation statement is also a place holder for a choice that you make. Since this will be a simple script we will choose a simple action to perform when the object is tapped.

    

11. Tap the word operation in the statement. The operation statement provides you with a variety of operations you can request of the RESPONDER object. The #RESPONDER is the object that will respond to the operation. In this case, the responder is the Greeter object that you are scripting. The script editor gets its list of operations from the responder by determining which of the responder's operations have the safe and common flags set. You can set the responder to object other than the one you're scripting by tapping #RESPONDER and then tapping the other object.

    

12. Tap the phrase get/set highlighted in the statement choice box. Again the statement menu will disappear and the new statement will remain in the script editor window. By default the get/set highlighted statement displays its get variant.

    

13. Toggle the get word to set. The script now contains three statements that represent a valid and even useful script. The single operation statement tells the responder to reset its highlight color to the opposite of its current state when the object is tapped.

    

14. Close the script editor window. Tap the close box in the upper right corner of the script editor window.
15. Test the script. You can test the script by tapping the Greeter in the HelloWorld package and toggling its color. When you tap on the Greeter its highlight color will change. Tapping on it again will return it to its original state.

That's all there is to writing a script with the Magic Script editor. The sections that follow provide more details on the different features of Magic Script.

Handlers

A handler is a script statement that responds to a particular system event. Some events are the result of user actions; for example, when you tap an object, a tap event is sent to the object. Other events are generated automatically by the system. For example, the system sends idle events to all objects when nothing else is happening.

Note: The ObjectMaker chapter in this book describes classes and operations. Operations can have implementations that use C code or scripts.

The series of statements within an on _____ ... end _____ pair is called a handler since this is how Magic Script should handle certain events. All your script statements will be in handlers. You can set a handler's event type by tapping on the action keyword that appears after the on keyword. The on statement tells Magic Script when to execute the series of statements in the handler.

When you select on from the new statement menu, you'll get a handler that looks like this:

on action
end action

You can change the event that a handler responds to. Each class can define the events it accepts. Tap the under-bracketed word action and choose one of the other events from the menu. These are some of the events available for handlers:

Command	Description
idle	when nothing else is going on
tap	when you release the object soon after touching
touch	as soon as you touch the object
play sound	when the object plays a sound
pressed	when you release the object after holding down your finger on it
arrived	when the object arrives as part of a event
set orientation	when the rotation of a viewable object changes
set entity	when the entity (a person, company, or group) to which the object is set changes---particularly useful for objects that have to do with addressing or calling people
press	when the user holds down on the object
pressing	while the user is holding down on the object
on screen	when the object appears on the screen
tap center	when the object is tapped in its center
touching	while the user is touching the object
touched	when the user lets up after touching
delete scribble	when a scribble on the object gets deleted
prepare to send	just before the object gets sent as part of a event
closing, opening card	when the card the object is on is displayed on the screen
action	usually, when the object is touched
tap here	generally, when the object is tapped
set shadow offset	when the distance of the object's edge from its shadow is changed
inspect	when the inspector starts looking at the object
set max	when the value of the object is set to its maximum
set min	when the value of the object is set to its minimum
set value	when the value of the object is changed at all
set percent	when the percent value of a Control object is changed
set fraction	when the fractional value of an object is changed.

The list of events that appears when you touch action corresponds to the operations specified in the class's definition file with the scriptable keyword. You can use an advanced technique to create a script for any of an object's operations, not just scriptable ones. To do this, hold down the Macintosh option key and touch the action or other event name. You can then type the name of any operation defined by the class.

Statements

Each logical line of a script is called a statement. Some statements will wrap onto more than one physical line in the script editor, but each acts like a single line. When the Magic Cap communicator executes a script, it goes through the statements in order. When you want to add a line to a script, you can drag a new statement out of the inkwell at the right side of the script editor window. Or you can tap the inkwell to get a new statement. When you tap the newly created statement, you'll get a menu that lets you choose the kind of statement you want.

To pull a single script statement out of a multi-line script, touch and drag the statement to where you want it. As you drag a statement across the screen, it looks like a coupon.

New Statement Menu

Words in scripts with a gray bracket underneath are those that you can change. Tap on such changeable words to see your choices, to allow yourself to select an object to which the statement should apply, or to toggle between possibilities.

To make a new statement that operates on an object, touch operation and then RESPONDER and Magic Cap will get ready for you to point at an object on the screen. By default, #RESPONDER represents the object you are scripting. Touch some object and #RESPONDER will refer to it instead. You can then touch the operation name if you want to change it.

If you can't touch an object because it's not on the screen or is not a viewable, you can refer to it by typing. Option-touch #RESPONDER, then type the object's ID in hexadecimal, starting with a dollar sign (for example, $800024DA). You can specify an indexical using brace syntax to indicate its indexical number (for example {7,14}). See the file Indexicals.h to look up indexical numbers from their symbolic names. You can also look for the object in the Inspector and tap on its text description there.

Magic Script is not just extensible, it obtains the very statements it offers by asking each object what it can do. For you as a scripter, this just means that Magic Script will automatically know exactly what operations each object can perform, even if that object was not built into the system when Magic Script was created.

Tap operation to see the operations that are valid for scripting. These are operations that have the safe and common flags set in the object's class definition.

Note: You can change an existing statement to be one of the other kinds of statements by holding down the option key when you tap the statement.

on

math

get  object operator  object

Tap on the word operator to select the operation you'd like to perform and the two words object to set the values you'd like to operate on.

You can also select text--such as a number--and drag it into the object words in the script statement.

if

The if statement is the basic conditional in Magic Script, a way for Magic Script to make decisions. When you choose if from the new statement menu, you'll get this in your script:

if it is nil object then
end if

You can make the otherwise go away by tapping on the first if. Change either of the words something to be specific containers by tapping on it and choosing the container you want from the menu that appears. You can also drag text from a field into the word something in order to get other values.

You choose a comparison operator when you create an if statement. In this version of the software, these are the choices for comparison operators:

is
is not
<
>
>=
#
is in
is not in
contains

repeat

Use the repeat statement to make a script that executes repeatedly in a loop. Any statements that you place between the repeat and end repeat statements will be executed repeatedly as long the repeat condition is true.

You can specify five kinds of repeat conditions:

Statement	Description
repeat forever	executes until "abort scripts" message
repeat for number times	repeat a specified number of times
repeat while something is something	repeat while condition is true
repeat until something is something	repeat until condition becomes true
repeat with container = number to number	use a loop variable. Tap on the word to and toggle it to down to, which will allow your repeat statement to count down.

The software defines a special object called the system object. It accepts several global messages. One of these global messages is abort scripts, which causes runaway scripts to stop. Type Command-. (period) on the Macintosh keyboard to abort running scripts.

The repeat capability is under construction in this version of the software. You can use the forms repeat forever and repeat for number times to try out repeat statements. To get a number into a repeat for number times statement, drag a number from a field and drop it into the word number in the repeat statement.

value

When you choose value from the new statement menu, you'll see this in your script:

 
get object into it 

You can tap on get to change the statement to:

 
put "Cassiopeia" into it 

If you tap on container, the only pre-made container--it--will suggest itself to you. You can also create a text coupon with the keyboard's label maker and drag it into container to change its name. Text dragged here will create a container with that name. For example, drag "The Heavens" from a field into the word container in your put statement:

put "Cassiopeia" into The Heavens

Note that container names can be any text, even with spaces amidst.

comment

Comments don't do anything but tell you about what other things in the script do. To put a comment into the space labeled no comment, hold down the option key and touch the under-bracketed words no comment. They will be highlighted in gray. Now touch the keyboard at the bottom of the screen. The keyboard will appear. Type out your comment.

it

When you move a slider or change the value of a meter, it gets the new value. You can use it within the script of a slider or meter.

You can make other containers by dragging text coupons from the keyboard's label maker and dropping them into the word container in a Magic Script statement.

Special Keyboard Feature

Sometimes you'll need to enter information to a script with the keyboard. For example, if a statement needs an object ID or an indexical, you can enter these with the keyboard. To do this, hold down the option key and touch one of the under-bracketed words in a script--an area for an object, for a method, for a constant (like a string or an integer). The text there will be selected, highlighted in gray. Type out what you would like to go into the script.

The Inspector is a tool for interactively analyzing Magic Cap objects. With it you will point at objects and look at their contents. Magic Cap Simulator has a menu named Examine with several items that work with the Inspector.

Menu Item	Keyboard Equivalent	Description
Show Inspector	command-i	Displays the Inspector window.
Hide Inspector	"	Hides the Inspector window.
Dump Inspector Target	command-h	Dumps the text description of the object in the Inspector into the log file
Dump Inspector Target Deep		Dumps the text description of the object in the Inspector---and all the objects it contains---into the log file
Dump Package		Dumps the text descriptions of all the objects of a package into the log file

When the Inspector appears, it displays a list of the current hierarchy of viewable objects, called the view list (see the figure above). To see information about any object in the view list, tap it and the display will change (as in the figure below).

The Inspector displays the values for each of the fields of the object. Preceding the display of the object's fields are its object ID (with its name, if any), the object's size in bytes, and the settings of the object's flags. The Inspector draws gray lines to separate fields defined by superclasses.

If the information you're looking at doesn't fit in the Inspector window, you can scroll it (vertically only) by sliding the text, or you can use the stretch tool to enlarge the Inspector's window. You can also stretch the Inspector without getting the stretch tool by simply dragging on its frame, an operation that requires precise pointing.

If you tap on a field that holds an object ID, the Inspector will change to show you information about that object.

The Inspector provides five controls in its title bar that let you use additional features: O, X, <, $, and ?. If you tap ? in the title bar, then tap an object, the Inspector displays that object's fields. This will change the Inspector's target object to the newly selected object. Tap < to make the Inspector display the fields of the object that it displayed just previously. Tap the X to switch between seeing the view list and an object's fields.

You can use the Inspector to begin tinkering with any object in the view list, including objects that you can't touch, like the screen object. To do this, tap the O (for Open) in the Inspector's title bar while it's displaying information about the object that you want to open. Option-tap the O to open the Magic Script editor and edit the object's script.

Fields that show an object ID can be displayed in one of two modes. The first, shown above, describes each object by showing its class name, the object's name, if it has one, and the instance definition ID. This information is useful for high-level debugging and general exploration.

By tapping the $ in the title bar, you'll get the display shown below. In this mode, the display shows the object ID for each object. The high bit of a real object ID is always set, causing its first digit to be 8 or greater. Object IDs are especially useful for low-level debugging. Touch the $ again to switch between displaying instance definition IDs and object IDs.

If you option-tap the $, you'll see the name of the class the defines each field prefixed to the field name, revealing the inheritance chain of the object.

You can move the Inspector around on the screen by holding down the option key while you press on it anywhere and drag it, or by dragging the Inspector's title bar, with or without the option key.

You can drop coupons into the Inspector to change its appearance, including border, text style, color, and shadow coupons.

When you're done with the Inspector, you can get rid of it by tapping its close box in the top-left corner or by typing Command-I again.

Advanced Inspector Features

You can use text coupons, the option key, and other techniques to get the Inspector to display objects without having to find or touch them.

To inspect this...	Do this...	Example	Notes
any indexical	drop text coupon		Works with parentheses too; use double braces for package indexicals.
any flat indexical	drop text coupon
any object if you know its object ID	drop text coupon
any object if you know its name	drop text coupon		More than one object may have the same name.
system object, including	hold option key and tap X
system root list	in title bar
any class object	inspect any object of that class, then tap Object ID		Gratuitous note

Note that more than one object may have the same name, so dropping a coupon with an object name may not display the object you were expecting.

Dumping Single Objects

As you create your packages, working back and forth between MPW and Magic Cap Simulator, you may sometimes want to convert just a few objects to text rather than dumping all objects to text. While you're running Magic Cap Simulator, you can convert any object to its text representation (in ObjectMaker syntax) by displaying the object in the Inspector, then typing Command-H on the Macintosh keyboard or choosing Dump Inspector Target from the Examine menu.

When you dump an object this way, the text representation is written to an file called Log, located in the same folder as Magic Cap Simulator (the SystemSoftware folder, unless you've moved it). You can dump several objects by repeatedly aiming the Inspector, then typing Command-H. You can then use the Echo Log command in the Utils menu in MPW to see the dumped objects.

The dumped objects use object IDs. In order to use them in instance definition files, you must convert the object IDs to instance definition IDs. To perform this conversion, copy and paste the dumped objects from the log file to the instance definition file, then choose the Convert Object IDs to Instance IDs item from the Utils menu.

You can also use Command-option-H or the Dump Inspector Target Deep to dump the inspected object and all objects that it's related to, such as subviews, targets, object lists, and other objects referred to by fields. This feature, called deep dumping, is useful if you want to take an object and the objects that support it and move them to another package. Deep dumping dumps the same objects that would be copied if the object were copied; that is, it doesn't dump any fields marked noCopy in the class definition file.

If you hold down the shift key while you dump an object, a copy of the text of the dumped object is placed on the Macintosh clipboard. You can then paste this copy into an MPW file instead of using the Echo Log command.

Magic Cap provides assertions, a way you can verify runtime assumptions in your code. You can use assertions to make sure that a particular object is not nil, a value is within a specified range, one value is less than another, or perform any other test. Because assertions require a debug version of Magic Cap, they work only with Magic Cap Simulator and are ignored on communicators.

Assertions are implemented with the Assert macro. Here is the syntax for assertions:

/*  Evaluate condition; if false, break into debugger */
Assert(condition) 

Here are some examples of assertions:

 
/* Make sure sound is not nil before fooling around with it
*/
Assert(Sound(self) != nilObject);

/* Ensure that an object is a member of a particular class
*/
Assert(Implements(oldObject, Coupon_));

/* Make sure value is in range */ 
Assert(spoonCount < 1000);

/* See if cached value is still good */ 
Assert(EqualBox(border, &cached)); 

Because these macros require a debug version of Magic Cap, they work only with Magic Cap Simulator and are ignored on communicators. For extra debugging fun, the macros work differently depending on whether the Macintosh caps lock key is down when they execute. In general, they cause more fuss if caps lock is down.

The following table describes the debugging macros and their actions:

Macro	With caps lock off does...	With caps lock on does...
Whisper((message))	none	Break into debugger with message; also write message to log
QuickWhisper((message))	none	Break into debugger with message
Log((message))	Write message to log	Break into debugger with message; also write message to log
DebugMessage((message))	Write message to message window and to log	Break into debugger with message; also write message to log
Complain((message))	Break into debugger with message; also write message to log	Break into debugger with message; also write message to log

Wherever functions refer to (message), the message can be any sprintf parameter list, as in the following example:

 
Log(("the number %d is too small", number));