DR Developer's Guide
DR Interfaces | DR Methods | DR Types and Misc API
 
Using the Property page interfaces

The IMuiPropertyPage interface is available by calling IMoaCallback::MoaCreateInstance, with the class identifier CLSID_IMuiPropertyPage, and the interface identifier IID_IMuiPropertyPage.

The support interfaces, IMuiPropertyPageTarget and IMuiPropertyPageInstance, are only obtained when passed as parameters to the methods of the IMuiPropertyPage interface.

The Xtra you create must define and implement a new MOA object that implements the IMuiPropertyPage interface. The MOA object is created and used solely for user interface purposes and can be implemented in a separate authoring Xtra that supplements the playback Xtra.

Use the information in the View Description List File Syntax section to define Property Inspector controls for Xtras that you create.

Note: The IMuiPropertyPage interface should not be implemented by the asset object.

 
Registry setting
To set the registry for the IMuiPropertyPage interface, use the AddRegistryEntry method to add the kMuiDictKey_PropPageEntry to your Registry Dict.

Syntax
pRegDict->Put(kMuiDictKey_PropPageEntry, VDLPath, sizeof(VDLPath), kMuiDictKey_PropPageEntry);

Parameter
VDLPath A string separated by newlines ("\n") that points to a Property page in the Property page tree. For example, if the asset is registered under xtraTypeSymbol, the string would be member\nxtraTypeSymbol.

Description
When the Register method of the Asset Xtra you have created is called, the MOA object it defines and implements is registered with the IMuiPropertyPage interface using the registry setting kMuiDictKey_PropPageEntry. This key is used by Director to map the IMuiPropertyPage interface in the registry to the Property page it supports.

When Director is launched, it scans the registry and finds registered objects that support the IMuiPropertyPage interface, creates an instance of the objects, and invokes the GetDescriptor method for each object. These object instances remain in existence until Director shuts down.

The first time a user selects an instance of an asset associated with the Asset Xtra, the Property inspector will target the asset by instantiating a Property page from the template provided by the Xtra's GetDescriptor method.

 
IMuiPropertyPage

Interface ID: IID_IMuiPropertyPage
Class ID: CID_IMuiPropertyPage
Pointer type: PIMuiPropertyPage
Inheritance: IMoaUnknown
Header file: muippage.h

 
Description
The IMuiPropertyPage interface defines and maintains Property page information for the targeted object or group of objects, using the information in the Xtra's VDL file to map property values to controls, or in the case where the developer sets the controls directly from the C++ code, using the information inside the Xtra.

 
IMuiPropertryPage method summary
GetDescriptor This method is called by Director to retrieve the VDL file data used to describe the Property page associated with the interface. This information is stored in an external VDL file in the props folder, or is returned by the GetDescriptor method.

SetTarget This method is called by Director when the Property inspector targets an instance of a new media asset supported by the Asset Xtra you have created.

ItemClicked This method is called by Director whenever a user changes the value of a control (moves the Slider, clicks a button, changes text in an Edit field) on the Property page associated with the IMuiPropertyPage object.

UpdateItems This method is called by Director to update the Property page to reflect the state of the currently targeted item(s).

Idle This method is called by Director when a user changes the value of a control on the Property page associated with the IMuiPropertyPage object.

 
GetDescriptor

Syntax
GetDescriptor(MoaMmValue* pResult)

Parameters
pResult Contains the VDL file data provided by the Xtra.
Returns
MoaError is returned in the pResult parameter.

Description
Called by Director to retrieve the VDL file information used to describe the Property page for the Asset Xtra. The VDL data can be stored in the Xtra's VDL file in the props folder, or can be provided by the Xtra in this function.

This method can be used instead of a separate VDL file, to describe the layout of the Property page. If the Xtra supports this method, it returns a formatted string that describes it's Property page according to the rules of a VDL file. If an Xtra returns data from this method, and there is a matching VDL file in the props folder, the VDL file has precedence.

 
SetTarget

Syntax
void SetTarget (PIMuiPropertyPageInstance pPageInstance, PIMuiPropertyPageTarget pTarget)

Parameters
pPageInstance The current instance of the Property page as created from the data in a VDL file.

pTarget The object or group of objects currently targeted by the Property inspector. This parameter can be set to NULL to indicate that the Property page has no target.

Returns
No return value.

Description
Called by Director when the Property inspector targets an instance of a new media asset supported by the Asset Xtra you have created. For example, if you created a RealMedia Xtra, and the user selects a RealMedia cast member, the SetTarget method associated with the instance of IMuiPropertyPage created when Director was launched, is invoked.

 
ItemClicked

Syntax
MoaBool ItemClicked (MoaMmSymbol itemID, ConstPMoaMmValue pItemValue,
PIMuiPropertyPageInstance pPageInstance, PIMuiPropertyPageTarget pTarget)

Parameters
itemID The symbol for the control the user clicked or modified. The symbol is defined in the VDL data for the Property page.

pItemValue A Moa value representing the new value of the control. For example, if the control is an Edit field, the value is a string representing the contents of the Edit field when the user presses enter.

pPageInstance The current instance of the Property page. Use this parameter to query the state/value of the controls on the Property page that were not selected by the user, in order to determine the next action.

pTarget The object or collection of objects currently targeted by the Property inspector. This parameter can be used to set properties for the object(s) using the value of the controls on the Property page.

Returns
A boolean. Set this to TRUE if you have handled the Property page message and wish to discontinue the VDL property mapping. Set this to FALSE if you want VDL property mapping to continue.

Description
Called by Director whenever a user changes the value of a control (moves the Slider, clicks a button, changes text in an Edit field) on the Property page associated with the IMuiPropertyPage object. This method allows the Xtra to access controls or fields on the Property page that are not mapped directly to properties in the Xtra, such as buttons that invoke other dialog boxes or behaviors. The property mapping built directly into the VDL file automatically maps controls to property values for most properties; you need only provide special handling for the few special properties that require it.

 
UpdateItems

Syntax
void UpdateItems (PIMuiPropertyPageInstance pPageInstance, PIMuiPropertyPageTarget pTarget)

Parameters
pPageInstance The current instance of the Property page. Use this parameter to query the state/value of the controls on the Property page that were not selected by the user, in order to determine the next action.

pTarget The object or collection of objects currently targeted by the Property inspector. This parameter can be used to set properties for the targeted object(s) using the value of the controls on the Property page.

Returns
No value returned.

Description
This method is called by Director once an object or group of objects are targeted, or when targeted objects have changed in some way. This method allows the IMuiPropertyPage interface to set specific control values (enabled, visible, and so on) on the Property page according to the current state of the targeted object.

The VDL file for a Property page can take care of simple mappings of property values to controls that do not have additional built in logic, but once the value of a particular control is set from the Xtra's C++ code, the VDL property mapping will not happen for that control, and the state of that control becomes the responsibility of the programmer. Controls do not necessarily retain state information, therefore each time this method is called, it should set the controls it requires.

 
Idle

Syntax
void Idle (PIMuiPropertyPageInstance pPageInstance, PIMuiPropertyPageTarget pTarget)

Parameters
pPageInstance The current instance of the Property page.

pTarget The object or collection of objects currently targeted by the Property inspector.

Returns
No return value.

Description
This method is periodically called by Director when the IMuiPropertyPage interface is targeting an object, which allows Director to perform ongoing processing, such as animation, sound, and playback.

 
IMuiPropertyPageTarget

Interface ID: IID_IMuiPropertyPageTarget
Class ID: CID_IMuiPropertyPageTarget
Pointer type: PIMuiPropertyPageTarget
Inheritance: IMoaUnknown
Header file: muipage.h

 
Description
The IMuiPropertyPageTarget interface creates an abstraction layer above the object or group of objects targeted by the Property page. This layer of abstraction creates a generic interface for accessing multiple targeted objects. When the Property page targets multiple objects, a single call to this interface allows you to set the properties for all of the objects at the same time.

 
IMUIPropertyPageTarget method summary
GetTargetCount Determines how many items the Property inspector is currently targeting.

GetNthTarget Allows developers to access specific individual targeted objects when more than one object is targeted.

GetProp Returns the value of a particular property for all of the targeted objects.

SetProp Sets the value of a particular property for all of the targeted objects.

 
GetTargetCount

Syntax
GetTargetCount(PMoaLong pCount)

Parameters
pCount A pointer to a MoaLong.

Returns
MoaError

Description
Call this method to determine the number of objects currently targeted by the Property inspector.

 
GetNthTarget

Syntax
GetNthTarget(MoaLong index, PIMoaUnknown* ppTarget)

Parameters
index The index of the targeted object to be retrieved. Targeted objects use a zero-based index.

ppTarget A pointer to a PIMoaUnknown* interface for the targeted object (ppTarget) specified in the arguments.

Returns
MoaError

Description
Call this method to gain access to individual targeted objects. This interface can be queried to provide access for other interfaces such as the IMoaMmXAsset interface, or a private interface supported by the asset.

 
GetProp

Syntax
GetProp(MoaMmSymbol property, PMoaMmValue pResult)

Parameters
property A pointer to a specific MoaMmSymbol property.

pResult The parameter by which the value of the property being queried is returned.

Returns
MoaError

Description
Call this method to query the value of a particular property for all currently targeted objects. If all of the objects have the same value for the specified property, the value of that property is put into pResult. If all of the objects have different values, the type of pResult is void with a Null value.

 
SetProp

Syntax
SetProp(MoaMmSymbol property, PMoaMmValue pValue)

Parameters
property The property to be set.

pValue A pointer to a value for the property being set.

Returns
MoaError

Description
Call this method to set the value of a particular property for all of the currently targeted objects.

 
IMuiPropertyPageInstance

Interface ID: IID_IMuiPropertyPageInstance
Class ID: CID_IMuiPropertyPageInstance
Pointer type: PIMuiPropertyPageInstance
Inheritance: IMoaUnknown
Header file: muipage.h

 
Description
The IMuiPropertyPageInstance interface is a support interface for the IMuiPropertyPage interface, and represents the current state of the instantiated Property page generated from the VDL data provided by the Xtra or the data in the Xtra's VDL file in the props folder. Use the methods of the IMuiPropertyPageInstance interface to get or set the state or value of specific controls in the UpdateItem or ItemClicked methods of the IMuiPropertyPage interface.

You can use the SetControlProp and GetControlProp methods to set and retrieve the value of a control on the Property page. The developer passes in a symbol specifying a control to query and set, as well as a symbol identifying which control property they wish to set or receive.

 
IMuiPropertyPageInstance method summary
GetControlProp Retrieves the value of a particular property for all currently targeted objects.

SetControlProp Sets the value for a particular property for all currently targeted objects.

 
GetControlProp

Syntax
GetControl(MoaMmSymbol controlID, MoaMmSymbol property, MoaMmValue pResult)

Parameters
controlID The MoaMmSymbol identifying the control to query. This symbol is specified in the VDL information provided by the Xtra, or in the Xtra's VDL file in the props folder.

property The MoaMmSymbol identifying the property to retrieve. Predefined properties include: #value, #enabled, #visible, #range, #min and #max.

pResult Returns the value of the requested control's property. If the #value property is requested, and the control state cannot be determined, pResult is of type void.

Returns
MoaError

Description
Call this method to retrieve the state/value information on the Property page for the specified property.

 
SetControlProp

Syntax
SetControl(MoaMmSymbol controlID, MoaMmSymbol property, ConstPMoaMmValue pValue)

Parameters
controlID The MoaMmSymbol identifying the control to be set. This symbol is specified in the VDL information provided by the Xtra, or in the Xtra's VDL file in the props folder.

property The MoaMmSymbol identifying the property to retrieve. Predefined properties include: #value, #enabled, #visible, #range, #min and #max.

pValue A pointer to the value of the property being set.

Returns
MoaError

Description
Call this method to set the state/value of a control on the Property page. This method is typically called from the UpdateItems method.


Copyright © 1999-2007 Adobe Macromedia Software LLC, Inc.