Xtra Developer Kit Examples
About the Examples Folder
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++ and Xcode.
The skeleton projects contain source with comments that briefly describe modifications to make to create your Xtra.
All of the sample movies have been updated to D11 format.
Older versions of the movies can be found in older XDKs posted on the Adobe Exchange.
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.
There are also a number of working example projects that demonstrate various coding features described in this documentation.
An alternate 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.
This release of the XDK includes a folder called XDKXtras which contains prebuilt version of the example xtras
that are included in the kit.
All of the projects have now been setup to place their output into a common folder.
There is also an "AllExamples" master project that can be used to build all of the examples.
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.
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, and was useful for C/C++ development.
- Normal C++ Style syntax: This is a simpler standard C++ style method syntax can be used.
The "DrAccess", "Oval" and all Skeleton examples are written this way.
- 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
an Xtra, you can use the Windows application GenUID.EXE, which is provided
with the Microsoft Visual C++ development environment.
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.
Tip: 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 to demonstrate the new sprite filter interface
- 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
- a Movie - "tile_filter_test.dir" - is provided to demonstrate the filter in operation
- The TileFilter example is safe for shockwave and there is an HTML wrapper for the test movie
- -
- 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.
- -
- 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
- Recent changes:
- - 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
- - Add error checking to XPly_ResolveFileName in dracscrp.cpp so it will behave properly if used to resolve a non-existant file
- - Change XX_MoaFileWrite in dracscrp.cpp to generate full path to file since just using a simple name does not work in D11
- -
- 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. 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
- 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. 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
- 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
- There is an HTML wrapper for the test movie
- The InkTest example is safe for shockwave
- Recent changes:
- - 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
- 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
- oval.txt defines a property inspector page for this Xtra. Copy oval.txt
into Coniguration/Props/Member/ folder.
- -
- 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
- 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.
- 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
- Recent changes:
- - asset.cpp: Change prop streaming to deal with byte swapping on Intel Macintosh.
- - adjust Macintosh layout for checkboxes in dialog.cpp so they don't get clipped
- 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 editing Tool
Xtra
- new to the XDK this release
- running the tool creates a new text member, populates it with text and adds a sprite to the score that uses the member
- the code 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
- this tool does not present any UI, but 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
- The TallWide example is safe for shockwave and there is an HTML wrapper for the test movie
- 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
- Recent changes:
- - twasset.cpp: Change prop streaming to deal with byte swapping on Intel Macintosh.
- - Remove unused variables.