diff options
Diffstat (limited to 'src/declarative/items/qsgrectangle.cpp')
| -rw-r--r-- | src/declarative/items/qsgrectangle.cpp | 273 |
1 files changed, 253 insertions, 20 deletions
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 { |