Preconditions and Validators

Gadgets > Creating GUI Applications with Rogue Wave Views Studio > Using Inspector Classes > Components of an Inspector Panel > 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 Rogue Wave 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".

Version 6.3