From e5cc765d2fa1ff68f1592ad475d6b8f4e5a6f667 Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Mon, 31 May 2010 14:45:43 +1000
Subject: Document issues with rectangle border width of 1 where clipping is
 used

---
 doc/src/declarative/pics/rect-border-width.png       | Bin 0 -> 356 bytes
 doc/src/snippets/declarative/rect-border-width.qml   |  19 +++++++++++++++++++
 .../graphicsitems/qdeclarativerectangle.cpp          |  16 ++++++++++++++--
 3 files changed, 33 insertions(+), 2 deletions(-)
 create mode 100644 doc/src/declarative/pics/rect-border-width.png
 create mode 100644 doc/src/snippets/declarative/rect-border-width.qml

diff --git a/doc/src/declarative/pics/rect-border-width.png b/doc/src/declarative/pics/rect-border-width.png
new file mode 100644
index 0000000..c3c6c2c
Binary files /dev/null and b/doc/src/declarative/pics/rect-border-width.png differ
diff --git a/doc/src/snippets/declarative/rect-border-width.qml b/doc/src/snippets/declarative/rect-border-width.qml
new file mode 100644
index 0000000..27a241d
--- /dev/null
+++ b/doc/src/snippets/declarative/rect-border-width.qml
@@ -0,0 +1,19 @@
+import Qt 4.7
+
+//![0]
+Rectangle {
+    width: 100; height: 100
+    color: "yellow"
+
+    Rectangle {
+        anchor.fill: parent
+        anchors.margins: 10
+        clip: true
+
+        Rectangle {
+            anchors.fill: parent
+            border.width: 1
+        }
+    }
+}
+//![0]
diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index 301ca00..de3dbcd 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -202,8 +202,20 @@ void QDeclarativeRectangle::doUpdate()
 
     A width of 1 creates a thin line. For no line, use a width of 0 or a transparent color.
 
-    To keep the border smooth (rather than blurry), odd widths cause the rectangle to be painted at
-    a half-pixel offset;
+    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{clip}{clipped} by a parent item:
+   
+    \table
+    \row
+    \o \snippet doc/src/snippets/declarative/rect-border-width.qml 0
+    \o \image rect-border-width.png
+    \endtable
+
+    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.
 */
 QDeclarativePen *QDeclarativeRectangle::border()
 {
-- 
cgit v0.12