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

IMoaDrPreferenceAccess


Interface ID: IID_IMoaDrPreferenceAccess
Pointer type: PIMoaDrPreferenceAccess
Class ID: CID_IMoaDrPreferenceAccess Inheritance: IMoaUnknown
Header file: driservc.h

Description

The IMoaDrPreferenceAccess interface provides access to Director's preference file. This allows developers to add custom preferences (author time only) for an Xtra, that the Xtra can access at any time. These interfaces do not provide access to the built-in Director preferences. The Director preferences are stored in the registry on Windows and in the preference file on Macintosh.

To use the IMoaDrPreferenceAccess methods, you must pass in a unique ID (prefGUID) and a string identifying the preference (prefKey). Only by passing in the same GUID and string can you access the preference. The prefGUID needs to be an Xtra's ClassID and must have an associated kMoaMmDictKey_DisplayNameString value in the registry.

IMoaDrPreferenceAccess is an additional interface on the main callback object.

Note: syntax provided in C++ format.

 
IMoaDrPreferenceAccess method summary

SetDataPref Sets a preference containing raw data.
SetStringPref Sets a preference containing a string.
SetFlagPref Sets a preference containing a flag(Bool).
SetLongPref Sets a preference containing a long integer.
SetDoublePref Sets a preference containing a double float.
SetPointPref Sets a preference containing a point.
SetRectPref Sets a preference containing a rect.

GetDataPref Gets a preference containing raw data.
GetStringPref Gets a preference containing a string.
GetFlagPref Gets a preference containing a flag(Bool).
GetLongPref Gets a preference containing a long integer.
GetDoublePref Gets a preference containing a double float.
GetPointPref Gets a preference containing a point.
GetRectPref Gets a preference containing a rectangle.


SetDataPref()

Syntax
SetDataPref(PMoaChar prefKey, MoaID prefGUID, PMoaVoid pData, MoaUlong size)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pData
A pointer to data you have prepared for your custom preference
size
The size, in bytes, of the data referenced by pData
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidData No data available to save as a pref
Description
Sets a preference containing raw data.

SetStringPref()

Syntax
SetStringPref(PMoaChar prefKey, MoaID prefGUID, PMoaChar pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
A pointer to the null-terminated C-string value for the preference being set
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No string data to save as a pref
Description
Sets a preference containing a string.

SetFlagPref()

Syntax
SetFlagPref(PMoaChar prefKey, MoaID prefGUID, MoaBool value)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
value
A boolean value setting the flag for the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
Description
Sets a preference containing a flag (Boolean value).

SetLongPref()

Syntax
SetLongPref(PMoaChar prefKey, MoaID prefGUID, MoaLong value)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
value
A long integer value for the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
Description
Sets a preference containing a long integer.

SetDoublePref()

Syntax
SetDoublePref(PMoaChar prefKey, MoaID prefGUID, MoaDouble value)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
value
A double float value for the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
Description
Sets a preference containing a double float.

SetPointPref()

Syntax
SetPointPref(PMoaChar prefKey, MoaID prefGUID, MoaPoint value)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
value
A point value for the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
Description
Sets a preference containing a point.

SetRectPref()

Syntax
SetRectPref(PMoaChar prefKey, MoaID prefGUID, MoaRect value)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
value
A rect value for the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
Description
Sets a preference containing a rect.

GetDataPref()

Syntax
GetDataPref(PMoaChar prefKey, MoaID prefGUID, PMoaVoid pData, MoaUlong size)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pData
A pointer to place to receive data for your custom preference
size
The size, in bytes, of the data you want to receive
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the data
Description
Gets a preference containing raw data. If the preference does not exist no error is returned, so you will want to pre-populate your data bytes with a known value.

GetStringPref()

Syntax
GetStringPref(PMoaChar prefKey, MoaID prefGUID, PMoaChar* ppValue, MoaLong bufLen)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
ppValue
A pointer to a MoaChar* that will receive the string value of the preference
bufLen
The size, in bytes, of the string buffer
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the result
kMoaDrPrefsErr_BufferOverrun Not enough room for the result
Description
Gets a preference with a string value. If the preference has not yet been set, the string "notapref" is returned as the default preference value.

GetFlagPref()

Syntax
GetFlagPref(PMoaChar prefKey, MoaID prefGUID, MoaBool* pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
pointer to the flag (boolean) value of the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the pref
Description
Gets a preference containing a flag (Boolean). If the preference has not yet been set, FALSE is assigned to *pValue.

GetLongPref()

Syntax
GetLongPref(PMoaChar prefKey, MoaID prefGUID, MoaLong* pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
A pointer to the long integer value of the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the pref
Description
Gets a preference containing a long integer. If the preference hasn't been set, then a value of zero is provided for the pref.

GetDoublePref()

Syntax
GetDoublePref(PMoaChar prefKey, MoaID prefGUID, PMoaDouble pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
A pointer to the double float value of the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the pref value
Description
Gets a preference containing a double float. If the preference hasn't been set, then 0.0 is the default value.

GetPointPref()

Syntax
GetPointPref(PMoaChar prefKey, MoaID prefGUID, PMoaPoint pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
A pointer to the point value of the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the pref value
Description
Gets a preference containing a point. If no preference exists, point {0,0} is returned.

GetRectPref()

Syntax
GetRectPref(PMoaChar prefKey, MoaID prefGUID, PMoaRect pValue)
Parameters
prefKey
Pointer to a null-terminated C-string representing the preference to set
prefGUID
The ClassID GUID that allows the Xtra to access the preference
pValue
A pointer to the rect value of the preference
Returns
kMoaErr_NoErr Successful
kMoaDrPrefsErr_ClassIDNotValid No kMoaMmDictKey_DisplayNameString for the GUID
kMoaDrPrefsErr_InvalidKey No value provided for prefKey
kMoaDrPrefsErr_InvalidPointer No place to store the resulting pref value
Description
Gets a preference containing raw rectangle. If no preference was previously set, the rectangle {0,0,0,0} is used as the default value.

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