This guide describes the Director service callbacks, a set of
interfaces that provide access to objects representing internal
data structures of Director. Through these interfaces, you can
directly manipulate almost any feature of Director movies. This
enables Xtras to provide a high level of control over the media
and behavior of a Director movie. Using the Director services,
an Xtra can provide various levels of functionality, from simple
media access and editing tools to complete authoring models providing
alternate ways to create Director movies.
This discussion is in four parts. It begins with an overview of
the Director object model and how it shapes the interfaces provided
by the Director services. The overview is followed by a detailed
look at the interfaces to the model, describing how to use the
Director features available through them. Next, there's a discussion
of several supporting interfaces provided by the Director services
API. Finally, there are several examples of accessing and using
Director services.
For a list of updates to the documentation see Updates
to the XDK.
To allow Xtras to manipulate movies and their contents, the Director
service callbacks represent various objects of Director's internal
model. The abstract model is shown in the following diagram:
At the top of the Director object model is the player, the host
application itself. The player can be the Director authoring application,
a standalone projector, or Shockwave for Director. At the next
level, a player may have one or more open movies, including the
main movie and one or more movie-in-a-window. The next level shows
the two types of subcomponents of a movie, cast and score. A movie
can have several casts, but each movie has only one score. Casts
consist of a number of cast members, each of which presents a
specific type of media or provides a specific kind of behavior.
A movie's score is made up of frames, sounds, and sprites in sprite
channels.
The following diagram shows how Director's callback interfaces
correspond to the Director object model. For simplicity, this
diagram is limited to the top levels of the model: player, movie,
cast, and score. The interfaces for deeper levels--cast members
and score components--are described later in this section.
As shown in this diagram, Director's callback object provides
a number of interfaces including standard MOA callbacks. The Director
callback interfaces include the general interface IMoaMmUtils2
(described in the Multimedia Developer's Guide)
and IMoaDrUtils (whose methods are described where relevant
throughout in this section).
The callback object also provides the IMoaDrPlayer
interface. This interface represents the player at the top of
the Director object model shown in the previous diagram. From
this interface, Xtras can acquire other interfaces and access
other objects in the model.
To get the IMoaDrMovie interface for a movie object,
you call the IMoaDrPlayer methods GetActiveMovie()
or GetNthMovie().
To get the IMoaDrScoreAccess
interface for a movie's score object, you call IMoaDrMovie::GetScoreAccess().
To get the IMoaDrCast
interface for a movie's cast, you call the IMoaDrMovie
methods GetNthCast()
and GetCastFromName().
While this diagram illustrates the general approach to accessing
objects in the Director model, Director callbacks provide a variety
ways to access movie objects and manipulate the media they present.
The remainder of this section describes various techniques for
accessing objects in Director movies in greater detail.
Most interfaces for the objects of the Director model inherit
from the IMoaMmPropOwner
interface. Each type of object in the Director model defines specific
properties that you can access and manipulate through this interface.
For example, a player has properties to represent its authoring
mode and the filename of its executable. A movie has properties
representing its filename, its stage area, and the current palette.
These properties are described in the "Director Properties"
section of the Director API Reference. In the following
discussion, the properties supported by each interface are briefly
enumerated.
Accessing and manipulating media in a movie is central to controlling Director behavior. The Director services API defines two abstract interfaces, IMoaDrMediaOwner and IMoaDrMediaAccess, that enable manipulating media and placing it in a presentation.
The media owner interface, IMoaDrMediaOwner,
defines a general mechanism to get and set the media presented
by an object. Methods of this interface let you acquire media
for examination or editing, and pass media to an object for presentation.
The MoaDrMediaInfo
structure is defined for use in IMoaDrMediaOwnermethods
to pass media data between Director and Xtras.
In the MoaDrMediaInfo structure, media is categorized
by two fields: label and format. The media label specifies the
generic type of the media represented. Typical media label types
represent text, image, and sound. The media format specifies the
specific C type of the data. Typical format types are standard
data types such as RTF or application- or platform-specific data
types such as PICT or DIB.
Two Director services interfaces inherit from IMoaDrMediaOwner:
IMoaDrMovie and IMoaDrCastMem.
A movie can own one label type of media--a score--while a cast
member can own a wide variety of media label types including images,
text, digital video, scores, and so on.
The media access interface, IMoaDrMediaAccess,
defines a general base interface for accessing and editing media.
This interface is intended to be inherited by interfaces for manipulating
specific media types. For example, in the future there might be
a general interface for manipulating bitmap image data. Then,
any object that presents bitmap data, either an internal object
or a media asset Xtra, could provide the same interface. This
would enable the application's standard editor--or an Xtra-defined
editor--to edit any bitmap.
The general behavior defined by IMoaDrMediaAccess provides
ways to get and set the IMoaDrMediaOwnerinterface that
owns the media, as well as the label and format of the media being
accessed. It provides ways to clear the media being accessed,
to update or revert the media by getting a fresh copy from the
owner, and to commit any changes made back to the owner.
Currently, one interface inherits from IMoaDrMediaAccess:
IMoaDrScoreAccess. The IMoaDrScoreAccess
interface, discussed later in this section, provides ways to edit
frames, sounds, and sprites in a movie's score. It also provides
ways to assign the score to a specific owner, either a cast member
or a movie.
This discussion looks at the various interfaces representing the Director object model, describing how you acquire these interfaces and detailing the behavior available through each of them.
The IMoaDrPlayer
interface is provided by Director's callback object. The Director
executable, whether authoring application or projector, provides
one instance of this interface to represent its top-level movie
playing functionality and provide access to other interfaces of
the object model.
Among the capabilities provided by methods of the IMoaDrPlayer
interface are property support, scripting support, access to movies,
access to all available cast member types--both built-in and Xtras--and
file name resolution.
To get access to the application's single instance of IMoaDrPlayer, you call QueryInterface() on any Xtra object's pCallback instance variable. An example of acquiring the player interface is included at the end of this section.
The IMoaDrPlayer interface inherits from IMoaMmPropOwner. The player object supports a number of properties through this interface, all of which are get-only. These are:
Property | Description |
authorMode | Authoring application or a projector |
name | Executable name of host application |
pathName | Path to host executable (including file name) |
folderName | Path to host executable (excluding file name) |
For more details, see "Player properties" in the Director API Reference.
IMoaDrPlayer provides a number of methods that support
calls to Lingo handlers and globals.
To call an arbitrary handler in the currently active movie, use
the IMoaDrPlayer::CallHandler()
method. To let you get and set the values of Lingo globals, IMoaDrPlayer
provides the GetGlobalVarValue()
and SetGlobalVarValue()
methods.
The IMoaDrPlayer interface provides methods that give you access to any movie currently open in Director. The method GetActiveMovie() returns an IMoaDrMovie interface for the currently active movie--that is the movie being processed at the time your Xtra method is called. The GetMovieCount() method returns the number of open movies in the player, while the GetNthMovie() method returns the IMoaDrMovie interface for any open movie.
The player interface provides methods to access any cast member
type currently available in the Director executable, both internal
cast members and Sprite Asset Xtras. Using these methods in conjunction
with methods of the IMoaDrCast
interface, your Xtra can create new instances of any cast member
type and add them to a cast.
The GetCastMemTypeCount()
method returns the number of cast member types currently available,
including all internal Director types plus any Sprite Asset Xtra
types currently registered. The GetNthCastMemTypeSymbol()
method returns a type symbol for the cast member number specified.
GetCastMemTypeDisplayName()
returns the display string for the cast member type.
You could use these methods to implement an authoring or playback
interface that allows the user to select cast members and add
them to a cast. The IMoaDrCast method CreateCastMem()
takes the type symbol returned by GetNthCastMemTypeSymbol(),
creates a new cast member of the corresponding type, and adds
it to the specified cast. For more information, see the discussion
of the IMoaDrCast interface later in this section.
The IMoaDrPlayer interface provides a general method for finding paths to arbitrary files. The ResolveFileName() method takes a character string representing a filename and returns a string representing the path to that file. This method uses Director's standard file search algorithm to locate the path to the file.
The IMoaDrMovie and IMoaDrMovie2 interfaces are used to represent movie objects in the Director framework. You can acquire these interfaces for any open movie, and use them to access various features of the movie it represents. These interface supports access to movie properties, access to the score media and frame labels of a movie, access to the casts and cast members of the movie. They also provide access to graphics contexts for both the offscreen buffer and onscreen window in which the movie is drawn. IMoaDrMovie2 interfaces inherits from IMoaDrMovie, defining three additional methods for manipulating cast member references.
Except where noted, the following sections pertain to both the IMoaDrMovie and IMoaDrMovie2 interfaces. For simplicity, only the IMoaDrMovie interface is specifically mentioned.
There are several ways to get access to an IMoaDrMovie
interface.
The IMoaDrPlayer interface provides two methods for acquiring
the interface of any open movie. The method GetActiveMovie()
returns an IMoaDrMovie interface for the currently active
movie. The GetNthMovie() method
returns the IMoaDrMovie interface for any open movie.
A sprite asset's actor can access the movie it belongs to through
the IMoaDrSpriteCallback::GetMovie()
method. This allows the sprite to interact with its movie. For
more information on implementing a sprite asset and acquiring
the sprite callback interface, see "Asset Xtras" in the Multimedia Developer's Guide.
When using a score access object , you can access the score of
a movie through the IMoaDrScoreAccess::GetAccessInfo()
method. This method populates a MoaDrAccessInfo
structure; upon return, the pOwner field of this structure
contains a pointer to the score's owner, an IMoaDrMediaOwner.
A score's media owner may be either an IMoaDrMovie or
IMoaDrCastMem interface.
To acquire the IMoaDrMovie2 interface, you call QueryInterface() on the IMoaDrMovie interface.
The IMoaDrMovie interface inherits from IMoaMmPropOwner (through IMoaDrMediaOwner). The movie object supports a number of properties through this interface. These are:
Property | Description |
name | Name of the movie file |
pathName | Path to movie file |
playing | Movie's playback state |
defaultColorDepth | Bit depth of movie palette |
defaultStageRect | Size of movie stage |
tempo | Frame rate of movie |
defaultPalette | Standard CLUT for movie |
remapPalettes | Movie's remapping state |
castCount | Number of movie casts |
stageColor | Background color |
frame | Current frame number |
activeCastLib | Index of active cast (authoring only) |
scoreSelection | List of rects representing selection area (authoring only) |
For more details, see "Movie properties" in the Director API Reference.
The IMoaDrMovie interface inherits from IMoaDrMediaOwner.
The movie object supports one type of media data through this
interface: score media. You can access score media in a couple
of ways: through a handle to the score data, or through an IMoaDrScoreAccess
interface.
Handle access may be useful for moving score data between movies
or to and from disk. The data in the handle is in the same format
as Director uses to save score data. However, this form isn't
generally useful for accessing or modifying score data, since
the actual structure of the data isn't published. Because it inherits
from the IMoaDrMediaOwner interface, IMoaDrMovie
provides three methods for accessing handle data: AttachMedia(),
GetMedia(), and SetMedia(). GetMedia()
returns the handle to the score data of a movie, in a MoaDrMediaInfo
structure. SetMedia()
assigns the media to the movie, essentially copying the data into
the movie. AttachMedia()
is like SetMedia(), except that it transfers the score
data to the movie--the caller need not dispose of the data after
this method returns.
As an alternative to raw data access, the IMoaDrScoreAccess
interface provides a way to access and modify the contents of
a movie's score. To get a movie's score data through this interface,
call the IMoaDrMovie::GetScoreAccess()
method. This interface, described later in this section, includes
methods for interacting with the frames, sounds, and sprites in
a score.
A movie's score may have labeled frames, used to identify and
access specific frames in a movie. The IMoaDrMovie interface
provides ways to access frame labels. The GetFrameIndexFromLabel()
and GetFrameLabelFromIndex()
methods let you find the position of a frame if you know its label,
or find the label of a frame if you know its position in the score.
The SetFrameLabel()
method lets you assign a new label to a specific frame in a movie.
As shown in the Director object model diagram,
each movie can have several casts. Casts may be either internal
(saved in the same movie file) or external (saved in a separate
file). Casts are discussed in greater detail in the next section.
This discussion focuses on how a movie organizes and accesses
its casts.
Casts are identified in two ways: by index in the movie's cast
list and by name. The index of a cast depends on the order in
which it's added to the movie. Cast names are defined by the author
and are displayed in the user interface for identification purposes.
IMoaDrMovie::AddExternalCast() adds an existing external cast to the movie. You can provide a name along with the path to the cast file. The NewCast() method creates a new cast and adds it to the movie. The new cast can be either internal or external. Both methods return the index of the new cast in the movie's cast list in a parameter provided by the caller.
To find out how many casts belong to a movie, call GetCastCount().
This method returns a parameter representing the number of casts
in the cast list. To get the position of a cast with a particular
name, use the GetCastIndexFromName()
method.
To delete the cast at a particular position in the list, call
the RemoveCast()
method. To move a cast member to a new location, call the IMoaDrMovie2::MoveCastMember()
method.
To manipulate a cast and its cast members, you need to its IMoaDrCast
interface. To get the interface for a cast with a particular display
name, call IMoaDrMovie::GetCastFromName().
To get an interface for a specific cast in the movie's cast list,
call the IMoaDrMovie::GetNthCast()
method.
The GetCastMemFromCMRef() method provides a way to get the IMoaDrCastMem interface for any cast member in any cast in a movie. This method takes a MoaDrCmRef struct as an argument. This structure contains two fields, one an index of the cast in the movie list, and the other an index of the cast member in the cast.
The IMoaDrMovie2 interface provides two methods that let you manipulate cast member reference identifiers: GetCMRefFromCMId() and GetCMIdFromCMRef(). GetCMRefFromCMId() obtains the cast member reference for a cast member from its unique identifier. GetCMIdFromCMRef() obtains a unique identifier for the cast member referred to by its cast member reference; this identifier can be used to retrieve the cast member reference for the cast member at a later time, even if the cast member has been moved across cast boundaries.
Director also provides a number of macros for manipulating CMRef structures. These macros, defined in drtypes.h and described in "Director Types and Miscellaneous API", let you create a CMRef, get the cast index, the cast member index, or clear the contents of a CMRef. You should use these macros to manipulate a CMRef structure rather than accessing the contents directly.
To call any scripting handler, whether built-in or defined in a movie script, use the IMoaDrMovie::CallHandler() method. This method takes the handler name and a list containing arguments to the handler.
When your Xtra modifies a movie by manipulating either its cast or score, you can use the IMoaDrMovie::Save() to save it back to disk.
To create a new movie, clear the cast and score of an existing movie, then save the empty movie. To clear the cast, call IMoaDrMovie::RemoveCast() (note however that you can't remove the first cast in a movie--instead, you can clear all the members from the cast). Create a new empty score by calling IMoaDrUtils::NewScoreAccess(), and assign it to the movie by calling IMoaDrScoreAccess::SetOwner(). Call IMoaDrScoreAccess::Commit() to assign the empty score to the movie. Finally save the movie by calling IMoaDrMovie::Save(), giving the movie a new file name and path.
In Director, each movie has a window and offscreen buffer where it performs its drawing. (The Director imaging model and animation loop is described in more detail in "Asset Xtras" in the Multimedia Developer's Guide.)
The IMoaDrMovie interface provides access to the graphics contexts for Director's off- and onscreen drawing environments. This is useful when an authoring or playback Xtra wants to directly access the images presented in a movie. To get the offscreen drawing buffer, call the IMoaDrMovie::GetStageBufferGC() method. To get the onscreen drawing window, call IMoaDrMovie::GetStageWindowGC().
Note: Direct access to the drawing buffers creates potential for interference in the presentation and performance of a movie, so these features should be used with care. This access is intended for use in Scripting and Tool Xtras that need temporary access to the stage for image capture or other such non-invasive purposes.
The UpdateStageRect() method lets an Xtra force the movie to redraw an image from a specific area of the offscreen buffer to its onscreen window.
The IMoaDrCast interface represents a list of cast members belonging to a movie. A Director movie may have one or more casts.
Using the Director services, casts are always created and accessed
in association with a particular movie. However, a cast can be
internal, saved with its movie, or external, saved in a separate
cast file. External casts can be included in multiple movies,
or moved from one movie to another.
The IMoaDrMovie::NewCast()
method lets you create a new cast and place it in a specific movie.
This method lets you provide a name for the cast and specify whether
it's internal or external. This method returns, as a parameter,
the index of the new cast in the movie
To manipulate a cast, you acquire its IMoaDrCast interface.
You can get the interface for a cast with a particular display
name by calling IMoaDrMovie::GetCastFromName().
To get an interface for a specific cast in the movie's cast list,
call the IMoaDrMovie::GetNthCast()
method.
To save an external cast, call the IMoaDrCast::Save()
method. Save() can be used to move an external cast from
one movie to another. After save the cast by calling IMoaDrCast::Save(),
remove it from the movie by calling IMoaDrMovie::RemoveCast().
Finally, add it to the new movie by calling IMoaDrMovie::AddExternalCast().
The IMoaDrCast interface inherits from IMoaMmPropOwner. A cast object supports a number of properties through this interface. These are:
Property | Description |
name | Name of the cast in the user interface |
pathName | Full pathname of the cast |
preloadMode | Cast preload mode |
memberCount | Number of cast members in cast |
minMember | Index of first member in cast |
maxMember | Index of last member in cast |
selection | List of selection ranges (authoring only) |
For more details, see "Cast properties" in the Director API Reference.
A cast is made up of cast members, and the IMoaDrCast interface provides methods to create, delete, and access those members.
You can create a new cast member of a specific type by calling the CreateCastMem() method. This method lets you specify the type of cast member and where in the cast to place the new member. If a cast member already exists in the specified slot, it will be replaced. The IMoaDrCast::DuplicateCastMem() method lets you copy one cast member to another slot in any cast for which you have an IMoaDrCast interface. The destination cast may be the same as the source cast, another cast in the same movie, or a cast in a different movie.
To remove a member from a cast, call the IMoaDrCast::DeleteCastMem() method.
IMoaDrCast interface provides a number of methods for determining the number of members in the cast and finding open cast member slots. A cast has 32,000 slots for cast members.
Use the methods GetFirstUsedMemberIndex() and GetLastUsedMemberIndex() to determine the range of occupied slots in a cast. Use the methods GetFirstFreeMemberIndex() and GetLastFreeMemberIndex() to determine the available cast member slots in a cast. The method GetNextFreeMemberIndex() lets you determine where the next free slot can be found relative to a particular position in the cast; GetNextUsedMemberIndex() lets you determine the next occupied slot relative to a particular position. To find the position of a cast member with a particular name, use the method GetMemberIndexFromName().
To find the position of a particular cast in a movie, call the method IMoaDrCast::GetIndexInMovie().
The IMoaDrCastMem interface provides access to the members of a cast. You can use this interface to manipulate a cast member, access its media or properties, and call scripting functions provided by the cast member.
To acquire the interface for the cast member at a specific position in a cast, call the IMoaDrCast::GetCastMem() method. You can also acquire the interface for a particular member in a particular cast of a movie by calling the IMoaDrMovie method GetCastMemFromCMRef().
The IMoaDrCastMember interface inherits from IMoaMmPropOwner (through IMoaDrMediaOwner). A cast member object supports a number of properties through this interface. The general properties supported by all cast members are:
Property | Description |
name | User-defined name of cast member. |
size | Memory occupied by cast member |
castType | Type of cast member (as a string/symbol) |
type | Type of cast member (as a symbol) |
scriptText | Text of cast member script |
modified | Modified since last save |
loaded | Currently in memory |
fileName | Path to cast member (linked members only) |
purgePriority | Author-settable purge priority |
number | Cast member number of cast member |
member | Cast member type of cast member |
width | Width of default display rectangle |
height | Height of default display rectangle |
rect | Display rectangle |
hilite | Highlighting state of cast member |
regPoint | Registration point of cast member (settable for bitmaps only) |
interface | The Moa interface for the member (for Xtra based members only) |
In addition to the general properties listed here, cast members of various cast types support properties specific to their type. For more details, see "Cast member properties" in the Director API Reference.
The IMoaDrCastMem interface inherits from IMoaDrMediaOwner. Media owners provide methods for getting and setting their media. The media associated with a media owner is identified by label and format. Cast members support the following labels and formats:
Label | Description |
Composite | Cast member data in a portable (byte-swapped) handle |
Image | Primary image data |
Text | Text character string |
TextStyles | Text style run data |
Sound | Sound samples |
Palette | Palette entries |
Score | Score data for a movie or film loop |
Format | Description |
moaHandle | Generic MoaHandle of data |
moaTEStyles | textStyles format stored in a MoaHandle |
macTEStyles | textStyles in TextEdit format stored in a Macintosh StScrpHandle |
macPICT | Macintosh PicHandle |
macSnd | Macintosh sndHdl in Macintosh sound resource format |
macColorTable | Macintosh CTabHandle to a ColorTable record |
winDIB | Windows packed DIB GlobalHandle with bitmap information, table, and bits |
winWAVE | Windows RIFF WAVE GlobalHandle; RIFF sound format |
winPALETTE | Windows HPALETTE GlobalHandle; RIFF palette format |
The labels and formats supported by a particular cast member depend on the cast member type. The description of the IMoaDrCastMem interface includes a complete listing of cast member types and the media they support.
Before you can set the media of a cast member--by calling IMoaDrCastMem::SetMedia()--you need to populate a MoaDrMediaInfo structure with the format, type, and media data. To ensure that the media data is properly applied to the cast member, call the IMoaDrUtils::NewMediaInfo() method. Note that this method doesn't allocate the media data; you do that before calling these methods.
To dispose of a cast member's media data, you acquire the data by calling IMoaDrCastMem::GetMedia(). You then call the IMoaDrUtils::MediaRelease() method. This ensures that the data, originally allocated by the host application, is properly disposed of.
Note that special options are supported when setting "image" label media.
The IMoaDrCastMem interface supports scripting access to cast members through two methods, CallFunction() and CallHandler().
In addition to defining specific properties, the Digital Video, Text, and sprite Xtra cast member types define specific functions that you can call to access media information. To call the functions associated with a particular cast member, use the method IMoaDrCastMem::CallFunction(). The functions associated with particular cast member types are listed and described in "Cast member properties" in the Director API Reference.
To call a specific handler defined in a cast member's script, use the IMoaDrCastMem::CallHandler() method.
To find the position of a cast member in a cast, call the IMoaDrCastMem::GetMemberIndex() method.
For cast members that present Director filmloops, the IMoaDrCastMem::GetScoreAccess() method provides a way to get the IMoaDrScoreAccess interface for the loop. Use this interface as an alternative to the methods of the IMoaDrMediaOwner interface for accessing and manipulating score data owned by a cast member. The IMoaDrScoreAccess interface is described in greater detail in the next section of this discussion.
The IMoaDrScoreAccess interface provides a way to access the score data belonging to a movie (IMoaDrMovie) or a filmloop cast member (IMoaDrCastMem).
With the IMoaDrScoreAccess interface, you access data in a score frame by frame. When you first acquire an IMoaDrScoreAccess interface, it's not set to a particular frame. The interface provides methods for determining the number of frames in a score, moving to a specific frame, inserting a frame, deleting a frame, and so on. In addition, IMoaDrScoreAccess provides ways to get the interfaces for a frame (IMoaDrScoreFrame), the sound channels of a frame (IMoaDrScoreSound), and any sprite in the sprite channels of a frame (IMoaDrScoreSprite).
You can edit a score at two levels: by manipulating entire frames in the score, and by accessing the contents of specific frames. These two editing levels are described in separate sections of the following discussion.
You can acquire an IMoaDrScoreAccess interface in one of three ways. The IMoaDrMovie::GetScoreAccess() method returns an interface representing the score of a specific movie. The IMoaDrCastMem::GetScoreAccess() method returns an interface for the score of a filmloop cast member. The IMoaDrUtils::NewScoreAccess() method returns an interface for a new score without a specific owner. After acquiring a score through this method, you can call IMoaDrScoreAccess::SetOwner() to attach the score to a movie or cast member.
You edit a score in an editing session. An editing session begins with a call to the IMoaDrScoreAccess::BeginUpdate() method, and ends with a call to the IMoaDrScoreAccess::EndUpdate() method. In between these two method calls, you can add, modify, and delete frames in the score.
Once you begin an editing session, make changes to the score through methods of the IMoaDrScoreAccess interface. To save changes you've made to the score data, call the Commit() method. To restore data from the media owner, call the Refresh() method. If the score data is being edited through another means (e.g., Scripting calls or the authoring environment's user interface), Refresh() returns the latest version of the score data. Otherwise, it returns the media data as it was either when you began the editing session or when you last called IMoaDrScoreAccess::Commit() . To delete all data in the score and start with a blank slate, call IMoaDrScoreAccess::New() method.
This section looks at methods for accessing specific frames in a movie and editing the score by inserting, copying, and deleting frames.
Through an IMoaDrScoreAccess interface, you can move to any frame in the score by calling SetCurFrameIndex(). (When you first acquire the interface, it isn't set to a specific frame.) As you move around the frames of a score, you can determine the current frame index by calling GetCurFrameIndex(). To determine the last frame in the score, call GetLastFrameIndex().
You can manipulate the current frame using a number of IMoaDrScoreAccess methods. Call DuplicateFrame() or InsertFrame() to create a copy of the current frame, place it immediately after the current frame, and move score access to the new frame position. Call DeleteFrame() to remove the current frame. Call ClearFrame() to remove the data from all channels in a frame. Call UpdateFrame() to commit any changes made to the channels of the current frame and increment the frame position to the next frame in the score.
To access general properties of a frame, you acquire the frame's IMoaDrScoreFrame interface by calling GetFrame(). The IMoaDrScoreFrame interface inherits from IMoaMmPropOwner, and provides just the two methods of this interface: GetProp() and SetProp(). The properties of a frame that you can access through this interface are:
Property | Description |
tempo | Frame tempo in fps |
waitSeconds | Wait time of the frame |
waitClick | Mouse click wait state |
waitSound | Sound wait state |
waitDigitalVideo | Digital video wait state |
palette | CLUT for the frame (as an integer) |
paletteRef | Reference to palette as cast member (as a CMRef or symbol) |
paletteTransitionType | Cross palette transition |
paletteOverTime | Palette transition state |
paletteFrames | Time for palette transition |
paletteSpeed | Rate of palette transition |
transition | Cast member in transition channel |
script | Cast member in script channel |
You can get and set any of these frame properties through the methods GetProp() and SetProp(). For more details, see "Score frame properties" in the Director API Reference.
In addition to accessing general frame data through the score, you can also access and manipulate both sound and sprite channels of the current frame.
To manipulate the data in a specific sound channel of a frame, call the method IMoaDrScoreAccess::GetSound(). This method returns an instance of the IMoaDrScoreSound interface for the specified sound channel of the current frame.
The IMoaDrScoreSound interface inherits from IMoaMmPropOwner interface, and provides just the two methods of this interface: GetProp() and SetProp(). The properties of a sound channel that you can access through this interface are:
Property | Description |
member | Cast member represented in sound channel |
scoreColor | Color of sound in channel |
You can get and set these sound channel properties through the methods GetProp() and SetProp(). For more details, see "Score sound properties" in the Director API Reference.
To manipulate the data in a specific sprite channel of a frame, call the method IMoaDrScoreAccess::GetSprite(). This method returns an instance of the IMoaDrScoreSprite interface for the specified sprite channel of the current frame.
The IMoaDrScoreSprite interface inherits from IMoaMmPropOwner interface and provides just the two methods of this interface: GetProp() and SetProp(). The properties of a sprite channel that you can access through this interface are:
Property | Description |
member | Cast member presented in sprite channel |
scoreColor | Color of sprite in channel |
script | Cast member for the sprite's script |
size | Size of sprite as a point value |
loc | Location of sprite (position of the registration point) |
foreColor | Foreground color of sprite |
backColor | Background color of sprite |
ink | Inkmode of sprite |
trails | Trail drawing state |
moveableSprite | Movable state of sprite |
editableText | Editable state of text sprite |
blend | Blend percentage of sprite |
You can get and set any of these sprite channel properties through the methods GetProp() and SetProp(). For more details, see "Score sprite properties" in the Director API Reference.
You can determine and set ownership of a score using the IMoaDrScoreAccess methods SetAccessInfo(), GetAccessInfo(), and SetOwner(). The GetAccessInfo() method returns a MoaDrAccessInfo structure containing the owner, label, and format of the media data. For a score, the label is always score and the format is always MoaHandle. The owner may be either an IMoaDrMovie or IMoaDrCastMem (both of which inherit from IMoaDrMediaOwnerand support score media). To change ownership of a score, you can call either SetAccessInfo() with a completely filled out MoaDrAccessInfo structure, or SetOwner() providing the interface of the new owner.
The following table lists all the methods for acquiring access to Director services interfaces:
Interface | Accessed by |
IMoaDrUtils | IMoaCallback::QueryInterface() (from pCallback) |
IMoaDrPlayer | IMoaCallback::QueryInterface() (from pCallback) |
IMoaDrMovie | IMoaDrPlayer::GetActiveMovie(), IMoaDrPlayer::GetNthMovie() |
IMoaDrMovie2 | IMoaDrMovie::QueryInterface() |
IMoaDrCast | IMoaDrMovie::GetCastFromName(), IMoaDrMovie::GetNthCast(), IMoaDrMovie::NewCast() |
IMoaDrCastMem | IMoaDrCast::GetCastMemFromCMRef(), IMoaDrCastMem::GetCastMem() |
IMoaDrScoreAccess | IMoaDrCastMem::GetScoreAccess(), IMoaDrMovie::GetScoreAccess(), IMoaDrUtils::NewScoreAccess() |
IMoaDrScoreFrame | IMoaDrScoreAccess::GetFrame() |
IMoaDrScoreSound | IMoaDrScoreAccess::GetSound() |
IMoaDrScoreSprite | IMoaDrScoreAccess::GetSprite() |
In addition to interfaces representing the Director object model, the Director services provide a number of facilities for use by Xtras. The IMoaDrUtils interface provides methods for converting Director specific data to MoaMmValues, for attaching and releasing media data, and for creating clients to receive notification from the host application. The IMoaDrAssetCallback and IMoaDrSpriteCallback interfaces provide Director-specific callback facilities for use by media asset Xtras.
IMoaDrUtils is a general interface the provides useful utilities for working with Director. Part of the functionality of IMoaDrUtils has been superseded by IMoaDrValue.
As described in the earlier discussion of the IMoaDrCastMem interface, the IMoaDrUtils methods NewMediaInfo() and MediaRelease() provide ways to populate a MoaDrMediaInfo structure with appropriate data, and to release the application-allocated data belonging to a cast member. These methods are used in conjunction with the IMoaDrCastMem methods AttachMedia(), SetMedia() and GetMedia().
To create a new score outside the context of a specific movie or cast member, call the IMoaDrUtils::NewScoreAccess() method. You can then call the IMoaDrScoreAccess::SetOwner() method to specify the owner of the score.
The IMoaDrValue interface provides methods for converting between MoaMmValues and Director-specific types. The following table lists the methods of this interface and the types of values they convert.
Type | To MoaMmValue | From MoaMmValue |
Cast Member Reference | ValueToCMRef() | CMRefToValue() |
Sprite Reference | ValueToSpriteRef() | SpriteRefToValue() |
Cast Library Reference | ValueToCastLibRef() | CastLibRefToValue() |
Sound Sprite Reference | ValueToSoundSpriteRef() | SoundSpriteRefToValue() |
Director uses the MOA notification interfaces to notify Xtras of specific events of interest. Xtras call the callback interface IMoaNotification to register interest in specific events, and implement the IMoaNotificationClient interface to process the events requested.
Director defines the following event notification IDs, which an Xtra uses to indicate the events it's interested in, and which the application uses to indicate the events its sending to the Xtra. For each event type, a specific data type is passed to the IMoaNotification::Register() method when registering, and data is received from the application when it calls IMoaNotificationClient::Notify(). For some code illustrating how to use custom notifications see notify.htm. The following table lists Director event types and the associated Notification IDs and Data:
Event | Notification ID | Data passed to Register() | Data received by Notify() |
Movie opened | NID_DrNMovieOpened | PIMoaDrMovie of movie to notify on (NULL == all movies) | PIMoaDrMovie of movie that opened |
Movie closed | NID_DrNMovieClosed | PIMoaDrMovie of movie to notify on (NULL == all movies) | PIMoaDrMovie of movie that closed. Do not release this interface! |
Step frame | NID_DrNStep | PIMoaDrMovie of movie to notify on (NULL == all movies) | PIMoaDrMovie of movie that stepped |
Service background process | NID_DrNIdle | PMoaLong indicating max milliseconds between calls | PMoaLong indicating milliseconds since last call |
Palette changed | NID_DrNPaletteChanged | NULL | MoaMmValue representing new internal palette -OR- PIMoaMmCastMember representing new external palette |
Cast member modified | NID_DrNCastMemberModified | PIMoaDrCastMem of the cast member to notify on (NULL == all cast members) | PIMoaDrCastMem of the cast member modified |
Selection changed in cast window | NID_DrNCastSelectionChanged | NULL | NULL |
Score modified | NID_DrNScoreModified | NULL | NULL |
Selection changed in score window | NID_DrNScoreSelectionChanged | NULL | NULL |
Cue point passed | NID_DrNCuePointPassed | PIMoaMmValue sprite reference containing cue points of interest (NULL == all sprites) | PMoaMmCuePoint struct representing the cue point passed |
Animation state changed |
NID_DrAnimationState This was added in D8. |
NULL |
PMoaShort <=0 not animating, >0 animating |
Movie was rewound |
NID_DrNRewind This was added in D8.5. |
NULL |
NULL |
Movie halted due to lingo debugger stop |
NID_DrNEnteringDebugger This was added in D8.5. |
NULL |
NULL |
Movie continues after stopping |
NID_DrNLeavingDebugger This was added in D8.5. |
NULL |
NULL |
Window reveal | NID_DrNStageWindowOpen This was added in DMX 2004. |
NULL |
NULL |
Window collapse | NID_DrNStageWindowClose This was added in DMX 2004. |
NULL |
NULL |
The step, idle, and palette changed events are equivalent to events sent to sprite actors through the IMoaMmSpriteActor::Notify() method. However, any Xtra can implement the IMoaNotificationClient class and subscribe to these events through the host application's IMoaNotification callback interface.
Note: The IMoaDrUtils methods RegisterNotificationClient() and UnregisterNotificationClient() which enabled Director Xtras to receive notification in the previous release of this XDK are obsolete, though still provided by Director.
The Director services provide two interfaces that support media asset Xtras: IMoaDrAssetCallback and IMoaDrSpriteCallback.
After a media asset Xtra's IMoaMmXAsset interface is initialized by the host application, its SetCallback() method is called. This method provides an IMoaMmAssetCallback interface to the Xtra. This interface is described in "Asset Xtras" in the Multimedia Developer's Guide.
In Director, the object that provides IMoaMmAssetCallback also implements the IMoaDrAssetCallback interface. To acquire this interface, the media asset calls QueryInterface() on IMoaMmAssetCallback. It can then call the methods described here to interact with its internal representation within a Director movie.
IMoaDrAssetCallback provides the standard property owner methods GetProp() and SetProp(), which enable the media asset to access its Director-specific properties. These are the same properties described earlier in the discussion of the IMoaDrCastMem interface. In addition, the asset Xtra can access properties it defines in its own implementations of GetProp() and SetProp(). However, this isn't the most efficient way to access these properties and can create endless loops, so it should be used with caution.
IMoaDrAssetCallback provides the CallCMHandler() method to enable a media asset Xtra to call any Lingo handlers defined in the cast member script.
After a sprite asset Xtra's IMoaMmXSpriteActor interface is initialized by the host application, its SetCallback() method is called. This method provides an IMoaMmSpriteCallback interface to the Xtra. This interface is described in "Asset Xtras" in the Multimedia Developer's Guide.
In Director, the object that provides IMoaMmSpriteCallback also implements the IMoaDrSpriteCallback interface. To acquire this interface, the sprite actor calls QueryInterface() on IMoaMmSpriteCallback. It can then call the methods described here to interact with its Director movie.
To get access to the IMoaDrMovie interface for its movie, the sprite can call IMoaDrSpriteCallback::GetMovie(). It can then access other interfaces within the movie, using the techniques described in "Using the Director Object Model".
To determine its sprite channel in the score, the sprite calls IMoaDrSpriteCallback::GetSpriteChanIndex().
To call a handler in its sprite script, the sprite can invoke the method IMoaDrSpriteCallback::SendSpriteMessage(). This method ensures that handler calls are passed up the normal message passing chain, from sprite script to cast member script to frame script to movie script.
The IMoaDrPaletteAccess interface provides a way for any Xtra to access Director's built in palettes and to get the platform-specific media of the palettes.
The following fragments provide a couple examples of calls using the Director services interfaces.
As illustrated earlier, the Director services are accessible via callback interfaces available to all Director Xtras. Each Xtra is provided with a pointer to the Director callback object. Within a C implementation of an Xtra interface method, you'd acquire a pointer to the callback object using code similar to the following fragment:
PIMoaCallback pMyCallback; PIMoaDrPlayer pPlayer; PIMoaDrMovie pMovie; MoaError err; pMyCallback = This->pObj->pCallback; err = pMyCallback->lpVtbl->QueryInterface(pMyCallback, &IID_IMoaDrPlayer, &pPlayer);
In this example, the specified interface is returned in the pointer variable pPlayer. Interface ID's for the various Director services interfaces (such as IID_IMoaDrPlayer) are listed with each interface description in Director Interfaces in the Director API Reference.
Once you have the player interface, a you can call any of its methods through its function table (referenced through the standard pointer lpVtbl). For example, after using the above fragment to get an interface to the player interface, you'd make the following call to get the player's active movie:
err = pPlayer->lpVtbl->GetActiveMovie(pPlayer, &pMovie);
IMPORTANT: In all cases when you specifically request an
interface through a callback service method, you are responsible
for releasing it when you're through. See the documentation for
methods which return interfaces for more details. To release an
interface, you call its Release() method. Like QueryInterface(),
Release() is a standard method of all MOA interfaces,
provided by inheritance from the IMoaUnknown interface.
pMovie->lpVtbl->Release(pMovie);
pPlayer->lpVtbl->Release(pPlayer);
Here's a chunk of C code that determines the number of casts in the active movie. It is assumed that this code is the implementation of an Xtra method; "This" is a pointer to the object instance which is passed in to all implementation functions.
STDMETHODIMP TestClass_TestMethod(TestClass_ITestInterface * This) { MoaError err = kMoaErr_NoErr; PIMoaCallback pMyCallback; PIMoaDrPlayer pPlayer = NULL; PIMoaDrMovie pMovie = NULL; MoaLong castCount; // Get interface to player pMyCallback = This->pObj->pCallback; err = pMyCallback->lpVtbl->QueryInterface(pMyCallback, &IID_IMoaDrPlayer, &pPlayer); if (err == kMoaErr_NoErr) { // Get interface to currently active movie err = pPlayer->lpVtbl->GetActiveMovie(pPlayer, &pMovie); if (err == kMoaErr_NoErr) { // Get number of casts err = pMovie->lpVtbl->GetCastCount(pMovie, &castCount); // number of casts is in castCount ... pMovie->lpVtbl->Release(pMovie); } pPlayer->lpVtbl->Release(pPlayer); } return err; }
The following examples assume you have an instance of PIMoaMmUtils in pMmUtils, a PIMoaDrUtils in pDrUtils, and the PIMoaDrCastMem for the cast member of interest in pCastMem.
The following code fragment sets a cast member's palette to the built-in NTSC palette:
pMmUtils->lpVtbl->StringToSymbol(pMmUtils, "paletteRef", &myPropSym); pMmUtils->lpVtbl->StringToSymbol(pMmUtils, "NTSC", &myPalSym); pMmUtils->lpVtbl->SymbolToValue(pMmUtils, &myPalSym, &myPalValue); pCastMem->lpVtbl->SetProp(pMmUtils, &myPropSym, &myPalValue); pMmUtils->lpVtbl->ValueRelease(pMmUtils, &myPalValue);
Setting a cast member's palette to a cast-based palette member 5 of cast 1:
pMmUtils->lpVtbl->StringToSymbol(pMmUtils, "paletteRef", &myPropSym); CMRef_Make(&myCMRef, 1, 5); pDrUtils->lpVtbl->CMRefToValue(pDrUtils, &myCMRef, &myPalValue); pCastMem->lpVtbl->SetProp(pCastMem, &myPropSym, &myPalValue); pMmUtils->lpVtbl->ValueRelease(pMmUtils, &myPalValue);
The following code fragment shows how to get a cast member's palette, and see what kind it is:
pMmUtils->lpVtbl->StringToSymbol(pMmUtils, "paletteRef", &myPropSym); pCastMem->lpVtbl->GetProp(pCastMem, &myPropSym, &myPalValue); if (pDrUtils->lpVtbl->ValueToCMRef(pDrUtils, &myPalValue, &myCMRef) == kMoaErr_NoErr) { // it's a cast-based palette, CMRef is in myCMRef } else if (pMmUtils->lpVtbl->ValueToSymbol(pMmUtils, &myPalValue, &myPalSym) == kMoaErr_NoErr) { // it's a built-in palette, the symbol is in myPalSym } ... pMmUtils->lpVtbl->ValueRelease(pMmUtils, &myPalValue);
Director 8 allows developers to create and customize tabs in the Property Inspector by editing (or adding) the VDL (View Description List) files in the props folder. Use the information in View Description List File Syntax along with the information about the Property page interfaces section to define Property pages for Xtras that you create.
For information on creating and editing VDL files, see View Description List File Syntax.
The Property page interfaces allows you to define Property pages in the Property Inspector for Asset Xtras. If the Asset Xtra has a simple Property page that does not require any custom property processing, you do not need to use the IMuiPropertyPage interfaces to create a Property page for your Xtra, simply create a VDL (View Description List) file and place it in the props folder. If the Xtra requires a Property page with special logic, code, or property handling, you need to provide the logic for the Property page using the IMuiPropertyPage interfaces.
The following Property page interfaces are available starting in Director 8:
![]() |
IMuiPropertyPage Provides a mechanism for sending special logic, code, property handling, or special cases to Property pages for Asset Xtras. |
![]() |
IMuiPropertyPageTarget A support interface creating an abstraction layer above the object targeted by the Property page. Use this interface when the Property inspector targets multiple objects and you want to get or set the properties for all of the objects at the same time. |
![]() |
IMuiPropertyPageInstance Represents the current state of the instantiated Property page as generated from the VDL data provided by the Xtra or the Xtra's VDL file in the props folder. Use this interface to get or set the state/value of specific controls in the UpdateItems or ItemClicked methods of the IMuiPropertyPage interface. |
The VDL file information for Asset Xtras can be handled in one of two ways: you can create a VDL file for your Xtra, place it in the props folder located next to the Director application, and register its name and location using the Register() method; or you can include the VDL information inside the Xtra, in which case it is returned as a formatted string when Director calls the GetDescriptor method.
For information about xtra downloading, see the overview provided in TechNote 13653, Xtras downloading overview.This section answers some questions about the version information of xtras and how it applies to xtra packages and xtra downloading.
The version resource is used to determine which xtra is on the machine. The only time the version info internal to the Xtra comes into play is after an xtra has been downloaded and installed. For the remainder of that session, both versions of the xtra are installed and available to MOA. If the internal versions are the same, the MOA code selects one in an indeterminate manner. Otherwise the xtra with the higher internal version number is chosen. The internal version number is defined with the BEGIN_XTRA_DEFINES_CLASS and CLASS_DEFINES_INTERFACE macros.
This only comes into play if the movie has the "download when needed" box checked in the modify\movie\xtras dialog. If this box isn't checked then the movie has no information about what version of any xtra was used. When the movie author selects the "download when needed" box in the dialog, director looks up the package file on the net. Information about each file in the package - including the external version number - is pulled out of the package file at this time and saved in the movieXtraList. If the package is later updated with a newer version of the xtra, the movie does not automatically check under any circumstances. The movie author would have to uncheck/recheck the download box to update the movie with the version info about the xtra package updated.
Although some of the examples in the XDK don't have version information, the
ValueChecker example and all of the skeleton projects have been updated to have
version resources. As as external versions go, Shockwave/Director check
3 levels of version information. So:
Director MX 2004 added support for creating projectors on the "other" platform: macintosh projectors on windows and windows projectors on macintosh. To support this for your custom Xtra, first make sure there is an entry for your Xtra in the xtrainfo.txt file that gives the proper filename for the Xtra on each platform. Unless this information is provided, the code assumes your Xtra only exists on the current platform.
To make your custom Windows Xtra availabe for a Mac-created projector, simply put the Xtra in the /Cross Platform Resources/Windows/Xtras/ folder of the Macintosh Director installation.
On the macintosh there is a complication: a Mach-O Xtra is actually a bundle which consists of multiple folders and files - which could have resource forks.
Although, the Adobe Xtras and example xtras no longer use resource forks.
So here's how its handled.
You use the ditto command line tool to create a data fork archive of the entire xtra bundle.
This archive file can be placed into the /Cross Platform Resources/Macintosh/Xtras/ folder of the Windows Director installation.
For example:
ditto -c -X --rsrc /Volumes/plum/XDK/examples/OvalSprite.xtra /Volumes/plum/XDK/examples/OvalSprite.cpio
Director 11 was changed to support Unicode text. When passing strings to Director 11, you need to convert them to UTF8 format When retrieving a string from Director 11, it will be converted to UTF8 before it is passed to you. This includes movie names, file names, lingo variables, etc. A new example xtra, ComputerUser, has been added that demonstrates how to deal with converting Unicode text from the operating system on both Macintosh and Windows. Note that UTF8 encoding is the same as standard ASCII for values from 0 - 127, so normal C strings work fine in many cases. Also note that with UTF8, some characters take 1 byte, and some characters take more than 1 byte of data.
Director 11 does not support Unicode text in VDL files. Note that for some dictionary properties, the maximum supported length is actually in bytes rather than Unicode characters. For example, with kMoaMmDictKey_DisplayCategoryString the maximum length may be less than 64 Unicode characters.