diff options
| author | Edward Welbourne <edward.welbourne@qt.io> | 2018-11-20 16:59:41 +0100 |
|---|---|---|
| committer | Edward Welbourne <edward.welbourne@qt.io> | 2018-11-23 15:57:29 +0000 |
| commit | 900d2f611475df6e43972eac5fc3c9b4b06b1c0e (patch) | |
| tree | 2354f66c52c74d415e37b982386489cd53ea01a4 /src | |
| parent | 52e4e125b6d71baeb843da740cecf319fee99511 (diff) | |
Improve documentation of QML's handling of dates and times
Encourage use of QDateTime in preference to QDate.
Explain the problems of converting plain dates to date-times.
Include times in the examples.
Change-Id: I12731a9f80a833c41385f787336d1ba60a6fa4d3
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>
Diffstat (limited to 'src')
| -rw-r--r-- | src/qml/doc/src/cppintegration/data.qdoc | 2 | ||||
| -rw-r--r-- | src/qml/doc/src/qmltypereference.qdoc | 19 |
2 files changed, 17 insertions, 4 deletions
diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc index 6159ffe20b..8ebbd28737 100644 --- a/src/qml/doc/src/cppintegration/data.qdoc +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -91,7 +91,7 @@ when passed from C++ to QML and vice-versa: \li QFont \li \l font \row - \li QDate + \li QDateTime \li \l date \row \li QPoint, QPointF diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc index 79bfdc7042..ae36ebbcc9 100644 --- a/src/qml/doc/src/qmltypereference.qdoc +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -91,10 +91,17 @@ provided: The \c date type refers to a date value, including the time of the day. -To create a \c date value, specify it as a "YYYY-MM-DD" string: +To create a \c date value, specify it as a "YYYY-MM-DDThh:mm:ss.zzzZ" string. +(The T is literal, YYYY is a full year number, MM and DD are month and day +numbers, hh, mm and ss are hours, minutes and seconds, with .zzz as +milliseconds and Z as time-zone offset. The T and following time are optional. +If they are omitted, the date is handled as the start of UTC's day, which +falls on other dates in some time-zones. When T is included, the :ss.zzz or +just .zzz part can be omitted. With or without those, the zone offset can be +omitted, in which case local time is used.) For example: \qml -MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } +MyDatePicker { minDate: "2000-01-01 0:0"; maxDate: "2020-12-31 23:59" } \endqml To read a date value returned from a C++ extension class, use @@ -102,7 +109,13 @@ To read a date value returned from a C++ extension class, use When integrating with C++, note that any QDate or QDateTime value \l{qtqml-cppintegration-data.html}{passed into QML from C++} is automatically -converted into a \c date value, and vice-versa. +converted into a \c date value, and vice-versa. Note, however, that +converting a QDate will result in UTC's start of the day, which falls on +a different date in some other time-zones. It is usually more robust +to convert the QDate via a QDateTime explicitly, specifying local-time +or a relevant time-zone and selecting a time of day (such as noon) +that reliably exists (daylight-savings transitions skip an hour, near +one end or the other of a day). This basic type is provided by the QML language. It can be implicitly converted to a \l{QtQml::Date}{Date} object. |