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 <volker.hilsheimer@qt.io> Reviewed-by: Paul Wicking <paul.wicking@qt.io>bb10
Edward Welbourne
parent
6b5f848ebd
commit
ca7033935a
|
|
@ -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.
|
||||
|
||||
\sa date, time
|
||||
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, 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.
|
||||
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.
|
||||
|
||||
The default minimumDateTime can be restored with
|
||||
clearMinimumDateTime()
|
||||
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().
|
||||
|
||||
By default, this property contains a date that refers to September 14,
|
||||
1752 and a time of 00:00:00 and 0 milliseconds.
|
||||
|
||||
\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.
|
||||
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.
|
||||
|
||||
By default, this property contains a date that refers to December 31, 9999.
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue