doc/src/declarative/qmldate.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \qmlclass Date
  30     \inqmlmodule QtQuick 2
  31     \brief The Date object provides date functions
  32
  33     The QML Date object extends the JS Date object with
  34     locale aware functions.
  35
  36     Functions that accept a locale format may be either an enumeration
  37     value:
  38     \table
  39     \row \i Locale.LongFormat \i The long version of the string; for example, returning "January" as a month name.
  40     \row \i Locale.ShortFormat \i The short version of the string; for example, returning "Jan" as a month name.
  41     \row \i Locale.NarrowFormat \i A special version for use when space is limited;
  42         for example, returning "J" as a month name. Note that the narrow format might contain
  43         the same text for different months and days or it can even be an empty string if the
  44         locale doesn't support narrow names, so you should avoid using it for date formatting.
  45         Also, for the system locale this format is the same as ShortFormat.
  46     \endtable
  47
  48     or a string specifying the format  These expressions may be used for format dates:
  49     \table
  50     \header \i Expression \i Output
  51     \row \i d \i the day as number without a leading zero (1 to 31)
  52     \row \i dd \i the day as number with a leading zero (01 to 31)
  53     \row \i ddd
  54          \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
  55     \row \i dddd
  56          \i the long localized day name (e.g. 'Monday' to 'Sunday').
  57     \row \i M \i the month as number without a leading zero (1 to 12)
  58     \row \i MM \i the month as number with a leading zero (01 to 12)
  59     \row \i MMM
  60          \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
  61     \row \i MMMM
  62          \i the long localized month name (e.g. 'January' to 'December').
  63     \row \i yy \i the year as two digit number (00 to 99)
  64     \row \i yyyy \i the year as four digit number. If the year is negative,
  65             a minus sign is prepended in addition.
  66     \endtable
  67
  68     All other input characters will be ignored. Any sequence of characters that
  69     are enclosed in singlequotes will be treated as text and not be used as an
  70     expression. Two consecutive singlequotes ("''") are replaced by a singlequote
  71     in the output.
  72
  73     Example format strings (assuming that the Date is the 20 July
  74     1969):
  75
  76     \table
  77     \header \o Format            \o Result
  78     \row    \o dd.MM.yyyy        \o 20.07.1969
  79     \row    \o ddd MMMM d yy     \o Sun July 20 69
  80     \row    \o 'The day is' dddd \o The day is Sunday
  81     \endtable
  82
  83     These expressions may be used for formatting time:
  84
  85     \table
  86     \header \i Expression \i Output
  87     \row \i h
  88          \i the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
  89     \row \i hh
  90          \i the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
  91     \row \i H
  92          \i the hour without a leading zero (0 to 23, even with AM/PM display)
  93     \row \i HH
  94          \i the hour with a leading zero (00 to 23, even with AM/PM display)
  95     \row \i m \i the minute without a leading zero (0 to 59)
  96     \row \i mm \i the minute with a leading zero (00 to 59)
  97     \row \i s \i the second without a leading zero (0 to 59)
  98     \row \i ss \i the second with a leading zero (00 to 59)
  99     \row \i z \i the milliseconds without leading zeroes (0 to 999)
 100     \row \i zzz \i the milliseconds with leading zeroes (000 to 999)
 101     \row \i AP or A
 102          \i use AM/PM display. \e AP will be replaced by either "AM" or "PM".
 103     \row \i ap or a
 104          \i use am/pm display. \e ap will be replaced by either "am" or "pm".
 105     \row \i t \i the timezone (for example "CEST")
 106     \endtable
 107
 108     All other input characters will be ignored. Any sequence of characters that
 109     are enclosed in singlequotes will be treated as text and not be used as an
 110     expression. Two consecutive singlequotes ("''") are replaced by a singlequote
 111     in the output.
 112
 113     Example format strings (assuming that the QTime is 14:13:09.042)
 114
 115     \table
 116     \header \i Format \i Result
 117     \row \i hh:mm:ss.zzz \i 14:13:09.042
 118     \row \i h:m:s ap     \i 2:13:9 pm
 119     \row \i H:m:s a      \i 14:13:9 pm
 120     \endtable
 121
 122     If the date is invalid, an empty string will be returned.
 123
 124     \sa {QtQuick2::Locale}{Locale}
 125 */
 126
 127 /*!
 128     \qmlmethod string Date::toLocaleString(locale,format)
 129
 130     Converts the Date to a string containing the date and time
 131     suitable for the specified \a locale
 132     in the specified \a format.
 133
 134     If the format is not specified Locale.LongFormat will be used.
 135
 136     If \a locale is not specified, the default locale will be used.
 137
 138     The following example shows the current date and time formatted
 139     for the German locale:
 140     \code
 141     import QtQuick 2.0
 142
 143     Text {
 144         text: "The date is: " +  Date().toLocaleString(Qt.locale("de_DE"))
 145     }
 146     \endcode
 147 */
 148
 149 /*!
 150     \qmlmethod string Date::toLocaleDateString(locale,format)
 151
 152     Converts the Date to a string containing the date suitable for the specified \a locale
 153     in the specified \a format.
 154
 155     If the format is not specified Locale.LongFormat will be used.
 156
 157     If \a locale is not specified, the default locale will be used.
 158
 159     The following example shows the current date formatted
 160     for the German locale:
 161     \code
 162     import QtQuick 2.0
 163
 164     Text {
 165         text: "The date is: " +  Date().toLocaleDateString(Qt.locale("de_DE"))
 166     }
 167     \endcode
 168 */
 169
 170 /*!
 171     \qmlmethod string Date::toLocaleTimeString(locale,format)
 172
 173     Converts the Date to a string containing the time suitable for the specified \a locale
 174     in the specified \a format.
 175
 176     If the format is not specified Locale.LongFormat will be used.
 177
 178     If \a locale is not specified, the default locale will be used.
 179
 180     The following example shows the current time formatted
 181     for the German locale:
 182     \code
 183     import QtQuick 2.0
 184
 185     Text {
 186         text: "The date is: " +  Date().toLocaleTimeString(Qt.locale("de_DE"))
 187     }
 188     \endcode
 189 */
 190