diff options
author | J-P Nurmi <jpnurmi@theqtcompany.com> | 2015-09-23 20:01:40 +0200 |
---|---|---|
committer | J-P Nurmi <jpnurmi@theqtcompany.com> | 2015-09-25 16:30:47 +0000 |
commit | d703de8752e07cb12e8ce2e2a05d608f2b26425a (patch) | |
tree | 828ef61dd89e13c9af7896e0e63a935ebd68c4ac /src/imports/calendar | |
parent | e085574cd87c0faf99a79fee755a678347fcb540 (diff) |
Initial QtQuick.Calendar docs
The overview is still missing.
Change-Id: I081f1684b64fc8b95f59844b8373293523181266
Reviewed-by: Mitch Curtis <mitch.curtis@theqtcompany.com>
Diffstat (limited to 'src/imports/calendar')
14 files changed, 405 insertions, 0 deletions
diff --git a/src/imports/calendar/calendar.pro b/src/imports/calendar/calendar.pro index e8e29b8f..78fe53d3 100644 --- a/src/imports/calendar/calendar.pro +++ b/src/imports/calendar/calendar.pro @@ -5,6 +5,8 @@ IMPORT_VERSION = 2.0 QT += qml quick QT += core-private gui-private qml-private quick-private quicktemplates-private +QMAKE_DOCS = $$PWD/doc/qtquickcalendar2.qdocconf + DEFINES += QT_NO_CAST_TO_ASCII QT_NO_CAST_FROM_ASCII INCLUDEPATH += $$PWD diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-calendarview-layout.png b/src/imports/calendar/doc/images/qtquickcalendar2-calendarview-layout.png Binary files differnew file mode 100644 index 00000000..c5182644 --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-calendarview-layout.png diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-calendarview.png b/src/imports/calendar/doc/images/qtquickcalendar2-calendarview.png Binary files differnew file mode 100644 index 00000000..79d0ebc0 --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-calendarview.png diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow-layout.png b/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow-layout.png Binary files differnew file mode 100644 index 00000000..fd4dc065 --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow-layout.png diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow.png b/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow.png Binary files differnew file mode 100644 index 00000000..2d650a88 --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-dayofweekrow.png diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn-layout.png b/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn-layout.png Binary files differnew file mode 100644 index 00000000..f11be89d --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn-layout.png diff --git a/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn.png b/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn.png Binary files differnew file mode 100644 index 00000000..07ecc9f4 --- /dev/null +++ b/src/imports/calendar/doc/images/qtquickcalendar2-weeknumbercolumn.png diff --git a/src/imports/calendar/doc/qtquickcalendar2.qdocconf b/src/imports/calendar/doc/qtquickcalendar2.qdocconf new file mode 100644 index 00000000..a3313e86 --- /dev/null +++ b/src/imports/calendar/doc/qtquickcalendar2.qdocconf @@ -0,0 +1,50 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + +project = QtQuickCalendar2 +description = Qt Quick Calendar 2 Reference Documentation +version = $QT_VERSION + +qhp.projects = QtQuickCalendar2 + +qhp.QtQuickCalendar2.file = QtQuickCalendar2.qhp +qhp.QtQuickCalendar2.namespace = org.qt-project.QtQuickCalendar2.$QT_VERSION_TAG +qhp.QtQuickCalendar2.virtualFolder = QtQuickCalendar2 +qhp.QtQuickCalendar2.indexTitle = Qt Quick Calendar 2 +qhp.QtQuickCalendar2.indexRoot = + +qhp.QtQuickCalendar2.filterAttributes = QtQuickCalendar2 $QT_VERSION qtrefdoc +qhp.QtQuickCalendar2.customFilters.Qt.name = QtQuickCalendar2 $QT_VERSION +qhp.QtQuickCalendar2.customFilters.Qt.filterAttributes = QtQuickCalendar2 $QT_VERSION + +qhp.QtQuickCalendar2.subprojects = QtQuickCalendar2qmltypes + +qhp.QtQuickCalendar2.subprojects.QtQuickCalendar2qmltypes.title = Calendar 2 QML Types +qhp.QtQuickCalendar2.subprojects.QtQuickCalendar2qmltypes.indexTitle = Qt Quick Calendar 2 QML Types +qhp.QtQuickCalendar2.subprojects.QtQuickCalendar2qmltypes.selectors = qmlclass +qhp.QtQuickCalendar2.subprojects.QtQuickCalendar2qmltypes.sortPages = true + +depends = qtcore qtgui qtdoc qtqml qtquick qtquicklayouts qtquickcontrols2 + +# Specify the install path under QT_INSTALL_EXAMPLES +# Examples will be installed under quick/calendar - 'calendar' subdirectory +# is given as part of \example commands +exampledirs += ../../../../examples/quick/calendar \ + ../ \ + snippets \ + ../../../../tests/auto/snippets/data +examplesinstallpath = quick/calendar + +headerdirs += ../ +sourcedirs += ../ + +imagedirs += images + +navigation.landingpage = "Qt Quick Calendar 2" +navigation.qmltypespage = "Qt Quick Calendar 2 QML Types" + +tagfile = QtQuickCalendar2.tags + +# Specify a QML module suffix, applied to html filenames, to avoid +# clashes with Qt Quick Controls 1 documentation. +outputsuffixes = QML +outputsuffixes.QML = 2 diff --git a/src/imports/calendar/doc/src/qtquickcalendar2-index.qdoc b/src/imports/calendar/doc/src/qtquickcalendar2-index.qdoc new file mode 100644 index 00000000..a483ac95 --- /dev/null +++ b/src/imports/calendar/doc/src/qtquickcalendar2-index.qdoc @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtquickcalendar2-index.html + \title Qt Quick Calendar 2 + + \brief The Qt Quick Calendar 2 module provides a set of UI controls for Qt + Quick. + + The Qt Quick Calendar 2 module provides a set of types that can be used + to build calendars in Qt Quick. + + \section1 QML Types + + \generatelist {qmltypesbymodule QtQuick.Calendar} + + \section1 Related information + + \list + \li \l{Qt Quick} + \li \l{Qt Quick Layouts} + \li \l{Qt Quick Controls 2} + \li \l{Qt Quick Calendar 2 QML Types}{Qt Quick Calendar 2 QML Types} + \endlist +*/ diff --git a/src/imports/calendar/doc/src/qtquickcalendar2.qdoc b/src/imports/calendar/doc/src/qtquickcalendar2.qdoc new file mode 100644 index 00000000..21bf780b --- /dev/null +++ b/src/imports/calendar/doc/src/qtquickcalendar2.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule QtQuick.Calendar 2.0 + \title Qt Quick Calendar 2 QML Types + \ingroup qmlmodules + \brief Provides QML types for calendars (Qt Quick Calendar 2). + + The \l{Qt Quick Calendar 2} module provides QML types for creating + calendars. These QML types work in conjunction with \l{Qt Quick} and + \l{Qt Quick Controls 2}. + + The QML types can be imported into your application using the + following import statement in your .qml file. + + \code + import QtQuick.Calendar 2.0 + \endcode + + \section1 QML Types +*/ diff --git a/src/imports/calendar/qquickcalendarmodel.cpp b/src/imports/calendar/qquickcalendarmodel.cpp index c1386ed0..39e0c118 100644 --- a/src/imports/calendar/qquickcalendarmodel.cpp +++ b/src/imports/calendar/qquickcalendarmodel.cpp @@ -40,6 +40,29 @@ QT_BEGIN_NAMESPACE +/*! + \qmltype CalendarModel + \inherits QAbstractListModel + \instantiates QQuickCalendarModel + \inqmlmodule QtQuick.Calendar + \brief A calendar model. + + CalendarModel provides a way of creating a range of CalendarView + instances. It is typically used as a model for a ListView that uses + CalendarView as a delegate. + + \snippet calendarmodel/qtquickcalendar2-calendarmodel.qml 1 + + In addition to the \c index property, a list of model data roles + are available in the context of each delegate: + \table + \row \li \b model.month : int \li The number of the month + \row \li \b model.year : int \li The number of the year + \endtable + + \sa CalendarView +*/ + class QQuickCalendarModelPrivate : public QAbstractItemModelPrivate { Q_DECLARE_PUBLIC(QQuickCalendarModel) @@ -92,6 +115,11 @@ QQuickCalendarModel::QQuickCalendarModel(QObject *parent) : { } +/*! + \qmlproperty date QtQuick.Calendar::CalendarModel::from + + This property holds the start date. +*/ QDate QQuickCalendarModel::from() const { Q_D(const QQuickCalendarModel); @@ -109,6 +137,11 @@ void QQuickCalendarModel::setFrom(const QDate &from) } } +/*! + \qmlproperty date QtQuick.Calendar::CalendarModel::to + + This property holds the end date. +*/ QDate QQuickCalendarModel::to() const { Q_D(const QQuickCalendarModel); @@ -126,23 +159,43 @@ void QQuickCalendarModel::setTo(const QDate &to) } } +/*! + \qmlmethod int QtQuick.Calendar::CalendarModel::monthAt(int index) + + Returns the month number at the specified model \a index. +*/ int QQuickCalendarModel::monthAt(int index) const { Q_D(const QQuickCalendarModel); return d->from.addMonths(index).month(); } +/*! + \qmlmethod int QtQuick.Calendar::CalendarModel::yearAt(int index) + + Returns the year number at the specified model \a index. +*/ int QQuickCalendarModel::yearAt(int index) const { Q_D(const QQuickCalendarModel); return d->from.addMonths(index).year(); } +/*! + \qmlmethod int QtQuick.Calendar::CalendarModel::indexOf(Date date) + + Returns the model index of the specified \a date. +*/ int QQuickCalendarModel::indexOf(const QDate &date) const { return indexOf(date.year(), date.month()); } +/*! + \qmlmethod int QtQuick.Calendar::CalendarModel::indexOf(int year, int month) + + Returns the model index of the specified \a year and \a month. +*/ int QQuickCalendarModel::indexOf(int year, int month) const { Q_D(const QQuickCalendarModel); diff --git a/src/imports/calendar/qquickcalendarview.cpp b/src/imports/calendar/qquickcalendarview.cpp index 23ed9dd3..9b90c89f 100644 --- a/src/imports/calendar/qquickcalendarview.cpp +++ b/src/imports/calendar/qquickcalendarview.cpp @@ -43,6 +43,33 @@ QT_BEGIN_NAMESPACE +/*! + \qmltype CalendarView + \inherits Control + \instantiates QQuickCalendarView + \inqmlmodule QtQuick.Calendar + \brief A calendar view. + + CalendarView presents a calendar month in a grid. The contents + are calculated for a given \l month and \l year, using the specified + \l locale. + + \image qtquickcalendar2-calendarview.png + \snippet calendarview/qtquickcalendar2-calendarview.qml 1 + + CalendarView can be used as a standalone control, but it is most often + used in conjunction with DayOfWeekRow and WeekNumberColumn. Regardless + of the use case, positioning of the grid is left to the user. + + \image qtquickcalendar2-calendarview-layout.png + \snippet calendarview/qtquickcalendar2-calendarview-layout.qml 1 + + The visual appearance of CalendarView can be changed by + implementing a \l {delegate}{custom delegate}. + + \sa DayOfWeekRow, WeekNumberColumn, CalendarModel +*/ + class QQuickCalendarViewPrivate : public QQuickControlPrivate { Q_DECLARE_PUBLIC(QQuickCalendarView) @@ -149,6 +176,11 @@ QQuickCalendarView::QQuickCalendarView(QQuickItem *parent) : connect(d->model, &QQuickMonthModel::titleChanged, this, &QQuickCalendarView::titleChanged); } +/*! + \qmlproperty int QtQuick.Calendar::CalendarView::month + + This property holds the number of the month. +*/ int QQuickCalendarView::month() const { Q_D(const QQuickCalendarView); @@ -161,6 +193,11 @@ void QQuickCalendarView::setMonth(int month) d->model->setMonth(month); } +/*! + \qmlproperty int QtQuick.Calendar::CalendarView::year + + This property holds the number of the year. +*/ int QQuickCalendarView::year() const { Q_D(const QQuickCalendarView); @@ -173,6 +210,11 @@ void QQuickCalendarView::setYear(int year) d->model->setYear(year); } +/*! + \qmlproperty Locale QtQuick.Calendar::CalendarView::locale + + This property holds the locale that is used to calculate the contents. +*/ QLocale QQuickCalendarView::locale() const { Q_D(const QQuickCalendarView); @@ -185,6 +227,13 @@ void QQuickCalendarView::setLocale(const QLocale &locale) d->model->setLocale(locale); } +/*! + \internal + \qmlproperty model QtQuick.Calendar::CalendarView::source + + This property holds the source model that is used as a data model + for the internal content column. +*/ QVariant QQuickCalendarView::source() const { Q_D(const QQuickCalendarView); @@ -200,6 +249,15 @@ void QQuickCalendarView::setSource(const QVariant &source) } } +/*! + \qmlproperty string QtQuick.Calendar::CalendarView::title + + This property holds a title for the calendar. + + This property is provided for convenience. CalendarView itself does + not visualize the title. The default value consists of the month name, + formatted using \l locale, and the year number. +*/ QString QQuickCalendarView::title() const { Q_D(const QQuickCalendarView); @@ -217,6 +275,28 @@ void QQuickCalendarView::setTitle(const QString &title) } } +/*! + \qmlproperty Component QtQuick.Calendar::CalendarView::delegate + + This property holds the item delegate that visualizes each day. + + In addition to the \c index property, a list of model data roles + are available in the context of each delegate: + \table + \row \li \b model.date : date \li The date of the cell + \row \li \b model.day : int \li The number of the day + \row \li \b model.today : bool \li Whether the delegate represents today + \row \li \b model.weekNumber : int \li The week number + \row \li \b model.month : int \li The number of the month + \row \li \b model.year : int \li The number of the year + \endtable + + The following snippet presents the default implementation of the item + delegate. It can be used as a starting point for implementing custom + delegates. + + \snippet CalendarView.qml delegate +*/ QQmlComponent *QQuickCalendarView::delegate() const { Q_D(const QQuickCalendarView); diff --git a/src/imports/calendar/qquickdayofweekrow.cpp b/src/imports/calendar/qquickdayofweekrow.cpp index 9ace5bdd..1fceee35 100644 --- a/src/imports/calendar/qquickdayofweekrow.cpp +++ b/src/imports/calendar/qquickdayofweekrow.cpp @@ -41,6 +41,32 @@ QT_BEGIN_NAMESPACE +/*! + \qmltype DayOfWeekRow + \inherits Control + \instantiates QQuickDayOfWeekRow + \inqmlmodule QtQuick.Calendar + \brief A row of names for the days in a week. + + DayOfWeekRow presents day of week names in a row. The names of + the days are ordered and formatted using the specified \l locale. + + \image qtquickcalendar2-dayofweekrow.png + \snippet dayofweekrow/qtquickcalendar2-dayofweekrow.qml 1 + + DayOfWeekRow can be used as a standalone control, but it is most + often used in conjunction with CalendarView. Regardless of the use case, + positioning of the row is left to the user. + + \image qtquickcalendar2-dayofweekrow-layout.png + \snippet dayofweekrow/qtquickcalendar2-dayofweekrow-layout.qml 1 + + The visual appearance of DayOfWeekRow can be changed by + implementing a \l {delegate}{custom delegate}. + + \sa CalendarView, WeekNumberColumn +*/ + class QQuickDayOfWeekRowPrivate : public QQuickControlPrivate { public: @@ -75,6 +101,11 @@ QQuickDayOfWeekRow::QQuickDayOfWeekRow(QQuickItem *parent) : connect(d->model, &QQuickDayOfWeekModel::localeChanged, this, &QQuickDayOfWeekRow::localeChanged); } +/*! + \qmlproperty Locale QtQuick.Calendar::DayOfWeekRow::locale + + This property holds the locale that is used to format names of the days in a week. +*/ QLocale QQuickDayOfWeekRow::locale() const { Q_D(const QQuickDayOfWeekRow); @@ -87,6 +118,13 @@ void QQuickDayOfWeekRow::setLocale(const QLocale &locale) d->model->setLocale(locale); } +/*! + \internal + \qmlproperty model QtQuick.Calendar::DayOfWeekRow::source + + This property holds the source model that is used as a data model + for the internal content row. +*/ QVariant QQuickDayOfWeekRow::source() const { Q_D(const QQuickDayOfWeekRow); @@ -102,6 +140,26 @@ void QQuickDayOfWeekRow::setSource(const QVariant &source) } } +/*! + \qmlproperty Component QtQuick.Calendar::DayOfWeekRow::delegate + + This property holds the item delegate that visualizes each day of the week. + + In addition to the \c index property, a list of model data roles + are available in the context of each delegate: + \table + \row \li \b model.day : int \li The day of week (\l Qt::DayOfWeek) + \row \li \b model.longName : string \li The long version of the day name; for example, "Monday" (\l QLocale::LongFormat) + \row \li \b model.shortName : string \li The short version of the day name; for example, "Mon" (\l QLocale::ShortFormat) + \row \li \b model.narrowName : string \li A special version of the day name for use when space is limited; for example, "M" (\l QLocale::NarrowFormat) + \endtable + + The following snippet presents the default implementation of the item + delegate. It can be used as a starting point for implementing custom + delegates. + + \snippet DayOfWeekRow.qml delegate +*/ QQmlComponent *QQuickDayOfWeekRow::delegate() const { Q_D(const QQuickDayOfWeekRow); diff --git a/src/imports/calendar/qquickweeknumbercolumn.cpp b/src/imports/calendar/qquickweeknumbercolumn.cpp index 12f61bd4..e898acac 100644 --- a/src/imports/calendar/qquickweeknumbercolumn.cpp +++ b/src/imports/calendar/qquickweeknumbercolumn.cpp @@ -41,6 +41,33 @@ QT_BEGIN_NAMESPACE +/*! + \qmltype WeekNumberColumn + \inherits Control + \instantiates QQuickWeekNumberColumn + \inqmlmodule QtQuick.Calendar + \brief A column of week numbers. + + WeekNumberColumn presents week numbers in a column. The week numbers + are calculated for a given \l month and \l year, using the specified + \l locale. + + \image qtquickcalendar2-weeknumbercolumn.png + \snippet weeknumbercolumn/qtquickcalendar2-weeknumbercolumn.qml 1 + + WeekNumberColumn can be used as a standalone control, but it is most + often used in conjunction with CalendarView. Regardless of the use case, + positioning of the column is left to the user. + + \image qtquickcalendar2-weeknumbercolumn-layout.png + \snippet weeknumbercolumn/qtquickcalendar2-weeknumbercolumn-layout.qml 1 + + The visual appearance of WeekNumberColumn can be changed by + implementing a \l {delegate}{custom delegate}. + + \sa CalendarView, DayOfWeekRow +*/ + class QQuickWeekNumberColumnPrivate : public QQuickControlPrivate { public: @@ -77,6 +104,11 @@ QQuickWeekNumberColumn::QQuickWeekNumberColumn(QQuickItem *parent) : connect(d->model, &QQuickWeekNumberModel::localeChanged, this, &QQuickWeekNumberColumn::localeChanged); } +/*! + \qmlproperty int QtQuick.Calendar::WeekNumberColumn::month + + This property holds the number of the month that the week numbers are calculated for. +*/ int QQuickWeekNumberColumn::month() const { Q_D(const QQuickWeekNumberColumn); @@ -89,6 +121,11 @@ void QQuickWeekNumberColumn::setMonth(int month) d->model->setMonth(month); } +/*! + \qmlproperty int QtQuick.Calendar::WeekNumberColumn::year + + This property holds the number of the year that the week numbers are calculated for. +*/ int QQuickWeekNumberColumn::year() const { Q_D(const QQuickWeekNumberColumn); @@ -101,6 +138,11 @@ void QQuickWeekNumberColumn::setYear(int year) d->model->setYear(year); } +/*! + \qmlproperty Locale QtQuick.Calendar::WeekNumberColumn::locale + + This property holds the locale that is used to calculate the week numbers. +*/ QLocale QQuickWeekNumberColumn::locale() const { Q_D(const QQuickWeekNumberColumn); @@ -113,6 +155,13 @@ void QQuickWeekNumberColumn::setLocale(const QLocale &locale) d->model->setLocale(locale); } +/*! + \internal + \qmlproperty model QtQuick.Calendar::WeekNumberColumn::source + + This property holds the source model that is used as a data model + for the internal content column. +*/ QVariant QQuickWeekNumberColumn::source() const { Q_D(const QQuickWeekNumberColumn); @@ -128,6 +177,23 @@ void QQuickWeekNumberColumn::setSource(const QVariant &source) } } +/*! + \qmlproperty Component QtQuick.Calendar::WeekNumberColumn::delegate + + This property holds the item delegate that visualizes each week number. + + In addition to the \c index property, a list of model data roles + are available in the context of each delegate: + \table + \row \li \b model.weekNumber : int \li The week number + \endtable + + The following snippet presents the default implementation of the item + delegate. It can be used as a starting point for implementing custom + delegates. + + \snippet WeekNumberColumn.qml delegate +*/ QQmlComponent *QQuickWeekNumberColumn::delegate() const { Q_D(const QQuickWeekNumberColumn); |