From 39013a4a8238d522ed1d13adb25e702da9e25fc9 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Mon, 28 Feb 2011 12:31:50 +1000 Subject: fix/improve docs for new QtQuick 1.1 attributes Ensure attributes added in QtQuick 1.1 are marked with the '\since QtQuick 1.1' tag. Also add links to items listed in the QtQuick 1.1 section in whatsnew.qdoc. Task-number: QTBUG-17771 Change-Id: Ic8fb3c8d3c99a1469c1767779efaafd27ef460e1 --- doc/src/declarative/dynamicobjects.qdoc | 8 +-- doc/src/declarative/whatsnew.qdoc | 61 ++++++++++++---------- doc/src/snippets/declarative/componentCreation.js | 7 +-- .../graphicsitems/qdeclarativeborderimage.cpp | 9 ++++ .../graphicsitems/qdeclarativeflickable.cpp | 6 +-- .../graphicsitems/qdeclarativegridview.cpp | 1 + .../graphicsitems/qdeclarativelistview.cpp | 1 + .../graphicsitems/qdeclarativepositioners.cpp | 6 +++ src/declarative/graphicsitems/qdeclarativetext.cpp | 4 ++ .../graphicsitems/qdeclarativetextedit.cpp | 6 +-- .../graphicsitems/qdeclarativetextinput.cpp | 8 +++ src/declarative/qml/qdeclarativecomponent.cpp | 26 ++++++--- 12 files changed, 91 insertions(+), 52 deletions(-) diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 316fe6b..f2ca0fd 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -68,9 +68,11 @@ the component. This function can take one or two arguments: \o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to this function. -\o The second is optional and is a script which assigns values to the item's properties during creation. This avoids warnings - when certain properties have been bound to before they have been set by the code. Additionally, there are small performance - benefits when instantiating objects in this way. +\o The second is optional and is a map of property-value items that define initial any property values for the item. + Property values specified by this argument are applied to the object before its creation is finalized, avoiding + binding errors that may occur if particular properties must be initialized to enable other property bindings. + when certain properties have been bound to before they have been set by the code. Additionally, there are small + performance benefits when compared to defining property values and bindings after the object is created. \endlist Here is an example. First there is \c Sprite.qml, which defines a simple QML component: diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc index f4359f9..e8c2124 100644 --- a/doc/src/declarative/whatsnew.qdoc +++ b/doc/src/declarative/whatsnew.qdoc @@ -41,10 +41,10 @@ PinchArea provides support for the common two finger pinch gesture. Added the following properties: \list -\o lineSpacing -\o lineCount -\o maximumLineCount -\o truncated +\o \l {Text::}{lineHeight} +\o \l {Text::}{lineCount} +\o \l {Text::}{maximumLineCount} +\o \l {Text::}{truncated} \endlist horizontalAlignment now accepts Text.AlignJustify alignment mode. @@ -53,85 +53,88 @@ horizontalAlignment now accepts Text.AlignJustify alignment mode. Added the following properties, methods and signal handlers: \list -\o canPaste -\o lineCount -\o deselect() -\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word -\o onLinkActivated(string link) +\o \l {TextEdit::}{canPaste} +\o \l {TextEdit::}{lineCount} +\o \l {TextEdit::}{deselect()} +\o \l {TextEdit::}{moveCursorSelection()} to enable selection by word +\o \l {TextEdit::}{onLinkActivated} \endlist \section2 TextInput Added the following properties and methods: \list -\o canPaste -\o deselect() -\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word +\o \l{TextInput::}{canPaste} +\o \l{TextInput::}{deselect()} +\o \l{TextInput::}{moveCursorSelection()} to enable selection by word \endlist \section2 Image, BorderImage and AnimatedImage Added the following properties: \list -\o cache -\o mirror +\o \l{Image::}{cache} +\o \l{Image::}{mirror} \endlist \section2 Item Added the following properties: \list -\o implicitWidth and implicitHeight +\o \l{Item::}{implicitWidth} and \l{Item::}{implicitHeight} \endlist \section2 Flickable Added the following methods: \list -\o resizeContent(qreal w, qreal h, QPointF center) -\o returnToBounds() +\o \l{Flickable::}{resizeContent()} +\o \l{Flickable::}{returnToBounds()} \endlist \section2 ListView and GridView Added the following methods: \list -\o positionViewAtBeginning() -\o positionViewAtEnd() +\o \l{ListView::}{positionViewAtBeginning()} +\o \l{ListView::}{positionViewAtEnd()} \endlist -\section2 Flow, Grid, Row +\section2 Flow, Grid and Row Added the following properties: \list -\o layoutDirection +\o \l{Flow::}{layoutDirection} \endlist \section2 Repeater Added the following methods and signal handlers: \list -\o onItemAdded() -\o onItemRemoved() -\o itemAt(int index) +\o \l{Repeater::}{onItemAdded} +\o \l{Repeater::}{onItemRemoved} +\o \l{Repeater::}{itemAt()} \endlist \section2 Component -The createObject() method now accepts a map of initial property values for the created object. +\list +\o The \l{Component::}{createObject()} method now accepts a map of initial property values for +the created object. +\endlist \section2 Qt -Added the following properties and methods: \list -\o application.layoutDirection -\o application.active +\o Added the \l {QML:Qt::application}{Qt.application} object to hold generic global application +properties. \endlist \section2 Other changes \list -\o Functions can be assigned to properties from JavaScript to create property bindings +\o Functions can be \l{Binding Properties from JavaScript}{assigned to properties from JavaScript} +to create property bindings. \endlist diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js index cf59777..7364139 100644 --- a/doc/src/snippets/declarative/componentCreation.js +++ b/doc/src/snippets/declarative/componentCreation.js @@ -32,13 +32,10 @@ function createSpriteObjects() { //![finishCreation] function finishCreation() { if (component.status == Component.Ready) { - sprite = component.createObject(appWindow); + sprite = component.createObject(appWindow, {"x": 100, "y": 100}); if (sprite == null) { // Error Handling - } else { - sprite.x = 100; - sprite.y = 100; - // ... + console.log("Error creating object"); } } else if (component.status == Component.Error) { // Error Handling diff --git a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp index 91896f2..8f37e90 100644 --- a/src/declarative/graphicsitems/qdeclarativeborderimage.cpp +++ b/src/declarative/graphicsitems/qdeclarativeborderimage.cpp @@ -214,6 +214,15 @@ QDeclarativeBorderImage::~QDeclarativeBorderImage() */ /*! + \qmlproperty bool BorderImage::cache + \since Quick 1.1 + + Specifies whether the image should be cached. The default value is + true. Setting \a cache to false is useful when dealing with large images, + to make sure that they aren't cached at the expense of small 'ui element' images. +*/ + +/*! \qmlproperty bool BorderImage::mirror \since Quick 1.1 diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp index 91230c0..364d76f 100644 --- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp @@ -1297,11 +1297,10 @@ void QDeclarativeFlickable::setContentHeight(qreal h) /*! \qmlmethod Flickable::resizeContent(real width, real height, QPointF center) \preliminary + \since Quick 1.1 Resizes the content to \a width x \a height about \a center. - \bold {This method was added in QtQuick 1.1.} - This does not scale the contents of the Flickable - it only resizes the \l contentWidth and \l contentHeight. @@ -1333,11 +1332,10 @@ void QDeclarativeFlickable::resizeContent(qreal w, qreal h, QPointF center) /*! \qmlmethod Flickable::returnToBounds() \preliminary + \since Quick 1.1 Ensures the content is within legal bounds. - \bold {This method was added in QtQuick 1.1.} - This may be called to ensure that the content is within legal bounds after manually positioning the content. */ diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp index 6d2285d..00e5b3f 100644 --- a/src/declarative/graphicsitems/qdeclarativegridview.cpp +++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp @@ -2250,6 +2250,7 @@ void QDeclarativeGridView::positionViewAtIndex(int index, int mode) /*! \qmlmethod GridView::positionViewAtBeginning() \qmlmethod GridView::positionViewAtEnd() + \since Quick 1.1 Positions the view at the beginning or end, taking into account any header or footer. diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp index 431e311..e8bc1bf 100644 --- a/src/declarative/graphicsitems/qdeclarativelistview.cpp +++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp @@ -2709,6 +2709,7 @@ void QDeclarativeListView::positionViewAtIndex(int index, int mode) /*! \qmlmethod ListView::positionViewAtBeginning() \qmlmethod ListView::positionViewAtEnd() + \since Quick 1.1 Positions the view at the beginning or end, taking into account any header or footer. diff --git a/src/declarative/graphicsitems/qdeclarativepositioners.cpp b/src/declarative/graphicsitems/qdeclarativepositioners.cpp index 27a1301..c0be2a2 100644 --- a/src/declarative/graphicsitems/qdeclarativepositioners.cpp +++ b/src/declarative/graphicsitems/qdeclarativepositioners.cpp @@ -584,6 +584,8 @@ QDeclarativeRow::QDeclarativeRow(QDeclarativeItem *parent) /*! \qmlproperty enumeration Row::layoutDirection + \since Quick 1.1 + This property holds the layoutDirection of the row. Possible values: @@ -859,6 +861,8 @@ void QDeclarativeGrid::setFlow(Flow flow) /*! \qmlproperty enumeration Grid::layoutDirection + \since Quick 1.1 + This property holds the layout direction of the layout. Possible values are: @@ -1201,6 +1205,8 @@ void QDeclarativeFlow::setFlow(Flow flow) /*! \qmlproperty enumeration Flow::layoutDirection + \since Quick 1.1 + This property holds the layout direction of the layout. Possible values are: diff --git a/src/declarative/graphicsitems/qdeclarativetext.cpp b/src/declarative/graphicsitems/qdeclarativetext.cpp index 049169e..044425d 100644 --- a/src/declarative/graphicsitems/qdeclarativetext.cpp +++ b/src/declarative/graphicsitems/qdeclarativetext.cpp @@ -1168,6 +1168,7 @@ void QDeclarativeText::setWrapMode(WrapMode mode) /*! \qmlproperty int Text::lineCount + \since Quick 1.1 Returns the number of lines visible in the text item. @@ -1183,6 +1184,7 @@ int QDeclarativeText::lineCount() const /*! \qmlproperty bool Text::truncated + \since Quick 1.1 Returns true if the text has been truncated due to \l maximumLineCount or \l elide. @@ -1199,6 +1201,7 @@ bool QDeclarativeText::truncated() const /*! \qmlproperty int Text::maximumLineCount + \since Quick 1.1 Set this property to limit the number of lines that the text item will show. If elide is set to Text.ElideRight, the text will be elided appropriately. @@ -1451,6 +1454,7 @@ qreal QDeclarativeText::paintedHeight() const /*! \qmlproperty real Text::lineHeight + \since Quick 1.1 Sets the line height for the text. The value can be in pixels or a multiplier depending on lineHeightMode. diff --git a/src/declarative/graphicsitems/qdeclarativetextedit.cpp b/src/declarative/graphicsitems/qdeclarativetextedit.cpp index 7f383a6..59921d5 100644 --- a/src/declarative/graphicsitems/qdeclarativetextedit.cpp +++ b/src/declarative/graphicsitems/qdeclarativetextedit.cpp @@ -544,6 +544,7 @@ void QDeclarativeTextEdit::setWrapMode(WrapMode mode) /*! \qmlproperty int TextEdit::lineCount + \since Quick 1.1 Returns the total number of lines in the textEdit item. */ @@ -1134,6 +1135,7 @@ void QDeclarativeTextEditPrivate::focusChanged(bool hasFocus) /*! \qmlmethod void TextEdit::deselect() + \since Quick 1.1 Removes active text selection. */ @@ -1381,13 +1383,11 @@ void QDeclarativeTextEdit::updateImgCache(const QRectF &rf) /*! \qmlproperty bool TextEdit::canPaste + \since QtQuick 1.1 Returns true if the TextEdit is writable and the content of the clipboard is suitable for pasting into the TextEdit. - - \since QtQuick 1.1 */ - bool QDeclarativeTextEdit::canPaste() const { Q_D(const QDeclarativeTextEdit); diff --git a/src/declarative/graphicsitems/qdeclarativetextinput.cpp b/src/declarative/graphicsitems/qdeclarativetextinput.cpp index f3c6b93..65ed5c6 100644 --- a/src/declarative/graphicsitems/qdeclarativetextinput.cpp +++ b/src/declarative/graphicsitems/qdeclarativetextinput.cpp @@ -1299,6 +1299,7 @@ QVariant QDeclarativeTextInput::inputMethodQuery(Qt::InputMethodQuery property) /*! \qmlmethod void TextInput::deselect() + \since Quick 1.1 Removes active text selection. */ @@ -1480,6 +1481,13 @@ void QDeclarativeTextInput::setMouseSelectionMode(SelectionMode mode) } } +/*! + \qmlproperty bool TextInput::canPaste + \since QtQuick 1.1 + + Returns true if the TextInput is writable and the content of the clipboard is + suitable for pasting into the TextEdit. +*/ bool QDeclarativeTextInput::canPaste() const { Q_D(const QDeclarativeTextInput); diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index cf40182..fc393d1 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -615,10 +615,11 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q } /*! - \qmlmethod object Component::createObject(Item parent, Script valuemap = null) + \qmlmethod object Component::createObject(Item parent, object properties) - Creates and returns an object instance of this component that will have the given - \a parent. Returns null if object creation fails. + Creates and returns an object instance of this component that will have + the given \a parent and \a properties. The \a properties argument is optional. + 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 @@ -630,14 +631,23 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q property, or else the object will not be visible. If a \a parent is not provided to createObject(), a reference to the returned object must be held so that - it is not destroyed by the garbage collector. This is regardless of Item.parent being set afterwards, + it is not destroyed by the garbage collector. This is true regardless of whether \l{Item::parent} is set afterwards, since setting the Item parent does not change object ownership; only the graphical parent is changed. - Since QtQuick 1.1, a map of property values can be optionally passed to the method that applies values to the object's properties - before its creation is finalised. This will avoid binding issues that can occur when the object is - instantiated before property bindings have been set. For example: + As of QtQuick 1.1, this method accepts an optional \a properties argument that specifies a + map of initial property values for the created object. These values are applied before object + creation is finalized. (This is more efficient than setting property values after object creation, + particularly where large sets of property values are defined, and also allows property bindings + to be set up before the object is created.) - \code component.createObject(parent, {"x": 100, "y": 100, "specialProperty": someObject}); \endcode + The \a properties argument is specified as a map of property-value items. For example, the code + below creates an object with initial \c x and \c y values of 100 and 200, respectively: + + \qml + var component = Qt.createComponent("Button.qml"); + if (component.status == Component.Ready) + component.createObject(parent, {"x": 100, "y": 100}); + \endqml Dynamically created instances can be deleted with the \c destroy() method. See \l {Dynamic Object Management in QML} for more information. -- cgit v0.12