metrowerks magic cap utilities manual

8/13/2019 Metrowerks Magic Cap Utilities Manual

1/109

MetrowerksMagic Cap UtilitiesManual

Metrow

erksCodeWarriorTM

CD

Due to last-minute changes to CodeWarrior, some information in this manual

may be out of date. Please read all the Release Notes files that come with

CodeWarrior for the latest information.


2/109

Metrowerks CodeWarrior Copyright 1993-1995 by Metrowerks Inc. and its Licensors. Allrights reserved.

Documentation stored on the compact disc may be printed by licensee for personal use.Except for the foregoing, no part of this documentation may be reproduced or transmitted inany form by any means, electronic or mechanical, including photocopying, recording, or anyinformation storage and retrieval system, without permission in writing from Metrowerks Inc.

Metrowerks, the Metrowerks logo and Software at Work are registered trademarks ofMetrowerks Inc. CodeWarrior, PowerPlant, and PowerPlant Constructor are trademarks ofMetrowerks Inc.The General Magic logo, the Magic Cap logo, the Telescript logo, Magic Cap, Telescript, andthe rabbit-from-a-hat logo are trademarks of General Magic, and may be registered in certainjursidictions.All other trademarks or registered trademarks are the property of their respective owners.

ALL SOFTWARE AND DOCUMENTATION ON THE COMPACT DISC ARE SUBJECTTO THE LICENSE AGREEMENT IN THE CD BOOKLET.

Canada and International

Metrowerks Inc.1500 du College, suite 300St. Laurent, QCH4L 5G6 Canada

voice: (514) 747-5999fax: (514) 747-2822

U.S.A.

Metrowerks Inc.The Trimex Building, Route 11Mooers, NY 12958 USA

voice: (514) 747-5999fax: (514) 747-2822

World Wide Web site (Internet): http://www.metrowerks.com

Registration information (Internet): [email protected]

Technical support (Internet): [email protected]

Sales, marketing, & licensing (Internet): [email protected]

AppleLink: metrowerks

America OnLine: metrowerkseWorld: metrowerks


3/109

Table of Contents

Magic Cap Utilities Manual iii

Table of Contents

Introduction 9

About this manual 9

Magic Cap Simulator 11

Apple Menu 11About Magic Cap 11

File Menu 11Open Copy of Package 11Close Window 11Show/Hide Development Tools 11Dont Save Changes 11Quit 11

Edit Menu 12Undo 12Cut 12Copy 12Paste 12Clear 12Find 12Select All 12Capture Magic Cap Screen 12

Hardware Menu 13Power On/Power Off 13Force Warm Reset 13Choose Macintosh Modem 13Enable Macintosh Modem 13New Card in Simulated Slot 1 13Insert Card in Simulated Slot 1 13Eject Card from Simulated Slot 1 13New Card in Simulated Slot 2 13Insert Card in Simulated Slot 2 13Eject Card from Simulated Slot 2 14


4/109

Table of Contents

iv Magic Cap Utilities Manual

Connect/Disconnect Simulated Phone Line 14Simulate Incoming Call 14Connect/Disconnect Simulated Hardware Keyboard 14Start with 1 MB Additional RAM 14

Examine Menu 14Show/Hide Inspector 14Dump Inspector Target 14Dump Inspector Target Deep 14Dump Package 14Show/Hide Message Window 15Show/Hide Screen Buffer Window 15Show/Hide Drag Buffer Window 15Show/Hide Hit Cache Window 15Show/Hide Memory Window 15Can Move/Copy/Stretch Everything 15

Discipline Menu 15Validate Inspector Target 15Validate Package 15Validate System 16Validate System and Active Packages 16Faster Validates 16Find System References in Package 16Start/Stop Leak Checking 16

Enforce Allocation Rules 16Monitor Memory Management 16Require Card/Form Alignment 16Require Hit Cache Coherency 16Require Inherited Calls 16Require View Cache Coherency 17

Testing Menu 17Go To Testing Scene 17Execute Standard System Test 17Start/Stop Journaling 17Start/Stop Code Coverage 17

Present/Retract Sample Announcements 17Simulate Device Contrast 17Place Fried Egg in Name Bar 17Simulate Multiple Services 18


5/109

Table of Contents

Magic Cap Utilities Manual v

Fill Persistent Memory 18Return Persistent Memory to Normal 18Fill Transient Memory 18Return Transient Memory to Normal 18Send Package 18

Log Menu 18Construction Tools 19

Turning on Construction Mode 20Magic hat 21

Coupons 23Components 27Borders 29Text styles 30Shadows 32Extras 32Tool holder 34Authoring 34Debugging with Inspector 37

Magic Script 38Writing Scripts 39Handlers 47Statements 50

Inspector 55

Advanced Inspector Features 59Dumping Single Objects 61Assertions 61Macros for Debugging 62

Bowser Pro 65

How to Use Bowser Pro 65Find Menu 68

Find Inherited 68Find Class 68

Find Method 68Find Field 68Go To Next 68Go Back 68


6/109

Table of Contents

vi Magic Cap Utilities Manual

Parser Menu 69Parse More 69Reparse 69

Class Menu 69Hierarchical Classes 69Alphabetical Classes 69Ancestry of Class 69All Methods of Class 69All Fields of Class 70Implementors of Class 70Create Template 70Source File of Class 70Show Class Definition 70

Member Menu 70Implementations of 70Source File of Method 71Interface of Method 71Source File of Field 71

Known Bugs And Limitations 71

ObjectMaker 73

Terminology Overview 73ObjectMaker Syntax 75Class Definition File 76

Class Definition Syntax 77Inheritance 78Abstract Classes 79Mixin Classes 80Defining Fields 80Defining Attributes 83

Defining Operations 84Defining Globals 87Defining Simple Intrinsics 88

Overriding Methods 88Method Implementation 89Instance Definition File 89

Object Dumping 90


7/109

Table of Contents

Magic Cap Utilities Manual vii

Object Hierarchy 91Field Initialization Statements 92

Object Reference 93Indexical 93Operation Number 94Lightweight Objects 95Files 95long 96short 96byte 96Booleans 96Strings 96Fixed 97Hexadecimal Data 97Extra Data 97Pixels and Microns 97Dot 98Box 98

Index 99

Credits 109


8/109

Table of Contents

viii Magic Cap Utilities Manual


9/109

Magic Cap Utilities Manual 9

Introduction 1

About this manual

This manual describes the utility applications you use with MetrowerksCodeWarrior to develop software packages for Magic Cap.

Chapter 2, Magic Cap Simulator.This chapter describes how to useMagic Cap Simulator to test, debug, and customize Magic Cap softwareon your Macintosh computer. It also shows how to use Magic Script andhow to create and change user interface elements in your Magic Cappackage.

Chapter 3, Bowser Pro.This chapter describes how to use the MagicCap class browser application to view class definitions in the Magic Capsystem software and your own packages.

Chapter 4, ObjectMaker.This chapter describes the class and objectinstance definition language the CodeWarrior uses with the C languageto create Magic Cap packages.

For information on creating packages using CodeWarrior, see theCodeWarrior Users Guide, Creating Magic Cap Projects.

For information on debugging packages, see the CodeWarrior DebuggerManual, Debugging Magic Cap.

These chapter names may change.


10/109

Introduction

About this manual

10 Magic Cap Utilities Manual


11/109


Magic Cap Simulator 2

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

Apple Menu

About Magic Cap

Shows the information window for the desk.

File Menu

Open Copy of Package

Shows the Macintosh Standard File dialog and lists Magic Cap packages for

opening.

Close Window

Closes the front most window if its one of Magic Caps auxiliary windows.

Show/Hide Development Tools

Shows or hides the Examine, Discipline, Testing and Log menus.

Dont Save Changes

If checked, Magic Cap wont save changes when you quit.

Quit

Quits the Magic Cap application.


12/109

Magic Cap Simulator

Edit Menu


Edit Menu

Undo

Undoes the last action. This is always disabled in Magic Cap. Its here forMacintosh compatibility only.

Cut

If theres a text selection, deletes the selected text and places it on theMacintosh clipboard.

Copy

If theres a text selection, makes a copy of the selected text on the Macintoshclipboard.

Paste

Pastes the contents of the Macintosh clipboard into Magic Cap. This itemnow indicates the contents of the clipboard. You can paste Macintosh text,images, sounds, and fonts.

Clear

If theres a text selection, deletes the selected text.

Find

Same as touchingfind

button in the Magic lamp.

Select All

If theres a text selection or typing point, selects all the text in the object thathas the selection.

Capture Magic Cap Screen

Creates a disk file thats a bitmap of the Magic Cap screen. Use in Magic Cap

for screen shots for best results.


13/109

Magic Cap Simulator

Hardware Menu


Hardware Menu

Power On/Power Off

Simulates turning communicator on and off.

Force Warm Reset

Simulates pressing communicators reset button.

Choose Macintosh Modem

Selects a modem for Magic Cap Simulator to use as an emulated modem.

Enable Macintosh Modem

Allows Magic Cap to use a modem plugged into the Macintoshs modemconnector. After selecting this item you may need to quit and restart MagicCap before it will start using the modem. Note: not all Macintosh modemsare compatible with Magic Cap.

New Card in Simulated Slot 1

Simulates inserting a new RAM card in slot 1.

Insert Card in Simulated Slot 1

Shows Macintosh Standard File dialog and lists simulated RAM cards forinsertion in slot 1.

Eject Card from Simulated Slot 1

Ejects the simulated RAM card in slot 1.

New Card in Simulated Slot 2

Simulates inserting a new RAM card in slot 2.

Insert Card in Simulated Slot 2

Shows Macintosh Standard File dialog and lists simulated RAM cards forinsertion in slot 2.


14/109

Magic Cap Simulator

Examine Menu


Eject Card from Simulated Slot 2

Ejects the simulated RAM card in slot 2.

Connect/Disconnect Simulated Phone Line

Simulates connecting a telephone line. This item is used primarily for testingthe Phone line connected

window.

Simulate Incoming Call

Simulates an incoming telephone call.

Connect/Disconnect Simulated Hardware Keyboard

When a hardware keyboard is connected, the on-screen keyboard doesntappear automatically when Magic Cap expects you to type text.

Start with 1 MB Additional RAM

Simulate 2 MB main memory. After selecting this item you must quit andrestart Magic Cap.

Examine Menu

Show/Hide Inspector

Shows or hides the object inspector.

Dump Inspector Target

Writes text description of inspected object to the log file.

Dump Inspector Target Deep

Writes text description of inspected object and objects referred to by its fields(except noCopy fields) to the log file.

Dump Package

Writes text description of all objects in the current package to the log file.


15/109

Magic Cap Simulator

Discipline Menu


Show/Hide Message Window

Shows or hides a Macintosh window that displays debugging messages.

Show/Hide Screen Buffer Window

Shows or hides the window that Magic Cap draws into; Magic Cap thencopies the entire screen bitmap to the screen itself. This window is useful forrevealing inefficient or duplicated drawing.

Show/Hide Drag Buffer Window

Shows or hides the window that Magic Cap draws into directly when theuser slides an item on the screen.

Show/Hide Hit Cache Window

Shows or hides the window that displays Magic Caps hit cache graphically.This window is used internally by General Magic.

Show/Hide Memory Window

Shows or hides the window that displays Magic Cap memory graphically.This window is used internally by General Magic.

Can Move/Copy/Stretch Everything

Allow all viewables to be moved, copied, and stretched regardless of theirindividual flag settings.

Discipline Menu

Validate Inspector Target

Calls Validate method for the inspected object.

Validate Package

Calls Validate method for all objects in the current package.


16/109

Magic Cap Simulator

Discipline Menu


Validate System

Calls Validate method for all system objects.

Validate System and Active Packages

Calls Validate method for all system and package objects.

Faster Validates

{What does this do?}

Find System References in Package

Searches the current package and displays all package objects that refer to

system objects.

Find Indexical Candidates in Package

Searches the current package and displays all package objects that matchsystem indexicals.

Start/Stop Leak Checking

Enables/disables Magic Caps storage leak detector.

Enforce Allocation Rules

Enables various requirements for safe memory allocation.

Monitor Memory Management


Require Card/Form Alignment


Require Hit Cache Coherency


Require Inherited Calls

If this item is checked, Magic Cap executes a user break every time anoverridden method executes without calling its inherited implementation.


17/109

Magic Cap SimulatorTesting Menu


Require View Cache Coherency

Checks the Magic Cap view cache for consistency. This item is usedinternally by General Magic.

Testing Menu

Go To Testing Scene

Shows the Magic Cap testing scene. This scene and most of the items in thismenu are used internally by General Magic.

Execute Standard System Test

Performs the Magic Cap standard system test.

Start/Stop Journaling

Starts or stops recording a journal of Magic Cap actions which can bereplayed later.

Start/Stop Code Coverage

Starts or stops recording system code coverage.

Present/Retract Sample Announcements

Creates or removes several announcements to test the announcementcarousel.

Simulate Device Contrast

Simulates the grays used on personal communicator LCD screens. Youshould set your monitor to at least 16 grays to use this feature. If yourmonitor wont display 16 grays, you can simulate this feature by puttingcellophane tape over your eyes.

Place Fried Egg in Name Bar

Its a long story.


18/109

Magic Cap SimulatorLog Menu


Simulate Multiple Services

Simulates registering for multiple electronic mail services to test featuressuch as Collect from:window.

Fill Persistent Memory

Simulates filling up all persistent memory.

Return Persistent Memory to Normal

Ends simulation of full persistent memory.

Fill Transient Memory

Simulates filling up all transient memory.

Return Transient Memory to Normal

Ends simulation of full transient memory.

Send Package

Shows the Macintosh Standard File dialog and lists Magic Cap packages,then creates a new message and puts the package on the message.

Log MenuEach command in this menu enable or disables writing each kind of messageto the log file.

Log Communications

Log Communications Details

Log Copy Engine

Log CRC Computation

Log Datebook Alarms Log Encodings

Log Encoding Details


19/109

Magic Cap SimulatorConstruction Tools


Log Garbage Collection

Log Idles Log Memory

Log Moving

Log Packing

Log Redraws

Log Screen Captures

Log Search

Log Text Formatting

Construction ToolsThis chapter describes tools and techniques for working with objects inMagic Cap. These are called construction toolsbecause they involveassembling and modifying the raw materials supplied by classes and staticobjects. Building a Magic Cap package with CodeWarrior Magic/MPWinvolves spending part of your development time modifying objects in MagicCap itself.

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

Magic Cap offers users two basic operating modes. Most people will use thedefault normalmode in which the communicator behaves in the mannerdescribed by the user documentation. Magic Cap also provides constructionmode, which gives the user enhanced control over objects.

Construction mode may be used by two different kinds of people. A poweruser can use construction mode on a communicator to personalize theenvironment in ways not available in normal mode. In addition, a developer

can use construction mode as part of the design and testing cycle indeveloping packages for Magic Cap. This chapter is aimed at developers andprovides an introduction to the various tools available in construction mode.


20/109



When you make software packages, youll use the construction toolsdescribed here to build large parts of your software.

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

The sections that follow treat the four basic tools youll use to performconstruction 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 MagicCap Simulator, you should use the version on Magic Cap Simulator since ithas extra tools for developers.

First, change to construction mode by going to the control panel in thehallway. Touchgeneral to make the general control panel appear. Then touchconstruction mode so that its checked.

Figure 2.1 Turning on Construction Mode

Youll notice that the Stamper at the bottom of the screen immediatelychanges to the Magic hat. This important change is one of several that occurwhen construction mode is turned on.

Some of the changes youll see in construction mode include the following:

The Magic hat replaces the Stamper at the bottom of the screen. TheMagic hat is a combined catalog and storehouse of objects. In it youll findboxes, text fields, controls and lots of coupons for modifying viewableobjects on the screen. The Magic hat window also contains the originalcontents of the Stamper window.

The Tool holder at the bottom of the screen contains additionalconstruction tools.


21/109



The ability to write Magic Script is available only in construction mode. Ascript is a set of instructions for an object to follow at a certain time. MagicScript is the language in which these scripts are written. Magic Cap letsyou 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 thereasonable choices are for that spot in the script.

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

Magic hat

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

Figure 2.2 Magic Hat window


22/109



The Magic hat is arranged hierarchically into eight categories. If you touchon one of the category boxes Magic Cap will redraw its window to displaythat category. For example, the stamps category contains the contents of theoriginal Stamper. You can always make the Magic hat or the Stamper goaway by touching the xin its top right corner.

Touch on a category box to go down one level in the Magic hat and see theitems in that category. To go up one level, touch the pointing hand at the topright corner of the Magic hat. Touching Stamps displays the normalcollection of stamps from the Stamper. Touching another category displays abank of drawers containing objects of that category.

Figure 2.3 Other stamps

To dispense a stamp or other object from the Stamper or the Magic hat, touchthe object. and the Magic hat will make a copy of the object and then goaway, 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 acoupon to hold it until you do something with it.


23/109



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

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

Figure 2.4 Drawers organize objects into categories

Coupons

Coupons hold intangible attributes from the Magic hat for applying toviewable objects. For example, to change the color of an object you wouldselect the color in the Magic hat. This action will automatically put the colorin 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 onechange to a setting in a viewable object.


24/109



When you drag a coupon over another object, the object will highlight if itcan accept the coupon. If it doesnt highlight, the object cant do anythingwith the coupon. For example, you cant drop a border into a stamp, so thestamp doesnt highlight when you drag a border coupon over it.

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

Text Coupons

You can create a text coupon and drop it on any object that accept a textcoupona telecard, a notebook page or an address card. Sometimes when

youre using construction tools youll need to drop text coupons onto objectsto label them.

You can create a text coupon with the keyboard.

Heres how to make a text coupon: Hold down the option key and touch thekeyboard gadget at the bottom of the screen. The keyboard will appear witha 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 makea coupon.

Youll notice that when you make the coupon maker appear, the keyboard

also undergoes a slight change, the switch changes to a choice box. This givesyou access to the symbols and accents planes of the keyboard.

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

Stamps

As you look through Magic Cap and Magic Cap packages, youll see cardsdecorated with all sorts of small pictures: company logos, postage stamps,beasts, cacti, stylized skyscrapers. These pictures are called stamps. You canadd them to any card and position them anywhere you like.

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


25/109



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


26/109



Table 2.1 Kinds of stamps

Kind Description

general Thegeneraldrawer contains a selection of diversedecorative stamps, an animation, the sound-holdinglips stamp, and a sticky note.

office The stamps in the office drawer are designed formarking office messages and commercial transactions.

occasions The occasionsdrawer holds decorative stamps forassorted holidays and special events.

animations Magic Cap provides a selection of animated charactersthat you can use to decorate your cards. If you tinker an

animation with the Tinker tool described later in thischapter, you can control how fast it moves horizontallyand vertically and how rapidly the animations frameschange. You can also determine whether the animationshould turn when it hits the sides of its container.

local Scenes can have their own stamps. If they do, thesestamps will appear in the local drawer and the name ofthe local drawer will match that of the scene. Hallway isan example of a scene with its own stamps. Scenes inpackages can also have their own stamps.

faces The faces in thefacesdrawer are often useful whenyoure sending a message to someone and want toemphasize your mood visually.

symbols The symbolsdrawer contains common symbols youmight find useful for any message and for labelingpictures or maps you draw.

leisure The leisuredrawer includes stamps representingpopular diversions and pastimes.

songs Each song stamp contains a different tune. Place one ofthese stamps on a card, then touch the stamp to play.

misc. This drawer contains miscellaneous stamps.


27/109



Components

The components category contains a group of user-interface tools. These arethe main ingredients for building the parts of a package that people interactwith. These component objects have been developed to solve a variety ofuser-interface problems while maintaining a consistent set of userexpectations within the Magic Cap environment.

buttons

A button is an object that a user can touch to invoke some action in apackage. Buttons have two states: normal and highlighted. The highlightedstate is temporary and only lasts while the button is being touched. Afterthat, it returns to its normal state.

switches

A switch is a control with two positions. Change a switchs position bytapping it. You can change the sound it makes when its touched bydropping in a sound coupon. Switches can be collected into a group with theChooseOneBox class. In this case, they behave like a group of radio buttons.

choices

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

text

Text fields contain text and scribbles. Text has many characteristics that youcan set: typeface, size, style, and alignment. To edit the text in a text field, tapon the text field to get an insertion point, then touch the keyboard gadget toshow the keyboard, or type on the Macintosh keyboard. You can set thecharacteristics 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 drawnclipped 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 turnit on, tinker the text field with the Tinker tool and flip the can containswitchto the on position.


28/109



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

clocks

Clocks tell what time it is based on the time stored in the communicator.They come in several different shapes and sizes. Some are analog; others,digital. Many are both. Some clocks display the time zone.

boxes

Boxes are objects for organizing groups of other objects. They have a borderand are filled with a particular color. Theyre different from text fields in thatboxes are primarily organizational and are designed to hold heterogeneousgroups of graphical objects, not text.

shapes

Shapes are irregular objects that share some properties of boxes: they cancontain other objects and they have a border and a color. When they arestretched with the stretch tool, they maintain their shape while being scaledhorizontally or vertically.

icons

The icons drawer contains a group of icons used in Magic Cap. If you change

an icon by dropping an image coupon on a system icon, you can drop a newicon from the icons drawer to replace it.

Colors

You can change the color that fills an object by dropping a color coupon intoit. Most viewable objects accept color coupons. The color coupon category ofthe Magic hat also contains a Color box and a Color mixer, two objects quiteuseful for manipulating colors. Theyre not coupons but they use colorcoupons to work properly, which is why they are in the color couponcategory.


29/109



Sounds

A sound coupon specifies a digitized or synthesized sound. You can dropsound coupons into most viewable objects. The objects will play the specifiedsound when theyre tapped. To hear the sound in a sound coupon, tap thecoupon.

If you dont specify a sound, switches and buttons will play the touch soundwhen tapped.

Table 2.2 Kinds of sounds

Borders

Use a border coupon to change the style of an objects border. Use the nobordercoupon to remove the border from an object. Some objects that acceptborders are boxes, fields, the Inspector, and meters.

Kind Description

standard The standard drawer contains the sounds usedthroughout Magic Cap to keep the user aware of what

is happening. You can drop these coupons into anobject to change the sound that object makes whenactivated.

instruments The instrumentsdrawer contains coupons representingall the synthesized musical instruments that are part ofMagic Cap. These are the instruments used for makingMIDI songs.

songs The songs in the songs drawer use the instrumentsdescribed 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 aphone needs to make.

more The moredrawer contains extra sounds, including theever popular no sound coupon.


30/109



Table 2.3 Kinds of borders

Text styles

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

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

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

Table 2.4 Kinds of text styles

basic The basicborder drawer includes the no bordercoupon, which you drop on an object to rid it of anexisting border.

lines These are the simplest borders. They draw quicklyand are widely used in Magic Cap.

fancy These fancy frames might be used to set off anaustere minimalist sketch.

objects The book and clock frames in the objectsdrawer areuseful for books and clocks.

misc. The misc.drawer contains extra borders.

Kind Description

sign Sign is a basic sans-serif typeface. Many people find it isreadable on the screen even at small sizes.

book Book is a simple serif typeface. Many people find that theserifs on Book make the face look a little more personaland relaxed than the austere Sign. Magic Cap includestwo custom-drawn bold fonts of the Book face.

styles The stylesdrawer includes some sophisticated versions ofthe basic text styles.


31/109



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 Capsis used to fit labels in tight spaces.


32/109



Shadows

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

Extras

The extras drawer contains many different coupons that are useful forconstructing and adjusting package user interfaces.

misc.

hide

show contentsrotate left

rotate right

flip vertical

flip horizontal

bring to front

send to back

put in formpull from form

The misc.drawer contains

properties that control thegeometric properties of a viewableobject. Shapes, stamps, andanimations can be rotated in 90-degree increments. You can droporientation coupons into theseobjects to rotate or flip them. Theput in form coupon and the pullfrom form coupon work with theform objects in cards.


33/109



Table 2.5 Extra kinds of coupons

Kind Description

line styles Drop a line style coupon into anobject to change the appearance ofthe border thats drawn around it.

properties make moveable

make unmovable

make copiable

make uncopiable

make deletable

make undeletable

Many an object that you see can bemodified with the view couponsyou can find by tappingpropertiesin the Magic hat. You can use thesecoupons to change the behavior ofobjects.

shape types Shape type coupons let you changea shapes type among variousstyles, such as rectangle, circle,diamond, arrow. Shape typecoupons can only be dropped intoshape objects.

misc.

hide

show contentsrotate left

rotate right

flip vertical

flip horizontal

bring to front

send to back

put in formpull from form

The misc.drawer contains

properties that control thegeometric properties of a viewableobject. Shapes, stamps, andanimations can be rotated in 90-degree increments. You can droporientation coupons into theseobjects to rotate or flip them. Theput in form coupon and the pullfrom form coupon work with theform objects in cards.


34/109



Tool holder

In construction mode, the Tool holder contains two extra items in its choicebox. These represent tools that can change the layout of objects in a scene oraccess the Inspector. These tools only appear in the version of constructionmode available in Magic Cap Simulator.

Toolsare modes that you can turn on and off. When a tool is on, objects dosomething special when you touch them. Most of the time, you only need totouch objects to make them work. But in construction mode, you can copyand 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 thebottom of the Tools window is a choice box that lets you choose among thesets of tools. In construction mode, youll be able to use the authoringanddebuggingtools.

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

When you select a tool, the Tools window disappears and the Tool holdericon at the bottom of the screen changes to a tool indicator icon. This icon

represents the current toolthat will be applied to the next object you touch. Ifan object does not accept the tool, Magic Cap will play a sound to let youknow and let you choose another object. If you dont need a tool you havechosen, tap the tool indicator icon to dismiss it.

Authoring

The authoringtools control the layout of objects. You can move, copy andstretch object. In addition, you can change an objects attributes thatdetermine whether they can be moved, copied or stretched.

Figure 2.5 Move tool


35/109



To move an object, tap the move tool, then slide the object around on thescreen. Some objects can be moved simply by sliding them, without yourhaving to tap the move tool first. But most objects require that you tap themove tool to move them. Its always worth trying an object to see if you canmove it without the move tool. If you cant, try the move tool. If you stillcant move the object, you might need to turn its can moveswitch on. Use theTinker tool, described below, to tinker the object. Switch the appropriateswitch in the open Tinker window to can move. Close the Tinker window bytapping on the wide bar along its top. You should now be able to move theobject with the move tool.

When you move an object on the screen, its drawn with a shadow to showyou that its attached solidly to your finger but not to the screen.

Figure 2.6 Copy tool

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

You may have to set the can copyattribute with the Tinker tool mentionedbelow before using the copy tool.

Figure 2.7 Stretch tool

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

You may have to set the can stretchattribute with the Tinker tool mentionedbelow before using the stretch tool.

Figure 2.8 Tinker tool


36/109



The Tinker tool lets you work inside an object to examine or adjust itssettings. An objects settings are the qualities that affect its appearance andbehavior, such as its shape, the colors that its drawn with, how its labeled,and what happens when you touch it. You can change an objects qualities bydropping 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 toolicon appears in the bottom of the screen. When you tap another object, awindow will appear with information showing the settings and parts that areinside the object.

Figure 2.9 Tinker tool window

The switches on the right control a number of properties: whether the objectcan be moved, copied, or stretched, where and how its label is drawn relativeto the object being tinkered. The label chooser lets you select one of 15positions for the label by tapping the position you want. Theres also a datastring in the bottom right corner of the window that shows how many bytesof 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 ofthe open window and drop them on other objects. However, you cant dropcoupons into the Tinker window to change an object. Just drop the couponson the object itself to make the changes.


37/109



You can move the Tinker window around by grabbing its title bar, and youcan 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 theInspector. The Inspector provides information about objects in Magic Cap.

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

Heres how to use the Inspector from the Tool holder. In construction modedo 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:

Figure 2.10 Inspector tool


38/109



3. Tap on the Inspector tool so that it becomes the current tool. The Tool holdericon at the bottom of the screen will be replaced by the Inspector icon toindicate that it is the current tool.

4. Tap on some viewable object and the Inspector window will appear withinformation about that object.

Figure 2.11 Inspector window

For more information on using the Inspector, see the Inspector section laterin this book.

Magic Script

Scripts are instructions that let you tell objects how to behave. Scripts candetermine what buttons do when theyre touched, what meters display, andwhat happens when you flip switches.

Scripts are written in a simple language calledMagic Scriptwith aninteractive script editor that was designed to make scripting easy. UsingMagic Script is different than using other languages. At each stage of the


39/109



scripting process the Magic Script editor presents you with a series of optionsthat are valid at that point. You build a script by selecting among theseoptions. Along the way, the Magic Script editor helps you to find the correctMagic Script term for what you want to do so youll never make a syntaxerror!

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

Note: The Magic Script editor is part of Magic Cap Simulator and is aprogramming tool for developing Magic Cap packages. While Magic Script

itself is part of the Magic Cap runtime system and is reliable, the MagicScript editor is under development and can present some problems. Youshould only use Magic Script for simple tasks.

Writing Scripts

The following steps describe how to write a simple script. This example willdemonstrate the mechanics of script development with the Magic Scripteditor. We will use the HelloWorld sample package and write a script thattoggles 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 theconstruction mode switch in the control panels 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. Whenthe Tinker tool is the current tool at the bottom of the screen you are ready tobegin scripting an object.


40/109



4. Option-tap the object.

While holding down the option key find the object you want to script and tapit. A script editor window appears for the object whose script you want toedit. The script editor window appears with the name of the object and itsruntime object ID. If the object didnt have a script before, an empty scriptwindow appears.

Figure 2.12 Magic Script window

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 andthe Magic Script editor will insert a new statement into the script.


41/109



Figure 2.13 Inserting a Magic Script statement

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

6. Tap the word actionin the onstatement to present a series of choices.

When you choose an underlined word or phrase in a script a choice boxappears presenting a series of available options. The arrow at the bottom ofthe menu indicates more options to choose from.


42/109



Figure 2.14 Choosing an action

7. 7)Choose the word tapin the menu.

When you make a choice in a Magic Script statement menu the word orphrase is inserted into the corresponding statement in the script. The newstatement 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 itto 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 asimple template that you fill out with the Magic Script editor.


43/109



Figure 2.15 Inserting a new statement

9. 9)Tap new statementto display its menu.

The menu contains a list of different kinds of statements that a script canhave.

Figure 2.16 Choosing a statement


44/109



10. Tap operation in the statement menu.

The new statementphrase will be replaced by the operationstatement. Theoperation statement is also a place holder for a choice that you make. Sincethis will be a simple script we will choose a simple action to perform whenthe object is tapped.

Figure 2.17 Inserting an operation statement

11. Tap the word operation in the statement.

The operation statement provides you with a variety of operations you canrequest of the #RESPONDER object. The #RESPONDER is the object thatwill respond to the operation. In this case, the responder is the Greeter objectthat you are scripting. The script editor gets its list of operations from theresponder by determining which of the responders operations have the safeand common flags set. You can set the responder to object other than the oneyoure scripting by tapping #RESPONDER and then tapping the other object.


45/109



Figure 2.18 Choosing an operation

12. Tap the phrase get/set highlighted in the statement choice box.

Again the statement menu will disappear and the new statement will remainin the script editor window. By default theget/set highlightedstatementdisplays itsgetvariant.


46/109



Figure 2.19 After inserting an operation

13. Toggle the get word to set.

The script now contains three statements that represent a valid and evenuseful script. The single operation statement tells the responder to reset itshighlight color to the opposite of its current state when the object is tapped.


47/109



Figure 2.20 Changing get to set

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 andtoggling its color. When you tap on the Greeter its highlight color willchange. Tapping on it again will return it to its original state.

Thats all there is to writing a script with the Magic Script editor. The sectionsthat follow provide more details on the different features of Magic Script.

Handlers

A handleris a script statement that responds to a particular system event.Some events are the result of user actions; for example, when you tap anobject, a tapevent is sent to the object. Other events are generatedautomatically by the system. For example, the system sends idleevents to allobjects when nothing else is happening.


48/109



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 ahandler since this is how Magic Script should handlecertain events. All yourscript statements will be in handlers. You can set a handlers event type bytapping on the actionkeyword that appears after the onkeyword. The onstatement tells Magic Script when to execute the series of statements in thehandler.

When you select on from the new statement menu, youll get a handler thatlooks like this:

on action

end action

For many scripts, these are just what you want. An actionhandler performwhatever statements are in between the on actionand end actionhandler ends.

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


49/109



Table 2.6 Some handler events

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 downyour 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) towhich the object is set changesparticularlyuseful for objects that have to do with addressingor 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 touchingdelete 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 thescreen

action usually, when the object is touched

tap here generally, when the object is tapped

set shadow offset when the distance of the objects edge from itsshadow is changed

inspect when the inspector starts looking at the objectset 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


50/109



The list of events that appears when you touch actioncorresponds to theoperations specified in the classs definition file with the scriptablekeyword.You can use an advanced technique to create a script for any of an objectsoperations, not just scriptable ones. To do this, hold down the Macintoshoption key and touch the actionor other event name. You can then type thename of any operation defined by the class.

StatementsEach logical line of a script is called a statement. Some statements will wraponto more than one physical line in the script editor, but each acts like asingle line. When the Magic Cap communicator executes a script, it goesthrough the statements in order. When you want to add a line to a script, youcan drag a new statement out of the inkwell at the right side of the scripteditor window. Or you can tap the inkwell to get a new statement. When youtap the newly created statement, youll get a menu that lets you choose thekind 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, itlooks like a coupon.

Figure 2.21 New Statement Menu

set value when the value of the object is changed at all

set percent when the percent value of a Control object ischanged

set fraction when the fractional value of an object is changed.


51/109



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

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

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

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

Tap operationto see the operations that are valid for scripting. These areoperations that have the safe and common flags set in the objects classdefinition.

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

on

Selecting the on word from the new statement menu provides your scriptwith a new handler. Handlers are described above.


52/109



math

The mathstatement is Magic Scripts door into the realm of arithmeticoperations. When you choose mathfrom the new statement menu, youll geta statement that looks like this:

get object operator object

Tap on the word operatorto select the operation youd like to perform and thetwo words objectto set the values youd like to operate on.

You can also select textsuch as a numberand drag it into the objectwordsin the script statement.

if

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

ifit is nil object then

end if

You can make the otherwisego away by tapping on the first if. Change eitherof the words something to be specific containers by tapping on it and choosingthe container you want from the menu that appears. You can also drag textfrom a field into the word something in order to get other values.

You choose a comparison operator when you create an ifstatement. In thisversion of the software, these are the choices for comparison operators:

is

is not

#

is in

is not in

contains


53/109



repeat

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

You can specify five kinds of repeat conditions, listed in Table 2.7.

Table 2.7 Repeat conditions

The software defines a special object called the system object. It acceptsseveral global messages. One of these global messages is abort scripts, whichcauses runaway scripts to stop. Type Command-. (period) on the Macintoshkeyboard to abort running scripts.

The repeat capability is under construction in this version of the software.You can use the forms repeatforeverand repeatfor numbertimes to try outrepeatstatements. To get a number into a repeatfor numbertimes statement,drag a number from a field and drop it into the word number in the repeatstatement.

value

The value statement will put arbitrary text into the special container it or intoany new container you create. You create a container just by thinking up aname and entering it. As with any place that the word something appears in a

script, you can grab some text from a field and drop it into the wordsomething.

When you choose value from the new statement menu, youll see this in yourscript:

Condition Description

repeatforever executes until abort scripts message

repeatfor numbertimes repeat a specified number of times

repeat while something is

something

repeat while condition is true

repeat until something issomething

repeat until condition becomes true

repeat with container =number to number

use a loop variable. Tap on the word toand toggleit to down to, which will allow your repeatstatement to count down.


54/109



get object into it

You can tap onget to change the statement to:putCassiopeiainto it

If you tap on container, the only pre-made containeritwill suggest itself toyou. You can also create a text coupon with the keyboards label maker anddrag it into container to change its name. Text dragged here will create acontainer with that name. For example, drag The Heavens from a field intothe word containerin your put statement:

putCassiopeiainto The Heavens

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

comment

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

it

Theres a special container called itthat you can use when youre writingscripts. When a script statement usesget, the value that it gets goes into the

container it. For example, when the script statementget the time of dayisexecuted, the container itwill contain the time.

When you move a slider or change the value of a meter, itgets the newvalue. You can use itwithin the script of a slider or meter.

You can make other containers by dragging text coupons from thekeyboards label maker and dropping them into the word containerin aMagic Script statement.

Special Keyboard Feature

Sometimes youll need to enter information to a script with the keyboard. For

example, if a statement needs an object ID or an indexical, you can enterthese with the keyboard. To do this, hold down the option key and touch one


55/109

Magic Cap SimulatorInspector


of the under-bracketed words in a scriptan 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.

InspectorThe Inspector is a tool for interactively analyzing Magic Cap object. With ityou will point at objects and look at their contents. Magic Cap Simulator hasa menu named Examine with several items that work with the Inspector.

Table 2.8 Inspector commands

When the Inspector appears, it displays a list of the current hierarchy ofviewable objects, called the view list (see the figure above). To seeinformation about any object in the view list, tap it and the display willchange (as in Figure 2.22).

Menu Item Keyboard Equivalent Description

Show Inspector command-i Displays the Inspector window.

Hide Inspector Hides the Inspector window.

DumpInspector Target

command-h Dumps the text description ofthe object in the Inspector intothe log file

DumpInspectorTarget Deep

Dumps the text description ofthe object in the Inspectorandall the objects it containsintothe log file

Dump Package Dumps the text descriptions ofall the objects of a package intothe log file


56/109



Figure 2.22 Viewing an objects field values.

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


57/109



Figure 2.23 Viewing fields defined by superclasses

If the information youre looking at doesnt fit in the Inspector window, youcan scroll it (vertically only) by sliding the text, or you can use the stretch toolto enlarge the Inspectors window. You can also stretch the Inspector withoutgetting the stretch tool by simply dragging on its frame, an operation thatrequires precise pointing.

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

The Inspector provides five controls in its title bar that let you use additionalfeatures: O, X,


58/109



You can use the Inspector to begin tinkering with any object in the view list,including objects that you cant touch, like the screen object. To do this, tapthe O(for Open) in the Inspectors title bar while its displaying informationabout the object that you want to open. Option-tap the O to open the MagicScript editor and edit the objects 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 objectsname, if it has one, and the instance definition ID. This information is usefulfor high-level debugging and general exploration.

By tapping the $in the title bar, youll get the display shown below. In thismode, the display shows the object ID for each object. The high bit of a realobject ID is always set, causing its first digit to be 8 or greater. Object IDs areespecially useful for low-level debugging. Touch the $again to switchbetween displaying instance definition IDs and object IDs.

Figure 2.24 Viewing object IDs

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


59/109



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

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

When youre done with the Inspector, you can get rid of it by tapping itsclose box in the top-left corner or by typing -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.

system object,including system rootlist

hold option key and tapXin title bar

any class object inspect any object of thatclass, then tap Object ID


60/109



Table 2.9 Advanced Inspector features

{What does Expert-Tap on ? do? Looks like it searches for a referenceto the target, but it always seems to find the ref map.

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

To inspect... Do this. Example

any indexical(Works withparentheses too; usedouble braces forpackage indexicals.)

drop text coupon

any flat indexical drop text coupon

any object if you know

its object ID

drop text coupon

any object if you knowits name

drop text coupon

More than one objectmay have the samename.

system object,including system rootlist

hold option key and tapXin title bar

any class object inspect any object of thatclass, then tap Object ID


61/109

Magic Cap SimulatorAssertions


Dumping Single Objects

As you create your packages, working back and forth between theCodeWarrior environment and Magic Cap Simulator, you may sometimeswant to convert just a few objects to text rather than dumping all objects totext. While youre running Magic Cap Simulator, you can convert any objectto its text representation (in ObjectMaker syntax) by displaying the object inthe Inspector, then typing -H on the Macintosh keyboard or choosing DumpInspector Target from the Examine menu.

When you dump an object this way, the text representation is written to anfile called Log, located in the same folder as Magic Cap Simulator (theSystemSoftware folder, unless youve moved it). You can dump several

objects by repeatedly aiming the Inspector, then typing -H.The dumped objects use object IDs. In order to use them in instancedefinition files, you must convert the object IDs to instance definition IDs. Toperform this conversion, copy and paste the dumped objects from the log fileto the instance definition file, then choose the Convert Object IDs to InstanceIDs item from the Utils menu.

You can also use -option-H or the Dump Inspector Target Deep to dump theinspected object and all objects that its related to, such as subviews, targets,object lists, and other objects referred to by fields. This feature, called deepdumping, 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 sameobjects that would be copied if the object were copied; that is, it doesntdump 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 textof the dumped object is placed on the Macintosh clipboard. You can thenpaste this copy into a source code file instead of using the Echo Logcommand.

AssertionsMagic Cap provides assertions, a way you can verify runtime assumptionsin your code. You can use assertions to make sure that a particular object isnot nil, a value is within a specified range, one value is less than another, or


62/109

Magic Cap SimulatorMacros for Debugging


perform any other test. Because assertions require a debug version of MagicCap, they work only with Magic Cap Simulator and are ignored oncommunicators.

Assertions are implemented with the Assertmacro. Here is the syntax forassertions:

/*

* Evaluate condition; if false, break into debugger

*/

Assert(condition)

Here are some examples of assertions:

/*

* Make sure sound is not nil before fooling aroundwith 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));

Macros for DebuggingMagic Cap provides several macros you can use for debugging, some ofwhich work with the debugger and others that perform actions in Magic Capitself. Magic Cap Simulator maintains a log file and a message window,


63/109



along with macros you can call to write messages to the log and to thewindow. In addition, you can call macros that cause a user break intoMacsBug.

Because these macros require a debug version of Magic Cap, they work onlywith Magic Cap Simulator and are ignored on communicators. For extradebugging fun, the macros work differently depending on whether theMacintosh caps lockkey is down when they execute. In general, they causemore fuss if caps lockis down.

Table 2.10describes the debugging macros and their actions.

Table 2.10 Debugging Macros

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

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

Macro Action if caps lockoff Action if caps lockon

Whisper((message)) none Break into debuggerwith message; also writemessage to log

QuickWhisper((messa

ge))

none Break into debuggerwith message

Log((message)) Write message to log Break into debuggerwith message; also writemessage to log

DebugMessage((messa

ge))

Write message tomessage window and

to log

Break into debuggerwith message; also write

message to logComplain((message)) Break into debugger

with message; alsowrite message to log

Break into debuggerwith message; also writemessage to log


64/109




65/109


Bowser Pro 3Bowser Pro is a class and source code browser designed exclusively for usewith Magic Cap. Bowser Pro borrows technology from ObjectMaker to parsea set of class definition and C source files and presents a browsing windowof the classes, methods and fields defined there.

Bowser Pro has a preprocessing phase during which it reads in and parsesthe definitions for a group of classes and saves them in a browsingdocument. Most of the time youll use Bowser Pro to browse the classes inyour package together with Magic Caps class definitions. To do that youll

develop a browsing documents for the Magic Cap classes and for yourpackages classes. The next section describes the mechanics of creating abrowsing document.

How to Use Bowser ProHere are five steps for using Bowser Pro.

1. Start the Bowser Pro application.

2. Select the folder containing the source code you want to browse.

In Figure 3.1, the folder GM is about to be selected.


66/109

Bowser ProHow to Use Bowser Pro


Figure 3.1 Choosing a folder to browse

3. Wait.

Parsing Magic Cap classes may take several minutes.

4. Save the resulting document.

This is another area where patience is necessary. Saving a large browsingdocument may take several minutes.

5. Try clicking on the various lists to see what happens.

Figure 3.2shows a picture of Bowser Pro in action, with annotations thatdescribe the major features of Bowser Pro.


67/109

Bowser ProHow to Use Bowser Pro


Figure 3.2 The Browse Window

You can use the keyboard to select classes, methods, and fields. Type tab tomove from one pane to the next. When the class, method, or field pane is

selected, you can type alphabetical characters to make a selection. You canalso use the up arrow and down arrow keys to move through the selectedpane.

Shows the list of classesClick on a class to see itsmethods and fields displayed

in the text plane;option-click to see its classdefinition displayed;command-click to open

a new window that displaysthe class definition.

The Class List The Info PaneDisplays informationabout the currentlyselected class. Click on

a class to see its definitiondisplayed.

The Text PaneDisplays the source codeof the selected method,or the class definitionif the source code is not

available.

The Method PaneDisplays a list of methodsdefined by the class thatis selected in the class list.Click on a method to see its

source displayed in the textpane. Command-click on amethod to have its sourcecode displayed in a new

window.

The Ancestry DisplayThe data displayedin the ancestry display depends onwhich sub-window has been selected. If

the Class Window has been selected,the Value Liine displays the classinheritance chain. If the Method Panehas been selected, the relevant line in

the class definition is displayed.

The Field PaneDisplays informationabout the fields of thecurrently selected class.


68/109

Bowser ProFind Menu


Find MenuThe search is always case sensitive and does not wrap around when itreaches the end of the text in the text pane.

Find Inherited

Show the current method as implemented by the current classs superclass. Ifthe method has no inherited implementation, Bowser Pro beeps.

Find Class

This item prompts for the name of a class, then selects and displays thatclass. This is especially useful when viewing classes hierarchically.

Find Method

This item prompts for the name of a method, then selects and displays thefirst implementation of that method, searching all classes in alphabeticalorder.

Find Field

This item prompts for the name of a field, then selects and displays the firstimplementation of that field, searching all classes in alphabetical order.

Go To Next

This item finds the next class, if any, that implements a method with thesame name as the selected method. Classes are searched in alphabetical order.

Go Back

Use this item to see the class that was displayed immediately before thecurrently displayed class.


69/109

Bowser ProParser Menu


Parser Menu

Parse More

Use this item to begin parsing to create another Bowser Pro document.

Reparse

If any source files change after creating the browse document, use this itemto update the browse document without having to reparse everything.

Class Menu

Hierarchical Classes

This item displays classes according to their hierarchy.

Alphabetical Classes

This item displays classes according in alphabetical order.

Ancestry of Class

This item displays all the superclasses (except mixins) of the selected class.This list appears in the pane just above the text pane.

All Methods of Class

This item opens a new window that lists all the methods available in theselected class, including inherited methods. Select a method in this new

window to see its source, if available.


70/109

Bowser ProMember Menu


All Fields of Class

This item opens a new window that lists all the fields available in theselected class, including inherited fields. Select a field in this new window tosee its declaration.

Implementors of Class

This item opens a new window that lists all classes that implement theselected class anywhere in their ancestry.

Create Template

Use this item to create a instance definition for an Objects.Def file. A newwindow will open with a template for an object of the selected class.

Source File of Class

This item displays the name of the class definition file that contains thedefinition for the selected class. If you hold down the shift key whileselecting this menu item, the class definition file will be opened in the MPWShell.

Show Class Definition

If this item is checked, the text pane will automatically show the definition ofa newly selected class.

Member Menu

Implementations ofThis item opens a new window that lists all the implementations of theselected method. Select a method in this new window to see its source, ifavailable.


71/109

Bowser ProKnown Bugs And Limitations


Source File of Method

This item displays the name of the source file that contains the code for theselected method. If you hold down the shift key while selecting this item, thesource file will be opened in the MPW Shell.

Will this Shift key shortcut work for CodeWarrior too? I assume it could bedone by sending the appropriate AppleEvent to the CW IDE.

Interface of Method

This item shows the interface for the selected method, as defined in the classdefinition file.

Source File of Field

This item displays the name of the class definition file that contains thedefinition for the selected field. If you hold down the shift key whileselecting this item, the class definition file will be opened in the MPW Shell.Totally cool!

Known Bugs And Limitations

The About box is still lame.

Printing prints only the class hierarchy.

Opening a selected class in an external editor is only supported for theMPW shell, and only if it is running.


72/109

Bowser ProKnown Bugs And Limitations



73/109


ObjectMaker 4Is ObjectMaker still a tool? Or, to the user, is it an object definition language?CodeWarrior includes an essential tool called ObjectMaker that compilesobjects from text descriptions. Magic Cap software packages are created fromthese objects as well as from C source code.

ObjectMaker works with two kinds of files. A class definitionfile containsdescriptions of class templates. These templates can include methoddefinitions that are implemented in separate C files. An instance definitionfiledescribes the static objects used by a package. This chapter describes the

syntax of class definition and instance definition files.From a programmers point of view, ObjectMaker contains most of what isobject-oriented about Magic Cap development using CodeWarrior. Theplanning and design process usually involves building a Magic Cap packagefrom existing classes with ObjectMaker. The actual C programming youll dooccurs when you have to write new classes or override the methods of anexisting class.

Using or modifying existing classes has several benefits. It savesimplementation effort and it conserves memory resources since the MagicCap classes are stored in system ROM and special-purpose classes you

develop must be stored in RAM.

Terminology OverviewIn object-oriented programming systems, an object is a combination of datastructures and procedures that act on that data. A classis a description of thedata and behavior of a class of objects. It represents an agreement between adeveloper and a development system about how the object will behave whenit is called upon to perform some action. Magic Cap classes are defined in a

class definition file.Magic Cap further distinguishes between two parts of a class definition: whata class can do and howit accomplishes this. A classs interfacerepresents thefirst part. It describes the kind of data an instance of a class can hold and the


74/109

ObjectMakerTerminology Overview


actions it can perform. It is like a group of data structure declarations andfunction prototypes in a structured programming environment. An operationrefers to the part of a classs interface that describes the actions it performs. Aspecial case of an operation is an attributewhich describes how to manipulatethe data stored by an object. Attributes provide access to fields.

For a given class interface, a programmer can supply an implementationof aclasss data storage structures and the code that performs its work or, insome cases, the programmer can indicate that these should be supplied byother classes. This implementation is divided intofieldsthat store the data, orinstance variables, of a Magic Cap object and methodsthat comprise the codethat manipulates the data in a field or performs some action in an object.Fields and methods can take different forms to give a developer flexibility in

software design.Figure 4.1presents this terminology in a grid.

Figure 4.1 Parts of object oriented programming

Classes can be defined in terms of other classes through a process calledinheritance. A group of related classes derived from a common source iscalled a class hierarchy.

A class is a static definition and by itself it doesnt do anything. At runtime,Magic Cap can create an instance of a class called an objectthat performs theactions advertised by the class. In Magic Cap, we often think of objects in two

places. The instance definition filecontains a textual representation of the staticobjects that ObjectMaker creates for a package. At runtime a package maycreate dynamicobjects as well. For example, whenever the user touches newin the Notebook, a new notebook page is created dynamically.

operations

methods

attributes

fieldsimplementation

interface

data procedures


75/109

ObjectMakerObjectMaker Syntax


A Magic Cap package is a collection of objects that are organized into anobject hierarchy. This hierarchy is different from but related to the classhierarchy used to organize class definitions. The object hierarchy is describedlater in this chapter.

ObjectMaker SyntaxObjectMaker is a simple language with a small set of Pascal-like syntax rules.Since

metrowerks magic cap utilities manual

Documents