Add kOfxParamPropChoiceValue

Signed-off-by: Gary Oberbrunner <[email protected]>

Documentation/sources/Reference/ofxParameter.rst

@@ -151,8 +151,9 @@ Choice Parameters
 
 This is typed by :c:macro:`kOfxParamTypeChoice`.
 
-Choice parameters are integer values from 0 to N-1, which correspond to
-N labeled options.
+Choice parameters are integer values from 0 to N-1, which correspond
+to N labeled options, but see :c:macro:`kOfxParamPropChoiceValue` and
+the section below this for how to change that.
 
 Choice parameters have their individual options set via the
 :c:macro:`kOfxParamPropChoiceOption` property,
@@ -169,6 +170,55 @@ for example
 It is an error to have gaps in the choices after the describe action has
 returned.
 
+Setting Choice Param Values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of OFX v1.5, plugins can optionally specify the value the host
+should store and return for each choice option, using
+:c:macro:`kOfxParamPropChoiceValue`.
+
+This property contains the set of values to be stored when the user
+chooses the corresponding (same-index) option for the choice
+parameter.
+
+This property is useful when changing order of choice param options, or adding new options in the middle,
+in a new version of the plugin.
+
+    ::
+
+       // Plugin v1:
+       Option = {"OptA", "OptB", "OptC"}
+       Value = {0, 1, 2}
+
+       // Plugin v2:
+       Option = {"OptA", "OptB", "NewOpt", "OptC"}
+       Value = {0, 1, 4, 2}
+
+In this case if the user had selected "OptC" in v1, and then loaded the
+project in v2, "OptC" will still be selected even though it is now the 4th
+option, and the plugin will get the param value 2, as it did in its previous
+version.
+
+The default, if unspecified, is ordinal integers starting from zero.
+
+Values may be arbitrary 32-bit integers. The same value must not occur
+more than once in the values list; behavior is undefined if the same
+value occurs twice in the list. The values list must contain the
+default value as specified by :c:macro:`kOfxParamPropDefault`;
+behavior is unspecified if it does not.
+
+To query whether a host supports this, just attempt to set the
+property and check the return status. If the host does not support
+:c:macro:`kOfxParamPropChoiceValue`, a plugin should not insert new
+values into the middle of the options list, nor reorder the options,
+in a new version, otherwise old projects will not load properly.
+
+Note: this property does not help if a plugin wants to *remove* an option. One way to
+handle that case is to define a new choice param in v2 and hide the old v1 param, then use some
+custom logic to populate the v2 param appropriately.
+
+Available since 1.5.
+
 
 String Parameters
 -----------------
@@ -190,6 +240,8 @@ these are
 
 -  .. doxygendefine:: kOfxParamStringIsLabel
 
+-  .. doxygendefine:: kOfxParamStringIsRichTextFormat
+
 Group Parameters
 ----------------
 

Documentation/sources/Reference/ofxPropertiesByObject.rst

@@ -458,6 +458,8 @@ Properties On Choice Parameters
 
 -  kOfxParamPropChoiceOption
    read/write in the descriptor and instance
+-  kOfxParamPropChoiceValue
+   read/write in the descriptor and instance
 
 Properties On Custom Parameters
 -------------------------------

Documentation/sources/Reference/ofxPropertiesReference.rst

@@ -201,6 +201,8 @@ Properties Reference
 
 .. doxygendefine:: kOfxParamPropChoiceOption
 
+.. doxygendefine:: kOfxParamPropChoiceValue
+
 .. doxygendefine:: kOfxParamPropCustomInterpCallbackV1
 
 .. doxygendefine:: kOfxParamPropCustomValue

Support/Library/ofxsParams.cpp

@@ -747,7 +747,7 @@ namespace OFX {
     return nCurrentValues;
   }
 
-  /** @brief set the default value */
+  /** @brief append an option to the choice param */
   void ChoiceParamDescriptor::appendOption(const std::string &v, const std::string& label)
   {
     int nCurrentValues = _paramProps.propGetDimension(kOfxParamPropChoiceOption);
@@ -769,7 +769,7 @@ namespace OFX {
     }
   }
 
-  /** @brief set the default value */
+  /** @brief reset all options */
   void ChoiceParamDescriptor::resetOptions(void)
   {
     _paramProps.propReset(kOfxParamPropChoiceOption);

include/ofxParam.h

@@ -600,16 +600,52 @@ This data pointer is unique to each parameter instance, so two instances of the
  */
 #define kOfxParamPropDataPtr "OfxParamPropDataPtr"
 
-/** @brief Set an option in a choice parameter.
+/** @brief Set options of a choice parameter.
 
     - Type - UTF8 C string X N
     - Property Set - plugin parameter descriptor (read/write) and instance (read/write),
     - Default - the property is empty with no options set.
 
-This property contains the set of options that will be presented to a user from a choice parameter. See @ref ParametersChoice for more details. 
+This property contains the set of options that will be presented to a user
+from a choice parameter. See @ref ParametersChoice for more details.
 */
 #define kOfxParamPropChoiceOption "OfxParamPropChoiceOption"
 
+/** @brief Set values the host should store for a choice parameter.
+
+    - Type - int X N
+    - Property Set - plugin parameter descriptor (read/write) and instance (read/write),
+    - Default - Zero-based ordinal list of same length as `OfxParamPropChoiceOption`
+
+This property contains the set of values to be stored when the user chooses the corresponding
+(same-index) option for the choice parameter. See @ref "Choice Parameters" for more details.
+This property is optional; if not set, the host will store the zero-based integer index
+of the chosen ::kOfxParamPropChoiceOption.
+This property is useful when changing order of choice param options, or adding new options in the middle,
+in a new version of the plugin.
+
+  @verbatim
+  Plugin v1:
+  Option = {"OptA", "OptB", "OptC"}
+  Value = {1, 2, 3}
+
+  Plugin v2:
+  Option = {"OptA", "OptB", "NewOpt", "OptC"}
+  Value = {1, 2, 4, 3}
+  @endverbatim
+
+In this case if the user had selected "OptC" in v1, and then loaded the
+project in v2, "OptC" will still be selected even though it is now the 4th
+option, and the plugin will get the param value 3 (as it did in its previous
+version).
+
+Values may be arbitrary 32-bit integers. Behavior is undefined if the same
+value occurs twice in the list; plugins should not do that.
+
+\since Version 1.5
+*/
+#define kOfxParamPropChoiceValue "OfxParamPropChoiceValue"
+
 /** @brief The minimum value for a numeric parameter.
 
     - Type - int or double X N
@@ -732,26 +768,26 @@ If set to 0, it implies the user can specify a new file name, not just a pre-exi
 #define kOfxParamPropStringFilePathExists    "OfxParamPropStringFilePathExists"
 
 /** @brief Used to set a string parameter to be single line, 
-    value to be passed to a kOfxParamPropStringMode property */
+    value to be passed to a ::kOfxParamPropStringMode property */
 #define kOfxParamStringIsSingleLine    "OfxParamStringIsSingleLine"
 
 /** @brief Used to set a string parameter to be multiple line, 
-    value to be passed to a kOfxParamPropStringMode property */
+    value to be passed to a ::kOfxParamPropStringMode property */
 #define kOfxParamStringIsMultiLine     "OfxParamStringIsMultiLine"
 
 /** @brief Used to set a string parameter to be a file path,
-    value to be passed to a kOfxParamPropStringMode property */
+    value to be passed to a ::kOfxParamPropStringMode property */
 #define kOfxParamStringIsFilePath      "OfxParamStringIsFilePath"
 
 /** @brief Used to set a string parameter to be a directory path,
-    value to be passed to a kOfxParamPropStringMode property */
+    value to be passed to a ::kOfxParamPropStringMode property */
 #define kOfxParamStringIsDirectoryPath "OfxParamStringIsDirectoryPath"
 
 /** @brief Use to set a string parameter to be a simple label, 
-    value to be passed to a kOfxParamPropStringMode property  */
+    value to be passed to a ::kOfxParamPropStringMode property  */
 #define kOfxParamStringIsLabel         "OfxParamStringIsLabel"
 
-/** @brief String value on the OfxParamPropStringMode property of a
+  /** @brief String value on the ::kOfxParamPropStringMode property of a
     string parameter (added in 1.3) */
 #define kOfxParamStringIsRichTextFormat "OfxParamStringIsRichTextFormat"