Type definitions for for plugin configuration. More...

Typedefs
typedef enum MVPluginParameterPresentationProperty_t	MVPluginParameterPresentationProperty_t

typedef enum MVPluginParameterWidget_t	MVPluginParameterWidget_t

typedef enum MVPluginParameterConstraint_t	MVPluginParameterConstraint_t

typedef enum MVPluginConfigValidationErrorState_t	MVPluginConfigValidationErrorState_t

typedef struct _MVPluginUserParameterDescription_t *	MVPluginUserParameterDescription_t
	Opaque data type which stores the plug-in-provided description of user configuration parameters. More...

typedef struct _MVPluginConfigValidation_t *	MVPluginConfigValidation_t
	Opaque data type which stores the result of a configuration parameter validation. More...

Enumerations
enum	MVPluginParameterPresentationProperty_t { eMVPluginParameterPresentationProperty_DisplayName = 0, eMVPluginParameterPresentationProperty_Prefix = 1, eMVPluginParameterPresentationProperty_Suffix = 2, eMVPluginParameterPresentationProperty_Category = 3, eMVPluginParameterPresentationProperty_PreferredWidget = 4 }
	Specifies how the parameter is presented to the user in the configuration interface. More...

enum	MVPluginParameterWidget_t { eMVPluginParameterWidget_Default = 0, eMVPluginParameterWidget_TextField = 1, eMVPluginParameterWidget_PasswordEntry = 2, eMVPluginParameterWidget_SpinBox = 3, eMVPluginParameterWidget_Slider = 4, eMVPluginParameterWidget_CheckBox = 5, eMVPluginParameterWidget_ComboBox = 6, eMVPluginParameterWidget_ButtonGroup = 7, eMVPluginParameterWidget_FileChooser = 8, eMVPluginParameterWidget_DirectoryChooser = 9 }
	Suggests a type of widget suitable for a given plug-in user parameter. More...

enum	MVPluginParameterConstraint_t { eMVPluginParameterConstraint_Range = 0, eMVPluginParameterConstraint_ValueList = 1 }
	Enforces the parameter values to meet certain requirements. More...

enum	MVPluginConfigValidationErrorState_t { eMVPluginConfigValidationErrorState_NoError = 0, eMVPluginConfigValidationErrorState_Warning = 1, eMVPluginConfigValidationErrorState_Error = 2 }
	Indicates the error state of a user parameter or plug-in configuration. More...

Detailed Description

Type definitions for for plugin configuration.

Typedef Documentation

◆ MVPluginConfigValidation_t

typedef struct _MVPluginConfigValidation_t* MVPluginConfigValidation_t

Opaque data type which stores the result of a configuration parameter validation.

MVPluginConfigValidation_t is a pointer to an opaque data structure. It is passed as an argument to the MVValidate plug-in API function along with the configuration which is to be validated and initially does not indicate any validation errors. Plug-ins can apply whatever domain- specific validation logic and use the API functions in mv_plugin_config.h to store their validation result.

◆ MVPluginUserParameterDescription_t

typedef struct _MVPluginUserParameterDescription_t* MVPluginUserParameterDescription_t

Opaque data type which stores the plug-in-provided description of user configuration parameters.

MVPluginUserParameterDescription_t is a pointer to an opaque data structure. It is passed as an argument to the MVExpose plug-in API function and initially represents an plug-in with no user-providable configuration parameters. Plug-ins can dynamically build their configuration interface by calling the API functions in mv_plugin_config.h to modify the parameter description.

Enumeration Type Documentation

◆ MVPluginConfigValidationErrorState_t

enum MVPluginConfigValidationErrorState_t

Indicates the error state of a user parameter or plug-in configuration.

Set these states by calling MV_PluginConfigValidation_SetUserParameterErrorState() or MV_PluginConfigValidation_SetMessage() passing the enum value.

Enumerator
eMVPluginConfigValidationErrorState_NoError	Indicates a non erroneous state. This is the default.
eMVPluginConfigValidationErrorState_Warning	Indicates potential configuration issues that may prevent the plug-in from working correctly.
eMVPluginConfigValidationErrorState_Error	Indicates an error that will prevent the plug-in from working correctly.

◆ MVPluginParameterConstraint_t

enum MVPluginParameterConstraint_t

Enforces the parameter values to meet certain requirements.

Set these options by calling MV_PluginUserParameterDescription_ImposeConstraint() passing the enum value and an MVValue_t with the data structured as documented.

Note that imposing a constraint replaces any existing constraint.

Enumerator

eMVPluginParameterConstraint_Range

Enforces the values of the parameter to be in a specified range.

Possible values are MV_Value_Arrays with either two or three numeric values. If two numeric values are given, they are interpreted as minimum and maximum value, respectively. If three numeric values are given, the third value is interpreted as the step size, i.e., the strictly positive number with which the parameter value is incremented or decremented in each step.

All arguments must be of the same data type as the initial value. Passing something different than an MV_Value_Array with two or three numeric values will result in an error. For each combination, the conditions min < min + step_size <= max and min <= initial_value <= max must hold.

Range constrained values are truncated in order to fulfill the min <= value <= max property. In case of a present step size, the value will be rounded towards the nearest step. Ambiguity is addressed with rounding towards zero.

eMVPluginParameterConstraint_ValueList

Adds a list with possible values to the parameter.

A value list is an exclusive list of possible parameter values of the same data type as the initial value. They can be shown in the interface, e.g., as a dropdown menu.

Possible values are MV_Value_Arrays with any number of items. All values must be of the same data type as the initial value. The initial value must be included in the list.

For arithmetic types, value list constrained values are rounded towards the nearest option in the list. Ambiguity is addressed with rounding towards zero.

◆ MVPluginParameterPresentationProperty_t

enum MVPluginParameterPresentationProperty_t

Specifies how the parameter is presented to the user in the configuration interface.

Set these properties by calling MV_PluginUserParameterDescription_SetPresentationProperty() passing the enum value and an MVValue_t with the data structured as documented.

Enumerator
eMVPluginParameterPresentationProperty_DisplayName	Sets the display name for a parameter. The UTF-8 encoded string is used as a readable name for the parameter in the configuration interface.
eMVPluginParameterPresentationProperty_Prefix	Adds a (unit) prefix to the parameter value. The UTF-8 encoded string is shown before the parameter value editor in the configuration interface. An example for a parameter prefix is `$` as currency.
eMVPluginParameterPresentationProperty_Suffix	Adds a (unit) suffix to the parameter value. The UTF-8 encoded string is shown after the parameter value editor in the configuration interface. An example for a parameter suffix is `"ms"` for a connection timeout.
eMVPluginParameterPresentationProperty_Category	Sets the displayed category name for a parameter.
eMVPluginParameterPresentationProperty_PreferredWidget	Provide a hint as to the preferred control widget for the parameter. The associated UInt32 should correspond to the numeric value of the desired enumerator in

◆ MVPluginParameterWidget_t

enum MVPluginParameterWidget_t

Suggests a type of widget suitable for a given plug-in user parameter.

The default widget type used to represent a plug-in parameter will in general depend on the parameter's type and on the constraints imposed on it. However, sometimes multiple widgets are compatible with the constraints. For instance, a numeric parameter with a value range and a step size could be equally well represented by a spinbox or a slider widget. It is up to the configuration GUI (and its capabilities) to decide which widget will be used, but it is possible it express a preference by setting the property eMVPluginParameterPresentationProperty_PreferredWidget to the numeric value one of these enumerators.

Enumerator
eMVPluginParameterWidget_Default	Do not express a preference; use the default widget.
eMVPluginParameterWidget_TextField	Use a plain text field.
eMVPluginParameterWidget_PasswordEntry	Use a text field which hides the entered text. This aims to prevent "shoulder surfing" but does not provide any encryption.
eMVPluginParameterWidget_SpinBox	Use a spinbox which allows to increment and decrement numeric values by a step. Spinboxes can only be used when a range constraint with step size is imposed.
eMVPluginParameterWidget_Slider	Use a slider to visualize the position of the value in the allowed range. Sliders can only be used when a range constraint is imposed. They should be preferred when the precise value is not important.
eMVPluginParameterWidget_CheckBox	Use a checkbox to represent a toggleable boolean option.
eMVPluginParameterWidget_ComboBox	Use a combobox to represent a choice between multiple values. Comboboxes can only be used when a value list constraint is imposed.
eMVPluginParameterWidget_ButtonGroup	Use a connected button group to represent a choice between few values. Button groups can only be used when a value list constraint is imposed.
eMVPluginParameterWidget_FileChooser	Allow setting a text field to a browsable file path. File choosers may only be supported when the plugin is configured on the same system that the Communicator is running on.
eMVPluginParameterWidget_DirectoryChooser	Allow setting a text field to a browsable directory path. Directory choosers may only be supported when the plugin is configured on the same system that the Communicator is running on.

Typedefs

Enumerations