Download - 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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
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/13/2019 Metrowerks Magic Cap Utilities Manual
8/109
Table of Contents
viii Magic Cap Utilities Manual
-
8/13/2019 Metrowerks 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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
10/109
Introduction
About this manual
10 Magic Cap Utilities Manual
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
11/109
Magic Cap Utilities Manual 11
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
12/109
Magic Cap Simulator
Edit Menu
12 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
13/109
Magic Cap Simulator
Hardware Menu
Magic Cap Utilities Manual 13
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
14/109
Magic Cap Simulator
Examine Menu
14 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
15/109
Magic Cap Simulator
Discipline Menu
Magic Cap Utilities Manual 15
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
16/109
Magic Cap Simulator
Discipline Menu
16 Magic Cap Utilities Manual
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
{What does this do?}
Require Card/Form Alignment
{What does this do?}
Require Hit Cache Coherency
{What does this do?}
Require Inherited Calls
If this item is checked, Magic Cap executes a user break every time anoverridden method executes without calling its inherited implementation.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
17/109
Magic Cap SimulatorTesting Menu
Magic Cap Utilities Manual 17
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
18/109
Magic Cap SimulatorLog Menu
18 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
19/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 19
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
20/109
Magic Cap SimulatorConstruction Tools
20 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
21/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 21
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
22/109
Magic Cap SimulatorConstruction Tools
22 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
23/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 23
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
24/109
Magic Cap SimulatorConstruction Tools
24 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
25/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 25
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
26/109
Magic Cap SimulatorConstruction Tools
26 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
27/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 27
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
28/109
Magic Cap SimulatorConstruction Tools
28 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
29/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 29
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
30/109
Magic Cap SimulatorConstruction Tools
30 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
31/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 31
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
32/109
Magic Cap SimulatorConstruction Tools
32 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
33/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 33
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
34/109
Magic Cap SimulatorConstruction Tools
34 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
35/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 35
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
36/109
Magic Cap SimulatorConstruction Tools
36 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
37/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 37
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
38/109
Magic Cap SimulatorConstruction Tools
38 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
39/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 39
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
40/109
Magic Cap SimulatorConstruction Tools
40 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
41/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 41
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
42/109
Magic Cap SimulatorConstruction Tools
42 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
43/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 43
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
44/109
Magic Cap SimulatorConstruction Tools
44 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
45/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 45
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
46/109
Magic Cap SimulatorConstruction Tools
46 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
47/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 47
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
48/109
Magic Cap SimulatorConstruction Tools
48 Magic Cap Utilities Manual
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:
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
49/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 49
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
50/109
Magic Cap SimulatorConstruction Tools
50 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
51/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 51
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
52/109
Magic Cap SimulatorConstruction Tools
52 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
53/109
Magic Cap SimulatorConstruction Tools
Magic Cap Utilities Manual 53
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
54/109
Magic Cap SimulatorConstruction Tools
54 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
55/109
Magic Cap SimulatorInspector
Magic Cap Utilities Manual 55
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
56/109
Magic Cap SimulatorInspector
56 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
57/109
Magic Cap SimulatorInspector
Magic Cap Utilities Manual 57
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,
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
58/109
Magic Cap SimulatorInspector
58 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
59/109
Magic Cap SimulatorInspector
Magic Cap Utilities Manual 59
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
60/109
Magic Cap SimulatorInspector
60 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
61/109
Magic Cap SimulatorAssertions
Magic Cap Utilities Manual 61
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
62/109
Magic Cap SimulatorMacros for Debugging
62 Magic Cap Utilities Manual
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,
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
63/109
Magic Cap SimulatorMacros for Debugging
Magic Cap Utilities Manual 63
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
64/109
Magic Cap SimulatorMacros for Debugging
64 Magic Cap Utilities Manual
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
65/109
Magic Cap Utilities Manual 65
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
66/109
Bowser ProHow to Use Bowser Pro
66 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
67/109
Bowser ProHow to Use Bowser Pro
Magic Cap Utilities Manual 67
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
68/109
Bowser ProFind Menu
68 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
69/109
Bowser ProParser Menu
Magic Cap Utilities Manual 69
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
70/109
Bowser ProMember Menu
70 Magic Cap Utilities Manual
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
71/109
Bowser ProKnown Bugs And Limitations
Magic Cap Utilities Manual 71
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.
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
72/109
Bowser ProKnown Bugs And Limitations
72 Magic Cap Utilities Manual
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
73/109
Magic Cap Utilities Manual 73
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
74/109
ObjectMakerTerminology Overview
74 Magic Cap Utilities Manual
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
-
8/13/2019 Metrowerks Magic Cap Utilities Manual
75/109
ObjectMakerObjectMaker Syntax
Magic Cap Utilities Manual 75
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