Document how keyboard tracking can prevent use of a date/time editor

This follows up on commit 580e9eedf783ccbdcb67baa3d1a9dcdd53922f86; if
the allowed range is narrower than some time interval whose end it
straddles, users can only access the later part of the range if
keyboard tracking is disabled.

Pick-to: 5.15
Task-number: QTBUG-65
Change-Id: Ie8882bd65bda603133abaa82ad83eb1cdd91f175
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 52 insertions, 9 deletions

diff --git a/src/widgets/widgets/qdatetimeedit.cpp b/src/widgets/widgets/qdatetimeedit.cpp
index d825676035..2e8033dbf1 100644
--- a/src/widgets/widgets/qdatetimeedit.cpp
+++ b/src/widgets/widgets/qdatetimeedit.cpp
@@ -104,6 +104,23 @@ QT_BEGIN_NAMESPACE
   calendar pop-up by calling the setCalendarWidget() function. The existing
   calendar widget can be retrieved with calendarWidget().
 
+  \section1 Keyboard Tracking
+
+  When \l{QAbstractSpinBox::keyboardTracking}{keyboard tracking} is enabled
+  (the default), every keystroke of editing a field triggers signals for value
+  changes.
+
+  When the allowed \l{QDateTimeEdit::setDateTimeRange}{range} is narrower than
+  some time interval whose end it straddles, keyboard tracking prevents the
+  user editing the date or time to access the later part of the interval. For
+  example, for a range from 29.04.2020 to 02.05.2020 and an initial date of
+  30.04.2020, the user can change neither the month (May 30th is outside the
+  range) nor the day (April 2nd is outside the range).
+
+  When keyboard tracking is disabled, changes are only signalled when focus
+  leaves the text field after edits have modified the content. This allows the
+  user to edit via an invalid date-time to reach a valid one.
+
   \sa QDateEdit, QTimeEdit, QDate, QTime
 */
 
@@ -128,6 +145,8 @@ QT_BEGIN_NAMESPACE
 
   This signal is emitted whenever the date or time is changed. The
   new date and time is passed in \a datetime.
+
+  \sa {Keyboard Tracking}
 */
 
 /*!
@@ -135,6 +154,8 @@ QT_BEGIN_NAMESPACE
 
   This signal is emitted whenever the time is changed. The new time
   is passed in \a time.
+
+  \sa {Keyboard Tracking}
 */
 
 /*!
@@ -142,6 +163,8 @@ QT_BEGIN_NAMESPACE
 
   This signal is emitted whenever the date is changed. The new date
   is passed in \a date.
+
+  \sa {Keyboard Tracking}
 */
 
 
@@ -352,7 +375,8 @@ void QDateTimeEdit::setCalendar(QCalendar calendar)
   property's default is the start of September 14, 1752 CE. This default can be
   restored with clearMinimumDateTime().
 
-  \sa maximumDateTime, minimumTime, minimumDate, setDateTimeRange(), QDateTime::isValid()
+  \sa maximumDateTime, minimumTime, minimumDate, setDateTimeRange(),
+      QDateTime::isValid(), {Keyboard Tracking}
 */
 
 QDateTime QDateTimeEdit::minimumDateTime() const
@@ -393,7 +417,8 @@ void QDateTimeEdit::setMinimumDateTime(const QDateTime &dt)
   default for this property. This default can be restored with
   clearMaximumDateTime().
 
-  \sa minimumDateTime, maximumTime, maximumDate(), setDateTimeRange(), QDateTime::isValid()
+  \sa minimumDateTime, maximumTime, maximumDate(), setDateTimeRange(),
+      QDateTime::isValid(), {Keyboard Tracking}
 */
 
 QDateTime QDateTimeEdit::maximumDateTime() const
@@ -433,7 +458,12 @@ void QDateTimeEdit::setMaximumDateTime(const QDateTime &dt)
   If either \a min or \a max is invalid, this function does nothing. If \a max
   is less than \a min, \a min is used also as \a max.
 
-  \sa minimumDateTime, maximumDateTime, setDateRange(), setTimeRange(), QDateTime::isValid()
+  If the range is narrower then a time interval whose end it spans, for example
+  a week that spans the end of a month, users can only edit the date-time to one
+  in the later part of the range if keyboard-tracking is disabled.
+
+  \sa minimumDateTime, maximumDateTime, setDateRange(), setTimeRange(),
+      QDateTime::isValid(), {Keyboard Tracking}
 */
 
 void QDateTimeEdit::setDateTimeRange(const QDateTime &min, const QDateTime &max)
@@ -463,7 +493,8 @@ void QDateTimeEdit::setDateTimeRange(const QDateTime &min, const QDateTime &max)
   default for this property is September 14, 1752 CE. This default can be
   restored with clearMinimumDateTime().
 
-  \sa maximumDate, minimumTime, minimumDateTime, setDateRange(), QDate::isValid()
+  \sa maximumDate, minimumTime, minimumDateTime, setDateRange(),
+      QDate::isValid(), {Keyboard Tracking}
 */
 
 QDate QDateTimeEdit::minimumDate() const
@@ -503,7 +534,8 @@ void QDateTimeEdit::clearMinimumDate()
   default for this property. This default can be restored with
   clearMaximumDateTime().
 
-  \sa minimumDate, maximumTime, maximumDateTime, setDateRange(), QDate::isValid()
+  \sa minimumDate, maximumTime, maximumDateTime, setDateRange(),
+      QDate::isValid(), {Keyboard Tracking}
 */
 
 QDate QDateTimeEdit::maximumDate() const
@@ -540,7 +572,8 @@ void QDateTimeEdit::clearMaximumDate()
   contains a time of 00:00:00 and 0 milliseconds. This default can be restored
   with clearMinimumTime().
 
-  \sa maximumTime, minimumDate, minimumDateTime, setTimeRange(), QTime::isValid()
+  \sa maximumTime, minimumDate, minimumDateTime, setTimeRange(),
+      QTime::isValid(), {Keyboard Tracking}
 */
 
 QTime QDateTimeEdit::minimumTime() const
@@ -579,7 +612,8 @@ void QDateTimeEdit::clearMinimumTime()
   contains a time of 23:59:59 and 999 milliseconds. This default can be restored
   with clearMaximumTime().
 
-  \sa minimumTime, maximumDate, maximumDateTime, setTimeRange(), QTime::isValid()
+  \sa minimumTime, maximumDate, maximumDateTime, setTimeRange(),
+      QTime::isValid(), {Keyboard Tracking}
 */
 QTime QDateTimeEdit::maximumTime() const
 {
@@ -620,7 +654,11 @@ void QDateTimeEdit::clearMaximumTime()
   minimumTime property, the \l maximumTime property is set to the \l minimumTime
   property. Otherwise, this preserves the \l maximumTime property.
 
-  \sa minimumDate, maximumDate, setDateTimeRange(), QDate::isValid()
+  If the range is narrower then a time interval whose end it spans, for example
+  a week that spans the end of a month, users can only edit the date to one in
+  the later part of the range if keyboard-tracking is disabled.
+
+  \sa minimumDate, maximumDate, setDateTimeRange(), QDate::isValid(), {Keyboard Tracking}
 */
 
 void QDateTimeEdit::setDateRange(QDate min, QDate max)
@@ -654,7 +692,12 @@ void QDateTimeEdit::setDateRange(QDate min, QDate max)
   function preserves the \l minimumDate and \l maximumDate properties. If those
   properties coincide and \a max is less than \a min, \a min is used as \a max.
 
-  \sa minimumTime, maximumTime, setDateTimeRange(), QTime::isValid()
+  If the range is narrower then a time interval whose end it spans, for example
+  the interval from ten to an hour to ten past the same hour, users can only
+  edit the time to one in the later part of the range if keyboard-tracking is
+  disabled.
+
+  \sa minimumTime, maximumTime, setDateTimeRange(), QTime::isValid(), {Keyboard Tracking}
 */
 
 void QDateTimeEdit::setTimeRange(QTime min, QTime max)