From a4b6572b8fb8eb247a7bd952dca7e99e5d4e5707 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Tue, 14 Sep 2010 20:35:48 +0200 Subject: Doc: Continued work on the QML documentation. --- doc/src/declarative/pics/gradient.png | Bin 364 -> 0 bytes doc/src/declarative/pics/qml-gradient.png | Bin 0 -> 364 bytes .../declarative/rectangle/rectangle-smooth.qml | 87 +++++++++++++++++++++ .../graphicsitems/qdeclarativerectangle.cpp | 59 +++++++++++--- src/gui/painting/qbrush.cpp | 15 ++-- 5 files changed, 143 insertions(+), 18 deletions(-) delete mode 100644 doc/src/declarative/pics/gradient.png create mode 100644 doc/src/declarative/pics/qml-gradient.png create mode 100644 doc/src/snippets/declarative/rectangle/rectangle-smooth.qml diff --git a/doc/src/declarative/pics/gradient.png b/doc/src/declarative/pics/gradient.png deleted file mode 100644 index 5eefdd2..0000000 Binary files a/doc/src/declarative/pics/gradient.png and /dev/null differ diff --git a/doc/src/declarative/pics/qml-gradient.png b/doc/src/declarative/pics/qml-gradient.png new file mode 100644 index 0000000..5eefdd2 Binary files /dev/null and b/doc/src/declarative/pics/qml-gradient.png differ diff --git a/doc/src/snippets/declarative/rectangle/rectangle-smooth.qml b/doc/src/snippets/declarative/rectangle/rectangle-smooth.qml new file mode 100644 index 0000000..e1d6980 --- /dev/null +++ b/doc/src/snippets/declarative/rectangle/rectangle-smooth.qml @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import Qt 4.7 + +Rectangle { + width: 400; height: 200 + color: "white" + + Grid { + anchors.centerIn: parent + columns: 4; rows: 2; spacing: 10 + + Rectangle { + color: "steelblue"; width: 80; height: 80 + rotation: 10 + } + Rectangle { + color: "#F0A080"; width: 80; height: 80 + border.color: "gray"; rotation: 10 + } + Rectangle { + color: "steelblue"; width: 80; height: 80 + radius: 10; rotation: 10 + } + Rectangle { + color: "#F0A080"; width: 80; height: 80 + radius: 10; border.color: "gray" + rotation: 10 + } + + Rectangle { + color: "steelblue"; width: 80; height: 80 + rotation: 10; smooth: true + } + Rectangle { + color: "#F0A080"; width: 80; height: 80 + border.color: "gray"; rotation: 10; smooth: true + } + Rectangle { + color: "steelblue"; width: 80; height: 80 + radius: 10; rotation: 10; smooth: true + } + Rectangle { + color: "#F0A080"; width: 80; height: 80 + radius: 10; border.color: "gray" + rotation: 10; smooth: true + } + } +} diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp index 9238004..e33969d 100644 --- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp +++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp @@ -95,7 +95,12 @@ void QDeclarativePen::setWidth(int w) \qmlproperty real GradientStop::position \qmlproperty color GradientStop::color - Sets a \e color at a \e position in a gradient. + 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 */ void QDeclarativeGradientStop::updateGradient() @@ -107,20 +112,50 @@ void QDeclarativeGradientStop::updateGradient() /*! \qmlclass Gradient QDeclarativeGradient \ingroup qml-basic-visual-elements - \since 4.7 + \since 4.7 \brief The Gradient item defines a gradient fill. - A gradient is defined by two or more colors, which will be blended seemlessly. The - colors are specified at their position in the range 0.0 - 1.0 via - the GradientStop item. For example, the following code paints a - rectangle with a gradient starting with red, blending to yellow at 1/3 of the - size of the rectangle, and ending with Green: + A gradient is defined by two or more colors, which will be blended seamlessly. - \snippet doc/src/snippets/declarative/gradient.qml code + 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 item (like rectangle) which supports having a gradient set - on it for display. + gradient, use a visual element (like \l Rectangle) which supports the use + of gradients. + + \section1 Example Usage + + \beginfloatright + \inlineimage qml-gradient.png + \endfloat + + 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 */ @@ -128,6 +163,10 @@ void QDeclarativeGradientStop::updateGradient() /*! \qmlproperty list Gradient::stops 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. */ const QGradient *QDeclarativeGradient::gradient() const diff --git a/src/gui/painting/qbrush.cpp b/src/gui/painting/qbrush.cpp index d3061d8..d0788c7 100644 --- a/src/gui/painting/qbrush.cpp +++ b/src/gui/painting/qbrush.cpp @@ -1218,17 +1218,16 @@ QDataStream &operator>>(QDataStream &s, QBrush &b) \o QConicalGradient \endtable - The colors in a gradient is defined using stop points of the - QGradientStop type, i.e. a position and a color. Use the - setColorAt() function to define a single stop - point. Alternatively, use the setStops() function to define - several stop points in one go. Note that the latter function \e - replaces the current set of stop points. + The colors in a gradient are defined using stop points of the + QGradientStop type; i.e., a position and a color. Use the setColorAt() + function to define a single stop point. Alternatively, use the + setStops() function to define several stop points in one go. Note that + the latter function \e replaces the current set of stop points. It is the gradient's complete set of stop points (accessible through the stops() function) that describes how the gradient area - should be filled. If no stop points have been specified, a - gradient of black at 0 to white at 1 is used. + should be filled. If no stop points have been specified, a gradient + of black at 0 to white at 1 is used. A diagonal linear gradient from black at (100, 100) to white at (200, 200) could be specified like this: -- cgit v0.12