Xtra Developer Kit Examples
This XDK comes with skeleton (template) projects in the Examples folder for
Interrogator, Transition, Sprite, Scripting, Filter, and Tool Xtras.
These templates include projects for Visual C++, CodeWarrior and Xcode.
The Xcode projects are setup to build universal binary targets - for both Intel and PPC processors.
Note that xtras built with Xcode will not work with Director MX 2004 since they are Mach-O format rather than CFM format.
The Codewarrior projects are setup to build for Macintosh Classic or OS X.
The skeleton projects contain source with comments that briefly describe modifications to make to create your Xtra.
There are also a number of working example projects that demonstrate various coding features described in this documentation.
One way to begin Xtra development is to start with a working example that implements many of the features
you plan to provide, and modify it to include your code.
IMPORTANT: You may freely change source files in the example projects.
However, take care in modifying any project settings. These projects provide
a number of standard settings required to make Xtras work correctly.
For information about development environments, please see the readme
file that comes with the XDK.
This release of the XDK includes a folder in the Examples folder called XDKXtras.
It contains prebuilt version of the example xtras that are included in the kit.
Xtra Syntax
The examples include a variety of different coding styles to implement Xtras:
- X_ENTER, X_EXIT, X_RETURN macros: are used to bracket methods in most of the examples (Greeting, EventTest, InkTest, Beep, and TallWide).
This method has been used in previous versions of the XDK.
It was required when the XDK supported 68K and Win31, as well as C development.
- Normal C++ Style syntax: Now that just PPC and Win32 environments are supported, a more familiar C++ style method syntax can be used.
The "DrAccess", "Oval" and all Skeleton examples are written this way.
We also recommend using something like our "exit_gracefully" strategy, which provides one exit point for each method,
and thereby ensures releasing all interfaces/resources that were acquired during that routine.
- MoaTry/MoaCatch exception handling: The "PlaySound" example demonstrates this new method for exception handling.
Using moa_try and moa_catch blocks may simplify syntax by automagically checking the return values on your Moa calls.
Any error gets thrown to a predefined moa_catch block.
See the "moa_try.h" include file for more info.
- XSupport exception handling: An even more powerful exception handling scheme, used by the "Wacky Dialog" example.
See the example for details.
Creating GUIDs
To create globally unique identifiers (GUIDs) for the classes you define in
a Windows Xtra, you need to use the application GenUID.EXE, which is provided
with the Microsoft Visual C++ development environment.
For the Macintosh Classic, use the GenGuid.app file which is found in the Utility folder.
For Macintosh OSX, just use the uuidgen command in the terminal window.
Copy the GUID created by the utility into the class header file.
You need to create a new GUID for each class in a project.
(After copying, be sure to correctly redefine the class that existed in the same line the GUID line is on.)
Description of Examples
Filter
- TileFilter: A basic filter example
- this filter displays a sprite as a series of tiled thumbnail images
- there is a VDL file that can be put in the /Configuration/Props/Filters folder to provide a UI for the filter properties
- this xtra is safe for shockwave
- TileFilter works in Director 11 or later
- a Movie - "tile_filter_test.dir" - is provided to demonstrate the filter in operation
- -
- Skeleton: Template project for a filter xtra
Interrogate
- Greeting: Shows how to implement the Interrogate/Terminate
interfaces which allow you to implement functionality at Director startup
and shutdown times. When this xtra is is available a greeting dialog is presented
during Director startup.
- Greeting works in Director 7 and later.
- -
- Skeleton: Template project
Script
- DrAccess: Implements global and instance level Lingo commands. Uses several callbacks
and interfaces, including Director Player, Movie, Cast and Score access.
- The DrAccess Xtra is NOT "safe for shockwave" so it will not run in a browser
- Although Draccess works in D7 and later, the companion Director files (DrAccess.dir, DrAccessAssistant.dir, and DrOffice.cst)
are in D8 format.
- DrAccess.dir was modified from the version included in the D8.5 XDK:
- fixed lingo errors in saveMedia, readMedia & xferMedia members
- score access section uses the same sprite for both buttons
- fixed crash bug in drascrp.cpp: code had "=" (assignment) when it really needed "=="
(equivalence). The problem was in both of the castmemprop routines
- called Commit() in drascrp.cpp/XScs_SetScoreSpriteProp so the changes are saved in the score
- Use Macintosh GetWindowBounds call in dracscrp.cpp for Xcode development
- Change DrFixMediaHeader calls to be used on Intel macintosh as well as Windows machines in drmedfix.c and dracsrp.c
- -
- Valuechecker: A lingo script example. Shows how to access complex lingo datatypes within an xtra: lists,
points, rects, numbers. Shows receiving a list of values from lingo as well returning a list of values to lingo. If version
8.5 (or later) of director is running, this Xtra also uses the vector/value interface. Designed to run with the sample
movie.
- The Valuechecker Xtra is safe for shockwave
- This xtra has version information for windows and macintosh
- Valuechecker.dir is the companion Director movie (in D8 format)
- There is an HTML wrapper for the test movie
- -
- XArray: Shows how to add a new object type to lingo with the IMoaMmXValue interface.
Creates a new XValue object (in this example the object is an array) and shows how to do property and handler access with the object.
Also demonstrates how to use the IMoaMmXValueUtils conversion routines.
- XArrayTest.dir is the companion Director movie (in D8.5 format). It shows how to access all the properties and methods of the XArray object in both lingo and Javascript
- The XArray Xtra is safe for shockwave and there is an HTML wrapper for the test movie
- -
- Skeleton: Template project for a script xtra
- -
- Skeleton2: Alternate template project for a script xtra.
- uses a .r file to specify version and xtra resources for the Macintosh
- uses a .rc file to specify version info for the Windows OS
- source files are less peppered with comments than the other template source
- uses moatry/moacatch macros for exception handling
- uses a single source and header file rather than the multiple files of the other skeleton projects
- just assign a GUID for the project and you will be able to build and run a functioning script xtra
Sprite
- EventTest: Spews Sprite events to the message window. Handy to familiarize yourself with the order of events
in a Sprite Xtra.
- EventTest.dir is the companion Director movie (in D7 format)
- There is an HTML wrapper for the test movie
- The EventTest example is safe for shockwave
- -
- InkTest: Uses the Blit2 interface to blit to its own offscreen GC.
This enables the sprite to support new D7 features such as rotation and skewing, as well as the old Blit functionality
(for this example in particular the ability to set the inkmode of the sprite).
- InkTest.dir is the companion Director movie (in D7 format)
- There is an HTML wrapper for the test movie
- The InkTest example is safe for shockwave
- itasset.cpp: use QDGetPictureBounds call for intel Macintosh
- -
- Oval: Basic Sprite / Asset Xtra example.
- Also shows how to stream props and media to/from the Director movie, and shows how to use ForceMediaLoad and ForceMediaUnload
to load and unload asset media on demand. The media and props in this example are not real, they have been inserted for
demonstration purposes.
- OvalSprite.dir is the companion Director movie (in D7 format)
- There is an HTML wrapper for the test movie
- This xtra has version information for windows and macintosh
- The OvalSprite example is safe for shockwave
- The OvalSprite asset supports the "image" property and returns an image object (new Director 8.5 feature)
- oval.txt defines a property inspector page for this Xtra. Copy oval.txt
into Props/Member/ folder of the Director application.
- -
- PlaySound: Shows how to use the IMoaDrSound interface to implement a
simple sound player (supports AIFF, Wav, and SWA sounds). The type of sound is determined by the file extension (a more
robust implementation is recommended). Properties are not persistent.
- The Xtra does not store the path and file name of the sound file in the cast member. The example movie keeps this information
in a script.
- PlaySoundDemo.dir is the companion Director movie (in D7 format)
- The Macintosh project does not use the cfmruntime.lib library, but instead links with standard CodeWarrior libraries
- The PlaySound example uses Mix Services and the SWA Import Export Xtra in order to play the SWA sound. Director relies
on Mix Services and various other Sound xtras to be present in order to import and play the different sound formats that
it supports.
- In order to reliably use IMoaDrCastMem::GetMedia, IMoaDrCastMem::SetMedia and IMoaDrCastMem::AttachMedia on sound cast
members, you need to have the following Xtras available:
- Mix Services
- Sound Import Export
- any other sound Xtras (e.g. SWA Import Export, MPEG3 Import Export, etc.) that are required for the type of sound
media in the member.
- Important Note: These Xtras are always available during authoring and they are automatically packaged up by default
in projectors. This needs to be considered for Shockwave movies and for projectors that are not created with the default
set of Xtras.
- -
- Skeleton: Template project for a sprite xtra
- -
- Wacky Dialog: shows how to write an interdependent Sprite Asset and its author-time properties dialog. There
are two projects for this example. The Dialog Project creates the Xtra that implements the dialog box that appears at
author time. The Asset Project creates the sprite asset itself; it is active at author and playback time. Features for
this example:
- Implements a complex MUI Dialog.
- This Xtra runs with Director 8 and later.
- Separates runtime and UI Xtras for smaller Shockwave download (i.e. just the runtime component is needed to run
in Shockwave).
- Uses the XSupport lib for many helper functions.
- The runtime Asset xtra is marked safe for shockwave, the dialog xtra is not
- Now both Macintosh projects have been setup with Classic and Carbon targets
- asset.cpp: Xcode. Change prop streaming to deal with byte swapping on Intel Macintosh.
- Once you've compiled the two Xtras, place them in Director's Xtras folder. Launch Director, and from the Insert menu,
select Sprite Examples > Wacky Dialog. The Wacky Dialog itself will appear and let you set the text that will appear within
the sprite. The purpose of the dialog box is to show how to create all the different kinds of dialog-box elements. Not
all of the controls actually do anything.
- To show that the asset Xtra works independently of the dialog Xtra, remove Wacky Dialog from the Xtras folder and run
the movie. It works ... but you cannot change the asset's properties. Quit Director and remove Wacky Dialog Asset. Now
if you try to open the movie, you will get an alert stating that the required asset Xtra is missing.
Tool
- Beep: demonstrates a basic Tool Xtra
- -
- ComputerUser: Simple movie edit tool
- this tool does not present any UI
- running the tool creates a new text member, populates it with text and adds a sprite to the score that uses the member
- it shows how to combine system specific Unicode strings and text from Director
- the computer name and computer user name are obtained from the operating system
- the move name and movie path are obtained from the movie
- It demonstrates creating both castmembers and score
- -
- Skeleton: Template project for a tool xtra
Transition
- Skeleton: Template project for a transition xtra
- -
- TallWide: Transition Xtra demo
- also shows streaming of props into/out of Director movie
- demonstrates a throttled animated thumbnail
- uses a native property dialog and About box.
- tallwide.dir is the companion Director movie (D7 format)
- There is an HTML wrapper for the test movie
- The TallWide example is safe for shockwave
- In the transition dialog box, tallwide appears in the "transition examples" category
- To adjust options using the Director UI click on the "options" button in the transition dialog box
- twasset.cpp: Minor change so source compiles in CodeWarrior 6 or CodeWarrior 8 without problems.
- twasset.cpp: Xcode. Change prop streaming to deal with byte swapping on Intel Macintosh. Remove unused variables.
- tallwide.rsrc:
- Moved OK button to Item 1 and removed unused static text.
- Expanded width of OK/Cancel buttons so the text on OS X is not truncated.