ComponentDefinition

Provides a way to dynamically define QML Components.

This class is used to define Components - reusable and encapsulated QML elements with well-defined interfaces (see QDeclarativeComponent). ComponentDefinition is useful for dynamic creation of both visual and non visual objects defined either inline (using the default content property) or by loading the content from a QML file specified by URL (the source property).

ComponentDefinition only defines the component - the actual instance has to be created by calling the createObject() function. Alternatively, controls can be loaded dynamically using ControlDelegate.

Here's an example of how to define a component inline:

Container {
    Button {
        text: "Click to create bordered text"
        onClicked: {
             // Creates borderedTextComponent control and appends it
             // to the container
             var createdControl = borderedTextComponent.createObject();
             container.add(createdControl);
             createdControl.textString = "Hello Component";
             createdControl.padding = 30;
             createdControl.textColor = Color.DarkGray;
        }
    } 
    Container {
        id: container
    }
    attachedObjects: [
         ComponentDefinition {
             id: borderedTextComponent

             Container {
                 property variant borderColor: Color.Red
                 property variant fillColor: Color.White
                 property variant textColor: Color.Black
                 property string textString
                 property real padding: 10;

                 background: borderColor

                 leftPadding: padding
                 rightPadding: padding
                 topPadding: padding
                 bottomPadding: padding

                 Container {
                     background: fillColor
                     Label { 
                         text: textString
                         textStyle.color: textColor
                     }
                 }
             }
         }
     ]
} 

And here's how to define a component located in a separate file. This example assumes that the BorderedTextComponent.qml file is located in the same directory as the file that's referencing it.

Container {
    Button {
        text: "Click to create control" 
        onClicked: {
             // Checks whether the component has been correctly loaded and
             // creates borderedTextComponent control and appends it
             // to the container
             if (! borderedTextComponent.hasErrors()) {
                 var createdControl = 
                         borderedTextComponent.createObject(container);
                 container.add(createdControl); 
                 createdControl.textString = "Hello Component";
                 createdControl.padding = 30;
                 createdControl.textColor = Color.DarkGray;
             } else {
                  console.log("Problem loading borderedTextComponent: "
                             +borderedTextComponent.errorString());
             }
        }
    } 
    Container { 
        id: container
    }
    attachedObjects: [
         ComponentDefinition {
             id: borderedTextComponent
             source: "BorderedTextComponent.qml"
         }
     ]
}


Overview

Inheritance

bb::cascades::BaseObject
bb::cascades::QtObject
bb::cascades::ComponentDefinition

QML properties

content: QDeclarativeComponent
source: QUrl
objectName: QStringInherited
parent: QObject [read-only]Inherited

QML signals

Properties Index

QDeclarativeComponentcontent
QUrlsource
QStringobjectNameInherited
QObjectparent [read-only]Inherited

Public Functions Index

Q_INVOKABLE bb::cascades::BaseObject *createObject (QObject *parent=0)
Q_INVOKABLE QStringerrorMessage () const
Q_INVOKABLE boolhasErrors () const
Q_INVOKABLE boolload ()
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidcontentChanged (QDeclarativeComponent *content)
voiderror (const QString &errorMessage)
voidsourceChanged (const QUrl &source)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

QDeclarativeComponent content

A definition of inline component.

Defines the actual content which can be created from this component definition In the case both content and source properties are set, source is used. In the case loading source fails, the content is used instead of failed source.

By default this property is null

QUrl source

A definition of inline component.

Defines the source of the component definition. In the case both content and source properties are set, source is used. In the case loading source fails, the content is used instead of failed source.

Changing source after component instances have been created does not affect the created instances.

Currently supported URLs are relative, file:// or asset://. Loading files from network (http://, ftp://) or other schemas is not supported.

By default this property returns empty
See also:

QUrl

QString objectNameInherited

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

Q_INVOKABLE bb::cascades::BaseObject * createObject (

creates a new object instance from this component definition

Creates a new object instance from this component definition. In the case object cannot be created, this function returns null. In the case parent is specified, the parent takes ownership of the created object.

Only classes deriving from BaseObject can be instantiated using this method.

Parameters
parent

optional parent object, default is null

Return:

created object

Q_INVOKABLE QString errorMessage ()

returns error message in the case something goes wrong with loading and parsing the component defined by the source property or the inlined component

In the case there are no errors, an empty string is returned.
Return:

string with the error message

Q_INVOKABLE bool hasErrors ()

Returns false when this component was successfully loaded and defined.

This method returns false if the document or inlined component associated with this definition was loaded and parsed successfully. It returns true if the document / component hasn't yet been loaded or it failed to load. If it failed the errorString() function can used to get the error messages.

See also:

errorString()

Return:

true if the component has errors, false otherwise.

Q_INVOKABLE bool load ()

explicitly loads the component defined by source property.

This function can be used to explicitly load the content defined by the source property. By default, the content is not loaded until the createObject() function is called.

In the case the component has been successfully loaded, subsequent calls to this function have no effect and always returns true. In the case the loading failed, the function tries to load the component again.
Return:

true if the loading succeeded or false in the case it failed

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

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 contentChanged (
  • QDeclarativeComponent *content)

Emitted when content property is changed.

Parameters
content

The defined content

void error (

Emitted when loading component from specified source fails.

Parameters
errorMessage

The error messages returned by QmlDocument loader

void sourceChanged (

Emitted when source property is changed.

Parameters
source

The QUrl from which the component should be loaded

void creationCompleted ()Inherited

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 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-03-13

comments powered by Disqus