diff options
Diffstat (limited to 'doc/src/examples/calendarwidget.qdoc')
| -rw-r--r-- | doc/src/examples/calendarwidget.qdoc | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/doc/src/examples/calendarwidget.qdoc b/doc/src/examples/calendarwidget.qdoc new file mode 100644 index 0000000000..f4417c2a3f --- /dev/null +++ b/doc/src/examples/calendarwidget.qdoc @@ -0,0 +1,305 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Calendar Widget Example + \example widgets/calendarwidget + + The Calendar Widget example shows use of \c QCalendarWidget. + + \image calendarwidgetexample.png + + QCalendarWidget displays one calendar month + at a time and lets the user select a date. + The calendar consists of four components: a navigation + bar that lets the user change the month that is + displayed, a grid where each cell represents one day + in the month, and two headers that display weekday names + and week numbers. + + The Calendar Widget example displays a QCalendarWidget and lets the user + configure its appearance and behavior using + \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In + addition, the user can influence the formatting of individual dates + and headers. + + The properties of the QCalendarWidget are summarized in the table + below. + + \table + \header \o Property + \o Description + \row \o \l{QCalendarWidget::}{selectedDate} + \o The currently selected date. + \row \o \l{QCalendarWidget::}{minimumDate} + \o The earliest date that can be selected. + \row \o \l{QCalendarWidget::}{maximumDate} + \o The latest date that can be selected. + \row \o \l{QCalendarWidget::}{firstDayOfWeek} + \o The day that is displayed as the first day of the week + (usually Sunday or Monday). + \row \o \l{QCalendarWidget::}{gridVisible} + \o Whether the grid should be shown. + \row \o \l{QCalendarWidget::}{selectionMode} + \o Whether the user can select a date or not. + \row \o \l{QCalendarWidget::}{horizontalHeaderFormat} + \o The format of the day names in the horizontal header + (e.g., "M", "Mon", or "Monday"). + \row \o \l{QCalendarWidget::}{verticalHeaderFormat} + \o The format of the vertical header. + \row \o \l{QCalendarWidget::}{navigationBarVisible} + \o Whether the navigation bar at the top of the calendar + widget is shown. + \endtable + + The example consists of one class, \c Window, which creates and + lays out the QCalendarWidget and the other widgets that let the + user configure the QCalendarWidget. + + \section1 Window Class Definition + + Here is the definition of the \c Window class: + + \snippet examples/widgets/calendarwidget/window.h 0 + \dots + \snippet examples/widgets/calendarwidget/window.h 1 + + As is often the case with classes that represent self-contained + windows, most of the API is private. We will review the private + members as we stumble upon them in the implementation. + + \section1 Window Class Implementation + + Let's now review the class implementation, starting with the constructor: + + \snippet examples/widgets/calendarwidget/window.cpp 0 + + We start by creating the four \l{QGroupBox}es and their child + widgets (including the QCalendarWidget) using four private \c + create...GroupBox() functions, described below. Then we arrange + the group boxes in a QGridLayout. + + We set the grid layout's resize policy to QLayout::SetFixedSize to + prevent the user from resizing the window. In that mode, the + window's size is set automatically by QGridLayout based on the + size hints of its contents widgets. + + To ensure that the window isn't automatically resized every time + we change a property of the QCalendarWidget (e.g., hiding the + navigation bar, trhe vertical header, or the grid), we set the + minimum height of row 0 and the minimum width of column 0 to the + initial size of the QCalendarWidget. + + Let's move on to the \c createPreviewGroupBox() function: + + \snippet examples/widgets/calendarwidget/window.cpp 9 + + The \gui Preview group box contains only one widget: the + QCalendarWidget. We set it up, connect its + \l{QCalendarWidget::}{currentPageChanged()} signal to our \c + reformatCalendarPage() slot to make sure that every new page gets + the formatting specified by the user. + + The \c createGeneralOptionsGroupBox() function is somewhat large + and several widgets are set up the same way; we look at parts of + its implementation here and skip the rest: + + \snippet examples/widgets/calendarwidget/window.cpp 10 + \dots + + We start with the setup of the \gui{Week starts on} combobox. + This combobox controls which day should be displayed as the first + day of the week. + + The QComboBox class lets us attach user data as a QVariant to + each item. The data can later be retrieved with QComboBox's + \l{QComboBox::}{itemData()} function. QVariant doesn't directly + support the Qt::DayOfWeek data type, but it supports \c int, and + C++ will happily convert any enum value to \c int. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 11 + \dots + + After creating the widgets, we connect the signals and slots. We + connect the comboboxes to private slots of \c Window or to + public slots provided by QComboBox. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 12 + + At the end of the function, we call the slots that update the calendar to ensure + that the QCalendarWidget is synchronized with the other widgets on startup. + + Let's now take a look at the \c createDatesGroupBox() private function: + + \snippet examples/widgets/calendarwidget/window.cpp 13 + + In this function, we create the \gui {Minimum Date}, \gui {Maximum Date}, + and \gui {Current Date} editor widgets, + which control the calendar's minimum, maximum, and selected dates. + The calendar's minimum and maximum dates have already been + set in \c createPrivewGroupBox(); we can then set the widgets + default values to the calendars values. + + \snippet examples/widgets/calendarwidget/window.cpp 14 + \dots + \snippet examples/widgets/calendarwidget/window.cpp 15 + + We connect the \c currentDateEdit's + \l{QDateEdit::}{dateChanged()} signal directly to the calendar's + \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's + selected date changes, either as a result of a user action or + programmatically, our \c selectedDateChanged() slot updates + the \gui {Current Date} editor. We also need to react when the user + changes the \gui{Minimum Date} and \gui{Maximum Date} editors. + + Here is the \c createTextFormatsGroup() function: + + \snippet examples/widgets/calendarwidget/window.cpp 16 + + We set up the \gui {Weekday Color} and \gui {Weekend Color} comboboxes + using \c createColorCombo(), which instantiates a QComboBox and + populates it with colors ("Red", "Blue", etc.). + + \snippet examples/widgets/calendarwidget/window.cpp 17 + + The \gui {Header Text Format} combobox lets the user change the + text format (bold, italic, or plain) used for horizontal and + vertical headers. The \gui {First Friday in blue} and \gui {May 1 + in red} check box affect the rendering of specific dates. + + \snippet examples/widgets/calendarwidget/window.cpp 18 + + We connect the check boxes and comboboxes to various private + slots. The \gui {First Friday in blue} and \gui {May 1 in red} + check boxes are both connected to \c reformatCalendarPage(), + which is also called when the calendar switches month. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 19 + + At the end of \c createTextFormatsGroupBox(), we call private + slots to synchronize the QCalendarWidget with the other widgets. + + We're now done reviewing the four \c create...GroupBox() + functions. Let's now take a look at the other private functions + and slots. + + \snippet examples/widgets/calendarwidget/window.cpp 20 + + In \c createColorCombo(), we create a combobox and populate it with + standard colors. The second argument to QComboBox::addItem() + is a QVariant storing user data (in this case, QColor objects). + + This function was used to set up the \gui {Weekday Color} + and \gui {Weekend Color} comboboxes. + + \snippet examples/widgets/calendarwidget/window.cpp 1 + + When the user changes the \gui {Week starts on} combobox's + value, \c firstDayChanged() is invoked with the index of the + combobox's new value. We retrieve the custom data item + associated with the new current item using + \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek. + + \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c + verticalHeaderChanged() are very similar to \c firstDayChanged(), + so they are omitted. + + \snippet examples/widgets/calendarwidget/window.cpp 2 + + The \c selectedDateChanged() updates the \gui{Current Date} + editor to reflect the current state of the QCalendarWidget. + + \snippet examples/widgets/calendarwidget/window.cpp 3 + + When the user changes the minimum date, we tell the + QCalenderWidget. We also update the \gui {Maximum Date} editor, + because if the new minimum date is later than the current maximum + date, QCalendarWidget will automatically adapt its maximum date + to avoid a contradicting state. + + \snippet examples/widgets/calendarwidget/window.cpp 4 + + \c maximumDateChanged() is implemented similarly to \c + minimumDateChanged(). + + \snippet examples/widgets/calendarwidget/window.cpp 5 + + Each combobox item has a QColor object as user data corresponding to the + item's text. After fetching the colors from the comboboxes, we + set the text format of each day of the week. + + The text format of a column in the calendar is given as a + QTextCharFormat, which besides the foreground color lets us + specify various character formatting information. In this + example, we only show a subset of the possibilities. + + \snippet examples/widgets/calendarwidget/window.cpp 6 + + \c weekendFormatChanged() is the same as \c + weekdayFormatChanged(), except that it affects Saturday and + Sunday instead of Monday to Friday. + + \snippet examples/widgets/calendarwidget/window.cpp 7 + + The \c reformatHeaders() slot is called when the user + changes the text format of + the headers. We compare the current text of the \gui {Header Text Format} + combobox to determine which format to apply. (An alternative would + have been to store \l{QTextCharFormat} values alongside the combobox + items.) + + \snippet examples/widgets/calendarwidget/window.cpp 8 + + In \c reformatCalendarPage(), we set the text format of the first + Friday in the month and May 1 in the current year. The text + formats that are actually used depend on which check boxes are + checked. + + QCalendarWidget lets us set the text format of individual dates + with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to + set the dates when the calendar page changes, i.e., a new month is + displayed. We check which of the \c mayFirstCheckBox and \c + firstDayCheckBox, if any, are checked + and set the text formats accordingly. +*/ |