This page contains Magic Cap sample packages created by various members of GMDTS, past and present. These packages tend to be small, exercising specific areas of the Magic Cap API. The source code is liberally interspersed with comments, so you can learn exactly why you need to call a particular method.These samples ship with every CodeWarrior CD, but we'll be putting the latest versions of these samples as well as new sample packages on this page as they're completed.
All Magic Cap packages have a minimum set of required objects. These sample packages represent the basic minimum set of code and objects you'll need for almost any Magic Cap package you can write.
EmptyPackage is the simplest Magic Cap package. It contains the minimum number of objects required in a package that contains a scene. This package is the perfect place to start if you're starting a new package completely from scratch.
What's a programming language without a Hello World sample? The HelloWorld package demonstrates the basics of creating separate classes and objects in Magic Cap. The instance definition file for HelloWorld is filled with comments about the types of data you can fill your instance fields with.
The SimpleStack package shows you how to use the StackOfCards class. It's useful as a template for constructing packages that are stack based, like the notebook or name cards file. SimpleStack also shows you the basic relationship between forms and cards.
Cards are not particularly efficient at storing large amounts of data. SingleCardScene demonstrates a method for maximizing the amount of data you can stuff into Magic Cap by simulating a stack of cards, but using an external data manager to store your data.This package shows how to enable the navigation arrows in the name bar, how to file data that is not stored on cards or in tasks, how to opaquely manage that data, and how to use exception class hierarchies.
A lot of little things go into making a Magic Cap package feel like it's a Magic Cap package, be it stamps in the stamper, rules in the magic lamp, or tools in the tool cup. These packages show you how to implement a number of these "little things."
AccessDemo is an example of setting instance variables, what Magic Cap calls fields, in several different ways. It also demonstrates how to have an object behave like the totebag that's in the command bar.AccessDemo demonstrates creating attribute interfaces for auto-getters and auto-setters, and how and why to call MakeUsable() and MakeStorable().
The Arranger and ClientPackage sample packages demonstrate package to package communication. These two packages demonstrate how one package can instantiate instances of, and dispatch against, classes that are defined by another package.Arranger is a faceless package - it does nothing to visibly affect the user interface. It consists of a class that can be used by other packages to install items into the Stamper. This class implements a method called InstallIntoDrawer() which creates a new bank of drawers each time it's called.
ClientPackage provides the user interface. It uses an instance of creating an instance of the class defined in the Arranger package to install its objects into the Stamper. ClientPackage demonstrates using the Import() method to create instances of other package classes.
CardDataExtracter is a package that implements a custom form element, FormBox, that can store and retrieve an image and some raw data from the data portion of a card. The source file describes what methods you need to implement to create your own form element.CardDataExtracter can also take the data from the cards in its stack and export this data into a list maintained by the CardDataLister package. CardDataLister contains a list view that allows you to view that data in an alternate format.
DigiClock demonstrates installing objects into existing places in Magic Cap; it puts a digital clock (well, it's just a button that displays the time) in the "office" drawer of the stamper.DigiClock shows how to use InstallInto() to implement custom installation code.
HelloScripting teaches you how to use MagicScript to invoke operations of a class you've created. The comments in this package provide a walk through tutorial on how to define your methods so that they can be called from a script, and how to create the script itself in the simulator.HelloScripting shows you how to use the safe and common keywords from your class definition files.
The package scene is the scene that is displayed when the user taps ona package's storage box in the storerooom. Along the right edge of this scene are five buttons. From top to button, they are: Pack/Unpack, Go to, Guide, Credits and Response. This package shows how to enable the Guide, Credits and Response buttons.
The RulesSample package demonstrates how to construct Magic Cap rules. It provides samples of simple rules, which utilize the built in behavior defined by the LocalRuleAction and LocalRuleQualifier classes as well as showing a more complicated custom rule.This package also shows how triggers relate to rules and how to invoke triggers.
Scenes is a simple package that demonstrates having multiple Scene objects in a package. It also shows how to install scene specific viewables in the stamper as well as how to create custom doors and buildings.
Most of the scrolling text you see inside of Magic Cap is in the form of cards. Sometimes, it would be nice to scroll text in an area that's somewhat smaller than most of the screen. The ScrollableTextField package implements a box that can scroll text of arbitrary length inside.
Some packages have come out with the cool capability of dragging large images around the screen at incredible speed. This package contains three framework classes that allow you to drop this functionality into your own packages.This package shows you how to work with purgeable objects and how to use the CopyPixels() method. SpeedScrollSample also demonstrates how to leverage the object oriented nature of Magic Cap to break functionality into multiple classes and let clients pick and choose which features they want to have.
The WindowTool package shows you how to set up your own page of tools in the tool cup and how to make your own Tool subclass. WindowTool creates four tools that allow you to create windows directly in the Magic Cap interface instead of creating one by hand in your instance definition file.
Underneath the friendly interface of Magic Cap lies a powerful object runtime. These packages show you how to take advantage of this runtime to do multiple threads of execution, to properly handle error conditions, and to use memory efficiently.This section looks a little sparse now, but you'll see more packages that deal with the underpinnings of Magic Cap in the near future.
The Exceptions package demonstrates simple exception handling in Magic Cap. Magic Cap provides two methods for lightweight exception handling, Try() and Catch(). This sample shows the difference between the two when catching out of memory exceptions.
Magic Cap means communication. These sample show you the myriad ways you can utilize the communication capabilities of Magic Cap in your own packages.
CujoTerm shows how to do low-level and TCP/IP communications with Magic Cap. CujoTerm has its own page with more information on what it does and why it is useful.
Gordon Sheridan of GMDTS has this to say about ShackMail: "ShackMail is the definitive source of information on how to set up your own Magic Cap front end to anelectronic mail service. Its functionality is belied by its interface."Seriously, just about every electronic mail service front end in existence on Magic Cap started from ShackMail. It shows you how to install custom ElectronicMailLabel stamps in the stamper; how to interact properly with the in and out boxes; and how to send and collect messages from Magic Cap, either as plain text messages or as wireline encoded telecards.
TimeMinder uses the Telenumber class and builds a dialable phone number. Unlike most other sample packages, TimeMinder actually does something useful; it connects to a time service and synchronizes Magic Cap's clock to this time.
These simple packages are more complex than your run of the mill sample package. They don't demonstrate one particular area of Magic Cap. Instead, they use a variety of techniques to do whatever it is that they need to do.
Miscellany contains a variety of demos and samples. In general, each demo will be on a single card of a stack. Miscellany is a great example of how not to write a package.The BoxWatcher card shows that tools don't necessarily need to reside in the tool cup. The code implemented by the BoxWatcher class demonstrates how to add to an object's extra data area.
The MacCom card demonstrates the use of Stream objects. The code behind this code writes bytes out to a file, so this demo only works on the simulator.
The AttributeText card demonstrates how to wire together AttributeText objects. This is not the simplest thing in the world to do, so be sure to read up on this topic.
ActorDemo provides a demonstration of creating new threads of execution, which are known as actors in Magic Cap. This sample also demonstrates the use of the Semaphore class to make actors block on certain events.
The PrintDemo card shows how to create a ContentProxy object so that the user can print or fax from your package.
Finally, the DebugInfo card, which works only in the simulator, demonstrates some of the logging macros that area available to you. These macros will write out messages to the log file created by the simulator.
Puzzle is an implementation of a common toy/game involving 15 moveable tiles laid out in a square grid. Puzzle shows you how to:
- create resizable viewables that know how to draw their own contents, and how to do hit testing on themselves
- accept coupons using the CanAccept() and AppleImage() methods
- swallow morsels using the Swallow() method
- attach a Switch attribute to your object
TicTacToe is a simple game that demonstrates the interactive nature of the development process for Magic Cap. Among many other things, TicTacToe demonstrates how to:
- create scriptable operations and assign operation numbers to them
- use scripts to pass parameters
- access fields of a fairly complex object using both [Set]Field() and ReadFields()/WriteFields()
- iterate using the Each() call
- convert between a Text object and a Pascal style string
Back to Tech Docs