Added a placeholderText(*) property to QLineEdit.

Please note: Qt for Maemo5 will already use it in 4.6, while the other
platforms will be enabled in 4.7 (otherwise be would break BIC there)

This commit adds a so-called placeholder text for line edits. If the widget
doesn't have focus and the text() is empty, this placeholder will be shown.

(*) also known as hint, click-message or descriptive text

Reviewed-by: jasplin

3 files changed, 56 insertions, 0 deletions

diff --git a/src/gui/widgets/qlineedit.cpp b/src/gui/widgets/qlineedit.cpp
index 785b2bd..650b0ab 100644
--- a/src/gui/widgets/qlineedit.cpp
+++ b/src/gui/widgets/qlineedit.cpp
@@ -383,6 +383,38 @@ void QLineEdit::setText(const QString& text)
     d->control->setText(text);
 }
 
+// ### Qt 4.7: remove this #if guard
+#if (QT_VERSION >= 0x407000) || defined(Q_WS_MAEMO_5)
+/*!
+    \since 4.7
+
+    \property QLineEdit::placeholderText
+    \brief the line edit's placeholder text
+
+    Setting this property makes the line edit display a grayed-out
+    placeholder text as long as the text() is empty and the widget doesn't
+    have focus.
+
+    By default, this property contains an empty string.
+
+    \sa text()
+*/
+QString QLineEdit::placeholderText() const
+{
+    Q_D(const QLineEdit);
+    return d->placeholderText;
+}
+
+void QLineEdit::setPlaceholderText(const QString& placeholderText)
+{
+    Q_D(QLineEdit);
+    if (d->placeholderText != placeholderText) {
+        d->placeholderText = placeholderText;
+        if (!hasFocus())
+            update();
+    }
+}
+#endif
 
 /*!
     \property QLineEdit::displayText
@@ -1829,6 +1861,18 @@ void QLineEdit::paintEvent(QPaintEvent *)
     }
     QRect lineRect(r.x() + d->horizontalMargin, d->vscroll, r.width() - 2*d->horizontalMargin, fm.height());
 
+    if (d->control->text().isEmpty()) {
+        if (!hasFocus() && !d->placeholderText.isEmpty()) {
+            QColor col = pal.text().color();
+            col.setAlpha(128);
+            QPen oldpen = p.pen();
+            p.setPen(col);
+            p.drawText(lineRect, va, d->placeholderText);
+            p.setPen(oldpen);
+            return;
+        }
+    }
+
     int cix = qRound(d->control->cursorToX());
 
     // horizontal scrolling. d->hscroll is the left indent from the beginning
diff --git a/src/gui/widgets/qlineedit.h b/src/gui/widgets/qlineedit.h
index ac918c7..594e488 100644
--- a/src/gui/widgets/qlineedit.h
+++ b/src/gui/widgets/qlineedit.h
@@ -83,6 +83,10 @@ class Q_GUI_EXPORT QLineEdit : public QWidget
     Q_PROPERTY(bool undoAvailable READ isUndoAvailable)
     Q_PROPERTY(bool redoAvailable READ isRedoAvailable)
     Q_PROPERTY(bool acceptableInput READ hasAcceptableInput)
+// ### Qt 4.7: remove this #if guard
+#if (QT_VERSION >= 0x407000) || defined(Q_WS_MAEMO_5)
+    Q_PROPERTY(QString placeholderText READ placeholderText WRITE setPlaceholderText)
+#endif
 
 public:
     explicit QLineEdit(QWidget* parent=0);
@@ -98,6 +102,12 @@ public:
 
     QString displayText() const;
 
+// ### Qt 4.7: remove this #if guard
+#if (QT_VERSION >= 0x407000) || defined(Q_WS_MAEMO_5)
+    QString placeholderText() const;
+    void setPlaceholderText(const QString &);
+#endif
+
     int maxLength() const;
     void setMaxLength(int);
 
diff --git a/src/gui/widgets/qlineedit_p.h b/src/gui/widgets/qlineedit_p.h
index 244d2be..dc648e8 100644
--- a/src/gui/widgets/qlineedit_p.h
+++ b/src/gui/widgets/qlineedit_p.h
@@ -142,6 +142,8 @@ public:
     int topTextMargin;
     int rightTextMargin;
     int bottomTextMargin;
+
+    QString placeholderText;
 };
 
 #endif // QT_NO_LINEEDIT