TweetFollow Us on Twitter

Making Magic
Volume Number:11
Issue Number:5
Column Tag:Magic

Making Magic

A developer’s introduction to General Magic and Magic Cap

by Richard Clark, Scott Knaster, and the staff of General Magic

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

“Where should Apple go after the Macintosh?” The year was 1990, and Marc Porat was leading a group of engineers considering that question. Porat’s answer to this question became the Paradigm project: Apple’s plan to build a small, personal, communication-oriented computer. Porat asked to spin off a small company to realize this vision, Apple’s board gave its blessing, and General Magic was born.

Several members of the original Macintosh team - Andy Hertzfeld, Bill Atkinson, Joanna Hoffman, and Susan Kare - joined with scores of new Magicians to realize Porat’s dream. Major companies (including Apple, Sony, Motorola, AT&T, Matsushita, and Philips) formed an alliance around General Magic to bring their talents and resources to the project. Last October, the world saw the first examples of that work when Sony shipped the Magic Link™ Personal Intelligent Communicator and AT&T opened the AT&T PersonaLink™ Services network. Two months later, Motorola shipped Envoy™, which is their implementation of a Personal Intelligent Communicator. These products have two things in common: Magic Cap™ and Telescript™.

Even though this article is about Magic Cap, we should take a moment to describe Telescript. Telescript is a programming language for building distributed systems-programs which aren’t entirely resident within a single computer but are spread out across a network. AT&T’s PersonaLink Services use Telescript programs to carry messages between a communicator and the network, then uses these programs to transport messages around the network. Even though Magic Cap uses Telescript for many of its communications tasks, we’ll see that there are plenty of opportunities that Magic Cap developers can pursue without Telescript.

What is Magic Cap?

Magic Cap is General Magic’s software environment for personal communicators. Magic Cap embraces both the most common tasks found in today’s workplace (managing your schedule and relationships) and such communication tools as the telephone, FAX, and electronic mail. Magic Cap doesn’t skimp on the programming side either: it contains an extensive collection of user interface building blocks, a multitasking kernel, and a rich set of utility routines for third-party developers.

Magic Cap was designed with two key principles in mind: communication and ease of use. Communication means that every device is ready to communicate: all Magic Cap communicators have a data/FAX modem built-in along with the software to support it. Each communicator is also designed to act as a telephone dialer and can act as a handset with the appropriate attachment. Communicators may interact by sending electronic mail over the telephone or directly via an infrared transceiver. Magic Cap packages -the equivalent of programs on a desktop machine-have easy access to e-mail, fax, beaming, printing, and other communication features.

Magic Cap’s ease of use comes from its graphical interface. Magic Cap embodies the original spirit of the Macintosh-it creates an inviting world that uses familiar objects in common ways. In order to be more than a novelty in the personal electronics world, communicators must be consumer electronics products, not tiny computers. They must be usable by both self-admitted “gadget freaks” as well as people who draw the line at telephones and possibly automated teller machines. This means that communicators must be much easier to use than even the friendliest personal computers. In Magic Cap, ease of use comes from great user interface design with simple, powerful metaphors and consistent features. General Magic has performed an enormous quantity of user testing, and continues to do so, as do its most successful developers.

Magic Cap was implemented with efficiency, utility, and safety as its key goals. Efficiency begins with Magic Cap’s object-oriented structure. Packages can build on the rich set of objects provided in ROM. Utility comes from a runtime environment designed to work with existing development and debugging tools and which assumes that it is running in a very constrained space. Safety is embodied by the memory management system: it makes efficient use of limited RAM even when creating and destroying scores of objects, protects user data, and includes a clean up feature to recapture memory that a programmer might otherwise leave behind.

The Magic Cap Hardware Platform

Magic Cap offers another feature that developers can feel good about - a standardized hardware platform. The current generation of communicators is built around the Motorola 68349 Dragon microprocessor. The Dragon contains a 68000-family core with memory protection hardware and low-power operating features. Communicators also include at least 1MB of RAM, 3MB of ROM (including the software environment and bundled third-party packages), a data/FAX modem, the Magicbus ™ high speed interface bus, a PCMCIA Type II slot, a high-speed infrared transceiver, and an option button. Each communicator has a 480 x 320 LCD screen with 4 levels of gray, a speaker, a microphone, and an interface for a headset which turns the communicator into a telephone. These features provide a rich hardware base upon which to build software packages for all Magic Cap communicators.

This minimum hardware requirement ensures that developers can build packages that work on a variety of communicators, yet allow hardware vendors to add unique features. For example, Motorola’s Envoy includes a second PCMCIA slot and a wireless modem. These hardware enhancements have been integrated into Magic Cap.

A User’s View of Magic Cap

When you turn on a new Magic Cap personal communicator, you’ll see the desk. This is the jumping off point for most of the things you’ll do with a communicator.

Magic Cap’s objects suggest items that you use in the real world. To make them work, you touch them: touch your in box to see your mail, touch the datebook to make an appointment, and so on. This display shows several other constants in the Magic Cap world: the upper name bar and the lower control bar. The name bar supplies help, shows the date and/or time, and contains the step back hand to allow for navigation from one Magic Cap package to another. From left to right, the control bar contains:

• A button that returns the user to the desk,

• A stamper that contains both decorative and functional objects to drop on other objects (this is also used to access the magic hat which allows users to change the fundamental behaviors and appearance of their communicators),

• The magic lamp from which you can search, print, fax, mail, and beam (package-specific commands also go here),

• The tote bag, like the Macintosh Clipboard, can be used to carry information from one place to another,

• The tool holder , which is full of drawing and editing tools,

• A button to display the on-screen keyboard, and

• The trash truck to dispose of unwanted or unneeded items.

Though some might dismiss the interface as “cartoon-like,” Magic Cap’s items are big, clean, and familiar for several important reasons. First, LCD screens on communicators are not the clear bright CRTs that we’re used to on computers; small images and fine shadings are harder to see. Second, because many people don’t like having to reach for a stylus, Magic Cap is designed to be used with fingers and fingertips doing the touching (although a stylus also works), so having big objects to touch is vital. Finally, users learn and work better with simple, abstract images than with complex, realistic ones.

This desk scene demonstrates that communication is at the heart of Magic Cap. The center of the screen is occupied by the most important elements of communication: the in box (where newly arrived messages appear) and the out box where newly created messages go. Surrounding these are other important communicating software packages built into Magic Cap, including a notebook for free-form drawing and writing, a phone that you can use when your communicator has access to a phone line, and a file cabinet for organizing saved messages. The name cards file to the left of center contains postal and e-mail addresses for your associates as well as their telephone numbers.

Magic Cap also applies its communication abilities in more subtle ways. When you use the datebook to schedule a meeting, Magic Cap will offer to create an e-mail message telling the other attendees about the meeting. If the attendees have Magic Cap communicators, they can install the appointment in their datebooks automatically when they get the message, and even generate an RSVP message that comes back to you. If you create a drawing in the notebook, you can mail that page to a colleague’s communicator.

These features - an inviting, graphical interface, careful attention to how people use the machine, and a standardized hardware platform - demonstrate Magic Cap’s kinship with the Macintosh. The similarities to the Macintosh don’t end at the human interface though, as we’ll see in the next section.

In Magic Cap, Everything Is An Object

The original Macintosh was also designed with consistency and limited resources in mind. The original Macintosh team’s answer provided a “toolbox” in ROM that supplied programmers with many of the common user interface elements. Magic Cap follows this same path by providing all of its object classes in ROM for developers to build on.

Every Magic Cap object descends from class Object, thus inheriting the memory management commands, the ability to be encoded and decoded for transmission to another communicator, tools for reading and writing its own data, and debugging code. New classes may also inherit from Linkable, which allows you to build lists of arbitrary objects.

Magic Cap builds on the foundation classes to create Viewable objects and their subclasses. Anything that gets drawn on the screen and anything that the user can touch is there because of a viewable. Viewable’s subclasses include Button, Control, Card, Scene, Form, Color, TextField, and Coupon.

When you look at the Desk scene, you can see several viewables at work. (Each different screen in Magic Cap is known as a scene.) The name bar and control bar at the top and bottom of the screen are both viewables, as is the Scene object that lies between them. Each of these viewables contains multiple other viewables. The contained viewables are clipped to their container’s boundaries, and receive touches before their container does. We’ll see some more examples of viewables when we demonstrate how to build a Magic Cap package later in this article.

Objects, Memory, and Magic Cap

The Magic Cap runtime system has to perform three basic functions: manage objects in memory, execute operations against those objects, and handle any errors that might arise.

Since objects may be created and destroyed quickly within a communicator’s limited memory, the runtime system has to work to fill in gaps left by old deleted objects. Thus, just as the Macintosh has handles which allow it to rearrange blocks of memory on the fly, Magic Cap has object IDs. Each object ID is a 32-bit value that uniquely identifies an object within a package. When you use an object ID, Magic Cap’s object runtime quickly and efficiently converts it into a pointer to the object. Because an object ID isn’t an actual pointer to an object, the runtime system is free to move the object around in memory to minimize memory fragmentation and thus make room for new objects.

The runtime system also controls how code gets access to data. Magic Cap objects are structures that define both data elements and a set of functions that operate on the data. The data elements are called fields, and the functions are called operations. Most objects define operations that read and write specific fields, these are called attributes. Under most circumstances, an object doesn’t access its fields directly but uses either attributes or the special Field operation inherited from Object.

Since a personal communicator is designed to keep all of its permanent user data in RAM, the runtime system also works to protect this data. Every communicator contains a block of persistent RAM which is preserved when the communicator is turned off. (This memory is standard low-power static RAM, so either the main battery, backup battery, or AC power has to be connected.) Persistent RAM is protected from change through a set of internal routines provided by Magic Cap. Packages can’t write directly to persistent memory; instead, packages write changes to a buffer area of memory. Magic Cap updates persistent memory from this buffer area periodically, ensuring that packages don’t corrupt structures in persistent memory. Because persistent memory is protected from direct change, writing to it is somewhat slower than if memory were not protected, but essential user data is safe.

As a performance enhancement, Magic Cap requires a second kind of RAM that is not protected from change and does not retain its contents when the main power shuts off. This transient memory is implemented using low-power dynamic RAM. Transient memory is useful for objects that are created and destroyed within the scope of an existing operation, objects that can be recreated from persistent data, and other temporary objects. If your package uses transient memory, it must be prepared to recreate any objects stored there if the communicator shuts off or is reset.

Magic Cap gathers objects into clusters. Each cluster is similar to a Macintosh heap; it has a master block that refers to each of the objects in the cluster. Each object ID refers to a master block and contains an index number into that block. Unlike the Macintosh, clusters may cover several disparate area of memory. (In other words, a single cluster might include both the RAM built into a communicator and the RAM on an inserted PCMCIA card.) A package has both a package persistent and package transient cluster, and may define additional clusters for its own use. Packages also have access to the system persistent and system transient clusters so they can access system data and call system operations.

The system also maintains a shadow cluster for objects in ROM. If the user decides to modify an object in ROM (e.g. changing the background color in the Desk scene), that object is copied into the ROM shadow cluster and modified. The runtime system looks for objects in the shadow clusters before checking ROM. This allows the user to customize any part of the system. This also allows General Magic to patch code in the ROM for software enhancements and upgrades.

A package’s clusters are all gathered into the context for that package. Only one context may be active at a time. If the user moves from package to package or the preemptive kernel switches execution from one package to another, the context will be switched to that of the current package. The use of contexts and object IDs isolate packages from each other and thus protects both the developer and the user.

Executing Operations

Executing an operation against an object requires both an object ID for that object and the name of the operation to execute. The runtime system will search through the object’s class then its superclasses until it finds the appropriate operation and then will execute the code. (Magic Cap draws a distinction between a method and an operation - a method is the code that implements an operation, thus the Method keyword at the start of our code examples.)

Magic Cap packages are written in C with some object extensions, so executing an operation looks just like a standard C function call. The only thing that distinguishes executing an operation from a C function call is the object’s ID in the first parameter. This is shown in the code below. In this code, we’re first asking the SimpleAgent class to create an instance of itself in transient memory. (The trailing “_” in the sample code denotes a class.) This ability is inherited from Object. We then extract the text of our message object and copy it into transient memory. Finally, we use an attribute to put our newly copied text into the agent’s message field and return the agent’s object ID to the caller.

Method ObjectID
AgentSender_MakeAgent(ObjectID self, ObjectID messageText)
{
    // Create an “agent” object which will carry a message to another
    // user.  Return the agent’s ObjectID to the caller.
 ObjectID agent, message;
 
    // Create one object of class SimpleAgent in transient memory
 agent = NewTransient(SimpleAgent_, nil);
    // Read the contents of our message (passed in messageText)
    // and make a duplicate in transient memory.
 message = CopyTextTransient(messageText);
    // Give the copied message to the agent
 SetMessage(agent, message);
 
 return agent;
}

Magic Cap also supports intrinsic functions which aren’t bound to a particular class and which use a fast dispatching scheme. Certain common system and utility functions are implemented as intrinsics, and are called if they were regular C functions. (The difference is that Magic Cap locates the intrinsic’s code through its dispatching mechanism so intrinsics can be patched later in life. Most C compilers and linkers call functions by their addresses which makes later patching difficult or impossible.)

Error Handling

Since communicators hold important personal information and have no separate mass storage, they must recover gracefully from programming errors without losing data. To simplify error handling and make sure it can detect any errors that a package doesn’t, Magic Cap incorporates exception handling.

Exception handling isn’t new, but if you aren’t familiar with it here’s the idea: before executing some code that might fail, a routine can add an exception handler to a list in the system. When a subsequent routine fails, it creates an exception object containing information about the failure and passes it to a system routine which throws the exception. Throwing an exception passes control to the last exception handler installed, resetting the stack pointer and the processor’s registers along the way. (Receiving an exception is also known as catching the exception.) The exception handling routine can look at the specific exception and decide whether to fix the problem or to pass the exception to the next handler in the list.

Magic Cap’s exceptions are all subclasses of Exception so a package can define its own exceptions. An exception handler may specify that it catches all exceptions or only those of a particular class. Calling Try() or CatchAll() installs a handler which catches all exceptions. Calling Catch(exception: Object) installs a handler which catches a specific class of exceptions. If your code wants to signal an exception, it should call Fail(exception: Object). Exception handlers are removed from the list in two ways: explicitly, or by catching an exception. Calling Commit() removes the most recently installed handler.

Method ObjectID
MyCardClass_ExceptionDemo(ObjectID self)
 {
    // “volatile” is a C keyword which turns off some optimizations.  In particular, 
    // we want to make sure the following two ObjectIDs are allocated on the stack.  
    // This is a prerequisite for variables that are used in an exception handler.
 volatile ObjectID formOwnerCard = nilObject;
 volatile ObjectID requestedItem = nilObject;
 
 ObjectID exc;   // caught exception
 
    // Push an exception handler on the list, then continue execution.  Pushing the 
    // handler returns nilObject, catching an exception brings control back to here and
    // returns a non-nil object ID.
 if ((exc = CatchAll()) == nilObject)
 {
 requestedItem = NewPreferred(MyItemClass_, nil);

    // Set up a form as the "current form".  We want to use exception handling
    // around this so we can reset to the previous "current form" if any subsequent 
    // operation fails
 formOwnerCard = BorrowForm(self, true);
 
    // do something that might fail...
 
    // Reset the "current form" to its old value
 ReturnForm(self, formOwnerCard, true);
    // We’re at the end of the code that might fail, so remove the exception handler.
 Commit();
 } else {
    // Something went wrong.  If we changed the "current form", 
    // restore the old form.  If we allocated memory, dispose of it.
 if (formOwnerCard != nilObject)
 ReturnForm(self, formOwnerCard, true);
 Destroy(requestedItem);
 requestedItem = nilObject;
    // We’ve handled this exception completely.  If we want 
    // another handler to know about this problem, use Fail(exc);
    // to propagate the exception to our caller
 }
 return requestedItem;
}

Inter- and Intra-Package Communication

Magic Cap’s memory protection services are useful, but what if your package wants to access information in the system or another package? If the system (or a package) places an object ID into a special list, packages can refer to that object by its position in the list instead of using an actual object ID. This alternate form of object ID is called an indexical. Indexicals are a powerful tool in Magic Cap - packages can use them to hold package-specific global variables and to export selected objects for other packages to use. Packages can also use system indexicals for well-known global objects. The system provides indexical values for nearly everything: images, input devices, text styles, colors, sounds, system error messages, line styles, windows, objects describing the system’s current state, and so on. System indexicals deliver a treasure chest of objects for packages.

Packages not only get to read indexicals, but packages also get to replace indexicals with their own object references. Packages can change both Magic Cap’s appearance and behaviors in this way. For example, an enhanced Calendar program could replace the Datebook viewable on the desk or the Datebook object itself with a custom version.

Packages can also export code. Developers can release the class numbers for classes defined in their packages and the citation codes used to identify their packages to Magic Cap. Given these two pieces of information, a developer can instantiate objects using the classes defined in another package while leaving the original package untouched.

Graphics in Magic Cap

Magic Cap’s graphics system is built around Viewable and its subclasses. Magic Cap already includes viewables for most things that you want to draw: bitmapped images, text, shapes, lines, boxes, arbitrary paths, lists of other items, and so on.

The fundamental viewable in most packages is a Scene which contains the package’s other viewables as its subviews. Each viewable acts much as a Macintosh GrafPort does: it sets up a clipping area within its bounds and supplies a local coordinate system. Each viewable is also responsible for drawing itself when Magic Cap requests it; like the Macintosh, Magic Cap keeps track of which viewables are “dirty” and need redrawing. Magic Cap also buffers the screen image through an intermediate bitmap so that drawing is always flicker-free.

While any viewable can respond to the user’s touch, some viewables have been specialized for just this purpose:

Icons go to a destination scene when touched

Gadgets open a target window (which may contain additional viewables)

Buttons execute some code directly

SimpleActionButtons invoke an operation on a target object.

We’ll discuss viewables at greater length in a future article.

Other Ways To Program Magic Cap

Not all of the code on a communicator has to be compiled 68349 code. Magic Cap also interprets two additional languages - Magic Script and Telescript. We’ve already described Telescript as a language for building distributed systems and the language upon which AT&T built PersonaLink Services. Magic Script is a powerful yet easy to use scripting language built into Magic Cap. Magic Script gives developers direct access to selected classes and operations, so developers can use it to control packages without writing C code. In fact, there is a one-to-one correspondence between Magic Script statements and Magic Cap operations.

Building a Package

Let’s put all of this knowledge to work in constructing a new Magic Cap package. At a minimum, package development involves three files:

packageName.Def which defines the custom classes for a package

• Objects.Def which resembles a Macintosh Rez source file in that it lists the code and data objects that go into a package.

packageName.c which implements the methods for the classes defined in packageName.Def.

These files are built into a package using a standard Macintosh C compiler and linker, and General Magic’s custom ObjectMaker program. Object Maker performs several functions while building a package: it creates C calling interfaces for the classes in packageName.Def, it compiles the descriptions in Objects.Def into actual objects, and it merges the compiled and linked C code into the final package. Magic Developer, General Magic’s fundamental development environment, runs all of these tools within Apple’s Macintosh Programmer’s Workshop.

Magic Developer is part of the standard Magic Cap Software Development Kit. The development kit includes a special Developer’s edition of Magic Cap which runs on any Macintosh with a 68881 FPU (or a Power Macintosh with an emulated FPU.) This kit also includes several sample packages, a code browser, and online documentation.

One of the sample packages is EmptyPackage: a package which has the name bar, control bar, and an empty scene in between. Many packages begin life as duplicates of EmptyPackage. One such package is MT-Fortune, MacTech Magazine’s automated psychic advisor. Pressing a button in the package delivers a randomly selected “fortune cookie”-style message to the screen.

Construct a user interface in Magic Cap

One of the first tasks in developing a new package is laying out the user interface elements. Every copy of Magic Cap can be set to use construction mode. This reveals a magic hat full of components for customizing the interface or building new packages. Opening the components section of the Magic Hat gives us both a button and a text box which we’ll place into our scene.

The button and text box provided by the Magic Hat don’t fit our needs precisely - the button has the wrong name and the box is too small. We can fix this by touching the tool holder in the control bar and selecting the Authoring tools. These tools allow us to move, stretch, and duplicate objects as well as “tinkering” with the appearance and behavior of each object. (The tinker tool is represented by a small wrench in the tools window.) We can also change nearly any piece of text by creating a text coupon from the keyboard and dropping it on the desired object. We used the authoring tools to stretch and center the text box and to change the button’s name from “button” to “get fortune.”

Write the changes in Object Maker format.

Our original Objects.Def file doesn’t contain these new interface objects, so we have to describe them in the file somehow. The developer’s version of Magic Cap can take a package and “dump” all of its objects into a new Objects.Def file. We’ll do that now, and see that two new objects have been added to the end of the file:

Instance Button 'get fortune' 14;
           next: (TextField 15);
       previous: nilObject;
      superview: (Scene 'MT-Fortunes' 10);
        subview: nilObject;
 relativeOrigin: <-2.0,90.0>;
    contentSize: <88.0,21.0>;
      viewFlags: 0x70101200;
     labelStyle: {60,13}; // (TextStyle 8767)
          color: 0xFF000000;
       altColor: 0xFF000000;
         shadow: nilObject;
          sound: {33,11}; // (Sound 'Touch’ 289)
          image: nilObject;
         border: {120,19};  // (BorderImage 'But1Up’ 213)
End Instance;

Instance TextField 15;
           next: nilObject;
       previous: (Button 'get fortune' 14);
      superview: (Scene 'MT-Fortunes' 10);
        subview: nilObject;
 relativeOrigin: <-5.0,-32.0>;
    contentSize: <236.0,129.0>;
      viewFlags: 0x700D1200;
     labelStyle: {60,13}; // (TextStyle 8767)
          color: 0xFF000000;
       altColor: 0xFF000000;
         shadow: nilObject;
          sound: nilObject;
         border: {120,103}; // (BorderImage 1512)
     fieldFlags: 0x01040000;
      dataStore: nilObject;
      baseStyle: {60,1};  // (TextStyle 8734)
End Instance;

Two things become obvious when you first look at these objects: they’re subviews of the scene (see the superview field), and they’re connected in a doubly-linked list. This is typical of viewables.

The next, previous, and superview fields contain typical references to other numbered objects in the same package or references to nilObject (Magic Cap’s way of saying “this field intentionally left blank.”) However, if you look at the button’s sound field or either border field, you’ll see an unusual value in curly brackets, e.g., {60,1}. These values refer to system indexicals, the system-wide global variables we mentioned earlier.

Create supporting classes and objects.

We now have an interface for our package, but it doesn’t do anything special yet. We still need to create a class which can generate and display fortunes. Then we’ll attach a Magic Script script to the button to get a fortune from this class and drop the result into the text field. (We could simply subclass Button to create and display a fortune when pressed, but that would be less interesting.)

Creating a new class begins in another Object Maker file, MT-Fortunes.Def in this case. We’ll add the definition for a new class which can generate and return fortunes on demand.

Define Class FortuneMaker;
 inherits from Object;
 
// Two data values: a block of characters that contains all of our fortunes (separated by 
// newlines) and a number which refers to the fortune currently being displayed.
 field fortunes:  Text, getter, setter;
 field fortuneNum:  Unsigned;

// An attribute used for reading and writing the “fortunes” field above.
 attribute Fortunes: Text; 

// A bit of code to select and return a fortune.  The options after “Text” make this 
// operation visible to Magic Script.
 operation GetFortune(): Text, safe, common, scriptable;
End Class;

This class includes a long text object which contains all of the possible fortunes, an integer which stores an ID number for the last fortune returned, and attributes to read and write the text string. This class also defines an operation to generate and return a new fortune string. The suffix safe, common, scriptable makes this operation available to Magic Script so we can demonstrate scripting later.

Now that we have a template for the class, we must write its GetFortune operation. MT-Fortunes.c contains this code:

Method ObjectID
FortuneMaker_GetFortune(ObjectID self)
{
 ObjectID newFortune = nilObject;
 ObjectID ourFortuneText;
 TextRangeselectedLine;
 short  numLines;
 unsigned newFortuneNum;
 
    // Get a reference to our "fortune" field, which is a Text object,
    // then count the lines in this field
 ourFortuneText = Fortunes(self);
 numLines = Lines(ourFortuneText);
 
    // Pick a new fortune randomly, checking to make sure that it
    // isn’t the same fortune we’re already displaying
 for (;;) {
 newFortuneNum = ShortRandom() % numLines + 1;
    // Read our "fortuneNum" field without using an attribute
 if (newFortuneNum != Field(self, fortuneNum)) {
    // Store the new value
 SetField(self, fortuneNum, newFortuneNum);
 break;
 }
 };

    // Select a random line in this field and build a text 
    // object in transient memory containing the selected text.
 LineToTextRange(ourFortuneText, newFortuneNum, false,
     &selectedLine);
 newFortune = CopyTextRangeTransient(ourFortuneText,
 &selectedLine);
 
 return newFortune;
}

This code reveals several facts about Magic Cap programming. First, note that the object references are all untyped object IDs. Magic Cap defers object type checking until runtime. Next, we’re using Fortunes() which is a getter attribute that reads our fortunes field. We requested one of these by appending getter to the field in MT-Fortunes.Def. We didn’t request an attribute for fortuneNum, so we’re using the built-in functions Field() and SetField() to read and write this field. Finally, we’re returning our result by creating a new Text object in transient memory. Since we’ll take this object and copy its contents elsewhere, we didn’t need to allocate it in persistent RAM.

We now have the definition and code for a class, but our package doesn’t actually contain any objects of this class. We need to go back to Objects.Def and add a FortuneMaker object:

Instance FortuneMaker 17;
     fortunes: (Text 'fortunes' 18);
   fortuneNum: 0;
End Instance;

Instance Text 'fortunes' 18;
       text: 'You will meet a tall, dark stranger\n';
End Instance;

The above lines add our object to the package, but the package doesn’t have any way to refer to them. If a package needs to refer to specific objects, most programmers create a list of references to those objects and place them into one of the package indexicals. Just as a system indexical represents an object available from anywhere in Magic Cap, a package indexical represents an object available from anywhere in the package. We’ll put our FortuneMaker object into a list then install it into one of our software package’s indexical lists.

Instance ObjectList 'Indexicals' 16;
         length: 1;
      entry1: (FortuneMaker 17);
End Instance;

Instance SoftwarePackage 'MT-Fortunes' 1;
         length: 32;
    dateCreated: 49771;
    timeCreated: 0xFFFFFFFF;
   dateModified: 49771;
   timeModified: 0x041B65B0;
         author: {141,1}; // (ProviderAddressCard 874)
    installList: (ObjectList 'Install' 2);
      receivers: (ObjectList 'Receiver' 3);
   installFlags: nilObject;
installParameters: nilObject;
 installTargets: nilObject;
   autoActivate: true;
       citation: (Citation 4);
      publisher: {141,1}; // (ProviderAddressCard 874)
persistentShadowSize: 0;
persistentChangesSize: 0;
  transientSize: 0;
gotoActionSelector: 3.s;
         hidden: false;
   dontSaveData: false;
 copyOnActivate: false;
 dontDeactivate: false;
     needsReset: false;
systemPackageReserved6: false;
    // skipped a range of reserved fields, all of which are nilObject
systemPackageReserved16: false;
         entry1: nilObject;
    // skipped more empty fields
         entry6: (ObjectList 'Standard Places' 5);
    // skipped more empty fields
         entry9: (ObjectList 'Objects With Help' 6);
        entry10: (ObjectList 'Help On Objects' 7);
    // skipped more empty fields
        entry13: {40,7}; <$f"Garamond-Book">// (Scene 'Hallway’ 88)
    // skipped more empty fields
        entry25: (ObjectList 'Indexicals' 16);
    // skipped more empty fields
End Instance;

Note: We didn’t have to set up any of the fields of this object except for the indexical we installed. The values were copied from EmptyPackage, the sample used to start the MT-Fortune package.

Add the script

Since we want to tie the FortuneMaker object to the button with a script, it’s time to compile the package and run it. Once we’re in the package, we can select the tinker tool, hold down the option key, and touch the button to edit its script.

Magic Script is extremely easy to use. Touching the ink well at the right side of the window inserts a new statement into the script, with the entries for the command and the responder (the object which will execute the operation corresponding with this command) underlined. You can touch an underlined object to change it, or touch an underlined field to get a pop-up menu of all possible commands that go there. While a full discussion of Magic Script is beyond the scope of this article, you can get all of the details from the documentation in the software development kit.

Once we’ve added a script to the button, our package is nearly done. The package should be dumped back into Objects.Def so we can build future versions which contains the script. Objects.Def also contains information about the package’s authors and some help text; these should be updated. Still, you’ve seen enough that you should be able to begin experimenting with the Magic Cap software development kit as soon as you get one.

Starting Down The Road To Magic Cap

Now that you’ve taken a look inside Magic Cap, you may be wondering how you can bring your software to this powerful new platform. General Magic has teamed up with Metrowerks to release Magic Cap software development tools by the summer of 1995. You can receive information about General Magic’s developer program and a notice when the development kits become available by sending electronic mail to dev-info@genmagic.com or by calling (408) 774-4000.

 
AAPL
$102.50
Apple Inc.
+0.25
MSFT
$45.43
Microsoft Corpora
+0.55
GOOG
$571.60
Google Inc.
+2.40

MacTech Search:
Community Search:

Software Updates via MacUpdate

VueScan 9.4.41 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
Cloud 3.0.0 - File sharing from your men...
Cloud is simple file sharing for the Mac. Drag a file from your Mac to the CloudApp icon in the menubar and we take care of the rest. A link to the file will automatically be copied to your clipboard... Read more
LibreOffice 4.3.1.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
SlingPlayer Plugin 3.3.20.505 - Browser...
SlingPlayer is the screen interface software that works hand-in-hand with the hardware inside the Slingbox to make your TV viewing experience just like that at home. It features an array of... Read more
Get Lyrical 3.8 - Auto-magically adds ly...
Get Lyrical auto-magically add lyrics to songs in iTunes. You can choose either a selection of tracks, or the current track. Or turn on "Active Tagging" to get lyrics for songs as you play them.... Read more
Viber 4.2.2 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device,... Read more
Cocktail 7.6 - General maintenance and o...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
LaunchBar 6.1 - Powerful file/URL/email...
LaunchBar is an award-winning productivity utility that offers an amazingly intuitive and efficient way to search and access any kind of information stored on your computer or on the Web. It provides... Read more
Maya 2015 - Professional 3D modeling and...
Maya is an award-winning software and powerful, integrated 3D modeling, animation, visual effects, and rendering solution. Because Maya is based on an open architecture, all your work can be scripted... Read more
BBEdit 10.5.12 - Powerful text and HTML...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more

Latest Forum Discussions

See All

Qube Kingdom – Tips, Tricks, Strategies,...
Qube Kingdom is a tower defense game from DeNA. You rally your troops – magicians, archers, knights, barbarians, and others – and fight against an evil menace looking to dominate your kingdom of tiny squares. Planning a war isn’t easy, so here are a... | Read more »
Qube Kingdom Review
Qube Kingdom Review By Nadia Oxford on August 29th, 2014 Our Rating: :: KIND OF A SQUARE KINGDOMUniversal App - Designed for iPhone and iPad Qube Kingdom has cute visuals, but it’s a pretty basic tower defense game at heart.   | Read more »
Fire in the Hole Review
Fire in the Hole Review By Rob Thomas on August 29th, 2014 Our Rating: :: WALK THE PLANKUniversal App - Designed for iPhone and iPad Seafoam’s Fire in the Hole looks like a bright, 8-bit throwback, but there’s not enough booty to... | Read more »
Alien Creeps TD is Now Available Worldwi...
Alien Creeps TD is Now Available Worldwide Posted by Ellis Spice on August 29th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Dodo Master Review
Dodo Master Review By Jordan Minor on August 29th, 2014 Our Rating: :: NEST EGGiPad Only App - Designed for the iPad Dodo Master is tough but fair, and that’s what makes it a joy to play.   | Read more »
Motorsport Manager Review
Motorsport Manager Review By Lee Hamlet on August 29th, 2014 Our Rating: :: MARVELOUS MANAGEMENTUniversal App - Designed for iPhone and iPad Despite its depth and sense of tactical freedom, Motorsport Manager is one of the most... | Read more »
Motorsport Manager – Beginner Tips, Tric...
The world of Motorsport management can be an unforgiving and merciless one, so to help with some of the stress that comes with running a successful race team, here are a few hints and tips to leave your opponents in the dust. | Read more »
CalPal Update Brings the App to 2.0, Add...
CalPal Update Brings the App to 2.0, Adds Lots of New Stuff Posted by Ellis Spice on August 29th, 2014 [ permalink ] | Read more »
Baseball Battle Review
Baseball Battle Review By Jennifer Allen on August 29th, 2014 Our Rating: :: SIMPLE HITTINGUniversal App - Designed for iPhone and iPad Simple and cute, Baseball Battle is a fairly fun baseball game for those looking for something... | Read more »
Checkmark 2.1 Update Released, and it’s...
Checkmark 2.1 Update Released, and it’s on Sale for a Limited Time Posted by Jessica Fisher on August 29th, 2014 [ permalink ] | Read more »

Price Scanner via MacPrices.net

Labor Day Weekend MacBook Pro sale; 15-inch m...
B&H Photo has the new 2014 15″ Retina MacBook Pros on sale for up to $125 off MSRP. Shipping is free, and B&H charges NY sales tax only. They’ll also include free copies of Parallels Desktop... Read more
Labor Day Weekend iPad mini sale; $50 to $100...
Best Buy has the iPad mini with Retina Display (WiFi models) on sale for $50 off MSRP on their online store for Labor Day Weekend. Choose free shipping or free local store pick up. Price is for... Read more
13-inch 1.4GHz MacBook Air on sale for $899,...
Adorama has the new 2014 13″ 1.4GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY & NJ tax only. Their price is $100 off MSRP. Read more
It’s Official: Apple Issues Invitations To Se...
Apple has issued one of its characteristically cryptic press invitations for a special event to be held at the Flint Center for the Performing Arts in hometown Cupertino on Sept. 9, 2014 at 10:00 am... Read more
Tablet Shipments To See First On-year Decline...
TrendForce analyst Caroline Chen notes that when the iPad launched in 2010, it was an instant hit and spurred a tablet PC revolution, with tablets so popular that that notebook PC sales stagnated and... Read more
SOBERLINK Releases Apple iOS Compatible Handh...
Cypress, California based SOBERLINK, Inc., creator of the first handheld Breathalyzer designed to improve recovery outcomes, continues to show prominence in the mobile alcohol monitoring space with... Read more
New 21″ 1.4GHz iMac on sale again for $999, s...
Best Buy has the new 21″ 1.4GHz iMac on sale for $999.99 on their online store. Their price is $100 off MSRP. Choose free shipping or free local store pick up. Price is for online orders only, in-... Read more
Smartphone Outlook Remains Strong for 2014, U...
According to a new mobile phone forecast from the International Data Corporation (IDC) Worldwide Quarterly Mobile Phone Tracker, more than 1.25 billion smartphones will be shipped worldwide in 2014,... Read more
Save up to $60 with Apple refurbished iPod to...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
12-Inch MacBook Air Coming in 4Q14 or 2015 –...
Digitimes’ Aaron Lee and Joseph Tsai report that according to Taiwan-based upstream supply chain insiders, Apple plans to launch a thinner MacBook model either at year end 2014 or in 2015, and that... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.