DR Developer's Guide
DR Interfaces |
DR Methods |
DR Types and Misc API
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.
- 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.
- 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.
- 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.
- 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.
- 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.