DR Developer's Guide
DR Interfaces | DR Methods | DR Types and Misc API

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.

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.
Functionality
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.

Methods

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.
UpdateItems() This method is called by Director to update the Property page to reflect the state of the currently targeted item(s).
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.
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
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.

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.

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.

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.

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.

Copyright © 1995-2008 Adobe Macromedia Software LLC, Inc.