Validator

Since: BlackBerry 10.1.0

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


Overview

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: QStringInherited
parent: QObject [read-only]Inherited

Public Types Index

Public Functions Index

Validator (QObject *parent=0)
virtual ~Validator ()
intdelay () const
QStringerrorMessage () const
boolisValid () const
bb::cascades::ValidationMode::Typemode () const
Q_SLOT voidrequestValidation ()
Q_INVOKABLE voidresetDelay ()
Q_INVOKABLE voidresetErrorMessage ()
Q_INVOKABLE voidresetMode ()
Q_INVOKABLE voidresetState ()
Q_INVOKABLE voidresetValid ()
Q_INVOKABLE voidresetValidationRequested ()
Q_SLOT voidsetDelay (int delay)
Q_SLOT voidsetErrorMessage (const QString &errorMessage)
Q_SLOT voidsetMode (bb::cascades::ValidationMode::Type mode)
Q_SLOT voidsetState (bb::cascades::ValidationState::Type state)
Q_SLOT voidsetValid (bool valid)
Q_SLOT voidsetValidationRequested (bool requested)
Q_SLOT voidshowMessage ()
bb::cascades::ValidationState::Typestate () const
boolvalidationRequested () const
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Static Public Functions Index

Buildercreate ()

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voiddelayChanged (int delay)
voiderrorMessageChanged (const QString errorMessage)
voidmodeChanged (bb::cascades::ValidationMode::Type newMode)
voidstateChanged (bb::cascades::ValidationState::Type newState)
voidvalidate ()
voidvalidationRequestedChanged (bool requested)
voidvalidChanged (bool valid)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Public Types

typedef BaseObject BaseClass

Properties

int delay

Represents a delay in 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 objectNameInherited

This property is overridden from QObject.

See also:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[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

Validator (

Constructs a Validator instance.

Since:

BlackBerry 10.1.0

virtual~Validator ()

Destructor.

int delay ()

Returns the delay value.

Return:

The delay in milliseconds.

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

bool isValid ()

Returns the valid value.

Return:

The valid value. The default value is false.

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_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

Q_INVOKABLE void resetDelay ()

Resets the delay to its default value.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetErrorMessage ()

Resets the errorMessage to its default value.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetMode ()

Resets the mode to its default value.

Since:

BlackBerry 10.1.0

Q_INVOKABLE void resetState ()

Resets the state to its default value.

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_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 (

Sets the error message text.

Parameters
errorMessage

The error message text.

Since:

BlackBerry 10.1.0

Q_SLOT void setMode (

Sets the validation mode.

Parameters
mode

The validation mode.

Since:

BlackBerry 10.1.0

Q_SLOT void setState (

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:

BlackBerry 10.1.0

Q_SLOT void showMessage ()

Shows a toast message with errorMessage text.

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

bool validationRequested ()

Returns the validationRequested value.

Return:

The validationRequested value. The default value is false.

Since:

BlackBerry 10.1.0

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

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 (Inherited

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 (

Emitted when the error message text changes.

Parameters
errorMessage

The new error message text.

Since:

BlackBerry 10.1.0

void modeChanged (

Emitted when the validation mode changes.

Parameters
newMode

The new validation mode.

Since:

BlackBerry 10.1.0

void stateChanged (

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

Emitted 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 indicates 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 also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus