diff --git a/Documentation/sources/Reference/ofxParameter.rst b/Documentation/sources/Reference/ofxParameter.rst index 4f3c91d68..9e26b7c50 100644 --- a/Documentation/sources/Reference/ofxParameter.rst +++ b/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 ---------------- diff --git a/Documentation/sources/Reference/ofxPropertiesByObject.rst b/Documentation/sources/Reference/ofxPropertiesByObject.rst index 097047816..ccc77e83f 100644 --- a/Documentation/sources/Reference/ofxPropertiesByObject.rst +++ b/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 ------------------------------- diff --git a/Documentation/sources/Reference/ofxPropertiesReference.rst b/Documentation/sources/Reference/ofxPropertiesReference.rst index 6bc551e81..b0151d01e 100644 --- a/Documentation/sources/Reference/ofxPropertiesReference.rst +++ b/Documentation/sources/Reference/ofxPropertiesReference.rst @@ -201,6 +201,8 @@ Properties Reference .. doxygendefine:: kOfxParamPropChoiceOption +.. doxygendefine:: kOfxParamPropChoiceValue + .. doxygendefine:: kOfxParamPropCustomInterpCallbackV1 .. doxygendefine:: kOfxParamPropCustomValue diff --git a/Support/Library/ofxsParams.cpp b/Support/Library/ofxsParams.cpp index 5077d3dcf..7229ab6d5 100644 --- a/Support/Library/ofxsParams.cpp +++ b/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); diff --git a/include/ofxParam.h b/include/ofxParam.h index c3f355315..6197098de 100644 --- a/include/ofxParam.h +++ b/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"