Preconditions and Validators
Accessors use internally the classes
IlvStIPrecondition and
IlvStIValidator, and their derived classes, to perform a number of verifications.
Preconditions
Preconditions are tests that accessors can run to determine whether they can access the inspected property. These tests are performed by calling the method
isAccessible of the class
IlvStIPrecondition. If the precondition test succeeds, access is allowed. Otherwise, it is denied and the associated editors are disabled.
The classes
IlvStIPreconditionValue and
IlvStICallbackPrecondition are two classes derived from
IlvStIPrecondition that are sufficient to run precondition tests in most cases.
IlvStIPreconditionValue objects compare the value returned by an accessor with a given value.
Let us consider an accessor to the scientific mode property of a number field. As shown below, access is permitted only if the float mode is set for the number field.
//This code extract is part of the code of an inspector panel.
IlvStIEditor* editor = link("NumFieldFloat", IlvNumberField::_floatModeValue);
IlvStIPropertyAccessor* floatAccessor = editor->getAccessor();
floatAccessor->setPreviewValueAccessor(previewAccessor,
IlvNumberField::_floatModeValue);
// Scientific value.
IlvStIEditor* editor = link(“ScientificField”,
IlvNumberField::_scientificModeValue);
editor->getAccessor()->setPrecondition(
new IlvStIPreconditionValue(floatAccessor,
(IlBoolean)IlTrue,
(IlBoolean)IlFalse));
The
IlvStICallbackPrecondition class is provided for cases where the code of the
isAccessible function can be included in a callback. Using this class, you can avoid deriving the
IlvStIPrecondition class.
The following code sample implements a precondition that is used to avoid changing the alignment of a gadget item label if it does not contain one or more “end-of-line” characters.
IlBoolean
IlvStIsMultiLineText(IlvStIProperty* property,
IlvAny,
IlvStIProperty**,
IlvStIPropertyAccessor::PropertyStatus*)
{
if (!property)
return IlFalse;
IlvValue value;
const char* label = (const char*)property->getValue(value);
if (!label)
return IlFalse;
while (*label)
if (*label++ == ‘\n’)
return IlTrue;
return IlFalse;
}
The callback precondition will be used as follows:
// Define an accessor to the label of the inspected gadget item.
IlvStIPropertyAccessor* labelAcc;
...
// Define the accessor to the alignment of the
// the inspected gadget item label.
IlvStIPropertyAccessor* labelAlignAcc;
...
labelAlignAcc->setPrecondition(
new IlvStICallbackPrecondition(labelAcc,
IlvStIsMultiLineText));
Validators
The Views Studio Inspectors API includes a validator class,
IlvStIValidator, that you can use to test whether the values entered by the user are correct. The test is performed with the
isValid method of the class. This methods tests the value passed as its parameter and returns an error of the type
IlvStIError if the value is not valid. You can define whether the test should be carried out when the user’s modifications are entered or only when he/she clicks on Apply button in the inspector panel.
IlvStIValidator has a derived class,
IlvStIRangeValidator, that tests whether a value is between a minimum and a maximum value. In addition to a value range, this class takes a message string as a parameter. This message string specifies an error message that can contain one or more
%1,
%2, and
%3 substrings. These substrings are replaced by the minimum value, the maximum value, and the tested value, respectively.
The following example shows how to use a validator to check whether the month entered by the user is between 1 and 12.
// Define an accessor to the month property, called monthAccessor.
IlvStIPropertyAccessor* monthAccessor;
...
// Add the month validator to the month accessor.
IlvStIRangeValidator* monthValidator =
new IlvStIRangeValidator((IlvInt)1, (IlvInt)12, "&MonthNotInRange");
monthAccessor->setValidator(monthValidator);
The message string "&MonthNotInRange" is translated as follows:
"You must specify a month between %1 and %2".
Published date: 05/24/2022
Last modified date: 02/24/2022
