You are on page 1of 109

Metrowerks CodeWarrior CD

Metrowerks Magic Cap Utilities Manual

TM

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.

Metrowerks CodeWarrior Copyright ©1993-1995 by Metrowerks Inc. and its Licensors. All rights 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 in any form by any means, electronic or mechanical, including photocopying, recording, or any information storage and retrieval system, without permission in writing from Metrowerks Inc. Metrowerks, the Metrowerks logo and Software at Work are registered trademarks of Metrowerks Inc. CodeWarrior, PowerPlant, and PowerPlant Constructor are trademarks of Metrowerks Inc. The General Magic logo, the Magic Cap logo, the Telescript logo, Magic Cap, Telescript, and the rabbit-from-a-hat logo are trademarks of General Magic, and may be registered in certain jursidictions. All other trademarks or registered trademarks are the property of their respective owners. ALL SOFTWARE AND DOCUMENTATION ON THE COMPACT DISC ARE SUBJECT TO THE LICENSE AGREEMENT IN THE CD BOOKLET. Canada and International Metrowerks Inc. 1500 du College, suite 300 St. Laurent, QC H4L 5G6 Canada voice: (514) 747-5999 fax: (514) 747-2822 U.S.A. Metrowerks Inc. The Trimex Building, Route 11 Mooers, NY 12958 USA voice: (514) 747-5999 fax: (514) 747-2822

Registration information (Internet): Sales, marketing, & licensing (Internet): America OnLine: eWorld: AppleLink: Technical support (Internet):

World Wide Web site (Internet):

support@metrowerks.com metrowerks sales@metrowerks.com

register@metrowerks.ca

http://www.metrowerks.com

metrowerks metrowerks

Table of Co n t en t s

Table of Contents
Introduction 9
About this manual 9 Apple Menu 11 About Magic Cap 11 File Menu 11 Open Copy of Package 11 Close Window 11 Show/Hide Development Tools 11 Don’t Save Changes 11 Quit 11 Edit Menu 12 Undo 12 Cut 12 Copy 12 Paste 12 Clear 12 Find 12 Select All 12 Capture Magic Cap Screen 12 Hardware Menu 13 Power On/Power Off 13 Force Warm Reset 13 Choose Macintosh Modem 13 Enable Macintosh Modem 13 New Card in Simulated Slot 1 13 Insert Card in Simulated Slot 1 13 Eject Card from Simulated Slot 1 13 New Card in Simulated Slot 2 13 Insert Card in Simulated Slot 2 13 Eject Card from Simulated Slot 2 14

Magic Cap Simulator 11

Magic Cap Utilities Manual iii

Ta b l e o f C on ten ts

Connect/Disconnect Simulated Phone Line 14 Simulate Incoming Call 14 Connect/Disconnect Simulated Hardware Keyboard 14 Start with 1 MB Additional RAM 14 Examine Menu 14 Show/Hide Inspector 14 Dump Inspector Target 14 Dump Inspector Target Deep 14 Dump Package 14 Show/Hide Message Window 15 Show/Hide Screen Buffer Window 15 Show/Hide Drag Buffer Window 15 Show/Hide Hit Cache Window 15 Show/Hide Memory Window 15 Can Move/Copy/Stretch Everything 15 Discipline Menu 15 Validate Inspector Target 15 Validate Package 15 Validate System 16 Validate System and Active Packages 16 Faster Validates 16 Find System References in Package 16 Start/Stop Leak Checking 16 Enforce Allocation Rules 16 Monitor Memory Management 16 Require Card/Form Alignment 16 Require Hit Cache Coherency 16 Require Inherited Calls 16 Require View Cache Coherency 17 Testing Menu 17 Go To Testing Scene 17 Execute Standard System Test 17 Start/Stop Journaling 17 Start/Stop Code Coverage 17 Present/Retract Sample Announcements 17 Simulate Device Contrast 17 Place Fried Egg in Name Bar 17 Simulate Multiple Services 18

iv Magic Cap Utilities Manual

Table of Co n t en t s

Fill Persistent Memory 18 Return Persistent Memory to Normal 18 Fill Transient Memory 18 Return Transient Memory to Normal 18 Send Package 18 Log Menu 18 Construction Tools 19 Turning on Construction Mode 20 Magic hat 21 Coupons 23 Components 27 Borders 29 Text styles 30 Shadows 32 Extras 32 Tool holder 34 Authoring 34 Debugging with Inspector 37 Magic Script 38 Writing Scripts 39 Handlers 47 Statements 50 Inspector 55 Advanced Inspector Features 59 Dumping Single Objects 61 Assertions 61 Macros for Debugging 62

Bowser Pro 65

How to Use Bowser Pro 65 Find Menu 68 Find Inherited 68 Find Class 68 Find Method 68 Find Field 68 Go To Next 68 Go Back 68

Magic Cap Utilities Manual v

Ta b l e o f C on ten ts

Parser Menu 69 Parse More 69 Reparse 69 Class Menu 69 Hierarchical Classes 69 Alphabetical Classes 69 Ancestry of Class 69 All Methods of Class 69 All Fields of Class 70 Implementors of Class 70 Create Template 70 Source File of Class 70 Show Class Definition 70 Member Menu 70 Implementations of 70 Source File of Method 71 Interface of Method 71 Source File of Field 71 Known Bugs And Limitations 71

ObjectMaker 73

Terminology Overview 73 ObjectMaker Syntax 75 Class Definition File 76 Class Definition Syntax 77 Inheritance 78 Abstract Classes 79 Mixin Classes 80 Defining Fields 80 Defining Attributes 83 Defining Operations 84 Defining Globals 87 Defining Simple Intrinsics 88 Overriding Methods 88 Method Implementation 89 Instance Definition File 89 Object Dumping 90

vi Magic Cap Utilities Manual

Table of Co n t en t s

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

Index 99

Credits 109

Magic Cap Utilities Manual vii

Ta b l e o f C on ten ts

viii Magic Cap Utilities Manual

Introduction
About this manual
This manual describes the utility applications you use with Metrowerks CodeWarrior to develop software packages for Magic Cap.

1

• Chapter 2, “Magic Cap Simulator.”This chapter describes how to use Magic Cap Simulator to test, debug, and customize Magic Cap software on your Macintosh computer. It also shows how to use Magic Script and how to create and change user interface elements in your Magic Cap package. • Chapter 3, “Bowser Pro.”This chapter describes how to use the Magic Cap class browser application to view class definitions in the Magic Cap system software and your own packages. • Chapter 4, “ObjectMaker.”This chapter describes the class and object instance definition language the CodeWarrior uses with the C language to create Magic Cap packages. • For information on creating packages using CodeWarrior, see the CodeWarrior User’s Guide, “Creating Magic Cap Projects.” These chapter names may change.

• For information on debugging packages, see the CodeWarrior Debugger Manual, “Debugging Magic Cap.”

Magic Cap Utilities Manual 9

I n t ro d u c t i on About this manual

10 Magic Cap Utilities Manual

Magic Cap Simulator

2

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

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 it’s one of Magic Cap’s auxiliary windows. Show/Hide Development Tools Shows or hides the Examine, Discipline, Testing and Log menus. Don’t Save Changes If checked, Magic Cap won’t save changes when you quit. Quit Quits the Magic Cap application.

Magic Cap Utilities Manual 11

M a g i c C a p S imu la to r Edit Menu

Edit Menu
Undo Undoes the last action. This is always disabled in Magic Cap. It’s here for Macintosh compatibility only. Cut If there’s a text selection, deletes the selected text and places it on the Macintosh clipboard. Copy If there’s a text selection, makes a copy of the selected text on the Macintosh clipboard. Paste Pastes the contents of the Macintosh clipboard into Magic Cap. This item now indicates the contents of the clipboard. You can paste Macintosh text, images, sounds, and fonts. Clear If there’s a text selection, deletes the selected text. Find Same as touching find button in the Magic lamp. Select All If there’s a text selection or typing point, selects all the text in the object that has the selection. Capture Magic Cap Screen Creates a disk file that’s a bitmap of the Magic Cap screen. Use in Magic Cap for screen shots for best results.

12 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Hardware Menu

Hardware Menu
Power On/Power Off Simulates turning communicator on and off. Force Warm Reset Simulates pressing communicator’s 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 Macintosh’s modem connector. After selecting this item you may need to quit and restart Magic Cap before it will start using the modem. Note: not all Macintosh modems are 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 for insertion 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 for insertion in slot 2.

Magic Cap Utilities Manual 13

M a g i c C a p S imu la to r 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 testing the 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 doesn’t appear 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 and restart 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.

14 Magic Cap Utilities Manual

M agic Cap Sim u lat o r 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 then copies the entire screen bitmap to the screen itself. This window is useful for revealing inefficient or duplicated drawing. Show/Hide Drag Buffer Window Shows or hides the window that Magic Cap draws into directly when the user slides an item on the screen. Show/Hide Hit Cache Window Shows or hides the window that displays Magic Cap’s 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 their individual 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.

Magic Cap Utilities Manual 15

M a g i c C a p S imu la to r 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 match system indexicals. Start/Stop Leak Checking Enables/disables Magic Cap’s 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 an overridden method executes without calling its inherited implementation.

16 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Testing Menu

Require View Cache Coherency Checks the Magic Cap view cache for consistency. This item is used internally by General Magic.

Testing Menu
Go To Testing Scene Shows the Magic Cap testing scene. This scene and most of the items in this menu 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 be replayed later. Start/Stop Code Coverage Starts or stops recording system code coverage. Present/Retract Sample Announcements Creates or removes several announcements to test the announcement carousel. Simulate Device Contrast Simulates the grays used on personal communicator LCD screens. You should set your monitor to at least 16 grays to use this feature. If your monitor won’t display 16 grays, you can simulate this feature by putting cellophane tape over your eyes. Place Fried Egg in Name Bar It’s a long story.

Magic Cap Utilities Manual 17

M a g i c C a p S imu la to r Log Menu

Simulate Multiple Services Simulates registering for multiple electronic mail services to test features such 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 Menu

Each command in this menu enable or disables writing each kind of message to the log file. • Log Communications • Log Copy Engine • Log Communications Details • Log CRC Computation • Log Datebook Alarms • Log Encodings • Log Encoding Details

18 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools • Log Garbage Collection • Log Idles • Log Memory • Log Moving • Log Packing

• Log Redraws • Log Search

• Log Screen Captures • Log Text Formatting

Construction Tools

This chapter describes tools and techniques for working with objects in Magic Cap. These are called construction tools because they involve assembling and modifying the raw materials supplied by classes and static objects. Building a Magic Cap package with CodeWarrior Magic/MPW involves spending part of your development time modifying objects in Magic Cap itself. Most of your work with Magic Cap objects will be modifying the appearance of viewable objects. This includes changing the size, placement and color of different objects, among other things. Magic Cap offers users two basic operating modes. Most people will use the default normal mode in which the communicator behaves in the manner described by the user documentation. Magic Cap also provides construction mode, which gives the user enhanced control over objects.

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

Magic Cap Utilities Manual 19

M a g i c C a p S imu la to r Construction Tools When you make software packages, you’ll use the construction tools described here to build large parts of your software.

Construction mode itself is different in a Magic Cap communicator and in Magic Cap Simulator. The simulator provides additional features not found on a communicator. The sections that follow treat the four basic tools you’ll use to perform construction with Magic Cap.

Turning on Construction Mode

First, change to construction mode by going to the control panel in the hallway. Touch general to make the general control panel appear. Then touch construction mode so that it’s checked. Figure 2.1 Turning on Construction Mode

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

You’ll notice that the Stamper at the bottom of the screen immediately changes to the Magic hat. This important change is one of several that occur when construction mode is turned on. Some of the changes you’ll see in construction mode include the following: • The Magic hat replaces the Stamper at the bottom of the screen. The Magic hat is a combined catalog and storehouse of objects. In it you’ll find boxes, text fields, controls and lots of coupons for modifying viewable objects on the screen. The Magic hat window also contains the original contents of the Stamper window. • The Tool holder at the bottom of the screen contains additional construction tools.

20 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools • The ability to write Magic Script is available only in construction mode. A script is a set of instructions for an object to follow at a certain time. Magic Script is the language in which these scripts are written. Magic Cap lets you write scripts without learning any commands. As you edit a script, you simply touch on an object or on a script statement to see what the reasonable choices are for that spot in the script. Shortcut: There is a temporary shortcut to begin construction mode. First, open the stamps window open. Then, while pressing the option key, touch the middle of the gray title bar that runs across the top of the stamps window. This shortcut only works for a single choice from Magic hat. After you make the choice and use it, Magic hat turns back into Stamper.

Magic hat

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

Magic Cap Utilities Manual 21

M a g i c C a p S imu la to r Construction Tools The Magic hat is arranged hierarchically into eight categories. If you touch on one of the category boxes Magic Cap will redraw its window to display that category. For example, the stamps category contains the contents of the original Stamper. You can always make the Magic hat or the Stamper go away by touching the x in its top right corner.

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

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

22 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools Once you’ve opened the Magic hat, you may want to dispense more than one object. To do this, hold down the option key and tap on an object. It will fall out of the Magic hat into the scene behind while the window remains. Let go of the option key and touch another item. The Magic hat will go away. Within a category, drawers are used to select among different sub-categories of objects. Each drawer contains a screenful of objects. Touch a drawer to see the objects inside. At the bottom of the set of drawers is a choice box that lets you choose among whole banks of drawers when there are too many objects to fit in one bank. Touch one of the arrows to switch between the banks. Figure 2.4 Drawers organize objects into categories

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

Magic Cap Utilities Manual 23

M a g i c C a p S imu la to r Construction Tools When you drag a coupon over another object, the object will highlight if it can accept the coupon. If it doesn’t highlight, the object can’t do anything with the coupon. For example, you can’t drop a border into a stamp, so the stamp doesn’t highlight when you drag a border coupon over it.

Some objects have multiple parts and you can drop coupons onto each part to perform different functions. For example, boxes have content and border parts. You can drop different color coupons into the border and content, setting them to different colors. Text Coupons You can create a text coupon and drop it on any object that accept a text coupon—a telecard, a notebook page or an address card. Sometimes when you’re using construction tools you’ll need to drop text coupons onto objects to label them. You can create a text coupon with the keyboard. Here’s how to make a text coupon: Hold down the option key and touch the keyboard gadget at the bottom of the screen. The keyboard will appear with a label maker above it. This kind of keyboard is called the coupon maker. Once the coupon maker appears, anything you type will go into it and make a coupon.

You’ll notice that when you make the coupon maker appear, the keyboard also undergoes a slight change, the switch changes to a choice box. This gives you access to the symbols and accents planes of the keyboard. To put the coupon maker away: Tear the coupon off by touching down on it and sliding your finger across the screen or touch the coupon maker. Stamps As you look through Magic Cap and Magic Cap packages, you’ll see cards decorated with all sorts of small pictures: company logos, postage stamps, beasts, cacti, stylized skyscrapers. These pictures are called stamps. You can add them to any card and position them anywhere you like.

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

24 Magic Cap Utilities Manual

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

Magic Cap Utilities Manual 25

M a g i c C a p S imu la to r Construction Tools

Table 2.1

Kinds of stamps Kind general office occasions animations

local

faces symbols leisure songs misc.

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

26 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

Components
The components category contains a group of user-interface tools. These are the main ingredients for building the parts of a package that people interact with. These component objects have been developed to solve a variety of user-interface problems while maintaining a consistent set of user expectations within the Magic Cap environment. buttons A button is an object that a user can touch to invoke some action in a package. Buttons have two states: normal and highlighted. The highlighted state is temporary and only lasts while the button is being touched. After that, it returns to its normal state. switches A switch is a control with two positions. Change a switch’s position by tapping it. You can change the sound it makes when it’s touched by dropping in a sound coupon. Switches can be collected into a group with the ChooseOneBox 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 also contains meters which let users select numeric values. text Text fields contain text and scribbles. Text has many characteristics that you can set: typeface, size, style, and alignment. To edit the text in a text field, tap on the text field to get an insertion point, then touch the keyboard gadget to show the keyboard, or type on the Macintosh keyboard. You can set the characteristics of a text field with the coupons in the text styles category box. Text fields can contain many other kinds of objects, including shapes, stamps, animations, and even other text fields; objects inside are drawn clipped to the containing text field. When you create a text field by pulling it out of the Magic hat, its ability to contain other objects is turned off. To turn it on, tinker the text field with the Tinker tool and flip the can contain switch to the on position.

Magic Cap Utilities Manual 27

M a g i c C a p S imu la to r Construction Tools The text field components include three special objects named phone, time and numbers. These are simple forms processing controls. For example, the numbers text field control component only accepts numeric input. clocks 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 border and are filled with a particular color. They’re different from text fields in that boxes are primarily organizational and are designed to hold heterogeneous groups of graphical objects, not text. shapes Shapes are irregular objects that share some properties of boxes: they can contain other objects and they have a border and a color. When they are stretched with the stretch tool, they maintain their shape while being scaled horizontally 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 new icon from the icons drawer to replace it. Colors You can change the color that fills an object by dropping a color coupon into it. Most viewable objects accept color coupons. The color coupon category of the Magic hat also contains a Color box and a Color mixer, two objects quite useful for manipulating colors. They’re not coupons but they use color coupons to work properly, which is why they are in the color coupon category.

28 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools Sounds

A sound coupon specifies a digitized or synthesized sound. You can drop sound coupons into most viewable objects. The objects will play the specified sound when they’re tapped. To hear the sound in a sound coupon, tap the coupon. If you don’t specify a sound, switches and buttons will play the touch sound when tapped. Table 2.2 Kinds of sounds Kind standard

instruments

songs phone more

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

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

Magic Cap Utilities Manual 29

M a g i c C a p S imu la to r Construction Tools

Table 2.3

Kinds of borders basic lines fancy objects misc.

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

Text styles
Text style coupons come in several flavors. Probably the most useful are complete font coupons, which combine a type style and face with a size, like Book 18, which is an upright (Roman), 18-point version of the serif typeface Book. Coupons are also available to change individual aspects of type—the face, size, or style (obliqueness and weight, underlining and outlining).

All font coupons can be dropped into text in text fields. Many objects have text labels associated with them. You can change the appearance of a label by dropping text style coupons into it. Table 2.4 Kinds of text styles Kind Description sign Sign is a basic sans-serif typeface. Many people find it is readable on the screen even at small sizes. book Book is a simple serif typeface. Many people find that the serifs on Book make the face look a little more personal and relaxed than the austere Sign. Magic Cap includes two custom-drawn bold fonts of the Book face. styles The styles drawer includes some sophisticated versions of the basic text styles.

30 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools misc. Fat Caps and Jot are two special-purpose typefaces. In Magic Cap, Jot is used as a kind of proxy for handwriting, often showing information that the user added. Fat Caps is used to fit labels in tight spaces.

Magic Cap Utilities Manual 31

M a g i c C a p S imu la to r Construction Tools

Shadows
Many objects are drawn with shadows to improve their appearance. You can use shadow coupons to change a shadow’s appearance, or to remove a shadow. You can drop shadows into most viewable objects. The shadow style chooser includes arrows to select among its choices. To get a coupon from this dispenser, press down on the center section and drag a coupon out. Extras The extras drawer contains many different coupons that are useful for constructing and adjusting package user interfaces. hide The misc. drawer contains properties that control the show contents geometric properties of a viewable rotate left object. Shapes, stamps, and animations can be rotated in 90rotate right degree increments. You can drop flip vertical orientation coupons into these objects to rotate or flip them. The flip horizontal put in form coupon and the pull bring to front from form coupon work with the misc. form objects in cards. send to back put in form pull from form

32 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

Table 2.5

Extra kinds of coupons Kind line styles properties make moveable make copiable

make unmovable make uncopiable hide make deletable show contents make undeletable rotate left rotate right flip vertical

Description Drop a line style coupon into an object to change the appearance of the border that’s drawn around it. Many an object that you see can be modified with the view coupons you can find by tapping properties in the Magic hat. You can use these coupons to change the behavior of objects. The misc. drawer contains

shape types

flip horizontal misc. bring to front send to back put in form

properties that control the geometric properties of a viewable object. Shapes, stamps, and change Shape type coupons let you animations can be rotated in 90a shape’s type among various degree increments. You can drop styles, such as rectangle, circle, orientation coupons into these diamond, arrow. Shape type objects to rotate or flip them. coupons can only be droppedThe into put in objects. form coupon and the pull shape from form coupon work with the form objects in cards.

pull from form

Magic Cap Utilities Manual 33

M a g i c C a p S imu la to r Construction Tools

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

Tools are modes that you can turn on and off. When a tool is on, objects do something special when you touch them. Most of the time, you only need to touch objects to make them work. But in construction mode, you can copy and stretch and manipulate objects in various ways. To make the Tool holder appear, touch its icon at the bottom of the screen. The Tool holder window will appear and display a set of pencils. At the bottom of the Tools window is a choice box that lets you choose among the sets of tools. In construction mode, you’ll be able to use the authoring and debugging tools. Note:

Once the Tool holder is open, you can turn on construction mode temporarily by holding down the option key and touching in the gray bar at the top, where the text reads Tools. When you select a tool, the Tools window disappears and the Tool holder icon at the bottom of the screen changes to a tool indicator icon. This icon represents the current tool that will be applied to the next object you touch. If an object does not accept the tool, Magic Cap will play a sound to let you know and let you choose another object. If you don’t need a tool you have chosen, tap the tool indicator icon to dismiss it. Authoring The authoring tools control the layout of objects. You can move, copy and stretch object. In addition, you can change an object’s attributes that determine whether they can be moved, copied or stretched.

Figure 2.5

Move tool

34 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools To move an object, tap the move tool, then slide the object around on the screen. Some objects can be moved simply by sliding them, without your having to tap the move tool first. But most objects require that you tap the move tool to move them. It’s always worth trying an object to see if you can move it without the move tool. If you can’t, try the move tool. If you still can’t move the object, you might need to turn its can move switch on. Use the Tinker tool, described below, to tinker the object. Switch the appropriate switch in the open Tinker window to can move. Close the Tinker window by tapping on the wide bar along its top. You should now be able to move the object with the move tool. When you move an object on the screen, it’s drawn with a shadow to show you that it’s attached solidly to your finger but not to the screen. Figure 2.6 Copy tool

You can use the copy tool to create a copy of an object. To make a copy, tap the copy tool, then slide out a new copy of an object. The original object will remain in its old location while you slide the newly created copy. You may have to set the can copy attribute with the Tinker tool mentioned below before using the copy tool. Figure 2.7 Stretch tool

You can use the stretch tool to resize most objects. To do this, tap the stretch tool, then drag an object to its new size. You may have to set the can stretch attribute with the Tinker tool mentioned below before using the stretch tool. Figure 2.8 Tinker tool

Magic Cap Utilities Manual 35

M a g i c C a p S imu la to r Construction Tools The Tinker tool lets you work inside an object to examine or adjust its settings. An object’s settings are the qualities that affect its appearance and behavior, such as its shape, the colors that it’s drawn with, how it’s labeled, and what happens when you touch it. You can change an object’s qualities by dropping coupons on it, by tinkering it or with some other tool. When you tap the Tinker tool, it becomes the current tool and the Tinker tool icon appears in the bottom of the screen. When you tap another object, a window will appear with information showing the settings and parts that are inside the object. Figure 2.9 Tinker tool window

The switches on the right control a number of properties: whether the object can be moved, copied, or stretched, where and how its label is drawn relative to the object being tinkered. The label chooser lets you select one of 15 positions for the label by tapping the position you want. There’s also a data string in the bottom right corner of the window that shows how many bytes of memory the object uses. The settings that are shown when you open an object will vary for different classes of objects. If you see coupons that you like, you can drag them out of the open window and drop them on other objects. However, you can’t drop coupons into the Tinker window to change an object. Just drop the coupons on the object itself to make the changes.

36 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools You can move the Tinker window around by grabbing its title bar, and you can tap the close box to close the window. Debugging with Inspector The other choice box added to the tool holder in construction mode is for the Inspector. The Inspector provides information about objects in Magic Cap. There are two ways to use the Inspector: through the Tool holder and through menus in Magic Cap Simulator.

Here’s how to use the Inspector from the Tool holder. In construction mode do the following: 1. Tap on the Tool holder and the Tool holder choice box will appear. 2. Use the arrows or the tool name choice box to display the Inspector tool: Figure 2.10 Inspector tool

Magic Cap Utilities Manual 37

M a g i c C a p S imu la to r Construction Tools

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

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

Magic Script

Scripts are instructions that let you tell objects how to behave. Scripts can determine what buttons do when they’re touched, what meters display, and what happens when you flip switches. Scripts are written in a simple language called Magic Script with an interactive script editor that was designed to make scripting easy. Using Magic Script is different than using other languages. At each stage of the

38 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools scripting process the Magic Script editor presents you with a series of options that are valid at that point. You build a script by selecting among these options. Along the way, the Magic Script editor helps you to find the correct Magic Script term for what you want to do so you’ll never make a syntax error! Writing scripts is often more convenient and no slower than writing the equivalent with ObjectMaker or C. With the script editor, you will write a script and then close it. To save the script for future use, you’ll have to dump the contents of your package or object into a text file. Note: The Magic Script editor is part of Magic Cap Simulator and is a programming tool for developing Magic Cap packages. While Magic Script itself is part of the Magic Cap runtime system and is reliable, the Magic Script editor is under development and can present some problems. You should only use Magic Script for simple tasks. Writing Scripts The following steps describe how to write a simple script. This example will demonstrate the mechanics of script development with the Magic Script editor. We will use the HelloWorld sample package and write a script that toggles the color of the box in the HelloWorld package when you tap it. 1. Turn on construction mode. Scripting is usually done while Magic Cap is in construction mode. Select the construction mode switch in the control panel’s general category. 2. Display an object. Navigate through Magic Cap until the object you want to script is visible. Use the Greeter object in the HelloWorld package as an example. 3. Tap the Tinker tool. Scripting is done with the Tinker tool described earlier in this chapter. When the Tinker tool is the current tool at the bottom of the screen you are ready to begin scripting an object.

Magic Cap Utilities Manual 39

M a g i c C a p S imu la to r Construction Tools

4. Option-tap the object. While holding down the option key find the object you want to script and tap it. A script editor window appears for the object whose script you want to edit. The script editor window appears with the name of the object and its runtime object ID. If the object didn’t have a script before, an empty script window appears. 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 and the Magic Script editor will insert a new statement into the script.

40 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

Figure 2.13

Inserting a Magic Script statement

6. Tap the word action in the on statement to present a series of choices.

The first statement you add to a script creates a handler. A handler is a part of a script that is associated with an event, either a user action or a message from an object. The word action is a place holder for a choice that you make. When you choose an underlined word or phrase in a script a choice box appears presenting a series of available options. The arrow at the bottom of the menu indicates more options to choose from.

Magic Cap Utilities Manual 41

M a g i c C a p S imu la to r Construction Tools

Figure 2.14

Choosing an action

7. 7)Choose the word tap in the menu.

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

8. Tap the inkwell again to insert another statement.

42 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

Figure 2.15

Inserting a new statement

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

Magic Cap Utilities Manual 43

M a g i c C a p S imu la to r Construction Tools

10. Tap operation in the statement menu. The new statement phrase will be replaced by the operation statement. The operation statement is also a place holder for a choice that you make. Since this will be a simple script we will choose a simple action to perform when the object is tapped. 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 can request of the #RESPONDER object. The #RESPONDER is the object that will respond to the operation. In this case, the responder is the Greeter object that you are scripting. The script editor gets its list of operations from the responder by determining which of the responder’s operations have the safe and common flags set. You can set the responder to object other than the one you’re scripting by tapping #RESPONDER and then tapping the other object.

44 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

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 remain in the script editor window. By default the get/set highlighted statement displays its get variant.

Magic Cap Utilities Manual 45

M a g i c C a p S imu la to r Construction Tools

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 even useful script. The single operation statement tells the responder to reset its highlight color to the opposite of its current state when the object is tapped.

46 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

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

That’s all there is to writing a script with the Magic Script editor. The sections that follow provide more details on the different features of Magic Script. Handlers A handler is a script statement that responds to a particular system event. Some events are the result of user actions; for example, when you tap an object, a tap event is sent to the object. Other events are generated automatically by the system. For example, the system sends idle events to all objects when nothing else is happening.

Magic Cap Utilities Manual 47

M a g i c C a p S imu la to r Construction Tools

Note:

The ObjectMaker chapter in this book describes classes and operations. Operations can have implementations that use C code or scripts. The series of statements within an on _____ … end _____ pair is called a handler since this is how Magic Script should handle certain events. All your script statements will be in handlers. You can set a handler’s event type by tapping on the action keyword that appears after the on keyword. The on statement tells Magic Script when to execute the series of statements in the handler. When you select on from the new statement menu, you’ll get a handler that looks like this: on action end action For many scripts, these are just what you want. An action handler perform whatever statements are in between the on action and end action handler ends.

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

48 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools

Table 2.6

Some handler events Command idle tap touch play sound pressed arrived set orientation set entity

press pressing on screen tap center touching touched delete scribble prepare to send closing, opening card action tap here set shadow offset inspect set max set min

Description when nothing else is going on when you release the object soon after touching as soon as you touch the object when the object plays a sound when you release the object after holding down your finger on it when the object arrives as part of a event when the rotation of a viewable object changes when the entity (a person, company, or group) to which the object is set changes—particularly useful for objects that have to do with addressing or calling people when the user holds down on the object while the user is holding down on the object when the object appears on the screen when the object is tapped in its center while the user is touching the object when the user lets up after touching when a scribble on the object gets deleted just before the object gets sent as part of a event when the card the object is on is displayed on the screen usually, when the object is touched generally, when the object is tapped when the distance of the object’s edge from its shadow is changed when the inspector starts looking at the object when the value of the object is set to its maximum when the value of the object is set to its minimum

Magic Cap Utilities Manual 49

M a g i c C a p S imu la to r Construction Tools when the value of the object is changed at all when the percent value of a Control object is changed when the fractional value of an object is changed.

set value set percent set fraction

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

Each logical line of a script is called a statement. Some statements will wrap onto more than one physical line in the script editor, but each acts like a single line. When the Magic Cap communicator executes a script, it goes through the statements in order. When you want to add a line to a script, you can drag a new statement out of the inkwell at the right side of the script editor window. Or you can tap the inkwell to get a new statement. When you tap the newly created statement, you’ll get a menu that lets you choose the kind of statement you want. To pull a single script statement out of a multi-line script, touch and drag the statement to where you want it. As you drag a statement across the screen, it looks like a coupon. New Statement Menu

Figure 2.21

50 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools Words in scripts with a gray bracket underneath are those that you can change. Tap on such changeable words to see your choices, to allow yourself to select an object to which the statement should apply, or to toggle between possibilities.

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

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

Magic Script is not just extensible, it obtains the very statements it offers by asking each object what it can do. For you as a scripter, this just means that Magic Script will automatically know exactly what operations each object can perform, even if that object was not built into the system when Magic Script was created. Tap operation to see the operations that are valid for scripting. These are operations that have the safe and common flags set in the object’s class definition. Note:

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

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

Magic Cap Utilities Manual 51

M a g i c C a p S imu la to r Construction Tools math

The math statement is Magic Script’s door into the realm of arithmetic operations. When you choose math from the new statement menu, you’ll get a statement that looks like this: get object operator object Tap on the word operator to select the operation you’d like to perform and the two words object to set the values you’d like to operate on. You can also select text—such as a number—and drag it into the object words in the script statement. if The if statement is the basic conditional in Magic Script, a way for Magic Script to make decisions. When you choose if from the new statement menu, you’ll get this in your script: if it is nil object then end if You can make the otherwise go away by tapping on the first if. Change either of the words something to be specific containers by tapping on it and choosing the container you want from the menu that appears. You can also drag text from a field into the word something in order to get other values. You choose a comparison operator when you create an if statement. In this version of the software, these are the choices for comparison operators: is is not < > ≥ # is in is not in contains

52 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Construction Tools repeat

Use the repeat statement to make a script that executes repeatedly in a loop. Any statements that you place between the repeat and end repeat statements will be executed repeatedly as long the repeat condition is true. You can specify five kinds of repeat conditions, listed in Table 2.7. Table 2.7 Repeat conditions Condition repeat forever repeat for number times repeat while something is something repeat until something is something repeat with container = number to number Description executes until “abort scripts” message repeat a specified number of times repeat while condition is true repeat until condition becomes true use a loop variable. Tap on the word to and toggle it to down to, which will allow your repeat statement to count down.

The software defines a special object called the system object. It accepts several global messages. One of these global messages is abort scripts, which causes runaway scripts to stop. Type Command-. (period) on the Macintosh keyboard to abort running scripts. The repeat capability is under construction in this version of the software. You can use the forms repeat forever and repeat for number times to try out repeat statements. To get a number into a repeat for number times statement, drag a number from a field and drop it into the word number in the repeat statement. value

The value statement will put arbitrary text into the special container it or into any new container you create. You create a container just by thinking up a name 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 word something. When you choose value from the new statement menu, you’ll see this in your script:

Magic Cap Utilities Manual 53

M a g i c C a p S imu la to r Construction Tools

get object into it You can tap on get to change the statement to: put “Cassiopeia” into it If you tap on container, the only pre-made container—it—will suggest itself to you. You can also create a text coupon with the keyboard’s label maker and drag it into container to change its name. Text dragged here will create a container with that name. For example, drag “The Heavens” from a field into the word container in your put statement: put “Cassiopeia” into The Heavens Note that container names can be any text, even with spaces amidst. Comments don’t do anything but tell you about what other things in the script do. To put a comment into the space labeled no comment, hold down the option key and touch the under-bracketed words no comment. They will be highlighted in gray. Now touch the keyboard at the bottom of the screen. The keyboard will appear. Type out your comment. it There’s a special container called it that you can use when you’re writing scripts. When a script statement uses get, the value that it gets goes into the container it. For example, when the script statement get the time of day is executed, the container it will contain the time. When you move a slider or change the value of a meter, it gets the new value. You can use it within the script of a slider or meter. comment

You can make other containers by dragging text coupons from the keyboard’s label maker and dropping them into the word container in a Magic Script statement. Special Keyboard Feature Sometimes you’ll need to enter information to a script with the keyboard. For example, if a statement needs an object ID or an indexical, you can enter these with the keyboard. To do this, hold down the option key and touch one

54 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Inspector of the under-bracketed words in a script—an area for an object, for a method, for a constant (like a string or an integer). The text there will be selected, highlighted in gray. Type out what you would like to go into the script.

Inspector

The Inspector is a tool for interactively analyzing Magic Cap object. With it you will point at objects and look at their contents. Magic Cap Simulator has a menu named Examine with several items that work with the Inspector. Inspector commands Menu Item Keyboard Equivalent Show Inspector command-i Hide Inspector “ Dump command-h Inspector Target Dump Inspector Target Deep Dump Package Description Displays the Inspector window. Hides the Inspector window. Dumps the text description of the object in the Inspector into the log file Dumps the text description of the object in the Inspector—and all the objects it contains—into the log file Dumps the text descriptions of all the objects of a package into the log file

Table 2.8

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

Magic Cap Utilities Manual 55

M a g i c C a p S imu la to r Inspector

Figure 2.22

Viewing an object’s field values.

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

56 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Inspector

Figure 2.23

Viewing fields defined by superclasses

If the information you’re looking at doesn’t fit in the Inspector window, you can scroll it (vertically only) by sliding the text, or you can use the stretch tool to enlarge the Inspector’s window. You can also stretch the Inspector without getting the stretch tool by simply dragging on its frame, an operation that requires precise pointing. If you tap on a field that holds an object ID, the Inspector will change to show you information about that object.

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

Magic Cap Utilities Manual 57

M a g i c C a p S imu la to r Inspector You can use the Inspector to begin tinkering with any object in the view list, including objects that you can’t touch, like the screen object. To do this, tap the O (for Open) in the Inspector’s title bar while it’s displaying information about the object that you want to open. Option-tap the O to open the Magic Script editor and edit the object’s script.

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

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

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

58 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Inspector You can move the Inspector around on the screen by holding down the option key while you press on it anywhere and drag it, or by dragging the Inspector’s title bar, with or without the option key.

You can drop coupons into the Inspector to change its appearance, including border, text style, color, and shadow coupons. When you’re done with the Inspector, you can get rid of it by tapping its close box in the top-left corner or by typing -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. hold option key and tap X in title bar any class object inspect any object of that class, then tap Object ID

system object, including system root list

Magic Cap Utilities Manual 59

M a g i c C a p S imu la to r Inspector

Table 2.9

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

Example

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

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

60 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Assertions

As you create your packages, working back and forth between the CodeWarrior environment and Magic Cap Simulator, you may sometimes want to convert just a few objects to text rather than dumping all objects to text. While you’re running Magic Cap Simulator, you can convert any object to its text representation (in ObjectMaker syntax) by displaying the object in the Inspector, then typing -H on the Macintosh keyboard or choosing Dump Inspector Target from the Examine menu. When you dump an object this way, the text representation is written to an file called Log, located in the same folder as Magic Cap Simulator (the SystemSoftware folder, unless you’ve moved it). You can dump several objects by repeatedly aiming the Inspector, then typing -H.

Dumping Single Objects

You can also use -option-H or the Dump Inspector Target Deep to dump the inspected object and all objects that it’s related to, such as subviews, targets, object lists, and other objects referred to by fields. This feature, called deep dumping, is useful if you want to take an object and the objects that support it and move them to another package. Deep dumping dumps the same objects that would be copied if the object were copied; that is, it doesn’t dump any fields marked noCopy in the class definition file. If you hold down the shift key while you dump an object, a copy of the text of the dumped object is placed on the Macintosh clipboard. You can then paste this copy into a source code file instead of using the Echo Log command.

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

Assertions

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

Magic Cap Utilities Manual 61

M a g i c C a p S imu la to r Macros for Debugging perform any other test. Because assertions require a debug version of Magic Cap, they work only with Magic Cap Simulator and are ignored on communicators. Assertions are implemented with the Assert macro. Here is the syntax for assertions: /* * Evaluate condition; if false, break into debugger */ Assert(condition) Here are some examples of assertions: /* * Make sure sound is not nil before fooling around with it */ Assert(Sound(self) != nilObject); /* * Ensure that an object is a member of a particular class */ Assert(Implements(oldObject, Coupon_)); /* * Make sure value is in range */ Assert(spoonCount < 1000); /* * See if cached value is still good */ Assert(EqualBox(border, &cached));

Macros for Debugging

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

62 Magic Cap Utilities Manual

M agic Cap Sim u lat o r Macros for Debugging along with macros you can call to write messages to the log and to the window. In addition, you can call macros that cause a user break into MacsBug.

Because these macros require a debug version of Magic Cap, they work only with Magic Cap Simulator and are ignored on communicators. For extra debugging fun, the macros work differently depending on whether the Macintosh caps lock key is down when they execute. In general, they cause more fuss if caps lock is down. Table 2.10 describes the debugging macros and their actions. Table 2.10 Debugging Macros Macro Whisper((message))

Wherever functions refer to (message), the message can be any sprintf parameter list, as in the following example: Log(("the number %d is too small", number));

Action if caps lock off Action if caps lock on none Break into debugger with message; also write message to log QuickWhisper((messa none Break into debugger ge)) with message Log((message)) Write message to log Break into debugger with message; also write message to log DebugMessage((messa Write message to Break into debugger ge)) message window and with message; also write to log message to log Complain((message)) Break into debugger Break into debugger with message; also with message; also write write message to log message to log

Magic Cap Utilities Manual 63

M a g i c C a p S imu la to r Macros for Debugging

64 Magic Cap Utilities Manual

Bowser Pro

3

Bowser Pro is a class and source code browser designed exclusively for use with Magic Cap. Bowser Pro borrows technology from ObjectMaker to parse a set of class definition and C source files and presents a browsing window of the classes, methods and fields defined there. Bowser Pro has a preprocessing phase during which it reads in and parses the definitions for a group of classes and saves them in a browsing document. Most of the time you’ll use Bowser Pro to browse the classes in your package together with Magic Cap’s class definitions. To do that you’ll develop a browsing documents for the Magic Cap classes and for your packages classes. The next section describes the mechanics of creating a browsing document.

How to Use Bowser Pro

Here 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.

Magic Cap Utilities Manual 65

Bo w s e r Pro How 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 browsing document may take several minutes. 5. Try clicking on the various lists to see what happens. Figure 3.2 shows a picture of Bowser Pro in action, with annotations that describe the major features of Bowser Pro.

66 Magic Cap Utilities Manual

Bowser Pr o How to Use Bowser Pro

Figure 3.2

The Browse Window
The Class List Shows the list of classes Click on a class to see its methods and fields displayed in the text plane; option-click to see its class definition displayed; command-click to open a new window that displays the class definition. The Info Pane Displays information about the currently selected class. Click on a class to see its definition displayed. The Field Pane Displays information about the fields of the currently selected class.

The Text Pane Displays the source code of the selected method, or the class definition if the source code is not available.

The Method Pane Displays a list of methods defined by the class that is selected in the class list. Click on a method to see its source displayed in the text pane. Command-click on a method to have its source code displayed in a new window.

The Ancestry Display The data displayed in the ancestry display depends on which sub-window has been selected. If the Class Window has been selected, the Value Liine displays the class inheritance chain. If the Method Pane has been selected, the relevant line in the class definition is displayed.

You can use the keyboard to select classes, methods, and fields. Type tab to move 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 can also use the up arrow and down arrow keys to move through the selected pane.

Magic Cap Utilities Manual 67

Bo w s e r Pro Find Menu

Find Menu

The search is always case sensitive and does not wrap around when it reaches the end of the text in the text pane.

Find Inherited

Show the current method as implemented by the current class’s superclass. If the method has no inherited implementation, Bowser Pro beeps.

Find Class

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

Find Method

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

Find Field

This item prompts for the name of a field, then selects and displays the first implementation 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 the same 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 the currently displayed class.

68 Magic Cap Utilities Manual

Bowser Pr o Parser 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 item to 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 the selected class, including inherited methods. Select a method in this new window to see its source, if available.

Magic Cap Utilities Manual 69

Bo w s e r Pro Member Menu

All Fields of Class

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

Implementors of Class

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

Create Template

Use this item to create a instance definition for an Objects.Def file. A new window 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 the definition for the selected class. If you hold down the shift key while selecting this menu item, the class definition file will be opened in the MPW Shell.

Show Class Definition

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

Member Menu
Implementations of
This item opens a new window that lists all the implementations of the selected method. Select a method in this new window to see its source, if available.

70 Magic Cap Utilities Manual

Bowser Pr o Known Bugs And Limitations

Source File of Method

This item displays the name of the source file that contains the code for the selected method. If you hold down the shift key while selecting this item, the source file will be opened in the MPW Shell. Will this Shift key shortcut work for CodeWarrior too? I assume it could be done 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 class definition file.

Source File of Field

This item displays the name of the class definition file that contains the definition for the selected field. If you hold down the shift key while selecting 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 the MPW shell, and only if it is running.

Magic Cap Utilities Manual 71

Bo w s e r Pro Known Bugs And Limitations

72 Magic Cap Utilities Manual

ObjectMaker

4

Is ObjectMaker still a tool? Or, to the user, is it an object definition language?

ObjectMaker works with two kinds of files. A class definition file contains descriptions of class templates. These templates can include method definitions that are implemented in separate C files. An instance definition file describes the static objects used by a package. This chapter describes the syntax of class definition and instance definition files.

CodeWarrior includes an essential tool called ObjectMaker that compiles objects from text descriptions. Magic Cap software packages are created from these objects as well as from C source code.

From a programmer’s point of view, ObjectMaker contains most of what is object-oriented about Magic Cap development using CodeWarrior. The planning and design process usually involves building a Magic Cap package from existing classes with ObjectMaker. The actual C programming you’ll do occurs when you have to write new classes or override the methods of an existing class. Using or modifying existing classes has several benefits. It saves implementation effort and it conserves memory resources since the Magic Cap classes are stored in system ROM and special-purpose classes you develop must be stored in RAM.

Terminology Overview

In object-oriented programming systems, an object is a combination of data structures and procedures that act on that data. A class is a description of the data and behavior of a class of objects. It represents an agreement between a developer and a development system about how the object will behave when it 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: what a class can do and how it accomplishes this. A class’s interface represents the first part. It describes the kind of data an instance of a class can hold and the

Magic Cap Utilities Manual 73

O b j e c t M a k er Terminology Overview actions it can perform. It is like a group of data structure declarations and function prototypes in a structured programming environment. An operation refers to the part of a class’s interface that describes the actions it performs. A special case of an operation is an attribute which describes how to manipulate the data stored by an object. Attributes provide access to fields.

For a given class interface, a programmer can supply an implementation of a class’s data storage structures and the code that performs its work or, in some cases, the programmer can indicate that these should be supplied by other classes. This implementation is divided into fields that store the data, or instance variables, of a Magic Cap object and methods that comprise the code that 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.1 presents this terminology in a grid. Figure 4.1 Parts of object oriented programming

data interface

procedures

attributes

operations

implementation

fields

methods

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

A class is a static definition and by itself it doesn’t do anything. At runtime, Magic Cap can create an instance of a class called an object that performs the actions advertised by the class. In Magic Cap, we often think of objects in two places. The instance definition file contains a textual representation of the static objects that ObjectMaker creates for a package. At runtime a package may create dynamic objects as well. For example, whenever the user touches new in the Notebook, a new notebook page is created dynamically.

74 Magic Cap Utilities Manual

Object M aker ObjectMaker Syntax A Magic Cap package is a collection of objects that are organized into an object hierarchy. This hierarchy is different from but related to the class hierarchy used to organize class definitions. The object hierarchy is described later in this chapter.

ObjectMaker Syntax

ObjectMaker is a simple language with a small set of Pascal-like syntax rules. Since ObjectMaker performs minimal compile-time checking you should adhere to the naming rules described in the following sections. An ObjectMaker file is composed of a series of statements. Each statement is terminated by a semicolon. If a statement line is too long it can be spliced with a backslash \ character and continued on the following line. The backslash must be the last character on the line. • Any text between the delimiters /* and */ is treated as comments and ignored by ObjectMaker.

ObjectMaker recognizes two forms of comments borrowed from C and C++.

ObjectMaker has a simple conditional compilation facility that mimics the C preprocessor. The main statements are #define, #ifdef and #endif: #define identifier #ifdef identifier #endif In subsequent instances the identifier string will be replaced by the token sequence.

• // indicates a single line comment. Text to the right of this delimiter is treated as a comment and ignored by ObjectMaker.

ObjectMaker can include the contents of another file into an ObjectMaker file. This can be useful way to store definitions in one file shared by a number of ObjectMaker files. The include statement provides this feature. include ‘fileName’ ObjectMaker statements can use a C-like numeric expression syntax. Standard operators like + and - as well as parentheses are supported.

Magic Cap Utilities Manual 75

O b j e c t M a k er Class Definition File

Class Definition File

The class definition file contains descriptions of classes that are unique to a given package. The name for this file is usually derived by taking the package’s name and appended the .Def suffix to it. Class definition files are compiled by ObjectMaker during the package build process. Syntax for specifying fields, attributes, operations, and more is described in the following pages.

If a package doesn’t define any new classes, it doesn’t need a class definition file. Packages can have more than one class definition file in which case the additional files should have names derived from the first, e.g. MyClass.Def, OtherMyClass.Def, Other1MyClass.Def.

Table 4.1

Table 4.1 shows what the definition of a new class must have: Class definition properties Property Description class name Each class has a name to associate instances of it with the class definition. inheritance Classes are derived from superclasses and inherit their interfaces and implementation. fields Classes store their data in fields. attributes Attributes are interfaces for special operations that manipulate data in a class. operations Operations describe what you can do to an object. methods Methods are code that implements a class’s operations and attributes. The interface part of the class definition specifies the operations and attributes of a class. These declare the name, arguments and return type of the class. The implementation part defines the fields and methods of a class. The fields define the types for the data holders of a class and the methods define the code or algorithms for the procedures of a class. • methods for new operations

To implement the methods of a new class, you must provide source code for • methods for operations you override

76 Magic Cap Utilities Manual

Object M aker Class Definition File The source code for these methods are stored in C files separately from the class definition file. The section Method Implementation describes how to structure this source code.

Class Definition Syntax

Classes are defined in class definition files like this: Define Class className; // inheritance part // interface part // implementation part End Class; The first statement in a class’s definition specifies the name used to identify it to its subclasses and for objects that are instances of it. Each class has a class number. By default, the CodeWarrior environment creates a class number for each new class. Alternatively, you can explicitly assign numbers to classes in your packages. If you do so, you must choose class numbers that are unique within a package. This may be useful if the class’s interface will be public and its class numbers must be stable across different versions of the software. Class numbers are defined with the following syntax: class className classNumber; Statements that defines class numbers should be placed at the beginning of the class definition file. The file ClassNumbers.Def contains a list of class numbers for Magic Cap classes.

The interior portion of a class definition contains three parts. The inheritance part determines the mechanisms by which one class is derived from other classes. The interface part describes the attributes and operations of the class. The implementation part provides the data handling for the classes fields and the algorithms for its methods.

Magic Cap Utilities Manual 77

O b j e c t M a k er Class Definition File

CodeWarrior includes a useful tool called Bowser Pro for browsing the class hierarchy and looking at different class definitions. See this book’s Bowser Pro section for more information. Classes you create can be derived from other classes through inheritance. Most classes are ultimately derived from the Object class.

Magic Cap is like other object-oriented systems in that it has a class hierarchy that organizes classes according to their functionality. The mechanism that enables this system of organization is called inheritance. When one class inherits from another class, it inherits its fields, methods, attributes and operations. It is called a subclass of the first class, which is also called a superclass.

Inheritance

ObjectMaker provides several ways in which one class can inherit from another. The syntax for enabling this process is the inherits from statement. A class definition can contain multiple inherits from statements that specify different superclasses. The various forms of the inherits from statement can contain more than a single superclass. You should use a comma to separate them on the statement line. The following sections describe the different forms of the inherits from statement. inherits from superclassName; The inherits from statement indicates the superclass from which a subclass inherits its attributes, operations, fields, and methods. Operations and attributes in the subclass that need to be changed from what is defined in a superclass can be overridden with the overrides statement described below.

Normally, a class will inherit from a superclass that is itself ultimately derived from the Object class. This kind of superclass is sometimes called a flavor class.

Mixin classes precisely define their relationship with other classes in the class inheritance scheme. Mixin classes provide the convenience of holding a group of features in a class that can be used in combination with other classes

78 Magic Cap Utilities Manual

Object M aker Class Definition File while it is not tied to a specific place in the class hierarchy. This can be more flexible than taking a general purpose class and overriding what you don’t need.

Flavor classes must inherit implementation from exactly one flavor and from any number of mixins. They must inherit interface from at least one flavor and any number of mixins. Mixin classes must “mixin with” exactly one flavor class. They can inherit interface or implementation from any number of mixin classes. inherits interface from superclassName; This form of inheritance is useful in forcing a class to match the interface of another class and completely provide a new implementation for each attribute and operation of the inherited class. The inherits interface from statement has a performance benefit by removing the need for Magic Cap to search for the implementation of a class’s methods in the interface superclass. Another benefit of this statement is to provide more type checking during class development. inherits implementation from superclassName; This statement allows a class to inherit the implementation of another class without guaranteeing subclasses in the hierarchy that it provides that implementation. It is a weak form of support for private methods and it is rarely used.

Abstract Classes

ObjectMaker provides mechanisms for a superclass to specify the manner in which a subclass inherits from it. The first is an abstract class which is a class that cannot have any instances, though its subclasses can have instances. An abstract class can be derived from another abstract class or from a concrete class.

Abstract classes are used to collect attributes and operations into a convenient class that can then be inherited by other classes. They exist to help organize the class hierarchy and not for the immediate purpose of instantiation. Abstract classes include the keyword abstract at the top of their class definition.

Magic Cap Utilities Manual 79

O b j e c t M a k er Class Definition File Abstract classes can contain fields with the noGetter, noSetter and noMethod flags. These will be explained later in this chapter. getter

Mixin classes are abstract classes that are independent of Object and branch off the class hierarchy. The classes that can inherit from a particular mixin class can be limited toA a setter specific with the mixes in with statement. setter is list a method for setting the value in a field. This flag generates a setter method for the field. No mixes in with flavorClassName; interface is created for this automatic setter and a This statement limits the mixin class to flavorClassName and any of its separate attribute statement should also be defined for subclasses. To make a mixin class applicable to any class, specify Object as it. the class that it can mix with. Since all classes in the class hierarchy are noCopyfrom Object this The noCopy control an object over derived will allowflag the limits mixin the class to be applied tohas any the data in a field. When this flag is set, the object subclass of Object. referenced by this field will not be copied with the Mixins also provide a object way to distribute functionality to object disparate areas of the that controls it, though the ID remains class hierarchy without having to gather them into a when common superclass. By intact in the copy. In addition, an object instance not gathering them, the possible overhead of fields provided by mixins is is destroyed, the object referenced by this field will not only carried by the classes that require itthe and not by all the subclasses of the be destroyed with object that controls it. It can be common superclass. This can save memory on an instance by instance basis, used to control access to an object during wireline especially in a memory limited system like Magic encoding. This flag can onlyCap. be applied to fields with objects. It is rarely used. noSend Defining Fields The noSend flag prevents a field from being sent with an object instance that refers to it. It can be used to Fields provide the implementation data in an object. The field control accessfor to storing an object during wireline encoding. statement has the following syntax: This flag can only be applied to fields with objects and is: rarely used. , [optionalFlags]; fieldType field fieldName sendOptional This flag controls the default wireline encoding. This Field names should begin with a lower-case letter. The field type can be any flag can only be applied to fields with objects and is data type or class name. The optional flags modify the properties of a field. rarely used. Table 4.2 describes the different options: A getter is a method for getting the value in a field. This flag generates a getter method for the field. No interface is created for this automatic getter and a separate attribute statement should also be defined for it.

Mixin Classes

80 Magic Cap Utilities Manual

Object M aker Class Definition File setter A setter is a method for setting the value in a field. This flag generates a setter method for the field. No interface is created for this automatic setter and a separate attribute statement should also be defined for it. The noCopy flag limits the control an object has over the data in a field. When this flag is set, the object referenced by this field will not be copied with the object that controls it, though the object ID remains intact in the copy. In addition, when an object instance is destroyed, the object referenced by this field will not be destroyed with the object that controls it. It can be used to control access to an object during wireline encoding. This flag can only be applied to fields with objects. It is rarely used. The noSend flag prevents a field from being sent with an object instance that refers to it. It can be used to control access to an object during wireline encoding. This flag can only be applied to fields with objects and is rarely used. This flag controls the default wireline encoding. This flag can only be applied to fields with objects and is rarely used.

noCopy

noSend

sendOptional

Magic Cap Utilities Manual 81

O b j e c t M a k er Class Definition File Field definition options setter A setter is a method for setting the value in a field. This Option Description flag generates a setter method for the field. No interface is created for this automatic setter and a getter separate attribute statement should also be defined for it. noCopy The noCopy flag limits the control an object has over the data in a field. When this flag is set, the object referenced by this field will not be copied with the object that controls it, though the object ID remains intact in the copy. In addition, when an object instance is destroyed, the object referenced by this field will not be destroyed with the object that controls it. It can be used to control access to an object during wireline encoding. This flag can only be applied to fields with objects. It is rarely used. noSend The noSend flag prevents a field from being sent with an object instance that refers to it. It can be used to control access to an object during wireline encoding. This flag can only be applied to fields with objects and is rarely used. sendOptional This flag controls the default wireline encoding. This flag can only be applied to fields with objects and is rarely used.

Table 4.2

Here is an example of a simple field: field bookColor: Unsigned; This specifies a field named bookColor that has the type Unsigned.

82 Magic Cap Utilities Manual

Object M aker Class Definition File If the field definition includes a getter or setter flag, ObjectMaker generates an automatic method for these fields. The name of the automatic getter is derived from the field’s name by capitalizing the first letter in its name. The automatic setter attribute also adds the prefix ‘Set’ to the field’s name. If an attribute is new to a class, then a matching attribute statement is required. If an attribute is inherited, then getter or setter can be used to override the getter or setter flag of the inherited attribute. In that case, no additional attribute statement is needed in the subclass. This is described in the next section.

Defining Attributes

An attribute describes the interface to methods that access a class’s fields. There are two forms of attributes. The first form provides a well-defined interface for the automatic methods mentioned in the previous section. Here is an example of field and attribute definitions that a class definition might include: field visible: Boolean, getter, setter; attribute Visible: Boolean; The first line defines a field with its type and special flags indicating that getter and setter attributes are necessary. The second line defines these attributes. It defines both the getter operation Visible and the setter operation SetVisible. Objects can use these methods to get and set the value of the visible field. The second form of an attribute is independent of a specific field in a class. For example, attributes can be created that set and return a calculated value instead. The calculation could be based upon a field value (such as returning a percentage based on a field that maintains a fractional value), the system state (such as the current scene or the modem status), or system constants (such as the image of the General Magic logo or a system sound). In this case the package needs to provide the implementation of the getter and setter. Attributes in class definitions are defined like this: Table 4.3 describes the different attribute options: attribute attributeName: attributeType, [flags];

Magic Cap Utilities Manual 83

O b j e c t M a k er Defining Operations

Table 4.3

Attribute definition options Option Description noSetter The noSetter flag indicates that the class provides no setter method for this attribute but that subclasses could provide one. This flag can only be used with attributes of abstract classes. noGetter The noGetter flag indicates that the class provides no getter method for this attribute but that subclasses could provide one. This flag can only be used with attributes of abstract classes. readOnly The readOnly flag indicates that the attribute can return a value but cannot set one, and so neither this class nor its subclasses should provide a method to do so. Subclasses can redeclare an attribute to add a setter. safe The safe flag is an advisory flag to inform a high level programmer that the attribute does not need to be called in combination with any other attributes or operations. common The common flag is an advisory flag indicating that the attribute will appear in Magic Script menus. All common attributes must be safe. scriptable The scriptable flag indicates that the attribute should appear in Magic Script menus that list attributes and operations that can be overridden with Magic Script scripts.

Defining Operations
An operation describes the interface to a class’s method. It is similar to a procedure declaration with a list of flags that control the operation’s behavior. Operations in class definitions are defined like this: operation operationName[(paramName: paramType)]: returnValueType, [flags];

84 Magic Cap Utilities Manual

Object M aker Defining Operations This includes the operation’s name, its return value and an optional list of parameters with their types. In addition, an operation definition may include a list of flags that control the behavior of operations.

Every method in a class has one required parameter, known as self. The self parameter represents the object ID of the object whose method is being invoked. Since every method requires this object ID as its first parameter, this parameter is omitted in the class definition file. However, you must use it in the C file that contains the source code for the class. The following list describes options for operations:

Magic Cap Utilities Manual 85

O b j e c t M a k er Defining Operations

Table 4.4

Each operation has an operation number used by Magic Cap for method dispatching. By default, ObjectMaker defines these numbers for operations. You can specify numbers for the operations in your classes in a manner

Operation definition options Option Description noMethod The noMethod flag indicates that the class does not provide a method for this operation. Concrete subclasses of a superclass must provide the method. Classes that specify the noMethod flag on their operations must be defined as abstract. noFail The noFail flag indicates that the Magic Cap method dispatcher will do nothing and return 0 (if there is a return value) if the object passed to the operation is a nil object. This may provide convenience during debugging. This flag is only useful during package development on CodeWarrior since all methods are treated as noFail on a communicator. intrinsic The intrinsic flag indicates that this operation is called by a direct jump to the method which is faster than the usual method dispatching mechanism. Intrinsic operations can’t be overridden by subclasses and can’t be called by objects of other packages. There can be no other flags specified with the intrinsic flag. safe The safe flag indicates that this operation does not need to be called in combination with any other attributes or operations. common The common flag indicates that the operation should appear in Magic Script menus. All common operations must be safe. scriptable The scriptable flag indicates that this operation should appear in Magic Script menus that list attributes and operations that can be overridden with Magic Script scripts.

86 Magic Cap Utilities Manual

Object M aker Defining Operations similar to how class number can be specified. You might do this if your class has a public interface and you don’t want the operation numbers to change across different versions of the software. Operation numbers are defined with the following syntax: operation operationName operationNumber; The statement that defines an operation number should be placed at the beginning of the class definition file. Each operation number must be unique within a package. Attributes represent a special case for operation numbers. Because two operations are created when an attribute is defined (one for the getter and one for the setter), two operation numbers must also be defined. ObjectMaker defines syntax for assigning operation numbers to attributes as follows: attribute attributeName attributeNumber; This assigns attributeNumber to the automatic getter and attributeNumber+ 1 to the automatic setter. So, the assignment of the attribute number below attribute Visible 66; is equivalent to operation Visible 66; operation SetVisible 67; Attribute numbers have the same requirements as operation numbers.

Defining Globals

A class can define fields that hold data for the class itself, rather than for instances of the class. These fields are called globals. Globals in class definitions are defined like this: global globalName: globalType; You use FieldOf(ClassGlobals, <ClassName>Globals_<globalName>) to get a single global. Other accessors like SetFieldOf, BeginReadFieldsOf, ReadFieldsOf, etc.) can also be used to access global fields.

Magic Cap Utilities Manual 87

O b j e c t M a k er Defining Operations

Defining Simple Intrinsics

A class can define operations that don’t require an instance of the class in order to execute. These operations are called simple intrinsics. They have the same properties as intrinsics but they do not require an object ID as their first parameter. Simple intrinsics are faster to invoke than other operations but they cannot be overridden by subclasses. Simple intrinsics in class definitions are defined like this: intrinsic intrinsicName(paramName: paramType): returnValueType; As with operations, simple intrinsics can be assigned numbers that must be unique within the package. The ObjectMaker syntax for assigning an intrinsic number to a simple intrinsic in a class definition file is: intrinsic intrinsicName intrinsicNumber; This statement must precede the class that defines the simple intrinsic in the class definition file.

Overriding Methods

Once an operation or attribute has been defined in a superclass, a simple overrides statement can be used to provide a new implementation in a subclass. The overrides keyword can also define an implementation for a previously unimplemented operation, such as for operations that were defined with the noMethod flag in a superclass. A class can also use the overrides keyword to override an auto-getter or auto-setter method that was defined for a field of a superclass. To override a method in a class definition, use the overrides statement: overrides operationName; This statement indicates that a given class will supply its own implementation for the operation.

88 Magic Cap Utilities Manual

Object M aker Instance Definition File

Method Implementation

ObjectMaker extracts code from files that have been compiled and linked and installs that code into the correct classes. ObjectMaker uses a naming convention to decide which routine’s code to attach to an operation. The key part of this convention is that operations in the source file are indicated by the class name and operation name connected with an underscore. For example, a C function named TestClass_DoSomething would provide the code for the DoSomething operation of the TestClass class. When an operation is declared or called in C source, the first parameter must be the responder, the object whose operation is being called. When an operation is defined in a class definition file (ObjectMaker source), the responder is implied but is never shown. See Magic Cap Concepts for more information.

Instance Definition File

Each Magic Cap package must have an instance definition file named Objects.Def that describes the objects used by that package. A package can have more than one instance definition files. In that case the additional files should have names that use “Objects.Def” as a suffix.

As part of the process of building a Magic Cap package, ObjectMaker compiles this instance definition file into a package along with any special classes defined in the class definition file and implemented in separate C files.

The instance definition file contains textual representations of the package’s static objects. These are the objects the package creates when it is loaded into the Magic Cap environment. The package usually creates other dynamic objects at runtime but they are managed by the Magic Cap environment itself. Instance Class [objectName] instanceID; fieldName: value; . . End Instance;

Magic Cap Utilities Manual 89

O b j e c t M a k er Instance Definition File The instance definition file simply contains a list of object instances. Each object instance definition includes the name of its class, an optional object name and an instance definition id. The name can be helpful in the debugging process though it does incur some system overhead.

The instance definition ID used as a bookkeeping device for organizing instance definitions in an instance definition file. At runtime Magic Cap keeps track of a different number to refer to objects called an object ID. These numbers are not equivalent and it is a programming error to substitute one for the other. Instance IDs should be unique within the package. The GetUniqueInstanceID menu item in the ToolServer Tools menu in CodeWarrior can choose a suitable number for this field. If you do select instance ids manually, be sure to choose numbers that are small and not too far apart to avoid putting a memory burden on the Magic Cap runtime environment. The objects in a definition file do not have to be in numerical order (or any other special order). Every object in the file must have a unique instance definition ID, and instance definition IDs must be positive integers.

The interior of an instance definition contains a list of field initialization statements with the name of the field followed by its value. These correspond directly to the fields in the object’s class or superclass and must use the same order found in the class definitions. The different values that a field can have are described in the next section. The instance definition is finished with an End Instance statement.

Object Dumping

Magic Cap Simulator can translate objects from the Magic Cap runtime environment to instance definition files. This process of decompiling is called dumping in CodeWarrior. Dumping is a vital feature for moving between textual and live binary representations of objects. You can also convert objects directly from Magic Cap to text one at a time. One way to develop an instance definition file is to write a series of instance definitions, build a Magic Cap package, modify the objects with construction mode and then dump them back into the CodeWarrior environment. While this is a recommended method for developing instance definitions it does

90 Magic Cap Utilities Manual

Object M aker Instance Definition File remove any comments you may have stored in your instance file. So comments should be placed carefully in the instance definition file so that you can easily fold in your modified instance definitions.

If you add an object to a package by using the Magic Cap software and then dumping it to the Objects.Def file, CodeWarrior assigns a number in hexadecimal format. Delete the hex value and replace it with a number returned by the Get Unique Instance ID item from the Utils menu.

Object Hierarchy

The objects in the instance definition file are structured in a tree-like hierarchy. The top of this hierarchy is the SoftwarePackage object. Every other object in the instance definition file must be referred to by at least one other object and ultimately referred to by SoftwarePackage.

Figure 4.2 represents the object hierarchy used in the HelloWorld package. While this is a very simple package, more complex packages will have the same basic structure. More complex packages will tend to have a deeper tree branching from the subviews of the scene or will have multiple scenes pointed to by the standard places list.

Magic Cap Utilities Manual 91

O b j e c t M a k er Instance Definition File

Figure 4.2

Object hierarchy for HelloWorld
softwarepackage ID: 1

standard places ID: 5

help dictionary lists IDs: 6, 7

install/receive lists IDs: 3, 4

citation ID: 10

scene ID: 8

help text ID: 11

reference ID: 12

subviews ID: 9

Each object in this package has an instance definition ID number. The choice of numbers for instance definition ID’s is up to the package developer. You should choose instance definition ID’s that are small and closely packed because this avoids putting a memory burden on the Magic Cap runtime environment.

Field Initialization Statements

Each object can contain any number of fields. The instance definition file lists the values that these fields have when the package is loaded. fieldName: value; Each field initialization statement has a pair of tokens separated by a colon and terminated with a semicolon. The token on the left is the name of the field beginning with a lower-case letter. The token on the right is the value of the field. Each value has a type that indicates the kind of data that the field can contain. For example, one field may contain a floating point value and another may contain an indexical. The following sections describe the different types a field value can have.

92 Magic Cap Utilities Manual

Object M aker Instance Definition File

Object Reference An object reference takes the following form: (Class nameString instanceID) Class is the name of the class that the object is instantiated from. nameString is the name of the object instance. instanceID should be unique within the instance definition file. The object reference information in the field initialization statement should match the information used to define the instance. For example, target: (Greeter 'MyHelloWorld' 9); Indexical Indexicals allow you to refer to standard system objects, important objects in your package or dynamic objects like the current scene. Standard system objects and dynamic objects are listed in Indexicals.h. Indexicals can be a reference to an object or a list of objects.

The most common use of indexicals is to get to an item that is an element of a list. For example, Indexicals.h contains a list of standard text styles. To use one of the text styles in your object, such as Book 12, without having a copy of that object in your package, you can look up Book in Indexicals.h and you will see: #define iBook12 MakeIndexical(60,1) The numbers in parentheses (60,1) refer to the first element in the sixtieth object list of standard system objects. (Note that the object list of standard system objects is called the system root list.) To use this in your package, you would have a line like the following: labelStyle: iBook12;// recommended labelStyle: {60,1};// not recommended The first form of representing indexicals is strongly preferred over the second form. It is better programming style to leave the management of indexical numbers to ObjectMaker and use the predefined numbers in Indexicals.h. Unfortunately, Magic Cap Simulator dumps objects as raw indexical numbers. CodeWarrior has a ToolServer script named ConvertDumpedIndexicals that handles this conversion process.

Magic Cap Utilities Manual 93

O b j e c t M a k er Instance Definition File Flat indexicals refer to an object in the system root list, rather than an object in a list stored in the system root list. For example: #define iTextStylesMakeFlatIndexical(60) #define iDatebook MakeFlatIndexical(2) To refer to a flat indexical in the instance definition file, you would use a field definition statement like the following: field: iDatebook; // recommended field: {2}; // not recommended Package indexicals serve the same purpose as system indexicals but they are restricted to a package. In this case, the syntax is slightly different, you need to let the system know that you are referring to a package indexical, so you use {{n}} instead of {n}. You might have a list of special text styles in your package, which you have put into the 25th entry of the SoftwarePackage object, to refer to the second text style in that list. The definition of a package indexical for this would be the following: labelStyle: ipkgTextStyle;// recommended labelStyle: {{25,2}};// not recommended Operation Number Some Magic Cap classes, like Control and AttributeText, define fields that require operation numbers as values. System operation numbers are defined for the operations in system classes. The system operation numbers are listed in OperationNumbers.h. Package operation numbers are assigned to all package-defined operations when a class definition file is compiled by ObjectMaker. These package operation numbers are stored in the package’s PackageOperationNumbers.h file. CodeWarrior has a separate instance of this file for each communicator platform. For every system or package operation number, a constant of the form operation_OperationName is defined.

To specify an operation number as the value for a field in Objects.Def, use either a system operation number, a package operation number, or the constant for either:

94 Magic Cap Utilities Manual

Object M aker Instance Definition File

operation: operation_ShowOrHide;// recommended operation: 0x000003EC;// not recommended Note that it’s a good idea to explicitly define your package operation numbers in the class definition file. That way, ObjectMaker always translates the constant to the correct operation number, regardless of additional operations added to your class definitions. See AccessDemo for an example. Lightweight Objects Lightweight objects are used for Magic Script scripts. You will see them in an Objects.Def file that contains compiled Magic Script scripts. The following declares a lightweight integer. See the Calculator package for an example. See Generic.h for other lightweight data types. Note: You’ll see these in Objects.Def files but you won’t necessarily create any yourself. object: LtWtOpNum(operation_operationName); object: LtWtInteger(number); The object runtime defines a special lightweight object ID that represents the absence of an object. This ID is defined by the symbol nilObject. Files A field can extract its value from a file with the include keyword. For example, it may be more convenient to store the data for an image in a separate file and refer to it indirectly. The include keyword has three syntax variants. data: include ‘fileName’; data: include ‘fileName’ start_offset; data: include ‘fileName’ start_offset:end_offset; The first form includes an entire file as the value for a field. The second form use the begin value as an offset into the file. The third form uses both begin and end to limit the portion of the file to extract. These last two forms are not inclusive. For example, data: include ‘table’ 0:32; includes bytes 0 through 31 of the file table.

Magic Cap Utilities Manual 95

O b j e c t M a k er Instance Definition File

long The following declare a field that is 32 bits in length. myLong: 6; viewFlags: 0x11005200; The first example has an integer number and the second example has a hex value that is 32 bits in length. short The following declares a field that is 16 bits in length. myShort: 6.s; byte The following declares a field that is 8 bits in length. myByte: 6.b; Booleans The following declares a field that is 1 bit in length. autoActivate: true;// or false Strings Strings can include ASCII text, special characters or Unicode constants. name: 'Hello World'; Strings can include the escape characters listed in Table 4.5:

96 Magic Cap Utilities Manual

Object M aker Instance Definition File

Table 4.5

Escape characters This escape sequence... \n \t \’ \\ \xdddd Fixed

Represents this character new-line tab single-quote back slash Unicode constant

A Fixed value is 32 bits in length with 16 bits of integer and 16 bits of fractional data. width: 1.0; // hex equivalent: 00010000 Hexadecimal Data ObjectMaker uses the $ character to indicate a string of characters to be interpreted as hexadecimal. object: $00A6E27C; Extra Data Many objects store unformatted data as hex strings in their extra data (the variable length portion of an object that can exist in addition to its fields). Objects like images and cards often have extra data. data: $0400 007F FE40 F700 031F FFFF E4F9 000A \ 1701 FD40 017A 0000 01AA A4FD 000E 0FD0; Pixels and Microns Positional data can be specified with either pixels or microns. A pixel is the basic image unit of a graphics display. A micron is a smaller image unit used for more precise imaging calculations. The following relationship converts between these two systems: 1 pixel = 256 microns. Both pixels and microns are stored as 32-bit data types. They are both represented by using angle brackets. If the value between the <> is a fixed value that includes a decimal point it is a pixel; otherwise it is a micron. For example,

Magic Cap Utilities Manual 97

O b j e c t M a k er Instance Definition File

height <28.0>;// 28 pixelsrecommended height <7168>;// 7168 micronsnot recommended See the book Magic Cap Concepts for more information on the Magic Cap imaging model. Dot An object can store a location on the communicator’s display with a Dot value. The value is represented as a horizontal and vertical coordinates in a coordinate system with the origin in the center of the display. location: <20.0,30.0>;// x-y The location of a Dot can be specified in either fixed values or integers. If the values used are fixed, the location is interpreted in pixel units; otherwise microns are used. Box A Box is a rectangular region of the Magic Cap communicator’s display. The value is represented as a set of four 32-bit values. At with Dot, if the values are specified the Fixed type, its units are interpreted as pixels; otherwise they are interpreted as microns. region: <5.0, 40.0, 80.0, 90.0>; // left, top, right, bottom

98 Magic Cap Utilities Manual

In d ex

Index
A
abort scripts 53 About Magic Cap 11 Abstract classes 80 abstract classes 79, 80 action 41, 48, 49, 50 action handler 48 basic 30 book 30 BeginReadFieldsOf 87 Booleans 96 border 29 border coupon 24, 29 Boxes 28, 98 browser 65 button 27 byte 96

All Fields of Class 70

Bowser Pro 65, 66, 78 bring to front 32, 33 browsing document 65, 66

All Methods of Class 69 Alphabetical Classes 69 Ancestry of Class 69 animations 26 arrived 49 Assert 62 announcements 17 ASCII text 96 assertions 61, 62 attribute 83 attribute numbers 87 authoring 34

C
C preprocessor 75 C source code 73 can contain switch 27 can copy attribute 35 can move switch 35

attributes 74, 76, 78, 83, 87, 88 authoring tools 34

Can Move/Copy/Stretch Everything 15 can stretch attribute 35 caps lock key 63 carousel 17

B
banks of drawers 23

Capture Magic Cap Screen 12

Magic Cap Utilities Manual 99

Index

category boxes 22 Choice boxes 27

choice box 24, 34, 37, 41 Choose Macintosh Modem 13 ChooseOneBox 27 class 73, 77, 78, 87, 88

comparison operator 52 Complain 63 components category 27 Connect/Disconnect Keyboard 14

conditional compilation 75

Simulated

Hardware

class definition 61, 76

class definition file 73, 76, 77, 87, 88, 89, 94, 95 class hierarchy 74, 75, 78, 79, 80 class name 76, 89 class numbers 77 ClassGlobals 87 Clear 12

Connect/Disconnect Simulated Phone Line 14 construction mode 19, 20, 21, 34, 37, 39 construction tools 11, 19, 20 container 53, 54 control 27

ClassNumbers.Def 77 clipboard 12, 25 Clocks 28 close box 47, 59

control panel 20

Convert Object IDs to Instance IDs 61 ConvertDumpedIndexicals 93 coordinate system 98 Copy 12 copy tool 35 Coupons 23

Close Window 11 CodeWarrior 78 Collect from window 18 color 28 Color box 28

closing, opening card 49 CodeWarrior environment 61, 73, 77, 90

coupon maker 24 Create Template 70 Cut 12

current tool 34, 36, 38

D
debug version 63 debugger 62 debugging 34, 62

color coupons 24, 28 Color mixer 28 comments 54, 75, 91 common 44, 84

DebugMessage 63

100 Magic Cap Utilities Manual

In d ex

delete scribble 49 Discipline 11 Dot 98

deep dumping 61

F
faces 26 fancy 30 Faster Validates 16

Don’t Save Changes 11 drawers 23

field 80, 83, 90, 95, 96 FieldOf 87 file 95

Dump Inspector Target 14, 55, 61 Dump Package 14, 55 dumping 61, 90, 91

field initialization 92, 93 fields 58, 74, 76, 78, 80, 87, 92 Fill Persistent Memory 18 Fill Transient Memory 18 Find 12 Find Class 68 Find Field 68 Find Indexical Candidates in Package 16 Find Inherited 69 Find Method 68 Fixed 97

Dump Inspector Target Deep 14, 55, 61

dynamic objects 74, 89

E
Echo Log 61 Edit menu 25 Eject Card from Simulated Slot 1 13 Eject Card from Simulated Slot 2 14 Enable Macintosh Modem 13 end action 48 End Instance statement 90 event 41, 47, 48 event name 50 Examine 11

Find System References in Package 16 flat indexical 94

Enforce Allocation Rules 16

flat indexicals 94

flavor class 78, 79

flip horizontal 32, 33 flip vertical 32, 33 font coupons 30 fonts 12

Examine menu 61 extra data 97

Execute Standard System Test 17

Force Warm Reset 13

Magic Cap Utilities Manual 101

Index

G
general 27 Generic.h 95 getter 80, 83 globals 87 Get Unique Instance ID 91 GetUniqueInstanceID 90 Go Back 68

Implementations of 71 Implements 62

Implementors of Class 70 include keyword 95

include statement 75 Indexicals 93 indexicals 93

indexical numbers 93

Go To Next 68

Go To Testing Scene 17

Indexicals.h 51, 93

information window 11 inheritance chain 58

inheritance 74, 76, 77, 78 inherits from statement 78 inkwell 40, 42, 50

H
hallway 20 handler 41, 47, 48, 51 hexadecimal 97 hide 32, 33 hardware keyboard 14

inherits interface from statement 79 Insert Card in Simulated Slot 1 13 Insert Card in Simulated Slot 2 13 inspect 49 Inspector 14, 34, 37, 38, 55, 56, 57, 58, 59, 61 Inspector window 38 instance definition 90

Hide Inspector 55

highlighted state 27

I
icons 28 idle 47, 49 idle messages 47 if statement 52 images 12 image coupon 25 implementation 74, 76, 77, 79, 80, 88

instance definition file 61, 73, 74, 89, 90, 91, 92, 94 instance definition ID 58, 61, 90, 92 instruments 29 interactive script editor 38 Interface of Method 71 intrinsic number 88

interface 73, 76, 77, 79, 84

102 Magic Cap Utilities Manual

In d ex

it 53, 54

Log Memory 19 Log Moving 19 Log Packing 19

J
journal 17

Log Redraws 19 Log Search 19 long 96

Log Screen Captures 19 Log Text Formatting 19

K
keyboard 24, 27, 54 keyboard gadget 24, 27

L
label chooser 36 label maker 24 labels 30 leisure 26 lines 30

M
Magic Cap communicator 20 Magic Cap for screen shots 12 Magic hat 20, 21, 22, 23, 27, 28 Magic Script editor 58 make copiable 33 make deletable 33 Magic Cap Simulator 11, 20, 25, 34, 37, 39, 55, 61, 62, 63, 90 Magic Script 21, 38, 39, 40, 42, 47, 48, 51, 95

Lightweight objects 95 local 26

Log 11, 61, 63

Log Communications 18 Log Copy Engine 18

Log Communications Details 18 Log CRC Computation 18 Log Datebook Alarms 18 Log Encoding Details 18 Log Encodings 18 log file 14, 62 Log Idles 19

make moveable 33

make uncopiable 33

make undeletable 33 make unmovable 33 math statement 52 messages 47 meters 27

message window 62

Log Garbage Collection 19

method dispatching 86

methods 74, 76, 78, 83, 84, 85 Magic Cap Utilities Manual 103

Index

microns 97, 98

misc 26, 30, 31, 32, 33

object ID 40, 56, 57, 58, 85, 88, 90 object name 90 object reference 93

mixes in with statement 80 mixin classes 78, 79, 80 modem 13 more 29

ObjectMaker 61, 73, 75, 76, 89 objects 30

Monitor Memory Management 16 move tool 23, 35

object-oriented programming 73 Objects.Def 89, 91, 94, 95 occasions 26 office 26 on action 48

N
naming convention 89 New Card in Simulated Slot 1 13 New Card in Simulated Slot 2 13 new statement 43, 44 no border coupon 29 no comment 54 noGetter 80, 84

on screen 49

on statement 48

Open Copy of Package 11 operation name 89

operation 44, 51, 74, 83, 84, 85, 86, 88 operation numbers 86, 87, 94 operation statement 44 operation_OperationName 94 OperationNumbers.h 94 operations 76, 78, 88 operator 52

noCopy 61, 80, 81, 82 noMethod 80, 88 normal mode 19 noSetter 80, 84 noSend 80, 81, 82 numeric input 28

option key 21, 23, 24, 34, 40, 50, 51, 54, 59, 60 overrides statement 78, 88

O
object 52, 73, 74 Object class 78 object hierarchy 75

P
package 61, 76 Package indexicals 94 package operation numbers 94

104 Magic Cap Utilities Manual

In d ex

PackageOperationNumbers.h 94 packages 24 Paste 12, 25 phone 29 Parse More 69 Paste Image Coupon 25 Phone line connected window 14 pixels 97, 98 Place Fried Egg in Name Bar 17 play sound 49 pointing hand 22

RAM card 13 readOnly 84 Reparse 69

ReadFieldsOf 87

repeat statement 53

Require Card/Form Alignment 16 Require Hit Cache Coherency 16 Require Inherited Calls 16 reset button 13 RESPONDER

Require View Cache Coherency 17

Power On/Off 13

prepare to send 49 press 49

responder 44, 89

Present/Retract Sample Announcements 17 pressed 49

Return Persistent Memory to Normal 18 ROM 73 Return Transient Memory to Normal 18

pressing 49

rotate left 32, 33

properties 33

rotate right 32, 33

pull from form 32, 33 put in form 32, 33

S
safe 44, 84 scribbles 27 script 46, 50, 55

Q
QuickWhisper 63 Quit 11

script editor 39, 40 scriptable 50, 84 scripting 21, 39 scripts 38, 39 Select All 12

script editor window 47

R
radio buttons 27 RAM 73

Magic Cap Utilities Manual 105

Index

self 85

Send Package 18

sign 32

send to back 32, 33 set entity 49 set max 49 set min 49

simple intrinsics 88

sendOptional 80, 81, 82 set fraction 50

Simulate Device Contrast 17 Simulate Multiple Services 18 Sliders 27 SoftwarePackage 91, 94 something 53 songs 26, 29 Simulate Incoming Call 14

set orientation 49 set percent 50 set value 50 set shadow offset 49 SetFieldOf 87 shadow 35 Shapes 28 short 96

sound coupon 27, 29 sounds 12, 29 Source File of Class 70 Source File of Field 71 sprintf 63 Source File of Method 71 Stamper 20, 21, 22 stamps 24 stamps window 21 standard 29 Start with 1 MB Additional RAM 14 Start/Stop Code Coverage 17 Start/Stop Journaling 17 statement 50, 51 Start/Stop Leak Checking 16 static definition 74

setter 80, 81, 82, 83 shape types 33

Show Class Definition 70 show contents 32, 33 Show Inspector 55

Show/Hide Development Tools 11 Show/Hide Hit Cache Window 15 Show/Hide Inspector 14 Show/Hide Memory Window 15

Show/Hide Drag Buffer Window 15

Show/Hide Message Window 15

static objects 74, 89 Strings 96

Show/Hide Screen Buffer Window 15

stretch tool 28, 35, 57

106 Magic Cap Utilities Manual

In d ex

styles 30

subclass 78 switch 27

touched 49 trash 42

superclass 78, 79 symbols 26

touching 49

System operation numbers 94 system root list 94 SystemSoftware folder 61

U
Undo 12 Unicode 96 Utils menu 61

T
tap 42, 47, 49 tap center 49 tap here 49 Testing 11 text 12, 27

V
Validate Inspector Target 15 Validate method 15 Validate System 16 value statement 53 view list 55 viewable 55 Validate Package 15 Validate System and Active Packages 16

text coupon 24 Text fields 27 Text style coupons 30

text styles category 27 Tinker window 35, 37 tinkering 58 title bar 57, 58, 59 tool holder 37

Tinker tool 27, 35, 36, 39

viewable objects 23

W
Whisper 63

Tool holder 20, 34, 37 tool indicator 34 touch 49

Tools window 34

Magic Cap Utilities Manual 107

Index

108 Magic Cap Utilities Manual

Credits
CodeWarrior Writing Lead. Marc Paquette General Magic Writing Lead. Daniel Sears Documentation Lead. Avi Rappoport Valued assitance and feedback. Darin Adler, Scott Knaster, Dave Newman, Greg Marriott, CJ Silverio, Susan Rayl, Dean Yu, CodeWarrior users everywhere.

Magic Cap Utilities Manual 109