Merge branch '4.7' of scm.dev.nokia.troll.no:qt/qt-qml into 4.7-integration

* '4.7' of scm.dev.nokia.troll.no:qt/qt-qml:
  Various doc fixes and improvements
  Document issues with rectangle border width of 1 where clipping is used
  Simplify selection setting. Make TextInput more like TextEdit.

7 files changed, 133 insertions, 77 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index 301ca005b9..de3dbcd19e 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()
 {
diff --git a/src/declarative/graphicsitems/qdeclarativerepeater.cpp b/src/declarative/graphicsitems/qdeclarativerepeater.cpp
index 04076f826b..691cfa24bf 100644
--- a/src/declarative/graphicsitems/qdeclarativerepeater.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerepeater.cpp
@@ -80,14 +80,20 @@ QDeclarativeRepeaterPrivate::~QDeclarativeRepeaterPrivate()
     The index is always exposed as an accessible \c index property.
     In the case of an object or string list, the data element (of type string
     or object) is available as the \c modelData property.  In the case of a Qt model,
-    all roles are available as named properties just like in the view classes. The
-    following example shows how to use the index property inside the instantiated
-    items.
+    all roles are available as named properties just like in the view classes. 
 
-    \snippet doc/src/snippets/declarative/repeater-index.qml 0
+    The following example shows how to use the \c index property inside the instantiated
+    items:
 
+    \snippet doc/src/snippets/declarative/repeater-index.qml 0
     \image repeater-index.png
 
+    The repeater could also use the \c modelData property to reference the data for a
+    particular index:
+
+    \snippet doc/src/snippets/declarative/repeater-modeldata.qml 0
+    \image repeater-modeldata.png
+
     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 is to allow
diff --git a/src/declarative/graphicsitems/qdeclarativetextedit.cpp b/src/declarative/graphicsitems/qdeclarativetextedit.cpp
index f8876f2af8..935b431506 100644
--- a/src/declarative/graphicsitems/qdeclarativetextedit.cpp
+++ b/src/declarative/graphicsitems/qdeclarativetextedit.cpp
@@ -717,12 +717,9 @@ void QDeclarativeTextEdit::loadCursorDelegate()
     \qmlproperty int TextEdit::selectionStart
 
     The cursor position before the first character in the current selection.
-    Setting this and selectionEnd allows you to specify a selection in the
-    text edit.
 
-    Note that if selectionStart == selectionEnd then there is no current
-    selection. If you attempt to set selectionStart to a value outside of
-    the current text, selectionStart will not be changed.
+    This property is read-only. To change the selection, use select(start,end),
+    selectAll(), or selectWord().
 
     \sa selectionEnd, cursorPosition, selectedText
 */
@@ -732,25 +729,13 @@ int QDeclarativeTextEdit::selectionStart() const
     return d->control->textCursor().selectionStart();
 }
 
-void QDeclarativeTextEdit::setSelectionStart(int s)
-{
-    Q_D(QDeclarativeTextEdit);
-    if(d->lastSelectionStart == s || s < 0 || s > text().length())
-        return;
-    d->lastSelectionStart = s;
-    d->updateSelection();// Will emit the relevant signals
-}
-
 /*!
     \qmlproperty int TextEdit::selectionEnd
 
     The cursor position after the last character in the current selection.
-    Setting this and selectionStart allows you to specify a selection in the
-    text edit.
 
-    Note that if selectionStart == selectionEnd then there is no current
-    selection. If you attempt to set selectionEnd to a value outside of
-    the current text, selectionEnd will not be changed.
+    This property is read-only. To change the selection, use select(start,end),
+    selectAll(), or selectWord().
 
     \sa selectionStart, cursorPosition, selectedText
 */
@@ -760,15 +745,6 @@ int QDeclarativeTextEdit::selectionEnd() const
     return d->control->textCursor().selectionEnd();
 }
 
-void QDeclarativeTextEdit::setSelectionEnd(int s)
-{
-    Q_D(QDeclarativeTextEdit);
-    if(d->lastSelectionEnd == s || s < 0 || s > text().length())
-        return;
-    d->lastSelectionEnd = s;
-    d->updateSelection();// Will emit the relevant signals
-}
-
 /*!
     \qmlproperty string TextEdit::selectedText
 
@@ -1018,6 +994,8 @@ void QDeclarativeTextEditPrivate::focusChanged(bool hasFocus)
 }
 
 /*!
+    \qmlmethod void TextEdit::selectAll()
+
     Causes all text to be selected.
 */
 void QDeclarativeTextEdit::selectAll()
@@ -1027,6 +1005,8 @@ void QDeclarativeTextEdit::selectAll()
 }
 
 /*!
+    \qmlmethod void TextEdit::selectWord()
+
     Causes the word closest to the current cursor position to be selected.
 */
 void QDeclarativeTextEdit::selectWord()
@@ -1038,6 +1018,35 @@ void QDeclarativeTextEdit::selectWord()
 }
 
 /*!
+    \qmlmethod void TextEdit::select(start,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 QDeclarativeTextEdit::select(int start, int end)
+{
+    Q_D(QDeclarativeTextEdit);
+    if (start < 0 || end < 0 || start > d->text.length() || end > d->text.length())
+        return;
+    QTextCursor cursor = d->control->textCursor();
+    cursor.beginEditBlock();
+    cursor.setPosition(start, QTextCursor::MoveAnchor);
+    cursor.setPosition(end, QTextCursor::KeepAnchor);
+    cursor.endEditBlock();
+    d->control->setTextCursor(cursor);
+
+    // QTBUG-11100
+    updateSelectionMarkers();
+}
+
+/*!
     \qmlmethod TextEdit::cut()
 
     Moves the currently selected text to the system clipboard.
@@ -1254,7 +1263,6 @@ void QDeclarativeTextEditPrivate::updateSelection()
     QTextCursor cursor = control->textCursor();
     bool startChange = (lastSelectionStart != cursor.selectionStart());
     bool endChange = (lastSelectionEnd != cursor.selectionEnd());
-    //### Is it worth calculating a more minimal set of movements?
     cursor.beginEditBlock();
     cursor.setPosition(lastSelectionStart, QTextCursor::MoveAnchor);
     cursor.setPosition(lastSelectionEnd, QTextCursor::KeepAnchor);
@@ -1264,8 +1272,6 @@ void QDeclarativeTextEditPrivate::updateSelection()
         q->selectionStartChanged();
     if(endChange)
         q->selectionEndChanged();
-    startChange = (lastSelectionStart != control->textCursor().selectionStart());
-    endChange = (lastSelectionEnd != control->textCursor().selectionEnd());
 }
 
 void QDeclarativeTextEdit::updateSelectionMarkers()
diff --git a/src/declarative/graphicsitems/qdeclarativetextedit_p.h b/src/declarative/graphicsitems/qdeclarativetextedit_p.h
index a83b3db635..3abfc352cf 100644
--- a/src/declarative/graphicsitems/qdeclarativetextedit_p.h
+++ b/src/declarative/graphicsitems/qdeclarativetextedit_p.h
@@ -82,8 +82,8 @@ class Q_DECLARATIVE_EXPORT QDeclarativeTextEdit : public QDeclarativePaintedItem
     Q_PROPERTY(int cursorPosition READ cursorPosition WRITE setCursorPosition NOTIFY cursorPositionChanged)
     Q_PROPERTY(QRect cursorRectangle READ cursorRectangle NOTIFY cursorRectangleChanged)
     Q_PROPERTY(QDeclarativeComponent* cursorDelegate READ cursorDelegate WRITE setCursorDelegate NOTIFY cursorDelegateChanged)
-    Q_PROPERTY(int selectionStart READ selectionStart WRITE setSelectionStart NOTIFY selectionStartChanged)
-    Q_PROPERTY(int selectionEnd READ selectionEnd WRITE setSelectionEnd NOTIFY selectionEndChanged)
+    Q_PROPERTY(int selectionStart READ selectionStart NOTIFY selectionStartChanged)
+    Q_PROPERTY(int selectionEnd READ selectionEnd NOTIFY selectionEndChanged)
     Q_PROPERTY(QString selectedText READ selectedText NOTIFY selectionChanged)
     Q_PROPERTY(bool focusOnPress READ focusOnPress WRITE setFocusOnPress NOTIFY focusOnPressChanged)
     Q_PROPERTY(bool showInputPanelOnFocus READ showInputPanelOnFocus WRITE setShowInputPanelOnFocus NOTIFY showInputPanelOnFocusChanged)
@@ -160,10 +160,7 @@ public:
     void setCursorDelegate(QDeclarativeComponent*);
 
     int selectionStart() const;
-    void setSelectionStart(int);
-
     int selectionEnd() const;
-    void setSelectionEnd(int);
 
     QString selectedText() const;
 
@@ -230,6 +227,7 @@ Q_SIGNALS:
 public Q_SLOTS:
     void selectAll();
     void selectWord();
+    void select(int start, int end);
     void cut();
     void copy();
     void paste();
diff --git a/src/declarative/graphicsitems/qdeclarativetextinput.cpp b/src/declarative/graphicsitems/qdeclarativetextinput.cpp
index 9a6a0706cb..25a2b490b1 100644
--- a/src/declarative/graphicsitems/qdeclarativetextinput.cpp
+++ b/src/declarative/graphicsitems/qdeclarativetextinput.cpp
@@ -46,6 +46,7 @@
 #include <qdeclarativeinfo.h>
 
 #include <QValidator>
+#include <QTextCursor>
 #include <QApplication>
 #include <QFontMetrics>
 #include <QPainter>
@@ -429,10 +430,12 @@ void QDeclarativeTextInput::setCursorPosition(int cp)
   Returns a Rect which encompasses the cursor, but which may be larger than is
   required. Ignores custom cursor delegates.
 */
-QRect QDeclarativeTextInput::cursorRect() const
+QRect QDeclarativeTextInput::cursorRectangle() const
 {
     Q_D(const QDeclarativeTextInput);
-    return d->control->cursorRect();
+    QRect r = d->control->cursorRect();
+    r.setHeight(r.height()-1); // Make consistent with TextEdit (QLineControl inexplicably adds 1)
+    return r;
 }
 
 /*!
@@ -454,15 +457,6 @@ int QDeclarativeTextInput::selectionStart() const
     return d->lastSelectionStart;
 }
 
-void QDeclarativeTextInput::setSelectionStart(int s)
-{
-    Q_D(QDeclarativeTextInput);
-    if(d->lastSelectionStart == s || s < 0 || s > text().length())
-        return;
-    d->lastSelectionStart = s;
-    d->control->setSelection(s, d->lastSelectionEnd - s);
-}
-
 /*!
     \qmlproperty int TextInput::selectionEnd
 
@@ -482,13 +476,12 @@ int QDeclarativeTextInput::selectionEnd() const
     return d->lastSelectionEnd;
 }
 
-void QDeclarativeTextInput::setSelectionEnd(int s)
+void QDeclarativeTextInput::select(int start, int end)
 {
     Q_D(QDeclarativeTextInput);
-    if(d->lastSelectionEnd == s || s < 0 || s > text().length())
+    if (start < 0 || end < 0 || start > d->control->text().length() || end > d->control->text().length())
         return;
-    d->lastSelectionEnd = s;
-    d->control->setSelection(d->lastSelectionStart, s - d->lastSelectionStart);
+    d->control->setSelection(start, end-start);
 }
 
 /*!
@@ -833,6 +826,19 @@ void QDeclarativeTextInput::moveCursor()
 }
 
 /*!
+    \qmlmethod rect TextInput::positionToRectangle(int x)
+*/
+QRectF QDeclarativeTextInput::positionToRectangle(int x) const
+{
+    Q_D(const QDeclarativeTextInput);
+    QFontMetrics fm = QFontMetrics(d->font);
+    return QRectF(d->control->cursorToX(x)-d->hscroll,
+        0.0,
+        d->control->cursorWidth(),
+        cursorRectangle().height());
+}
+
+/*!
     \qmlmethod int TextInput::positionAt(int x)
 
     This function returns the character position at
@@ -843,7 +849,7 @@ void QDeclarativeTextInput::moveCursor()
     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.
 */
-int QDeclarativeTextInput::positionAt(int x)
+int QDeclarativeTextInput::positionAt(int x) const
 {
     Q_D(const QDeclarativeTextInput);
     return d->control->xToPos(x - d->hscroll);
@@ -1019,7 +1025,6 @@ void QDeclarativeTextInput::drawContents(QPainter *p, const QRect &r)
         d->hscroll -= minLB;
         offset = QPoint(d->hscroll, 0);
     }
-
     d->control->draw(p, offset, r, flags);
 
     p->restore();
@@ -1057,12 +1062,27 @@ QVariant QDeclarativeTextInput::inputMethodQuery(Qt::InputMethodQuery property)
     }
 }
 
+/*!
+    \qmlmethod void TextInput::selectAll()
+
+    Causes all text to be selected.
+*/
 void QDeclarativeTextInput::selectAll()
 {
     Q_D(QDeclarativeTextInput);
     d->control->setSelection(0, d->control->text().length());
 }
 
+/*!
+    \qmlmethod void TextInput::selectWord()
+
+    Causes the word closest to the current cursor position to be selected.
+*/
+void QDeclarativeTextInput::selectWord()
+{
+    Q_D(QDeclarativeTextInput);
+    d->control->selectWordAtPos(d->control->cursor());
+}
 
 /*!
     \qmlproperty bool TextInput::smooth
diff --git a/src/declarative/graphicsitems/qdeclarativetextinput_p.h b/src/declarative/graphicsitems/qdeclarativetextinput_p.h
index 6bb94c2e79..0b7ddd5f45 100644
--- a/src/declarative/graphicsitems/qdeclarativetextinput_p.h
+++ b/src/declarative/graphicsitems/qdeclarativetextinput_p.h
@@ -72,10 +72,10 @@ class Q_DECLARATIVE_EXPORT QDeclarativeTextInput : public QDeclarativePaintedIte
     Q_PROPERTY(bool readOnly READ isReadOnly WRITE setReadOnly NOTIFY readOnlyChanged)
     Q_PROPERTY(bool cursorVisible READ isCursorVisible WRITE setCursorVisible NOTIFY cursorVisibleChanged)
     Q_PROPERTY(int cursorPosition READ cursorPosition WRITE setCursorPosition NOTIFY cursorPositionChanged)
-    Q_PROPERTY(QRect cursorRect READ cursorRect NOTIFY cursorPositionChanged)
+    Q_PROPERTY(QRect cursorRectangle READ cursorRectangle NOTIFY cursorPositionChanged)
     Q_PROPERTY(QDeclarativeComponent *cursorDelegate READ cursorDelegate WRITE setCursorDelegate NOTIFY cursorDelegateChanged)
-    Q_PROPERTY(int selectionStart READ selectionStart WRITE setSelectionStart NOTIFY selectionStartChanged)
-    Q_PROPERTY(int selectionEnd READ selectionEnd WRITE setSelectionEnd NOTIFY selectionEndChanged)
+    Q_PROPERTY(int selectionStart READ selectionStart NOTIFY selectionStartChanged)
+    Q_PROPERTY(int selectionEnd READ selectionEnd NOTIFY selectionEndChanged)
     Q_PROPERTY(QString selectedText READ selectedText NOTIFY selectedTextChanged)
 
     Q_PROPERTY(int maximumLength READ maxLength WRITE setMaxLength NOTIFY maximumLengthChanged)
@@ -110,7 +110,8 @@ public:
     };
 
     //Auxilliary functions needed to control the TextInput from QML
-    Q_INVOKABLE int positionAt(int x);
+    Q_INVOKABLE int positionAt(int x) const;
+    Q_INVOKABLE QRectF positionToRectangle(int x) const;
     Q_INVOKABLE void moveCursorSelection(int pos);
 
     Q_INVOKABLE void openSoftwareInputPanel();
@@ -143,13 +144,10 @@ public:
     int cursorPosition() const;
     void setCursorPosition(int cp);
 
-    QRect cursorRect() const;
+    QRect cursorRectangle() const;
 
     int selectionStart() const;
-    void setSelectionStart(int);
-
     int selectionEnd() const;
-    void setSelectionEnd(int);
 
     QString selectedText() const;
 
@@ -231,6 +229,8 @@ protected:
 
 public Q_SLOTS:
     void selectAll();
+    void selectWord();
+    void select(int start, int end);
 
 private Q_SLOTS:
     void updateSize(bool needsRedraw = true);
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index 8679e76d3e..d8c842bdc9 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -155,14 +155,26 @@ void QDeclarativeEnginePrivate::defineModule()
 \qmlclass Qt QDeclarativeEnginePrivate
 \brief The QML global Qt object provides useful enums and functions from Qt.
 
-The Qt object provides useful enums and functions from Qt, for use in all QML files. 
+The \c Qt object provides useful enums and functions from Qt, for use in all QML files. 
+
+The \c Qt object is not a QML element; it cannot be instantiated. It is a global object 
+with enums and functions.  To use it, call the members of the global \c Qt object directly. 
+For example:
+
+\qml
+import Qt 4.7
+
+Text {
+    color: Qt.rgba(255, 0, 0, 1)
+    text: Qt.md5("hello, world")
+}
+\endqml
 
-You do not create instances of this type, but instead use the members of the global "Qt" object.
 
 \section1 Enums
 
 The Qt object contains all enums in the Qt namespace. For example, you can
-access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft.
+access the \c AlignLeft member of the \c Qt::AlignmentFlag enum with \c Qt.AlignLeft.
 
 For a full list of enums, see the \l{Qt Namespace} documentation.
 
@@ -172,7 +184,7 @@ data types. This is primarily useful when setting the properties of an item
 when the property has one of the following types:
 
 \list
-\o \c color - use \l{Qt::rgba()}{Qt.rgba()}, \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()} or \l{Qt::tint()}{Qt.tint()}
+\o \c color - use \l{Qt::rgba()}{Qt.rgba()}, \l{Qt::hsla()}{Qt.hsla()}, \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()} or \l{Qt::tint()}{Qt.tint()}
 \o \c rect - use \l{Qt::rect()}{Qt.rect()}
 \o \c point - use \l{Qt::point()}{Qt.point()}
 \o \c size - use \l{Qt::size()}{Qt.size()}
@@ -200,8 +212,8 @@ items from files or strings. See \l{Dynamic Object Management} for an overview
 of their use.
 
 \list
-    \o \l{Qt::createComponent}{object Qt.createComponent(url)}
-    \o \l{Qt::createQmlObject}{object Qt.createQmlObject(string qml, object parent, string filepath)}
+    \o \l{Qt::createComponent()}{object Qt.createComponent(url)}
+    \o \l{Qt::createQmlObject()}{object Qt.createQmlObject(string qml, object parent, string filepath)}
 \endlist
 */
 
@@ -1034,7 +1046,7 @@ QString QDeclarativeEnginePrivate::urlToLocalFileOrQrc(const QUrl& url)
 /*!
 \qmlmethod object Qt::createComponent(url)
 
-Returns a \l Component object created from the QML file at the specified \a url,
+Returns a \l Component object created using the QML file at the specified \a url,
 or \c null if there was an error in creating the component.
 
 Call \l {Component::createObject()}{Component.createObject()} on the returned
@@ -1360,7 +1372,7 @@ QScriptValue QDeclarativeEnginePrivate::formatDateTime(QScriptContext*ctxt, QScr
 /*!
 \qmlmethod color Qt::rgba(real red, real green, real blue, real alpha)
 
-Returns a Color with the specified \c red, \c green, \c blue and \c alpha components.
+Returns a color with the specified \c red, \c green, \c blue and \c alpha components.
 All components should be in the range 0-1 inclusive.
 */
 QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1388,7 +1400,7 @@ QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine
 /*!
 \qmlmethod color Qt::hsla(real hue, real saturation, real lightness, real alpha)
 
-Returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components.
+Returns a color with the specified \c hue, \c saturation, \c lightness and \c alpha components.
 All components should be in the range 0-1 inclusive.
 */
 QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1416,7 +1428,9 @@ QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine
 /*!
 \qmlmethod rect Qt::rect(int x, int y, int width, int height) 
 
-Returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height.
+Returns a \c rect with the top-left corner at \c x, \c y and the specified \c width and \c height.
+
+The returned object has \c x, \c y, \c width and \c height attributes with the given values.
 */
 QScriptValue QDeclarativeEnginePrivate::rect(QScriptContext *ctxt, QScriptEngine *engine)
 {