DR Developer's Guide
DR Interfaces |
DR Methods |
DR Types and Misc API
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.
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.
- 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.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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-2008 Adobe Macromedia Software LLC, Inc.