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