MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API
Director Xtra Development Kit: MOA Developer's Guide
MOA Technical Concepts
The MOA object model
-
- This section covers the main conceptual points of the MOA
object model, beginning with the central mechanism of MOA, the
interface. It then goes on to describe the conceptual relationship
among MOA objects, classes, and interfaces.
-
- MOA is built on the fundamental concept of interface,
one of the foundations of COM. Interfaces are the basic mechanism
by which an application and an external code module--an Xtra--interact.
- An interface can be thought of as a template that specifies
how independent code modules interact.

For two modules to interact through an interface, each plays a
specific role: either providing or using the interface. A provider is a module that implements the interface by providing specific
behavior that conforms to the template.
A user is a module that relies on the behavior specified
by the interface.
When a provider and user of the interface come together, they
can interact through the template of the interface.
Interfaces can be defined independently of both providers and
users: one programmer or organization may define an interface,
while others implement or use it. This separation makes the MOA
object model well-suited to defining and implementing Xtras.
For two independent modules to interact, each must provide an
interface to the other, and use an interface provided by another.
Interfaces define self-contained units of behavior. Each interface
has a specific, coherent purpose. For complex behaviors, a single
module provides more than one interface, and uses more than one
interface in other modules.
A Macromedia application may provide a number of interfaces to
its Xtras. It may also define several interfaces intended to be
provided by Xtras.
-
- In C-language terms, an interface is a set of prototypes--names,
argument types, and return types--for a set of related functions.
These function prototypes are referred to as methods. Because
an interface declares only the external signature of its methods,
it can be declared independently of both its providers and users.
For example, consider an interface named Shape. This interface
specifies standard behavior for rendering 2D graphic shapes. In
this simple example, the Shape interface specifies just one method:
Draw. An application may use the Shape interface by calling the
Draw method.
An Xtra that provides the Shape interface includes code for the
Draw method. For example, a rectangle Xtra would include code
to render a rectangle.
-
- Traditionally, a program consists of two types of entities:
data and procedures. Data represents things such as names, addresses,
or the position and size of a graphic shape. Procedures operate
on data--for example, by adding two numbers and returning the
result, sorting a list of names, and so on. Frequently, programmers
develop suites of functions to operate on specific types of data.
Object-oriented programming formalizes and extends this approach
to programming. Data and procedures are combined in a single unit,
the object. Generally, the data of an object can only be accessed
and manipulated through procedures belonging to the object. This
is referred to as encapsulation.
Encapsulation helps ensure data integrity. Since the data is controlled
by the object, the user is less likely to make inadvertent changes
than with traditional data structures. Encapsulation also facilitates
code maintenance, because objects are manipulated solely through
procedures. The structure of an object's data can be designed
and modified to suit its own needs, without affecting the users.
Because interfaces represent units of behavior agreed on by separate
code modules, they're well suited to object-oriented programming.
By providing one or more interfaces, a MOA object provides a specific
set of behavior to its users, while keeping its data encapsulated.
In addition to encapsulation, interfaces enable different types
of objects to respond to the same procedures in their own way.
In object-oriented terms, this is referred to as polymorphism.
Because of polymorphism, a user can interact with objects of many
types without knowing about the internal details of those objects.
The benefits of polymorphism and encapsulation can be demonstrated
by the Shape interface. You can imagine many types of object that
provide this interface: circles, rectangles, line segments, and
so on. Each of these object types may implement the Draw method
in its own way. For example, the rectangle implements Draw to
render a rectangle, while the circle implements Draw to render
a circle.
Each of these shapes can use the most appropriate type of data
to define what to draw. The rectangle would probably use two control
points to define its drawing area, while the circle might use
a center point and radius. Encapsulation keeps this implementation
detail hidden from users of the Shape interface.
An application that uses the Shape interface could call the Draw
method on a rectangle Xtra, a circle Xtra, or any other Xtra that
implements the Shape interface, and reliably get a rendering of
the appropriate shape.
-
- The previous section referred to a type of object,
such as a rectangle object. For a given Xtra, you may want to
create any number of objects. For example, an animation program
may use several rectangles, each independent of the other. This
means you need a way to define the behavior of a rectangle Xtra
once, then allow the application to recreate that behavior any
number of times. To define a specific type of Xtra object, you
define a class. Objects of a specific class are referred to as
instances of that class.
A MOA class implements an interface by providing a method implementation
for each method. It's possible for any number of instances to
be created from the class, each responding to the methods in its
interfaces. The class also defines data, or instance variables,
and each instance has its own set of these variables.
Instance variables are private, accessible only within the method
implementations. The terms object and instance are
often used interchangeably throughout this document.
In practice, some classes are only instantiated once. For example,
you may only need one instance of a particular sound filter in
SoundEdit. In any case, classes provide a modular way to implement
the specific interaction described by an interface.
-
- Using interfaces, classes, and objects, the MOA object model
provides a modular way to specify interaction between a Macromedia
application and an Xtra. This section explores the general relationship
between applications and Xtras.
-
- All interfaces used between applications and Xtras are defined
by Macromedia. In a sense, the application forms the base or foundation
for the Xtra, the interfaces serve as an intermediate layer, and
Xtras are supported by the application and its interfaces.
-
- Some MOA interfaces are intended to be implemented by classes
in an application, others by classes in an Xtra. The interfaces
implemented by an application are referred to as callback interfaces.
Those implemented by Xtras are called Xtra interfaces.

Callback interfaces are implemented by classes in an application
and provided for use by its Xtras. When implementing an Xtra,
you are given access to the callback interfaces to get information
from the application. Some callback interfaces are general purpose;
others are provided for the specific purposes of a particular
application. Each application defines and instantiates the classes
that implement its callback interfaces.
Xtra interfaces are intended to be implemented by classes in the
Xtra and used by the application. The application creates instances
of the classes in the Xtra and uses them to perform behavior specified
by the Xtra interface.
-
- The lifetime of an Xtra object is controlled in part by MOA
and in part by the specific application it is interacting with.
There are five general phases in the lifecycle of a MOA Xtra:
startup, registration, instantiation, activation, and release.
This section explores these phases in sequence.
-
- When an application starts up, it checks for Xtras in a couple
of standard directories. The precise path to these directories
is platform dependent, as listed in the following table:
Macintosh
<Application folder>:Xtras
Windows NT/Windows 95
<Application dir>\Xtras
In all cases, MOA applications search this directory to a depth
of five subdirectories. When it encounters a new Xtra (one that
wasn't registered the last time the application started), MOA
attempts to register the Xtra.
-
- When an application finds an Xtra for the first time, it registers
it. Registration is provided through a standard Xtra interface, IMoaRegister, with
one method, Register().
The purpose of this interface is to enable an application to determine
the classes and interfaces implemented by your Xtra. Each Xtra
includes this information in its implementation of the IMoaRegister interface. In addition, all MOA applications define specific keys
and values to be added to the cache through the IMoaRegister interface. This enables the application to determine what functionality
your Xtra provides--and thus, where in its user interface to make
your Xtra available to the user.
-
- Once an Xtra has been registered, the application automatically
makes it available to the user at appropriate times. Instances
of your Xtra classes are often created as the result of the user
selecting an item from a menu or manipulating some other user
interface feature. For example, in SoundEdit, Xtra objects are
created when the user selects their behavior from the menu, and
disposed of after the user finishes using them (usually by closing
their dialog box).
In other cases, one Xtra object may create instances of other
classes defined by the same Xtra. In Director, for example, a
media asset object is created when the user adds a media asset
Xtra to the cast. The media asset object, in turn, creates an
instance of an associated sprite actor class when the media asset
is added to the score.
Whenever an Xtra object is instantiated, MOA automatically initializes
a couple of instance variables belonging to all MOA objects: pCalloc and pCallback. These
are set to some standard interfaces within the application. The
next section describes in greater detail how an Xtra uses these
instance variables.
-
- A Macromedia application invokes the behavior of your Xtra
by calling methods in the Xtra interfaces you've implemented.
Some Xtra interface methods may be called by an application as
the result of user action. Other methods are called as the internal
code of the application performs some behavior in which your Xtra
interacts, for example, the animation or event-handling loops.
-
- As the application uses Xtra objects, it requests interfaces
from them, calls methods in those interfaces, then releases them.
MOA uses reference counting to determine when an object is in
use and when it can be purged from memory. Each time an interface
is requested from an object, the reference count for that interface
is incremented. Each time an interface is released, the reference
count is decremented. When all references to all interfaces of
an object have been released, the reference count drops to 0 and
the object becomes a target for purging from memory. Note that
the object may not be purged immediately--the application will
determine when it needs additional memory and purge any unreferenced
objects at the appropriate time.
-
- To complete the picture of how applications and Xtras interact
through MOA interfaces, this discussion details the ways applications
provide interfaces to Xtras and Xtras provide interfaces to applications.
-
- There are a number of standard interfaces defined by MOA.
Among these are several standard callback interfaces intended
to be provided by an application for the use of its Xtras. These
callback interfaces are:
Interface Purpose
IMoaCalloc Standard
memory allocation and release
IMoaCallback General
access to an application
IMoaHandle Handle-based
memory allocation
IMoaProgressBox User
notification for longer processes
IMoaStream Access
to file and memory buffers
IMoaPixelAccess Access
to bitmap pixel information
In addition, MOA defines a standard Xtra interface, IMoaRegister.
This interface defines a way for Xtras to describe their capabilities
to an application, including the classes and interfaces they implement.
-
- Each MOA-capable application defines a class that represents
the top-level access to its capabilities. One instance of this
class is created when the application starts; this instance is
referred to as the callback object. The callback object is the
main way all Xtras get access to the capabilities of an application.
The callback object is accessed through the standard MOA instance
variable pCallback.
-
- An application makes its capabilities available to an Xtra
through various callback interfaces. Some of these are provided
by the callback object, others are provided by objects of other
classes.
The diagram below shows a number of callback interfaces provided
by an application to an Xtra. Some of these are standard interfaces
defined by MOA. Some are standard interfaces defined by the application.
Others are optional interfaces, supplied by either MOA or the
application.
This diagram illustrates three ways interfaces are provided by
an application for use by an Xtra. From top to bottom, these are:
-
- Each Xtra object has two instance variables provided by MOA
that point to interfaces within an application, pCalloc and pCallback.
The pCalloc instance
variable provides the application's IMoaCalloc interface. This interface is used by the Xtra to allocate small
chunks of non-relocatable memory, such as those required by its
instance variables.
The pCallback instance
variable provides the IMoaCallback interface of the application's callback object. This interface
can be considered the main entry point to the application. Through
it, the Xtra acquires access to all other interfaces and objects
provided by the application.
-
- To use other interfaces provided by an application, an Xtra
often acquires them from the application's callback object. To
do so, it calls the QueryInterface() method on the interface provided by pCallback. QueryInterface() is
a standard method of all MOA interfaces, used to acquire other
interfaces provided by the same object. Through this method, the
Xtra gets access to the application's IMoaHandle interface, used for allocating larger chunks of relocatable memory.
The Xtra can also use QueryInterface() to access the "top-level"
interface for application-specific functionality. Other general-purpose
interfaces provided by calling QueryInterface() on pCallback may include IMoaProgressBox, IMoaStream,
and utility interfaces provided by the application.
-
- The third general way an Xtra acquires interfaces and objects
from an application is by calling methods in one of the callback
interfaces provided through pCallback.
For example, the application's top-level interface may provide
methods that return interfaces to other objects--referred to in
the diagram as "model objects"--within the application.
One example would be an object representing an open document in
an application. The interfaces of these model objects in turn
may include methods for accessing the interfaces of other objects
representing internal details of the application.
-
- A MOA application can get the use of interfaces provided by
an Xtra in a couple of ways, as shown in the following diagram.
The diagram also illustrates how methods of an Xtra interface
may be used to provide callback interfaces from the application
to the Xtra.

-
- Before it accesses any other classes or interfaces provided
by an Xtra, an application needs to learn the capabilities of
the Xtra. The standard Xtra interface IMoaRegister provides the mechanism for this. This interface consists of one
method, Register(),
invoked by the application's registration process the first time
it detects your Xtra. The registry calls your Xtra's Register() method to get some standard information and some application-specific
information. Standard information provided by every Xtra includes
the classes and interfaces it provides. Application-specific information
provided by an Xtra helps the application determine where your
Xtra should appear in its menus. When it calls this method, the
application provides the callback interfaces IMoaCache and IMoaDict to the
Xtra for storing registration information.
Note that MOA creates an instance of an Xtra object before calling Register() on it.
It only does this the first time it encounters the Xtra in the
standard Xtras folders. The object is only created so the application
can register it; it is usually purged from memory immediately.
Subsequently, MOA and the application can use information in the
cache to create "real" instances of the Xtra for use
within the context of the application.
-
- After registration, the application knows the classes and
interfaces your Xtra provides. It can then create an instance
of the class and access the Xtra interfaces it provides. Certain
methods in the interface you implement may be passed additional
callback interfaces from the application. For example, the hypothetical
Xtra interface IMoaHello could include a Hello() method for your object to pass its greeting. One parameter of
this method may be an instance of IMoaStream,
a MOA callback interface for writing data to streams. Your implementation
of Hello() calls methods
in IMoaStream to write
a greeting from the Xtra to the application.
The next chapter shows how an Xtra would implement this hypothetical IMoaHello interface,
using the various mechanisms described above to provide interfaces
to the application and to access interfaces provided by the application.
Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.