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