Validator

#include <bb/cascades/Validator>

A default validation class used to validate any Control.

Validator includes the following properties:

state: Specifies the current validation state. This property shows the current ValidationState of the control. Controls can listen to changes to this property to respond to state changes.

mode: Specifies the current validation mode. This property configures the validator's scheduling logic.

valid: Specifies the current validity of the Control. This property can be used to set a Validator to a Valid or Invalid state. Controls can listen to changes to this property to respond to state changes if some specific actions must be performed when the state changes to a Valid or Invalid state. For example, if the Control should show an error when the validation state is changed to Invalid. When the valid property changes, the state property changes also.

errorMessage: Specifies the error message. This property contains a text representation of the error in an Invalid state.

The following sample demonstrates how to validate a TextField in C++. The code below assumes that ValidatePasswordApplication has the onValidate() slot.

ValidatePasswordApplication::ValidatePasswordApplication()
{
  TextField* passwordField = TextField::create().hintText("Password");
  passwordField.setValidator(
      Validator::create()
        .errorMessage("Incorrect password")
        .mode(ValidationMode::FocusLost))
        .connect(SIGNAL(validate()), this, SLOT(onValidate()));
}

Here's how to validate a TextField in QML:

TextField {
  id: passwordField
  validator: Validator {
    mode: ValidationMode::FocusLost
    errorMessage: "Invalid password"
    onValidate: {
      // validate a passwordField's text and set appropriate state.
    }
  }
}

Since:

BlackBerry 10.1.0

Inheritance

bb::cascades::BaseObject
	bb::cascades::Validator

QML properties

state	: bb::cascades::ValidationState::Type
mode	: bb::cascades::ValidationMode::Type
valid	: bool
errorMessage	: QString
delay	: int
validationRequested	: bool
objectName	: QString
parent	: QObject [read-only]

QML signals

onStateChanged	: {}
onModeChanged	: {}
onValidChanged	: {}
onErrorMessageChanged	: {}
onDelayChanged	: {}
onValidationRequestedChanged	: {}
onValidate	: {}
onCreationCompleted	: {}
onObjectNameChanged	: {}

Public Types Index

BaseObject

BaseClass

Properties Index

bb::cascades::ValidationState::Type	state
bb::cascades::ValidationMode::Type	mode
bool	valid
QString	errorMessage
int	delay
bool	validationRequested
QString	objectName
QObject	parent [read-only]

Public Functions Index

Q_SLOT void	setState (bb::cascades::ValidationState::Type state)
bb::cascades::ValidationState::Type	state () const
Q_INVOKABLE void	resetState ()
Q_SLOT void	setMode (bb::cascades::ValidationMode::Type mode)
bb::cascades::ValidationMode::Type	mode () const
Q_INVOKABLE void	resetMode ()
Q_SLOT void	setValid (bool valid)
bool	isValid () const
Q_INVOKABLE void	resetValid ()
Q_SLOT void	setErrorMessage (const QString &errorMessage)
QString	errorMessage () const
Q_INVOKABLE void	resetErrorMessage ()
Q_SLOT void	setDelay (int delay)
int	delay () const
Q_INVOKABLE void	resetDelay ()
Q_SLOT void	showMessage ()
Q_SLOT void	setValidationRequested (bool requested)
bool	validationRequested () const
Q_INVOKABLE void	resetValidationRequested ()
Q_SLOT void	requestValidation ()
	Validator (QObject *parent=0)
virtual	~Validator ()
void	setObjectName (const QString &name)
virtual Q_INVOKABLE QString	toDebugString () const

Static Public Functions Index

Builder

create ()

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)

Signals Index

void	stateChanged (bb::cascades::ValidationState::Type newState)
void	modeChanged (bb::cascades::ValidationMode::Type newMode)
void	validChanged (bool valid)
void	errorMessageChanged (const QString errorMessage)
void	delayChanged (int delay)
void	validationRequestedChanged (bool requested)
void	validate ()
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)

Public Types

typedef BaseObject BaseClass

Properties

bb::cascades::ValidationState::Type state

The validation state.

Validation state as defined in ValidationState.

The default value is ValidationState::Unknown.

Since:

BlackBerry 10.1.0

bb::cascades::ValidationMode::Type mode

The validation mode.

Validation mode as defined in ValidationMode.

The default value is ValidationMode::Default.

Since:

BlackBerry 10.1.0

bool valid

Represents whether validation was successful or not.

Returns true if the state property is in a Valid state or no validation was performed yet, false otherwise. This property is bound with the state property. If the state changes to ValidationState::Valid, the valid property will be true. If the state changes to ValidationState::Invalid, the valid property will be false.

Note:

If the state property changes to ValidationState::Unknown or ValidationState::InProgress, then the valid property will not change.

The default value is false.

Since:

BlackBerry 10.1.0

QString errorMessage

Represents the error message.

Contains an error message for the invalid validation state.

The default value is QString::null.

Since:

BlackBerry 10.1.0

int delay

Represents a delay in milliseconds.

The delay, in milliseconds, before the validate signal will be emitted. This value is used in the requestValidation slot in ValidationMode::Delayed mode.

The default value is 2000 milliseconds.

Since:

BlackBerry 10.1.0

bool validationRequested

Represents whether validation was requested or not.

If this property is set to true then requestValidation will be called. When the validate signal is emitted this property would set back to false.

Note:

If the mode is set to ValidationMode::Custom, you can listen to this property to find out when validation has been requested. You are responsible for calling validate and resetting the validationRequested property back to false.

Since:

BlackBerry 10.1.0

QString objectName

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parent[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

Q_SLOT void setState (
bb::cascades::ValidationState::Typestate)

Sets the validation state.

Parameters
state	The validation state.

Since:

BlackBerry 10.1.0

bb::cascades::ValidationState::Type state ()

Returns the validation state.

Return:

The validation state. ValidationState::Unknown by default.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetState ()

Resets the state to its default value.

Since:

BlackBerry 10.1.0

Q_SLOT void setMode (
bb::cascades::ValidationMode::Typemode)

Sets the validation mode.

Parameters
mode	The validation mode.

Since:

BlackBerry 10.1.0

bb::cascades::ValidationMode::Type mode ()

Returns the validation mode.

Return:

The validation mode. ValidationMode::Default by default.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetMode ()

Resets the mode to its default value.

Since:

BlackBerry 10.1.0

Q_SLOT void setValid (
boolvalid)

Sets the valid property.

Parameters
valid	Boolean value.

Since:

BlackBerry 10.1.0

bool isValid ()

Returns the valid value.

Return:

The valid value. The default value is false.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetValid ()

Resets valid to its default value.

Also resets the state to its default value.

Since:

BlackBerry 10.1.0

Q_SLOT void setErrorMessage (
const QString &errorMessage)

Sets the error message text.

Parameters
errorMessage	The error message text.

Since:

BlackBerry 10.1.0

QString errorMessage ()

Returns the errorMessage text.

Return:

The error message text. Returns an empty string if it is not set.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetErrorMessage ()

Resets the errorMessage to its default value.

Since:

BlackBerry 10.1.0

Q_SLOT void setDelay (
intdelay)

Sets the delay in milliseconds.

Parameters
delay	The delay in milliseconds.

Since:

BlackBerry 10.1.0

int delay ()

Returns the delay value.

Return:

The delay in milliseconds.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetDelay ()

Resets the delay to its default value.

Since:

BlackBerry 10.1.0

Q_SLOT void showMessage ()

Shows a toast message with errorMessage text.

Since:

BlackBerry 10.1.0

Q_SLOT void setValidationRequested (
boolrequested)

Sets the validationRequested property.

Parameters
requested	Boolean value.

Since:

BlackBerry 10.1.0

bool validationRequested ()

Returns the validationRequested value.

Return:

The validationRequested value. The default value is false.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetValidationRequested ()

Resets the validationRequested to its default value of false.

Since:

BlackBerry 10.1.0

Q_SLOT void requestValidation ()

Requests a re-validation of the source according to the mode property.

The validate signal is emitted directly from this slot or with a delay, depending on the mode property. If mode is set to ValidationMode::Custom the validate signal is not emitted.

Since:

BlackBerry 10.1.0

Validator (
QObject *parent)

Constructs a Validator instance.

Since:

BlackBerry 10.1.0

virtual~Validator ()

Destructor.

void setObjectName (
const QString &name)

Sets the objectName property.

Parameters
name	The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create ()

Creates and returns a builder for constructing a Validator.

The following sample uses the builder to create a Validator:

Validator* validator = Validator::create();

Return:

A builder used for constructing a Validator.

Since:

BlackBerry 10.1.0

Protected Functions

(Only has inherited protected functions)

BaseObject (
QObject *parent)

Constructs an instance of BaseObject's subclass.

Parameters
parent	An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

Signals

void stateChanged (
bb::cascades::ValidationState::TypenewState)

Emitted when the validation state changes.

Parameters
newState	The new validation state.

Since:

BlackBerry 10.1.0

void modeChanged (
bb::cascades::ValidationMode::TypenewMode)

Emitted when the validation mode changes.

Parameters
newMode	The new validation mode.

Since:

BlackBerry 10.1.0

void validChanged (
boolvalid)

Emitted when the valid property changes.

Parameters
valid	The new valid property value.

Since:

BlackBerry 10.1.0

void errorMessageChanged (
const QStringerrorMessage)

Emitted when the error message text changes.

Parameters
errorMessage	The new error message text.

Since:

BlackBerry 10.1.0

void delayChanged (
intdelay)

Emitted when the delay property changes.

Parameters
delay	The new delay in milliseconds.

Since:

BlackBerry 10.1.0

void validationRequestedChanged (
boolrequested)

Emitted when the validationRequested property changes.

Parameters
requested	The new validationRequested property value.

Since:

BlackBerry 10.1.0

void validate ()

Emitted when validation should be performed by the client.

Since:

BlackBerry 10.1.0

void creationCompleted ()

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class. This signal is emitted to indicate that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (
const QString &objectName)

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

Inheritance

QML properties

QML signals

Public Types Index

Properties Index

Public Functions Index

Static Public Functions Index

Protected Functions Index

Signals Index

Public Types

typedef BaseObject BaseClass

Properties

bb::cascades::ValidationState::Type state

bb::cascades::ValidationMode::Type mode

bool valid

QString errorMessage

int delay

bool validationRequested

QString objectName

QObject parent[read-only]

Public Functions

Q_SLOT void setState (bb::cascades::ValidationState::Typestate)

bb::cascades::ValidationState::Type state ()

Q_INVOKABLE void resetState ()

Q_SLOT void setMode (bb::cascades::ValidationMode::Typemode)

bb::cascades::ValidationMode::Type mode ()

Q_INVOKABLE void resetMode ()

Q_SLOT void setValid (boolvalid)

bool isValid ()

Q_INVOKABLE void resetValid ()

Q_SLOT void setErrorMessage (const QString &errorMessage)

QString errorMessage ()

Q_INVOKABLE void resetErrorMessage ()

Q_SLOT void setDelay (intdelay)

int delay ()

Q_INVOKABLE void resetDelay ()

Q_SLOT void showMessage ()

Q_SLOT void setValidationRequested (boolrequested)

bool validationRequested ()

Q_INVOKABLE void resetValidationRequested ()

Q_SLOT void requestValidation ()

Validator (QObject *parent)

virtual~Validator ()

void setObjectName (const QString &name)

virtual Q_INVOKABLE QString toDebugString ()

Static Public Functions

Builder create ()

Protected Functions

BaseObject (QObject *parent)

Signals

void stateChanged (bb::cascades::ValidationState::TypenewState)

void modeChanged (bb::cascades::ValidationMode::TypenewMode)

void validChanged (boolvalid)

void errorMessageChanged (const QStringerrorMessage)

void delayChanged (intdelay)

void validationRequestedChanged (boolrequested)

void validate ()

void creationCompleted ()

void objectNameChanged (const QString &objectName)

Q_SLOT void setState (
bb::cascades::ValidationState::Typestate)

Q_SLOT void setMode (
bb::cascades::ValidationMode::Typemode)

Q_SLOT void setValid (
boolvalid)

Q_SLOT void setErrorMessage (
const QString &errorMessage)

Q_SLOT void setDelay (
intdelay)

Q_SLOT void setValidationRequested (
boolrequested)

Validator (
QObject *parent)

void setObjectName (
const QString &name)

BaseObject (
QObject *parent)

void stateChanged (
bb::cascades::ValidationState::TypenewState)

void modeChanged (
bb::cascades::ValidationMode::TypenewMode)

void validChanged (
boolvalid)

void errorMessageChanged (
const QStringerrorMessage)

void delayChanged (
intdelay)

void validationRequestedChanged (
boolrequested)

void objectNameChanged (
const QString &objectName)