From 97feace2aaaf08075c17ea175a5ed0c12aa40a0d Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Tue, 17 Sep 2013 11:38:40 +0200 Subject: Improve QML Date object documentation. Carrying on from https://codereview.qt-project.org/#change,61255, I've added documentation for the from*String() functions, as they weren't actually documented. I've also formatted some arguments and linked to Locale documentation where the format enums are mentioned. Note that, because of QTBUG-32505, I can't link to the format enum directly, so I just link to the Locale page itself. The import QtQuick 2.0 should also be removed from the documentation when that bug is fixed. Task-number: QTBUG-32492 Change-Id: I19c6c8450746ef2a68bc55fd3ef7db776f4acc35 Reviewed-by: Jerome Pasion --- src/qml/doc/src/javascript/date.qdoc | 104 ++++++++++++++++++++++++++++++++--- 1 file changed, 97 insertions(+), 7 deletions(-) diff --git a/src/qml/doc/src/javascript/date.qdoc b/src/qml/doc/src/javascript/date.qdoc index d4eeede8eb..89dc464adb 100644 --- a/src/qml/doc/src/javascript/date.qdoc +++ b/src/qml/doc/src/javascript/date.qdoc @@ -136,13 +136,14 @@ */ /*! - \qmlmethod string Date::toLocaleString(locale,format) + \qmlmethod string Date::toLocaleString(locale, format) Converts the Date to a string containing the date and time suitable for the specified \a locale in the specified \a format. - If the format is not specified Locale.LongFormat will be used. + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. If \a locale is not specified, the default locale will be used. @@ -158,12 +159,13 @@ */ /*! - \qmlmethod string Date::toLocaleDateString(locale,format) + \qmlmethod string Date::toLocaleDateString(locale, format) Converts the Date to a string containing the date suitable for the specified \a locale in the specified \a format. - If the format is not specified Locale.LongFormat will be used. + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. If \a locale is not specified, the default locale will be used. @@ -179,12 +181,13 @@ */ /*! - \qmlmethod string Date::toLocaleTimeString(locale,format) + \qmlmethod string Date::toLocaleTimeString(locale, format) Converts the Date to a string containing the time suitable for the specified \a locale in the specified \a format. - If the format is not specified Locale.LongFormat will be used. + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. If \a locale is not specified, the default locale will be used. @@ -199,11 +202,98 @@ \endcode */ +/*! + \qmlmethod string Date::fromLocaleString(locale, dateTimeString, format) + + Converts the datetime string \a dateTimeString to a \l {QtQml2::Date}{Date} + object using \a locale and \a format. + + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows a datetime being parsed from a datetime string + in a certain format using the default locale: + \code + import QtQml 2.0 + + QtObject { + property var locale: Qt.locale() + property string dateTimeString: "Tue 2013-09-17 10:56:06" + + Component.onCompleted: { + print(Date.fromLocaleString(locale, dateTimeString, "ddd yyyy-MM-dd hh:mm:ss")); + } + } + \endcode +*/ + +/*! + \qmlmethod string Date::fromLocaleDateString(locale, dateString, format) + + Converts the date string \a dateString to a \l {QtQml2::Date}{Date} object + using \a locale and \a format. + + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows the current date first being formatted as a date + string using the default locale and format, then parsed back again in the + same manner: + \code + import QtQml 2.0 + + QtObject { + property var locale: Qt.locale() + property date currentDate: new Date() + property string dateString + + Component.onCompleted: { + dateString = currentDate.toLocaleDateString(); + print(Date.fromLocaleDateString(dateString)); + } + } + \endcode +*/ + +/*! + \qmlmethod string Date::fromLocaleTimeString(locale, timeString, format) + + Converts the time string \a timeString to a \l {QtQml2::Date}{Date} object + using \a locale and \a format. + + If \a format is not specified, \l {QtQml2::Locale}{Locale.LongFormat} will + be used. + + If \a locale is not specified, the default locale will be used. + + The following example shows the current time first being formatted as a time + string using the default locale and a short format, then parsed back again + in the same manner: + \code + import QtQuick 2.0 + + QtObject { + property var locale: Qt.locale() + property date currentTime: new Date() + property string timeString + + Component.onCompleted: { + timeString = currentTime.toLocaleTimeString(locale, Locale.ShortFormat); + print(Date.fromLocaleTimeString(locale, timeString, Locale.ShortFormat)); + } + } + \endcode +*/ + /*! \qmlmethod string Date::timeZoneUpdated() Informs the JS engine that the system's timezone has been changed, which is necessary - for the correct manipulation of date/time data. + for the correct manipulation of datetime data. JS stores Date objects in UTC time; all access to and from Date components in local time involves the application of the current offset from UTC. If the current offset -- cgit v1.2.1