Magic Cap Developer Resources

Migrating from Magic Cap 1.0


Last Revised: 1/16/96

Audience

If you wrote a package using the 1.0 interface files, you need to read this document to determine whether your package will run on a Magic Cap 1.5 communicator.

Introduction

While we tried to keep Magic Cap 1.5 totally compatible with Magic Cap 1.0, there are some isolated parts of the system which are different enough that packages using certain classes, operations, and fields may not work under both versions. We provide these notes, as well as the three sets of interface files in order to address this issue. The Universal Interfaces were designed to build packages that run on both versions of Magic Cap. Classes, fields, operations, and attributes which did not exist on both platforms, or whose interface changed from 1.0 to 1.5, were removed from these interface files. The Only 1.0 Interfaces are the original Magic Cap 1.0 interfaces. You may use these only if you know your package will never be used on a Magic Cap 1.5 communicator. You might want to use these if your package depends on features that existed only in Magic Cap 1.0. The Only 1.5 Interfaces are the new Magic Cap 1.5 interfaces. You may use these only if you know your package will never be used on a Magic Cap 1.0 communicator. You might want to use these if your package needs to take advantage of new Magic Cap 1.5 features.

Testing for Compatibility

If your package rebuilds successfully with the new universal interfaces, you can assume that the package you built with the 1.0 interfaces is compatible with communicators running either version of Magic Cap. There are, of course, a few exceptions which we will enumerate in the following section.

Exceptions

If your package uses the following classes read the interface changes listed and decide whether they will effect the package's operation under Magic Cap 1.5:

Ramifications of Instant On

The instant on feature of Magic Cap 1.5 means that transient memory is not lost when the device is powered down and Load() will not be called when the user powers on the device, but Reset() will be. If your package needs to do some initialization when the user powers up the device, use Reset().

Using the Universal Interfaces

The universal interfaces are the preferred set of interfaces you should use to develop Magic Cap packages. Applications built on these interfaces will work on communicators running either Magic Cap 1.0 or Magic Cap 1.5.

Using Version Specific Features of Magic Cap

There are several compatibility issues which can best be solved by determining, at runtime, which features the device your package is running on has available; then executing the appropriate code. Greg Marriott and Chris Derossi's presentation at the General Magic Developer's Conference 1995 on Compatibility Guidelines contains the best information on this topic. The slides and notes from this presentation are on the CodeWarrior CD distributed at the conference.

Using the 1.0 Interface Files

You can continue using the existing Magic Cap 1.0 interfaces to develop packages. However, packages built this way might not work on 1.5 based communicators, so we don't recommend this. Even if you don't think your users are ever going to use 1.5 devices, you never know what the future holds, and we've made it relatively painless to be compatible with both versions of Magic Cap. If all this gloom and doom hasn't swayed you, you can still use the old interfaces from the CodeWarrior IDE. In the IDE, go to the Magic Cap Project preferences panel and pick a Magic Cap 1.0 platform target from the Target pop up menu. The old 1.0 interfaces will be used automatically. The MPW version of the development environment only supports building packages with the universal interfaces.

Using the 1.5 Interface Files

While we encourage developers to use the universal interfaces, you might find some features of Magic Cap 1.5 compelling enough that you would be willing to eschew the 1.0 communicators for the chance to use these features. By using the Compatibility Guidelines of Marriot & Derossi you may not have to give up 1.0 compatibility to use 1.5 features.

CodeWarrior Magic/MPW and non-Universal Interfaces

CodeWarrior Magic/MPW as supplied only supports building packages with the universal interfaces. To build using the original Magic Cap 1.0 interfaces, you will need to do the following:
  1. Quit MPW.
  2. Rename your :MagicDeveloper:Interfaces folder to something else, like UniversalInterfaces:.
  3. Copy the Only 1.0 folder from your Metrowerks CodeWarrior:Magic Cap Support:Interfaces:Only 1.0: into your :MagicDeveloper: folder.
  4. Rename the Only 1.0 folder you just copied to "Interfaces."
  5. Launch MPW with at least 10,500K.
  6. Ensure that your target and debug selections are as you desire, and start a Full Build of your package. This will cause the precompiled SystemInterfaces and C dump files to be generated.
If you need to build against the Only 1.5 interfaces, you should follow the above steps, replacing your Interfaces: folder with the Only 1.5: folder. In addition, you will need to use a new version of the ObjectMaker tool. You can find this tool, along with important information about its use, in your :MagicDeveloper:Tools:Magic Cap 1.5 ObjectMaker: folder.

Special Note about 1.5 Interface Files

In Magic Cap 1.0, mixins that did not define any fields were still encoded during wireline encoding. This made it impossible to extend the functionality of a class without changing its wireline format. In 1.5, this was changed so mixins with no fields would not change the wireline format. To maintain compatibility with 1.0, existing field-less mixins are marked with the "encodes empty field list" tag to mimic the old 1.0 behavior.

Sending Telecards Between Different Versions of Magic Cap

If you are using the Universal Interface files, you will have no problems.

Types of Changes in the Universal Interfaces vs. the 1.0 Interfaces

The following list of items is intended to alert developers to these problems, and help them change their packages to become fully compatible with both versions of Magic Cap. The goal of this list is to point out changes that would prevent packages from running on any Magic Cap based communicator, so classes introduced in Magic Cap 1.5 are not detailed here.

Getter/Setter routines removed

Most of the fields which have had their getter/setter routines removed are private fields which shouldn't be accessed directly from outside their class anyway. Use the public attributes if they are available. Packages written for 1.0 using the getter/setter routines will not work on 1.5 devices, and will not build using the universal interface files.

Private Fields removed from the interface

Private fields are fields that are not meant to be accessed from anywhere other than the class's own methods. Even subclasses are not meant to be accessing these directly. We have removed these from the interface files. Code which relied on these fields should use their public attributes. You won't be able to create instances of these classes in your object definition file, but none of these classes should be instantiated anyway.

This class has been removed

These classes were either broken or weren't meant for developer use. In general they should be so esoteric that you would not be using them anyway. If the classes are small enough or simple enough, you should create them as package classes instead of relying on the system to provide them. This approach ensures compatibility on both 1.0 and 1.5.

Operation operationName has been removed

Some operations have been removed or reused in Magic Cap 1.5. These operation numbers are not defined by the universal interfaces. If you use any of these operations, you will get compile errors when you build against the universal interfaces.

Field fieldName is noCopy in 1.0, but not in 1.5 (or vice versa)

Dependence on the noCopy behavior in your package will not get caught during the build process. If your package uses an object with this field, you must decide if the change will impact the operation of your package.

Interface Changes Alphabetically By Class

Actor

Field stackSegment is a private field and no longer has a getter.

Agent

Private fields removed from interface. Use the attributes instead.

AgentStamp

This class has been removed.

BeamWindow

Private fields removed from interface. Use the attributes instead.

CardServer

The values kBatteryLow and kBatteryDead have been swapped to come into adherence to the PCMCIA spec.

ClassList

Operation DisableClass() has been removed.

Clock

Field city is noCopy in 1.0, but not in 1.5.

Cluster

Operations ShadowObject() and Clean() have been removed. This should not affect your package.

Context

Operation SetUpContextRuntime() has been removed. This should not affect your package.

Coupon

Attribute Amount is type Unsigned in 1.0, but it is Signed in 1.5. You can treat the value as Signed.


Operation ApplyAndDiscardCoupon() has been removed, because its interface has changed.

CreditCard and iCreditCardSteps

The defines kVisaType and kAmericanExpressType have swapped values, which makes kVisaType the default credit card selection in iCreditCardTypesText. This also changes the order of credit card types in edit steps and corresponding constants for type checking. If you cannot avoid iCreditCardSteps, you must avoid using the defines to determine which type of card was selected; compare Text values, instead.

Datebook

Private fields removed from interface. Use the attributes instead.


Operation Confirm() has been removed because it no longer exists in 1.5.

EnclosureProxy

This class has been removed.

FaxServer

Private fields removed from interface. Use the attributes instead.

Operation InitFaxModem() has been removed because it no longer exists in 1.5. Magic Cap 1.5 uses Modem_InitFax, which does not exist in MC1.0. Build using the MC1.5 interfaces and make a runtime version check to call the correct operation. If you need to override InitFaxModem(), General Magic has a workaround that will enable you to build a version which works on both MC 1.0 and MC 1.5 using the MPW-based development environment.


Operations ReadHDLC(), WriteHDLC(), DoPhaseB(), DoPhaseC(), and DoTCFTraining() have been removed because their interfaces have changed in 1.5.

FaxWindow

Private fields removed from interface. Use the attributes instead.

FileWindow

Private fields removed from interface. Use the attributes instead.

FolderTray

Private fields removed from interface. Use the attributes instead.

HasContentList

Operation NewFolder() has been removed because it no longer exists in 1.5.

HitCacheWindow

This class has been removed.

ImmigrationPlace

This class has been removed.

InBox

Private fields removed from interface. Use the attributes instead.


Operations EmptyMailbox(), RequestSummaries(), EmptyMailboxForService(), and RequestSummariesForService() have been removed because they no longer exist in 1.5.

InfoWindow

Operation ExtendBottomToFitContent() has been removed because it no longer exists in 1.5.

JPEGImage

This class has been removed.

ListView

Operation ValueAt() is now defined to return an ObjectID. To maintain compatibility, return an ObjectID if the value is an Object, and return nilObject if it is not an Object.

In Magic Cap 1.0, one could display lines of a multi-line text object by specifying the line number desired as the ListView key. This feature has been removed from 1.5 and future versions of Magic Cap.

MacModem

This class has been renamed MacintoshModem.

MacTCP

This class has been removed.

MacWindow

This class has been renamed MacintoshWindow.

MailboxRequestCard

This class has been removed.

MailStack

Field sortKind is now private, because it is used differently in 1.5.


Attribute SortKind has been removed.

MailSummaryCard

This class has been removed.

MailWindow

Private fields removed from interface. Use the attributes instead.

MessageRecord

Private fields removed from interface. Use the attributes instead.


Attribute IsOrdered has been removed.

NameCardsScene

Private fields removed from interface. Use the attributes instead.


Operation AutoUpdateMode() has been removed because it no longer exists in 1.5.

NameCardsStack

Private fields removed from interface. Use the attributes instead.

Object

Operation DispatchLookup() has been removed. It was private, anyway.

Attribute Named is now readOnly. SetNamed had no coherent purpose.


Operations StringData() and EachInspectorField() have been removed.

OrderListView

This class has been removed.

PackageContext

Private fields removed from interface. Use the attributes instead.


Operations DestroyKeepChanges(), MakeAllValid(), MakeAllValidByList(), CleanSystemReferences(), and ForgetClusters() have been removed.

PackageScene

Private fields removed from interface. Use the attributes instead.


Attribute Data has been removed, because it has been replaced with attribute Package in 1.5. If you need to access this information, you will have to determine which version of Magic Cap you are running under at run time, and use the appropriate attribute.

PersonalMessage

Fields blindCopyRecipients, copyRecipients, from, groupCards, replyTo, and toRecipients are defined noCopy in 1.5, but not in 1.0.

Phone

Operation PlayDTMFStr() has been removed, because it no longer exists in 1.5.

PhoneScene

Private fields removed from interface. Use the attributes instead.

PostalLabelStamp

Private fields removed from interface. Use the attributes instead.

PostOffice

Operation InitiateIncomingMagicmail() has been removed.

Power

Operations SleepNow() and WakeUpEventNotify() have been removed.

PrintWindow

Private fields removed from interface. Use the attributes instead.

PurgeableContents

Intrinsic PurgeableContents() has been removed, because its interface has changed in 1.5 (it is now an operation).

RequestAgent

Private fields removed from interface. Use the attributes instead.

Scene

Field additions is noCopy in 1.0, but not in 1.5.

Scribble

Operation Breaks() has been removed because it no longer exists in 1.5.

Scrollable

All the functionality and interface of Scrollable has been moved to a mixin class named HasScrolling in MC1.5. A placeholder class in 1.5, named CompatibilityScrollable, which inherits from HasScrolling will allow objects of class Scrollable to work seamlessly in 1.5. You should use HasScrolling for all new development. If you subclass Scrollable in 1.0, or HasScrolling in 1.5, you need to override either ScrollToEnd(), ScrollToBottom() or both. If not, option-tapping a scroll down arrow will accomplish: in 1.0: nothing will happen, not even scrolling; in 1.5: the two routines will recursively call each other and overflow the stack, thereby resetting the device.

ScrollBox

Fields topArrow and bottomArrow are defined as noCopy in 1.5, but not in 1.0.

SizedList

This class has been removed.

SystemContext

Operation CleanAll() has been removed. This should not affect your package.

TextContainer

This class no longer implements the operations AboutToShow() and AboutToHide(). If your package relies on these overrides, you must subclass TextContainer and implement them yourself.

ToolButton

Field tool is defined as noCopy in 1.0, but not in 1.5.

Way

Field entity is noCopy in 1.0, but not noCopy in 1.5.

Wireline

Operation EnableClasses() has been removed.

Tech Docs Magic Cap in Depth