Validator

#include <bb/cascades/Validator>

A default validation class that's used to validate some controls (currently, only TextField is supported).

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.
    }
  }
}

Inheritance

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

QML properties

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

QML signals

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

Public Types Index

BaseObject

BaseClass

Properties Index

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

Public Functions Index

	Validator (QObject *parent=0)
virtual	~Validator ()
int	delay () const
QString	errorMessage () const
bool	isValid () const
bb::cascades::ValidationMode::Type	mode () const
Q_SLOT void	requestValidation ()
Q_INVOKABLE void	resetDelay ()
Q_INVOKABLE void	resetErrorMessage ()
Q_INVOKABLE void	resetMode ()
Q_INVOKABLE void	resetState ()
Q_INVOKABLE void	resetValid ()
Q_INVOKABLE void	resetValidationRequested ()
Q_SLOT void	setDelay (int delay)
Q_SLOT void	setErrorMessage (const QString &errorMessage)
Q_SLOT void	setMode (bb::cascades::ValidationMode::Type mode)
Q_SLOT void	setState (bb::cascades::ValidationState::Type state)
Q_SLOT void	setValid (bool valid)
Q_SLOT void	setValidationRequested (bool requested)
Q_SLOT void	showMessage ()
bb::cascades::ValidationState::Type	state () const
bool	validationRequested () const
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	delayChanged (int delay)
void	errorMessageChanged (const QString errorMessage)
void	modeChanged (bb::cascades::ValidationMode::Type newMode)
void	stateChanged (bb::cascades::ValidationState::Type newState)
void	validate ()
void	validationRequestedChanged (bool requested)
void	validChanged (bool valid)
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)

Public Types

typedef BaseObject BaseClass

Properties

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

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

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

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

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

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.

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 requestValidation ()

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

Q_INVOKABLE void resetValidationRequested ()

Resets the validationRequested to its default value of false.

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

Q_SLOT void setErrorMessage (
const QString &errorMessage)

Sets the error message text.

Parameters
errorMessage	The error message text.

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

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

Sets the validation state.

Parameters
state	The validation state.

Since:

BlackBerry 10.1.0

Q_SLOT void setValid (
boolvalid)

Sets the valid property.

Parameters
valid	Boolean value.

Since:

BlackBerry 10.1.0

Q_SLOT void setValidationRequested (
boolrequested)

Sets the validationRequested property.

Parameters
requested	Boolean value.

Since:

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 delayChanged (
intdelay)

Emitted when the delay property changes.

Parameters
delay	The new delay in milliseconds.

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 modeChanged (
bb::cascades::ValidationMode::TypenewMode)

Emitted when the validation mode changes.

Parameters
newMode	The new validation mode.

Since:

BlackBerry 10.1.0

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

Emitted when the validation state changes.

Parameters
newState	The new validation state.

Since:

BlackBerry 10.1.0

void validate ()

Emitted when validation should be performed by the client.

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 validChanged (
boolvalid)

Emitted when the valid property changes.

Parameters
valid	The new valid property value.

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.

void objectNameChanged (
const QString &objectName)

This signal is emitted when the objectName property is changed.

Overview

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

int delay

QString errorMessage

bb::cascades::ValidationMode::Type mode

bb::cascades::ValidationState::Type state

bool valid

bool validationRequested

QString objectName

QObject parent[read-only]

Public Functions

Validator (QObject *parent)

virtual~Validator ()

int delay ()

QString errorMessage ()

bool isValid ()

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

Q_SLOT void requestValidation ()

Q_INVOKABLE void resetDelay ()

Q_INVOKABLE void resetErrorMessage ()

Q_INVOKABLE void resetMode ()

Q_INVOKABLE void resetState ()

Q_INVOKABLE void resetValid ()

Q_INVOKABLE void resetValidationRequested ()

Q_SLOT void setDelay (intdelay)

Q_SLOT void setErrorMessage (const QString &errorMessage)

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

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

Q_SLOT void setValid (boolvalid)

Q_SLOT void setValidationRequested (boolrequested)

Q_SLOT void showMessage ()

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

bool validationRequested ()

void setObjectName (const QString &name)

virtual Q_INVOKABLE QString toDebugString ()

Static Public Functions

Builder create ()

Protected Functions

BaseObject (QObject *parent)

Signals

void delayChanged (intdelay)

void errorMessageChanged (const QStringerrorMessage)

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

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

void validate ()

void validationRequestedChanged (boolrequested)

void validChanged (boolvalid)

void creationCompleted ()

void objectNameChanged (const QString &objectName)

1. Choose your focus

2. Download the tools

3. Try the sample apps

4. Educate yourself

5. Start developing

Validator (
QObject *parent)

Q_SLOT void setDelay (
intdelay)

Q_SLOT void setErrorMessage (
const QString &errorMessage)

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

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

Q_SLOT void setValid (
boolvalid)

Q_SLOT void setValidationRequested (
boolrequested)

void setObjectName (
const QString &name)

BaseObject (
QObject *parent)

void delayChanged (
intdelay)

void errorMessageChanged (
const QStringerrorMessage)

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

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

void validationRequestedChanged (
boolrequested)

void validChanged (
boolvalid)

void objectNameChanged (
const QString &objectName)