diff options
| author | Alan Alpert <alan.alpert@nokia.com> | 2011-08-08 18:03:31 +1000 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2011-08-09 10:11:27 +0200 |
| commit | 1a84b190bd1a2781d03f13fa43ab92bf34809041 (patch) | |
| tree | be4523371df6d2d07041d95c070a22f4724cf031 /src | |
| parent | 955c2b0f29dc709a5cc7e563c21f0f2cf2370336 (diff) | |
Add documentation
Copy the documentation back to the scenegraph items, and update it to
the new module syntax.
Change-Id: I5d030a231f991a209a8593ddb069e1b6cd03580e
Reviewed-on: http://codereview.qt.nokia.com/2735
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>
Diffstat (limited to 'src')
42 files changed, 7815 insertions, 300 deletions
diff --git a/src/declarative/items/qsganimatedimage.cpp b/src/declarative/items/qsganimatedimage.cpp index 0a9fdd1783..ea36153ef0 100644 --- a/src/declarative/items/qsganimatedimage.cpp +++ b/src/declarative/items/qsganimatedimage.cpp @@ -52,6 +52,75 @@ #include <private/qdeclarativeengine_p.h> QT_BEGIN_NAMESPACE +/*! + \qmlclass AnimatedImage QSGAnimatedImage + \inqmlmodule QtQuick 2 + \inherits Image + \ingroup basic-visual-elements + + The AnimatedImage element extends the features of the \l Image element, providing + a way to play animations stored as images containing a series of frames, + such as those stored in GIF files. + + Information about the current frame and totla length of the animation can be + obtained using the \l currentFrame and \l frameCount properties. You can + start, pause and stop the animation by changing the values of the \l playing + and \l paused properties. + + The full list of supported formats can be determined with QMovie::supportedFormats(). + + \section1 Example Usage + + \beginfloatleft + \image animatedimageitem.gif + \endfloat + + The following QML shows how to display an animated image and obtain information + about its state, such as the current frame and total number of frames. + The result is an animated image with a simple progress indicator underneath it. + + \bold Note: Unlike images, animated images are not cached or shared internally. + + \clearfloat + \snippet doc/src/snippets/declarative/animatedimage.qml document + + \sa BorderImage, Image +*/ + +/*! + \qmlproperty url QtQuick2::AnimatedImage::source + + This property holds the URL that refers to the source image. + + AnimatedImage can handle any image format supported by Qt, loaded from any + URL scheme supported by Qt. + + \sa QDeclarativeImageProvider +*/ + +/*! + \qmlproperty bool QtQuick2::AnimatedImage::asynchronous + + Specifies that images on the local filesystem should be loaded + asynchronously in a separate thread. The default value is + false, causing the user interface thread to block while the + image is loaded. Setting \a asynchronous to true is useful where + maintaining a responsive user interface is more desirable + than having images immediately visible. + + Note that this property is only valid for images read from the + local filesystem. Images loaded via a network resource (e.g. HTTP) + are always loaded asynchonously. +*/ + +/*! + \qmlproperty bool QtQuick2::AnimatedImage::mirror + + This property holds whether the image should be horizontally inverted + (effectively displaying a mirrored image). + + The default value is false. +*/ QSGAnimatedImage::QSGAnimatedImage(QSGItem *parent) : QSGImage(*(new QSGAnimatedImagePrivate), parent) @@ -64,6 +133,14 @@ QSGAnimatedImage::~QSGAnimatedImage() delete d->_movie; } +/*! + \qmlproperty bool QtQuick2::AnimatedImage::paused + This property holds whether the animated image is paused. + + By default, this property is false. Set it to true when you want to pause + the animation. +*/ + bool QSGAnimatedImage::isPaused() const { Q_D(const QSGAnimatedImage); @@ -83,6 +160,14 @@ void QSGAnimatedImage::setPaused(bool pause) d->_movie->setPaused(pause); } +/*! + \qmlproperty bool QtQuick2::AnimatedImage::playing + This property holds whether the animated image is playing. + + By default, this property is true, meaning that the animation + will start playing immediately. +*/ + bool QSGAnimatedImage::isPlaying() const { Q_D(const QSGAnimatedImage); @@ -105,6 +190,16 @@ void QSGAnimatedImage::setPlaying(bool play) d->_movie->stop(); } +/*! + \qmlproperty int QtQuick2::AnimatedImage::currentFrame + \qmlproperty int QtQuick2::AnimatedImage::frameCount + + currentFrame is the frame that is currently visible. By monitoring this property + for changes, you can animate other items at the same time as the image. + + frameCount is the number of frames in the animation. For some animation formats, + frameCount is unknown and has a value of zero. +*/ int QSGAnimatedImage::currentFrame() const { Q_D(const QSGAnimatedImage); diff --git a/src/declarative/items/qsgborderimage.cpp b/src/declarative/items/qsgborderimage.cpp index e4cb535bcd..931a681c1a 100644 --- a/src/declarative/items/qsgborderimage.cpp +++ b/src/declarative/items/qsgborderimage.cpp @@ -50,6 +50,119 @@ QT_BEGIN_NAMESPACE + +/*! + \qmlclass BorderImage QSGBorderImage + \inqmlmodule QtQuick 2 + \brief The BorderImage element provides an image that can be used as a border. + \inherits Item + \ingroup qml-basic-visual-elements + + The BorderImage element is used to create borders out of images by scaling or tiling + parts of each image. + + A BorderImage element breaks a source image, specified using the \l url property, + into 9 regions, as shown below: + + \image declarative-scalegrid.png + + When the image is scaled, regions of the source image are scaled or tiled to + create the displayed border image in the following way: + + \list + \i The corners (regions 1, 3, 7, and 9) are not scaled at all. + \i Regions 2 and 8 are scaled according to + \l{BorderImage::horizontalTileMode}{horizontalTileMode}. + \i Regions 4 and 6 are scaled according to + \l{BorderImage::verticalTileMode}{verticalTileMode}. + \i The middle (region 5) is scaled according to both + \l{BorderImage::horizontalTileMode}{horizontalTileMode} and + \l{BorderImage::verticalTileMode}{verticalTileMode}. + \endlist + + The regions of the image are defined using the \l border property group, which + describes the distance from each edge of the source image to use as a border. + + \section1 Example Usage + + The following examples show the effects of the different modes on an image. + Guide lines are overlaid onto the image to show the different regions of the + image as described above. + + \beginfloatleft + \image qml-borderimage-normal-image.png + \endfloat + + An unscaled image is displayed using an Image element. The \l border property is + used to determine the parts of the image that will lie inside the unscaled corner + areas and the parts that will be stretched horizontally and vertically. + + \snippet doc/src/snippets/declarative/borderimage/normal-image.qml normal image + + \clearfloat + \beginfloatleft + \image qml-borderimage-scaled.png + \endfloat + + A BorderImage element is used to display the image, and it is given a size that is + larger than the original image. Since the \l horizontalTileMode property is set to + \l{BorderImage::horizontalTileMode}{BorderImage.Stretch}, the parts of image in + regions 2 and 8 are stretched horizontally. Since the \l verticalTileMode property + is set to \l{BorderImage::verticalTileMode}{BorderImage.Stretch}, the parts of image + in regions 4 and 6 are stretched vertically. + + \snippet doc/src/snippets/declarative/borderimage/borderimage-scaled.qml scaled border image + + \clearfloat + \beginfloatleft + \image qml-borderimage-tiled.png + \endfloat + + Again, a large BorderImage element is used to display the image. With the + \l horizontalTileMode property set to \l{BorderImage::horizontalTileMode}{BorderImage.Repeat}, + the parts of image in regions 2 and 8 are tiled so that they fill the space at the + top and bottom of the element. Similarly, the \l verticalTileMode property is set to + \l{BorderImage::verticalTileMode}{BorderImage.Repeat}, the parts of image in regions + 4 and 6 are tiled so that they fill the space at the left and right of the element. + + \snippet doc/src/snippets/declarative/borderimage/borderimage-tiled.qml tiled border image + + \clearfloat + In some situations, the width of regions 2 and 8 may not be an exact multiple of the width + of the corresponding regions in the source image. Similarly, the height of regions 4 and 6 + may not be an exact multiple of the height of the corresponding regions. It can be useful + to use \l{BorderImage::horizontalTileMode}{BorderImage.Round} instead of + \l{BorderImage::horizontalTileMode}{BorderImage.Repeat} in cases like these. + + The \l{declarative/imageelements/borderimage}{BorderImage example} shows how a BorderImage + can be used to simulate a shadow effect on a rectangular item. + + \section1 Quality and Performance + + By default, any scaled regions of the image are rendered without smoothing to improve + rendering speed. Setting the \l smooth property improves rendering quality of scaled + regions, but may slow down rendering. + + The source image may not be loaded instantaneously, depending on its original location. + Loading progress can be monitored with the \l progress property. + + \sa Image, AnimatedImage + */ + +/*! + \qmlproperty bool QtQuick2::BorderImage::asynchronous + + Specifies that images on the local filesystem should be loaded + asynchronously in a separate thread. The default value is + false, causing the user interface thread to block while the + image is loaded. Setting \a asynchronous to true is useful where + maintaining a responsive user interface is more desirable + than having images immediately visible. + + Note that this property is only valid for images read from the + local filesystem. Images loaded via a network resource (e.g. HTTP) + are always loaded asynchonously. +*/ QSGBorderImage::QSGBorderImage(QSGItem *parent) : QSGImageBase(*(new QSGBorderImagePrivate), parent) { @@ -62,6 +175,99 @@ QSGBorderImage::~QSGBorderImage() d->sciReply->deleteLater(); } +/*! + \qmlproperty enumeration QtQuick2::BorderImage::status + + This property describes the status of image loading. It can be one of: + + \list + \o BorderImage.Null - no image has been set + \o BorderImage.Ready - the image has been loaded + \o BorderImage.Loading - the image is currently being loaded + \o BorderImage.Error - an error occurred while loading the image + \endlist + + \sa progress +*/ + +/*! + \qmlproperty real QtQuick2::BorderImage::progress + + This property holds the progress of image loading, from 0.0 (nothing loaded) + to 1.0 (finished). + + \sa status +*/ + +/*! + \qmlproperty bool QtQuick2::BorderImage::smooth + + Set this property if you want the image to be smoothly filtered when scaled or + transformed. Smooth filtering gives better visual quality, but is slower. If + the image is displayed at its natural size, this property has no visual or + performance effect. + + By default, this property is set to false. + + \note Generally scaling artifacts are only visible if the image is stationary on + the screen. A common pattern when animating an image is to disable smooth + filtering at the beginning of the animation and enable it at the conclusion. +*/ + +/*! + \qmlproperty bool QtQuick2::BorderImage::cache + + 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 QtQuick2::BorderImage::mirror + + This property holds whether the image should be horizontally inverted + (effectively displaying a mirrored image). + + The default value is false. +*/ + +/*! + \qmlproperty url QtQuick2::BorderImage::source + + This property holds the URL that refers to the source image. + + BorderImage can handle any image format supported by Qt, loaded from any + URL scheme supported by Qt. + + This property can also be used to refer to .sci files, which are + written in a QML-specific, text-based format that specifies the + borders, the image file and the tile rules for a given border image. + + The following .sci file sets the borders to 10 on each side for the + image \c picture.png: + + \code + border.left: 10 + border.top: 10 + border.bottom: 10 + border.right: 10 + source: "picture.png" + \endcode + + The URL may be absolute, or relative to the URL of the component. + + \sa QDeclarativeImageProvider +*/ + +/*! + \qmlproperty QSize QtQuick2::BorderImage::sourceSize + + This property holds the actual width and height of the loaded image. + + In BorderImage, this property is read-only. + + \sa Image::sourceSize +*/ void QSGBorderImage::setSource(const QUrl &url) { Q_D(QSGBorderImage); @@ -160,12 +366,55 @@ void QSGBorderImage::load() emit statusChanged(d->status); } +/*! + \qmlproperty int QtQuick2::BorderImage::border.left + \qmlproperty int QtQuick2::BorderImage::border.right + \qmlproperty int QtQuick2::BorderImage::border.top + \qmlproperty int QtQuick2::BorderImage::border.bottom + + The 4 border lines (2 horizontal and 2 vertical) break the image into 9 sections, + as shown below: + + \image declarative-scalegrid.png + + Each border line (left, right, top, and bottom) specifies an offset in pixels + from the respective edge of the source image. By default, each border line has + a value of 0. + + For example, the following definition sets the bottom line 10 pixels up from + the bottom of the image: + + \qml + BorderImage { + border.bottom: 10 + // ... + } + \endqml + + The border lines can also be specified using a + \l {BorderImage::source}{.sci file}. +*/ + QSGScaleGrid *QSGBorderImage::border() { Q_D(QSGBorderImage); return d->getScaleGrid(); } +/*! + \qmlproperty enumeration QtQuick2::BorderImage::horizontalTileMode + \qmlproperty enumeration QtQuick2::BorderImage::verticalTileMode + + This property describes how to repeat or stretch the middle parts of the border image. + + \list + \o BorderImage.Stretch - Scales the image to fit to the available area. + \o BorderImage.Repeat - Tile the image until there is no more space. May crop the last image. + \o BorderImage.Round - Like Repeat, but scales the images down to ensure that the last image is not cropped. + \endlist + + The default tile mode for each property is BorderImage.Stretch. +*/ QSGBorderImage::TileMode QSGBorderImage::horizontalTileMode() const { Q_D(const QSGBorderImage); diff --git a/src/declarative/items/qsgevents.cpp b/src/declarative/items/qsgevents.cpp index 0c5d8cac34..2173b4a21f 100644 --- a/src/declarative/items/qsgevents.cpp +++ b/src/declarative/items/qsgevents.cpp @@ -43,4 +43,197 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass KeyEvent QSGKeyEvent + \inqmlmodule QtQuick 2 + \ingroup qml-event-elements + + \brief The KeyEvent object provides information about a key event. + + For example, the following changes the Item's state property when the Enter + key is pressed: + \qml +Item { + focus: true + Keys.onPressed: { if (event.key == Qt.Key_Enter) state = 'ShowDetails'; } +} + \endqml +*/ + +/*! + \qmlproperty int QtQuick2::KeyEvent::key + + This property holds the code of the key that was pressed or released. + + See \l {Qt::Key}{Qt.Key} for the list of keyboard codes. These codes are + independent of the underlying window system. Note that this + function does not distinguish between capital and non-capital + letters, use the text() function (returning the Unicode text the + key generated) for this purpose. + + A value of either 0 or \l {Qt::Key_unknown}{Qt.Key_Unknown} means that the event is not + the result of a known key; for example, it may be the result of + a compose sequence, a keyboard macro, or due to key event + compression. +*/ + +/*! + \qmlproperty string QtQuick2::KeyEvent::text + + This property holds the Unicode text that the key generated. + The text returned can be an empty string in cases where modifier keys, + such as Shift, Control, Alt, and Meta, are being pressed or released. + In such cases \c key will contain a valid value +*/ + +/*! + \qmlproperty bool QtQuick2::KeyEvent::isAutoRepeat + + This property holds whether this event comes from an auto-repeating key. +*/ + +/*! + \qmlproperty int QtQuick2::KeyEvent::count + + This property holds the number of keys involved in this event. If \l KeyEvent::text + is not empty, this is simply the length of the string. +*/ + +/*! + \qmlproperty bool QtQuick2::KeyEvent::accepted + + Setting \a accepted to true prevents the key event from being + propagated to the item's parent. + + Generally, if the item acts on the key event then it should be accepted + so that ancestor items do not also respond to the same event. +*/ + +/*! + \qmlproperty int QtQuick2::KeyEvent::modifiers + + This property holds the keyboard modifier flags that existed immediately + before the event occurred. + + It contains a bitwise combination of: + \list + \o Qt.NoModifier - No modifier key is pressed. + \o Qt.ShiftModifier - A Shift key on the keyboard is pressed. + \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed. + \o Qt.AltModifier - An Alt key on the keyboard is pressed. + \o Qt.MetaModifier - A Meta key on the keyboard is pressed. + \o Qt.KeypadModifier - A keypad button is pressed. + \endlist + + For example, to react to a Shift key + Enter key combination: + \qml + Item { + focus: true + Keys.onPressed: { + if ((event.key == Qt.Key_Enter) && (event.modifiers & Qt.ShiftModifier)) + doSomething(); + } + } + \endqml +*/ + + +/*! + \qmlclass MouseEvent QSGMouseEvent + \inqmlmodule QtQuick 2 + \ingroup qml-event-elements + + \brief The MouseEvent object provides information about a mouse event. + + The position of the mouse can be found via the \l x and \l y properties. + The button that caused the event is available via the \l button property. + + \sa MouseArea +*/ + +/*! + \internal + \class QSGMouseEvent +*/ + +/*! + \qmlproperty int QtQuick2::MouseEvent::x + \qmlproperty int QtQuick2::MouseEvent::y + + These properties hold the coordinates of the position supplied by the mouse event. +*/ + + +/*! + \qmlproperty bool QtQuick2::MouseEvent::accepted + + Setting \a accepted to true prevents the mouse event from being + propagated to items below this item. + + Generally, if the item acts on the mouse event then it should be accepted + so that items lower in the stacking order do not also respond to the same event. +*/ + +/*! + \qmlproperty enumeration QtQuick2::MouseEvent::button + + This property holds the button that caused the event. It can be one of: + \list + \o Qt.LeftButton + \o Qt.RightButton + \o Qt.MiddleButton + \endlist +*/ + +/*! + \qmlproperty bool QtQuick2::MouseEvent::wasHeld + + This property is true if the mouse button has been held pressed longer the + threshold (800ms). +*/ + +/*! + \qmlproperty int QtQuick2::MouseEvent::buttons + + This property holds the mouse buttons pressed when the event was generated. + For mouse move events, this is all buttons that are pressed down. For mouse + press and double click events this includes the button that caused the event. + For mouse release events this excludes the button that caused the event. + + It contains a bitwise combination of: + \list + \o Qt.LeftButton + \o Qt.RightButton + \o Qt.MiddleButton + \endlist +*/ + +/*! + \qmlproperty int QtQuick2::MouseEvent::modifiers + + This property holds the keyboard modifier flags that existed immediately + before the event occurred. + + It contains a bitwise combination of: + \list + \o Qt.NoModifier - No modifier key is pressed. + \o Qt.ShiftModifier - A Shift key on the keyboard is pressed. + \o Qt.ControlModifier - A Ctrl key on the keyboard is pressed. + \o Qt.AltModifier - An Alt key on the keyboard is pressed. + \o Qt.MetaModifier - A Meta key on the keyboard is pressed. + \o Qt.KeypadModifier - A keypad button is pressed. + \endlist + + For example, to react to a Shift key + Left mouse button click: + \qml + MouseArea { + onClicked: { + if ((mouse.button == Qt.LeftButton) && (mouse.modifiers & Qt.ShiftModifier)) + doSomething(); + } + } + \endqml +*/ + + QT_END_NAMESPACE diff --git a/src/declarative/items/qsgflickable.cpp b/src/declarative/items/qsgflickable.cpp index f226c4b468..d62197f7d6 100644 --- a/src/declarative/items/qsgflickable.cpp +++ b/src/declarative/items/qsgflickable.cpp @@ -456,6 +456,107 @@ is finished. touch/mouse button is released then a flick will start. */ +/*! + \qmlclass Flickable QSGFlickable + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + + \brief The Flickable item provides a surface that can be "flicked". + \inherits Item + + The Flickable item places its children on a surface that can be dragged + and flicked, causing the view onto the child items to scroll. This + behavior forms the basis of Items that are designed to show large numbers + of child items, such as \l ListView and \l GridView. + + In traditional user interfaces, views can be scrolled using standard + controls, such as scroll bars and arrow buttons. In some situations, it + is also possible to drag the view directly by pressing and holding a + mouse button while moving the cursor. In touch-based user interfaces, + this dragging action is often complemented with a flicking action, where + scrolling continues after the user has stopped touching the view. + + Flickable does not automatically clip its contents. If it is not used as + a full-screen item, you should consider setting the \l{Item::}{clip} property + to true. + + \section1 Example Usage + + \div {class="float-right"} + \inlineimage flickable.gif + \enddiv + + The following example shows a small view onto a large image in which the + user can drag or flick the image in order to view different parts of it. + + \snippet doc/src/snippets/declarative/flickable.qml document + + \clearfloat + + Items declared as children of a Flickable are automatically parented to the + Flickable's \l contentItem. This should be taken into account when + operating on the children of the Flickable; it is usually the children of + \c contentItem that are relevant. For example, the bound of Items added + to the Flickable will be available by \c contentItem.childrenRect + + \section1 Limitations + + \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by + \c id. Use \c parent instead. +*/ + +/*! + \qmlsignal QtQuick2::Flickable::onMovementStarted() + + This handler is called when the view begins moving due to user + interaction. +*/ + +/*! + \qmlsignal QtQuick2::Flickable::onMovementEnded() + + This handler is called when the view stops moving due to user + interaction. If a flick was generated, this handler will + be triggered once the flick stops. If a flick was not + generated, the handler will be triggered when the + user stops dragging - i.e. a mouse or touch release. +*/ + +/*! + \qmlsignal QtQuick2::Flickable::onFlickStarted() + + This handler is called when the view is flicked. A flick + starts from the point that the mouse or touch is released, + while still in motion. +*/ + +/*! + \qmlsignal QtQuick2::Flickable::onFlickEnded() + + This handler is called when the view stops moving due to a flick. +*/ + +/*! + \qmlproperty real QtQuick2::Flickable::visibleArea.xPosition + \qmlproperty real QtQuick2::Flickable::visibleArea.widthRatio + \qmlproperty real QtQuick2::Flickable::visibleArea.yPosition + \qmlproperty real QtQuick2::Flickable::visibleArea.heightRatio + + These properties describe the position and size of the currently viewed area. + The size is defined as the percentage of the full view currently visible, + scaled to 0.0 - 1.0. The page position is usually in the range 0.0 (beginning) to + 1.0 minus size ratio (end), i.e. \c yPosition is in the range 0.0 to 1.0-\c heightRatio. + However, it is possible for the contents to be dragged outside of the normal + range, resulting in the page positions also being outside the normal range. + + These properties are typically used to draw a scrollbar. For example: + + \snippet doc/src/snippets/declarative/flickableScrollbar.qml 0 + \dots 8 + \snippet doc/src/snippets/declarative/flickableScrollbar.qml 1 + + \sa {declarative/ui-components/scrollbar}{scrollbar example} +*/ QSGFlickable::QSGFlickable(QSGItem *parent) : QSGItem(*(new QSGFlickablePrivate), parent) { @@ -474,6 +575,14 @@ QSGFlickable::~QSGFlickable() { } +/*! + \qmlproperty real QtQuick2::Flickable::contentX + \qmlproperty real QtQuick2::Flickable::contentY + + These properties hold the surface coordinate currently at the top-left + corner of the Flickable. For example, if you flick an image up 100 pixels, + \c contentY will be 100. +*/ qreal QSGFlickable::contentX() const { Q_D(const QSGFlickable); @@ -510,6 +619,19 @@ void QSGFlickable::setContentY(qreal pos) } } +/*! + \qmlproperty bool QtQuick2::Flickable::interactive + + This property describes whether the user can interact with the Flickable. + A user cannot drag or flick a Flickable that is not interactive. + + By default, this property is true. + + This property is useful for temporarily disabling flicking. This allows + special interaction with Flickable's children; for example, you might want + to freeze a flickable map while scrolling through a pop-up dialog that + is a child of the Flickable. +*/ bool QSGFlickable::isInteractive() const { Q_D(const QSGFlickable); @@ -535,6 +657,14 @@ void QSGFlickable::setInteractive(bool interactive) } } +/*! + \qmlproperty real QtQuick2::Flickable::horizontalVelocity + \qmlproperty real QtQuick2::Flickable::verticalVelocity + + The instantaneous velocity of movement along the x and y axes, in pixels/sec. + + The reported velocity is smoothed to avoid erratic output. +*/ qreal QSGFlickable::horizontalVelocity() const { Q_D(const QSGFlickable); @@ -547,6 +677,15 @@ qreal QSGFlickable::verticalVelocity() const return d->vData.smoothVelocity.value(); } +/*! + \qmlproperty bool QtQuick2::Flickable::atXBeginning + \qmlproperty bool QtQuick2::Flickable::atXEnd + \qmlproperty bool QtQuick2::Flickable::atYBeginning + \qmlproperty bool QtQuick2::Flickable::atYEnd + + These properties are true if the flickable view is positioned at the beginning, + or end respecively. +*/ bool QSGFlickable::isAtXEnd() const { Q_D(const QSGFlickable); @@ -576,6 +715,24 @@ void QSGFlickable::ticked() viewportMoved(); } +/*! + \qmlproperty Item QtQuick2::Flickable::contentItem + + The internal item that contains the Items to be moved in the Flickable. + + Items declared as children of a Flickable are automatically parented to the Flickable's contentItem. + + Items created dynamically need to be explicitly parented to the \e contentItem: + \code + Flickable { + id: myFlickable + function addItem(file) { + var component = Qt.createComponent(file) + component.createObject(myFlickable.contentItem); + } + } + \endcode +*/ QSGItem *QSGFlickable::contentItem() { Q_D(QSGFlickable); @@ -590,6 +747,21 @@ QSGFlickableVisibleArea *QSGFlickable::visibleArea() return d->visibleArea; } +/*! + \qmlproperty enumeration QtQuick2::Flickable::flickableDirection + + This property determines which directions the view can be flicked. + + \list + \o Flickable.AutoFlickDirection (default) - allows flicking vertically if the + \e contentHeight is not equal to the \e height of the Flickable. + Allows flicking horizontally if the \e contentWidth is not equal + to the \e width of the Flickable. + \o Flickable.HorizontalFlick - allows flicking horizontally. + \o Flickable.VerticalFlick - allows flicking vertically. + \o Flickable.HorizontalAndVerticalFlick - allows flicking in both directions. + \endlist +*/ QSGFlickable::FlickableDirection QSGFlickable::flickableDirection() const { Q_D(const QSGFlickable); @@ -1118,6 +1290,27 @@ QDeclarativeListProperty<QSGItem> QSGFlickable::flickableChildren() return QSGItemPrivate::get(d->contentItem)->children(); } +/*! + \qmlproperty enumeration QtQuick2::Flickable::boundsBehavior + This property holds whether the surface may be dragged + beyond the Fickable's boundaries, or overshoot the + Flickable's boundaries when flicked. + + This enables the feeling that the edges of the view are soft, + rather than a hard physical boundary. + + The \c boundsBehavior can be one of: + + \list + \o Flickable.StopAtBounds - the contents can not be dragged beyond the boundary + of the flickable, and flicks will not overshoot. + \o Flickable.DragOverBounds - the contents can be dragged beyond the boundary + of the Flickable, but flicks will not overshoot. + \o Flickable.DragAndOvershootBounds (default) - the contents can be dragged + beyond the boundary of the Flickable, and can overshoot the + boundary when flicked. + \endlist +*/ QSGFlickable::BoundsBehavior QSGFlickable::boundsBehavior() const { Q_D(const QSGFlickable); @@ -1133,6 +1326,23 @@ void QSGFlickable::setBoundsBehavior(BoundsBehavior b) emit boundsBehaviorChanged(); } +/*! + \qmlproperty real QtQuick2::Flickable::contentWidth + \qmlproperty real QtQuick2::Flickable::contentHeight + + The dimensions of the content (the surface controlled by Flickable). + This should typically be set to the combined size of the items placed in the + Flickable. + + The following snippet shows how these properties are used to display + an image that is larger than the Flickable item itself: + + \snippet doc/src/snippets/declarative/flickable.qml document + + In some cases, the the content dimensions can be automatically set + using the \l {Item::childrenRect.width}{childrenRect.width} + and \l {Item::childrenRect.height}{childrenRect.height} properties. +*/ qreal QSGFlickable::contentWidth() const { Q_D(const QSGFlickable); @@ -1189,6 +1399,19 @@ void QSGFlickable::setContentHeight(qreal h) d->updateBeginningEnd(); } +/*! + \qmlmethod QtQuick2::Flickable::resizeContent(real width, real height, QPointF center) + \preliminary + + Resizes the content to \a width x \a height about \a center. + + This does not scale the contents of the Flickable - it only resizes the \l contentWidth + and \l contentHeight. + + Resizing the content may result in the content being positioned outside + the bounds of the Flickable. Calling \l returnToBounds() will + move the content back within legal bounds. +*/ void QSGFlickable::resizeContent(qreal w, qreal h, QPointF center) { Q_D(QSGFlickable); @@ -1215,6 +1438,15 @@ void QSGFlickable::resizeContent(qreal w, qreal h, QPointF center) d->updateBeginningEnd(); } +/*! + \qmlmethod QtQuick2::Flickable::returnToBounds() + \preliminary + + Ensures the content is within legal bounds. + + This may be called to ensure that the content is within legal bounds + after manually positioning the content. +*/ void QSGFlickable::returnToBounds() { Q_D(QSGFlickable); @@ -1363,6 +1595,12 @@ bool QSGFlickable::childMouseEventFilter(QSGItem *i, QEvent *e) return QSGItem::childMouseEventFilter(i, e); } +/*! + \qmlproperty real QtQuick2::Flickable::maximumFlickVelocity + This property holds the maximum velocity that the user can flick the view in pixels/second. + + The default value is platform dependent. +*/ qreal QSGFlickable::maximumFlickVelocity() const { Q_D(const QSGFlickable); @@ -1378,6 +1616,12 @@ void QSGFlickable::setMaximumFlickVelocity(qreal v) emit maximumFlickVelocityChanged(); } +/*! + \qmlproperty real QtQuick2::Flickable::flickDeceleration + This property holds the rate at which a flick will decelerate. + + The default value is platform dependent. +*/ qreal QSGFlickable::flickDeceleration() const { Q_D(const QSGFlickable); @@ -1399,6 +1643,14 @@ bool QSGFlickable::isFlicking() const return d->flickingHorizontally || d->flickingVertically; } +/*! + \qmlproperty bool QtQuick2::Flickable::flicking + \qmlproperty bool QtQuick2::Flickable::flickingHorizontally + \qmlproperty bool QtQuick2::Flickable::flickingVertically + + These properties describe whether the view is currently moving horizontally, + vertically or in either direction, due to the user flicking the view. +*/ bool QSGFlickable::isFlickingHorizontally() const { Q_D(const QSGFlickable); @@ -1473,6 +1725,20 @@ void QSGFlickablePrivate::draggingEnding() } } +/*! + \qmlproperty int QtQuick2::Flickable::pressDelay + + This property holds the time to delay (ms) delivering a press to + children of the Flickable. This can be useful where reacting + to a press before a flicking action has undesirable effects. + + If the flickable is dragged/flicked before the delay times out + the press event will not be delivered. If the button is released + within the timeout, both the press and release will be delivered. + + Note that for nested Flickables with pressDelay set, the pressDelay of + inner Flickables is overridden by the outermost Flickable. +*/ int QSGFlickable::pressDelay() const { Q_D(const QSGFlickable); @@ -1488,6 +1754,15 @@ void QSGFlickable::setPressDelay(int delay) emit pressDelayChanged(); } +/*! + \qmlproperty bool QtQuick2::Flickable::moving + \qmlproperty bool QtQuick2::Flickable::movingHorizontally + \qmlproperty bool QtQuick2::Flickable::movingVertically + + These properties describe whether the view is currently moving horizontally, + vertically or in either direction, due to the user either dragging or + flicking the view. +*/ bool QSGFlickable::isMoving() const { diff --git a/src/declarative/items/qsgflipable.cpp b/src/declarative/items/qsgflipable.cpp index faceb29f73..ac68b3171c 100644 --- a/src/declarative/items/qsgflipable.cpp +++ b/src/declarative/items/qsgflipable.cpp @@ -87,6 +87,47 @@ public: bool wantBackYFlipped; }; +/*! + \qmlclass Flipable QSGFlipable + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + \brief The Flipable item provides a surface that can be flipped. + \inherits Item + + Flipable is an item that can be visibly "flipped" between its front and + back sides, like a card. It is used together with \l Rotation, \l State + and \l Transition elements to produce a flipping effect. + + The \l front and \l back properties are used to hold the items that are + shown respectively on the front and back sides of the flipable item. + + \section1 Example Usage + + The following example shows a Flipable item that flips whenever it is + clicked, rotating about the y-axis. + + This flipable item has a \c flipped boolean property that is toggled + whenever the MouseArea within the flipable is clicked. When + \c flipped is true, the item changes to the "back" state; in this + state, the \c angle of the \l Rotation item is changed to 180 + degrees to produce the flipping effect. When \c flipped is false, the + item reverts to the default state, in which the \c angle value is 0. + + \snippet doc/src/snippets/declarative/flipable/flipable.qml 0 + + \image flipable.gif + + The \l Transition creates the animation that changes the angle over + four seconds. When the item changes between its "back" and + default states, the NumberAnimation animates the angle between + its old and new values. + + See \l {QML States} for details on state changes and the default + state, and \l {QML Animation and Transitions} for more information on how + animations work within transitions. + + \sa {declarative/ui-components/flipable}{Flipable example} +*/ QSGFlipable::QSGFlipable(QSGItem *parent) : QSGItem(*(new QSGFlipablePrivate), parent) { @@ -96,6 +137,13 @@ QSGFlipable::~QSGFlipable() { } +/*! + \qmlproperty Item QtQuick2::Flipable::front + \qmlproperty Item QtQuick2::Flipable::back + + The front and back sides of the flipable. +*/ + QSGItem *QSGFlipable::front() { Q_D(const QSGFlipable); @@ -153,6 +201,12 @@ void QSGFlipable::retransformBack() d->setBackTransform(); } +/*! + \qmlproperty enumeration QtQuick2::Flipable::side + + The side of the Flipable currently visible. Possible values are \c + Flipable.Front and \c Flipable.Back. +*/ QSGFlipable::Side QSGFlipable::side() const { Q_D(const QSGFlipable); diff --git a/src/declarative/items/qsgfocusscope.cpp b/src/declarative/items/qsgfocusscope.cpp index 156869120d..2018d5ce7d 100644 --- a/src/declarative/items/qsgfocusscope.cpp +++ b/src/declarative/items/qsgfocusscope.cpp @@ -43,7 +43,21 @@ QT_BEGIN_NAMESPACE -QSGFocusScope::QSGFocusScope(QSGItem *parent) +/*! + \qmlclass FocusScope QSGFocusScope + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + + \brief The FocusScope object explicitly creates a focus scope. + \inherits Item + + Focus scopes assist in keyboard focus handling when building reusable QML + components. All the details are covered in the + \l {qmlfocus}{keyboard focus documentation}. + + \sa {declarative/keyinteraction/focus}{Keyboard focus example} +*/ +QSGFocusScope::QSGFocusScope(QSGItem *parent) : QSGItem(parent) { setFlag(ItemIsFocusScope); diff --git a/src/declarative/items/qsggridview.cpp b/src/declarative/items/qsggridview.cpp index c9e02a0601..5cfb04ecc7 100644 --- a/src/declarative/items/qsggridview.cpp +++ b/src/declarative/items/qsggridview.cpp @@ -968,6 +968,80 @@ void QSGGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExtent, //---------------------------------------------------------------------------- +/*! + \qmlclass GridView QSGGridView + \inqmlmodule QtQuick 2 + \ingroup qml-view-elements + + \inherits Flickable + \brief The GridView item provides a grid view of items provided by a model. + + A GridView displays data from models created from built-in QML elements like ListModel + and XmlListModel, or custom model classes defined in C++ that inherit from + QAbstractListModel. + + A GridView has a \l model, which defines the data to be displayed, and + a \l delegate, which defines how the data should be displayed. Items in a + GridView are laid out horizontally or vertically. Grid views are inherently flickable + as GridView inherits from \l Flickable. + + \section1 Example Usage + + The following example shows the definition of a simple list model defined + in a file called \c ContactModel.qml: + + \snippet doc/src/snippets/declarative/gridview/ContactModel.qml 0 + + \div {class="float-right"} + \inlineimage gridview-simple.png + \enddiv + + This model can be referenced as \c ContactModel in other QML files. See \l{QML Modules} + for more information about creating reusable components like this. + + Another component can display this model data in a GridView, as in the following + example, which creates a \c ContactModel component for its model, and a \l Column element + (containing \l Image and \l Text elements) for its delegate. + + \clearfloat + \snippet doc/src/snippets/declarative/gridview/gridview.qml import + \codeline + \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs simple + + \div {class="float-right"} + \inlineimage gridview-highlight.png + \enddiv + + The view will create a new delegate for each item in the model. Note that the delegate + is able to access the model's \c name and \c portrait data directly. + + An improved grid view is shown below. The delegate is visually improved and is moved + into a separate \c contactDelegate component. + + \clearfloat + \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs advanced + + The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property, + and \c focus is set to \c true to enable keyboard navigation for the grid view. + The grid view itself is a focus scope (see \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} for more details). + + Delegates are instantiated as needed and may be destroyed at any time. + State should \e never be stored in a delegate. + + GridView attaches a number of properties to the root item of the delegate, for example + \c {GridView.isCurrentItem}. In the following example, the root delegate item can access + this attached property directly as \c GridView.isCurrentItem, while the child + \c contactInfo object must refer to this property as \c wrapper.GridView.isCurrentItem. + + \snippet doc/src/snippets/declarative/gridview/gridview.qml isCurrentItem + + \note Views do not set the \l{Item::}{clip} property automatically. + If the view is not clipped by another item or the screen, it will be necessary + to set this property to true in order to clip the items that are partially or + fully outside the view. + + \sa {declarative/modelviews/gridview}{GridView example} +*/ QSGGridView::QSGGridView(QSGItem *parent) : QSGItemView(*(new QSGGridViewPrivate), parent) @@ -990,6 +1064,242 @@ void QSGGridView::setHighlightFollowsCurrentItem(bool autoHighlight) } } +/*! + \qmlattachedproperty bool GridView::isCurrentItem + This attached property is true if this delegate is the current item; otherwise false. + + It is attached to each instance of the delegate. +*/ + +/*! + \qmlattachedproperty GridView GridView::view + This attached property holds the view that manages this delegate instance. + + It is attached to each instance of the delegate. + + \snippet doc/src/snippets/declarative/gridview/gridview.qml isCurrentItem +*/ + +/*! + \qmlattachedproperty bool GridView::delayRemove + This attached property holds whether the delegate may be destroyed. + + It is attached to each instance of the delegate. + + It is sometimes necessary to delay the destruction of an item + until an animation completes. + + The example below ensures that the animation completes before + the item is removed from the grid. + + \snippet doc/src/snippets/declarative/gridview/gridview.qml delayRemove +*/ + +/*! + \qmlattachedsignal QtQuick2::GridView::onAdd() + This attached handler is called immediately after an item is added to the view. +*/ + +/*! + \qmlattachedsignal QtQuick2::GridView::onRemove() + This attached handler is called immediately before an item is removed from the view. +*/ + + +/*! + \qmlproperty model QtQuick2::GridView::model + This property holds the model providing data for the grid. + + The model provides the set of data that is used to create the items + in the view. Models can be created directly in QML using \l ListModel, \l XmlListModel + or \l VisualItemModel, or provided by C++ model classes. If a C++ model class is + used, it must be a subclass of \l QAbstractItemModel or a simple list. + + \sa {qmlmodels}{Data Models} +*/ + +/*! + \qmlproperty Component QtQuick2::GridView::delegate + + The delegate provides a template defining each item instantiated by the view. + The index is exposed as an accessible \c index property. Properties of the + model are also available depending upon the type of \l {qmlmodels}{Data Model}. + + The number of elements in the delegate has a direct effect on the + flicking performance of the view. If at all possible, place functionality + that is not needed for the normal display of the delegate in a \l Loader which + can load additional elements when needed. + + The GridView will layout the items based on the size of the root item + in the delegate. + + \note Delegates are instantiated as needed and may be destroyed at any time. + State should \e never be stored in a delegate. +*/ + +/*! + \qmlproperty int QtQuick2::GridView::currentIndex + \qmlproperty Item QtQuick2::GridView::currentItem + + The \c currentIndex property holds the index of the current item, and + \c currentItem holds the current item. Setting the currentIndex to -1 + will clear the highlight and set currentItem to null. + + If highlightFollowsCurrentItem is \c true, setting either of these + properties will smoothly scroll the GridView so that the current + item becomes visible. + + Note that the position of the current item + may only be approximate until it becomes visible in the view. +*/ + + +/*! + \qmlproperty Item QtQuick2::GridView::highlightItem + + This holds the highlight item created from the \l highlight component. + + The highlightItem is managed by the view unless + \l highlightFollowsCurrentItem is set to false. + + \sa highlight, highlightFollowsCurrentItem +*/ + + +/*! + \qmlproperty int QtQuick2::GridView::count + This property holds the number of items in the view. +*/ + + +/*! + \qmlproperty Component QtQuick2::GridView::highlight + This property holds the component to use as the highlight. + + An instance of the highlight component is created for each view. + The geometry of the resulting component instance will be managed by the view + so as to stay with the current item, unless the highlightFollowsCurrentItem property is false. + + \sa highlightItem, highlightFollowsCurrentItem +*/ + +/*! + \qmlproperty bool QtQuick2::GridView::highlightFollowsCurrentItem + This property sets whether the highlight is managed by the view. + + If this property is true (the default value), the highlight is moved smoothly + to follow the current item. Otherwise, the + highlight is not moved by the view, and any movement must be implemented + by the highlight. + + Here is a highlight with its motion defined by a \l {SpringAnimation} item: + + \snippet doc/src/snippets/declarative/gridview/gridview.qml highlightFollowsCurrentItem +*/ + + +/*! + \qmlproperty int QtQuick2::GridView::highlightMoveDuration + This property holds the move animation duration of the highlight delegate. + + highlightFollowsCurrentItem must be true for this property + to have effect. + + The default value for the duration is 150ms. + + \sa highlightFollowsCurrentItem +*/ + +/*! + \qmlproperty real QtQuick2::GridView::preferredHighlightBegin + \qmlproperty real QtQuick2::GridView::preferredHighlightEnd + \qmlproperty enumeration QtQuick2::GridView::highlightRangeMode + + These properties define the preferred range of the highlight (for the current item) + within the view. The \c preferredHighlightBegin value must be less than the + \c preferredHighlightEnd value. + + These properties affect the position of the current item when the view is scrolled. + For example, if the currently selected item should stay in the middle of the + view when it is scrolled, set the \c preferredHighlightBegin and + \c preferredHighlightEnd values to the top and bottom coordinates of where the middle + item would be. If the \c currentItem is changed programmatically, the view will + automatically scroll so that the current item is in the middle of the view. + Furthermore, the behavior of the current item index will occur whether or not a + highlight exists. + + Valid values for \c highlightRangeMode are: + + \list + \o GridView.ApplyRange - the view attempts to maintain the highlight within the range. + However, the highlight can move outside of the range at the ends of the view or due + to mouse interaction. + \o GridView.StrictlyEnforceRange - the highlight never moves outside of the range. + The current item changes if a keyboard or mouse action would cause the highlight to move + outside of the range. + \o GridView.NoHighlightRange - this is the default value. + \endlist +*/ + + +/*! + \qmlproperty enumeration QtQuick2::GridView::layoutDirection + This property holds the layout direction of the grid. + + Possible values: + + \list + \o Qt.LeftToRight (default) - Items will be laid out starting in the top, left corner. The flow is + dependent on the \l GridView::flow property. + \o Qt.RightToLeft - Items will be laid out starting in the top, right corner. The flow is dependent + on the \l GridView::flow property. + \endlist + + \bold Note: If GridView::flow is set to GridView.LeftToRight, this is not to be confused if + GridView::layoutDirection is set to Qt.RightToLeft. The GridView.LeftToRight flow value simply + indicates that the flow is horizontal. +*/ + + +/*! + \qmlproperty enumeration QtQuick2::GridView::effectiveLayoutDirection + This property holds the effective layout direction of the grid. + + When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts, + the visual layout direction of the grid will be mirrored. However, the + property \l {GridView::layoutDirection}{layoutDirection} will remain unchanged. + + \sa GridView::layoutDirection, {LayoutMirroring}{LayoutMirroring} +*/ +/*! + \qmlproperty bool QtQuick2::GridView::keyNavigationWraps + This property holds whether the grid wraps key navigation + + If this is true, key navigation that would move the current item selection + past one end of the view instead wraps around and moves the selection to + the other end of the view. + + By default, key navigation is not wrapped. +*/ +/*! + \qmlproperty int QtQuick2::GridView::cacheBuffer + This property determines whether delegates are retained outside the + visible area of the view. + + If non-zero the view will keep as many delegates + instantiated as will fit within the buffer specified. For example, + if in a vertical view the delegate is 20 pixels high and \c cacheBuffer is + set to 40, then up to 2 delegates above and 2 delegates below the visible + area may be retained. + + Note that cacheBuffer is not a pixel buffer - it only maintains additional + instantiated delegates. + + Setting this value can make scrolling the list smoother at the expense + of additional memory usage. It is not a substitute for creating efficient + delegates; the fewer elements in a delegate, the faster a view may be + scrolled. +*/ void QSGGridView::setHighlightMoveDuration(int duration) { Q_D(QSGGridView); @@ -1002,6 +1312,17 @@ void QSGGridView::setHighlightMoveDuration(int duration) } } +/*! + \qmlproperty enumeration QtQuick2::GridView::flow + This property holds the flow of the grid. + + Possible values: + + \list + \o GridView.LeftToRight (default) - Items are laid out from left to right, and the view scrolls vertically + \o GridView.TopToBottom - Items are laid out from top to bottom, and the view scrolls horizontally + \endlist +*/ QSGGridView::Flow QSGGridView::flow() const { Q_D(const QSGGridView); @@ -1028,6 +1349,14 @@ void QSGGridView::setFlow(Flow flow) } +/*! + \qmlproperty int QtQuick2::GridView::cellWidth + \qmlproperty int QtQuick2::GridView::cellHeight + + These properties holds the width and height of each cell in the grid. + + The default cell size is 100x100. +*/ int QSGGridView::cellWidth() const { Q_D(const QSGGridView); @@ -1061,7 +1390,22 @@ void QSGGridView::setCellHeight(int cellHeight) d->layout(); } } - +/*! + \qmlproperty enumeration QtQuick2::GridView::snapMode + + This property determines how the view scrolling will settle following a drag or flick. + The possible values are: + + \list + \o GridView.NoSnap (default) - the view stops anywhere within the visible area. + \o GridView.SnapToRow - the view settles with a row (or column for \c GridView.TopToBottom flow) + aligned with the start of the view. + \o GridView.SnapOneRow - the view will settle no more than one row (or column for \c GridView.TopToBottom flow) + away from the first visible row at the time the mouse button is released. + This mode is particularly useful for moving one page at a time. + \endlist + +*/ QSGGridView::SnapMode QSGGridView::snapMode() const { Q_D(const QSGGridView); @@ -1078,6 +1422,24 @@ void QSGGridView::setSnapMode(SnapMode mode) } +/*! + \qmlproperty Component QtQuick2::GridView::footer + This property holds the component to use as the footer. + + An instance of the footer component is created for each view. The + footer is positioned at the end of the view, after any items. + + \sa header +*/ +/*! + \qmlproperty Component QtQuick2::GridView::header + This property holds the component to use as the header. + + An instance of the header component is created for each view. The + header is positioned at the beginning of the view, before any items. + + \sa footer +*/ void QSGGridView::viewportMoved() { Q_D(QSGGridView); @@ -1183,6 +1545,16 @@ void QSGGridView::keyPressEvent(QKeyEvent *event) event->ignore(); QSGItemView::keyPressEvent(event); } +/*! + \qmlmethod QtQuick2::GridView::moveCurrentIndexUp() + + Move the currentIndex up one item in the view. + The current index will wrap if keyNavigationWraps is true and it + is currently at the end. This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ + void QSGGridView::moveCurrentIndexUp() { @@ -1203,6 +1575,15 @@ void QSGGridView::moveCurrentIndexUp() } } +/*! + \qmlmethod QtQuick2::GridView::moveCurrentIndexDown() + + Move the currentIndex down one item in the view. + The current index will wrap if keyNavigationWraps is true and it + is currently at the end. This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGGridView::moveCurrentIndexDown() { Q_D(QSGGridView); @@ -1222,6 +1603,15 @@ void QSGGridView::moveCurrentIndexDown() } } +/*! + \qmlmethod QtQuick2::GridView::moveCurrentIndexLeft() + + Move the currentIndex left one item in the view. + The current index will wrap if keyNavigationWraps is true and it + is currently at the end. This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGGridView::moveCurrentIndexLeft() { Q_D(QSGGridView); @@ -1255,6 +1645,16 @@ void QSGGridView::moveCurrentIndexLeft() } } + +/*! + \qmlmethod QtQuick2::GridView::moveCurrentIndexRight() + + Move the currentIndex right one item in the view. + The current index will wrap if keyNavigationWraps is true and it + is currently at the end. This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGGridView::moveCurrentIndexRight() { Q_D(QSGGridView); @@ -1633,7 +2033,71 @@ void QSGGridView::itemsMoved(int from, int to, int count) d->layout(); } +/*! + \qmlmethod QtQuick2::GridView::positionViewAtIndex(int index, PositionMode mode) + + Positions the view such that the \a index is at the position specified by + \a mode: + + \list + \o GridView.Beginning - position item at the top (or left for \c GridView.TopToBottom flow) of the view. + \o GridView.Center - position item in the center of the view. + \o GridView.End - position item at bottom (or right for horizontal orientation) of the view. + \o GridView.Visible - if any part of the item is visible then take no action, otherwise + bring the item into view. + \o GridView.Contain - ensure the entire item is visible. If the item is larger than + the view the item is positioned at the top (or left for \c GridView.TopToBottom flow) of the view. + \endlist + + If positioning the view at the index would cause empty space to be displayed at + the beginning or end of the view, the view will be positioned at the boundary. + + It is not recommended to use \l {Flickable::}{contentX} or \l {Flickable::}{contentY} to position the view + at a particular index. This is unreliable since removing items from the start + of the view does not cause all other items to be repositioned. + The correct way to bring an item into view is with \c positionViewAtIndex. + + \bold Note: methods should only be called after the Component has completed. To position + the view at startup, this method should be called by Component.onCompleted. For + example, to position the view at the end: + + \code + Component.onCompleted: positionViewAtIndex(count - 1, GridView.Beginning) + \endcode +*/ + +/*! + \qmlmethod QtQuick2::GridView::positionViewAtBeginning() + \qmlmethod QtQuick2::GridView::positionViewAtEnd() + + Positions the view at the beginning or end, taking into account any header or footer. + + It is not recommended to use \l {Flickable::}{contentX} or \l {Flickable::}{contentY} to position the view + at a particular index. This is unreliable since removing items from the start + of the list does not cause all other items to be repositioned, and because + the actual start of the view can vary based on the size of the delegates. + + \bold Note: methods should only be called after the Component has completed. To position + the view at startup, this method should be called by Component.onCompleted. For + example, to position the view at the end on startup: + + \code + Component.onCompleted: positionViewAtEnd() + \endcode +*/ + +/*! + \qmlmethod int QtQuick2::GridView::indexAt(int x, int y) + + Returns the index of the visible item containing the point \a x, \a y in content + coordinates. If there is no item at the point specified, or the item is + not visible -1 is returned. + + If the item is outside the visible area, -1 is returned, regardless of + whether an item will exist at that point when scrolled into view. + \bold Note: methods should only be called after the Component has completed. +*/ QSGGridViewAttached *QSGGridView::qmlAttachedProperties(QObject *obj) { return new QSGGridViewAttached(obj); diff --git a/src/declarative/items/qsgimage.cpp b/src/declarative/items/qsgimage.cpp index ed55104f2d..e2e766ff0a 100644 --- a/src/declarative/items/qsgimage.cpp +++ b/src/declarative/items/qsgimage.cpp @@ -62,7 +62,6 @@ QSGImagePrivate::QSGImagePrivate() /*! \qmlclass Image QSGImage - \since QtQuick 1.0 \inqmlmodule QtQuick 2 \ingroup qml-basic-visual-elements \brief The Image element displays an image in a declarative user interface @@ -410,7 +409,6 @@ qreal QSGImage::paintedHeight() const /*! \qmlproperty bool QtQuick2::Image::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, @@ -419,7 +417,6 @@ qreal QSGImage::paintedHeight() const /*! \qmlproperty bool QtQuick2::Image::mirror - \since Quick 1.1 This property holds whether the image should be horizontally inverted (effectively displaying a mirrored image). @@ -430,7 +427,6 @@ qreal QSGImage::paintedHeight() const /*! \qmlproperty enumeration QtQuick2::Image::horizontalAlignment \qmlproperty enumeration QtQuick2::Image::verticalAlignment - \since Quick 2.0 Sets the horizontal and vertical alignment of the image. By default, the image is top-left aligned. diff --git a/src/declarative/items/qsgitem.cpp b/src/declarative/items/qsgitem.cpp index f94aa96666..2298be1341 100644 --- a/src/declarative/items/qsgitem.cpp +++ b/src/declarative/items/qsgitem.cpp @@ -72,6 +72,168 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass Transform QSGTransform + \inqmlmodule QtQuick 2 + \ingroup qml-transform-elements + \brief The Transform elements provide a way of building advanced transformations on Items. + + The Transform element is a base type which cannot be instantiated directly. + The following concrete Transform types are available: + + \list + \o \l Rotation + \o \l Scale + \o \l Translate + \endlist + + The Transform elements let you create and control advanced transformations that can be configured + independently using specialized properties. + + You can assign any number of Transform elements to an \l Item. Each Transform is applied in order, + one at a time. +*/ + +/*! + \qmlclass Translate QSGTranslate + \inqmlmodule QtQuick 2 + \ingroup qml-transform-elements + \brief The Translate object provides a way to move an Item without changing its x or y properties. + + The Translate object provides independent control over position in addition to the Item's x and y properties. + + The following example moves the Y axis of the \l Rectangle elements while still allowing the \l Row element + to lay the items out as if they had not been transformed: + \qml + import QtQuick 1.0 + + Row { + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Translate { y: 20 } + } + Rectangle { + width: 100; height: 100 + color: "red" + transform: Translate { y: -20 } + } + } + \endqml + + \image translate.png +*/ + +/*! + \qmlproperty real QtQuick2::Translate::x + + The translation along the X axis. +*/ + +/*! + \qmlproperty real QtQuick2::Translate::y + + The translation along the Y axis. +*/ + +/*! + \qmlclass Scale QSGScale + \inqmlmodule QtQuick 2 + \ingroup qml-transform-elements + \brief The Scale element provides a way to scale an Item. + + The Scale element gives more control over scaling than using \l Item's \l{Item::scale}{scale} property. Specifically, + it allows a different scale for the x and y axes, and allows the scale to be relative to an + arbitrary point. + + The following example scales the X axis of the Rectangle, relative to its interior point 25, 25: + \qml + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Scale { origin.x: 25; origin.y: 25; xScale: 3} + } + \endqml + + \sa Rotation, Translate +*/ + +/*! + \qmlproperty real QtQuick2::Scale::origin.x + \qmlproperty real QtQuick2::Scale::origin.y + + The point that the item is scaled from (i.e., the point that stays fixed relative to the parent as + the rest of the item grows). By default the origin is 0, 0. +*/ + +/*! + \qmlproperty real QtQuick2::Scale::xScale + + The scaling factor for the X axis. +*/ + +/*! + \qmlproperty real QtQuick2::Scale::yScale + + The scaling factor for the Y axis. +*/ + +/*! + \qmlclass Rotation QSGRotation + \inqmlmodule QtQuick 2 + \ingroup qml-transform-elements + \brief The Rotation object provides a way to rotate an Item. + + The Rotation object gives more control over rotation than using \l Item's \l{Item::rotation}{rotation} property. + Specifically, it allows (z axis) rotation to be relative to an arbitrary point. + + The following example rotates a Rectangle around its interior point 25, 25: + \qml + Rectangle { + width: 100; height: 100 + color: "blue" + transform: Rotation { origin.x: 25; origin.y: 25; angle: 45} + } + \endqml + + Rotation also provides a way to specify 3D-like rotations for Items. For these types of + rotations you must specify the axis to rotate around in addition to the origin point. + + The following example shows various 3D-like rotations applied to an \l Image. + \snippet doc/src/snippets/declarative/rotation.qml 0 + + \image axisrotation.png + + \sa {declarative/ui-components/dialcontrol}{Dial Control example}, {declarative/toys/clocks}{Clocks example} +*/ + +/*! + \qmlproperty real QtQuick2::Rotation::origin.x + \qmlproperty real QtQuick2::Rotation::origin.y + + The origin point of the rotation (i.e., the point that stays fixed relative to the parent as + the rest of the item rotates). By default the origin is 0, 0. +*/ + +/*! + \qmlproperty real QtQuick2::Rotation::axis.x + \qmlproperty real QtQuick2::Rotation::axis.y + \qmlproperty real QtQuick2::Rotation::axis.z + + The axis to rotate around. For simple (2D) rotation around a point, you do not need to specify an axis, + as the default axis is the z axis (\c{ axis { x: 0; y: 0; z: 1 } }). + + For a typical 3D-like rotation you will usually specify both the origin and the axis. + + \image 3d-rotation-axis.png +*/ + +/*! + \qmlproperty real QtQuick2::Rotation::angle + + The angle to rotate, in degrees clockwise. +*/ + QSGTransformPrivate::QSGTransformPrivate() { } @@ -105,7 +267,7 @@ void QSGTransform::update() } } -QSGContents::QSGContents(QSGItem *item) +QSGContents::QSGContents(QSGItem *item) : m_item(item), m_x(0), m_y(0), m_width(0), m_height(0) { //### optimize @@ -284,6 +446,69 @@ void QSGItemKeyFilter::componentComplete() { if (m_next) m_next->componentComplete(); } +/*! + \qmlclass KeyNavigation QSGKeyNavigationAttached + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + \brief The KeyNavigation attached property supports key navigation by arrow keys. + + Key-based user interfaces commonly allow the use of arrow keys to navigate between + focusable items. The KeyNavigation attached property enables this behavior by providing a + convenient way to specify the item that should gain focus when an arrow or tab key is pressed. + + The following example provides key navigation for a 2x2 grid of items: + + \snippet doc/src/snippets/declarative/keynavigation.qml 0 + + The top-left item initially receives focus by setting \l {Item::}{focus} to + \c true. When an arrow key is pressed, the focus will move to the + appropriate item, as defined by the value that has been set for + the KeyNavigation \l left, \l right, \l up or \l down properties. + + Note that if a KeyNavigation attached property receives the key press and release + events for a requested arrow or tab key, the event is accepted and does not + propagate any further. + + By default, KeyNavigation receives key events after the item to which it is attached. + If the item accepts the key event, the KeyNavigation attached property will not + receive an event for that key. Setting the \l priority property to + \c KeyNavigation.BeforeItem allows the event to be used for key navigation + before the item, rather than after. + + If item to which the focus is switching is not enabled or visible, an attempt will + be made to skip this item and focus on the next. This is possible if there are + a chain of items with the same KeyNavigation handler. If multiple items in a row are not enabled + or visible, they will also be skipped. + + KeyNavigation will implicitly set the other direction to return focus to this item. So if you set + \l left to another item, \l right will be set on that item's KeyNavigation to set focus back to this + item. However, if that item's KeyNavigation has had right explicitly set then no change will occur. + This means that the above example could have been written, with the same behaviour, without specifing + KeyNavigation.right or KeyNavigation.down for any of the items. + + \sa {Keys}{Keys attached property} +*/ + +/*! + \qmlproperty Item QtQuick2::KeyNavigation::left + \qmlproperty Item QtQuick2::KeyNavigation::right + \qmlproperty Item QtQuick2::KeyNavigation::up + \qmlproperty Item QtQuick2::KeyNavigation::down + \qmlproperty Item QtQuick2::KeyNavigation::tab + \qmlproperty Item QtQuick2::KeyNavigation::backtab + + These properties hold the item to assign focus to + when the left, right, up or down cursor keys, or the + tab key are pressed. +*/ + +/*! + \qmlproperty Item QtQuick2::KeyNavigation::tab + \qmlproperty Item QtQuick2::KeyNavigation::backtab + + These properties hold the item to assign focus to + when the Tab key or Shift+Tab key combination (Backtab) are pressed. +*/ QSGKeyNavigationAttached::QSGKeyNavigationAttached(QObject *parent) : QObject(*(new QSGKeyNavigationAttachedPrivate), parent), @@ -430,6 +655,21 @@ void QSGKeyNavigationAttached::setBacktab(QSGItem *i) emit backtabChanged(); } +/*! + \qmlproperty enumeration QtQuick2::KeyNavigation::priority + + This property determines whether the keys are processed before + or after the attached item's own key handling. + + \list + \o KeyNavigation.BeforeItem - process the key events before normal + item key processing. If the event is used for key navigation, it will be accepted and will not + be passed on to the item. + \o KeyNavigation.AfterItem (default) - process the key events after normal item key + handling. If the item accepts the key event it will not be + handled by the KeyNavigation attached property handler. + \endlist +*/ QSGKeyNavigationAttached::Priority QSGKeyNavigationAttached::priority() const { return m_processPost ? AfterItem : BeforeItem; @@ -618,6 +858,393 @@ bool QSGKeysAttachedPrivate::isConnected(const char *signalName) return isSignalConnected(signalIndex(signalName)); } +/*! + \qmlclass Keys QSGKeysAttached + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + \brief The Keys attached property provides key handling to Items. + + All visual primitives support key handling via the Keys + attached property. Keys can be handled via the onPressed + and onReleased signal properties. + + 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 hierarchy. + + \section1 Example Usage + + The following example shows how the general onPressed handler can + be used to test for a certain key; in this case, the left cursor + key: + + \snippet doc/src/snippets/declarative/keys/keys-pressed.qml key item + + Some keys may alternatively be handled via specific signal properties, + for example \e onSelectPressed. These handlers automatically set + \e event.accepted to true. + + \snippet doc/src/snippets/declarative/keys/keys-handler.qml key item + + See \l{Qt::Key}{Qt.Key} for the list of keyboard codes. + + \section1 Key Handling Priorities + + The Keys attached property can be configured to handle key events + before or after the item it is attached to. This makes it possible + to intercept events in order to override an item's default behavior, + or act as a fallback for keys not handled by the item. + + If \l priority is Keys.BeforeItem (default) the order of key event processing is: + + \list 1 + \o Items specified in \c forwardTo + \o specific key handlers, e.g. onReturnPressed + \o onKeyPress, onKeyRelease handlers + \o Item specific key handling, e.g. TextInput key handling + \o parent item + \endlist + + If priority is Keys.AfterItem the order of key event processing is: + + \list 1 + \o Item specific key handling, e.g. TextInput key handling + \o Items specified in \c forwardTo + \o specific key handlers, e.g. onReturnPressed + \o onKeyPress, onKeyRelease handlers + \o parent item + \endlist + + If the event is accepted during any of the above steps, key + propagation stops. + + \sa KeyEvent, {KeyNavigation}{KeyNavigation attached property} +*/ + +/*! + \qmlproperty bool QtQuick2::Keys::enabled + + This flags enables key handling if true (default); otherwise + no key handlers will be called. +*/ + +/*! + \qmlproperty enumeration QtQuick2::Keys::priority + + This property determines whether the keys are processed before + or after the attached item's own key handling. + + \list + \o Keys.BeforeItem (default) - process the key events before normal + item key processing. If the event is accepted it will not + be passed on to the item. + \o Keys.AfterItem - process the key events after normal item key + handling. If the item accepts the key event it will not be + handled by the Keys attached property handler. + \endlist +*/ + +/*! + \qmlproperty list<Object> QtQuick2::Keys::forwardTo + + This property provides a way to forward key presses, key releases, and keyboard input + coming from input methods to other items. This can be useful when you want + one item to handle some keys (e.g. the up and down arrow keys), and another item to + handle other keys (e.g. the left and right arrow keys). Once an item that has been + forwarded keys accepts the event it is no longer forwarded to items later in the + list. + + This example forwards key events to two lists: + \qml + Item { + ListView { + id: list1 + // ... + } + ListView { + id: list2 + // ... + } + Keys.forwardTo: [list1, list2] + focus: true + } + \endqml +*/ + +/*! + \qmlsignal QtQuick2::Keys::onPressed(KeyEvent event) + + This handler is called when a key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onReleased(KeyEvent event) + + This handler is called when a key has been released. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit0Pressed(KeyEvent event) + + This handler is called when the digit '0' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit1Pressed(KeyEvent event) + + This handler is called when the digit '1' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit2Pressed(KeyEvent event) + + This handler is called when the digit '2' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit3Pressed(KeyEvent event) + + This handler is called when the digit '3' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit4Pressed(KeyEvent event) + + This handler is called when the digit '4' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit5Pressed(KeyEvent event) + + This handler is called when the digit '5' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit6Pressed(KeyEvent event) + + This handler is called when the digit '6' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit7Pressed(KeyEvent event) + + This handler is called when the digit '7' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit8Pressed(KeyEvent event) + + This handler is called when the digit '8' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDigit9Pressed(KeyEvent event) + + This handler is called when the digit '9' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onLeftPressed(KeyEvent event) + + This handler is called when the Left arrow has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onRightPressed(KeyEvent event) + + This handler is called when the Right arrow has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onUpPressed(KeyEvent event) + + This handler is called when the Up arrow has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDownPressed(KeyEvent event) + + This handler is called when the Down arrow has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onTabPressed(KeyEvent event) + + This handler is called when the Tab key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onBacktabPressed(KeyEvent event) + + This handler is called when the Shift+Tab key combination (Backtab) has + been pressed. The \a event parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onAsteriskPressed(KeyEvent event) + + This handler is called when the Asterisk '*' has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onEscapePressed(KeyEvent event) + + This handler is called when the Escape key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onReturnPressed(KeyEvent event) + + This handler is called when the Return key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onEnterPressed(KeyEvent event) + + This handler is called when the Enter key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onDeletePressed(KeyEvent event) + + This handler is called when the Delete key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onSpacePressed(KeyEvent event) + + This handler is called when the Space key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onBackPressed(KeyEvent event) + + This handler is called when the Back key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onCancelPressed(KeyEvent event) + + This handler is called when the Cancel key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onSelectPressed(KeyEvent event) + + This handler is called when the Select key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onYesPressed(KeyEvent event) + + This handler is called when the Yes key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onNoPressed(KeyEvent event) + + This handler is called when the No key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onContext1Pressed(KeyEvent event) + + This handler is called when the Context1 key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onContext2Pressed(KeyEvent event) + + This handler is called when the Context2 key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onContext3Pressed(KeyEvent event) + + This handler is called when the Context3 key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onContext4Pressed(KeyEvent event) + + This handler is called when the Context4 key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onCallPressed(KeyEvent event) + + This handler is called when the Call key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onHangupPressed(KeyEvent event) + + This handler is called when the Hangup key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onFlipPressed(KeyEvent event) + + This handler is called when the Flip key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onMenuPressed(KeyEvent event) + + This handler is called when the Menu key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onVolumeUpPressed(KeyEvent event) + + This handler is called when the VolumeUp key has been pressed. The \a event + parameter provides information about the event. +*/ + +/*! + \qmlsignal QtQuick2::Keys::onVolumeDownPressed(KeyEvent event) + + This handler is called when the VolumeDown key has been pressed. The \a event + parameter provides information about the event. +*/ + QSGKeysAttached::QSGKeysAttached(QObject *parent) : QObject(*(new QSGKeysAttachedPrivate), parent), QSGItemKeyFilter(qobject_cast<QSGItem*>(parent)) @@ -760,7 +1387,7 @@ QVariant QSGKeysAttached::inputMethodQuery(Qt::InputMethodQuery query) const if (d->item) { for (int ii = 0; ii < d->targets.count(); ++ii) { QSGItem *i = d->targets.at(ii); - if (i && i->isVisible() && (i->flags() & QSGItem::ItemAcceptsInputMethod) && i == d->imeItem) { + if (i && i->isVisible() && (i->flags() & QSGItem::ItemAcceptsInputMethod) && i == d->imeItem) { //### how robust is i == d->imeItem check? QVariant v = i->inputMethodQuery(query); if (v.userType() == QVariant::RectF) @@ -777,6 +1404,69 @@ QSGKeysAttached *QSGKeysAttached::qmlAttachedProperties(QObject *obj) return new QSGKeysAttached(obj); } +/*! + \qmlclass LayoutMirroring QSGLayoutMirroringAttached + \inqmlmodule QtQuick 2 + \ingroup qml-utility-elements + \brief The LayoutMirroring attached property is used to mirror layout behavior. + + The LayoutMirroring attached property is used to horizontally mirror \l {anchor-layout}{Item anchors}, + \l{Using QML Positioner and Repeater Items}{positioner} elements (such as \l Row and \l Grid) + and views (such as \l GridView and horizontal \l ListView). Mirroring is a visual change: left + anchors become right anchors, and positioner elements like \l Grid and \l Row reverse the + horizontal layout of child items. + + Mirroring is enabled for an item by setting the \l enabled property to true. By default, this + only affects the item itself; setting the \l childrenInherit property to true propagates the mirroring + behavior to all child elements as well. If the \c LayoutMirroring attached property has not been defined + for an item, mirroring is not enabled. + + The following example shows mirroring in action. The \l Row below is specified as being anchored + to the left of its parent. However, since mirroring has been enabled, the anchor is horizontally + reversed and it is now anchored to the right. Also, since items in a \l Row are positioned + from left to right by default, they are now positioned from right to left instead, as demonstrated + by the numbering and opacity of the items: + + \snippet doc/src/snippets/declarative/layoutmirroring.qml 0 + + \image layoutmirroring.png + + Layout mirroring is useful when it is necessary to support both left-to-right and right-to-left + layout versions of an application to target different language areas. The \l childrenInherit + property allows layout mirroring to be applied without manually setting layout configurations + for every item in an application. Keep in mind, however, that mirroring does not affect any + positioning that is defined by the \l Item \l {Item::}{x} coordinate value, so even with + mirroring enabled, it will often be necessary to apply some layout fixes to support the + desired layout direction. Also, it may be necessary to disable the mirroring of individual + child items (by setting \l {enabled}{LayoutMirroring.enabled} to false for such items) if + mirroring is not the desired behavior, or if the child item already implements mirroring in + some custom way. + + See \l {QML Right-to-left User Interfaces} for further details on using \c LayoutMirroring and + other related features to implement right-to-left support for an application. +*/ + +/*! + \qmlproperty bool QtQuick2::LayoutMirroring::enabled + + This property holds whether the item's layout is mirrored horizontally. Setting this to true + horizontally reverses \l {anchor-layout}{anchor} settings such that left anchors become right, + and right anchors become left. For \l{Using QML Positioner and Repeater Items}{positioner} elements + (such as \l Row and \l Grid) and view elements (such as \l {GridView}{GridView} and \l {ListView}{ListView}) + this also mirrors the horizontal layout direction of the item. + + The default value is false. +*/ + +/*! + \qmlproperty bool QtQuick2::LayoutMirroring::childrenInherit + + This property holds whether the \l {enabled}{LayoutMirroring.enabled} value for this item + is inherited by its children. + + The default value is false. +*/ + QSGLayoutMirroringAttached::QSGLayoutMirroringAttached(QObject *parent) : QObject(parent), itemPrivate(0) { @@ -881,6 +1571,137 @@ void QSGItemPrivate::setLayoutMirror(bool mirror) } } +/*! + \class QSGItem + \brief The QSGItem class provides the most basic of all visual items in QML. + + All visual items in Qt Declarative inherit from QSGItem. Although QSGItem + has no visual appearance, it defines all the properties that are + common across visual items - such as the x and y position, the + width and height, \l {anchor-layout}{anchoring} and key handling. + + You can subclass QSGItem to provide your own custom visual item that inherits + these features. Note that, because it does not draw anything, QSGItem sets the + QGraphicsItem::ItemHasNoContents flag. If you subclass QSGItem to create a visual + item, you will need to unset this flag. + +*/ + +/*! + \qmlclass Item QSGItem + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The Item is the most basic of all visual items in QML. + + All visual items in Qt Declarative inherit from Item. Although Item + has no visual appearance, it defines all the properties that are + common across visual items - such as the x and y position, the + width and height, \l {anchor-layout}{anchoring} and key handling. + + Item is also useful for grouping items together. + + \qml + Item { + Image { + source: "tile.png" + } + Image { + x: 80 + width: 100 + height: 100 + source: "tile.png" + } + Image { + x: 190 + width: 100 + height: 100 + fillMode: Image.Tile + source: "tile.png" + } + } + \endqml + + + \section1 Key Handling + + Key handling is available to all Item-based visual elements via the \l {Keys}{Keys} + attached property. The \e Keys attached property provides basic handlers such + as \l {Keys::onPressed}{onPressed} and \l {Keys::onReleased}{onReleased}, + as well as handlers for specific keys, such as + \l {Keys::onCancelPressed}{onCancelPressed}. The example below + assigns \l {qmlfocus}{focus} to the item and handles + the Left key via the general \e onPressed handler and the Select key via the + onSelectPressed handler: + + \qml + Item { + focus: true + Keys.onPressed: { + if (event.key == Qt.Key_Left) { + console.log("move left"); + event.accepted = true; + } + } + Keys.onSelectPressed: console.log("Selected"); + } + \endqml + + See the \l {Keys}{Keys} attached property for detailed documentation. + + \section1 Layout Mirroring + + Item layouts can be mirrored using the \l {LayoutMirroring}{LayoutMirroring} attached property. + +*/ + +/*! + \fn void QSGItem::childrenRectChanged(const QRectF &) + \internal +*/ + +/*! + \fn void QSGItem::baselineOffsetChanged(qreal) + \internal +*/ + +/*! + \fn void QSGItem::stateChanged(const QString &state) + \internal +*/ + +/*! + \fn void QSGItem::parentChanged(QSGItem *) + \internal +*/ + +/*! + \fn void QSGItem::smoothChanged(bool) + \internal +*/ + +/*! + \fn void QSGItem::clipChanged(bool) + \internal +*/ + +/*! \fn void QSGItem::transformOriginChanged(TransformOrigin) + \internal +*/ + +/*! + \fn void QSGItem::focusChanged(bool) + \internal +*/ + +/*! + \fn void QSGItem::activeFocusChanged(bool) + \internal +*/ +/*! + \fn QSGItem::QSGItem(QSGItem *parent) + + Constructs a QSGItem with the given \a parent. +*/ QSGItem::QSGItem(QSGItem* parent) : QObject(*(new QSGItemPrivate), parent) { @@ -888,6 +1709,8 @@ QSGItem::QSGItem(QSGItem* parent) d->init(parent); } +/*! \internal +*/ QSGItem::QSGItem(QSGItemPrivate &dd, QSGItem *parent) : QObject(dd, parent) { @@ -895,6 +1718,9 @@ QSGItem::QSGItem(QSGItemPrivate &dd, QSGItem *parent) d->init(parent); } +/*! + Destroys the QSGItem. +*/ QSGItem::~QSGItem() { Q_D(QSGItem); @@ -903,7 +1729,7 @@ QSGItem::~QSGItem() setParentItem(0); while (!d->childItems.isEmpty()) d->childItems.first()->setParentItem(0); - + for (int ii = 0; ii < d->changeListeners.count(); ++ii) { QSGAnchorsPrivate *anchor = d->changeListeners.at(ii).listener->anchorPrivate(); if (anchor) @@ -916,7 +1742,7 @@ QSGItem::~QSGItem() if (anchor && anchor->item && anchor->item->parent() != this) //child will be deleted anyway anchor->updateOnComplete(); } - + for (int ii = 0; ii < d->changeListeners.count(); ++ii) { const QSGItemPrivate::ChangeListener &change = d->changeListeners.at(ii); if (change.types & QSGItemPrivate::Destroyed) @@ -929,6 +1755,38 @@ QSGItem::~QSGItem() delete d->_contents; d->_contents = 0; } +/*! + \qmlproperty enumeration QtQuick2::Item::transformOrigin + This property holds the origin point around which scale and rotation transform. + + Nine transform origins are available, as shown in the image below. + + \image declarative-transformorigin.png + + This example rotates an image around its bottom-right corner. + \qml + Image { + source: "myimage.png" + transformOrigin: Item.BottomRight + rotation: 45 + } + \endqml + + The default transform origin is \c Item.Center. + + To set an arbitrary transform origin point use the \l Scale or \l Rotation + transform elements. +*/ + +/*! + \qmlproperty Item QtQuick2::Item::parent + This property holds the parent of the item. +*/ + +/*! + \property QSGItem::parent + This property holds the parent of the item. +*/ void QSGItem::setParentItem(QSGItem *parentItem) { Q_D(QSGItem); @@ -953,10 +1811,10 @@ void QSGItem::setParentItem(QSGItem *parentItem) scopeItem = oldParentItem; while (!scopeItem->isFocusScope()) scopeItem = scopeItem->parentItem(); scopeFocusedItem = d->subFocusItem; - } + } - if (scopeFocusedItem) - QSGCanvasPrivate::get(d->canvas)->clearFocusInScope(scopeItem, scopeFocusedItem, + if (scopeFocusedItem) + QSGCanvasPrivate::get(d->canvas)->clearFocusInScope(scopeItem, scopeFocusedItem, QSGCanvasPrivate::DontChangeFocusProperty); op->removeChild(this); @@ -975,7 +1833,7 @@ void QSGItem::setParentItem(QSGItem *parentItem) } d->dirty(QSGItemPrivate::ParentChanged); - + if (d->parentItem) QSGItemPrivate::get(d->parentItem)->addChild(this); @@ -992,7 +1850,7 @@ void QSGItem::setParentItem(QSGItem *parentItem) QSGItemPrivate::get(scopeFocusedItem)->focus = false; emit scopeFocusedItem->focusChanged(false); } else { - QSGCanvasPrivate::get(d->canvas)->setFocusInScope(scopeItem, scopeFocusedItem, + QSGCanvasPrivate::get(d->canvas)->setFocusInScope(scopeItem, scopeFocusedItem, QSGCanvasPrivate::DontChangeFocusProperty); } } @@ -1016,7 +1874,7 @@ void QSGItem::stackBefore(const QSGItem *sibling) int myIndex = parentPrivate->childItems.indexOf(this); int siblingIndex = parentPrivate->childItems.indexOf(const_cast<QSGItem *>(sibling)); - + Q_ASSERT(myIndex != -1 && siblingIndex != -1); if (myIndex == siblingIndex - 1) @@ -1030,7 +1888,7 @@ void QSGItem::stackBefore(const QSGItem *sibling) parentPrivate->dirty(QSGItemPrivate::ChildrenStackingChanged); - for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii) + for (int ii = qMin(siblingIndex, myIndex); ii < parentPrivate->childItems.count(); ++ii) QSGItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged(); } @@ -1046,7 +1904,7 @@ void QSGItem::stackAfter(const QSGItem *sibling) int myIndex = parentPrivate->childItems.indexOf(this); int siblingIndex = parentPrivate->childItems.indexOf(const_cast<QSGItem *>(sibling)); - + Q_ASSERT(myIndex != -1 && siblingIndex != -1); if (myIndex == siblingIndex + 1) @@ -1060,7 +1918,7 @@ void QSGItem::stackAfter(const QSGItem *sibling) parentPrivate->dirty(QSGItemPrivate::ChildrenStackingChanged); - for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii) + for (int ii = qMin(myIndex, siblingIndex + 1); ii < parentPrivate->childItems.count(); ++ii) QSGItemPrivate::get(parentPrivate->childItems.at(ii))->siblingOrderChanged(); } @@ -1078,8 +1936,8 @@ QSGEngine *QSGItem::sceneGraphEngine() const return canvas()->sceneGraphEngine(); } -QSGCanvas *QSGItem::canvas() const -{ +QSGCanvas *QSGItem::canvas() const +{ Q_D(const QSGItem); return d->canvas; } @@ -1129,13 +1987,13 @@ void QSGItemPrivate::removeChild(QSGItem *child) emit q->childrenChanged(); } -void QSGItemPrivate::InitializationState::clear() -{ - focusScope = 0; +void QSGItemPrivate::InitializationState::clear() +{ + focusScope = 0; } -void QSGItemPrivate::InitializationState::clear(QSGItem *fs) -{ +void QSGItemPrivate::InitializationState::clear(QSGItem *fs) +{ focusScope = fs; } @@ -1167,7 +2025,7 @@ void QSGItemPrivate::initCanvas(InitializationState *state, QSGCanvas *c) canvas = c; - if (canvas && polishScheduled) + if (canvas && polishScheduled) QSGCanvasPrivate::get(canvas)->itemsToPolish.insert(q); if (canvas && hoverEnabled && !canvas->hasMouseTracking()) @@ -1254,6 +2112,55 @@ void QSGItemPrivate::itemToParentTransform(QTransform &t) const } } + +/*! + \qmlproperty real QtQuick2::Item::childrenRect.x + \qmlproperty real QtQuick2::Item::childrenRect.y + \qmlproperty real QtQuick2::Item::childrenRect.width + \qmlproperty real QtQuick2::Item::childrenRect.height + + The childrenRect properties allow an item access to the geometry of its + children. This property is useful if you have an item that needs to be + sized to fit its children. +*/ + + +/*! + \qmlproperty list<Item> QtQuick2::Item::children + \qmlproperty list<Object> QtQuick2::Item::resources + + The children property contains the list of visual children of this item. + The resources property contains non-visual resources that you want to + reference by name. + + Generally you can rely on Item's default property to handle all this for + you, but it can come in handy in some cases. + + \qml + Item { + children: [ + Text {}, + Rectangle {} + ] + resources: [ + Component { + id: myComponent + Text {} + } + ] + } + \endqml +*/ + +/*! + Returns true if construction of the QML component is complete; otherwise + returns false. + + It is often desirable to delay some processing until the component is + completed. + + \sa componentComplete() +*/ bool QSGItem::isComponentComplete() const { Q_D(const QSGItem); @@ -1261,11 +2168,11 @@ bool QSGItem::isComponentComplete() const } QSGItemPrivate::QSGItemPrivate() -: _anchors(0), _contents(0), baselineOffset(0), _anchorLines(0), _stateGroup(0), origin(QSGItem::Center), - - flags(0), widthValid(false), heightValid(false), componentComplete(true), +: _anchors(0), _contents(0), baselineOffset(0), _anchorLines(0), _stateGroup(0), origin(QSGItem::Center), + + flags(0), widthValid(false), heightValid(false), componentComplete(true), keepMouse(false), hoverEnabled(false), smooth(false), focus(false), activeFocus(false), notifiedFocus(false), - notifiedActiveFocus(false), filtersChildMouseEvents(false), explicitVisible(true), + notifiedActiveFocus(false), filtersChildMouseEvents(false), explicitVisible(true), effectiveVisible(true), explicitEnable(true), effectiveEnable(true), polishScheduled(false), inheritedLayoutMirror(false), effectiveLayoutMirror(false), isMirrorImplicit(true), inheritMirrorFromParent(false), inheritMirrorFromItem(false), childrenDoNotOverlap(false), @@ -1274,12 +2181,12 @@ QSGItemPrivate::QSGItemPrivate() subFocusItem(0), - x(0), y(0), width(0), height(0), implicitWidth(0), implicitHeight(0), + x(0), y(0), width(0), height(0), implicitWidth(0), implicitHeight(0), z(0), scale(1), rotation(0), opacity(1), attachedLayoutDirection(0), acceptedMouseButtons(0), imHints(Qt::ImhNone), - + keyHandler(0), dirtyAttributes(0), nextDirtyItem(0), prevDirtyItem(0), @@ -1311,7 +2218,7 @@ void QSGItemPrivate::data_append(QDeclarativeListProperty<QObject> *prop, QObjec // This test is measurably (albeit only slightly) faster than qobject_cast<>() const QMetaObject *mo = o->metaObject(); while (mo && mo != &QSGItem::staticMetaObject) { - if (mo == &QGraphicsObject::staticMetaObject) + if (mo == &QGraphicsObject::staticMetaObject) qWarning("Cannot add a QtQuick 1.0 item (%s) into a QtQuick 2.0 scene!", o->metaObject()->className()); mo = mo->d.superdata; } @@ -1325,6 +2232,40 @@ void QSGItemPrivate::data_append(QDeclarativeListProperty<QObject> *prop, QObjec } } +/*! + \qmlproperty list<Object> QtQuick2::Item::data + \default + + The data property allows you to freely mix visual children and resources + in an item. If you assign a visual item to the data list it becomes + a child and if you assign any other object type, it is added as a resource. + + So you can write: + \qml + Item { + Text {} + Rectangle {} + Timer {} + } + \endqml + + instead of: + \qml + Item { + children: [ + Text {}, + Rectangle {} + ] + resources: [ + Timer {} + ] + } + \endqml + + data is a behind-the-scenes property: you should never need to explicitly + specify it. + */ + int QSGItemPrivate::data_count(QDeclarativeListProperty<QObject> *prop) { Q_UNUSED(prop); @@ -1489,6 +2430,227 @@ void QSGItemPrivate::transform_clear(QDeclarativeListProperty<QSGTransform> *pro p->dirty(QSGItemPrivate::Transform); } +/*! + \property QSGItem::childrenRect + \brief The geometry of an item's children. + + This property holds the (collective) position and size of the item's children. +*/ + +/*! + \qmlproperty real QtQuick2::Item::x + \qmlproperty real QtQuick2::Item::y + \qmlproperty real QtQuick2::Item::width + \qmlproperty real QtQuick2::Item::height + + Defines the item's position and size relative to its parent. + + \qml + Item { x: 100; y: 100; width: 100; height: 100 } + \endqml + */ + +/*! + \qmlproperty real QtQuick2::Item::z + + Sets the stacking order of sibling items. By default the stacking order is 0. + + Items with a higher stacking value are drawn on top of siblings with a + lower stacking order. Items with the same stacking value are drawn + bottom up in the order they appear. Items with a negative stacking + value are drawn under their parent's content. + + The following example shows the various effects of stacking order. + + \table + \row + \o \image declarative-item_stacking1.png + \o Same \c z - later children above earlier children: + \qml + Item { + Rectangle { + color: "red" + width: 100; height: 100 + } + Rectangle { + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + \endqml + \row + \o \image declarative-item_stacking2.png + \o Higher \c z on top: + \qml + Item { + Rectangle { + z: 1 + color: "red" + width: 100; height: 100 + } + Rectangle { + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + \endqml + \row + \o \image declarative-item_stacking3.png + \o Same \c z - children above parents: + \qml + Item { + Rectangle { + color: "red" + width: 100; height: 100 + Rectangle { + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + } + \endqml + \row + \o \image declarative-item_stacking4.png + \o Lower \c z below: + \qml + Item { + Rectangle { + color: "red" + width: 100; height: 100 + Rectangle { + z: -1 + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + } + \endqml + \endtable + */ + +/*! + \qmlproperty bool QtQuick2::Item::visible + + This property holds whether the item is visible. By default this is true. + + Setting this property directly affects the \c visible value of child + items. When set to \c false, the \c visible values of all child items also + become \c false. When set to \c true, the \c visible values of child items + are returned to \c true, unless they have explicitly been set to \c false. + + (Because of this flow-on behavior, using the \c visible property may not + have the intended effect if a property binding should only respond to + explicit property changes. In such cases it may be better to use the + \l opacity property instead.) + + Setting this property to \c false automatically causes \l focus to be set + to \c false, and this item will longer receive mouse and keyboard events. + (In contrast, setting the \l opacity to 0 does not affect the \l focus + property and the receiving of key events.) + + \note This property's value is only affected by changes to this property or + the parent's \c visible property. It does not change, for example, if this + item moves off-screen, or if the \l opacity changes to 0. +*/ + + +/*! + \qmlproperty AnchorLine QtQuick2::Item::anchors.top + \qmlproperty AnchorLine QtQuick2::Item::anchors.bottom + \qmlproperty AnchorLine QtQuick2::Item::anchors.left + \qmlproperty AnchorLine QtQuick2::Item::anchors.right + \qmlproperty AnchorLine QtQuick2::Item::anchors.horizontalCenter + \qmlproperty AnchorLine QtQuick2::Item::anchors.verticalCenter + \qmlproperty AnchorLine QtQuick2::Item::anchors.baseline + + \qmlproperty Item QtQuick2::Item::anchors.fill + \qmlproperty Item QtQuick2::Item::anchors.centerIn + + \qmlproperty real QtQuick2::Item::anchors.margins + \qmlproperty real QtQuick2::Item::anchors.topMargin + \qmlproperty real QtQuick2::Item::anchors.bottomMargin + \qmlproperty real QtQuick2::Item::anchors.leftMargin + \qmlproperty real QtQuick2::Item::anchors.rightMargin + \qmlproperty real QtQuick2::Item::anchors.horizontalCenterOffset + \qmlproperty real QtQuick2::Item::anchors.verticalCenterOffset + \qmlproperty real QtQuick2::Item::anchors.baselineOffset + + \qmlproperty bool QtQuick2::Item::anchors.mirrored + + Anchors provide a way to position an item by specifying its + relationship with other items. + + Margins apply to top, bottom, left, right, and fill anchors. + The \c anchors.margins property can be used to set all of the various margins at once, to the same value. + Note that margins are anchor-specific and are not applied if an item does not + use anchors. + + Offsets apply for horizontal center, vertical center, and baseline anchors. + + \table + \row + \o \image declarative-anchors_example.png + \o Text anchored to Image, horizontally centered and vertically below, with a margin. + \qml + Item { + Image { + id: pic + // ... + } + Text { + id: label + anchors.horizontalCenter: pic.horizontalCenter + anchors.top: pic.bottom + anchors.topMargin: 5 + // ... + } + } + \endqml + \row + \o \image declarative-anchors_example2.png + \o + Left of Text anchored to right of Image, with a margin. The y + property of both defaults to 0. + + \qml + Item { + Image { + id: pic + // ... + } + Text { + id: label + anchors.left: pic.right + anchors.leftMargin: 5 + // ... + } + } + \endqml + \endtable + + \c anchors.fill provides a convenient way for one item to have the + same geometry as another item, and is equivalent to connecting all + four directional anchors. + + To clear an anchor value, set it to \c undefined. + + \c anchors.mirrored returns true it the layout has been \l {LayoutMirroring}{mirrored}. + + \note You can only anchor an item to siblings or a parent. + + For more information see \l {anchor-layout}{Anchor Layouts}. +*/ + +/*! + \property QSGItem::baselineOffset + \brief The position of the item's baseline in local coordinates. + + The baseline of a \l Text item is the imaginary line on which the text + sits. Controls containing text usually set their baseline to the + baseline of their text. + + For non-text items, a default baseline offset of 0 is used. +*/ QSGAnchors *QSGItemPrivate::anchors() const { if (!_anchors) { @@ -1500,7 +2662,7 @@ QSGAnchors *QSGItemPrivate::anchors() const return _anchors; } -QSGItemPrivate::AnchorLines *QSGItemPrivate::anchorLines() const +QSGItemPrivate::AnchorLines *QSGItemPrivate::anchorLines() const { Q_Q(const QSGItem); if (!_anchorLines) _anchorLines = @@ -1559,6 +2721,12 @@ void QSGItem::setClip(bool c) emit clipChanged(c); } + +/*! + This function is called to handle this item's changes in + geometry from \a oldGeometry to \a newGeometry. If the two + geometries are the same, it doesn't do anything. + */ void QSGItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry) { Q_D(QSGItem); @@ -1881,7 +3049,7 @@ QTransform QSGItem::itemTransform(QSGItem *other, bool *ok) const { Q_D(const QSGItem); - // XXX todo - we need to be able to handle common parents better and detect + // XXX todo - we need to be able to handle common parents better and detect // invalid cases if (ok) *ok = true; @@ -1927,7 +3095,7 @@ void QSGItem::forceActiveFocus() while (parent) { if (parent->flags() & QSGItem::ItemIsFocusScope) { parent->setFocus(true); - } + } parent = parent->parentItem(); } } @@ -1957,11 +3125,11 @@ QDeclarativeListProperty<QObject> QSGItemPrivate::resources() QDeclarativeListProperty<QSGItem> QSGItemPrivate::children() { - return QDeclarativeListProperty<QSGItem>(q_func(), 0, QSGItemPrivate::children_append, + return QDeclarativeListProperty<QSGItem>(q_func(), 0, QSGItemPrivate::children_append, QSGItemPrivate::children_count, QSGItemPrivate::children_at, QSGItemPrivate::children_clear); - + } QDeclarativeListProperty<QDeclarativeState> QSGItemPrivate::states() @@ -2084,7 +3252,7 @@ void QSGItemPrivate::transformChanged() void QSGItemPrivate::deliverKeyEvent(QKeyEvent *e) { Q_Q(QSGItem); - + Q_ASSERT(e->isAccepted()); if (keyHandler) { if (e->type() == QEvent::KeyPress) @@ -2252,7 +3420,7 @@ QSGItem::TransformOrigin QSGItem::transformOrigin() const void QSGItem::setTransformOrigin(TransformOrigin origin) { Q_D(QSGItem); - if (origin == d->origin) + if (origin == d->origin) return; d->origin = origin; @@ -2282,19 +3450,146 @@ void QSGItem::setZ(qreal v) d->z = v; d->dirty(QSGItemPrivate::ZValue); - if (d->parentItem) + if (d->parentItem) QSGItemPrivate::get(d->parentItem)->dirty(QSGItemPrivate::ChildrenStackingChanged); emit zChanged(); } -qreal QSGItem::rotation() const -{ + +/*! + \qmlproperty real QtQuick2::Item::rotation + This property holds the rotation of the item in degrees clockwise. + + This specifies how many degrees to rotate the item around its transformOrigin. + The default rotation is 0 degrees (i.e. not rotated at all). + + \table + \row + \o \image declarative-rotation.png + \o + \qml + Rectangle { + color: "blue" + width: 100; height: 100 + Rectangle { + color: "red" + x: 25; y: 25; width: 50; height: 50 + rotation: 30 + } + } + \endqml + \endtable + + \sa transform, Rotation +*/ + +/*! + \qmlproperty real QtQuick2::Item::scale + This property holds the scale of the item. + + A scale of less than 1 means the item will be displayed smaller than + normal, and a scale of greater than 1 means the item will be + displayed larger than normal. A negative scale means the item will + be mirrored. + + By default, items are displayed at a scale of 1 (i.e. at their + normal size). + + Scaling is from the item's transformOrigin. + + \table + \row + \o \image declarative-scale.png + \o + \qml + Rectangle { + color: "blue" + width: 100; height: 100 + Rectangle { + color: "green" + width: 25; height: 25 + } + Rectangle { + color: "red" + x: 25; y: 25; width: 50; height: 50 + scale: 1.4 + } + } + \endqml + \endtable + + \sa transform, Scale +*/ + +/*! + \qmlproperty real QtQuick2::Item::opacity + + This property holds the opacity of the item. Opacity is specified as a + number between 0 (fully transparent) and 1 (fully opaque). The default is 1. + + When this property is set, the specified opacity is also applied + individually to child items. In almost all cases this is what you want, + but in some cases it may produce undesired results. For example in the + second set of rectangles below, the red rectangle has specified an opacity + of 0.5, which affects the opacity of its blue child rectangle even though + the child has not specified an opacity. + + \table + \row + \o \image declarative-item_opacity1.png + \o + \qml + Item { + Rectangle { + color: "red" + width: 100; height: 100 + Rectangle { + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + } + \endqml + \row + \o \image declarative-item_opacity2.png + \o + \qml + Item { + Rectangle { + opacity: 0.5 + color: "red" + width: 100; height: 100 + Rectangle { + color: "blue" + x: 50; y: 50; width: 100; height: 100 + } + } + } + \endqml + \endtable + + If an item's opacity is set to 0, the item will no longer receive mouse + events, but will continue to receive key events and will retain the keyboard + \l focus if it has been set. (In contrast, setting the \l visible property + to \c false stops both mouse and keyboard events, and also removes focus + from the item.) +*/ + +/*! + Returns a value indicating whether mouse input should + remain with this item exclusively. + + \sa setKeepMouseGrab() + */ + +qreal QSGItem::rotation() const +{ Q_D(const QSGItem); return d->rotation; } -void QSGItem::setRotation(qreal r) +void QSGItem::setRotation(qreal r) { Q_D(QSGItem); if (d->rotation == r) @@ -2309,13 +3604,13 @@ void QSGItem::setRotation(qreal r) emit rotationChanged(); } -qreal QSGItem::scale() const -{ +qreal QSGItem::scale() const +{ Q_D(const QSGItem); return d->scale; } -void QSGItem::setScale(qreal s) +void QSGItem::setScale(qreal s) { Q_D(QSGItem); if (d->scale == s) @@ -2341,7 +3636,7 @@ void QSGItem::setOpacity(qreal o) return; d->opacity = o; - + d->dirty(QSGItemPrivate::OpacityValue); d->itemChange(ItemOpacityHasChanged, o); @@ -2415,7 +3710,7 @@ void QSGItemPrivate::setEffectiveVisibleRecur(bool newEffectiveVisible) q->ungrabMouse(); } - for (int ii = 0; ii < childItems.count(); ++ii) + for (int ii = 0; ii < childItems.count(); ++ii) QSGItemPrivate::get(childItems.at(ii))->setEffectiveVisibleRecur(newEffectiveVisible); for(int ii = 0; ii < changeListeners.count(); ++ii) { @@ -2459,7 +3754,7 @@ void QSGItemPrivate::setEffectiveEnableRecur(bool newEffectiveEnable) q->ungrabMouse(); } - for (int ii = 0; ii < childItems.count(); ++ii) + for (int ii = 0; ii < childItems.count(); ++ii) QSGItemPrivate::get(childItems.at(ii))->setEffectiveEnableRecur(newEffectiveEnable); emit q->enabledChanged(); @@ -2640,12 +3935,37 @@ void QSGItemPrivate::itemChange(QSGItem::ItemChange change, const QSGItem::ItemC } } +/*! + \property QSGItem::smooth + \brief whether the item is smoothly transformed. + + This property is provided purely for the purpose of optimization. Turning + smooth transforms off is faster, but looks worse; turning smooth + transformations on is slower, but looks better. + + By default smooth transformations are off. +*/ + +/*! + Returns true if the item should be drawn with antialiasing and + smooth pixmap filtering, false otherwise. + + The default is false. + + \sa setSmooth() +*/ bool QSGItem::smooth() const { Q_D(const QSGItem); return d->smooth; } +/*! + Sets whether the item should be drawn with antialiasing and + smooth pixmap filtering to \a smooth. + + \sa smooth() +*/ void QSGItem::setSmooth(bool smooth) { Q_D(QSGItem); @@ -2658,14 +3978,14 @@ void QSGItem::setSmooth(bool smooth) emit smoothChanged(smooth); } -QSGItem::Flags QSGItem::flags() const -{ +QSGItem::Flags QSGItem::flags() const +{ Q_D(const QSGItem); return (QSGItem::Flags)d->flags; } void QSGItem::setFlag(Flag flag, bool enabled) -{ +{ Q_D(QSGItem); if (enabled) setFlags((Flags)(d->flags | (quint32)flag)); @@ -2673,8 +3993,8 @@ void QSGItem::setFlag(Flag flag, bool enabled) setFlags((Flags)(d->flags & ~(quint32)flag)); } -void QSGItem::setFlags(Flags flags) -{ +void QSGItem::setFlags(Flags flags) +{ Q_D(QSGItem); if ((flags & ItemIsFocusScope) != (d->flags & ItemIsFocusScope)) { @@ -2684,10 +4004,10 @@ void QSGItem::setFlags(Flags flags) } else if (d->flags & ItemIsFocusScope) { qWarning("QSGItem: Cannot unset FocusScope flag."); flags |= ItemIsFocusScope; - } + } } - if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape)) + if ((flags & ItemClipsChildrenToShape ) != (d->flags & ItemClipsChildrenToShape)) d->dirty(QSGItemPrivate::Clip); d->flags = flags; @@ -2801,13 +4121,54 @@ qreal QSGItemPrivate::getImplicitWidth() const { return implicitWidth; } - +/*! + Returns the width of the item that is implied by other properties that determine the content. +*/ qreal QSGItem::implicitWidth() const { Q_D(const QSGItem); return d->getImplicitWidth(); } +/*! + \qmlproperty real QtQuick2::Item::implicitWidth + \qmlproperty real QtQuick2::Item::implicitHeight + + Defines the natural width or height of the Item if no \l width or \l height is specified. + + The default implicit size for most items is 0x0, however some elements have an inherent + implicit size which cannot be overridden, e.g. Image, Text. + + Setting the implicit size is useful for defining components that have a preferred size + based on their content, for example: + + \qml + // Label.qml + import QtQuick 1.1 + + Item { + property alias icon: image.source + property alias label: text.text + implicitWidth: text.implicitWidth + image.implicitWidth + implicitHeight: Math.max(text.implicitHeight, image.implicitHeight) + Image { id: image } + Text { + id: text + wrapMode: Text.Wrap + anchors.left: image.right; anchors.right: parent.right + anchors.verticalCenter: parent.verticalCenter + } + } + \endqml + + \bold Note: using implicitWidth of Text or TextEdit and setting the width explicitly + incurs a performance penalty as the text must be laid out twice. +*/ + +/*! + Sets the implied width of the item to \a w. + This is the width implied by other properties that determine the content. +*/ void QSGItem::setImplicitWidth(qreal w) { Q_D(QSGItem); @@ -2817,11 +4178,11 @@ void QSGItem::setImplicitWidth(qreal w) if (changed) d->implicitWidthChanged(); return; - } + } qreal oldWidth = d->width; d->width = w; - + d->dirty(QSGItemPrivate::Size); geometryChanged(QRectF(x(), y(), width(), height()), @@ -2831,6 +4192,9 @@ void QSGItem::setImplicitWidth(qreal w) d->implicitWidthChanged(); } +/*! + Returns whether the width property has been set explicitly. +*/ bool QSGItem::widthValid() const { Q_D(const QSGItem); @@ -2880,12 +4244,20 @@ qreal QSGItemPrivate::getImplicitHeight() const return implicitHeight; } +/*! + Returns the height of the item that is implied by other properties that determine the content. +*/ qreal QSGItem::implicitHeight() const { Q_D(const QSGItem); return d->getImplicitHeight(); } + +/*! + Sets the implied height of the item to \a h. + This is the height implied by other properties that determine the content. +*/ void QSGItem::setImplicitHeight(qreal h) { Q_D(QSGItem); @@ -2909,6 +4281,9 @@ void QSGItem::setImplicitHeight(qreal h) d->implicitHeightChanged(); } +/*! + Returns whether the height property has been set explicitly. +*/ bool QSGItem::heightValid() const { Q_D(const QSGItem); @@ -2978,19 +4353,19 @@ QSGItem *QSGItem::scopedFocusItem() const Q_D(const QSGItem); if (!isFocusScope()) return 0; - else + else return d->subFocusItem; } -Qt::MouseButtons QSGItem::acceptedMouseButtons() const -{ +Qt::MouseButtons QSGItem::acceptedMouseButtons() const +{ Q_D(const QSGItem); return d->acceptedMouseButtons; } -void QSGItem::setAcceptedMouseButtons(Qt::MouseButtons buttons) -{ +void QSGItem::setAcceptedMouseButtons(Qt::MouseButtons buttons) +{ Q_D(QSGItem); d->acceptedMouseButtons = buttons; } @@ -3001,13 +4376,13 @@ bool QSGItem::filtersChildMouseEvents() const return d->filtersChildMouseEvents; } -void QSGItem::setFiltersChildMouseEvents(bool filter) -{ +void QSGItem::setFiltersChildMouseEvents(bool filter) +{ Q_D(QSGItem); d->filtersChildMouseEvents = filter; } -bool QSGItem::isUnderMouse() const +bool QSGItem::isUnderMouse() const { Q_D(const QSGItem); if (!d->canvas) @@ -3016,17 +4391,17 @@ bool QSGItem::isUnderMouse() const QPoint cursorPos = QCursor::pos(); if (QRectF(0, 0, width(), height()).contains(mapFromScene(d->canvas->mapFromGlobal(cursorPos)))) return true; - return false; + return false; } -bool QSGItem::acceptHoverEvents() const -{ +bool QSGItem::acceptHoverEvents() const +{ Q_D(const QSGItem); return d->hoverEnabled; } -void QSGItem::setAcceptHoverEvents(bool enabled) -{ +void QSGItem::setAcceptHoverEvents(bool enabled) +{ Q_D(QSGItem); d->hoverEnabled = enabled; @@ -3062,7 +4437,7 @@ void QSGItem::grabMouse() oldGrabber->mouseUngrabEvent(); } -void QSGItem::ungrabMouse() +void QSGItem::ungrabMouse() { Q_D(QSGItem); if (!d->canvas) @@ -3083,22 +4458,60 @@ bool QSGItem::keepMouseGrab() const return d->keepMouse; } +/*! + The flag indicating whether the mouse should remain + with this item is set to \a keep. + + This is useful for items that wish to grab and keep mouse + interaction following a predefined gesture. For example, + an item that is interested in horizontal mouse movement + may set keepMouseGrab to true once a threshold has been + exceeded. Once keepMouseGrab has been set to true, filtering + items will not react to mouse events. + + If the item does not indicate that it wishes to retain mouse grab, + a filtering item may steal the grab. For example, Flickable may attempt + to steal a mouse grab if it detects that the user has begun to + move the viewport. + + \sa keepMouseGrab() + */ void QSGItem::setKeepMouseGrab(bool keep) { Q_D(QSGItem); d->keepMouse = keep; } -QPointF QSGItem::mapToItem(const QSGItem *item, const QPointF &point) const -{ +/*! + \qmlmethod object QtQuick2::Item::mapFromItem(Item item, real x, real y) + + Maps the point (\a x, \a y), which is in \a item's coordinate system, to + this item's coordinate system, and returns an object with \c x and \c y + properties matching the mapped cooordinate. + + If \a item is a \c null value, this maps the point from the coordinate + system of the root QML view. +*/ +/*! + \qmlmethod object QtQuick2::Item::mapToItem(Item item, real x, real y) + + Maps the point (\a x, \a y), which is in this item's coordinate system, to + \a item's coordinate system, and returns an object with \c x and \c y + properties matching the mapped cooordinate. + + If \a item is a \c null value, this maps \a x and \a y to the coordinate + system of the root QML view. +*/ +QPointF QSGItem::mapToItem(const QSGItem *item, const QPointF &point) const +{ QPointF p = mapToScene(point); if (item) p = item->mapFromScene(p); return p; } -QPointF QSGItem::mapToScene(const QPointF &point) const -{ +QPointF QSGItem::mapToScene(const QPointF &point) const +{ Q_D(const QSGItem); return d->itemToCanvasTransform().map(point); } @@ -3112,26 +4525,26 @@ QRectF QSGItem::mapRectToItem(const QSGItem *item, const QRectF &rect) const return t.mapRect(rect); } -QRectF QSGItem::mapRectToScene(const QRectF &rect) const -{ +QRectF QSGItem::mapRectToScene(const QRectF &rect) const +{ Q_D(const QSGItem); return d->itemToCanvasTransform().mapRect(rect); } -QPointF QSGItem::mapFromItem(const QSGItem *item, const QPointF &point) const -{ +QPointF QSGItem::mapFromItem(const QSGItem *item, const QPointF &point) const +{ QPointF p = item?item->mapToScene(point):point; return mapFromScene(p); } -QPointF QSGItem::mapFromScene(const QPointF &point) const -{ +QPointF QSGItem::mapFromScene(const QPointF &point) const +{ Q_D(const QSGItem); return d->canvasToItemTransform().map(point); } -QRectF QSGItem::mapRectFromItem(const QSGItem *item, const QRectF &rect) const -{ +QRectF QSGItem::mapRectFromItem(const QSGItem *item, const QRectF &rect) const +{ Q_D(const QSGItem); QTransform t = item?QSGItemPrivate::get(item)->itemToCanvasTransform():QTransform(); t *= d->canvasToItemTransform(); @@ -3144,6 +4557,318 @@ QRectF QSGItem::mapRectFromScene(const QRectF &rect) const return d->canvasToItemTransform().mapRect(rect); } + +/*! + \qmlmethod QtQuick2::Item::forceActiveFocus() + + Forces active focus on the item. + + This method sets focus on the item and makes sure that all the focus scopes + higher in the object hierarchy are also given the focus. +*/ + +/*! + Forces active focus on the item. + + This method sets focus on the item and makes sure that all the focus scopes + higher in the object hierarchy are also given the focus. +*/ + +/*! + \qmlmethod QtQuick2::Item::childAt(real x, real y) + + Returns the visible child item at point (\a x, \a y), which is in this + item's coordinate system, or \c null if there is no such item. +*/ + +/*! + Returns the visible child item at point (\a x, \a y), which is in this + item's coordinate system, or 0 if there is no such item. +*/ + +/*! + \qmlproperty list<State> QtQuick2::Item::states + This property holds a list of states defined by the item. + + \qml + Item { + states: [ + State { + // ... + }, + State { + // ... + } + // ... + ] + } + \endqml + + \sa {qmlstate}{States} +*/ +/*! + \qmlproperty list<Transition> QtQuick2::Item::transitions + This property holds a list of transitions defined by the item. + + \qml + Item { + transitions: [ + Transition { + // ... + }, + Transition { + // ... + } + // ... + ] + } + \endqml + + \sa {QML Animation and Transitions}{Transitions} +*/ +/* + \qmlproperty list<Filter> QtQuick2::Item::filter + This property holds a list of graphical filters to be applied to the item. + + \l {Filter}{Filters} include things like \l {Blur}{blurring} + the item, or giving it a \l Reflection. Some + filters may not be available on all canvases; if a filter is not + available on a certain canvas, it will simply not be applied for + that canvas (but the QML will still be considered valid). + + \qml + Item { + filter: [ + Blur { + // ... + }, + Reflection { + // ... + } + // ... + ] + } + \endqml +*/ + +/*! + \qmlproperty bool QtQuick2::Item::clip + This property holds whether clipping is enabled. The default clip value is \c false. + + If clipping is enabled, an item will clip its own painting, as well + as the painting of its children, to its bounding rectangle. + + Non-rectangular clipping regions are not supported for performance reasons. +*/ + +/*! + \property QSGItem::clip + This property holds whether clipping is enabled. The default clip value is \c false. + + If clipping is enabled, an item will clip its own painting, as well + as the painting of its children, to its bounding rectangle. If you set + clipping during an item's paint operation, remember to re-set it to + prevent clipping the rest of your scene. + + Non-rectangular clipping regions are not supported for performance reasons. +*/ + +/*! + \qmlproperty string QtQuick2::Item::state + + This property holds the name of the current state of the item. + + This property is often used in scripts to change between states. For + example: + + \js + function toggle() { + if (button.state == 'On') + button.state = 'Off'; + else + button.state = 'On'; + } + \endjs + + If the item is in its base state (i.e. no explicit state has been + set), \c state will be a blank string. Likewise, you can return an + item to its base state by setting its current state to \c ''. + + \sa {qmlstates}{States} +*/ + +/*! + \qmlproperty list<Transform> QtQuick2::Item::transform + This property holds the list of transformations to apply. + + For more information see \l Transform. +*/ + +/*! + \enum QSGItem::TransformOrigin + + Controls the point about which simple transforms like scale apply. + + \value TopLeft The top-left corner of the item. + \value Top The center point of the top of the item. + \value TopRight The top-right corner of the item. + \value Left The left most point of the vertical middle. + \value Center The center of the item. + \value Right The right most point of the vertical middle. + \value BottomLeft The bottom-left corner of the item. + \value Bottom The center point of the bottom of the item. + \value BottomRight The bottom-right corner of the item. +*/ + + +/*! + \qmlproperty bool QtQuick2::Item::activeFocus + + This property indicates whether the item has active focus. + + An item with active focus will receive keyboard input, + or is a FocusScope ancestor of the item that will receive keyboard input. + + Usually, activeFocus is gained by setting focus on an item and its enclosing + FocusScopes. In the following example \c input will have activeFocus. + \qml + Rectangle { + FocusScope { + focus: true + TextInput { + id: input + focus: true + } + } + } + \endqml + + \sa focus, {qmlfocus}{Keyboard Focus} +*/ + +/*! + \qmlproperty bool QtQuick2::Item::focus + This property indicates whether the item has focus within the enclosing focus scope. If true, this item + will gain active focus when the enclosing focus scope gains active focus. + In the following example, \c input will be given active focus when \c scope gains active focus. + \qml + Rectangle { + FocusScope { + id: scope + TextInput { + id: input + focus: true + } + } + } + \endqml + + For the purposes of this property, the scene as a whole is assumed to act like a focus scope. + On a practical level, that means the following QML will give active focus to \c input on startup. + + \qml + Rectangle { + TextInput { + id: input + focus: true + } + } + \endqml + + \sa activeFocus, {qmlfocus}{Keyboard Focus} +*/ + + +/*! + \property QSGItem::anchors + \internal +*/ + +/*! + \property QSGItem::left + \internal +*/ + +/*! + \property QSGItem::right + \internal +*/ + +/*! + \property QSGItem::horizontalCenter + \internal +*/ + +/*! + \property QSGItem::top + \internal +*/ + +/*! + \property QSGItem::bottom + \internal +*/ + +/*! + \property QSGItem::verticalCenter + \internal +*/ + +/*! + \property QSGItem::focus + \internal +*/ + +/*! + \property QSGItem::transform + \internal +*/ + +/*! + \property QSGItem::transformOrigin + \internal +*/ + +/*! + \property QSGItem::activeFocus + \internal +*/ + +/*! + \property QSGItem::baseline + \internal +*/ + +/*! + \property QSGItem::data + \internal +*/ + +/*! + \property QSGItem::resources + \internal +*/ + +/*! + \property QSGItem::state + \internal +*/ + +/*! + \property QSGItem::states + \internal +*/ + +/*! + \property QSGItem::transformOriginPoint + \internal +*/ + +/*! + \property QSGItem::transitions + \internal +*/ + bool QSGItem::event(QEvent *ev) { return QObject::event(ev); diff --git a/src/declarative/items/qsglistview.cpp b/src/declarative/items/qsglistview.cpp index c3466be4a8..11828fc59e 100644 --- a/src/declarative/items/qsglistview.cpp +++ b/src/declarative/items/qsglistview.cpp @@ -1265,6 +1265,68 @@ void QSGListViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExtent, //---------------------------------------------------------------------------- +/*! + \qmlclass ListView QSGListView + \inqmlmodule QtQuick 2 + \ingroup qml-view-elements + \inherits Flickable + \brief The ListView item provides a list view of items provided by a model. + + A ListView displays data from models created from built-in QML elements like ListModel + and XmlListModel, or custom model classes defined in C++ that inherit from + QAbstractListModel. + + A ListView has a \l model, which defines the data to be displayed, and + a \l delegate, which defines how the data should be displayed. Items in a + ListView are laid out horizontally or vertically. List views are inherently + flickable because ListView inherits from \l Flickable. + + \section1 Example Usage + + The following example shows the definition of a simple list model defined + in a file called \c ContactModel.qml: + + \snippet doc/src/snippets/declarative/listview/ContactModel.qml 0 + + Another component can display this model data in a ListView, like this: + + \snippet doc/src/snippets/declarative/listview/listview.qml import + \codeline + \snippet doc/src/snippets/declarative/listview/listview.qml classdocs simple + + \image listview-simple.png + + Here, the ListView creates a \c ContactModel component for its model, and a \l Text element + for its delegate. The view will create a new \l Text component for each item in the model. Notice + the delegate is able to access the model's \c name and \c number data directly. + + An improved list view is shown below. The delegate is visually improved and is moved + into a separate \c contactDelegate component. + + \snippet doc/src/snippets/declarative/listview/listview.qml classdocs advanced + \image listview-highlight.png + + The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property, + and \c focus is set to \c true to enable keyboard navigation for the list view. + The list view itself is a focus scope (see \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} for more details). + + Delegates are instantiated as needed and may be destroyed at any time. + State should \e never be stored in a delegate. + + ListView attaches a number of properties to the root item of the delegate, for example + \c {ListView.isCurrentItem}. In the following example, the root delegate item can access + this attached property directly as \c ListView.isCurrentItem, while the child + \c contactInfo object must refer to this property as \c wrapper.ListView.isCurrentItem. + + \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem + + \note Views do not enable \e clip automatically. If the view + is not clipped by another item or the screen, it will be necessary + to set \e {clip: true} in order to have the out of view items clipped + nicely. + + \sa {QML Data Models}, GridView, {declarative/modelviews/listview}{ListView examples} +*/ QSGListView::QSGListView(QSGItem *parent) : QSGItemView(*(new QSGListViewPrivate), parent) { @@ -1274,6 +1336,203 @@ QSGListView::~QSGListView() { } +/*! + \qmlattachedproperty bool ListView::isCurrentItem + This attached property is true if this delegate is the current item; otherwise false. + + It is attached to each instance of the delegate. + + This property may be used to adjust the appearance of the current item, for example: + + \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem +*/ + +/*! + \qmlattachedproperty ListView ListView::view + This attached property holds the view that manages this delegate instance. + + It is attached to each instance of the delegate. +*/ + +/*! + \qmlattachedproperty string ListView::previousSection + This attached property holds the section of the previous element. + + It is attached to each instance of the delegate. + + The section is evaluated using the \l {ListView::section.property}{section} properties. +*/ + +/*! + \qmlattachedproperty string ListView::nextSection + This attached property holds the section of the next element. + + It is attached to each instance of the delegate. + + The section is evaluated using the \l {ListView::section.property}{section} properties. +*/ + +/*! + \qmlattachedproperty string ListView::section + This attached property holds the section of this element. + + It is attached to each instance of the delegate. + + The section is evaluated using the \l {ListView::section.property}{section} properties. +*/ + +/*! + \qmlattachedproperty bool ListView::delayRemove + This attached property holds whether the delegate may be destroyed. + + It is attached to each instance of the delegate. + + It is sometimes necessary to delay the destruction of an item + until an animation completes. + + The example delegate below ensures that the animation completes before + the item is removed from the list. + + \snippet doc/src/snippets/declarative/listview/listview.qml delayRemove +*/ + +/*! + \qmlattachedsignal QtQuick2::ListView::onAdd() + This attached handler is called immediately after an item is added to the view. +*/ + +/*! + \qmlattachedsignal QtQuick2::ListView::onRemove() + This attached handler is called immediately before an item is removed from the view. +*/ + +/*! + \qmlproperty model QtQuick2::ListView::model + This property holds the model providing data for the list. + + The model provides the set of data that is used to create the items + in the view. Models can be created directly in QML using \l ListModel, \l XmlListModel + or \l VisualItemModel, or provided by C++ model classes. If a C++ model class is + used, it must be a subclass of \l QAbstractItemModel or a simple list. + + \sa {qmlmodels}{Data Models} +*/ + +/*! + \qmlproperty Component QtQuick2::ListView::delegate + + The delegate provides a template defining each item instantiated by the view. + The index is exposed as an accessible \c index property. Properties of the + model are also available depending upon the type of \l {qmlmodels}{Data Model}. + + The number of elements in the delegate has a direct effect on the + flicking performance of the view. If at all possible, place functionality + that is not needed for the normal display of the delegate in a \l Loader which + can load additional elements when needed. + + The ListView will lay out the items based on the size of the root item + in the delegate. + + It is recommended that the delagate's size be a whole number to avoid sub-pixel + alignment of items. + + \note Delegates are instantiated as needed and may be destroyed at any time. + State should \e never be stored in a delegate. +*/ +/*! + \qmlproperty int QtQuick2::ListView::currentIndex + \qmlproperty Item QtQuick2::ListView::currentItem + + The \c currentIndex property holds the index of the current item, and + \c currentItem holds the current item. Setting the currentIndex to -1 + will clear the highlight and set currentItem to null. + + If highlightFollowsCurrentItem is \c true, setting either of these + properties will smoothly scroll the ListView so that the current + item becomes visible. + + Note that the position of the current item + may only be approximate until it becomes visible in the view. +*/ + +/*! + \qmlproperty Item QtQuick2::ListView::highlightItem + + This holds the highlight item created from the \l highlight component. + + The \c highlightItem is managed by the view unless + \l highlightFollowsCurrentItem is set to false. + + \sa highlight, highlightFollowsCurrentItem +*/ + +/*! + \qmlproperty int QtQuick2::ListView::count + This property holds the number of items in the view. +*/ + +/*! + \qmlproperty Component QtQuick2::ListView::highlight + This property holds the component to use as the highlight. + + An instance of the highlight component is created for each list. + The geometry of the resulting component instance is managed by the list + so as to stay with the current item, unless the highlightFollowsCurrentItem + property is false. + + \sa highlightItem, highlightFollowsCurrentItem, {declarative/modelviews/listview}{ListView examples} +*/ + +/*! + \qmlproperty bool QtQuick2::ListView::highlightFollowsCurrentItem + This property holds whether the highlight is managed by the view. + + If this property is true (the default value), the highlight is moved smoothly + to follow the current item. Otherwise, the + highlight is not moved by the view, and any movement must be implemented + by the highlight. + + Here is a highlight with its motion defined by a \l {SpringAnimation} item: + + \snippet doc/src/snippets/declarative/listview/listview.qml highlightFollowsCurrentItem + + Note that the highlight animation also affects the way that the view + is scrolled. This is because the view moves to maintain the + highlight within the preferred highlight range (or visible viewport). + + \sa highlight, highlightMoveSpeed +*/ +//###Possibly rename these properties, since they are very useful even without a highlight? +/*! + \qmlproperty real QtQuick2::ListView::preferredHighlightBegin + \qmlproperty real QtQuick2::ListView::preferredHighlightEnd + \qmlproperty enumeration QtQuick2::ListView::highlightRangeMode + + These properties define the preferred range of the highlight (for the current item) + within the view. The \c preferredHighlightBegin value must be less than the + \c preferredHighlightEnd value. + + These properties affect the position of the current item when the list is scrolled. + For example, if the currently selected item should stay in the middle of the + list when the view is scrolled, set the \c preferredHighlightBegin and + \c preferredHighlightEnd values to the top and bottom coordinates of where the middle + item would be. If the \c currentItem is changed programmatically, the list will + automatically scroll so that the current item is in the middle of the view. + Furthermore, the behavior of the current item index will occur whether or not a + highlight exists. + + Valid values for \c highlightRangeMode are: + + \list + \o ListView.ApplyRange - the view attempts to maintain the highlight within the range. + However, the highlight can move outside of the range at the ends of the list or due + to mouse interaction. + \o ListView.StrictlyEnforceRange - the highlight never moves outside of the range. + The current item changes if a keyboard or mouse action would cause the highlight to move + outside of the range. + \o ListView.NoHighlightRange - this is the default value. + \endlist +*/ void QSGListView::setHighlightFollowsCurrentItem(bool autoHighlight) { Q_D(QSGListView); @@ -1288,6 +1547,13 @@ void QSGListView::setHighlightFollowsCurrentItem(bool autoHighlight) } } +/*! + \qmlproperty real QtQuick2::ListView::spacing + + This property holds the spacing between items. + + The default value is 0. +*/ qreal QSGListView::spacing() const { Q_D(const QSGListView); @@ -1304,6 +1570,27 @@ void QSGListView::setSpacing(qreal spacing) } } +/*! + \qmlproperty enumeration QtQuick2::ListView::orientation + This property holds the orientation of the list. + + Possible values: + + \list + \o ListView.Horizontal - Items are laid out horizontally + \o ListView.Vertical (default) - Items are laid out vertically + \endlist + + \table + \row + \o Horizontal orientation: + \image ListViewHorizontal.png + + \row + \o Vertical orientation: + \image listview-highlight.png + \endtable +*/ QSGListView::Orientation QSGListView::orientation() const { Q_D(const QSGListView); @@ -1329,6 +1616,116 @@ void QSGListView::setOrientation(QSGListView::Orientation orientation) } } +/*! + \qmlproperty enumeration QtQuick2::ListView::layoutDirection + This property holds the layout direction of the horizontal list. + + Possible values: + + \list + \o Qt.LeftToRight (default) - Items will be laid out from left to right. + \o Qt.RightToLeft - Items will be laid out from right to let. + \endlist + + \sa ListView::effectiveLayoutDirection +*/ + + +/*! + \qmlproperty enumeration QtQuick2::ListView::effectiveLayoutDirection + This property holds the effective layout direction of the horizontal list. + + When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts, + the visual layout direction of the horizontal list will be mirrored. However, the + property \l {ListView::layoutDirection}{layoutDirection} will remain unchanged. + + \sa ListView::layoutDirection, {LayoutMirroring}{LayoutMirroring} +*/ + +/*! + \qmlproperty bool QtQuick2::ListView::keyNavigationWraps + This property holds whether the list wraps key navigation. + + If this is true, key navigation that would move the current item selection + past the end of the list instead wraps around and moves the selection to + the start of the list, and vice-versa. + + By default, key navigation is not wrapped. +*/ + + +/*! + \qmlproperty int QtQuick2::ListView::cacheBuffer + This property determines whether delegates are retained outside the + visible area of the view. + + If this value is non-zero, the view keeps as many delegates + instantiated as it can fit within the buffer specified. For example, + if in a vertical view the delegate is 20 pixels high and \c cacheBuffer is + set to 40, then up to 2 delegates above and 2 delegates below the visible + area may be retained. + + Note that cacheBuffer is not a pixel buffer - it only maintains additional + instantiated delegates. + + Setting this value can improve the smoothness of scrolling behavior at the expense + of additional memory usage. It is not a substitute for creating efficient + delegates; the fewer elements in a delegate, the faster a view can be + scrolled. +*/ + + +/*! + \qmlproperty string QtQuick2::ListView::section.property + \qmlproperty enumeration QtQuick2::ListView::section.criteria + \qmlproperty Component QtQuick2::ListView::section.delegate + + These properties hold the expression to be evaluated for the \l section attached property. + + The \l section attached property enables a ListView to be visually + separated into different parts. These properties determine how sections + are created. + + \c section.property holds the name of the property that is the basis + of each section. + + \c section.criteria holds the criteria for forming each section based on + \c section.property. This value can be one of: + + \list + \o ViewSection.FullString (default) - sections are created based on the + \c section.property value. + \o ViewSection.FirstCharacter - sections are created based on the first + character of the \c section.property value (for example, 'A', 'B', 'C' + sections, etc. for an address book) + \endlist + + \c section.delegate holds the delegate component for each section. + + Each item in the list has attached properties named \c ListView.section, + \c ListView.previousSection and \c ListView.nextSection. These may be + used to place a section header for related items. + + For example, here is a ListView that displays a list of animals, separated + into sections. Each item in the ListView is placed in a different section + depending on the "size" property of the model item. The \c sectionHeading + delegate component provides the light blue bar that marks the beginning of + each section. + + + \snippet examples/declarative/modelviews/listview/sections.qml 0 + + \image qml-listview-sections-example.png + + \note Adding sections to a ListView does not automatically re-order the + list items by the section criteria. + If the model is not ordered by section, then it is possible that + the sections created will not be unique; each boundary between + differing sections will result in a section header being created + even if that section exists elsewhere. + + \sa {declarative/modelviews/listview}{ListView examples} +*/ QSGViewSection *QSGListView::sectionCriteria() { Q_D(QSGListView); @@ -1339,12 +1736,35 @@ QSGViewSection *QSGListView::sectionCriteria() return d->sectionCriteria; } +/*! + \qmlproperty string QtQuick2::ListView::currentSection + This property holds the section that is currently at the beginning of the view. +*/ QString QSGListView::currentSection() const { Q_D(const QSGListView); return d->currentSection; } +/*! + \qmlproperty real QtQuick2::ListView::highlightMoveSpeed + \qmlproperty int QtQuick2::ListView::highlightMoveDuration + \qmlproperty real QtQuick2::ListView::highlightResizeSpeed + \qmlproperty int QtQuick2::ListView::highlightResizeDuration + + These properties hold the move and resize animation speed of the highlight delegate. + + \l highlightFollowsCurrentItem must be true for these properties + to have effect. + + The default value for the speed properties is 400 pixels/second. + The default value for the duration properties is -1, i.e. the + highlight will take as much time as necessary to move at the set speed. + + These properties have the same characteristics as a SmoothedAnimation. + + \sa highlightFollowsCurrentItem +*/ qreal QSGListView::highlightMoveSpeed() const { Q_D(const QSGListView); @@ -1406,6 +1826,27 @@ void QSGListView::setHighlightResizeDuration(int duration) } } +/*! + \qmlproperty enumeration QtQuick2::ListView::snapMode + + This property determines how the view scrolling will settle following a drag or flick. + The possible values are: + + \list + \o ListView.NoSnap (default) - the view stops anywhere within the visible area. + \o ListView.SnapToItem - the view settles with an item aligned with the start of + the view. + \o ListView.SnapOneItem - the view settles no more than one item away from the first + visible item at the time the mouse button is released. This mode is particularly + useful for moving one page at a time. + \endlist + + \c snapMode does not affect the \l currentIndex. To update the + \l currentIndex as the list is moved, set \l highlightRangeMode + to \c ListView.StrictlyEnforceRange. + + \sa highlightRangeMode +*/ QSGListView::SnapMode QSGListView::snapMode() const { Q_D(const QSGListView); @@ -1421,6 +1862,28 @@ void QSGListView::setSnapMode(SnapMode mode) } } + +/*! + \qmlproperty Component QtQuick2::ListView::footer + This property holds the component to use as the footer. + + An instance of the footer component is created for each view. The + footer is positioned at the end of the view, after any items. + + \sa header +*/ + + +/*! + \qmlproperty Component QtQuick2::ListView::header + This property holds the component to use as the header. + + An instance of the header component is created for each view. The + header is positioned at the beginning of the view, before any items. + + \sa footer +*/ + void QSGListView::viewportMoved() { Q_D(QSGListView); @@ -1555,6 +2018,15 @@ void QSGListView::geometryChanged(const QRectF &newGeometry, const QRectF &oldGe } +/*! + \qmlmethod QtQuick2::ListView::incrementCurrentIndex() + + Increments the current index. The current index will wrap + if keyNavigationWraps is true and it is currently at the end. + This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGListView::incrementCurrentIndex() { Q_D(QSGListView); @@ -1566,6 +2038,15 @@ void QSGListView::incrementCurrentIndex() } } +/*! + \qmlmethod QtQuick2::ListView::decrementCurrentIndex() + + Decrements the current index. The current index will wrap + if keyNavigationWraps is true and it is currently at the beginning. + This method has no effect if the \l count is zero. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGListView::decrementCurrentIndex() { Q_D(QSGListView); @@ -1954,6 +2435,72 @@ void QSGListView::itemsMoved(int from, int to, int count) d->layout(); } +/*! + \qmlmethod QtQuick2::ListView::positionViewAtIndex(int index, PositionMode mode) + + Positions the view such that the \a index is at the position specified by + \a mode: + + \list + \o ListView.Beginning - position item at the top (or left for horizontal orientation) of the view. + \o ListView.Center - position item in the center of the view. + \o ListView.End - position item at bottom (or right for horizontal orientation) of the view. + \o ListView.Visible - if any part of the item is visible then take no action, otherwise + bring the item into view. + \o ListView.Contain - ensure the entire item is visible. If the item is larger than + the view the item is positioned at the top (or left for horizontal orientation) of the view. + \endlist + + If positioning the view at \a index would cause empty space to be displayed at + the beginning or end of the view, the view will be positioned at the boundary. + + It is not recommended to use \l {Flickable::}{contentX} or \l {Flickable::}{contentY} to position the view + at a particular index. This is unreliable since removing items from the start + of the list does not cause all other items to be repositioned, and because + the actual start of the view can vary based on the size of the delegates. + The correct way to bring an item into view is with \c positionViewAtIndex. + + \bold Note: methods should only be called after the Component has completed. To position + the view at startup, this method should be called by Component.onCompleted. For + example, to position the view at the end: + + \code + Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning) + \endcode +*/ + +/*! + \qmlmethod QtQuick2::ListView::positionViewAtBeginning() + \qmlmethod QtQuick2::ListView::positionViewAtEnd() + + Positions the view at the beginning or end, taking into account any header or footer. + + It is not recommended to use \l {Flickable::}{contentX} or \l {Flickable::}{contentY} to position the view + at a particular index. This is unreliable since removing items from the start + of the list does not cause all other items to be repositioned, and because + the actual start of the view can vary based on the size of the delegates. + + \bold Note: methods should only be called after the Component has completed. To position + the view at startup, this method should be called by Component.onCompleted. For + example, to position the view at the end on startup: + + \code + Component.onCompleted: positionViewAtEnd() + \endcode +*/ + +/*! + \qmlmethod int QtQuick2::ListView::indexAt(int x, int y) + + Returns the index of the visible item containing the point \a x, \a y in content + coordinates. If there is no item at the point specified, or the item is + not visible -1 is returned. + + If the item is outside the visible area, -1 is returned, regardless of + whether an item will exist at that point when scrolled into view. + + \bold Note: methods should only be called after the Component has completed. +*/ QSGListViewAttached *QSGListView::qmlAttachedProperties(QObject *obj) { diff --git a/src/declarative/items/qsgloader.cpp b/src/declarative/items/qsgloader.cpp index ccf16896fb..999c174ee9 100644 --- a/src/declarative/items/qsgloader.cpp +++ b/src/declarative/items/qsgloader.cpp @@ -103,6 +103,115 @@ void QSGLoaderPrivate::initResize() _q_updateSize(); } +/*! + \qmlclass Loader QSGLoader + \inqmlmodule QtQuick 2 + \ingroup qml-utility-elements + \inherits Item + + \brief The Loader item allows dynamically loading an Item-based + subtree from a URL or Component. + + Loader is used to dynamically load visual QML components. It can load a + QML file (using the \l source property) or a \l Component object (using + the \l sourceComponent property). It is useful for delaying the creation + of a component until it is required: for example, when a component should + be created on demand, or when a component should not be created + unnecessarily for performance reasons. + + Here is a Loader that loads "Page1.qml" as a component when the + \l MouseArea is clicked: + + \snippet doc/src/snippets/declarative/loader/simple.qml 0 + + The loaded item can be accessed using the \l item property. + + If the \l source or \l sourceComponent changes, any previously instantiated + items are destroyed. Setting \l source to an empty string or setting + \l sourceComponent to \c undefined destroys the currently loaded item, + freeing resources and leaving the Loader empty. + + \section2 Loader sizing behavior + + Loader is like any other visual item and must be positioned and sized + accordingly to become visible. + + \list + \o If an explicit size is not specified for the Loader, the Loader + is automatically resized to the size of the loaded item once the + component is loaded. + \o If the size of the Loader is specified explicitly by setting + the width, height or by anchoring, the loaded item will be resized + to the size of the Loader. + \endlist + + In both scenarios the size of the item and the Loader are identical. + This ensures that anchoring to the Loader is equivalent to anchoring + to the loaded item. + + \table + \row + \o sizeloader.qml + \o sizeitem.qml + \row + \o \snippet doc/src/snippets/declarative/loader/sizeloader.qml 0 + \o \snippet doc/src/snippets/declarative/loader/sizeitem.qml 0 + \row + \o The red rectangle will be sized to the size of the root item. + \o The red rectangle will be 50x50, centered in the root item. + \endtable + + + \section2 Receiving signals from loaded items + + Any signals emitted from the loaded item can be received using the + \l Connections element. For example, the following \c application.qml + loads \c MyItem.qml, and is able to receive the \c message signal from + the loaded item through a \l Connections object: + + \table + \row + \o application.qml + \o MyItem.qml + \row + \o \snippet doc/src/snippets/declarative/loader/connections.qml 0 + \o \snippet doc/src/snippets/declarative/loader/MyItem.qml 0 + \endtable + + Alternatively, since \c MyItem.qml is loaded within the scope of the + Loader, it could also directly call any function defined in the Loader or + its parent \l Item. + + + \section2 Focus and key events + + Loader is a focus scope. Its \l {Item::}{focus} property must be set to + \c true for any of its children to get the \e {active focus}. (See + \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} + for more details.) Any key events received in the loaded item should likely + also be \l {KeyEvent::}{accepted} so they are not propagated to the Loader. + + For example, the following \c application.qml loads \c KeyReader.qml when + the \l MouseArea is clicked. Notice the \l {Item::}{focus} property is + set to \c true for the Loader as well as the \l Item in the dynamically + loaded object: + + \table + \row + \o application.qml + \o KeyReader.qml + \row + \o \snippet doc/src/snippets/declarative/loader/focus.qml 0 + \o \snippet doc/src/snippets/declarative/loader/KeyReader.qml 0 + \endtable + + Once \c KeyReader.qml is loaded, it accepts key events and sets + \c event.accepted to \c true so that the event is not propagated to the + parent \l Rectangle. + + \sa {dynamic-object-creation}{Dynamic Object Creation} +*/ + QSGLoader::QSGLoader(QSGItem *parent) : QSGImplicitSizeItem(*(new QSGLoaderPrivate), parent) { @@ -118,6 +227,19 @@ QSGLoader::~QSGLoader() } } +/*! + \qmlproperty url QtQuick2::Loader::source + This property holds the URL of the QML component to instantiate. + + Note the QML component must be an \l{Item}-based component. The loader + cannot load non-visual components. + + To unload the currently loaded item, set this property to an empty string, + or set \l sourceComponent to \c undefined. Setting \c source to a + new URL will also cause the item created by the previous URL to be unloaded. + + \sa sourceComponent, status, progress +*/ QUrl QSGLoader::source() const { Q_D(const QSGLoader); @@ -148,6 +270,28 @@ void QSGLoader::setSource(const QUrl &url) d->load(); } +/*! + \qmlproperty Component QtQuick2::Loader::sourceComponent + This property holds the \l{Component} to instantiate. + + \qml + Item { + Component { + id: redSquare + Rectangle { color: "red"; width: 10; height: 10 } + } + + Loader { sourceComponent: redSquare } + Loader { sourceComponent: redSquare; x: 10 } + } + \endqml + + To unload the currently loaded item, set this property to an empty string + or \c undefined. + + \sa source, progress +*/ + QDeclarativeComponent *QSGLoader::sourceComponent() const { Q_D(const QSGLoader); @@ -270,6 +414,46 @@ void QSGLoaderPrivate::_q_sourceLoaded() } } +/*! + \qmlproperty enumeration QtQuick2::Loader::status + + This property holds the status of QML loading. It can be one of: + \list + \o Loader.Null - no QML source has been set + \o Loader.Ready - the QML source has been loaded + \o Loader.Loading - the QML source is currently being loaded + \o Loader.Error - an error occurred while loading the QML source + \endlist + + Use this status to provide an update or respond to the status change in some way. + For example, you could: + + \list + \o Trigger a state change: + \qml + State { name: 'loaded'; when: loader.status == Loader.Ready } + \endqml + + \o Implement an \c onStatusChanged signal handler: + \qml + Loader { + id: loader + onStatusChanged: if (loader.status == Loader.Ready) console.log('Loaded') + } + \endqml + + \o Bind to the status value: + \qml + Text { text: loader.status == Loader.Ready ? 'Loaded' : 'Not loaded' } + \endqml + \endlist + + Note that if the source is a local file, the status will initially be Ready (or Error). While + there will be no onStatusChanged signal in that case, the onLoaded will still be invoked. + + \sa progress +*/ + QSGLoader::Status QSGLoader::status() const { Q_D(const QSGLoader); @@ -290,6 +474,23 @@ void QSGLoader::componentComplete() d->load(); } +/*! + \qmlsignal QtQuick2::Loader::onLoaded() + + This handler is called when the \l status becomes \c Loader.Ready, or on successful + initial load. +*/ + + +/*! +\qmlproperty real QtQuick2::Loader::progress + +This property holds the progress of loading QML data from the network, from +0.0 (nothing loaded) to 1.0 (finished). Most QML files are quite small, so +this value will rapidly change from 0 to 1. + +\sa status +*/ qreal QSGLoader::progress() const { Q_D(const QSGLoader); @@ -328,6 +529,10 @@ void QSGLoaderPrivate::_q_updateSize(bool loaderGeometryChanged) updatingSize = false; } +/*! + \qmlproperty Item QtQuick2::Loader::item + This property holds the top-level item that is currently loaded. +*/ QSGItem *QSGLoader::item() const { Q_D(const QSGLoader); diff --git a/src/declarative/items/qsgmousearea.cpp b/src/declarative/items/qsgmousearea.cpp index 5bf0867cdb..0f9d0a4780 100644 --- a/src/declarative/items/qsgmousearea.cpp +++ b/src/declarative/items/qsgmousearea.cpp @@ -85,7 +85,7 @@ void QSGDrag::resetTarget() } /*! - \qmlproperty Item MouseArea::drag.dropItem + \qmlproperty Item QtQuick2::MouseArea::drag.dropItem This property holds the item an active drag will be dropped on if released at the current position. @@ -115,7 +115,7 @@ void QSGDrag::setGrabItem(QSGItem *item) } /*! - \qmlproperty variant MouseArea::drag.data + \qmlproperty variant QtQuick2::MouseArea::drag.data This property holds the data sent to recipients of drag events generated by a MouseArea. @@ -234,7 +234,7 @@ void QSGDrag::setFilterChildren(bool filter) } /*! - \qmlproperty stringlist MouseArea::drag.keys + \qmlproperty stringlist QtQuick2::MouseArea::drag.keys This property holds a list of keys drag recipients can use to identify the source or data type of a drag event. @@ -272,7 +272,7 @@ void QSGMouseAreaPrivate::init() q->setFiltersChildMouseEvents(true); } -void QSGMouseAreaPrivate::saveEvent(QGraphicsSceneMouseEvent *event) +void QSGMouseAreaPrivate::saveEvent(QGraphicsSceneMouseEvent *event) { lastPos = event->pos(); lastScenePos = event->scenePos(); @@ -287,14 +287,14 @@ void QSGMouseAreaPrivate::forwardEvent(QGraphicsSceneMouseEvent* event) event->setPos(q->mapFromScene(event->scenePos())); } -bool QSGMouseAreaPrivate::isPressAndHoldConnected() +bool QSGMouseAreaPrivate::isPressAndHoldConnected() { Q_Q(QSGMouseArea); static int idx = QObjectPrivate::get(q)->signalIndex("pressAndHold(QSGMouseEvent*)"); return QObjectPrivate::get(q)->isSignalConnected(idx); } -bool QSGMouseAreaPrivate::isDoubleClickConnected() +bool QSGMouseAreaPrivate::isDoubleClickConnected() { Q_Q(QSGMouseArea); static int idx = QObjectPrivate::get(q)->signalIndex("doubleClicked(QSGMouseEvent*)"); @@ -373,7 +373,65 @@ bool QSGMouseAreaPrivate::propagateHelper(QSGMouseEvent *ev, QSGItem *item,const } -/* +/*! + \qmlclass MouseArea QSGMouseArea + \inqmlmodule QtQuick 2 + \ingroup qml-basic-interaction-elements + \brief The MouseArea item enables simple mouse handling. + \inherits Item + + A MouseArea is an invisible item that is typically used in conjunction with + a visible item in order to provide mouse handling for that item. + By effectively acting as a proxy, the logic for mouse handling can be + contained within a MouseArea item. + + For basic key handling, see the \l{Keys}{Keys attached property}. + + The \l enabled property is used to enable and disable mouse handling for + the proxied item. When disabled, the mouse area becomes transparent to + mouse events. + + The \l pressed read-only property indicates whether or not the user is + holding down a mouse button over the mouse area. This property is often + used in bindings between properties in a user interface. The containsMouse + read-only property indicates the presence of the mouse cursor over the + mouse area but, by default, only when a mouse button is held down; see below + for further details. + + Information about the mouse position and button clicks are provided via + signals for which event handler properties are defined. The most commonly + used involved handling mouse presses and clicks: onClicked, onDoubleClicked, + onPressed, onReleased and onPressAndHold. + + By default, MouseArea items only report mouse clicks and not changes to the + position of the mouse cursor. Setting the hoverEnabled property ensures that + handlers defined for onPositionChanged, onEntered and onExited are used and + that the containsMouse property is updated even when no mouse buttons are + pressed. + + \section1 Example Usage + + \div {class="float-right"} + \inlineimage qml-mousearea-snippet.png + \enddiv + + The following example uses a MouseArea in a \l Rectangle that changes + the \l Rectangle color to red when clicked: + + \snippet doc/src/snippets/declarative/mousearea/mousearea.qml import + \codeline + \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro + + \clearfloat + Many MouseArea signals pass a \l{MouseEvent}{mouse} parameter that contains + additional information about the mouse event, such as the position, button, + and any key modifiers. + + Here is an extension of the previous example that produces a different + color when the area is right clicked: + + \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro-extended + Behavioral Change in QtQuick 2.0 From QtQuick 2.0, the signals clicked, doubleClicked and pressAndHold have a different interaction @@ -385,7 +443,149 @@ bool QSGMouseAreaPrivate::propagateHelper(QSGMouseEvent *ev, QSGItem *item,const Note that to get the same behavior as a QtQuick 1.0 MouseArea{} with regard to absorbing all mouse events, you will now need to add empty signal handlers for these three signals. - */ + + \sa MouseEvent, {declarative/touchinteraction/mousearea}{MouseArea example} +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onEntered() + + This handler is called when the mouse enters the mouse area. + + By default the onEntered handler is only called while a button is + pressed. Setting hoverEnabled to true enables handling of + onEntered when no mouse button is pressed. + + \sa hoverEnabled +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onExited() + + This handler is called when the mouse exits the mouse area. + + By default the onExited handler is only called while a button is + pressed. Setting hoverEnabled to true enables handling of + onExited when no mouse button is pressed. + + The example below shows a fairly typical relationship between + two MouseAreas, with \c mouseArea2 on top of \c mouseArea1. Moving the + mouse into \c mouseArea2 from \c mouseArea1 will cause \c onExited + to be called for \c mouseArea1. + \qml + Rectangle { + width: 400; height: 400 + MouseArea { + id: mouseArea1 + anchors.fill: parent + hoverEnabled: true + } + MouseArea { + id: mouseArea2 + width: 100; height: 100 + anchors.centerIn: parent + hoverEnabled: true + } + } + \endqml + + If instead you give the two mouseAreas a parent-child relationship, + moving the mouse into \c mouseArea2 from \c mouseArea1 will \b not + cause \c onExited to be called for \c mouseArea1. Instead, they will + both be considered to be simultaneously hovered. + + \sa hoverEnabled +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onPositionChanged(MouseEvent mouse) + + This handler is called when the mouse position changes. + + The \l {MouseEvent}{mouse} parameter provides information about the mouse, including the x and y + position, and any buttons currently pressed. + + The \e accepted property of the MouseEvent parameter is ignored in this handler. + + By default the onPositionChanged handler is only called while a button is + pressed. Setting hoverEnabled to true enables handling of + onPositionChanged when no mouse button is pressed. +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onClicked(MouseEvent mouse) + + This handler is called when there is a click. A click is defined as a press followed by a release, + both inside the MouseArea (pressing, moving outside the MouseArea, and then moving back inside and + releasing is also considered a click). + + The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y + position of the release of the click, and whether the click was held. + + The \e accepted property of the MouseEvent parameter is ignored in this handler. +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onPressed(MouseEvent mouse) + + This handler is called when there is a press. + The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y + position and which button was pressed. + + The \e accepted property of the MouseEvent parameter determines whether this MouseArea + will handle the press and all future mouse events until release. The default is to accept + the event and not allow other MouseArea beneath this one to handle the event. If \e accepted + is set to false, no further events will be sent to this MouseArea until the button is next + pressed. +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onReleased(MouseEvent mouse) + + This handler is called when there is a release. + The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y + position of the release of the click, and whether the click was held. + + The \e accepted property of the MouseEvent parameter is ignored in this handler. + + \sa onCanceled +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onPressAndHold(MouseEvent mouse) + + This handler is called when there is a long press (currently 800ms). + The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y + position of the press, and which button is pressed. + + The \e accepted property of the MouseEvent parameter is ignored in this handler. +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onDoubleClicked(MouseEvent mouse) + + This handler is called when there is a double-click (a press followed by a release followed by a press). + The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y + position of the release of the click, and whether the click was held. + + If the \e accepted property of the \l {MouseEvent}{mouse} parameter is set to false + in the handler, the onPressed/onReleased/onClicked handlers will be called for the second + click; otherwise they are suppressed. The accepted property defaults to true. +*/ + +/*! + \qmlsignal QtQuick2::MouseArea::onCanceled() + + This handler is called when mouse events have been canceled, either because an event was not accepted, or + because another element stole the mouse event handling. + + This signal is for advanced use: it is useful when there is more than one MouseArea + that is handling input, or when there is a MouseArea inside a \l Flickable. In the latter + case, if you execute some logic on the pressed signal and then start dragging, the + \l Flickable will steal the mouse handling from the MouseArea. In these cases, to reset + the logic when the MouseArea has lost the mouse handling to the \l Flickable, + \c onCanceled should be used in addition to onReleased. +*/ QSGMouseArea::QSGMouseArea(QSGItem *parent) : QSGItem(*(new QSGMouseAreaPrivate), parent) { @@ -397,6 +597,25 @@ QSGMouseArea::~QSGMouseArea() { } +/*! + \qmlproperty real QtQuick2::MouseArea::mouseX + \qmlproperty real QtQuick2::MouseArea::mouseY + These properties hold the coordinates of the mouse cursor. + + If the hoverEnabled property is false then these properties will only be valid + while a button is pressed, and will remain valid as long as the button is held + down even if the mouse is moved outside the area. + + By default, this property is false. + + If hoverEnabled is true then these properties will be valid when: + \list + \i no button is pressed, but the mouse is within the MouseArea (containsMouse is true). + \i a button is pressed and held, even if it has since moved out of the area. + \endlist + + The coordinates are relative to the MouseArea. +*/ qreal QSGMouseArea::mouseX() const { Q_D(const QSGMouseArea); @@ -409,6 +628,12 @@ qreal QSGMouseArea::mouseY() const return d->lastPos.y(); } +/*! + \qmlproperty bool QtQuick2::MouseArea::enabled + This property holds whether the item accepts mouse events. + + By default, this property is true. +*/ bool QSGMouseArea::isEnabled() const { Q_D(const QSGMouseArea); @@ -424,6 +649,22 @@ void QSGMouseArea::setEnabled(bool a) } } +/*! + \qmlproperty bool QtQuick2::MouseArea::preventStealing + This property holds whether the mouse events may be stolen from this + MouseArea. + + If a MouseArea is placed within an item that filters child mouse + events, such as Flickable, the mouse + events may be stolen from the MouseArea if a gesture is recognized + by the parent element, e.g. a flick gesture. If preventStealing is + set to true, no element will steal the mouse events. + + Note that setting preventStealing to true once an element has started + stealing events will have no effect until the next press event. + + By default this property is false. +*/ bool QSGMouseArea::preventStealing() const { Q_D(const QSGMouseArea); @@ -440,6 +681,23 @@ void QSGMouseArea::setPreventStealing(bool prevent) } } +/*! + \qmlproperty MouseButtons QtQuick2::MouseArea::pressedButtons + This property holds the mouse buttons currently pressed. + + It contains a bitwise combination of: + \list + \o Qt.LeftButton + \o Qt.RightButton + \o Qt.MiddleButton + \endlist + + The code below displays "right" when the right mouse buttons is pressed: + + \snippet doc/src/snippets/declarative/mousearea/mousearea.qml mousebuttons + + \sa acceptedButtons +*/ Qt::MouseButtons QSGMouseArea::pressedButtons() const { Q_D(const QSGMouseArea); @@ -832,6 +1090,17 @@ void QSGMouseArea::itemChange(ItemChange change, const ItemChangeData &value) QSGItem::itemChange(change, value); } +/*! + \qmlproperty bool QtQuick2::MouseArea::hoverEnabled + This property holds whether hover events are handled. + + By default, mouse events are only handled in response to a button event, or when a button is + pressed. Hover enables handling of all mouse events even when no mouse button is + pressed. + + This property affects the containsMouse property and the onEntered, onExited and + onPositionChanged signals. +*/ bool QSGMouseArea::hoverEnabled() const { return acceptHoverEvents(); @@ -847,12 +1116,24 @@ void QSGMouseArea::setHoverEnabled(bool h) emit hoverEnabledChanged(); } + +/*! + \qmlproperty bool QtQuick2::MouseArea::containsMouse + This property holds whether the mouse is currently inside the mouse area. + + \warning This property is not updated if the area moves under the mouse: \e containsMouse will not change. + In addition, if hoverEnabled is false, containsMouse will only be valid when the mouse is pressed. +*/ bool QSGMouseArea::hovered() const { Q_D(const QSGMouseArea); return d->hovered; } +/*! + \qmlproperty bool QtQuick2::MouseArea::pressed + This property holds whether the mouse area is currently pressed. +*/ bool QSGMouseArea::pressed() const { Q_D(const QSGMouseArea); @@ -868,7 +1149,26 @@ void QSGMouseArea::setHovered(bool h) d->hovered ? emit entered() : emit exited(); } } +/*! + \qmlproperty QtQuick2::Qt::MouseButtons MouseArea::acceptedButtons + This property holds the mouse buttons that the mouse area reacts to. + + The available buttons are: + \list + \o Qt.LeftButton + \o Qt.RightButton + \o Qt.MiddleButton + \endlist + To accept more than one button the flags can be combined with the + "|" (or) operator: + + \code + MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton } + \endcode + + The default value is \c Qt.LeftButton. +*/ Qt::MouseButtons QSGMouseArea::acceptedButtons() const { return acceptedMouseButtons(); @@ -916,6 +1216,43 @@ bool QSGMouseArea::setPressed(bool p) return false; } +/*! + \qmlproperty Item QtQuick2::MouseArea::drag.target + \qmlproperty bool QtQuick2::MouseArea::drag.active + \qmlproperty enumeration QtQuick2::MouseArea::drag.axis + \qmlproperty real QtQuick2::MouseArea::drag.minimumX + \qmlproperty real QtQuick2::MouseArea::drag.maximumX + \qmlproperty real QtQuick2::MouseArea::drag.minimumY + \qmlproperty real QtQuick2::MouseArea::drag.maximumY + \qmlproperty bool QtQuick2::MouseArea::drag.filterChildren + + \c drag provides a convenient way to make an item draggable. + + \list + \i \c drag.target specifies the id of the item to drag. + \i \c drag.active specifies if the target item is currently being dragged. + \i \c drag.axis specifies whether dragging can be done horizontally (\c Drag.XAxis), vertically (\c Drag.YAxis), or both (\c Drag.XandYAxis) + \i \c drag.minimum and \c drag.maximum limit how far the target can be dragged along the corresponding axes. + \endlist + + The following example displays a \l Rectangle that can be dragged along the X-axis. The opacity + of the rectangle is reduced when it is dragged to the right. + + \snippet doc/src/snippets/declarative/mousearea/mousearea.qml drag + + \note Items cannot be dragged if they are anchored for the requested + \c drag.axis. For example, if \c anchors.left or \c anchors.right was set + for \c rect in the above example, it cannot be dragged along the X-axis. + This can be avoided by settng the anchor value to \c undefined in + an \l onPressed handler. + + If \c drag.filterChildren is set to true, a drag can override descendant MouseAreas. This + enables a parent MouseArea to handle drags, for example, while descendants handle clicks: + + \snippet doc/src/snippets/declarative/mousearea/mouseareadragfilter.qml dragfilter + +*/ + QSGDrag *QSGMouseArea::drag() { Q_D(QSGMouseArea); diff --git a/src/declarative/items/qsgpathview.cpp b/src/declarative/items/qsgpathview.cpp index 4a0496c4ae..54344d0947 100644 --- a/src/declarative/items/qsgpathview.cpp +++ b/src/declarative/items/qsgpathview.cpp @@ -349,6 +349,71 @@ void QSGPathViewPrivate::regenerate() q->refill(); } +/*! + \qmlclass PathView QSGPathView + \inqmlmodule QtQuick 2 + \ingroup qml-view-elements + \brief The PathView element lays out model-provided items on a path. + \inherits Item + + A PathView displays data from models created from built-in QML elements like ListModel + and XmlListModel, or custom model classes defined in C++ that inherit from + QAbstractListModel. + + The view has a \l model, which defines the data to be displayed, and + a \l delegate, which defines how the data should be displayed. + The \l delegate is instantiated for each item on the \l path. + The items may be flicked to move them along the path. + + For example, if there is a simple list model defined in a file \c ContactModel.qml like this: + + \snippet doc/src/snippets/declarative/pathview/ContactModel.qml 0 + + This data can be represented as a PathView, like this: + + \snippet doc/src/snippets/declarative/pathview/pathview.qml 0 + + \image pathview.gif + + (Note the above example uses PathAttribute to scale and modify the + opacity of the items as they rotate. This additional code can be seen in the + PathAttribute documentation.) + + PathView does not automatically handle keyboard navigation. This is because + the keys to use for navigation will depend upon the shape of the path. Navigation + can be added quite simply by setting \c focus to \c true and calling + \l decrementCurrentIndex() or \l incrementCurrentIndex(), for example to navigate + using the left and right arrow keys: + + \qml + PathView { + // ... + focus: true + Keys.onLeftPressed: decrementCurrentIndex() + Keys.onRightPressed: incrementCurrentIndex() + } + \endqml + + The path view itself is a focus scope (see \l{qmlfocus#Acquiring Focus and Focus Scopes}{the focus documentation page} for more details). + + Delegates are instantiated as needed and may be destroyed at any time. + State should \e never be stored in a delegate. + + PathView attaches a number of properties to the root item of the delegate, for example + \c {PathView.isCurrentItem}. In the following example, the root delegate item can access + this attached property directly as \c PathView.isCurrentItem, while the child + \c nameText object must refer to this property as \c wrapper.PathView.isCurrentItem. + + \snippet doc/src/snippets/declarative/pathview/pathview.qml 1 + + \bold Note that views do not enable \e clip automatically. If the view + is not clipped by another item or the screen, it will be necessary + to set \e {clip: true} in order to have the out of view items clipped + nicely. + + \sa Path, {declarative/modelviews/pathview}{PathView example} +*/ + QSGPathView::QSGPathView(QSGItem *parent) : QSGItem(*(new QSGPathViewPrivate), parent) { @@ -366,6 +431,54 @@ QSGPathView::~QSGPathView() delete d->model; } +/*! + \qmlattachedproperty PathView PathView::view + This attached property holds the view that manages this delegate instance. + + It is attached to each instance of the delegate. +*/ + +/*! + \qmlattachedproperty bool PathView::onPath + This attached property holds whether the item is currently on the path. + + If a pathItemCount has been set, it is possible that some items may + be instantiated, but not considered to be currently on the path. + Usually, these items would be set invisible, for example: + + \qml + Component { + Rectangle { + visible: PathView.onPath + // ... + } + } + \endqml + + It is attached to each instance of the delegate. +*/ + +/*! + \qmlattachedproperty bool PathView::isCurrentItem + This attached property is true if this delegate is the current item; otherwise false. + + It is attached to each instance of the delegate. + + This property may be used to adjust the appearance of the current item. + + \snippet doc/src/snippets/declarative/pathview/pathview.qml 1 +*/ + +/*! + \qmlproperty model QtQuick2::PathView::model + This property holds the model providing data for the view. + + The model provides a set of data that is used to create the items for the view. + For large or dynamic datasets the model is usually provided by a C++ model object. + Models can also be created directly in QML, using the ListModel element. + + \sa {qmlmodels}{Data Models} +*/ QVariant QSGPathView::model() const { Q_D(const QSGPathView); @@ -430,12 +543,21 @@ void QSGPathView::setModel(const QVariant &model) emit modelChanged(); } +/*! + \qmlproperty int QtQuick2::PathView::count + This property holds the number of items in the model. +*/ int QSGPathView::count() const { Q_D(const QSGPathView); return d->model ? d->modelCount : 0; } +/*! + \qmlproperty Path QtQuick2::PathView::path + This property holds the path used to lay out the items. + For more information see the \l Path documentation. +*/ QDeclarativePath *QSGPathView::path() const { Q_D(const QSGPathView); @@ -462,6 +584,10 @@ void QSGPathView::setPath(QDeclarativePath *path) emit pathChanged(); } +/*! + \qmlproperty int QtQuick2::PathView::currentIndex + This property holds the index of the current item. +*/ int QSGPathView::currentIndex() const { Q_D(const QSGPathView); @@ -512,6 +638,13 @@ QSGItem *QSGPathView::currentItem() const return d->currentItem; } +/*! + \qmlmethod QtQuick2::PathView::incrementCurrentIndex() + + Increments the current index. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGPathView::incrementCurrentIndex() { Q_D(QSGPathView); @@ -519,6 +652,13 @@ void QSGPathView::incrementCurrentIndex() setCurrentIndex(currentIndex()+1); } +/*! + \qmlmethod QtQuick2::PathView::decrementCurrentIndex() + + Decrements the current index. + + \bold Note: methods should only be called after the Component has completed. +*/ void QSGPathView::decrementCurrentIndex() { Q_D(QSGPathView); @@ -531,6 +671,12 @@ void QSGPathView::decrementCurrentIndex() } } +/*! + \qmlproperty real QtQuick2::PathView::offset + + The offset specifies how far along the path the items are from their initial positions. + This is a real number that ranges from 0.0 to the count of items in the model. +*/ qreal QSGPathView::offset() const { Q_D(const QSGPathView); @@ -565,6 +711,30 @@ void QSGPathViewPrivate::setAdjustedOffset(qreal o) setOffset(o+offsetAdj); } +/*! + \qmlproperty Component QtQuick2::PathView::highlight + This property holds the component to use as the highlight. + + An instance of the highlight component will be created for each view. + The geometry of the resultant component instance will be managed by the view + so as to stay with the current item. + + The below example demonstrates how to make a simple highlight. Note the use + of the \l{PathView::onPath}{PathView.onPath} attached property to ensure that + the highlight is hidden when flicked away from the path. + + \qml + Component { + Rectangle { + visible: PathView.onPath + // ... + } + } + \endqml + + \sa highlightItem, highlightRangeMode +*/ + QDeclarativeComponent *QSGPathView::highlight() const { Q_D(const QSGPathView); @@ -582,12 +752,54 @@ void QSGPathView::setHighlight(QDeclarativeComponent *highlight) } } +/*! + \qmlproperty Item QtQuick2::PathView::highlightItem + + \c highlightItem holds the highlight item, which was created + from the \l highlight component. + + \sa highlight +*/ QSGItem *QSGPathView::highlightItem() { Q_D(const QSGPathView); return d->highlightItem; } - +/*! + \qmlproperty real QtQuick2::PathView::preferredHighlightBegin + \qmlproperty real QtQuick2::PathView::preferredHighlightEnd + \qmlproperty enumeration QtQuick2::PathView::highlightRangeMode + + These properties set the preferred range of the highlight (current item) + within the view. The preferred values must be in the range 0.0-1.0. + + If highlightRangeMode is set to \e PathView.NoHighlightRange + + If highlightRangeMode is set to \e PathView.ApplyRange the view will + attempt to maintain the highlight within the range, however + the highlight can move outside of the range at the ends of the path + or due to a mouse interaction. + + If highlightRangeMode is set to \e PathView.StrictlyEnforceRange the highlight will never + move outside of the range. This means that the current item will change + if a keyboard or mouse action would cause the highlight to move + outside of the range. + + Note that this is the correct way to influence where the + current item ends up when the view moves. For example, if you want the + currently selected item to be in the middle of the path, then set the + highlight range to be 0.5,0.5 and highlightRangeMode to PathView.StrictlyEnforceRange. + Then, when the path scrolls, + the currently selected item will be the item at that position. This also applies to + when the currently selected item changes - it will scroll to within the preferred + highlight range. Furthermore, the behaviour of the current item index will occur + whether or not a highlight exists. + + The default value is \e PathView.StrictlyEnforceRange. + + Note that a valid range requires preferredHighlightEnd to be greater + than or equal to preferredHighlightBegin. +*/ qreal QSGPathView::preferredHighlightBegin() const { Q_D(const QSGPathView); @@ -638,6 +850,15 @@ void QSGPathView::setHighlightRangeMode(HighlightRangeMode mode) emit highlightRangeModeChanged(); } +/*! + \qmlproperty int QtQuick2::PathView::highlightMoveDuration + This property holds the move animation duration of the highlight delegate. + + If the highlightRangeMode is StrictlyEnforceRange then this property + determines the speed that the items move along the path. + + The default value for the duration is 300ms. +*/ int QSGPathView::highlightMoveDuration() const { Q_D(const QSGPathView); @@ -653,6 +874,14 @@ void QSGPathView::setHighlightMoveDuration(int duration) emit highlightMoveDurationChanged(); } +/*! + \qmlproperty real QtQuick2::PathView::dragMargin + This property holds the maximum distance from the path that initiate mouse dragging. + + By default the path can only be dragged by clicking on an item. If + dragMargin is greater than zero, a drag can be initiated by clicking + within dragMargin pixels of the path. +*/ qreal QSGPathView::dragMargin() const { Q_D(const QSGPathView); @@ -668,6 +897,12 @@ void QSGPathView::setDragMargin(qreal dragMargin) emit dragMarginChanged(); } +/*! + \qmlproperty real QtQuick2::PathView::flickDeceleration + This property holds the rate at which a flick will decelerate. + + The default is 100. +*/ qreal QSGPathView::flickDeceleration() const { Q_D(const QSGPathView); @@ -683,6 +918,14 @@ void QSGPathView::setFlickDeceleration(qreal dec) emit flickDecelerationChanged(); } +/*! + \qmlproperty bool QtQuick2::PathView::interactive + + A user cannot drag or flick a PathView that is not interactive. + + This property is useful for temporarily disabling flicking. This allows + special interaction with PathView's children. +*/ bool QSGPathView::isInteractive() const { Q_D(const QSGPathView); @@ -700,18 +943,79 @@ void QSGPathView::setInteractive(bool interactive) } } +/*! + \qmlproperty bool QtQuick2::PathView::moving + + This property holds whether the view is currently moving + due to the user either dragging or flicking the view. +*/ bool QSGPathView::isMoving() const { Q_D(const QSGPathView); return d->moving; } +/*! + \qmlproperty bool QtQuick2::PathView::flicking + + This property holds whether the view is currently moving + due to the user flicking the view. +*/ bool QSGPathView::isFlicking() const { Q_D(const QSGPathView); return d->flicking; } +/*! + \qmlsignal QtQuick2::PathView::onMovementStarted() + + This handler is called when the view begins moving due to user + interaction. +*/ + +/*! + \qmlsignal QtQuick2::PathView::onMovementEnded() + + This handler is called when the view stops moving due to user + interaction. If a flick was generated, this handler will + be triggered once the flick stops. If a flick was not + generated, the handler will be triggered when the + user stops dragging - i.e. a mouse or touch release. +*/ + +/*! + \qmlsignal QtQuick2::PathView::onFlickStarted() + + This handler is called when the view is flicked. A flick + starts from the point that the mouse or touch is released, + while still in motion. +*/ + +/*! + \qmlsignal QtQuick2::PathView::onFlickEnded() + + This handler is called when the view stops moving due to a flick. +*/ + +/*! + \qmlproperty Component QtQuick2::PathView::delegate + + The delegate provides a template defining each item instantiated by the view. + The index is exposed as an accessible \c index property. Properties of the + model are also available depending upon the type of \l {qmlmodels}{Data Model}. + + The number of elements in the delegate has a direct effect on the + flicking performance of the view when pathItemCount is specified. If at all possible, place functionality + that is not needed for the normal display of the delegate in a \l Loader which + can load additional elements when needed. + + Note that the PathView will layout the items based on the size of the root + item in the delegate. + + Here is an example delegate: + \snippet doc/src/snippets/declarative/pathview/pathview.qml 1 +*/ QDeclarativeComponent *QSGPathView::delegate() const { Q_D(const QSGPathView); @@ -743,6 +1047,10 @@ void QSGPathView::setDelegate(QDeclarativeComponent *delegate) } } +/*! + \qmlproperty int QtQuick2::PathView::pathItemCount + This property holds the number of items visible on the path at any one time. +*/ int QSGPathView::pathItemCount() const { Q_D(const QSGPathView); diff --git a/src/declarative/items/qsgpincharea.cpp b/src/declarative/items/qsgpincharea.cpp index a9bf0286fa..b37dcaf646 100644 --- a/src/declarative/items/qsgpincharea.cpp +++ b/src/declarative/items/qsgpincharea.cpp @@ -50,6 +50,102 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass PinchEvent QSGPinchEvent + \inqmlmodule QtQuick 2 + \ingroup qml-event-elements + \brief The PinchEvent object provides information about a pinch event. + + \bold {The PinchEvent element was added in QtQuick 1.1} + + The \c center, \c startCenter, \c previousCenter properties provide the center position between the two touch points. + + The \c scale and \c previousScale properties provide the scale factor. + + The \c angle, \c previousAngle and \c rotation properties provide the angle between the two points and the amount of rotation. + + The \c point1, \c point2, \c startPoint1, \c startPoint2 properties provide the positions of the touch points. + + The \c accepted property may be set to false in the \c onPinchStarted handler if the gesture should not + be handled. + + \sa PinchArea +*/ + +/*! + \qmlproperty QPointF QtQuick2::PinchEvent::center + \qmlproperty QPointF QtQuick2::PinchEvent::startCenter + \qmlproperty QPointF QtQuick2::PinchEvent::previousCenter + + These properties hold the position of the center point between the two touch points. + + \list + \o \c center is the current center point + \o \c previousCenter is the center point of the previous event. + \o \c startCenter is the center point when the gesture began + \endlist +*/ + +/*! + \qmlproperty real QtQuick2::PinchEvent::scale + \qmlproperty real QtQuick2::PinchEvent::previousScale + + These properties hold the scale factor determined by the change in distance between the two touch points. + + \list + \o \c scale is the current scale factor. + \o \c previousScale is the scale factor of the previous event. + \endlist + + When a pinch gesture is started, the scale is 1.0. +*/ + +/*! + \qmlproperty real QtQuick2::PinchEvent::angle + \qmlproperty real QtQuick2::PinchEvent::previousAngle + \qmlproperty real QtQuick2::PinchEvent::rotation + + These properties hold the angle between the two touch points. + + \list + \o \c angle is the current angle between the two points in the range -180 to 180. + \o \c previousAngle is the angle of the previous event. + \o \c rotation is the total rotation since the pinch gesture started. + \endlist + + When a pinch gesture is started, the rotation is 0.0. +*/ + +/*! + \qmlproperty QPointF QtQuick2::PinchEvent::point1 + \qmlproperty QPointF QtQuick2::PinchEvent::startPoint1 + \qmlproperty QPointF QtQuick2::PinchEvent::point2 + \qmlproperty QPointF QtQuick2::PinchEvent::startPoint2 + + These properties provide the actual touch points generating the pinch. + + \list + \o \c point1 and \c point2 hold the current positions of the points. + \o \c startPoint1 and \c startPoint2 hold the positions of the points when the second point was touched. + \endlist +*/ + +/*! + \qmlproperty bool QtQuick2::PinchEvent::accepted + + Setting this property to false in the \c PinchArea::onPinchStarted handler + will result in no further pinch events being generated, and the gesture + ignored. +*/ + +/*! + \qmlproperty int QtQuick2::PinchEvent::pointCount + + Holds the number of points currently touched. The PinchArea will not react + until two touch points have initited a gesture, but will remain active until + all touch points have been released. +*/ + QSGPinch::QSGPinch() : m_target(0), m_minScale(1.0), m_maxScale(1.0) , m_minRotation(0.0), m_maxRotation(0.0) @@ -63,6 +159,87 @@ QSGPinchAreaPrivate::~QSGPinchAreaPrivate() delete pinch; } +/*! + \qmlclass PinchArea QSGPinchArea + \inqmlmodule QtQuick 2 + \brief The PinchArea item enables simple pinch gesture handling. + \inherits Item + + \bold {The PinchArea element was added in QtQuick 1.1} + + A PinchArea is an invisible item that is typically used in conjunction with + a visible item in order to provide pinch gesture handling for that item. + + The \l enabled property is used to enable and disable pinch handling for + the proxied item. When disabled, the pinch area becomes transparent to + mouse/touch events. + + PinchArea can be used in two ways: + + \list + \o setting a \c pinch.target to provide automatic interaction with an element + \o using the onPinchStarted, onPinchUpdated and onPinchFinished handlers + \endlist + + \sa PinchEvent +*/ + +/*! + \qmlsignal QtQuick2::PinchArea::onPinchStarted() + + This handler is called when the pinch area detects that a pinch gesture has started. + + The \l {PinchEvent}{pinch} parameter provides information about the pinch gesture, + including the scale, center and angle of the pinch. + + To ignore this gesture set the \c pinch.accepted property to false. The gesture + will be cancelled and no further events will be sent. +*/ + +/*! + \qmlsignal QtQuick2::PinchArea::onPinchUpdated() + + This handler is called when the pinch area detects that a pinch gesture has changed. + + The \l {PinchEvent}{pinch} parameter provides information about the pinch gesture, + including the scale, center and angle of the pinch. +*/ + +/*! + \qmlsignal QtQuick2::PinchArea::onPinchFinished() + + This handler is called when the pinch area detects that a pinch gesture has finished. + + The \l {PinchEvent}{pinch} parameter provides information about the pinch gesture, + including the scale, center and angle of the pinch. +*/ + + +/*! + \qmlproperty Item QtQuick2::PinchArea::pinch.target + \qmlproperty bool QtQuick2::PinchArea::pinch.active + \qmlproperty real QtQuick2::PinchArea::pinch.minimumScale + \qmlproperty real QtQuick2::PinchArea::pinch.maximumScale + \qmlproperty real QtQuick2::PinchArea::pinch.minimumRotation + \qmlproperty real QtQuick2::PinchArea::pinch.maximumRotation + \qmlproperty enumeration QtQuick2::PinchArea::pinch.dragAxis + \qmlproperty real QtQuick2::PinchArea::pinch.minimumX + \qmlproperty real QtQuick2::PinchArea::pinch.maximumX + \qmlproperty real QtQuick2::PinchArea::pinch.minimumY + \qmlproperty real QtQuick2::PinchArea::pinch.maximumY + + \c pinch provides a convenient way to make an item react to pinch gestures. + + \list + \i \c pinch.target specifies the id of the item to drag. + \i \c pinch.active specifies if the target item is currently being dragged. + \i \c pinch.minimumScale and \c pinch.maximumScale limit the range of the Item::scale property. + \i \c pinch.minimumRotation and \c pinch.maximumRotation limit the range of the Item::rotation property. + \i \c pinch.dragAxis specifies whether dragging in not allowed (\c Pinch.NoDrag), can be done horizontally (\c Pinch.XAxis), vertically (\c Pinch.YAxis), or both (\c Pinch.XandYAxis) + \i \c pinch.minimum and \c pinch.maximum limit how far the target can be dragged along the corresponding axes. + \endlist +*/ + QSGPinchArea::QSGPinchArea(QSGItem *parent) : QSGItem(*(new QSGPinchAreaPrivate), parent) { @@ -73,7 +250,12 @@ QSGPinchArea::QSGPinchArea(QSGItem *parent) QSGPinchArea::~QSGPinchArea() { } +/*! + \qmlproperty bool QtQuick2::PinchArea::enabled + This property holds whether the item accepts pinch gestures. + This property defaults to true. +*/ bool QSGPinchArea::isEnabled() const { Q_D(const QSGPinchArea); diff --git a/src/declarative/items/qsgpositioners.cpp b/src/declarative/items/qsgpositioners.cpp index fe1194339e..5ebf2d7a0d 100644 --- a/src/declarative/items/qsgpositioners.cpp +++ b/src/declarative/items/qsgpositioners.cpp @@ -78,6 +78,22 @@ QSGBasePositioner::QSGBasePositioner(PositionerType at, QSGItem *parent) Q_D(QSGBasePositioner); d->init(at); } +/*! + \internal + \class QSGBasePositioner + \brief The QSGBasePositioner class provides a base for QSGGraphics layouts. + + To create a QSGGraphics Positioner, simply subclass QSGBasePositioner and implement + doLayout(), which is automatically called when the layout might need + updating. In doLayout() use the setX and setY functions from QSGBasePositioner, and the + base class will apply the positions along with the appropriate transitions. The items to + position are provided in order as the protected member positionedItems. + + You also need to set a PositionerType, to declare whether you are positioning the x, y or both + for the child items. Depending on the chosen type, only x or y changes will be applied. + + Note that the subclass is responsible for adding the spacing in between items. +*/ QSGBasePositioner::QSGBasePositioner(QSGBasePositionerPrivate &dd, PositionerType at, QSGItem *parent) : QSGImplicitSizeItem(dd, parent) @@ -269,6 +285,120 @@ void QSGBasePositioner::finishApplyTransitions() d->moveActions.clear(); } +/*! + \qmlclass Column QSGColumn + \inqmlmodule QtQuick 2 + \ingroup qml-positioning-elements + \brief The Column item arranges its children vertically. + \inherits Item + + The Column item positions its child items so that they are vertically + aligned and not overlapping. + + Spacing between items can be added using the \l spacing property. + Transitions can be used for cases where items managed by a Column are + added or moved. These are stored in the \l add and \l move properties + respectively. + + See \l{Using QML Positioner and Repeater Items} for more details about this item and other + related items. + + \section1 Example Usage + + The following example positions differently shaped rectangles using a Column + item. + + \image verticalpositioner_example.png + + \snippet doc/src/snippets/declarative/column/vertical-positioner.qml document + + \section1 Using Transitions + + Transitions can be used to animate items that are added to, moved within, + or removed from a Column item. The \l add and \l move properties can be set to + the transitions that will be applied when items are added to, removed from, + or re-positioned within a Column item. + + The use of transitions with positioners is described in more detail in the + \l{Using QML Positioner and Repeater Items#Using Transitions}{Using QML + Positioner and Repeater Items} document. + + \image verticalpositioner_transition.gif + + \qml + Column { + spacing: 2 + add: Transition { + // Define an animation for adding a new item... + } + move: Transition { + // Define an animation for moving items within the column... + } + // ... + } + \endqml + + \section1 Limitations + + Note that the positioner assumes that the x and y positions of its children + will not change. If you manually change the x or y properties in script, bind + the x or y properties, use anchors on a child of a positioner, or have the + height of a child depend on the position of a child, then the + positioner may exhibit strange behavior. If you need to perform any of these + actions, consider positioning the items without the use of a Column. + + Items with a width or height of 0 will not be positioned. + + \sa Row, Grid, Flow, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty Transition QtQuick2::Column::add + + This property holds the transition to be applied when adding an + item to the positioner. The transition will only be applied to the + added item(s). Positioner transitions will only affect the + position (x, y) of items. + + For a positioner, adding an item can mean that either the object + has been created or reparented, and thus is now a child or the + positioner, or that the object has had its opacity increased from + zero, and thus is now visible. + + \sa move +*/ +/*! + \qmlproperty Transition QtQuick2::Column::move + + This property holds the transition to apply when moving an item + within the positioner. Positioner transitions will only affect + the position (x, y) of items. + + This transition can be performed when other items are added or removed + from the positioner, or when items resize themselves. + + \image positioner-move.gif + + \qml + Column { + move: Transition { + NumberAnimation { + properties: "y" + duration: 1000 + } + } + } + \endqml + + \sa add, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty int QtQuick2::Column::spacing + + The spacing is the amount in pixels left empty between adjacent + items. The default spacing is 0. + + \sa Grid::spacing +*/ QSGColumn::QSGColumn(QSGItem *parent) : QSGBasePositioner(Vertical, parent) { @@ -319,11 +449,119 @@ void QSGColumn::reportConflictingAnchors() qmlInfo(this) << "Cannot specify top, bottom, verticalCenter, fill or centerIn anchors for items inside Column"; } } +/*! + \qmlclass Row QSGRow + \inqmlmodule QtQuick 2 + \ingroup qml-positioning-elements + \brief The Row item arranges its children horizontally. + \inherits Item + + The Row item positions its child items so that they are horizontally + aligned and not overlapping. + + Use \l spacing to set the spacing between items in a Row, and use the + \l add and \l move properties to set the transitions that should be applied + when items are added to, removed from, or re-positioned within the Row. + + See \l{Using QML Positioner and Repeater Items} for more details about this item and other + related items. + + \section1 Example Usage + + The following example lays out differently shaped rectangles using a Row. + + \image horizontalpositioner_example.png + + \snippet doc/src/snippets/declarative/row/row.qml document + + \section1 Using Transitions + + Transitions can be used to animate items that are added to, moved within, + or removed from a Grid item. The \l add and \l move properties can be set to + the transitions that will be applied when items are added to, removed from, + or re-positioned within a Row item. + + \section1 Limitations + + Note that the positioner assumes that the x and y positions of its children + will not change. If you manually change the x or y properties in script, bind + the x or y properties, use anchors on a child of a positioner, or have the + width of a child depend on the position of a child, then the + positioner may exhibit strange behaviour. If you need to perform any of these + actions, consider positioning the items without the use of a Row. + + Items with a width or height of 0 will not be positioned. + + \sa Column, Grid, Flow, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty Transition QtQuick2::Row::add + + This property holds the transition to be applied when adding an + item to the positioner. The transition will only be applied to the + added item(s). Positioner transitions will only affect the + position (x, y) of items. + + For a positioner, adding an item can mean that either the object + has been created or reparented, and thus is now a child or the + positioner, or that the object has had its opacity increased from + zero, and thus is now visible. + + \sa move +*/ +/*! + \qmlproperty Transition QtQuick2::Row::move + + This property holds the transition to be applied when moving an + item within the positioner. Positioner transitions will only affect + the position (x, y) of items. + + This transition can be performed when other items are added or removed + from the positioner, or when items resize themselves. + + \qml + Row { + id: positioner + move: Transition { + NumberAnimation { + properties: "x" + duration: 1000 + } + } + } + \endqml + + \sa add, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty int QtQuick2::Row::spacing + + The spacing is the amount in pixels left empty between adjacent + items. The default spacing is 0. + + \sa Grid::spacing +*/ QSGRow::QSGRow(QSGItem *parent) : QSGBasePositioner(Horizontal, parent) { } +/*! + \qmlproperty enumeration QtQuick2::Row::layoutDirection + + This property holds the layoutDirection of the row. + + Possible values: + + \list + \o Qt.LeftToRight (default) - Items are laid out from left to right. If the width of the row is explicitly set, + the left anchor remains to the left of the row. + \o Qt.RightToLeft - Items are laid out from right to left. If the width of the row is explicitly set, + the right anchor remains to the right of the row. + \endlist + + \sa Grid::layoutDirection, Flow::layoutDirection, {declarative/righttoleft/layoutdirection}{Layout directions example} +*/ Qt::LayoutDirection QSGRow::layoutDirection() const { @@ -345,6 +583,16 @@ void QSGRow::setLayoutDirection(Qt::LayoutDirection layoutDirection) emit effectiveLayoutDirectionChanged(); } } +/*! + \qmlproperty enumeration QtQuick2::Row::effectiveLayoutDirection + This property holds the effective layout direction of the row positioner. + + When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts, + the visual layout direction of the row positioner will be mirrored. However, the + property \l {Row::layoutDirection}{layoutDirection} will remain unchanged. + + \sa Row::layoutDirection, {LayoutMirroring}{LayoutMirroring} +*/ Qt::LayoutDirection QSGRow::effectiveLayoutDirection() const { @@ -422,11 +670,138 @@ void QSGRow::reportConflictingAnchors() qmlInfo(this) << "Cannot specify left, right, horizontalCenter, fill or centerIn anchors for items inside Row"; } +/*! + \qmlclass Grid QSGGrid + \inqmlmodule QtQuick 2 + \ingroup qml-positioning-elements + \brief The Grid item positions its children in a grid. + \inherits Item + + The Grid item positions its child items so that they are + aligned in a grid and are not overlapping. + + The grid positioner calculates a grid of rectangular cells of sufficient + size to hold all items, placing the items in the cells, from left to right + and top to bottom. Each item is positioned in the top-left corner of its + cell with position (0, 0). + + A Grid defaults to four columns, and as many rows as are necessary to + fit all child items. The number of rows and columns can be constrained + by setting the \l rows and \l columns properties. + + Spacing can be added between child items by setting the \l spacing + property. The amount of spacing applied will be the same in the + horizontal and vertical directions. + + See \l{Using QML Positioner and Repeater Items} for more details about this item and other + related items. + + \section1 Example Usage + + The following example demonstrates this. + + \image gridLayout_example.png + + \snippet doc/src/snippets/declarative/grid/grid.qml document + + \section1 Using Transitions + + Transitions can be used to animate items that are added to, moved within, + or removed from a Grid item. The \l add and \l move properties can be set to + the transitions that will be applied when items are added to, removed from, + or re-positioned within a Grid item. + + \section1 Limitations + + Note that the positioner assumes that the x and y positions of its children + will not change. If you manually change the x or y properties in script, bind + the x or y properties, use anchors on a child of a positioner, or have the + width or height of a child depend on the position of a child, then the + positioner may exhibit strange behaviour. If you need to perform any of these + actions, consider positioning the items without the use of a Grid. + + Items with a width or height of 0 will not be positioned. + + \sa Flow, Row, Column, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty Transition QtQuick2::Grid::add + + This property holds the transition to be applied when adding an + item to the positioner. The transition will only be applied to the + added item(s). Positioner transitions will only affect the + position (x, y) of items. + + For a positioner, adding an item can mean that either the object + has been created or reparented, and thus is now a child or the + positioner, or that the object has had its opacity increased from + zero, and thus is now visible. + + \sa move +*/ +/*! + \qmlproperty Transition QtQuick2::Grid::move + + This property holds the transition to be applied when moving an + item within the positioner. Positioner transitions will only affect + the position (x, y) of items. + + This transition can be performed when other items are added or removed + from the positioner, or when items resize themselves. + + \qml + Grid { + move: Transition { + NumberAnimation { + properties: "x,y" + duration: 1000 + } + } + } + \endqml + + \sa add, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty int QtQuick2::Grid::spacing + + The spacing is the amount in pixels left empty between adjacent + items. The default spacing is 0. + + The below example places a Grid containing a red, a blue and a + green rectangle on a gray background. The area the grid positioner + occupies is colored white. The positioner on the left has the + no spacing (the default), and the positioner on the right has + a spacing of 6. + + \inlineimage qml-grid-no-spacing.png + \inlineimage qml-grid-spacing.png + + \sa rows, columns +*/ QSGGrid::QSGGrid(QSGItem *parent) : QSGBasePositioner(Both, parent), m_rows(-1), m_columns(-1), m_flow(LeftToRight) { } +/*! + \qmlproperty int QtQuick2::Grid::columns + + This property holds the number of columns in the grid. The default + number of columns is 4. + + If the grid does not have enough items to fill the specified + number of columns, some columns will be of zero width. +*/ + +/*! + \qmlproperty int QtQuick2::Grid::rows + This property holds the number of rows in the grid. + + If the grid does not have enough items to fill the specified + number of rows, some rows will be of zero width. +*/ + void QSGGrid::setColumns(const int columns) { if (columns == m_columns) @@ -445,6 +820,19 @@ void QSGGrid::setRows(const int rows) emit rowsChanged(); } +/*! + \qmlproperty enumeration QtQuick2::Grid::flow + This property holds the flow of the layout. + + Possible values are: + + \list + \o Grid.LeftToRight (default) - Items are positioned next to + each other in the \l layoutDirection, then wrapped to the next line. + \o Grid.TopToBottom - Items are positioned next to each + other from top to bottom, then wrapped to the next column. + \endlist +*/ QSGGrid::Flow QSGGrid::flow() const { return m_flow; @@ -459,6 +847,24 @@ void QSGGrid::setFlow(Flow flow) } } +/*! + \qmlproperty enumeration QtQuick2::Grid::layoutDirection + + This property holds the layout direction of the layout. + + Possible values are: + + \list + \o Qt.LeftToRight (default) - Items are positioned from the top to bottom, + and left to right. The flow direction is dependent on the + \l Grid::flow property. + \o Qt.RightToLeft - Items are positioned from the top to bottom, + and right to left. The flow direction is dependent on the + \l Grid::flow property. + \endlist + + \sa Flow::layoutDirection, Row::layoutDirection, {declarative/righttoleft/layoutdirection}{Layout directions example} +*/ Qt::LayoutDirection QSGGrid::layoutDirection() const { return QSGBasePositionerPrivate::getLayoutDirection(this); @@ -480,6 +886,16 @@ void QSGGrid::setLayoutDirection(Qt::LayoutDirection layoutDirection) } } +/*! + \qmlproperty enumeration QtQuick2::Grid::effectiveLayoutDirection + This property holds the effective layout direction of the grid positioner. + + When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts, + the visual layout direction of the grid positioner will be mirrored. However, the + property \l {Grid::layoutDirection}{layoutDirection} will remain unchanged. + + \sa Grid::layoutDirection, {LayoutMirroring}{LayoutMirroring} +*/ Qt::LayoutDirection QSGGrid::effectiveLayoutDirection() const { return QSGBasePositionerPrivate::getEffectiveLayoutDirection(this); @@ -642,6 +1058,105 @@ void QSGGrid::reportConflictingAnchors() qmlInfo(this) << "Cannot specify anchors for items inside Grid"; } +/*! + \qmlclass Flow QSGFlow + \inqmlmodule QtQuick 2 + \ingroup qml-positioning-elements + \brief The Flow item arranges its children side by side, wrapping as necessary. + \inherits Item + + The Flow item positions its child items like words on a page, wrapping them + to create rows or columns of items that do not overlap. + + Spacing between items can be added using the \l spacing property. + Transitions can be used for cases where items managed by a Column are + added or moved. These are stored in the \l add and \l move properties + respectively. + + See \l{Using QML Positioner and Repeater Items} for more details about this item and other + related items. + + \section1 Example Usage + + The following example positions \l Text items within a parent item using + a Flow item. + + \image qml-flow-snippet.png + + \snippet doc/src/snippets/declarative/flow.qml flow item + + \section1 Using Transitions + + Transitions can be used to animate items that are added to, moved within, + or removed from a Flow item. The \l add and \l move properties can be set to + the transitions that will be applied when items are added to, removed from, + or re-positioned within a Flow item. + + The use of transitions with positioners is described in more detail in the + \l{Using QML Positioner and Repeater Items#Using Transitions}{Using QML + Positioner and Repeater Items} document. + + \section1 Limitations + + Note that the positioner assumes that the x and y positions of its children + will not change. If you manually change the x or y properties in script, bind + the x or y properties, use anchors on a child of a positioner, or have the + width or height of a child depend on the position of a child, then the + positioner may exhibit strange behaviour. If you need to perform any of these + actions, consider positioning the items without the use of a Flow. + + Items with a width or height of 0 will not be positioned. + + \sa Column, Row, Grid, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty Transition QtQuick2::Flow::add + + This property holds the transition to be applied when adding an + item to the positioner. The transition will only be applied to the + added item(s). Positioner transitions will only affect the + position (x, y) of items. + + For a positioner, adding an item can mean that either the object + has been created or reparented, and thus is now a child or the + positioner, or that the object has had its opacity increased from + zero, and thus is now visible. + + \sa move +*/ +/*! + \qmlproperty Transition QtQuick2::Flow::move + + This property holds the transition to be applied when moving an + item within the positioner. Positioner transitions will only affect + the position (x, y) of items. + + This transition can be performed when other items are added or removed + from the positioner, or when items resize themselves. + + \qml + Flow { + id: positioner + move: Transition { + NumberAnimation { + properties: "x,y" + ease: "easeOutBounce" + } + } + } + \endqml + + \sa add, {declarative/positioners}{Positioners example} +*/ +/*! + \qmlproperty int QtQuick2::Flow::spacing + + spacing is the amount in pixels left empty between each adjacent + item, and defaults to 0. + + \sa Grid::spacing +*/ + class QSGFlowPrivate : public QSGBasePositionerPrivate { Q_DECLARE_PUBLIC(QSGFlow) @@ -662,6 +1177,21 @@ QSGFlow::QSGFlow(QSGItem *parent) d->addItemChangeListener(d, QSGItemPrivate::Geometry); } +/*! + \qmlproperty enumeration QtQuick2::Flow::flow + This property holds the flow of the layout. + + Possible values are: + + \list + \o Flow.LeftToRight (default) - Items are positioned next to + to each other according to the \l layoutDirection until the width of the Flow + is exceeded, then wrapped to the next line. + \o Flow.TopToBottom - Items are positioned next to each + other from top to bottom until the height of the Flow is exceeded, + then wrapped to the next column. + \endlist +*/ QSGFlow::Flow QSGFlow::flow() const { Q_D(const QSGFlow); @@ -678,6 +1208,25 @@ void QSGFlow::setFlow(Flow flow) } } +/*! + \qmlproperty enumeration QtQuick2::Flow::layoutDirection + + This property holds the layout direction of the layout. + + Possible values are: + + \list + \o Qt.LeftToRight (default) - Items are positioned from the top to bottom, + and left to right. The flow direction is dependent on the + \l Flow::flow property. + \o Qt.RightToLeft - Items are positioned from the top to bottom, + and right to left. The flow direction is dependent on the + \l Flow::flow property. + \endlist + + \sa Grid::layoutDirection, Row::layoutDirection, {declarative/righttoleft/layoutdirection}{Layout directions example} +*/ + Qt::LayoutDirection QSGFlow::layoutDirection() const { Q_D(const QSGFlow); @@ -695,6 +1244,17 @@ void QSGFlow::setLayoutDirection(Qt::LayoutDirection layoutDirection) } } +/*! + \qmlproperty enumeration QtQuick2::Flow::effectiveLayoutDirection + This property holds the effective layout direction of the flow positioner. + + When using the attached property \l {LayoutMirroring::enabled}{LayoutMirroring::enabled} for locale layouts, + the visual layout direction of the grid positioner will be mirrored. However, the + property \l {Flow::layoutDirection}{layoutDirection} will remain unchanged. + + \sa Flow::layoutDirection, {LayoutMirroring}{LayoutMirroring} +*/ + Qt::LayoutDirection QSGFlow::effectiveLayoutDirection() const { return QSGBasePositionerPrivate::getEffectiveLayoutDirection(this); diff --git a/src/declarative/items/qsgrectangle.cpp b/src/declarative/items/qsgrectangle.cpp index cb648e25d7..b1c26a5a2c 100644 --- a/src/declarative/items/qsgrectangle.cpp +++ b/src/declarative/items/qsgrectangle.cpp @@ -52,6 +52,24 @@ QT_BEGIN_NAMESPACE // XXX todo - should we change rectangle to draw entirely within its width/height? +/*! + \internal + \class QSGPen + \brief The QSGPen class provides a pen used for drawing rectangle borders on a QSGView. + + By default, the pen is invalid and nothing is drawn. You must either set a color (then the default + width is 1) or a width (then the default color is black). + + A width of 1 indicates is a single-pixel line on the border of the item being painted. + + Example: + \qml + Rectangle { + border.width: 2 + border.color: "red" + } + \endqml +*/ QSGPen::QSGPen(QObject *parent) : QObject(parent) @@ -63,7 +81,7 @@ QSGPen::QSGPen(QObject *parent) } qreal QSGPen::width() const -{ +{ return m_width; } @@ -77,9 +95,9 @@ void QSGPen::setWidth(qreal w) emit penChanged(); } -QColor QSGPen::color() const -{ - return m_color; +QColor QSGPen::color() const +{ + return m_color; } void QSGPen::setColor(const QColor &c) @@ -104,33 +122,53 @@ void QSGPen::setAligned(bool aligned) } bool QSGPen::isValid() const -{ +{ return m_valid; } -QSGGradientStop::QSGGradientStop(QObject *parent) +/*! + \qmlclass GradientStop QSGGradientStop + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The GradientStop item defines the color at a position in a Gradient. + + \sa Gradient +*/ + +/*! + \qmlproperty real QtQuick2::GradientStop::position + \qmlproperty color QtQuick2::GradientStop::color + + The position and color properties describe the color used at a given + position in a gradient, as represented by a gradient stop. + + The default position is 0.0; the default color is black. + + \sa Gradient +*/ +QSGGradientStop::QSGGradientStop(QObject *parent) : QObject(parent) { } -qreal QSGGradientStop::position() const +qreal QSGGradientStop::position() const { - return m_position; + return m_position; } -void QSGGradientStop::setPosition(qreal position) +void QSGGradientStop::setPosition(qreal position) { - m_position = position; updateGradient(); + m_position = position; updateGradient(); } -QColor QSGGradientStop::color() const +QColor QSGGradientStop::color() const { - return m_color; + return m_color; } -void QSGGradientStop::setColor(const QColor &color) +void QSGGradientStop::setColor(const QColor &color) { - m_color = color; updateGradient(); + m_color = color; updateGradient(); } void QSGGradientStop::updateGradient() @@ -139,19 +177,80 @@ void QSGGradientStop::updateGradient() grad->doUpdate(); } -QSGGradient::QSGGradient(QObject *parent) -: QObject(parent), m_gradient(0) +/*! + \qmlclass Gradient QSGGradient + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The Gradient item defines a gradient fill. + + A gradient is defined by two or more colors, which will be blended seamlessly. + + The colors are specified as a set of GradientStop child items, each of + which defines a position on the gradient from 0.0 to 1.0 and a color. + The position of each GradientStop is defined by setting its + \l{GradientStop::}{position} property; its color is defined using its + \l{GradientStop::}{color} property. + + A gradient without any gradient stops is rendered as a solid white fill. + + Note that this item is not a visual representation of a gradient. To display a + gradient, use a visual element (like \l Rectangle) which supports the use + of gradients. + + \section1 Example Usage + + \div {class="float-right"} + \inlineimage qml-gradient.png + \enddiv + + The following example declares a \l Rectangle item with a gradient starting + with red, blending to yellow at one third of the height of the rectangle, + and ending with green: + + \snippet doc/src/snippets/declarative/gradient.qml code + + \clearfloat + \section1 Performance and Limitations + + Calculating gradients can be computationally expensive compared to the use + of solid color fills or images. Consider using gradients for static items + in a user interface. + + In Qt 4.7, only vertical, linear gradients can be applied to items. If you + need to apply different orientations of gradients, a combination of rotation + and clipping will need to be applied to the relevant items. This can + introduce additional performance requirements for your application. + + The use of animations involving gradient stops may not give the desired + result. An alternative way to animate gradients is to use pre-generated + images or SVG drawings containing gradients. + + \sa GradientStop +*/ + +/*! + \qmlproperty list<GradientStop> QtQuick2::Gradient::stops + \default + + This property holds the gradient stops describing the gradient. + + By default, this property contains an empty list. + + To set the gradient stops, define them as children of the Gradient element. +*/ +QSGGradient::QSGGradient(QObject *parent) +: QObject(parent), m_gradient(0) { } -QSGGradient::~QSGGradient() +QSGGradient::~QSGGradient() { - delete m_gradient; + delete m_gradient; } -QDeclarativeListProperty<QSGGradientStop> QSGGradient::stops() +QDeclarativeListProperty<QSGGradientStop> QSGGradient::stops() { - return QDeclarativeListProperty<QSGGradientStop>(this, m_stops); + return QDeclarativeListProperty<QSGGradientStop>(this, m_stops); } const QGradient *QSGGradient::gradient() const @@ -177,6 +276,51 @@ void QSGGradient::doUpdate() int QSGRectanglePrivate::doUpdateSlotIdx = -1; +/*! + \qmlclass Rectangle QSGRectangle + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The Rectangle item provides a filled rectangle with an optional border. + \inherits Item + + Rectangle items are used to fill areas with solid color or gradients, and are + often used to hold other items. + + \section1 Appearance + + Each Rectangle item is painted using either a solid fill color, specified using + the \l color property, or a gradient, defined using a Gradient element and set + using the \l gradient property. If both a color and a gradient are specified, + the gradient is used. + + You can add an optional border to a rectangle with its own color and thickness + by settting the \l border.color and \l border.width properties. + + You can also create rounded rectangles using the \l radius property. Since this + introduces curved edges to the corners of a rectangle, it may be appropriate to + set the \l smooth property to improve its appearance. + + \section1 Example Usage + + \div {class="float-right"} + \inlineimage declarative-rect.png + \enddiv + + The following example shows the effects of some of the common properties on a + Rectangle item, which in this case is used to create a square: + + \snippet doc/src/snippets/declarative/rectangle/rectangle.qml document + + \clearfloat + \section1 Performance + + Using the \l smooth property improves the appearance of a rounded rectangle at + the cost of rendering performance. You should consider unsetting this property + for rectangles in motion, and only set it when they are stationary. + + \sa Image +*/ + QSGRectangle::QSGRectangle(QSGItem *parent) : QSGItem(*(new QSGRectanglePrivate), parent) { @@ -191,12 +335,58 @@ void QSGRectangle::doUpdate() update(); } +/*! + \qmlproperty int QtQuick2::Rectangle::border.width + \qmlproperty color QtQuick2::Rectangle::border.color + + The width and color used to draw the border of the rectangle. + + A width of 1 creates a thin line. For no line, use a width of 0 or a transparent color. + + \note The width of the rectangle's border does not affect the geometry of the + rectangle itself or its position relative to other items if anchors are used. + + If \c border.width is an odd number, the rectangle is painted at a half-pixel offset to retain + border smoothness. Also, the border is rendered evenly on either side of the + rectangle's boundaries, and the spare pixel is rendered to the right and below the + rectangle (as documented for QRect rendering). This can cause unintended effects if + \c border.width is 1 and the rectangle is \l{Item::clip}{clipped} by a parent item: + + \div {class="float-right"} + \inlineimage rect-border-width.png + \enddiv + + \snippet doc/src/snippets/declarative/rectangle/rect-border-width.qml 0 + + \clearfloat + Here, the innermost rectangle's border is clipped on the bottom and right edges by its + parent. To avoid this, the border width can be set to two instead of one. +*/ QSGPen *QSGRectangle::border() { Q_D(QSGRectangle); return d->getPen(); } +/*! + \qmlproperty Gradient QtQuick2::Rectangle::gradient + + The gradient to use to fill the rectangle. + + This property allows for the construction of simple vertical gradients. + Other gradients may by formed by adding rotation to the rectangle. + + \div {class="float-left"} + \inlineimage declarative-rect_gradient.png + \enddiv + + \snippet doc/src/snippets/declarative/rectangle/rectangle-gradient.qml rectangles + \clearfloat + + If both a gradient and a color are specified, the gradient will be used. + + \sa Gradient, color +*/ QSGGradient *QSGRectangle::gradient() const { Q_D(const QSGRectangle); @@ -221,6 +411,14 @@ void QSGRectangle::setGradient(QSGGradient *gradient) update(); } +/*! + \qmlproperty real QtQuick2::Rectangle::radius + This property holds the corner radius used to draw a rounded rectangle. + + If radius is non-zero, the rectangle will be painted as a rounded rectangle, otherwise it will be + painted as a normal rectangle. The same radius is used by all 4 corners; there is currently + no way to specify different radii for different corners. +*/ qreal QSGRectangle::radius() const { Q_D(const QSGRectangle); @@ -238,6 +436,26 @@ void QSGRectangle::setRadius(qreal radius) emit radiusChanged(); } +/*! + \qmlproperty color QtQuick2::Rectangle::color + This property holds the color used to fill the rectangle. + + The default color is white. + + \div {class="float-right"} + \inlineimage rect-color.png + \enddiv + + The following example shows rectangles with colors specified + using hexadecimal and named color notation: + + \snippet doc/src/snippets/declarative/rectangle/rectangle-colors.qml rectangles + + \clearfloat + If both a gradient and a color are specified, the gradient will be used. + + \sa gradient +*/ QColor QSGRectangle::color() const { Q_D(const QSGRectangle); @@ -297,6 +515,21 @@ QSGNode *QSGRectangle::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *da return rectangle; } +/*! + \qmlproperty bool QtQuick2::Rectangle::smooth + + Set this property if you want the item to be smoothly scaled or + transformed. Smooth filtering gives better visual quality, but is slower. If + the item is displayed at its natural size, this property has no visual or + performance effect. + + \note Generally scaling artifacts are only visible if the item is stationary on + the screen. A common pattern when animating an item is to disable smooth + filtering at the beginning of the animation and reenable it at the conclusion. + + \image rect-smooth.png + On this image, smooth is turned off on the top half and on on the bottom half. +*/ QRectF QSGRectangle::boundingRect() const { diff --git a/src/declarative/items/qsgrepeater.cpp b/src/declarative/items/qsgrepeater.cpp index cdada2d59d..bdb3a3d98a 100644 --- a/src/declarative/items/qsgrepeater.cpp +++ b/src/declarative/items/qsgrepeater.cpp @@ -60,6 +60,90 @@ QSGRepeaterPrivate::~QSGRepeaterPrivate() delete model; } +/*! + \qmlclass Repeater QSGRepeater + \inqmlmodule QtQuick 2 + \ingroup qml-utility-elements + \inherits Item + + \brief The Repeater element allows you to repeat an Item-based component using a model. + + The Repeater element is used to create a large number of + similar items. Like other view elements, a Repeater has a \l model and a \l delegate: + for each entry in the model, the delegate is instantiated + in a context seeded with data from the model. A Repeater item is usually + enclosed in a positioner element such as \l Row or \l Column to visually + position the multiple delegate items created by the Repeater. + + The following Repeater creates three instances of a \l Rectangle item within + a \l Row: + + \snippet doc/src/snippets/declarative/repeaters/repeater.qml import + \codeline + \snippet doc/src/snippets/declarative/repeaters/repeater.qml simple + + \image repeater-simple.png + + A Repeater's \l model can be any of the supported \l {qmlmodels}{data models}. + Additionally, like delegates for other views, a Repeater delegate can access + its index within the repeater, as well as the model data relevant to the + delegate. See the \l delegate property documentation for details. + + Items instantiated by the Repeater are inserted, in order, as + children of the Repeater's parent. The insertion starts immediately after + the repeater's position in its parent stacking list. This allows + a Repeater to be used inside a layout. For example, the following Repeater's + items are stacked between a red rectangle and a blue rectangle: + + \snippet doc/src/snippets/declarative/repeaters/repeater.qml layout + + \image repeater.png + + + \note A Repeater item owns all items it instantiates. Removing or dynamically destroying + an item created by a Repeater results in unpredictable behavior. + + + \section2 Considerations when using Repeater + + The Repeater element creates all of its delegate items when the repeater is first + created. This can be inefficient if there are a large number of delegate items and + not all of the items are required to be visible at the same time. If this is the case, + consider using other view elements like ListView (which only creates delegate items + when they are scrolled into view) or use the \l {Dynamic Object Creation} methods to + create items as they are required. + + Also, note that Repeater is \l {Item}-based, and can only repeat \l {Item}-derived objects. + For example, it cannot be used to repeat QtObjects: + \badcode + Item { + //XXX does not work! Can't repeat QtObject as it doesn't derive from Item. + Repeater { + model: 10 + QtObject {} + } + } + \endcode + */ + +/*! + \qmlsignal QtQuick2::Repeater::onItemAdded(int index, Item item) + + This handler is called when an item is added to the repeater. The \a index + parameter holds the index at which the item has been inserted within the + repeater, and the \a item parameter holds the \l Item that has been added. +*/ + +/*! + \qmlsignal QtQuick2::Repeater::onItemRemoved(int index, Item item) + + This handler is called when an item is removed from the repeater. The \a index + parameter holds the index at which the item was removed from the repeater, + and the \a item parameter holds the \l Item that was removed. + + Do not keep a reference to \a item if it was created by this repeater, as + in these cases it will be deleted shortly after the handler is called. +*/ QSGRepeater::QSGRepeater(QSGItem *parent) : QSGItem(*(new QSGRepeaterPrivate), parent) { @@ -69,6 +153,24 @@ QSGRepeater::~QSGRepeater() { } +/*! + \qmlproperty any QtQuick2::Repeater::model + + The model providing data for the repeater. + + This property can be set to any of the supported \l {qmlmodels}{data models}: + + \list + \o A number that indicates the number of delegates to be created by the repeater + \o A model (e.g. a ListModel item, or a QAbstractItemModel subclass) + \o A string list + \o An object list + \endlist + + The type of model affects the properties that are exposed to the \l delegate. + + \sa {qmlmodels}{Data Models} +*/ QVariant QSGRepeater::model() const { Q_D(const QSGRepeater); @@ -124,6 +226,39 @@ void QSGRepeater::setModel(const QVariant &model) emit countChanged(); } +/*! + \qmlproperty Component QtQuick2::Repeater::delegate + \default + + The delegate provides a template defining each item instantiated by the repeater. + + Delegates are exposed to a read-only \c index property that indicates the index + of the delegate within the repeater. For example, the following \l Text delegate + displays the index of each repeated item: + + \table + \row + \o \snippet doc/src/snippets/declarative/repeaters/repeater.qml index + \o \image repeater-index.png + \endtable + + If the \l model is a \l{QStringList-based model}{string list} or + \l{QObjectList-based model}{object list}, the delegate is also exposed to + a read-only \c modelData property that holds the string or object data. For + example: + + \table + \row + \o \snippet doc/src/snippets/declarative/repeaters/repeater.qml modeldata + \o \image repeater-modeldata.png + \endtable + + If the \l model is a model object (such as a \l ListModel) the delegate + can access all model roles as named properties, in the same way that delegates + do for view classes like ListView. + + \sa {QML Data Models} + */ QDeclarativeComponent *QSGRepeater::delegate() const { Q_D(const QSGRepeater); @@ -153,6 +288,11 @@ void QSGRepeater::setDelegate(QDeclarativeComponent *delegate) } } +/*! + \qmlproperty int QtQuick2::Repeater::count + + This property holds the number of items in the repeater. +*/ int QSGRepeater::count() const { Q_D(const QSGRepeater); @@ -161,6 +301,12 @@ int QSGRepeater::count() const return 0; } +/*! + \qmlmethod Item QtQuick2::Repeater::itemAt(index) + + Returns the \l Item that has been created at the given \a index, or \c null + if no item exists at \a index. +*/ QSGItem *QSGRepeater::itemAt(int index) const { Q_D(const QSGRepeater); diff --git a/src/declarative/items/qsgtext.cpp b/src/declarative/items/qsgtext.cpp index f3b2752479..a844f79cc6 100644 --- a/src/declarative/items/qsgtext.cpp +++ b/src/declarative/items/qsgtext.cpp @@ -694,6 +694,49 @@ QPixmap QSGTextPrivate::drawOutline(const QPixmap &source, const QPixmap &styleS return img; } +/*! + \qmlclass Text QSGText + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The Text item allows you to add formatted text to a scene. + \inherits Item + + Text items can display both plain and rich text. For example, red text with + a specific font and size can be defined like this: + + \qml + Text { + text: "Hello World!" + font.family: "Helvetica" + font.pointSize: 24 + color: "red" + } + \endqml + + Rich text is defined using HTML-style markup: + + \qml + Text { + text: "<b>Hello</b> <i>World!</i>" + } + \endqml + + \image declarative-text.png + + If height and width are not explicitly set, Text will attempt to determine how + much room is needed and set it accordingly. Unless \l wrapMode is set, it will always + prefer width to height (all text will be placed on a single line). + + The \l elide property can alternatively be used to fit a single line of + plain text to a set width. + + Note that the \l{Supported HTML Subset} is limited. Also, if the text contains + HTML img tags that load remote images, the text is reloaded. + + Text provides read-only text. For editable text, see \l TextEdit. + + \sa {declarative/text/fonts}{Fonts example} +*/ QSGText::QSGText(QSGItem *parent) : QSGImplicitSizeItem(*(new QSGTextPrivate), parent) { @@ -705,6 +748,149 @@ QSGText::~QSGText() { } +/*! + \qmlproperty bool QtQuick2::Text::clip + This property holds whether the text is clipped. + + Note that if the text does not fit in the bounding rectangle it will be abruptly chopped. + + If you want to display potentially long text in a limited space, you probably want to use \c elide instead. +*/ + +/*! + \qmlproperty bool QtQuick2::Text::smooth + + This property holds whether the text is smoothly scaled or transformed. + + Smooth filtering gives better visual quality, but is slower. If + the item is displayed at its natural size, this property has no visual or + performance effect. + + \note Generally scaling artifacts are only visible if the item is stationary on + the screen. A common pattern when animating an item is to disable smooth + filtering at the beginning of the animation and reenable it at the conclusion. +*/ + +/*! + \qmlsignal QtQuick2::Text::onLinkActivated(string link) + + This handler is called when the user clicks on a link embedded in the text. + The link must be in rich text or HTML format and the + \a link string provides access to the particular link. + + \snippet doc/src/snippets/declarative/text/onLinkActivated.qml 0 + + The example code will display the text + "The main website is at \l{http://qt.nokia.com}{Nokia Qt DF}." + + Clicking on the highlighted link will output + \tt{http://qt.nokia.com link activated} to the console. +*/ + +/*! + \qmlproperty string QtQuick2::Text::font.family + + Sets the family name of the font. + + The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]". + If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. + If the family isn't available a family will be set using the font matching algorithm. +*/ + +/*! + \qmlproperty bool QtQuick2::Text::font.bold + + Sets whether the font weight is bold. +*/ + +/*! + \qmlproperty enumeration QtQuick2::Text::font.weight + + Sets the font's weight. + + The weight can be one of: + \list + \o Font.Light + \o Font.Normal - the default + \o Font.DemiBold + \o Font.Bold + \o Font.Black + \endlist + + \qml + Text { text: "Hello"; font.weight: Font.DemiBold } + \endqml +*/ + +/*! + \qmlproperty bool QtQuick2::Text::font.italic + + Sets whether the font has an italic style. +*/ + +/*! + \qmlproperty bool QtQuick2::Text::font.underline + + Sets whether the text is underlined. +*/ + +/*! + \qmlproperty bool QtQuick2::Text::font.strikeout + + Sets whether the font has a strikeout style. +*/ + +/*! + \qmlproperty real QtQuick2::Text::font.pointSize + + Sets the font size in points. The point size must be greater than zero. +*/ + +/*! + \qmlproperty int QtQuick2::Text::font.pixelSize + + Sets the font size in pixels. + + Using this function makes the font device dependent. + Use \c pointSize to set the size of the font in a device independent manner. +*/ + +/*! + \qmlproperty real QtQuick2::Text::font.letterSpacing + + Sets the letter spacing for the font. + + Letter spacing changes the default spacing between individual letters in the font. + A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing. +*/ + +/*! + \qmlproperty real QtQuick2::Text::font.wordSpacing + + Sets the word spacing for the font. + + Word spacing changes the default spacing between individual words. + A positive value increases the word spacing by a corresponding amount of pixels, + while a negative value decreases the inter-word spacing accordingly. +*/ + +/*! + \qmlproperty enumeration QtQuick2::Text::font.capitalization + + Sets the capitalization for the text. + + \list + \o Font.MixedCase - This is the normal text rendering option where no capitalization change is applied. + \o Font.AllUppercase - This alters the text to be rendered in all uppercase type. + \o Font.AllLowercase - This alters the text to be rendered in all lowercase type. + \o Font.SmallCaps - This alters the text to be rendered in small-caps type. + \o Font.Capitalize - This alters the text to be rendered with the first character of each word as an uppercase character. + \endlist + + \qml + Text { text: "Hello"; font.capitalization: Font.AllLowercase } + \endqml +*/ QFont QSGText::font() const { Q_D(const QSGText); @@ -735,6 +921,14 @@ void QSGText::setFont(const QFont &font) emit fontChanged(d->sourceFont); } +/*! + \qmlproperty string QtQuick2::Text::text + + The text to display. Text supports both plain and rich text strings. + + The item will try to automatically determine whether the text should + be treated as rich text. This determination is made using Qt::mightBeRichText(). +*/ QString QSGText::text() const { Q_D(const QSGText); @@ -764,6 +958,27 @@ void QSGText::setText(const QString &n) emit textChanged(d->text); } +/*! + \qmlproperty color QtQuick2::Text::color + + The text color. + + An example of green text defined using hexadecimal notation: + \qml + Text { + color: "#00FF00" + text: "green text" + } + \endqml + + An example of steel blue text defined using an SVG color name: + \qml + Text { + color: "steelblue" + text: "blue text" + } + \endqml +*/ QColor QSGText::color() const { Q_D(const QSGText); @@ -780,7 +995,30 @@ void QSGText::setColor(const QColor &color) d->invalidateImageCache(); emit colorChanged(d->color); } +/*! + \qmlproperty enumeration QtQuick2::Text::style + + Set an additional text style. + + Supported text styles are: + \list + \o Text.Normal - the default + \o Text.Outline + \o Text.Raised + \o Text.Sunken + \endlist + + \qml + Row { + Text { font.pointSize: 24; text: "Normal" } + Text { font.pointSize: 24; text: "Raised"; style: Text.Raised; styleColor: "#AAAAAA" } + Text { font.pointSize: 24; text: "Outline";style: Text.Outline; styleColor: "red" } + Text { font.pointSize: 24; text: "Sunken"; style: Text.Sunken; styleColor: "#AAAAAA" } + } + \endqml + \image declarative-textstyle.png +*/ QSGText::TextStyle QSGText::style() const { Q_D(const QSGText); @@ -801,6 +1039,21 @@ void QSGText::setStyle(QSGText::TextStyle style) emit styleChanged(d->style); } +/*! + \qmlproperty color QtQuick2::Text::styleColor + + Defines the secondary color used by text styles. + + \c styleColor is used as the outline color for outlined text, and as the + shadow color for raised or sunken text. If no style has been set, it is not + used at all. + + \qml + Text { font.pointSize: 18; text: "hello"; style: Text.Raised; styleColor: "gray" } + \endqml + + \sa style + */ QColor QSGText::styleColor() const { Q_D(const QSGText); @@ -818,6 +1071,30 @@ void QSGText::setStyleColor(const QColor &color) emit styleColorChanged(d->styleColor); } +/*! + \qmlproperty enumeration QtQuick2::Text::horizontalAlignment + \qmlproperty enumeration QtQuick2::Text::verticalAlignment + \qmlproperty enumeration QtQuick2::Text::effectiveHorizontalAlignment + + Sets the horizontal and vertical alignment of the text within the Text items + width and height. By default, the text is vertically aligned to the top. Horizontal + alignment follows the natural alignment of the text, for example text that is read + from left to right will be aligned to the left. + + The valid values for \c horizontalAlignment are \c Text.AlignLeft, \c Text.AlignRight, \c Text.AlignHCenter and + \c Text.AlignJustify. The valid values for \c verticalAlignment are \c Text.AlignTop, \c Text.AlignBottom + and \c Text.AlignVCenter. + + Note that for a single line of text, the size of the text is the area of the text. In this common case, + all alignments are equivalent. If you want the text to be, say, centered in its parent, then you will + need to either modify the Item::anchors, or set horizontalAlignment to Text.AlignHCenter and bind the width to + that of the parent. + + When using the attached property LayoutMirroring::enabled to mirror application + layouts, the horizontal alignment of text will also be mirrored. However, the property + \c horizontalAlignment will remain unchanged. To query the effective horizontal alignment + of Text, use the read-only property \c effectiveHorizontalAlignment. +*/ QSGText::HAlignment QSGText::hAlign() const { Q_D(const QSGText); @@ -917,6 +1194,19 @@ void QSGText::setVAlign(VAlignment align) emit verticalAlignmentChanged(align); } +/*! + \qmlproperty enumeration QtQuick2::Text::wrapMode + + Set this property to wrap the text to the Text item's width. The text will only + wrap if an explicit width has been set. wrapMode can be one of: + + \list + \o Text.NoWrap (default) - no wrapping will be performed. If the text contains insufficient newlines, then \l paintedWidth will exceed a set width. + \o Text.WordWrap - wrapping is done on word boundaries only. If a word is too long, \l paintedWidth will exceed a set width. + \o Text.WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word. + \o Text.Wrap - if possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word. + \endlist +*/ QSGText::WrapMode QSGText::wrapMode() const { Q_D(const QSGText); @@ -935,18 +1225,48 @@ void QSGText::setWrapMode(WrapMode mode) emit wrapModeChanged(); } +/*! + \qmlproperty int QtQuick2::Text::lineCount + + Returns the number of lines visible in the text item. + + This property is not supported for rich text. + + \sa maximumLineCount +*/ int QSGText::lineCount() const { Q_D(const QSGText); return d->lineCount; } +/*! + \qmlproperty bool QtQuick2::Text::truncated + + Returns true if the text has been truncated due to \l maximumLineCount + or \l elide. + + This property is not supported for rich text. + + \sa maximumLineCount, elide +*/ bool QSGText::truncated() const { Q_D(const QSGText); return d->truncated; } +/*! + \qmlproperty int QtQuick2::Text::maximumLineCount + + 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. + By default, this is the value of the largest possible integer. + + This property is not supported for rich text. + + \sa lineCount, elide +*/ int QSGText::maximumLineCount() const { Q_D(const QSGText); @@ -976,6 +1296,61 @@ void QSGText::resetMaximumLineCount() } } +/*! + \qmlproperty enumeration QtQuick2::Text::textFormat + + The way the text property should be displayed. + + Supported text formats are: + + \list + \o Text.AutoText (default) + \o Text.PlainText + \o Text.RichText + \o Text.StyledText + \endlist + + If the text format is \c Text.AutoText the text element + will automatically determine whether the text should be treated as + rich text. This determination is made using Qt::mightBeRichText(). + + Text.StyledText is an optimized format supporting some basic text + styling markup, in the style of html 3.2: + + \code + <font size="4" color="#ff0000">font size and color</font> + <b>bold</b> + <i>italic</i> + <br> + > < & + \endcode + + \c Text.StyledText parser is strict, requiring tags to be correctly nested. + + \table + \row + \o + \qml +Column { + Text { + font.pointSize: 24 + text: "<b>Hello</b> <i>World!</i>" + } + Text { + font.pointSize: 24 + textFormat: Text.RichText + text: "<b>Hello</b> <i>World!</i>" + } + Text { + font.pointSize: 24 + textFormat: Text.PlainText + text: "<b>Hello</b> <i>World!</i>" + } +} + \endqml + \o \image declarative-textformat.png + \endtable +*/ QSGText::TextFormat QSGText::textFormat() const { Q_D(const QSGText); @@ -1002,6 +1377,31 @@ void QSGText::setTextFormat(TextFormat format) emit textFormatChanged(d->format); } +/*! + \qmlproperty enumeration QtQuick2::Text::elide + + Set this property to elide parts of the text fit to the Text item's width. + The text will only elide if an explicit width has been set. + + This property cannot be used with rich text. + + Eliding can be: + \list + \o Text.ElideNone - the default + \o Text.ElideLeft + \o Text.ElideMiddle + \o Text.ElideRight + \endlist + + If this property is set to Text.ElideRight, it can be used with multiline + text. The text will only elide if maximumLineCount has been set. + + If the text is a multi-length string, and the mode is not \c Text.ElideNone, + the first string that fits will be used, otherwise the last will be elided. + + Multi-length strings are ordered from longest to shortest, separated by the + Unicode "String Terminator" character \c U009C (write this in QML with \c{"\u009C"} or \c{"\x9C"}). +*/ QSGText::TextElideMode QSGText::elideMode() const { Q_D(const QSGText); @@ -1156,18 +1556,39 @@ bool QSGText::event(QEvent *e) } } +/*! + \qmlproperty real QtQuick2::Text::paintedWidth + + Returns the width of the text, including width past the width + which is covered due to insufficient wrapping if WrapMode is set. +*/ qreal QSGText::paintedWidth() const { Q_D(const QSGText); return d->paintedSize.width(); } +/*! + \qmlproperty real QtQuick2::Text::paintedHeight + + Returns the height of the text, including height past the height + which is covered due to there being more text than fits in the set height. +*/ qreal QSGText::paintedHeight() const { Q_D(const QSGText); return d->paintedSize.height(); } +/*! + \qmlproperty real QtQuick2::Text::lineHeight + + Sets the line height for the text. + The value can be in pixels or a multiplier depending on lineHeightMode. + + The default value is a multiplier of 1.0. + The line height must be a positive value. +*/ qreal QSGText::lineHeight() const { Q_D(const QSGText); @@ -1186,6 +1607,18 @@ void QSGText::setLineHeight(qreal lineHeight) emit lineHeightChanged(lineHeight); } +/*! + \qmlproperty enumeration QtQuick2::Text::lineHeightMode + + This property determines how the line height is specified. + The possible values are: + + \list + \o Text.ProportionalHeight (default) - this sets the spacing proportional to the + line (as a multiplier). For example, set to 2 for double spacing. + \o Text.FixedHeight - this sets the line height to a fixed line height (in pixels). + \endlist +*/ QSGText::LineHeightMode QSGText::lineHeightMode() const { Q_D(const QSGText); diff --git a/src/declarative/items/qsgtextedit.cpp b/src/declarative/items/qsgtextedit.cpp index 4797630441..8e76a8bffd 100644 --- a/src/declarative/items/qsgtextedit.cpp +++ b/src/declarative/items/qsgtextedit.cpp @@ -59,7 +59,57 @@ QT_BEGIN_NAMESPACE QWidgetPrivate *qt_widget_private(QWidget *widget); +/*! + \qmlclass TextEdit QSGTextEdit + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The TextEdit item displays multiple lines of editable formatted text. + \inherits Item + + The TextEdit item displays a block of editable, formatted text. + + It can display both plain and rich text. For example: + + \qml +TextEdit { + width: 240 + text: "<b>Hello</b> <i>World!</i>" + font.family: "Helvetica" + font.pointSize: 20 + color: "blue" + focus: true +} + \endqml + + \image declarative-textedit.gif + + Setting \l {Item::focus}{focus} to \c true enables the TextEdit item to receive keyboard focus. + + Note that the TextEdit does not implement scrolling, following the cursor, or other behaviors specific + to a look-and-feel. For example, to add flickable scrolling that follows the cursor: + + \snippet snippets/declarative/texteditor.qml 0 + + A particular look-and-feel might use smooth scrolling (eg. using SmoothedFollow), might have a visible + scrollbar, or a scrollbar that fades in to show location, etc. + + Clipboard support is provided by the cut(), copy(), and paste() functions, and the selection can + be handled in a traditional "mouse" mechanism by setting selectByMouse, or handled completely + from QML by manipulating selectionStart and selectionEnd, or using selectAll() or selectWord(). + + You can translate between cursor positions (characters from the start of the document) and pixel + points using positionAt() and positionToRectangle(). + + \sa Text, TextInput, {declarative/text/textselection}{Text Selection example} +*/ +/*! + \qmlsignal QtQuick2::TextEdit::onLinkActivated(string link) + + This handler is called when the user clicks on a link embedded in the text. + The link must be in rich text or HTML format and the + \a link string provides access to the particular link. +*/ QSGTextEdit::QSGTextEdit(QSGItem *parent) : QSGImplicitSizePaintedItem(*(new QSGTextEditPrivate), parent) { @@ -79,6 +129,119 @@ QString QSGTextEdit::text() const return d->document->toPlainText(); } +/*! + \qmlproperty string QtQuick2::TextEdit::font.family + + Sets the family name of the font. + + The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]". + If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. + If the family isn't available a family will be set using the font matching algorithm. +*/ + +/*! + \qmlproperty bool QtQuick2::TextEdit::font.bold + + Sets whether the font weight is bold. +*/ + +/*! + \qmlproperty enumeration QtQuick2::TextEdit::font.weight + + Sets the font's weight. + + The weight can be one of: + \list + \o Font.Light + \o Font.Normal - the default + \o Font.DemiBold + \o Font.Bold + \o Font.Black + \endlist + + \qml + TextEdit { text: "Hello"; font.weight: Font.DemiBold } + \endqml +*/ + +/*! + \qmlproperty bool QtQuick2::TextEdit::font.italic + + Sets whether the font has an italic style. +*/ + +/*! + \qmlproperty bool QtQuick2::TextEdit::font.underline + + Sets whether the text is underlined. +*/ + +/*! + \qmlproperty bool QtQuick2::TextEdit::font.strikeout + + Sets whether the font has a strikeout style. +*/ + +/*! + \qmlproperty real QtQuick2::TextEdit::font.pointSize + + Sets the font size in points. The point size must be greater than zero. +*/ + +/*! + \qmlproperty int QtQuick2::TextEdit::font.pixelSize + + Sets the font size in pixels. + + Using this function makes the font device dependent. Use + \l{TextEdit::font.pointSize} to set the size of the font in a + device independent manner. +*/ + +/*! + \qmlproperty real QtQuick2::TextEdit::font.letterSpacing + + Sets the letter spacing for the font. + + Letter spacing changes the default spacing between individual letters in the font. + A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing. +*/ + +/*! + \qmlproperty real QtQuick2::TextEdit::font.wordSpacing + + Sets the word spacing for the font. + + Word spacing changes the default spacing between individual words. + A positive value increases the word spacing by a corresponding amount of pixels, + while a negative value decreases the inter-word spacing accordingly. +*/ + +/*! + \qmlproperty enumeration QtQuick2::TextEdit::font.capitalization + + Sets the capitalization for the text. + + \list + \o Font.MixedCase - This is the normal text rendering option where no capitalization change is applied. + \o Font.AllUppercase - This alters the text to be rendered in all uppercase type. + \o Font.AllLowercase - This alters the text to be rendered in all lowercase type. + \o Font.SmallCaps - This alters the text to be rendered in small-caps type. + \o Font.Capitalize - This alters the text to be rendered with the first character of each word as an uppercase character. + \endlist + + \qml + TextEdit { text: "Hello"; font.capitalization: Font.AllLowercase } + \endqml +*/ + +/*! + \qmlproperty string QtQuick2::TextEdit::text + + The text to display. If the text format is AutoText the text edit will + automatically determine whether the text should be treated as + rich text. This determination is made using Qt::mightBeRichText(). +*/ void QSGTextEdit::setText(const QString &text) { Q_D(QSGTextEdit); @@ -98,6 +261,45 @@ void QSGTextEdit::setText(const QString &text) q_textChanged(); } +/*! + \qmlproperty enumeration QtQuick2::TextEdit::textFormat + + The way the text property should be displayed. + + \list + \o TextEdit.AutoText + \o TextEdit.PlainText + \o TextEdit.RichText + \endlist + + The default is TextEdit.AutoText. If the text format is TextEdit.AutoText the text edit + will automatically determine whether the text should be treated as + rich text. This determination is made using Qt::mightBeRichText(). + + \table + \row + \o + \qml +Column { + TextEdit { + font.pointSize: 24 + text: "<b>Hello</b> <i>World!</i>" + } + TextEdit { + font.pointSize: 24 + textFormat: TextEdit.RichText + text: "<b>Hello</b> <i>World!</i>" + } + TextEdit { + font.pointSize: 24 + textFormat: TextEdit.PlainText + text: "<b>Hello</b> <i>World!</i>" + } +} + \endqml + \o \image declarative-textformat.png + \endtable +*/ QSGTextEdit::TextFormat QSGTextEdit::textFormat() const { Q_D(const QSGTextEdit); @@ -161,6 +363,21 @@ void QSGTextEdit::setFont(const QFont &font) emit fontChanged(d->sourceFont); } +/*! + \qmlproperty color QtQuick2::TextEdit::color + + The text color. + + \qml + // green text using hexadecimal notation + TextEdit { color: "#00FF00" } + \endqml + + \qml + // steelblue text using SVG color name + TextEdit { color: "steelblue" } + \endqml +*/ QColor QSGTextEdit::color() const { Q_D(const QSGTextEdit); @@ -181,6 +398,11 @@ void QSGTextEdit::setColor(const QColor &color) emit colorChanged(d->color); } +/*! + \qmlproperty color QtQuick2::TextEdit::selectionColor + + The text highlight color, used behind selections. +*/ QColor QSGTextEdit::selectionColor() const { Q_D(const QSGTextEdit); @@ -201,6 +423,11 @@ void QSGTextEdit::setSelectionColor(const QColor &color) emit selectionColorChanged(d->selectionColor); } +/*! + \qmlproperty color QtQuick2::TextEdit::selectedTextColor + + The selected text color, used in selections. +*/ QColor QSGTextEdit::selectedTextColor() const { Q_D(const QSGTextEdit); @@ -221,6 +448,36 @@ void QSGTextEdit::setSelectedTextColor(const QColor &color) emit selectedTextColorChanged(d->selectedTextColor); } +/*! + \qmlproperty enumeration QtQuick2::TextEdit::horizontalAlignment + \qmlproperty enumeration QtQuick2::TextEdit::verticalAlignment + \qmlproperty enumeration QtQuick2::TextEdit::effectiveHorizontalAlignment + + Sets the horizontal and vertical alignment of the text within the TextEdit item's + width and height. By default, the text alignment follows the natural alignment + of the text, for example text that is read from left to right will be aligned to + the left. + + Valid values for \c horizontalAlignment are: + \list + \o TextEdit.AlignLeft (default) + \o TextEdit.AlignRight + \o TextEdit.AlignHCenter + \o TextEdit.AlignJustify + \endlist + + Valid values for \c verticalAlignment are: + \list + \o TextEdit.AlignTop (default) + \o TextEdit.AlignBottom + \o TextEdit.AlignVCenter + \endlist + + When using the attached property LayoutMirroring::enabled to mirror application + layouts, the horizontal alignment of text will also be mirrored. However, the property + \c horizontalAlignment will remain unchanged. To query the effective horizontal alignment + of TextEdit, use the read-only property \c effectiveHorizontalAlignment. +*/ QSGTextEdit::HAlignment QSGTextEdit::hAlign() const { Q_D(const QSGTextEdit); @@ -320,7 +577,21 @@ void QSGTextEdit::setVAlign(QSGTextEdit::VAlignment alignment) moveCursorDelegate(); emit verticalAlignmentChanged(d->vAlign); } +/*! + \qmlproperty enumeration QtQuick2::TextEdit::wrapMode + Set this property to wrap the text to the TextEdit item's width. + The text will only wrap if an explicit width has been set. + + \list + \o TextEdit.NoWrap - no wrapping will be performed. If the text contains insufficient newlines, then implicitWidth will exceed a set width. + \o TextEdit.WordWrap - wrapping is done on word boundaries only. If a word is too long, implicitWidth will exceed a set width. + \o TextEdit.WrapAnywhere - wrapping is done at any point on a line, even if it occurs in the middle of a word. + \o TextEdit.Wrap - if possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word. + \endlist + + The default is TextEdit.NoWrap. If you set a width, consider using TextEdit.Wrap. +*/ QSGTextEdit::WrapMode QSGTextEdit::wrapMode() const { Q_D(const QSGTextEdit); @@ -338,24 +609,48 @@ void QSGTextEdit::setWrapMode(WrapMode mode) emit wrapModeChanged(); } +/*! + \qmlproperty int QtQuick2::TextEdit::lineCount + + Returns the total number of lines in the textEdit item. +*/ int QSGTextEdit::lineCount() const { Q_D(const QSGTextEdit); return d->lineCount; } +/*! + \qmlproperty real QtQuick2::TextEdit::paintedWidth + + Returns the width of the text, including the width past the width + which is covered due to insufficient wrapping if \l wrapMode is set. +*/ qreal QSGTextEdit::paintedWidth() const { Q_D(const QSGTextEdit); return d->paintedSize.width(); } +/*! + \qmlproperty real QtQuick2::TextEdit::paintedHeight + + Returns the height of the text, including the height past the height + that is covered if the text does not fit within the set height. +*/ qreal QSGTextEdit::paintedHeight() const { Q_D(const QSGTextEdit); return d->paintedSize.height(); } +/*! + \qmlmethod rectangle QtQuick2::TextEdit::positionToRectangle(position) + + Returns the rectangle at the given \a position in the text. The x, y, + and height properties correspond to the cursor that would describe + that position. +*/ QRectF QSGTextEdit::positionToRectangle(int pos) const { Q_D(const QSGTextEdit); @@ -365,6 +660,14 @@ QRectF QSGTextEdit::positionToRectangle(int pos) const } +/*! + \qmlmethod int QtQuick2::TextEdit::positionAt(int x, int y) + + Returns the text position closest to pixel position (\a x, \a y). + + Position 0 is before the first character, position 1 is after the first character + but before the second, and so on until position \l {text}.length, which is after all characters. +*/ int QSGTextEdit::positionAt(int x, int y) const { Q_D(const QSGTextEdit); @@ -388,6 +691,43 @@ int QSGTextEdit::positionAt(int x, int y) const return r; } +/*! + \qmlmethod void QtQuick2::TextEdit::moveCursorSelection(int position, SelectionMode mode = TextEdit.SelectCharacters) + + Moves the cursor to \a position and updates the selection according to the optional \a mode + parameter. (To only move the cursor, set the \l cursorPosition property.) + + When this method is called it additionally sets either the + selectionStart or the selectionEnd (whichever was at the previous cursor position) + to the specified position. This allows you to easily extend and contract the selected + text range. + + The selection mode specifies whether the selection is updated on a per character or a per word + basis. If not specified the selection mode will default to TextEdit.SelectCharacters. + + \list + \o TextEdit.SelectCharacters - Sets either the selectionStart or selectionEnd (whichever was at + the previous cursor position) to the specified position. + \o TextEdit.SelectWords - Sets the selectionStart and selectionEnd to include all + words between the specified postion and the previous cursor position. Words partially in the + range are included. + \endlist + + For example, take this sequence of calls: + + \code + cursorPosition = 5 + moveCursorSelection(9, TextEdit.SelectCharacters) + moveCursorSelection(7, TextEdit.SelectCharacters) + \endcode + + This moves the cursor to position 5, extend the selection end from 5 to 9 + and then retract the selection end from 9 to 7, leaving the text from position 5 to 7 + selected (the 6th and 7th characters). + + The same sequence with TextEdit.SelectWords will extend the selection start to a word boundary + before or on position 5 and extend the selection end to a word boundary on or past position 9. +*/ void QSGTextEdit::moveCursorSelection(int pos) { //Note that this is the same as setCursorPosition but with the KeepAnchor flag set @@ -448,6 +788,13 @@ void QSGTextEdit::moveCursorSelection(int pos, SelectionMode mode) d->control->setTextCursor(cursor); } +/*! + \qmlproperty bool QtQuick2::TextEdit::cursorVisible + If true the text edit shows a cursor. + + This property is set and unset when the text edit gets active focus, but it can also + be set directly (useful, for example, if a KeyProxy might forward keys to it). +*/ bool QSGTextEdit::isCursorVisible() const { Q_D(const QSGTextEdit); @@ -467,6 +814,10 @@ void QSGTextEdit::setCursorVisible(bool on) emit cursorVisibleChanged(d->cursorVisible); } +/*! + \qmlproperty int QtQuick2::TextEdit::cursorPosition + The position of the cursor in the TextEdit. +*/ int QSGTextEdit::cursorPosition() const { Q_D(const QSGTextEdit); @@ -485,6 +836,19 @@ void QSGTextEdit::setCursorPosition(int pos) d->control->setTextCursor(cursor); } +/*! + \qmlproperty Component QtQuick2::TextEdit::cursorDelegate + The delegate for the cursor in the TextEdit. + + If you set a cursorDelegate for a TextEdit, this delegate will be used for + drawing the cursor instead of the standard cursor. An instance of the + delegate will be created and managed by the text edit when a cursor is + needed, and the x and y properties of delegate instance will be set so as + to be one pixel before the top left of the current character. + + Note that the root item of the delegate component must be a QDeclarativeItem or + QDeclarativeItem derived item. +*/ QDeclarativeComponent* QSGTextEdit::cursorDelegate() const { Q_D(const QSGTextEdit); @@ -532,24 +896,64 @@ void QSGTextEdit::loadCursorDelegate() } } +/*! + \qmlproperty int QtQuick2::TextEdit::selectionStart + + The cursor position before the first character in the current selection. + + This property is read-only. To change the selection, use select(start,end), + selectAll(), or selectWord(). + + \sa selectionEnd, cursorPosition, selectedText +*/ int QSGTextEdit::selectionStart() const { Q_D(const QSGTextEdit); return d->control->textCursor().selectionStart(); } +/*! + \qmlproperty int QtQuick2::TextEdit::selectionEnd + + The cursor position after the last character in the current selection. + + This property is read-only. To change the selection, use select(start,end), + selectAll(), or selectWord(). + + \sa selectionStart, cursorPosition, selectedText +*/ int QSGTextEdit::selectionEnd() const { Q_D(const QSGTextEdit); return d->control->textCursor().selectionEnd(); } +/*! + \qmlproperty string QtQuick2::TextEdit::selectedText + + This read-only property provides the text currently selected in the + text edit. + + It is equivalent to the following snippet, but is faster and easier + to use. + \code + //myTextEdit is the id of the TextEdit + myTextEdit.text.toString().substring(myTextEdit.selectionStart, + myTextEdit.selectionEnd); + \endcode +*/ QString QSGTextEdit::selectedText() const { Q_D(const QSGTextEdit); return d->control->textCursor().selectedText(); } +/*! + \qmlproperty bool QtQuick2::TextEdit::activeFocusOnPress + + Whether the TextEdit should gain active focus on a mouse press. By default this is + set to true. +*/ bool QSGTextEdit::focusOnPress() const { Q_D(const QSGTextEdit); @@ -565,6 +969,12 @@ void QSGTextEdit::setFocusOnPress(bool on) emit activeFocusOnPressChanged(d->focusOnPress); } +/*! + \qmlproperty bool QtQuick2::TextEdit::persistentSelection + + Whether the TextEdit should keep the selection visible when it loses active focus to another + item in the scene. By default this is set to true; +*/ bool QSGTextEdit::persistentSelection() const { Q_D(const QSGTextEdit); @@ -580,6 +990,11 @@ void QSGTextEdit::setPersistentSelection(bool on) emit persistentSelectionChanged(d->persistentSelection); } +/* + \qmlproperty real QtQuick2::TextEdit::textMargin + + The margin, in pixels, around the text in the TextEdit. +*/ qreal QSGTextEdit::textMargin() const { Q_D(const QSGTextEdit); @@ -604,6 +1019,10 @@ void QSGTextEdit::geometryChanged(const QRectF &newGeometry, QSGPaintedItem::geometryChanged(newGeometry, oldGeometry); } +/*! + Ensures any delayed caching or data loading the class + needs to performed is complete. +*/ void QSGTextEdit::componentComplete() { Q_D(QSGTextEdit); @@ -615,7 +1034,16 @@ void QSGTextEdit::componentComplete() d->dirty = false; } } +/*! + \qmlproperty bool QtQuick2::TextEdit::selectByMouse + + Defaults to false. + If true, the user can use the mouse to select text in some + platform-specific way. Note that for some platforms this may + not be an appropriate interaction (eg. may conflict with how + the text needs to behave inside a Flickable. +*/ bool QSGTextEdit::selectByMouse() const { Q_D(const QSGTextEdit); @@ -636,6 +1064,18 @@ void QSGTextEdit::setSelectByMouse(bool on) } } +/*! + \qmlproperty enum QtQuick2::TextEdit::mouseSelectionMode + + Specifies how text should be selected using a mouse. + + \list + \o TextEdit.SelectCharacters - The selection is updated with individual characters. (Default) + \o TextEdit.SelectWords - The selection is updated with whole words. + \endlist + + This property only applies when \l selectByMouse is true. +*/ QSGTextEdit::SelectionMode QSGTextEdit::mouseSelectionMode() const { Q_D(const QSGTextEdit); @@ -652,6 +1092,14 @@ void QSGTextEdit::setMouseSelectionMode(SelectionMode mode) } } +/*! + \qmlproperty bool QtQuick2::TextEdit::readOnly + + Whether the user can interact with the TextEdit item. If this + property is set to true the text cannot be edited by user interaction. + + By default this property is false. +*/ void QSGTextEdit::setReadOnly(bool r) { Q_D(QSGTextEdit); @@ -677,18 +1125,32 @@ bool QSGTextEdit::isReadOnly() const return !(d->control->textInteractionFlags() & Qt::TextEditable); } +/*! + Sets how the text edit should interact with user input to the given + \a flags. +*/ void QSGTextEdit::setTextInteractionFlags(Qt::TextInteractionFlags flags) { Q_D(QSGTextEdit); d->control->setTextInteractionFlags(flags); } +/*! + Returns the flags specifying how the text edit should interact + with user input. +*/ Qt::TextInteractionFlags QSGTextEdit::textInteractionFlags() const { Q_D(const QSGTextEdit); return d->control->textInteractionFlags(); } +/*! + \qmlproperty rectangle QtQuick2::TextEdit::cursorRectangle + + The rectangle where the text cursor is rendered + within the text edit. Read-only. +*/ QRect QSGTextEdit::cursorRectangle() const { Q_D(const QSGTextEdit); @@ -729,6 +1191,11 @@ void QSGTextEdit::keyReleaseEvent(QKeyEvent *event) QSGPaintedItem::keyReleaseEvent(event); } +/*! + \qmlmethod void QtQuick2::TextEdit::deselect() + + Removes active text selection. +*/ void QSGTextEdit::deselect() { Q_D(QSGTextEdit); @@ -737,12 +1204,22 @@ void QSGTextEdit::deselect() d->control->setTextCursor(c); } +/*! + \qmlmethod void QtQuick2::TextEdit::selectAll() + + Causes all text to be selected. +*/ void QSGTextEdit::selectAll() { Q_D(QSGTextEdit); d->control->selectAll(); } +/*! + \qmlmethod void QtQuick2::TextEdit::selectWord() + + Causes the word closest to the current cursor position to be selected. +*/ void QSGTextEdit::selectWord() { Q_D(QSGTextEdit); @@ -751,6 +1228,19 @@ void QSGTextEdit::selectWord() d->control->setTextCursor(c); } +/*! + \qmlmethod void QtQuick2::TextEdit::select(int start, int end) + + Causes the text from \a start to \a end to be selected. + + If either start or end is out of range, the selection is not changed. + + After calling this, selectionStart will become the lesser + and selectionEnd will become the greater (regardless of the order passed + to this method). + + \sa selectionStart, selectionEnd +*/ void QSGTextEdit::select(int start, int end) { Q_D(QSGTextEdit); @@ -767,6 +1257,12 @@ void QSGTextEdit::select(int start, int end) updateSelectionMarkers(); } +/*! + \qmlmethod void QtQuick2::TextEdit::isRightToLeft(int start, int end) + + Returns true if the natural reading direction of the editor text + found between positions \a start and \a end is right to left. +*/ bool QSGTextEdit::isRightToLeft(int start, int end) { Q_D(QSGTextEdit); @@ -779,18 +1275,33 @@ bool QSGTextEdit::isRightToLeft(int start, int end) } #ifndef QT_NO_CLIPBOARD +/*! + \qmlmethod QtQuick2::TextEdit::cut() + + Moves the currently selected text to the system clipboard. +*/ void QSGTextEdit::cut() { Q_D(QSGTextEdit); d->control->cut(); } +/*! + \qmlmethod QtQuick2::TextEdit::copy() + + Copies the currently selected text to the system clipboard. +*/ void QSGTextEdit::copy() { Q_D(QSGTextEdit); d->control->copy(); } +/*! + \qmlmethod QtQuick2::TextEdit::paste() + + Replaces the currently selected text by the contents of the system clipboard. +*/ void QSGTextEdit::paste() { Q_D(QSGTextEdit); @@ -938,12 +1449,44 @@ void QSGTextEdit::updateImgCache(const QRectF &rf) update(r); } +/*! + \qmlproperty bool QtQuick2::TextEdit::smooth + + This property holds whether the text is smoothly scaled or transformed. + + Smooth filtering gives better visual quality, but is slower. If + the item is displayed at its natural size, this property has no visual or + performance effect. + + \note Generally scaling artifacts are only visible if the item is stationary on + the screen. A common pattern when animating an item is to disable smooth + filtering at the beginning of the animation and reenable it at the conclusion. +*/ + +/*! + \qmlproperty bool QtQuick2::TextEdit::canPaste + + Returns true if the TextEdit is writable and the content of the clipboard is + suitable for pasting into the TextEdit. +*/ bool QSGTextEdit::canPaste() const { Q_D(const QSGTextEdit); return d->canPaste; } +/*! + \qmlproperty bool QtQuick2::TextEdit::inputMethodComposing + + + This property holds whether the TextEdit has partial text input from an + input method. + + While it is composing an input method may rely on mouse or key events from + the TextEdit to edit or commit the partial text. This property can be used + to determine when to disable events handlers that may interfere with the + correct operation of an input method. +*/ bool QSGTextEdit::isInputMethodComposing() const { Q_D(const QSGTextEdit); @@ -1119,7 +1662,7 @@ void QSGTextEdit::updateSize() } else { nyoff = 0; } - if (nyoff != d->yoff) + if (nyoff != d->yoff) d->yoff = nyoff; setBaselineOffset(fm.ascent() + d->yoff + d->textMargin); @@ -1188,6 +1731,46 @@ void QSGTextEditPrivate::updateDefaultTextOption() } + +/*! + \qmlmethod void QtQuick2::TextEdit::openSoftwareInputPanel() + + Opens software input panels like virtual keyboards for typing, useful for + customizing when you want the input keyboard to be shown and hidden in + your application. + + By default the opening of input panels follows the platform style. On Symbian^1 and + Symbian^3 -based devices the panels are opened by clicking TextEdit. On other platforms + the panels are automatically opened when TextEdit element gains active focus. Input panels are + always closed if no editor has active focus. + + You can disable the automatic behavior by setting the property \c activeFocusOnPress to false + and use functions openSoftwareInputPanel() and closeSoftwareInputPanel() to implement + the behavior you want. + + Only relevant on platforms, which provide virtual keyboards. + + \code + import QtQuick 1.0 + TextEdit { + id: textEdit + text: "Hello world!" + activeFocusOnPress: false + MouseArea { + anchors.fill: parent + onClicked: { + if (!textEdit.activeFocus) { + textEdit.forceActiveFocus(); + textEdit.openSoftwareInputPanel(); + } else { + textEdit.focus = false; + } + } + onPressAndHold: textEdit.closeSoftwareInputPanel(); + } + } + \endcode +*/ void QSGTextEdit::openSoftwareInputPanel() { if (qApp) { @@ -1198,6 +1781,45 @@ void QSGTextEdit::openSoftwareInputPanel() } } +/*! + \qmlmethod void QtQuick2::TextEdit::closeSoftwareInputPanel() + + Closes a software input panel like a virtual keyboard shown on the screen, useful + for customizing when you want the input keyboard to be shown and hidden in + your application. + + By default the opening of input panels follows the platform style. On Symbian^1 and + Symbian^3 -based devices the panels are opened by clicking TextEdit. On other platforms + the panels are automatically opened when TextEdit element gains active focus. Input panels are + always closed if no editor has active focus. + + You can disable the automatic behavior by setting the property \c activeFocusOnPress to false + and use functions openSoftwareInputPanel() and closeSoftwareInputPanel() to implement + the behavior you want. + + Only relevant on platforms, which provide virtual keyboards. + + \code + import QtQuick 1.0 + TextEdit { + id: textEdit + text: "Hello world!" + activeFocusOnPress: false + MouseArea { + anchors.fill: parent + onClicked: { + if (!textEdit.activeFocus) { + textEdit.forceActiveFocus(); + textEdit.openSoftwareInputPanel(); + } else { + textEdit.focus = false; + } + } + onPressAndHold: textEdit.closeSoftwareInputPanel(); + } + } + \endcode +*/ void QSGTextEdit::closeSoftwareInputPanel() { if (qApp) { diff --git a/src/declarative/items/qsgtextinput.cpp b/src/declarative/items/qsgtextinput.cpp index eb5e23187c..4b9aea1b21 100644 --- a/src/declarative/items/qsgtextinput.cpp +++ b/src/declarative/items/qsgtextinput.cpp @@ -56,6 +56,25 @@ QT_BEGIN_NAMESPACE QWidgetPrivate *qt_widget_private(QWidget *widget); +/*! + \qmlclass TextInput QSGTextInput + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + \brief The TextInput item displays an editable line of text. + \inherits Item + + The TextInput element displays a single line of editable plain text. + + TextInput is used to accept a line of text input. Input constraints + can be placed on a TextInput item (for example, through a \l validator or \l inputMask), + and setting \l echoMode to an appropriate value enables TextInput to be used for + a password input field. + + On Mac OS X, the Up/Down key bindings for Home/End are explicitly disabled. + If you want such bindings (on any platform), you will need to construct them in QML. + + \sa TextEdit, Text, {declarative/text/textselection}{Text Selection example} +*/ QSGTextInput::QSGTextInput(QSGItem* parent) : QSGImplicitSizePaintedItem(*(new QSGTextInputPrivate), parent) { @@ -67,6 +86,11 @@ QSGTextInput::~QSGTextInput() { } +/*! + \qmlproperty string QtQuick2::TextInput::text + + The text in the TextInput. +*/ QString QSGTextInput::text() const { Q_D(const QSGTextInput); @@ -81,6 +105,111 @@ void QSGTextInput::setText(const QString &s) d->control->setText(s); } +/*! + \qmlproperty string QtQuick2::TextInput::font.family + + Sets the family name of the font. + + The family name is case insensitive and may optionally include a foundry name, e.g. "Helvetica [Cronyx]". + If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. + If the family isn't available a family will be set using the font matching algorithm. +*/ + +/*! + \qmlproperty bool QtQuick2::TextInput::font.bold + + Sets whether the font weight is bold. +*/ + +/*! + \qmlproperty enumeration QtQuick2::TextInput::font.weight + + Sets the font's weight. + + The weight can be one of: + \list + \o Font.Light + \o Font.Normal - the default + \o Font.DemiBold + \o Font.Bold + \o Font.Black + \endlist + + \qml + TextInput { text: "Hello"; font.weight: Font.DemiBold } + \endqml +*/ + +/*! + \qmlproperty bool QtQuick2::TextInput::font.italic + + Sets whether the font has an italic style. +*/ + +/*! + \qmlproperty bool QtQuick2::TextInput::font.underline + + Sets whether the text is underlined. +*/ + +/*! + \qmlproperty bool QtQuick2::TextInput::font.strikeout + + Sets whether the font has a strikeout style. +*/ + +/*! + \qmlproperty real QtQuick2::TextInput::font.pointSize + + Sets the font size in points. The point size must be greater than zero. +*/ + +/*! + \qmlproperty int QtQuick2::TextInput::font.pixelSize + + Sets the font size in pixels. + + Using this function makes the font device dependent. + Use \c pointSize to set the size of the font in a device independent manner. +*/ + +/*! + \qmlproperty real QtQuick2::TextInput::font.letterSpacing + + Sets the letter spacing for the font. + + Letter spacing changes the default spacing between individual letters in the font. + A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing. +*/ + +/*! + \qmlproperty real QtQuick2::TextInput::font.wordSpacing + + Sets the word spacing for the font. + + Word spacing changes the default spacing between individual words. + A positive value increases the word spacing by a corresponding amount of pixels, + while a negative value decreases the inter-word spacing accordingly. +*/ + +/*! + \qmlproperty enumeration QtQuick2::TextInput::font.capitalization + + Sets the capitalization for the text. + + \list + \o Font.MixedCase - This is the normal text rendering option where no capitalization change is applied. + \o Font.AllUppercase - This alters the text to be rendered in all uppercase type. + \o Font.AllLowercase - This alters the text to be rendered in all lowercase type. + \o Font.SmallCaps - This alters the text to be rendered in small-caps type. + \o Font.Capitalize - This alters the text to be rendered with the first character of each word as an uppercase character. + \endlist + + \qml + TextInput { text: "Hello"; font.capitalization: Font.AllLowercase } + \endqml +*/ + QFont QSGTextInput::font() const { Q_D(const QSGTextInput); @@ -112,6 +241,11 @@ void QSGTextInput::setFont(const QFont &font) emit fontChanged(d->sourceFont); } +/*! + \qmlproperty color QtQuick2::TextInput::color + + The text color. +*/ QColor QSGTextInput::color() const { Q_D(const QSGTextInput); @@ -128,6 +262,12 @@ void QSGTextInput::setColor(const QColor &c) } } + +/*! + \qmlproperty color QtQuick2::TextInput::selectionColor + + The text highlight color, used behind selections. +*/ QColor QSGTextInput::selectionColor() const { Q_D(const QSGTextInput); @@ -144,11 +284,15 @@ void QSGTextInput::setSelectionColor(const QColor &color) QPalette p = d->control->palette(); p.setColor(QPalette::Highlight, d->selectionColor); d->control->setPalette(p); - if (d->control->hasSelectedText()) + if (d->control->hasSelectedText()) update(); emit selectionColorChanged(color); } +/*! + \qmlproperty color QtQuick2::TextInput::selectedTextColor + The highlighted text color, used in selections. +*/ QColor QSGTextInput::selectedTextColor() const { Q_D(const QSGTextInput); @@ -165,11 +309,34 @@ void QSGTextInput::setSelectedTextColor(const QColor &color) QPalette p = d->control->palette(); p.setColor(QPalette::HighlightedText, d->selectedTextColor); d->control->setPalette(p); - if (d->control->hasSelectedText()) + if (d->control->hasSelectedText()) update(); emit selectedTextColorChanged(color); } +/*! + \qmlproperty enumeration QtQuick2::TextInput::horizontalAlignment + \qmlproperty enumeration QtQuick2::TextInput::effectiveHorizontalAlignment + + Sets the horizontal alignment of the text within the TextInput item's + width and height. By default, the text alignment follows the natural alignment + of the text, for example text that is read from left to right will be aligned to + the left. + + TextInput does not have vertical alignment, as the natural height is + exactly the height of the single line of text. If you set the height + manually to something larger, TextInput will always be top aligned + vertically. You can use anchors to align it however you want within + another item. + + The valid values for \c horizontalAlignment are \c TextInput.AlignLeft, \c TextInput.AlignRight and + \c TextInput.AlignHCenter. + + When using the attached property LayoutMirroring::enabled to mirror application + layouts, the horizontal alignment of text will also be mirrored. However, the property + \c horizontalAlignment will remain unchanged. To query the effective horizontal alignment + of TextInput, use the read-only property \c effectiveHorizontalAlignment. +*/ QSGTextInput::HAlignment QSGTextInput::hAlign() const { Q_D(const QSGTextInput); @@ -250,6 +417,15 @@ void QSGTextInputPrivate::mirrorChange() } } +/*! + \qmlproperty bool QtQuick2::TextInput::readOnly + + Sets whether user input can modify the contents of the TextInput. + + If readOnly is set to true, then user input will not affect the text + property. Any bindings or attempts to set the text property will still + work. +*/ bool QSGTextInput::isReadOnly() const { Q_D(const QSGTextInput); @@ -270,6 +446,14 @@ void QSGTextInput::setReadOnly(bool ro) emit readOnlyChanged(ro); } +/*! + \qmlproperty int QtQuick2::TextInput::maximumLength + The maximum permitted length of the text in the TextInput. + + If the text is too long, it is truncated at the limit. + + By default, this property contains a value of 32767. +*/ int QSGTextInput::maxLength() const { Q_D(const QSGTextInput); @@ -287,6 +471,32 @@ void QSGTextInput::setMaxLength(int ml) emit maximumLengthChanged(ml); } +/*! + \qmlproperty bool QtQuick2::TextInput::cursorVisible + Set to true when the TextInput shows a cursor. + + This property is set and unset when the TextInput gets active focus, so that other + properties can be bound to whether the cursor is currently showing. As it + gets set and unset automatically, when you set the value yourself you must + keep in mind that your value may be overwritten. + + It can be set directly in script, for example if a KeyProxy might + forward keys to it and you desire it to look active when this happens + (but without actually giving it active focus). + + It should not be set directly on the element, like in the below QML, + as the specified value will be overridden an lost on focus changes. + + \code + TextInput { + text: "Text" + cursorVisible: false + } + \endcode + + In the above snippet the cursor will still become visible when the + TextInput gains active focus. +*/ bool QSGTextInput::isCursorVisible() const { Q_D(const QSGTextInput); @@ -308,6 +518,10 @@ void QSGTextInput::setCursorVisible(bool on) emit cursorVisibleChanged(d->cursorVisible); } +/*! + \qmlproperty int QtQuick2::TextInput::cursorPosition + The position of the cursor in the TextInput. +*/ int QSGTextInput::cursorPosition() const { Q_D(const QSGTextInput); @@ -321,6 +535,10 @@ void QSGTextInput::setCursorPosition(int cp) d->control->moveCursor(cp); } +/*! + Returns a Rect which encompasses the cursor, but which may be larger than is + required. Ignores custom cursor delegates. +*/ QRect QSGTextInput::cursorRectangle() const { Q_D(const QSGTextInput); @@ -331,19 +549,49 @@ QRect QSGTextInput::cursorRectangle() const r.adjust(5 - d->hscroll, 0, -4 - d->hscroll, -1); return r; } +/*! + \qmlproperty int QtQuick2::TextInput::selectionStart + + The cursor position before the first character in the current selection. + This property is read-only. To change the selection, use select(start,end), + selectAll(), or selectWord(). + + \sa selectionEnd, cursorPosition, selectedText +*/ int QSGTextInput::selectionStart() const { Q_D(const QSGTextInput); return d->lastSelectionStart; } +/*! + \qmlproperty int QtQuick2::TextInput::selectionEnd + + The cursor position after the last character in the current selection. + This property is read-only. To change the selection, use select(start,end), + selectAll(), or selectWord(). + + \sa selectionStart, cursorPosition, selectedText +*/ int QSGTextInput::selectionEnd() const { Q_D(const QSGTextInput); return d->lastSelectionEnd; } +/*! + \qmlmethod void QtQuick2::TextInput::select(int start, int end) + + Causes the text from \a start to \a end to be selected. + + If either start or end is out of range, the selection is not changed. + After calling this, selectionStart will become the lesser + and selectionEnd will become the greater (regardless of the order passed + to this method). + + \sa selectionStart, selectionEnd +*/ void QSGTextInput::select(int start, int end) { Q_D(QSGTextInput); @@ -352,12 +600,32 @@ void QSGTextInput::select(int start, int end) d->control->setSelection(start, end-start); } +/*! + \qmlproperty string QtQuick2::TextInput::selectedText + + This read-only property provides the text currently selected in the + text input. + + It is equivalent to the following snippet, but is faster and easier + to use. + + \js + myTextInput.text.toString().substring(myTextInput.selectionStart, + myTextInput.selectionEnd); + \endjs +*/ QString QSGTextInput::selectedText() const { Q_D(const QSGTextInput); return d->control->selectedText(); } +/*! + \qmlproperty bool QtQuick2::TextInput::activeFocusOnPress + + Whether the TextInput should gain active focus on a mouse press. By default this is + set to true. +*/ bool QSGTextInput::focusOnPress() const { Q_D(const QSGTextInput); @@ -374,7 +642,12 @@ void QSGTextInput::setFocusOnPress(bool b) emit activeFocusOnPressChanged(d->focusOnPress); } +/*! + \qmlproperty bool QtQuick2::TextInput::autoScroll + Whether the TextInput should scroll when the text is longer than the width. By default this is + set to true. +*/ bool QSGTextInput::autoScroll() const { Q_D(const QSGTextInput); @@ -395,6 +668,114 @@ void QSGTextInput::setAutoScroll(bool b) } #ifndef QT_NO_VALIDATOR + +/*! + \qmlclass IntValidator QIntValidator + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + + This element provides a validator for integer values. + + IntValidator uses the \l {QLocale::setDefault()}{default locale} to interpret the number and + will accept locale specific digits, group separators, and positive and negative signs. In + addition, IntValidator is always guaranteed to accept a number formatted according to the "C" + locale. +*/ +/*! + \qmlproperty int QtQuick2::IntValidator::top + + This property holds the validator's highest acceptable value. + By default, this property's value is derived from the highest signed integer available (typically 2147483647). +*/ +/*! + \qmlproperty int QtQuick2::IntValidator::bottom + + This property holds the validator's lowest acceptable value. + By default, this property's value is derived from the lowest signed integer available (typically -2147483647). +*/ + +/*! + \qmlclass DoubleValidator QDoubleValidator + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + + This element provides a validator for non-integer numbers. +*/ + +/*! + \qmlproperty real QtQuick2::DoubleValidator::top + + This property holds the validator's maximum acceptable value. + By default, this property contains a value of infinity. +*/ +/*! + \qmlproperty real QtQuick2::DoubleValidator::bottom + + This property holds the validator's minimum acceptable value. + By default, this property contains a value of -infinity. +*/ +/*! + \qmlproperty int QtQuick2::DoubleValidator::decimals + + This property holds the validator's maximum number of digits after the decimal point. + By default, this property contains a value of 1000. +*/ +/*! + \qmlproperty enumeration QtQuick2::DoubleValidator::notation + This property holds the notation of how a string can describe a number. + + The possible values for this property are: + + \list + \o DoubleValidator.StandardNotation + \o DoubleValidator.ScientificNotation (default) + \endlist + + If this property is set to DoubleValidator.ScientificNotation, the written number may have an exponent part (e.g. 1.5E-2). +*/ + +/*! + \qmlclass RegExpValidator QRegExpValidator + \inqmlmodule QtQuick 2 + \ingroup qml-basic-visual-elements + + This element provides a validator, which counts as valid any string which + matches a specified regular expression. +*/ +/*! + \qmlproperty regExp QtQuick2::RegExpValidator::regExp + + This property holds the regular expression used for validation. + + Note that this property should be a regular expression in JS syntax, e.g /a/ for the regular expression + matching "a". + + By default, this property contains a regular expression with the pattern .* that matches any string. +*/ + +/*! + \qmlproperty Validator QtQuick2::TextInput::validator + + Allows you to set a validator on the TextInput. When a validator is set + the TextInput will only accept input which leaves the text property in + an acceptable or intermediate state. The accepted signal will only be sent + if the text is in an acceptable state when enter is pressed. + + Currently supported validators are IntValidator, DoubleValidator and + RegExpValidator. An example of using validators is shown below, which allows + input of integers between 11 and 31 into the text input: + + \code + import QtQuick 1.0 + TextInput{ + validator: IntValidator{bottom: 11; top: 31;} + focus: true + } + \endcode + + \sa acceptableInput, inputMask +*/ + QValidator* QSGTextInput::validator() const { Q_D(const QSGTextInput); @@ -418,6 +799,15 @@ void QSGTextInput::setValidator(QValidator* v) } #endif // QT_NO_VALIDATOR +/*! + \qmlproperty string QtQuick2::TextInput::inputMask + + Allows you to set an input mask on the TextInput, restricting the allowable + text inputs. See QLineEdit::inputMask for further details, as the exact + same mask strings are used by TextInput. + + \sa acceptableInput, validator +*/ QString QSGTextInput::inputMask() const { Q_D(const QSGTextInput); @@ -434,12 +824,29 @@ void QSGTextInput::setInputMask(const QString &im) emit inputMaskChanged(d->control->inputMask()); } +/*! + \qmlproperty bool QtQuick2::TextInput::acceptableInput + + This property is always true unless a validator or input mask has been set. + If a validator or input mask has been set, this property will only be true + if the current text is acceptable to the validator or input mask as a final + string (not as an intermediate string). +*/ bool QSGTextInput::hasAcceptableInput() const { Q_D(const QSGTextInput); return d->control->hasAcceptableInput(); } +/*! + \qmlsignal QtQuick2::TextInput::onAccepted() + + This handler is called when the Return or Enter key is pressed. + Note that if there is a \l validator or \l inputMask set on the text + input, the handler will only be emitted if the input is in an acceptable + state. +*/ + void QSGTextInputPrivate::updateInputMethodHints() { Q_Q(QSGTextInput); @@ -453,7 +860,18 @@ void QSGTextInputPrivate::updateInputMethodHints() hints |= (Qt::ImhNoAutoUppercase | Qt::ImhNoPredictiveText); q->setInputMethodHints(hints); } - +/*! + \qmlproperty enumeration QtQuick2::TextInput::echoMode + + Specifies how the text should be displayed in the TextInput. + \list + \o TextInput.Normal - Displays the text as it is. (Default) + \o TextInput.Password - Displays asterixes instead of characters. + \o TextInput.NoEcho - Displays nothing. + \o TextInput.PasswordEchoOnEdit - Displays characters as they are entered + while editing, otherwise displays asterisks. + \endlist +*/ QSGTextInput::EchoMode QSGTextInput::echoMode() const { Q_D(const QSGTextInput); @@ -486,6 +904,19 @@ void QSGTextInput::setIMHints(Qt::InputMethodHints hints) d->updateInputMethodHints(); } +/*! + \qmlproperty Component QtQuick2::TextInput::cursorDelegate + The delegate for the cursor in the TextInput. + + If you set a cursorDelegate for a TextInput, this delegate will be used for + drawing the cursor instead of the standard cursor. An instance of the + delegate will be created and managed by the TextInput when a cursor is + needed, and the x property of delegate instance will be set so as + to be one pixel before the top left of the current character. + + Note that the root item of the delegate component must be a QDeclarativeItem or + QDeclarativeItem derived item. +*/ QDeclarativeComponent* QSGTextInput::cursorDelegate() const { Q_D(const QSGTextInput); @@ -547,6 +978,15 @@ void QSGTextInput::createCursor() d->cursorItem->setHeight(d->control->height()-1); // -1 to counter QLineControl's +1 which is not consistent with Text. } +/*! + \qmlmethod rect QtQuick2::TextInput::positionToRectangle(int pos) + + This function takes a character position and returns the rectangle that the + cursor would occupy, if it was placed at that character position. + + This is similar to setting the cursorPosition, and then querying the cursor + rectangle, but the cursorPosition is not changed. +*/ QRectF QSGTextInput::positionToRectangle(int pos) const { Q_D(const QSGTextInput); @@ -558,6 +998,24 @@ QRectF QSGTextInput::positionToRectangle(int pos) const cursorRectangle().height()); } +/*! + \qmlmethod int QtQuick2::TextInput::positionAt(int x, CursorPosition position = CursorBetweenCharacters) + + This function returns the character position at + x pixels from the left of the textInput. Position 0 is before the + first character, position 1 is after the first character but before the second, + and so on until position text.length, which is after all characters. + + This means that for all x values before the first character this function returns 0, + and for all x values after the last character this function returns text.length. + + The cursor position type specifies how the cursor position should be resolved. + + \list + \o TextInput.CursorBetweenCharacters - Returns the position between characters that is nearest x. + \o TextInput.CursorOnCharacter - Returns the position before the character that is nearest x. + \endlist +*/ int QSGTextInput::positionAt(int x) const { return positionAt(x, CursorBetweenCharacters); @@ -878,18 +1336,34 @@ QVariant QSGTextInput::inputMethodQuery(Qt::InputMethodQuery property) const } } +/*! + \qmlmethod void QtQuick2::TextInput::deselect() + + Removes active text selection. +*/ void QSGTextInput::deselect() { Q_D(QSGTextInput); d->control->deselect(); } +/*! + \qmlmethod void QtQuick2::TextInput::selectAll() + + Causes all text to be selected. +*/ void QSGTextInput::selectAll() { Q_D(QSGTextInput); d->control->setSelection(0, d->control->text().length()); } +/*! + \qmlmethod void QtQuick2::TextInput::isRightToLeft(int start, int end) + + Returns true if the natural reading direction of the editor text + found between positions \a start and \a end is right to left. +*/ bool QSGTextInput::isRightToLeft(int start, int end) { Q_D(QSGTextInput); @@ -902,6 +1376,11 @@ bool QSGTextInput::isRightToLeft(int start, int end) } #ifndef QT_NO_CLIPBOARD +/*! + \qmlmethod QtQuick2::TextInput::cut() + + Moves the currently selected text to the system clipboard. +*/ void QSGTextInput::cut() { Q_D(QSGTextInput); @@ -909,12 +1388,22 @@ void QSGTextInput::cut() d->control->del(); } +/*! + \qmlmethod QtQuick2::TextInput::copy() + + Copies the currently selected text to the system clipboard. +*/ void QSGTextInput::copy() { Q_D(QSGTextInput); d->control->copy(); } +/*! + \qmlmethod QtQuick2::TextInput::paste() + + Replaces the currently selected text by the contents of the system clipboard. +*/ void QSGTextInput::paste() { Q_D(QSGTextInput); @@ -923,12 +1412,41 @@ void QSGTextInput::paste() } #endif // QT_NO_CLIPBOARD +/*! + \qmlmethod void QtQuick2::TextInput::selectWord() + + Causes the word closest to the current cursor position to be selected. +*/ void QSGTextInput::selectWord() { Q_D(QSGTextInput); d->control->selectWordAtPos(d->control->cursor()); } +/*! + \qmlproperty bool QtQuick2::TextInput::smooth + + This property holds whether the text is smoothly scaled or transformed. + + Smooth filtering gives better visual quality, but is slower. If + the item is displayed at its natural size, this property has no visual or + performance effect. + + \note Generally scaling artifacts are only visible if the item is stationary on + the screen. A common pattern when animating an item is to disable smooth + filtering at the beginning of the animation and reenable it at the conclusion. +*/ + +/*! + \qmlproperty string QtQuick2::TextInput::passwordCharacter + + This is the character displayed when echoMode is set to Password or + PasswordEchoOnEdit. By default it is an asterisk. + + If this property is set to a string with more than one character, + the first character is used. If the string is empty, the value + is ignored and the property is not set. +*/ QString QSGTextInput::passwordCharacter() const { Q_D(const QSGTextInput); @@ -948,12 +1466,32 @@ void QSGTextInput::setPasswordCharacter(const QString &str) emit passwordCharacterChanged(); } +/*! + \qmlproperty string QtQuick2::TextInput::displayText + + This is the text displayed in the TextInput. + + If \l echoMode is set to TextInput::Normal, this holds the + same value as the TextInput::text property. Otherwise, + this property holds the text visible to the user, while + the \l text property holds the actual entered text. +*/ QString QSGTextInput::displayText() const { Q_D(const QSGTextInput); return d->control->displayText(); } +/*! + \qmlproperty bool QtQuick2::TextInput::selectByMouse + + Defaults to false. + + If true, the user can use the mouse to select text in some + platform-specific way. Note that for some platforms this may + not be an appropriate interaction (eg. may conflict with how + the text needs to behave inside a Flickable. +*/ bool QSGTextInput::selectByMouse() const { Q_D(const QSGTextInput); @@ -969,6 +1507,19 @@ void QSGTextInput::setSelectByMouse(bool on) } } +/*! + \qmlproperty enum QtQuick2::TextInput::mouseSelectionMode + + Specifies how text should be selected using a mouse. + + \list + \o TextInput.SelectCharacters - The selection is updated with individual characters. (Default) + \o TextInput.SelectWords - The selection is updated with whole words. + \endlist + + This property only applies when \l selectByMouse is true. +*/ + QSGTextInput::SelectionMode QSGTextInput::mouseSelectionMode() const { Q_D(const QSGTextInput); @@ -984,6 +1535,12 @@ void QSGTextInput::setMouseSelectionMode(SelectionMode mode) } } +/*! + \qmlproperty bool QtQuick2::TextInput::canPaste + + Returns true if the TextInput is writable and the content of the clipboard is + suitable for pasting into the TextEdit. +*/ bool QSGTextInput::canPaste() const { Q_D(const QSGTextInput); @@ -996,6 +1553,43 @@ void QSGTextInput::moveCursorSelection(int position) d->control->moveCursor(position, true); } +/*! + \qmlmethod void QtQuick2::TextInput::moveCursorSelection(int position, SelectionMode mode = TextInput.SelectCharacters) + + Moves the cursor to \a position and updates the selection according to the optional \a mode + parameter. (To only move the cursor, set the \l cursorPosition property.) + + When this method is called it additionally sets either the + selectionStart or the selectionEnd (whichever was at the previous cursor position) + to the specified position. This allows you to easily extend and contract the selected + text range. + + The selection mode specifies whether the selection is updated on a per character or a per word + basis. If not specified the selection mode will default to TextInput.SelectCharacters. + + \list + \o TextEdit.SelectCharacters - Sets either the selectionStart or selectionEnd (whichever was at + the previous cursor position) to the specified position. + \o TextEdit.SelectWords - Sets the selectionStart and selectionEnd to include all + words between the specified postion and the previous cursor position. Words partially in the + range are included. + \endlist + + For example, take this sequence of calls: + + \code + cursorPosition = 5 + moveCursorSelection(9, TextInput.SelectCharacters) + moveCursorSelection(7, TextInput.SelectCharacters) + \endcode + + This moves the cursor to position 5, extend the selection end from 5 to 9 + and then retract the selection end from 9 to 7, leaving the text from position 5 to 7 + selected (the 6th and 7th characters). + + The same sequence with TextInput.SelectWords will extend the selection start to a word boundary + before or on position 5 and extend the selection end to a word boundary on or past position 9. +*/ void QSGTextInput::moveCursorSelection(int pos, SelectionMode mode) { Q_D(QSGTextInput); @@ -1053,6 +1647,45 @@ void QSGTextInput::moveCursorSelection(int pos, SelectionMode mode) } } +/*! + \qmlmethod void QtQuick2::TextInput::openSoftwareInputPanel() + + Opens software input panels like virtual keyboards for typing, useful for + customizing when you want the input keyboard to be shown and hidden in + your application. + + By default the opening of input panels follows the platform style. On Symbian^1 and + Symbian^3 -based devices the panels are opened by clicking TextInput. On other platforms + the panels are automatically opened when TextInput element gains active focus. Input panels are + always closed if no editor has active focus. + + . You can disable the automatic behavior by setting the property \c activeFocusOnPress to false + and use functions openSoftwareInputPanel() and closeSoftwareInputPanel() to implement + the behavior you want. + + Only relevant on platforms, which provide virtual keyboards. + + \qml + import QtQuick 1.0 + TextInput { + id: textInput + text: "Hello world!" + activeFocusOnPress: false + MouseArea { + anchors.fill: parent + onClicked: { + if (!textInput.activeFocus) { + textInput.forceActiveFocus() + textInput.openSoftwareInputPanel(); + } else { + textInput.focus = false; + } + } + onPressAndHold: textInput.closeSoftwareInputPanel(); + } + } + \endqml +*/ void QSGTextInput::openSoftwareInputPanel() { QEvent event(QEvent::RequestSoftwareInputPanel); @@ -1064,6 +1697,45 @@ void QSGTextInput::openSoftwareInputPanel() } } +/*! + \qmlmethod void QtQuick2::TextInput::closeSoftwareInputPanel() + + Closes a software input panel like a virtual keyboard shown on the screen, useful + for customizing when you want the input keyboard to be shown and hidden in + your application. + + By default the opening of input panels follows the platform style. On Symbian^1 and + Symbian^3 -based devices the panels are opened by clicking TextInput. On other platforms + the panels are automatically opened when TextInput element gains active focus. Input panels are + always closed if no editor has active focus. + + . You can disable the automatic behavior by setting the property \c activeFocusOnPress to false + and use functions openSoftwareInputPanel() and closeSoftwareInputPanel() to implement + the behavior you want. + + Only relevant on platforms, which provide virtual keyboards. + + \qml + import QtQuick 1.0 + TextInput { + id: textInput + text: "Hello world!" + activeFocusOnPress: false + MouseArea { + anchors.fill: parent + onClicked: { + if (!textInput.activeFocus) { + textInput.forceActiveFocus(); + textInput.openSoftwareInputPanel(); + } else { + textInput.focus = false; + } + } + onPressAndHold: textInput.closeSoftwareInputPanel(); + } + } + \endqml +*/ void QSGTextInput::closeSoftwareInputPanel() { if (qApp) { @@ -1100,6 +1772,18 @@ void QSGTextInput::itemChange(ItemChange change, const ItemChangeData &value) QSGItem::itemChange(change, value); } +/*! + \qmlproperty bool QtQuick2::TextInput::inputMethodComposing + + + This property holds whether the TextInput has partial text input from an + input method. + + While it is composing an input method may rely on mouse or key events from + the TextInput to edit or commit the partial text. This property can be + used to determine when to disable events handlers that may interfere with + the correct operation of an input method. +*/ bool QSGTextInput::isInputMethodComposing() const { Q_D(const QSGTextInput); diff --git a/src/declarative/items/qsgtranslate.cpp b/src/declarative/items/qsgtranslate.cpp index fc2e7b3cc2..1de5c6c3ea 100644 --- a/src/declarative/items/qsgtranslate.cpp +++ b/src/declarative/items/qsgtranslate.cpp @@ -56,15 +56,29 @@ public: qreal y; }; +/*! + Constructs an empty QSGTranslate object with the given \a parent. +*/ QSGTranslate::QSGTranslate(QObject *parent) : QSGTransform(*new QSGTranslatePrivate, parent) { } +/*! + Destroys the graphics scale. +*/ QSGTranslate::~QSGTranslate() { } +/*! + \property QSGTranslate::x + \brief the horizontal translation. + + The translation can be any real number; the default value is 0.0. + + \sa y +*/ qreal QSGTranslate::x() const { Q_D(const QSGTranslate); @@ -81,6 +95,14 @@ void QSGTranslate::setX(qreal x) emit xChanged(); } +/*! + \property QSGTranslate::y + \brief the vertical translation. + + The translation can be any real number; the default value is 0.0. + + \sa x +*/ qreal QSGTranslate::y() const { Q_D(const QSGTranslate); diff --git a/src/declarative/items/qsgvisualitemmodel.cpp b/src/declarative/items/qsgvisualitemmodel.cpp index 09b5ea0d94..a3433253de 100644 --- a/src/declarative/items/qsgvisualitemmodel.cpp +++ b/src/declarative/items/qsgvisualitemmodel.cpp @@ -123,11 +123,56 @@ public: QList<Item> children; }; + +/*! + \qmlclass VisualItemModel QSGVisualItemModel + \inqmlmodule QtQuick 2 + \ingroup qml-working-with-data + \brief The VisualItemModel allows items to be provided to a view. + + 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 \l{VisualItemModel::index}{index} attached property. + + The example below places three colored rectangles in a ListView. + \code + import QtQuick 1.0 + + Rectangle { + VisualItemModel { + id: itemModel + Rectangle { height: 30; width: 80; color: "red" } + Rectangle { height: 30; width: 80; color: "green" } + Rectangle { height: 30; width: 80; color: "blue" } + } + + ListView { + anchors.fill: parent + model: itemModel + } + } + \endcode + + \image visualitemmodel.png + + \sa {declarative/modelviews/visualitemmodel}{VisualItemModel example} +*/ QSGVisualItemModel::QSGVisualItemModel(QObject *parent) : QSGVisualModel(*(new QSGVisualItemModelPrivate), parent) { } +/*! + \qmlattachedproperty int VisualItemModel::index + This attached property holds the index of this delegate's item within the model. + + It is attached to each instance of the delegate. +*/ + QDeclarativeListProperty<QSGItem> QSGVisualItemModel::children() { Q_D(QSGVisualItemModel); @@ -135,6 +180,11 @@ QDeclarativeListProperty<QSGItem> QSGVisualItemModel::children() d->children_count, d->children_at); } +/*! + \qmlproperty int QtQuick2::VisualItemModel::count + + The number of items in the model. This property is readonly. +*/ int QSGVisualItemModel::count() const { Q_D(const QSGVisualItemModel); @@ -746,6 +796,26 @@ QSGVisualDataModelData *QSGVisualDataModelPrivate::data(QObject *item) //--------------------------------------------------------------------------- +/*! + \qmlclass VisualDataModel QSGVisualDataModel + \inqmlmodule QtQuick 2 + \ingroup qml-working-with-data + \brief The VisualDataModel encapsulates a model and delegate + + A VisualDataModel encapsulates a model and the delegate that will + be instantiated for items in the model. + + 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. + + \snippet doc/src/snippets/declarative/visualdatamodel.qml 0 +*/ + QSGVisualDataModel::QSGVisualDataModel() : QSGVisualModel(*(new QSGVisualDataModelPrivate(0))) { @@ -765,6 +835,20 @@ QSGVisualDataModel::~QSGVisualDataModel() d->m_delegateDataType->release(); } +/*! + \qmlproperty model QtQuick2::VisualDataModel::model + This property holds the model providing data for the VisualDataModel. + + The model provides a set of data that is used to create the items + for a view. For large or dynamic datasets the model is usually + provided by a C++ model object. The C++ model object must be a \l + {QAbstractItemModel} subclass or a simple list. + + Models can also be created directly in QML, using a \l{ListModel} or + \l{XmlListModel}. + + \sa {qmlmodels}{Data Models} +*/ QVariant QSGVisualDataModel::model() const { Q_D(const QSGVisualDataModel); @@ -873,6 +957,13 @@ void QSGVisualDataModel::setModel(const QVariant &model) } } +/*! + \qmlproperty Component QtQuick2::VisualDataModel::delegate + + The delegate provides a template defining each item instantiated by a view. + The index is exposed as an accessible \c index property. Properties of the + model are also available depending upon the type of \l {qmlmodels}{Data Model}. +*/ QDeclarativeComponent *QSGVisualDataModel::delegate() const { Q_D(const QSGVisualDataModel); @@ -897,6 +988,35 @@ void QSGVisualDataModel::setDelegate(QDeclarativeComponent *delegate) } } +/*! + \qmlproperty QModelIndex QtQuick2::VisualDataModel::rootIndex + + 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 that + are hierarchical (e.g, a tree 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. + + \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 + + If the \l model is a QAbstractItemModel subclass, the delegate can also + reference a \c hasModelChildren property (optionally qualified by a + \e model. prefix) that indicates whether the delegate's model item has + any child nodes. + + + \sa modelIndex(), parentModelIndex() +*/ QVariant QSGVisualDataModel::rootIndex() const { Q_D(const QSGVisualDataModel); @@ -923,6 +1043,18 @@ void QSGVisualDataModel::setRootIndex(const QVariant &root) } } +/*! + \qmlmethod QModelIndex QtQuick2::VisualDataModel::modelIndex(int index) + + QAbstractItemModel provides a hierarchical tree of data, whereas + QML only operates on list data. This function assists in using + tree models in QML. + + Returns a QModelIndex for the specified index. + This value can be assigned to rootIndex. + + \sa rootIndex +*/ QVariant QSGVisualDataModel::modelIndex(int idx) const { Q_D(const QSGVisualDataModel); @@ -931,6 +1063,18 @@ QVariant QSGVisualDataModel::modelIndex(int idx) const return QVariant::fromValue(QModelIndex()); } +/*! + \qmlmethod QModelIndex QtQuick2::VisualDataModel::parentModelIndex() + + QAbstractItemModel provides a hierarchical tree of data, whereas + QML only operates on list data. This function assists in using + tree models in QML. + + Returns a QModelIndex for the parent of the current rootIndex. + This value can be assigned to rootIndex. + + \sa rootIndex +*/ QVariant QSGVisualDataModel::parentModelIndex() const { Q_D(const QSGVisualDataModel); @@ -939,6 +1083,33 @@ QVariant QSGVisualDataModel::parentModelIndex() const return QVariant::fromValue(QModelIndex()); } +/*! + \qmlproperty object QtQuick2::VisualDataModel::parts + + The \a parts property selects a VisualDataModel which creates + delegates from the part named. This is used in conjunction with + the \l Package element. + + For example, the code below selects a model which creates + delegates named \e list from a \l Package: + + \code + VisualDataModel { + id: visualModel + delegate: Package { + Item { Package.name: "list" } + } + model: myModel + } + + ListView { + width: 200; height:200 + model: visualModel.parts.list + } + \endcode + + \sa Package +*/ QString QSGVisualDataModel::part() const { Q_D(const QSGVisualDataModel); diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index 977f7fa0d9..11e1c7cc0a 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -74,8 +74,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Animation QDeclarativeAbstractAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \brief The Animation element is the base of all QML animations. The Animation element cannot be used directly in a QML file. It exists @@ -99,7 +99,7 @@ QDeclarativeAbstractAnimation::QDeclarativeAbstractAnimation(QDeclarativeAbstrac } /*! - \qmlproperty bool Animation::running + \qmlproperty bool QtQuick2::Animation::running This property holds whether the animation is currently running. The \c running property can be set to declaratively control whether or not @@ -236,7 +236,7 @@ void QDeclarativeAbstractAnimation::setRunning(bool r) } /*! - \qmlproperty bool Animation::paused + \qmlproperty bool QtQuick2::Animation::paused This property holds whether the animation is currently paused. The \c paused property can be set to declaratively control whether or not @@ -303,7 +303,7 @@ void QDeclarativeAbstractAnimation::componentFinalized() } /*! - \qmlproperty bool Animation::alwaysRunToEnd + \qmlproperty bool QtQuick2::Animation::alwaysRunToEnd This property holds whether the animation should run to completion when it is stopped. If this true the animation will complete its current iteration when it @@ -335,7 +335,7 @@ void QDeclarativeAbstractAnimation::setAlwaysRunToEnd(bool f) } /*! - \qmlproperty int Animation::loops + \qmlproperty int QtQuick2::Animation::loops This property holds the number of times the animation should play. By default, \c loops is 1: the animation will play through once and then stop. @@ -412,7 +412,7 @@ void QDeclarativeAbstractAnimation::setGroup(QDeclarativeAnimationGroup *g) } /*! - \qmlmethod Animation::start() + \qmlmethod QtQuick2::Animation::start() \brief Starts the animation. If the animation is already running, calling this method has no effect. The @@ -424,7 +424,7 @@ void QDeclarativeAbstractAnimation::start() } /*! - \qmlmethod Animation::pause() + \qmlmethod QtQuick2::Animation::pause() \brief Pauses the animation. If the animation is already paused, calling this method has no effect. The @@ -436,7 +436,7 @@ void QDeclarativeAbstractAnimation::pause() } /*! - \qmlmethod Animation::resume() + \qmlmethod QtQuick2::Animation::resume() \brief Resumes a paused animation. If the animation is not paused, calling this method has no effect. The @@ -448,7 +448,7 @@ void QDeclarativeAbstractAnimation::resume() } /*! - \qmlmethod Animation::stop() + \qmlmethod QtQuick2::Animation::stop() \brief Stops the animation. If the animation is not running, calling this method has no effect. The @@ -473,7 +473,7 @@ void QDeclarativeAbstractAnimation::stop() } /*! - \qmlmethod Animation::restart() + \qmlmethod QtQuick2::Animation::restart() \brief Restarts the animation. This is a convenience method, and is equivalent to calling \c stop() and @@ -486,7 +486,7 @@ void QDeclarativeAbstractAnimation::restart() } /*! - \qmlmethod Animation::complete() + \qmlmethod QtQuick2::Animation::complete() \brief Stops the animation, jumping to the final property values. If the animation is not running, calling this method has no effect. The @@ -562,8 +562,8 @@ void QDeclarativeAbstractAnimation::timelineComplete() /*! \qmlclass PauseAnimation QDeclarativePauseAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The PauseAnimation element provides a pause for an animation. @@ -600,7 +600,7 @@ void QDeclarativePauseAnimationPrivate::init() } /*! - \qmlproperty int PauseAnimation::duration + \qmlproperty int QtQuick2::PauseAnimation::duration This property holds the duration of the pause in milliseconds The default value is 250. @@ -633,8 +633,8 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation() /*! \qmlclass ColorAnimation QDeclarativeColorAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits PropertyAnimation \brief The ColorAnimation element animates changes in color values. @@ -674,7 +674,7 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation() } /*! - \qmlproperty color ColorAnimation::from + \qmlproperty color QtQuick2::ColorAnimation::from This property holds the color value at which the animation should begin. For example, the following animation is not applied until a color value @@ -711,7 +711,7 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f) } /*! - \qmlproperty color ColorAnimation::to + \qmlproperty color QtQuick2::ColorAnimation::to This property holds the color value at which the animation should end. @@ -737,8 +737,8 @@ void QDeclarativeColorAnimation::setTo(const QColor &t) /*! \qmlclass ScriptAction QDeclarativeScriptAction + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The ScriptAction element allows scripts to be run during an animation. @@ -782,7 +782,7 @@ void QDeclarativeScriptActionPrivate::init() } /*! - \qmlproperty script ScriptAction::script + \qmlproperty script QtQuick2::ScriptAction::script This property holds the script to run. */ QDeclarativeScriptString QDeclarativeScriptAction::script() const @@ -798,7 +798,7 @@ void QDeclarativeScriptAction::setScript(const QDeclarativeScriptString &script) } /*! - \qmlproperty string ScriptAction::scriptName + \qmlproperty string QtQuick2::ScriptAction::scriptName This property holds the the name of the StateChangeScript to run. This property is only valid when ScriptAction is used as part of a transition. @@ -871,8 +871,8 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() /*! \qmlclass PropertyAction QDeclarativePropertyAction + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The PropertyAction element allows immediate property changes during animation. @@ -958,10 +958,10 @@ void QDeclarativePropertyAction::setProperty(const QString &n) } /*! - \qmlproperty Object PropertyAction::target - \qmlproperty list<Object> PropertyAction::targets - \qmlproperty string PropertyAction::property - \qmlproperty string PropertyAction::properties + \qmlproperty Object QtQuick2::PropertyAction::target + \qmlproperty list<Object> QtQuick2::PropertyAction::targets + \qmlproperty string QtQuick2::PropertyAction::property + \qmlproperty string QtQuick2::PropertyAction::properties These properties determine the items and their properties that are affected by this action. @@ -994,7 +994,7 @@ QDeclarativeListProperty<QObject> QDeclarativePropertyAction::targets() } /*! - \qmlproperty list<Object> PropertyAction::exclude + \qmlproperty list<Object> QtQuick2::PropertyAction::exclude This property holds the objects that should not be affected by this action. \sa targets @@ -1006,7 +1006,7 @@ QDeclarativeListProperty<QObject> QDeclarativePropertyAction::exclude() } /*! - \qmlproperty any PropertyAction::value + \qmlproperty any QtQuick2::PropertyAction::value This property holds the value to be set on the property. If the PropertyAction is defined within a \l Transition or \l Behavior, @@ -1132,8 +1132,8 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions, /*! \qmlclass NumberAnimation QDeclarativeNumberAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits PropertyAnimation \brief The NumberAnimation element animates changes in qreal-type values. @@ -1181,7 +1181,7 @@ void QDeclarativeNumberAnimation::init() } /*! - \qmlproperty real NumberAnimation::from + \qmlproperty real QtQuick2::NumberAnimation::from This property holds the starting value for the animation. For example, the following animation is not applied until the \c x value @@ -1219,7 +1219,7 @@ void QDeclarativeNumberAnimation::setFrom(qreal f) } /*! - \qmlproperty real NumberAnimation::to + \qmlproperty real QtQuick2::NumberAnimation::to This property holds the end value for the animation. If the NumberAnimation is defined within a \l Transition or \l Behavior, @@ -1244,8 +1244,8 @@ void QDeclarativeNumberAnimation::setTo(qreal t) /*! \qmlclass Vector3dAnimation QDeclarativeVector3dAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits PropertyAnimation \brief The Vector3dAnimation element animates changes in QVector3d values. @@ -1273,7 +1273,7 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation() } /*! - \qmlproperty real Vector3dAnimation::from + \qmlproperty real QtQuick2::Vector3dAnimation::from This property holds the starting value for the animation. If the Vector3dAnimation is defined within a \l Transition or \l Behavior, @@ -1295,7 +1295,7 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f) } /*! - \qmlproperty real Vector3dAnimation::to + \qmlproperty real QtQuick2::Vector3dAnimation::to This property holds the end value for the animation. If the Vector3dAnimation is defined within a \l Transition or \l Behavior, @@ -1320,8 +1320,8 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) /*! \qmlclass RotationAnimation QDeclarativeRotationAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits PropertyAnimation \brief The RotationAnimation element animates changes in rotation values. @@ -1409,7 +1409,7 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() } /*! - \qmlproperty real RotationAnimation::from + \qmlproperty real QtQuick2::RotationAnimation::from This property holds the starting value for the animation. For example, the following animation is not applied until the \c angle value @@ -1446,7 +1446,7 @@ void QDeclarativeRotationAnimation::setFrom(qreal f) } /*! - \qmlproperty real RotationAnimation::to + \qmlproperty real QtQuick2::RotationAnimation::to This property holds the end value for the animation.. If the RotationAnimation is defined within a \l Transition or \l Behavior, @@ -1468,7 +1468,7 @@ void QDeclarativeRotationAnimation::setTo(qreal t) } /*! - \qmlproperty enumeration RotationAnimation::direction + \qmlproperty enumeration QtQuick2::RotationAnimation::direction This property holds the direction of the rotation. Possible values are: @@ -1564,8 +1564,8 @@ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeAnimationGro /*! \qmlclass SequentialAnimation QDeclarativeSequentialAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The SequentialAnimation element allows animations to be run sequentially. @@ -1638,8 +1638,8 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio /*! \qmlclass ParallelAnimation QDeclarativeParallelAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The ParallelAnimation element allows animations to be run in parallel. @@ -1752,8 +1752,8 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int /*! \qmlclass PropertyAnimation QDeclarativePropertyAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits Animation \brief The PropertyAnimation element animates changes in property values. @@ -1838,7 +1838,7 @@ void QDeclarativePropertyAnimationPrivate::init() } /*! - \qmlproperty int PropertyAnimation::duration + \qmlproperty int QtQuick2::PropertyAnimation::duration This property holds the duration of the animation, in milliseconds. The default value is 250. @@ -1864,7 +1864,7 @@ void QDeclarativePropertyAnimation::setDuration(int duration) } /*! - \qmlproperty real PropertyAnimation::from + \qmlproperty real QtQuick2::PropertyAnimation::from This property holds the starting value for the animation. If the PropertyAnimation is defined within a \l Transition or \l Behavior, @@ -1891,7 +1891,7 @@ void QDeclarativePropertyAnimation::setFrom(const QVariant &f) } /*! - \qmlproperty real PropertyAnimation::to + \qmlproperty real QtQuick2::PropertyAnimation::to This property holds the end value for the animation. If the PropertyAnimation is defined within a \l Transition or \l Behavior, @@ -1918,10 +1918,10 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t) } /*! - \qmlproperty enumeration PropertyAnimation::easing.type - \qmlproperty real PropertyAnimation::easing.amplitude - \qmlproperty real PropertyAnimation::easing.overshoot - \qmlproperty real PropertyAnimation::easing.period + \qmlproperty enumeration QtQuick2::PropertyAnimation::easing.type + \qmlproperty real QtQuick2::PropertyAnimation::easing.amplitude + \qmlproperty real QtQuick2::PropertyAnimation::easing.overshoot + \qmlproperty real QtQuick2::PropertyAnimation::easing.period \brief the easing curve used for the animation. To specify an easing curve you need to specify at least the type. For some curves you can also specify @@ -2179,10 +2179,10 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop) } /*! - \qmlproperty string PropertyAnimation::properties - \qmlproperty list<Object> PropertyAnimation::targets - \qmlproperty string PropertyAnimation::property - \qmlproperty Object PropertyAnimation::target + \qmlproperty string QtQuick2::PropertyAnimation::properties + \qmlproperty list<Object> QtQuick2::PropertyAnimation::targets + \qmlproperty string QtQuick2::PropertyAnimation::property + \qmlproperty Object QtQuick2::PropertyAnimation::target These properties are used as a set to determine which properties should be animated. The singular and plural forms are functionally identical, e.g. @@ -2275,7 +2275,7 @@ QDeclarativeListProperty<QObject> QDeclarativePropertyAnimation::targets() } /*! - \qmlproperty list<Object> PropertyAnimation::exclude + \qmlproperty list<Object> QtQuick2::PropertyAnimation::exclude This property holds the items not to be affected by this animation. \sa PropertyAnimation::targets */ diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp index 8587ccb4fb..84636e4701 100644 --- a/src/declarative/util/qdeclarativebehavior.cpp +++ b/src/declarative/util/qdeclarativebehavior.cpp @@ -72,8 +72,8 @@ public: /*! \qmlclass Behavior QDeclarativeBehavior + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \brief The Behavior element allows you to specify a default animation for a property change. A Behavior defines the default animation to be applied whenever a @@ -108,7 +108,7 @@ QDeclarativeBehavior::~QDeclarativeBehavior() } /*! - \qmlproperty Animation Behavior::animation + \qmlproperty Animation QtQuick2::Behavior::animation \default This property holds the animation to run when the behavior is triggered. @@ -149,7 +149,7 @@ void QDeclarativeBehavior::qtAnimationStateChanged(QAbstractAnimation::State new /*! - \qmlproperty bool Behavior::enabled + \qmlproperty bool QtQuick2::Behavior::enabled This property holds whether the behavior will be triggered when the tracked property changes value. diff --git a/src/declarative/util/qdeclarativebind.cpp b/src/declarative/util/qdeclarativebind.cpp index 320bca853a..ba120b959a 100644 --- a/src/declarative/util/qdeclarativebind.cpp +++ b/src/declarative/util/qdeclarativebind.cpp @@ -78,8 +78,8 @@ public: /*! \qmlclass Binding QDeclarativeBind + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data - \since 4.7 \brief The Binding element allows arbitrary property bindings to be created. \section1 Binding to an inaccessible property @@ -152,7 +152,7 @@ QDeclarativeBind::~QDeclarativeBind() } /*! - \qmlproperty bool Binding::when + \qmlproperty bool QtQuick2::Binding::when This property holds when the binding is active. This should be set to an expression that evaluates to true when you want the binding to be active. @@ -184,7 +184,7 @@ void QDeclarativeBind::setWhen(bool v) } /*! - \qmlproperty Object Binding::target + \qmlproperty Object QtQuick2::Binding::target The object to be updated. */ @@ -211,7 +211,7 @@ void QDeclarativeBind::setObject(QObject *obj) } /*! - \qmlproperty string Binding::property + \qmlproperty string QtQuick2::Binding::property The property to be updated. */ @@ -238,7 +238,7 @@ void QDeclarativeBind::setProperty(const QString &p) } /*! - \qmlproperty any Binding::value + \qmlproperty any QtQuick2::Binding::value The value to be set on the target object and property. This can be a constant (which isn't very useful), or a bound expression. diff --git a/src/declarative/util/qdeclarativeconnections.cpp b/src/declarative/util/qdeclarativeconnections.cpp index 956533f7ca..6559d4bb20 100644 --- a/src/declarative/util/qdeclarativeconnections.cpp +++ b/src/declarative/util/qdeclarativeconnections.cpp @@ -72,8 +72,8 @@ public: /*! \qmlclass Connections QDeclarativeConnections + \inqmlmodule QtQuick 2 \ingroup qml-utility-elements - \since 4.7 \brief A Connections element describes generalized connections to signals. A Connections object creates a connection to a QML signal. @@ -137,7 +137,7 @@ QDeclarativeConnections::~QDeclarativeConnections() } /*! - \qmlproperty Object Connections::target + \qmlproperty Object QtQuick2::Connections::target This property holds the object that sends the signal. If this property is not set, the \c target defaults to the parent of the Connection. @@ -172,7 +172,7 @@ void QDeclarativeConnections::setTarget(QObject *obj) } /*! - \qmlproperty bool Connections::ignoreUnknownSignals + \qmlproperty bool QtQuick2::Connections::ignoreUnknownSignals Normally, a connection to a non-existent signal produces runtime errors. diff --git a/src/declarative/util/qdeclarativefontloader.cpp b/src/declarative/util/qdeclarativefontloader.cpp index 4d67736e0c..7a1dec88f0 100644 --- a/src/declarative/util/qdeclarativefontloader.cpp +++ b/src/declarative/util/qdeclarativefontloader.cpp @@ -145,8 +145,8 @@ QHash<QUrl, QDeclarativeFontObject*> QDeclarativeFontLoaderPrivate::fonts; /*! \qmlclass FontLoader QDeclarativeFontLoader + \inqmlmodule QtQuick 2 \ingroup qml-utility-elements - \since 4.7 \brief The FontLoader element allows fonts to be loaded by name or URL. The FontLoader element is used to load fonts by name or URL. @@ -179,7 +179,7 @@ QDeclarativeFontLoader::~QDeclarativeFontLoader() } /*! - \qmlproperty url FontLoader::source + \qmlproperty url QtQuick2::FontLoader::source The url of the font to load. */ QUrl QDeclarativeFontLoader::source() const @@ -253,7 +253,7 @@ void QDeclarativeFontLoader::updateFontInfo(const QString& name, QDeclarativeFon } /*! - \qmlproperty string FontLoader::name + \qmlproperty string QtQuick2::FontLoader::name This property holds the name of the font family. It is set automatically when a font is loaded using the \c url property. @@ -294,7 +294,7 @@ void QDeclarativeFontLoader::setName(const QString &name) } /*! - \qmlproperty enumeration FontLoader::status + \qmlproperty enumeration QtQuick2::FontLoader::status This property holds the status of font loading. It can be one of: \list diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp index 035502140b..15d87c828d 100644 --- a/src/declarative/util/qdeclarativelistmodel.cpp +++ b/src/declarative/util/qdeclarativelistmodel.cpp @@ -204,8 +204,8 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM /*! \qmlclass ListModel QDeclarativeListModel + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data - \since 4.7 \brief The ListModel element defines a free-form list data source. The ListModel is a simple container of ListElement definitions, each containing data roles. @@ -436,7 +436,7 @@ QVariant QDeclarativeListModel::data(int index, int role) const } /*! - \qmlproperty int ListModel::count + \qmlproperty int QtQuick2::ListModel::count The number of data entries in the model. */ int QDeclarativeListModel::count() const @@ -445,7 +445,7 @@ int QDeclarativeListModel::count() const } /*! - \qmlmethod ListModel::clear() + \qmlmethod QtQuick2::ListModel::clear() Deletes all content from the model. @@ -498,7 +498,7 @@ ModelObject *ModelNode::object(const NestedListModel *model) } /*! - \qmlmethod ListModel::remove(int index) + \qmlmethod QtQuick2::ListModel::remove(int index) Deletes the content at \a index from the model. @@ -523,7 +523,7 @@ void QDeclarativeListModel::remove(int index) } /*! - \qmlmethod ListModel::insert(int index, jsobject dict) + \qmlmethod QtQuick2::ListModel::insert(int index, jsobject dict) Adds a new item to the list model at position \a index, with the values in \a dict. @@ -560,7 +560,7 @@ void QDeclarativeListModel::insert(int index, const QDeclarativeV8Handle &handle } /*! - \qmlmethod ListModel::move(int from, int to, int n) + \qmlmethod QtQuick2::ListModel::move(int from, int to, int n) Moves \a n items \a from one position \a to another. @@ -604,7 +604,7 @@ void QDeclarativeListModel::move(int from, int to, int n) } /*! - \qmlmethod ListModel::append(jsobject dict) + \qmlmethod QtQuick2::ListModel::append(jsobject dict) Adds a new item to the end of the list model, with the values in \a dict. @@ -628,7 +628,7 @@ void QDeclarativeListModel::append(const QDeclarativeV8Handle &handle) } /*! - \qmlmethod object ListModel::get(int index) + \qmlmethod object QtQuick2::ListModel::get(int index) Returns the item at \a index in the list model. This allows the item data to be accessed or modified from JavaScript: @@ -665,7 +665,7 @@ QDeclarativeV8Handle QDeclarativeListModel::get(int index) const } /*! - \qmlmethod ListModel::set(int index, jsobject dict) + \qmlmethod QtQuick2::ListModel::set(int index, jsobject dict) Changes the item at \a index in the list model with the values in \a dict. Properties not appearing in \a dict @@ -712,7 +712,7 @@ void QDeclarativeListModel::set(int index, const QDeclarativeV8Handle &handle, Q } /*! - \qmlmethod ListModel::setProperty(int index, string property, variant value) + \qmlmethod QtQuick2::ListModel::setProperty(int index, string property, variant value) Changes the \a property of the item at \a index in the list model to \a value. @@ -746,7 +746,7 @@ void QDeclarativeListModel::setProperty(int index, const QString& property, cons } /*! - \qmlmethod ListModel::sync() + \qmlmethod QtQuick2::ListModel::sync() Writes any unsaved changes to the list model after it has been modified from a worker script. @@ -1019,8 +1019,8 @@ bool QDeclarativeListModelParser::definesEmptyList(const QString &s) /*! \qmlclass ListElement QDeclarativeListElement + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data - \since 4.7 \brief The ListElement element defines a data item in a ListModel. List elements are defined inside ListModel definitions, and represent items in a diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp index 2f96b3c6da..915633f1ad 100644 --- a/src/declarative/util/qdeclarativepackage.cpp +++ b/src/declarative/util/qdeclarativepackage.cpp @@ -48,6 +48,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Package QDeclarativePackage + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data \brief Package provides a collection of named items. diff --git a/src/declarative/util/qdeclarativepath.cpp b/src/declarative/util/qdeclarativepath.cpp index 7b5d966719..34752b5242 100644 --- a/src/declarative/util/qdeclarativepath.cpp +++ b/src/declarative/util/qdeclarativepath.cpp @@ -53,8 +53,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass PathElement QDeclarativePathElement + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief PathElement is the base path type. This type is the base for all path types. It cannot @@ -65,8 +65,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Path QDeclarativePath + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief A Path object defines a path for use by \l PathView. A Path is composed of one or more path segments - PathLine, PathQuad, @@ -90,8 +90,8 @@ QDeclarativePath::~QDeclarativePath() } /*! - \qmlproperty real Path::startX - \qmlproperty real Path::startY + \qmlproperty real QtQuick2::Path::startX + \qmlproperty real QtQuick2::Path::startY These properties hold the starting position of the path. */ qreal QDeclarativePath::startX() const @@ -127,7 +127,7 @@ void QDeclarativePath::setStartY(qreal y) } /*! - \qmlproperty bool Path::closed + \qmlproperty bool QtQuick2::Path::closed This property holds whether the start and end of the path are identical. */ bool QDeclarativePath::isClosed() const @@ -137,7 +137,7 @@ bool QDeclarativePath::isClosed() const } /*! - \qmlproperty list<PathElement> Path::pathElements + \qmlproperty list<PathElement> QtQuick2::Path::pathElements This property holds the objects composing the path. \default @@ -502,8 +502,8 @@ void QDeclarativeCurve::setY(qreal y) /*! \qmlclass PathAttribute QDeclarativePathAttribute + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief The PathAttribute allows setting an attribute at a given position in a Path. The PathAttribute object allows attributes consisting of a name and @@ -533,7 +533,7 @@ void QDeclarativeCurve::setY(qreal y) */ /*! - \qmlproperty string PathAttribute::name + \qmlproperty string QtQuick2::PathAttribute::name This property holds the name of the attribute to change. This attribute will be available to the delegate as PathView.<name> @@ -562,7 +562,7 @@ void QDeclarativePathAttribute::setName(const QString &name) } /*! - \qmlproperty real PathAttribute::value + \qmlproperty real QtQuick2::PathAttribute::value This property holds the value for the attribute. The value specified can be used to influence the visual appearance @@ -618,8 +618,8 @@ void QDeclarativePathAttribute::setValue(qreal value) /*! \qmlclass PathLine QDeclarativePathLine + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief The PathLine defines a straight line. The example below creates a path consisting of a straight line from @@ -636,8 +636,8 @@ void QDeclarativePathAttribute::setValue(qreal value) */ /*! - \qmlproperty real PathLine::x - \qmlproperty real PathLine::y + \qmlproperty real QtQuick2::PathLine::x + \qmlproperty real QtQuick2::PathLine::y Defines the end point of the line. */ @@ -651,8 +651,8 @@ void QDeclarativePathLine::addToPath(QPainterPath &path) /*! \qmlclass PathQuad QDeclarativePathQuad + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief The PathQuad defines a quadratic Bezier curve with a control point. The following QML produces the path shown below: @@ -672,15 +672,15 @@ void QDeclarativePathLine::addToPath(QPainterPath &path) */ /*! - \qmlproperty real PathQuad::x - \qmlproperty real PathQuad::y + \qmlproperty real QtQuick2::PathQuad::x + \qmlproperty real QtQuick2::PathQuad::y Defines the end point of the curve. */ /*! - \qmlproperty real PathQuad::controlX - \qmlproperty real PathQuad::controlY + \qmlproperty real QtQuick2::PathQuad::controlX + \qmlproperty real QtQuick2::PathQuad::controlY Defines the position of the control point. */ @@ -729,8 +729,8 @@ void QDeclarativePathQuad::addToPath(QPainterPath &path) /*! \qmlclass PathCubic QDeclarativePathCubic + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief The PathCubic defines a cubic Bezier curve with two control points. The following QML produces the path shown below: @@ -754,15 +754,15 @@ void QDeclarativePathQuad::addToPath(QPainterPath &path) */ /*! - \qmlproperty real PathCubic::x - \qmlproperty real PathCubic::y + \qmlproperty real QtQuick2::PathCubic::x + \qmlproperty real QtQuick2::PathCubic::y Defines the end point of the curve. */ /*! - \qmlproperty real PathCubic::control1X - \qmlproperty real PathCubic::control1Y + \qmlproperty real QtQuick2::PathCubic::control1X + \qmlproperty real QtQuick2::PathCubic::control1Y Defines the position of the first control point. */ @@ -795,8 +795,8 @@ void QDeclarativePathCubic::setControl1Y(qreal y) } /*! - \qmlproperty real PathCubic::control2X - \qmlproperty real PathCubic::control2Y + \qmlproperty real QtQuick2::PathCubic::control2X + \qmlproperty real QtQuick2::PathCubic::control2Y Defines the position of the second control point. */ @@ -837,8 +837,8 @@ void QDeclarativePathCubic::addToPath(QPainterPath &path) /*! \qmlclass PathPercent QDeclarativePathPercent + \inqmlmodule QtQuick 2 \ingroup qml-view-elements - \since 4.7 \brief The PathPercent manipulates the way a path is interpreted. PathPercent allows you to manipulate the spacing between items on a @@ -886,7 +886,7 @@ void QDeclarativePathCubic::addToPath(QPainterPath &path) */ /*! - \qmlproperty real PathPercent::value + \qmlproperty real QtQuick2::PathPercent::value The proporation of items that should be laid out up to this point. This value should always be higher than the last value specified diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp index 5cdf785ccd..d03cd3bb1a 100644 --- a/src/declarative/util/qdeclarativepropertychanges.cpp +++ b/src/declarative/util/qdeclarativepropertychanges.cpp @@ -65,8 +65,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass PropertyChanges QDeclarativePropertyChanges + \inqmlmodule QtQuick 2 \ingroup qml-state-elements - \since 4.7 \brief The PropertyChanges element describes new property bindings or values for a state. PropertyChanges is used to define the property values or bindings in a @@ -132,7 +132,7 @@ QT_BEGIN_NAMESPACE */ /*! - \qmlproperty Object PropertyChanges::target + \qmlproperty Object QtQuick2::PropertyChanges::target This property holds the object which contains the properties to be changed. */ @@ -394,7 +394,7 @@ void QDeclarativePropertyChanges::setObject(QObject *o) } /*! - \qmlproperty bool PropertyChanges::restoreEntryValues + \qmlproperty bool QtQuick2::PropertyChanges::restoreEntryValues This property holds whether the previous values should be restored when leaving the state. @@ -496,7 +496,7 @@ QDeclarativePropertyChanges::ActionList QDeclarativePropertyChanges::actions() } /*! - \qmlproperty bool PropertyChanges::explicit + \qmlproperty bool QtQuick2::PropertyChanges::explicit If explicit is set to true, any potential bindings will be interpreted as once-off assignments that occur when the state is entered. diff --git a/src/declarative/util/qdeclarativepropertymap.cpp b/src/declarative/util/qdeclarativepropertymap.cpp index 765e237051..c9242672c5 100644 --- a/src/declarative/util/qdeclarativepropertymap.cpp +++ b/src/declarative/util/qdeclarativepropertymap.cpp @@ -97,7 +97,6 @@ void QDeclarativePropertyMapMetaObject::propertyCreated(int, QMetaPropertyBuilde /*! \class QDeclarativePropertyMap - \since 4.7 \brief The QDeclarativePropertyMap class allows you to set key-value pairs that can be used in QML bindings. QDeclarativePropertyMap provides a convenient way to expose domain data to the UI layer. diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp index 2200d2c77c..f76531a5f7 100644 --- a/src/declarative/util/qdeclarativesmoothedanimation.cpp +++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp @@ -253,8 +253,8 @@ void QSmoothedAnimation::init() /*! \qmlclass SmoothedAnimation QDeclarativeSmoothedAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \inherits NumberAnimation \brief The SmoothedAnimation element allows a property to smoothly track a value. @@ -382,7 +382,7 @@ void QDeclarativeSmoothedAnimation::transition(QDeclarativeStateActions &actions } /*! - \qmlproperty enumeration SmoothedAnimation::reversingMode + \qmlproperty enumeration QtQuick2::SmoothedAnimation::reversingMode Sets how the SmoothedAnimation behaves if an animation direction is reversed. @@ -412,7 +412,7 @@ void QDeclarativeSmoothedAnimation::setReversingMode(ReversingMode m) } /*! - \qmlproperty int SmoothedAnimation::duration + \qmlproperty int QtQuick2::SmoothedAnimation::duration This property holds the animation duration, in msecs, used when tracking the source. @@ -445,7 +445,7 @@ qreal QDeclarativeSmoothedAnimation::velocity() const } /*! - \qmlproperty real SmoothedAnimation::velocity + \qmlproperty real QtQuick2::SmoothedAnimation::velocity This property holds the average velocity allowed when tracking the 'to' value. @@ -468,7 +468,7 @@ void QDeclarativeSmoothedAnimation::setVelocity(qreal v) } /*! - \qmlproperty int SmoothedAnimation::maximumEasingTime + \qmlproperty int QtQuick2::SmoothedAnimation::maximumEasingTime This property specifies the maximum time, in msecs, any "eases" during the follow should take. Setting this property causes the velocity to "level out" after at a time. Setting diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp index 2c6058caf6..619811f789 100644 --- a/src/declarative/util/qdeclarativespringanimation.cpp +++ b/src/declarative/util/qdeclarativespringanimation.cpp @@ -235,9 +235,9 @@ void QDeclarativeSpringAnimationPrivate::updateMode() /*! \qmlclass SpringAnimation QDeclarativeSpringAnimation + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition \inherits NumberAnimation - \since 4.7 \brief The SpringAnimation element allows a property to track a value in a spring-like motion. @@ -273,7 +273,7 @@ QDeclarativeSpringAnimation::~QDeclarativeSpringAnimation() } /*! - \qmlproperty real SpringAnimation::velocity + \qmlproperty real QtQuick2::SpringAnimation::velocity This property holds the maximum velocity allowed when tracking the source. @@ -295,7 +295,7 @@ void QDeclarativeSpringAnimation::setVelocity(qreal velocity) } /*! - \qmlproperty real SpringAnimation::spring + \qmlproperty real QtQuick2::SpringAnimation::spring This property describes how strongly the target is pulled towards the source. The default value is 0 (that is, the spring-like motion is disabled). @@ -319,7 +319,7 @@ void QDeclarativeSpringAnimation::setSpring(qreal spring) } /*! - \qmlproperty real SpringAnimation::damping + \qmlproperty real QtQuick2::SpringAnimation::damping This property holds the spring damping value. This value describes how quickly the spring-like motion comes to rest. @@ -345,7 +345,7 @@ void QDeclarativeSpringAnimation::setDamping(qreal damping) /*! - \qmlproperty real SpringAnimation::epsilon + \qmlproperty real QtQuick2::SpringAnimation::epsilon This property holds the spring epsilon. The epsilon is the rate and amount of change in the value which is close enough @@ -367,7 +367,7 @@ void QDeclarativeSpringAnimation::setEpsilon(qreal epsilon) } /*! - \qmlproperty real SpringAnimation::modulus + \qmlproperty real QtQuick2::SpringAnimation::modulus This property holds the modulus value. The default value is 0. Setting a \a modulus forces the target value to "wrap around" at the modulus. @@ -391,7 +391,7 @@ void QDeclarativeSpringAnimation::setModulus(qreal modulus) } /*! - \qmlproperty real SpringAnimation::mass + \qmlproperty real QtQuick2::SpringAnimation::mass This property holds the "mass" of the property being moved. The value is 1.0 by default. diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp index 9f56ccb02e..63cb95d7b1 100644 --- a/src/declarative/util/qdeclarativestate.cpp +++ b/src/declarative/util/qdeclarativestate.cpp @@ -130,8 +130,8 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje /*! \qmlclass State QDeclarativeState + \inqmlmodule QtQuick 2 \ingroup qml-state-elements - \since 4.7 \brief The State element defines configurations of objects and properties. A \e state is a set of batched changes from the default configuration. @@ -176,7 +176,7 @@ QDeclarativeState::~QDeclarativeState() } /*! - \qmlproperty string State::name + \qmlproperty string QtQuick2::State::name This property holds the name of the state. Each state should have a unique name within its item. @@ -207,7 +207,7 @@ bool QDeclarativeState::isWhenKnown() const } /*! - \qmlproperty bool State::when + \qmlproperty bool QtQuick2::State::when This property holds when the state should be applied. This should be set to an expression that evaluates to \c true when you want the state to @@ -245,7 +245,7 @@ void QDeclarativeState::setWhen(QDeclarativeBinding *when) } /*! - \qmlproperty string State::extend + \qmlproperty string QtQuick2::State::extend This property holds the state that this state extends. When a state extends another state, it inherits all the changes of that state. @@ -266,7 +266,7 @@ void QDeclarativeState::setExtends(const QString &extends) } /*! - \qmlproperty list<Change> State::changes + \qmlproperty list<Change> QtQuick2::State::changes This property holds the changes to apply for this state \default diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp index 7200ac91af..df16c16fa2 100644 --- a/src/declarative/util/qdeclarativestategroup.cpp +++ b/src/declarative/util/qdeclarativestategroup.cpp @@ -93,8 +93,8 @@ public: /*! \qmlclass StateGroup QDeclarativeStateGroup + \inqmlmodule QtQuick 2 \ingroup qml-state-elements - \since 4.7 \brief The StateGroup element provides state support for non-Item elements. Item (and all derived elements) provides built in support for states and transitions @@ -140,7 +140,7 @@ QList<QDeclarativeState *> QDeclarativeStateGroup::states() const } /*! - \qmlproperty list<State> StateGroup::states + \qmlproperty list<State> QtQuick2::StateGroup::states This property holds a list of states defined by the state group. \qml @@ -201,7 +201,7 @@ void QDeclarativeStateGroupPrivate::clear_states(QDeclarativeListProperty<QDecla } /*! - \qmlproperty list<Transition> StateGroup::transitions + \qmlproperty list<Transition> QtQuick2::StateGroup::transitions This property holds a list of transitions defined by the state group. \qml @@ -255,7 +255,7 @@ void QDeclarativeStateGroupPrivate::clear_transitions(QDeclarativeListProperty<Q } /*! - \qmlproperty string StateGroup::state + \qmlproperty string QtQuick2::StateGroup::state This property holds the name of the current state of the state group. diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp index 0ced8ebd61..6ac21002a5 100644 --- a/src/declarative/util/qdeclarativestateoperations.cpp +++ b/src/declarative/util/qdeclarativestateoperations.cpp @@ -71,6 +71,7 @@ public: /*! \qmlclass StateChangeScript QDeclarativeStateChangeScript + \inqmlmodule QtQuick 2 \ingroup qml-state-elements \brief The StateChangeScript element allows you to run a script in a state. @@ -93,7 +94,7 @@ QDeclarativeStateChangeScript::~QDeclarativeStateChangeScript() } /*! - \qmlproperty script StateChangeScript::script + \qmlproperty script QtQuick2::StateChangeScript::script This property holds the script to run when the state is current. */ QDeclarativeScriptString QDeclarativeStateChangeScript::script() const @@ -109,7 +110,7 @@ void QDeclarativeStateChangeScript::setScript(const QDeclarativeScriptString &s) } /*! - \qmlproperty string StateChangeScript::name + \qmlproperty string QtQuick2::StateChangeScript::name This property holds the name of the script. This name can be used by a ScriptAction to target a specific script. diff --git a/src/declarative/util/qdeclarativesystempalette.cpp b/src/declarative/util/qdeclarativesystempalette.cpp index 3fe2e81df4..7c5a535935 100644 --- a/src/declarative/util/qdeclarativesystempalette.cpp +++ b/src/declarative/util/qdeclarativesystempalette.cpp @@ -58,8 +58,8 @@ public: /*! \qmlclass SystemPalette QDeclarativeSystemPalette + \inqmlmodule QtQuick 2 \ingroup qml-utility-elements - \since 4.7 \brief The SystemPalette element provides access to the Qt palettes. The SystemPalette element provides access to the Qt application @@ -94,7 +94,7 @@ QDeclarativeSystemPalette::~QDeclarativeSystemPalette() } /*! - \qmlproperty color SystemPalette::window + \qmlproperty color QtQuick2::SystemPalette::window The window (general background) color of the current color group. \sa QPalette::ColorRole @@ -106,7 +106,7 @@ QColor QDeclarativeSystemPalette::window() const } /*! - \qmlproperty color SystemPalette::windowText + \qmlproperty color QtQuick2::SystemPalette::windowText The window text (general foreground) color of the current color group. \sa QPalette::ColorRole @@ -118,7 +118,7 @@ QColor QDeclarativeSystemPalette::windowText() const } /*! - \qmlproperty color SystemPalette::base + \qmlproperty color QtQuick2::SystemPalette::base The base color of the current color group. \sa QPalette::ColorRole @@ -130,7 +130,7 @@ QColor QDeclarativeSystemPalette::base() const } /*! - \qmlproperty color SystemPalette::text + \qmlproperty color QtQuick2::SystemPalette::text The text color of the current color group. \sa QPalette::ColorRole @@ -142,7 +142,7 @@ QColor QDeclarativeSystemPalette::text() const } /*! - \qmlproperty color SystemPalette::alternateBase + \qmlproperty color QtQuick2::SystemPalette::alternateBase The alternate base color of the current color group. \sa QPalette::ColorRole @@ -154,7 +154,7 @@ QColor QDeclarativeSystemPalette::alternateBase() const } /*! - \qmlproperty color SystemPalette::button + \qmlproperty color QtQuick2::SystemPalette::button The button color of the current color group. \sa QPalette::ColorRole @@ -166,7 +166,7 @@ QColor QDeclarativeSystemPalette::button() const } /*! - \qmlproperty color SystemPalette::buttonText + \qmlproperty color QtQuick2::SystemPalette::buttonText The button text foreground color of the current color group. \sa QPalette::ColorRole @@ -178,7 +178,7 @@ QColor QDeclarativeSystemPalette::buttonText() const } /*! - \qmlproperty color SystemPalette::light + \qmlproperty color QtQuick2::SystemPalette::light The light color of the current color group. \sa QPalette::ColorRole @@ -190,7 +190,7 @@ QColor QDeclarativeSystemPalette::light() const } /*! - \qmlproperty color SystemPalette::midlight + \qmlproperty color QtQuick2::SystemPalette::midlight The midlight color of the current color group. \sa QPalette::ColorRole @@ -202,7 +202,7 @@ QColor QDeclarativeSystemPalette::midlight() const } /*! - \qmlproperty color SystemPalette::dark + \qmlproperty color QtQuick2::SystemPalette::dark The dark color of the current color group. \sa QPalette::ColorRole @@ -214,7 +214,7 @@ QColor QDeclarativeSystemPalette::dark() const } /*! - \qmlproperty color SystemPalette::mid + \qmlproperty color QtQuick2::SystemPalette::mid The mid color of the current color group. \sa QPalette::ColorRole @@ -226,7 +226,7 @@ QColor QDeclarativeSystemPalette::mid() const } /*! - \qmlproperty color SystemPalette::shadow + \qmlproperty color QtQuick2::SystemPalette::shadow The shadow color of the current color group. \sa QPalette::ColorRole @@ -238,7 +238,7 @@ QColor QDeclarativeSystemPalette::shadow() const } /*! - \qmlproperty color SystemPalette::highlight + \qmlproperty color QtQuick2::SystemPalette::highlight The highlight color of the current color group. \sa QPalette::ColorRole @@ -250,7 +250,7 @@ QColor QDeclarativeSystemPalette::highlight() const } /*! - \qmlproperty color SystemPalette::highlightedText + \qmlproperty color QtQuick2::SystemPalette::highlightedText The highlighted text color of the current color group. \sa QPalette::ColorRole @@ -262,7 +262,7 @@ QColor QDeclarativeSystemPalette::highlightedText() const } /*! - \qmlproperty enumeration SystemPalette::colorGroup + \qmlproperty enumeration QtQuick2::SystemPalette::colorGroup The color group of the palette. This can be one of: diff --git a/src/declarative/util/qdeclarativetimer.cpp b/src/declarative/util/qdeclarativetimer.cpp index de3e6ce44d..de37f60bf5 100644 --- a/src/declarative/util/qdeclarativetimer.cpp +++ b/src/declarative/util/qdeclarativetimer.cpp @@ -70,8 +70,8 @@ public: /*! \qmlclass Timer QDeclarativeTimer + \inqmlmodule QtQuick 2 \ingroup qml-utility-elements - \since 4.7 \brief The Timer item triggers a handler at a specified interval. A Timer can be used to trigger an action either once, or repeatedly @@ -118,7 +118,7 @@ QDeclarativeTimer::QDeclarativeTimer(QObject *parent) } /*! - \qmlproperty int Timer::interval + \qmlproperty int QtQuick2::Timer::interval Sets the \a interval between triggers, in milliseconds. @@ -141,7 +141,7 @@ int QDeclarativeTimer::interval() const } /*! - \qmlproperty bool Timer::running + \qmlproperty bool QtQuick2::Timer::running If set to true, starts the timer; otherwise stops the timer. For a non-repeating timer, \a running is set to false after the @@ -169,7 +169,7 @@ void QDeclarativeTimer::setRunning(bool running) } /*! - \qmlproperty bool Timer::repeat + \qmlproperty bool QtQuick2::Timer::repeat If \a repeat is true the timer is triggered repeatedly at the specified interval; otherwise, the timer will trigger once at the @@ -196,7 +196,7 @@ void QDeclarativeTimer::setRepeating(bool repeating) } /*! - \qmlproperty bool Timer::triggeredOnStart + \qmlproperty bool QtQuick2::Timer::triggeredOnStart When a timer is started, the first trigger is usually after the specified interval has elapsed. It is sometimes desirable to trigger immediately @@ -229,7 +229,7 @@ void QDeclarativeTimer::setTriggeredOnStart(bool triggeredOnStart) } /*! - \qmlmethod Timer::start() + \qmlmethod QtQuick2::Timer::start() \brief Starts the timer. If the timer is already running, calling this method has no effect. The @@ -241,7 +241,7 @@ void QDeclarativeTimer::start() } /*! - \qmlmethod Timer::stop() + \qmlmethod QtQuick2::Timer::stop() \brief Stops the timer. If the timer is not running, calling this method has no effect. The @@ -253,7 +253,7 @@ void QDeclarativeTimer::stop() } /*! - \qmlmethod Timer::restart() + \qmlmethod QtQuick2::Timer::restart() \brief Restarts the timer. If the Timer is not running it will be started, otherwise it will be @@ -298,7 +298,7 @@ void QDeclarativeTimer::componentComplete() } /*! - \qmlsignal Timer::onTriggered() + \qmlsignal QtQuick2::Timer::onTriggered() This handler is called when the Timer is triggered. */ diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp index e3af6b724f..5351f8a5c9 100644 --- a/src/declarative/util/qdeclarativetransition.cpp +++ b/src/declarative/util/qdeclarativetransition.cpp @@ -53,8 +53,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Transition QDeclarativeTransition + \inqmlmodule QtQuick 2 \ingroup qml-animation-transition - \since 4.7 \brief The Transition element defines animated transitions that occur on state changes. A Transition defines the animations to be applied when a \l State change occurs. @@ -225,8 +225,8 @@ void QDeclarativeTransition::prepare(QDeclarativeStateOperation::ActionList &act } /*! - \qmlproperty string Transition::from - \qmlproperty string Transition::to + \qmlproperty string QtQuick2::Transition::from + \qmlproperty string QtQuick2::Transition::to These properties indicate the state changes that trigger the transition. @@ -266,7 +266,7 @@ void QDeclarativeTransition::setFromState(const QString &f) } /*! - \qmlproperty bool Transition::reversible + \qmlproperty bool QtQuick2::Transition::reversible This property holds whether the transition should be automatically reversed when the conditions that triggered this transition are reversed. The default value is false. @@ -322,7 +322,7 @@ void QDeclarativeTransition::setToState(const QString &t) } /*! - \qmlproperty bool Transition::enabled + \qmlproperty bool QtQuick2::Transition::enabled This property holds whether the Transition will be run when moving from the \c from state to the \c to state. @@ -365,7 +365,7 @@ void QDeclarativeTransition::setEnabled(bool enabled) } /*! - \qmlproperty list<Animation> Transition::animations + \qmlproperty list<Animation> QtQuick2::Transition::animations \default This property holds a list of the animations to be run for this transition. diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp index 6b0edc00fc..7ac6c7679e 100644 --- a/src/declarative/util/qdeclarativexmllistmodel.cpp +++ b/src/declarative/util/qdeclarativexmllistmodel.cpp @@ -71,15 +71,15 @@ typedef QPair<int, int> QDeclarativeXmlListRange; /*! \qmlclass XmlRole QDeclarativeXmlListModelRole + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data - \since 4.7 \brief The XmlRole element allows you to specify a role for an XmlListModel. \sa {QtDeclarative} */ /*! - \qmlproperty string XmlRole::name + \qmlproperty string QtQuick2::XmlRole::name The name for the role. This name is used to access the model data for this role. @@ -106,7 +106,7 @@ typedef QPair<int, int> QDeclarativeXmlListRange; */ /*! - \qmlproperty string XmlRole::query + \qmlproperty string QtQuick2::XmlRole::query The relative XPath expression query for this role. The query must be relative; it cannot start with a '/'. @@ -124,7 +124,7 @@ typedef QPair<int, int> QDeclarativeXmlListRange; */ /*! - \qmlproperty bool XmlRole::isKey + \qmlproperty bool QtQuick2::XmlRole::isKey Defines whether this is a key role. Key roles are used to to determine whether a set of values should @@ -597,8 +597,8 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla /*! \qmlclass XmlListModel QDeclarativeXmlListModel + \inqmlmodule QtQuick 2 \ingroup qml-working-with-data - \since 4.7 \brief The XmlListModel element is used to specify a read-only model using XPath expressions. XmlListModel is used to create a read-only model from XML data. It can be used as a data source @@ -702,7 +702,7 @@ QDeclarativeXmlListModel::~QDeclarativeXmlListModel() } /*! - \qmlproperty list<XmlRole> XmlListModel::roles + \qmlproperty list<XmlRole> QtQuick2::XmlListModel::roles The roles to make available for this model. */ @@ -735,7 +735,7 @@ QVariant QDeclarativeXmlListModel::data(int index, int role) const } /*! - \qmlproperty int XmlListModel::count + \qmlproperty int QtQuick2::XmlListModel::count The number of data entries in the model. */ int QDeclarativeXmlListModel::count() const @@ -760,7 +760,7 @@ QString QDeclarativeXmlListModel::toString(int role) const } /*! - \qmlproperty url XmlListModel::source + \qmlproperty url QtQuick2::XmlListModel::source The location of the XML data source. If both \c source and \l xml are set, \l xml is used. @@ -783,7 +783,7 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src) } /*! - \qmlproperty string XmlListModel::xml + \qmlproperty string QtQuick2::XmlListModel::xml This property holds the XML data for this model, if set. The text is assumed to be UTF-8 encoded. @@ -807,7 +807,7 @@ void QDeclarativeXmlListModel::setXml(const QString &xml) } /*! - \qmlproperty string XmlListModel::query + \qmlproperty string QtQuick2::XmlListModel::query An absolute XPath query representing the base query for creating model items from this model's XmlRole objects. The query should start with '/' or '//'. */ @@ -833,7 +833,7 @@ void QDeclarativeXmlListModel::setQuery(const QString &query) } /*! - \qmlproperty string XmlListModel::namespaceDeclarations + \qmlproperty string QtQuick2::XmlListModel::namespaceDeclarations The namespace declarations to be used in the XPath queries. The namespaces should be declared as in XQuery. For example, if a requested document @@ -867,7 +867,7 @@ void QDeclarativeXmlListModel::setNamespaceDeclarations(const QString &declarati } /*! - \qmlmethod object XmlListModel::get(int index) + \qmlmethod object QtQuick2::XmlListModel::get(int index) Returns the item at \a index in the model. @@ -907,7 +907,7 @@ QDeclarativeV8Handle QDeclarativeXmlListModel::get(int index) const } /*! - \qmlproperty enumeration XmlListModel::status + \qmlproperty enumeration QtQuick2::XmlListModel::status Specifies the model loading status, which can be one of the following: \list @@ -928,7 +928,7 @@ QDeclarativeXmlListModel::Status QDeclarativeXmlListModel::status() const } /*! - \qmlproperty real XmlListModel::progress + \qmlproperty real QtQuick2::XmlListModel::progress This indicates the current progress of the downloading of the XML data source. This value ranges from 0.0 (no data downloaded) to @@ -949,7 +949,7 @@ qreal QDeclarativeXmlListModel::progress() const } /*! - \qmlmethod void XmlListModel::errorString() + \qmlmethod void QtQuick2::XmlListModel::errorString() Returns a string description of the last error that occurred if \l status is XmlListModel::Error. @@ -980,7 +980,7 @@ void QDeclarativeXmlListModel::componentComplete() } /*! - \qmlmethod XmlListModel::reload() + \qmlmethod QtQuick2::XmlListModel::reload() Reloads the model. diff --git a/src/declarative/util/qlistmodelinterface.cpp b/src/declarative/util/qlistmodelinterface.cpp index 17fce99f15..56fc8eeb51 100644 --- a/src/declarative/util/qlistmodelinterface.cpp +++ b/src/declarative/util/qlistmodelinterface.cpp @@ -46,7 +46,6 @@ QT_BEGIN_NAMESPACE /*! \internal \class QListModelInterface - \since 4.7 \brief The QListModelInterface class can be subclassed to provide C++ models to QDeclarativeGraphics Views This class is comprised primarily of pure virtual functions which |