From ca7033935a26e2a11c7d872a6673e828eddf49ca Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Wed, 4 Dec 2019 15:22:26 +0100 Subject: Tell the truth about QDateTimeEdit's range-of-values properties There were factual errors. Important details were omitted. The \sa blocks were haphazard and cluttered. Change-Id: I76ceb00830c36699c48529b64808844faf09391e Reviewed-by: Volker Hilsheimer Reviewed-by: Paul Wicking --- src/widgets/widgets/qdatetimeedit.cpp | 200 +++++++++++++++++++--------------- 1 file changed, 115 insertions(+), 85 deletions(-) (limited to 'src/widgets/widgets/qdatetimeedit.cpp') diff --git a/src/widgets/widgets/qdatetimeedit.cpp b/src/widgets/widgets/qdatetimeedit.cpp index e26993fb23..9189319364 100644 --- a/src/widgets/widgets/qdatetimeedit.cpp +++ b/src/widgets/widgets/qdatetimeedit.cpp @@ -90,12 +90,10 @@ QT_BEGIN_NAMESPACE today's date, and restricted the valid date range to today plus or minus 365 days. We've set the order to month, day, year. - The minimum value for QDateTimeEdit is 14 September 1752. You can - change this by calling setMinimumDate(), taking into account that - the minimum value for QDate is 2 January 4713BC. - - Other useful functions are setMaximumDate(), setMinimumTime() - and setMaximumTime(). + The range of valid values for a QDateTimeEdit is controlled by the properties + \l minimumDateTime, \l maximumDateTime, and their respective date and time + components. By default, any date-time from the start of 100 CE to the end of + 9999 CE is valid. \section1 Using a Pop-up Calendar Widget @@ -223,10 +221,16 @@ QDateTimeEdit::~QDateTimeEdit() When setting this property the timespec of the QDateTimeEdit remains the same and the timespec of the new QDateTime is ignored. - By default, this property contains a date that refers to January 1, - 2000 and a time of 00:00:00 and 0 milliseconds. + By default, this property is set to the start of 2000 CE. It can only be set + to a valid QDateTime value. If any operation causes this property to have an + invalid date-time as value, it is reset to the value of the \l minimumDateTime + property. + + If the QDateTimeEdit has no date fields, setting this property sets the + widget's date-range to start and end on the date of the new value of this + property. - \sa date, time + \sa date, time, minimumDateTime, maximumDateTime */ QDateTime QDateTimeEdit::dateTime() const @@ -329,25 +333,23 @@ void QDateTimeEdit::setCalendar(QCalendar calendar) } /*! - \property QDateTimeEdit::minimumDateTime \since 4.4 + \property QDateTimeEdit::minimumDateTime \brief the minimum datetime of the date time edit - When setting this property the \l maximumDateTime() is adjusted if - necessary to ensure that the range remains valid. If the datetime is - not a valid QDateTime object, this function does nothing. - - The default minimumDateTime can be restored with - clearMinimumDateTime() + Changing this property implicitly updates the \l minimumDate and \l + minimumTime properties to the date and time parts of this property, + respectively. When setting this property, the \l maximumDateTime is adjusted, + if necessary, to ensure that the range remains valid. Otherwise, changing this + property preserves the \l minimumDateTime property. - By default, this property contains a date that refers to September 14, - 1752 and a time of 00:00:00 and 0 milliseconds. + This property can only be set to a valid QDateTime value. The earliest + date-time that setMinimumDateTime() accepts is the start of 100 CE. The + property's default is the start of September 14, 1752 CE. This default can be + restored with clearMinimumDateTime(). - \sa maximumDateTime(), minimumTime(), maximumTime(), minimumDate(), - maximumDate(), setDateTimeRange(), setDateRange(), setTimeRange(), - clearMaximumDateTime(), clearMinimumDate(), - clearMaximumDate(), clearMinimumTime(), clearMaximumTime() + \sa maximumDateTime, minimumTime, minimumDate, setDateTimeRange(), QDateTime::isValid() */ QDateTime QDateTimeEdit::minimumDateTime() const @@ -372,25 +374,23 @@ void QDateTimeEdit::setMinimumDateTime(const QDateTime &dt) } /*! - \property QDateTimeEdit::maximumDateTime \since 4.4 + \property QDateTimeEdit::maximumDateTime \brief the maximum datetime of the date time edit - When setting this property the \l minimumDateTime() is adjusted if - necessary to ensure that the range remains valid. If the datetime is - not a valid QDateTime object, this function does nothing. + Changing this property implicitly updates the \l maximumDate and \l + maximumTime properties to the date and time parts of this property, + respectively. When setting this property, the \l minimumDateTime is adjusted, + if necessary, to ensure that the range remains valid. Otherwise, changing this + property preserves the \l minimumDateTime property. - The default maximumDateTime can be restored with + This property can only be set to a valid QDateTime value. The latest + date-time that setMaximumDateTime() accepts is the end of 9999 CE. This is the + default for this property. This default can be restored with clearMaximumDateTime(). - By default, this property contains a date that refers to 31 December, - 9999 and a time of 23:59:59 and 999 milliseconds. - - \sa minimumDateTime(), minimumTime(), maximumTime(), minimumDate(), - maximumDate(), setDateTimeRange(), setDateRange(), setTimeRange(), - clearMinimumDateTime(), clearMinimumDate(), - clearMaximumDate(), clearMinimumTime(), clearMaximumTime() + \sa minimumDateTime, maximumTime, maximumDate(), setDateTimeRange(), QDateTime::isValid() */ QDateTime QDateTimeEdit::maximumDateTime() const @@ -414,11 +414,12 @@ void QDateTimeEdit::setMaximumDateTime(const QDateTime &dt) } } - /*! - Convenience function to set minimum and maximum date time with one - function call. \since 4.4 + \brief Set the range of allowed date-times for the date time edit. + + This convenience function sets the \l minimumDateTime and \l maximumDateTime + properties. \snippet code/src_gui_widgets_qdatetimeedit.cpp 1 @@ -426,21 +427,18 @@ void QDateTimeEdit::setMaximumDateTime(const QDateTime &dt) \snippet code/src_gui_widgets_qdatetimeedit.cpp 2 - If either \a min or \a max are not valid, this function does - nothing. + 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 setMinimumDate(), maximumDate(), setMaximumDate(), - clearMinimumDate(), setMinimumTime(), maximumTime(), - setMaximumTime(), clearMinimumTime(), QDateTime::isValid() + \sa minimumDateTime, maximumDateTime, setDateRange(), setTimeRange(), QDateTime::isValid() */ void QDateTimeEdit::setDateTimeRange(const QDateTime &min, const QDateTime &max) { Q_D(QDateTimeEdit); + // FIXME: does none of the range checks applied to setMin/setMax methods ! const QDateTime minimum = min.toTimeSpec(d->spec); - QDateTime maximum = max.toTimeSpec(d->spec); - if (min > max) - maximum = minimum; + const QDateTime maximum = (min > max ? minimum : max.toTimeSpec(d->spec)); d->setRange(minimum, maximum); } @@ -449,15 +447,20 @@ void QDateTimeEdit::setDateTimeRange(const QDateTime &min, const QDateTime &max) \brief the minimum date of the date time edit - When setting this property the \l maximumDate is adjusted if - necessary, to ensure that the range remains valid. If the date is - not a valid QDate object, this function does nothing. + Changing this property updates the date of the \l minimumDateTime property + while preserving the \l minimumTime property. When setting this property, + the \l maximumDate is adjusted, if necessary, to ensure that the range remains + valid. When this happens, the \l maximumTime property is also adjusted if it + is less than the \l minimumTime property. Otherwise, changes to this property + preserve the \l maximumDateTime property. - By default, this property contains a date that refers to September 14, 1752. - The minimum date must be at least the first day in year 100, otherwise - setMinimumDate() has no effect. + This property can only be set to a valid QDate object describing a date on + which the current \l minimumTime property makes a valid QDateTime object. The + earliest date that setMinimumDate() accepts is the start of 100 CE. The + default for this property is September 14, 1752 CE. This default can be + restored with clearMinimumDateTime(). - \sa minimumTime(), maximumTime(), setDateRange() + \sa maximumDate, minimumTime, minimumDateTime, setDateRange(), QDate::isValid() */ QDate QDateTimeEdit::minimumDate() const @@ -484,13 +487,20 @@ void QDateTimeEdit::clearMinimumDate() \brief the maximum date of the date time edit - When setting this property the \l minimumDate is adjusted if - necessary to ensure that the range remains valid. If the date is - not a valid QDate object, this function does nothing. - - By default, this property contains a date that refers to December 31, 9999. + Changing this property updates the date of the \l maximumDateTime property + while preserving the \l maximumTime property. When setting this property, the + \l minimumDate is adjusted, if necessary, to ensure that the range remains + valid. When this happens, the \l minimumTime property is also adjusted if it + is greater than the \l maximumTime property. Otherwise, changes to this + property preserve the \l minimumDateTime property. + + This property can only be set to a valid QDate object describing a date on + which the current \l maximumTime property makes a valid QDateTime object. The + latest date that setMaximumDate() accepts is the end of 9999 CE. This is the + default for this property. This default can be restored with + clearMaximumDateTime(). - \sa minimumDate, minimumTime, maximumTime, setDateRange() + \sa minimumDate, maximumTime, maximumDateTime, setDateRange(), QDate::isValid() */ QDate QDateTimeEdit::maximumDate() const @@ -502,9 +512,8 @@ QDate QDateTimeEdit::maximumDate() const void QDateTimeEdit::setMaximumDate(const QDate &max) { Q_D(QDateTimeEdit); - if (max.isValid()) { + if (max.isValid()) setMaximumDateTime(QDateTime(max, d->maximum.toTime(), d->spec)); - } } void QDateTimeEdit::clearMaximumDate() @@ -517,13 +526,18 @@ void QDateTimeEdit::clearMaximumDate() \brief the minimum time of the date time edit - When setting this property the \l maximumTime is adjusted if - necessary, to ensure that the range remains valid. If the time is - not a valid QTime object, this function does nothing. + Changing this property updates the time of the \l minimumDateTime property + while preserving the \l minimumDate and \l maximumDate properties. If those + date properties coincide, when setting this property, the \l maximumTime + property is adjusted, if necessary, to ensure that the range remains + valid. Otherwise, changing this property preserves the \l maximumDateTime + property. - By default, this property contains a time of 00:00:00 and 0 milliseconds. + This property can be set to any valid QTime value. By default, this property + contains a time of 00:00:00 and 0 milliseconds. This default can be restored + with clearMinimumTime(). - \sa maximumTime, minimumDate, maximumDate, setTimeRange() + \sa maximumTime, minimumDate, minimumDateTime, setTimeRange(), QTime::isValid() */ QTime QDateTimeEdit::minimumTime() const @@ -551,13 +565,18 @@ void QDateTimeEdit::clearMinimumTime() \brief the maximum time of the date time edit - When setting this property, the \l minimumTime is adjusted if - necessary to ensure that the range remains valid. If the time is - not a valid QTime object, this function does nothing. + Changing this property updates the time of the \l maximumDateTime property + while preserving the \l minimumDate and \l maximumDate properties. If those + date properties coincide, when setting this property, the \l minimumTime + property is adjusted, if necessary, to ensure that the range remains + valid. Otherwise, changing this property preserves the \l minimumDateTime + property. - By default, this property contains a time of 23:59:59 and 999 milliseconds. + This property can be set to any valid QTime value. By default, this property + contains a time of 23:59:59 and 999 milliseconds. This default can be restored + with clearMaximumTime(). - \sa minimumTime, minimumDate, maximumDate, setTimeRange() + \sa minimumTime, maximumDate, maximumDateTime, setTimeRange(), QTime::isValid() */ QTime QDateTimeEdit::maximumTime() const { @@ -580,8 +599,10 @@ void QDateTimeEdit::clearMaximumTime() } /*! - Convenience function to set minimum and maximum date with one - function call. + \brief Set the range of allowed dates for the date time edit. + + This convenience function sets the \l minimumDate and \l maximumDate + properties. \snippet code/src_gui_widgets_qdatetimeedit.cpp 3 @@ -589,12 +610,14 @@ void QDateTimeEdit::clearMaximumTime() \snippet code/src_gui_widgets_qdatetimeedit.cpp 4 - If either \a min or \a max are not valid, this function does - nothing. + If either \a min or \a max is invalid, this function does nothing. This + function preserves the \l minimumTime property. If \a max is less than \a min, + the new maximumDateTime property shall be the new minimumDateTime property. If + \a max is equal to \a min and the \l maximumTime property was less then the \l + minimumTime property, the \l maximumTime property is set to the \l minimumTime + property. Otherwise, this preserves the \l maximumTime property. - \sa setMinimumDate(), maximumDate(), setMaximumDate(), - clearMinimumDate(), setMinimumTime(), maximumTime(), - setMaximumTime(), clearMinimumTime(), QDate::isValid() + \sa minimumDate, maximumDate, setDateTimeRange(), QDate::isValid() */ void QDateTimeEdit::setDateRange(const QDate &min, const QDate &max) @@ -607,8 +630,16 @@ void QDateTimeEdit::setDateRange(const QDate &min, const QDate &max) } /*! - Convenience function to set minimum and maximum time with one - function call. + \brief Set the range of allowed times for the date time edit. + + This convenience function sets the \l minimumTime and \l maximumTime + properties. + + Note that these only constrain the date time edit's value on, + respectively, the \l minimumDate and \l maximumDate. When these date + properties do not coincide, times after \a maximumTime are allowed on dates + before \l maximumDate and times before \a minimumTime are allowed on dates + after \l minimumDate. \snippet code/src_gui_widgets_qdatetimeedit.cpp 5 @@ -616,12 +647,11 @@ void QDateTimeEdit::setDateRange(const QDate &min, const QDate &max) \snippet code/src_gui_widgets_qdatetimeedit.cpp 6 - If either \a min or \a max are not valid, this function does - nothing. + If either \a min or \a max is invalid, this function does nothing. This + function preserves the \l minimumDate and \l maximumDate properties. If those + properties coincide and max is \a less than \a min, \a min is used as \a max. - \sa setMinimumDate(), maximumDate(), setMaximumDate(), - clearMinimumDate(), setMinimumTime(), maximumTime(), - setMaximumTime(), clearMinimumTime(), QTime::isValid() + \sa minimumTime, maximumTime, setDateTimeRange(), QTime::isValid() */ void QDateTimeEdit::setTimeRange(const QTime &min, const QTime &max) @@ -865,7 +895,7 @@ QString QDateTimeEdit::sectionText(Section section) const Note that if you specify a two digit year, it will be interpreted to be in the century in which the date time edit was initialized. - The default century is the 21 (2000-2099). + The default century is the 21st (2000-2099). If you specify an invalid format the format will not be set. -- cgit v1.2.3