diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/declarative/graphicsitems/qdeclarativeitem.cpp | 2 | ||||
| -rw-r--r-- | src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp | 99 | ||||
| -rw-r--r-- | src/declarative/qml/qdeclarativecomponent.cpp | 12 | ||||
| -rw-r--r-- | src/declarative/qml/qdeclarativecontext.cpp | 2 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativeanimation.cpp | 21 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativeconnections.cpp | 29 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativelistmodel.cpp | 126 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativepackage.cpp | 8 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativestate.cpp | 5 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativestateoperations.cpp | 10 | ||||
| -rw-r--r-- | src/declarative/util/qdeclarativexmllistmodel.cpp | 10 |
11 files changed, 106 insertions, 218 deletions
diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp index bef09bb..7ab280e 100644 --- a/src/declarative/graphicsitems/qdeclarativeitem.cpp +++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp @@ -726,7 +726,7 @@ void QDeclarativeKeyNavigationAttached::keyReleased(QKeyEvent *event, bool post) The signal properties have a \l KeyEvent parameter, named \e event which contains details of the event. If a key is handled \e event.accepted should be set to true to prevent the - event from propagating up the item heirarchy. + event from propagating up the item hierarchy. \code Item { diff --git a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp index 2a88a80..e133adb 100644 --- a/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp +++ b/src/declarative/graphicsitems/qdeclarativevisualitemmodel.cpp @@ -113,16 +113,18 @@ public: \since 4.7 \brief The VisualItemModel allows items to be provided to a view. - The children of the VisualItemModel are provided in a model which - can be used in a view. Note that no delegate should be - provided to a view since the VisualItemModel contains the - visual delegate (items). + A VisualItemModel contains the visual items to be used in a view. + When a VisualItemModel is used in a view, the view does not require + a delegate since the VisualItemModel already contains the visual + delegate (items). An item can determine its index within the model via the \c VisualItemModel.index attached property. The example below places three colored rectangles in a ListView. \code + import Qt 4.7 + Rectangle { VisualItemModel { id: itemModel @@ -607,30 +609,15 @@ QDeclarativeVisualDataModelData *QDeclarativeVisualDataModelPrivate::data(QObjec A VisualDataModel encapsulates a model and the delegate that will be instantiated for items in the model. - It is usually not necessary to create a VisualDataModel directly, - since the QML views will create one internally. + It is usually not necessary to create VisualDataModel elements. + However, it can be useful for manipulating and accessing the \l modelIndex + when a QAbstractItemModel subclass is used as the + model. Also, VisualDataModel is used together with \l Package to + provide delegates to multiple views. The example below illustrates using a VisualDataModel with a ListView. - \code - VisualDataModel { - id: visualModel - model: myModel - delegate: Component { - Rectangle { - height: 25 - width: 100 - Text { text: "Name:" + name} - } - } - } - ListView { - width: 100 - height: 100 - anchors.fill: parent - model: visualModel - } - \endcode + \snippet doc/src/snippets/declarative/visualdatamodel.qml 0 */ QDeclarativeVisualDataModel::QDeclarativeVisualDataModel() @@ -805,56 +792,22 @@ void QDeclarativeVisualDataModel::setDelegate(QDeclarativeComponent *delegate) /*! \qmlproperty QModelIndex VisualDataModel::rootIndex - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. \c rootIndex allows the children of any node in a QAbstractItemModel to be provided by this model. This property only affects models of type QAbstractItemModel. - \code - // main.cpp - - int main(int argc, char ** argv) - { - QApplication app(argc, argv); - - QDeclarativeView view; - - QDirModel model; - view.rootContext()->setContextProperty("myModel", &model); + For example, here is a simple interactive file system browser. + When a directory name is clicked, the view's \c rootIndex is set to the + QModelIndex node of the clicked directory, thus updating the view to show + the new directory's contents. - view.setSource(QUrl("qrc:view.qml")); - view.show(); - - return app.exec(); - } - - #include "main.moc" - \endcode - - \code - // view.qml - import Qt 4.7 - - ListView { - id: view - width: 200 - height: 200 - model: VisualDataModel { - model: myModel - delegate: Component { - Rectangle { - height: 25; width: 200 - Text { text: filePath } - MouseArea { - anchors.fill: parent; - onClicked: if (hasModelChildren) view.model.rootIndex = view.model.modelIndex(index) - } - } - } - } - } - \endcode + \c main.cpp: + \snippet doc/src/snippets/declarative/visualdatamodel_rootindex/main.cpp 0 + + \c view.qml: + \snippet doc/src/snippets/declarative/visualdatamodel_rootindex/view.qml 0 \sa modelIndex(), parentModelIndex() */ @@ -886,7 +839,7 @@ void QDeclarativeVisualDataModel::setRootIndex(const QVariant &root) /*! \qmlmethod QModelIndex VisualDataModel::modelIndex(int index) - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML. @@ -906,7 +859,7 @@ QVariant QDeclarativeVisualDataModel::modelIndex(int idx) const /*! \qmlmethod QModelIndex VisualDataModel::parentModelIndex() - QAbstractItemModel provides a heirachical tree of data, whereas + QAbstractItemModel provides a hierarchical tree of data, whereas QML only operates on list data. This function assists in using tree models in QML. @@ -1000,10 +953,10 @@ QDeclarativeVisualDataModel::ReleaseFlags QDeclarativeVisualDataModel::release(Q The \a parts property selects a VisualDataModel which creates delegates from the part named. This is used in conjunction with - the Package element. + the \l Package element. For example, the code below selects a model which creates - delegates named \e list from a Package: + delegates named \e list from a \l Package: \code VisualDataModel { diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 7b51239..55ee783 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -547,16 +547,18 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q /*! \qmlmethod object Component::createObject(parent) - Returns an object instance from this component, or null if object creation fails. + + Creates and returns an object instance of this component that will have the given + \a parent. Returns null if object creation fails. The object will be created in the same context as the one in which the component was created. This function will always return null when called on components which were not created in QML. - Note that if the returned object is to be displayed, its \c parent must be set to - an existing item in a scene, or else the object will not be visible. The parent - argument is required to help you avoid this, you must explicitly pass in null if - you wish to create an object without setting a parent. + If you wish to create an object without setting a parent, specify \c null for + the \a parent value. Note that if the returned object is to be displayed, you + must provide a valid \a parent value or set the returned object's \l{Item::parent}{parent} + property, or else the object will not be visible. */ /*! diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index 6a13f15..2221d78 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -116,7 +116,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over the context object's properties. - Contexts form a hierarchy. The root of this heirarchy is the QDeclarativeEngine's + Contexts form a hierarchy. The root of this hierarchy is the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context}. A component instance can access the data in its own context, as well as all its ancestor contexts. Data can be made available to all instances by modifying the diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index 1447532..25cf133 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -1774,7 +1774,7 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t) To specify an easing curve you need to specify at least the type. For some curves you can also specify amplitude, period and/or overshoot (more details provided after the table). The default easing curve is - Linear. + \c Easing.Linear. \qml PropertyAnimation { properties: "y"; easing.type: Easing.InOutElastic; easing.amplitude: 2.0; easing.period: 1.5 } @@ -1951,15 +1951,15 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t) \o \inlineimage qeasingcurve-outinbounce.png \endtable - easing.amplitude is only applicable for bounce and elastic curves (curves of type - Easing.InBounce, Easing.OutBounce, Easing.InOutBounce, Easing.OutInBounce, Easing.InElastic, - Easing.OutElastic, Easing.InOutElastic or Easing.OutInElastic). + \c easing.amplitude is only applicable for bounce and elastic curves (curves of type + \c Easing.InBounce, \c Easing.OutBounce, \c Easing.InOutBounce, \c Easing.OutInBounce, \c Easing.InElastic, + \c Easing.OutElastic, \c Easing.InOutElastic or \c Easing.OutInElastic). - easing.overshoot is only applicable if type is: Easing.InBack, Easing.OutBack, - Easing.InOutBack or Easing.OutInBack. + \c easing.overshoot is only applicable if \c easing.type is: \c Easing.InBack, \c Easing.OutBack, + \c Easing.InOutBack or \c Easing.OutInBack. - easing.period is only applicable if type is: Easing.InElastic, Easing.OutElastic, - Easing.InOutElastic or Easing.OutInElastic. + \c easing.period is only applicable if easing.type is: \c Easing.InElastic, \c Easing.OutElastic, + \c Easing.InOutElastic or \c Easing.OutInElastic. See the \l {declarative/animation/easing}{easing} example for a demonstration of the different easing settings. @@ -2045,8 +2045,9 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop) The singular forms are slightly optimized, so if you do have only a single target/property to animate you should try to use them. - In many cases these properties do not need to be explicitly specified -- they can be - inferred from the animation framework. + In many cases these properties do not need to be explicitly specified, as they can be + inferred from the animation framework: + \table 80% \row \o Value Source / Behavior diff --git a/src/declarative/util/qdeclarativeconnections.cpp b/src/declarative/util/qdeclarativeconnections.cpp index 808d196..b364821 100644 --- a/src/declarative/util/qdeclarativeconnections.cpp +++ b/src/declarative/util/qdeclarativeconnections.cpp @@ -72,7 +72,9 @@ public: /*! \qmlclass Connections QDeclarativeConnections \since 4.7 - \brief A Connections object describes generalized connections to signals. + \brief A Connections element describes generalized connections to signals. + + A Connections object creates a connection to a QML signal. When connecting to signals in QML, the usual way is to create an "on<Signal>" handler that reacts when a signal is received, like this: @@ -83,16 +85,16 @@ public: } \endqml - However, in some cases, it is not possible to connect to a signal in this - way, such as: + However, it is not possible to connect to a signal in this way in some + cases, such as when: \list - \i multiple connections to the same signal - \i connections outside the scope of the signal sender - \i connections to targets not defined in QML + \i Multiple connections to the same signal are required + \i Creating connections outside the scope of the signal sender + \i Connecting to targets not defined in QML \endlist - When any of these are needed, the Connections object can be used instead. + When any of these are needed, the Connections element can be used instead. For example, the above code can be changed to use a Connections object, like this: @@ -105,7 +107,7 @@ public: } \endqml - More generally, the Connections object can be a child of some other object than + More generally, the Connections object can be a child of some object other than the sender of the signal: \qml @@ -141,7 +143,7 @@ QDeclarativeConnections::~QDeclarativeConnections() \qmlproperty Object Connections::target This property holds the object that sends the signal. - If not set at all, the target defaults to be the parent of the Connections. + If this property is not set, the \c target defaults to the parent of the Connection. If set to null, no connection is made and any signal handlers are ignored until the target is not null. @@ -175,12 +177,11 @@ void QDeclarativeConnections::setTarget(QObject *obj) /*! \qmlproperty bool Connections::ignoreUnknownSignals - Normally, you will get a runtime error if you try to connect - to signals on an object which the object does not have. + Normally, a connection to a non-existent signal produces runtime errors. - By setting this flag to true, such errors are ignored. This is - useful if you intend to connect to different types of object, handling - a different set of signals for each. + If this property is set to \c true, such errors are ignored. + This is useful if you intend to connect to different types of objects, handling + a different set of signals for each object. */ bool QDeclarativeConnections::ignoreUnknownSignals() const { diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp index 7518eb7..78a3207 100644 --- a/src/declarative/util/qdeclarativelistmodel.cpp +++ b/src/declarative/util/qdeclarativelistmodel.cpp @@ -76,125 +76,41 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM For example: - \code - ListModel { - id: fruitModel - ListElement { - name: "Apple" - cost: 2.45 - } - ListElement { - name: "Orange" - cost: 3.25 - } - ListElement { - name: "Banana" - cost: 1.95 - } - } - \endcode + \snippet doc/src/snippets/declarative/listmodel.qml 0 - Roles (properties) must begin with a lower-case letter.The above example defines a + Roles (properties) must begin with a lower-case letter. The above example defines a ListModel containing three elements, with the roles "name" and "cost". Values must be simple constants - either strings (quoted), bools (true, false), numbers, or enum values (like Text.AlignHCenter). The defined model can be used in views such as ListView: - \code - Component { - id: fruitDelegate - Item { - width: 200; height: 50 - Text { text: name } - Text { text: '$'+cost; anchors.right: parent.right } - } - } - ListView { - model: fruitModel - delegate: fruitDelegate - anchors.fill: parent - } - \endcode + \snippet doc/src/snippets/declarative/listmodel-simple.qml 0 + \dots 8 + \snippet doc/src/snippets/declarative/listmodel-simple.qml 1 + \image listmodel.png It is possible for roles to contain list data. In the example below we create a list of fruit attributes: - \code - ListModel { - id: fruitModel - ListElement { - name: "Apple" - cost: 2.45 - attributes: [ - ListElement { description: "Core" }, - ListElement { description: "Deciduous" } - ] - } - ListElement { - name: "Orange" - cost: 3.25 - attributes: [ - ListElement { description: "Citrus" } - ] - } - ListElement { - name: "Banana" - cost: 1.95 - attributes: [ - ListElement { description: "Tropical" }, - ListElement { description: "Seedless" } - ] - } - } - \endcode + \snippet doc/src/snippets/declarative/listmodel-nested.qml model + + The delegate below displays all the fruit attributes: + + \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate + \image listmodel-nested.png - The delegate below will list all the fruit attributes: - \code - Component { - id: fruitDelegate - Item { - width: 200; height: 50 - Text { id: name; text: name } - Text { text: '$'+cost; anchors.right: parent.right } - Row { - anchors.top: name.bottom - spacing: 5 - Text { text: "Attributes:" } - Repeater { - model: attributes - Component { Text { text: description } } - } - } - } - } - \endcode \section2 Modifying list models The content of a ListModel may be created and modified using the clear(), - append(), and set() methods. For example: - - \code - Component { - id: fruitDelegate - Item { - width: 200; height: 50 - Text { text: name } - Text { text: '$'+cost; anchors.right: parent.right } - - // Double the price when clicked. - MouseArea { - anchors.fill: parent - onClicked: fruitModel.set(index, "cost", cost*2) - } - } - } - \endcode + append(), set() and setProperty() methods. For example: + + \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate When creating content dynamically, note that the set of available properties cannot be changed - except by first clearing the model - whatever properties are first added are then the - only permitted properties in the model. + except by first clearing the model. Whatever properties are first added to the model are then the + only permitted properties in the model until it is cleared. \section2 Using threaded list models with WorkerScript @@ -214,11 +130,11 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM \snippet examples/declarative/threading/threadedlistmodel/dataloader.js 0 The application's \tt Timer object periodically sends a message to the - worker script by calling \tt WorkerScript::sendMessage(). When this message - is received, \tt WorkerScript.onMessage() is invoked in + worker script by calling \l WorkerScript::sendMessage(). When this message + is received, \l {WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in \tt dataloader.js, which appends the current time to the list model. - Note the call to sync() from the \c WorkerScript.onMessage() handler. + Note the call to sync() from the \l {WorkerScript::onMessage}{WorkerScript.onMessage()} handler. You must call sync() or else the changes made to the list from the external thread will not be reflected in the list model in the main thread. @@ -454,7 +370,7 @@ void QDeclarativeListModel::insert(int index, const QScriptValue& valuemap) to the end of the list: \code - fruitModel.move(0,fruitModel.count-3,3) + fruitModel.move(0, fruitModel.count - 3, 3) \endcode \sa append() diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp index 9617b86..9245fc2 100644 --- a/src/declarative/util/qdeclarativepackage.cpp +++ b/src/declarative/util/qdeclarativepackage.cpp @@ -48,9 +48,9 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Package QDeclarativePackage - \brief Package provides a collection of named items + \brief Package provides a collection of named items. - The Package class is currently used in conjunction with + The Package class is used in conjunction with VisualDataModel to enable delegates with a shared context to be provided to multiple views. @@ -58,7 +58,7 @@ QT_BEGIN_NAMESPACE \e {Package.name} attached property. The example below creates a Package containing two named items; - \e list and \e grid. The third element in the package is parented to whichever + \e list and \e grid. The third element in the package (the \l Rectangle) is parented to whichever delegate it should appear in. This allows an item to move between views. @@ -70,7 +70,7 @@ QT_BEGIN_NAMESPACE \snippet examples/declarative/modelviews/package/view.qml 0 - \sa QtDeclarative + \sa {declarative/modelviews/package}{Package example}, QtDeclarative */ diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp index 37f9f6a..ae19a9c 100644 --- a/src/declarative/util/qdeclarativestate.cpp +++ b/src/declarative/util/qdeclarativestate.cpp @@ -144,8 +144,9 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje can, for example, be used to apply different sets of property values or execute different scripts. - Here is an example. In the default state, \c myRect is colored black. In the "clicked" - state, the color is red. Clicking within the MouseArea toggles the rectangle's state + The following example displays a single Rectangle. In the default state, the rectangle + is colored black. In the "clicked" state, a PropertyChanges element changes the + rectangle's color to red. Clicking within the MouseArea toggles the rectangle's state between the default state and the "clicked" state, thus toggling the color of the rectangle between black and red. diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp index 2d55931..51e6f99 100644 --- a/src/declarative/util/qdeclarativestateoperations.cpp +++ b/src/declarative/util/qdeclarativestateoperations.cpp @@ -172,6 +172,14 @@ void QDeclarativeParentChangePrivate::doChange(QDeclarativeItem *targetParent, Q items involved in the reparenting (i.e. items in the common ancestor tree for the original and new parent). + The example below displays a large red rectangle and a small blue rectangle, side by side. + When the \c blueRect is clicked, it changes to the "reparented" state: its parent is changed to \c redRect and it is + positioned at (10, 10) within the red rectangle, as specified in the ParentChange. + + \snippet doc/src/snippets/declarative/parentchange.qml 0 + + \image parentchange.png + You can specify at which point in a transition you want a ParentChange to occur by using a ParentAnimation. */ @@ -698,6 +706,8 @@ QString QDeclarativeStateChangeScript::typeName() const \snippet doc/src/snippets/declarative/anchorchanges.qml 0 + \image anchorchanges.png + AnchorChanges can be animated using AnchorAnimation. \qml //animate our anchor changes diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp index 4f9355b..4adef25 100644 --- a/src/declarative/util/qdeclarativexmllistmodel.cpp +++ b/src/declarative/util/qdeclarativexmllistmodel.cpp @@ -523,10 +523,13 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla A XmlListModel could create a model from this data, like this: \qml + import Qt 4.7 + XmlListModel { id: xmlModel source: "http://www.mysite.com/feed.xml" query: "/rss/channel/item" + XmlRole { name: "title"; query: "title/string()" } XmlRole { name: "pubDate"; query: "pubDate/string()" } } @@ -536,7 +539,7 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla a model item for each \c <item> in the XML document. The XmlRole objects define the - model item attributes; here, each model item will have \c title and \c pubDate + model item attributes. Here, each model item will have \c title and \c pubDate attributes that match the \c title and \c pubDate values of its corresponding \c <item>. (See \l XmlRole::query for more examples of valid XPath expressions for XmlRole.) @@ -672,11 +675,11 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src) /*! \qmlproperty string XmlListModel::xml - This property holds XML text set directly. + This property holds the XML data for this model, if set. The text is assumed to be UTF-8 encoded. - If both source and xml are set, xml will be used. + If both \l source and \c xml are set, \c xml will be used. */ QString QDeclarativeXmlListModel::xml() const { @@ -733,6 +736,7 @@ void QDeclarativeXmlListModel::setQuery(const QString &query) source: "http://mysite.com/feed.xml" query: "/feed/entry" namespaceDeclarations: "declare default element namespace 'http://www.w3.org/2005/Atom';" + XmlRole { name: "title"; query: "title/string()" } } \endqml |