Contents

• Public Types
• Properties
• Public Functions
• Signals
• Detailed Description
• Network Components

Detailed Description

TheQDeclarativeComponent class encapsulates a QML component definition.

Components are reusable, encapsulated QML elements with well-defined interfaces. They are often defined inComponent Files.

AQDeclarativeComponent instance can be created from a QML file. For example, if there is amain.qml file like this:

import QtQuick 1.0Item {width:200height:200}

The following code loads this QML file as a component, creates an instance of this component usingcreate(), and then queries theItem'swidth value:

QDeclarativeEngine*engine=newQDeclarativeEngine;QDeclarativeComponent component(engine,QUrl::fromLocalFile("main.qml"));QObject*myObject= component.create();QDeclarativeItem*item= qobject_cast<QDeclarativeItem*>(myObject);int width= item->width();// width = 200

Network Components

If the URL passed toQDeclarativeComponent is a network resource, or if the QML document references a network resource, theQDeclarativeComponent has to fetch the network data before it is able to create objects. In this case, theQDeclarativeComponent will have aLoadingstatus. An application will have to wait until the component isReady before callingQDeclarativeComponent::create().

The following example shows how to load a QML file from a network resource. After creating theQDeclarativeComponent, it tests whether the component is loading. If it is, it connects to theQDeclarativeComponent::statusChanged() signal and otherwise calls thecontinueLoading() method directly. Note thatQDeclarativeComponent::isLoading() may be false for a network component if the component has been cached and is ready immediately.

MyApplication::MyApplication(){// ...    component=newQDeclarativeComponent(engine,QUrl("http://www.example.com/main.qml"));if (component->isLoading())QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)),this, SLOT(continueLoading()));else        continueLoading();}void MyApplication::continueLoading(){if (component->isError()) {qWarning()<< component->errors();    }else {QObject*myObject= component->create();    }}

Member Type Documentation

enum QDeclarativeComponent::Status

Specifies the loading status of theQDeclarativeComponent.

Property Documentation

progress : constqreal

The progress of loading the component, from 0.0 (nothing loaded) to 1.0 (finished).

Access functions:

Notifier signal:

status : constStatus

The component's currentstatus.

Access functions:

Notifier signal:

url : constQUrl

The component URL. This is the URL passed to either the constructor, or theloadUrl() orsetData() methods.

Access functions:

Member Function Documentation

QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine * engine,QObject * parent = 0)

Create aQDeclarativeComponent with no data and give it the specifiedengine andparent. Set the data withsetData().

QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine * engine, constQString & fileName,QObject * parent = 0)

Create aQDeclarativeComponent from the givenfileName and give it the specifiedparent andengine.

See alsoloadUrl().

QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine * engine, constQUrl & url,QObject * parent = 0)

Create aQDeclarativeComponent from the givenurl and give it the specifiedparent andengine.

Ensure that the URL provided is full and correct, in particular, useQUrl::fromLocalFile() when loading a file from the local filesystem.

See alsoloadUrl().

[virtual]QDeclarativeComponent::~QDeclarativeComponent()

Destruct theQDeclarativeComponent.

[virtual]QObject * QDeclarativeComponent::beginCreate(QDeclarativeContext * context)

This method provides more advanced control over component instance creation. In general, programmers should useQDeclarativeComponent::create() to create a component.

Create an object instance from this component. Returns 0 if creation failed.context specifies the context within which to create the object instance.

WhenQDeclarativeComponent constructs an instance, it occurs in three steps:

1. The object hierarchy is created, and constant values are assigned.
2. Property bindings are evaluated for the the first time.
3. If applicable,QDeclarativeParserStatus::componentComplete() is called on objects.

QDeclarativeComponent::beginCreate() differs fromQDeclarativeComponent::create() in that it only performs step 1.QDeclarativeComponent::completeCreate() must be called to complete steps 2 and 3.

This breaking point is sometimes useful when using attached properties to communicate information to an instantiated component, as it allows their initial values to be configured before property bindings take effect.

[virtual]void QDeclarativeComponent::completeCreate()

This method provides more advanced control over component instance creation. In general, programmers should useQDeclarativeComponent::create() to create a component.

Complete a component creation begin withQDeclarativeComponent::beginCreate().

[virtual]QObject * QDeclarativeComponent::create(QDeclarativeContext * context = 0)

Create an object instance from this component. Returns 0 if creation failed.context specifies the context within which to create the object instance.

Ifcontext is 0 (the default), it will create the instance in the engine' sroot context.

QDeclarativeContext * QDeclarativeComponent::creationContext() const

Returns theQDeclarativeContext the component was created in. This is only valid for components created directly from QML.

QList<QDeclarativeError> QDeclarativeComponent::errors() const

Return the list of errors that occurred during the last compile or create operation. An empty list is returned ifisError() is not set.

bool QDeclarativeComponent::isError() const

Returns true ifstatus() ==QDeclarativeComponent::Error.

bool QDeclarativeComponent::isLoading() const

Returns true ifstatus() ==QDeclarativeComponent::Loading.

bool QDeclarativeComponent::isNull() const

Returns true ifstatus() ==QDeclarativeComponent::Null.

bool QDeclarativeComponent::isReady() const

Returns true ifstatus() ==QDeclarativeComponent::Ready.

void QDeclarativeComponent::loadUrl(constQUrl & url)

Load theQDeclarativeComponent from the providedurl.

Ensure that the URL provided is full and correct, in particular, useQUrl::fromLocalFile() when loading a file from the local filesystem.

void QDeclarativeComponent::setData(constQByteArray & data, constQUrl & url)

Sets theQDeclarativeComponent to use the given QMLdata. Ifurl is provided, it is used to set the component name and to provide a base path for items resolved by this component.