1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file. Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
26 ****************************************************************************/
29 \title Calendar Widget Example
30 \example widgets/calendarwidget
31 \ingroup examples-widgets
32 \brief The Calendar Widget example shows use of QCalendarWidget.
34 \image calendarwidgetexample.png
36 QCalendarWidget displays one calendar month
37 at a time and lets the user select a date.
38 The calendar consists of four components: a navigation
39 bar that lets the user change the month that is
40 displayed, a grid where each cell represents one day
41 in the month, and two headers that display weekday names
44 The Calendar Widget example displays a QCalendarWidget and lets the user
45 configure its appearance and behavior using
46 \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In
47 addition, the user can influence the formatting of individual dates
50 The properties of the QCalendarWidget are summarized in the table
56 \row \li \l{QCalendarWidget::}{selectedDate}
57 \li The currently selected date.
58 \row \li \l{QCalendarWidget::}{minimumDate}
59 \li The earliest date that can be selected.
60 \row \li \l{QCalendarWidget::}{maximumDate}
61 \li The latest date that can be selected.
62 \row \li \l{QCalendarWidget::}{firstDayOfWeek}
63 \li The day that is displayed as the first day of the week
64 (usually Sunday or Monday).
65 \row \li \l{QCalendarWidget::}{gridVisible}
66 \li Whether the grid should be shown.
67 \row \li \l{QCalendarWidget::}{selectionMode}
68 \li Whether the user can select a date or not.
69 \row \li \l{QCalendarWidget::}{horizontalHeaderFormat}
70 \li The format of the day names in the horizontal header
71 (e.g., "M", "Mon", or "Monday").
72 \row \li \l{QCalendarWidget::}{verticalHeaderFormat}
73 \li The format of the vertical header.
74 \row \li \l{QCalendarWidget::}{navigationBarVisible}
75 \li Whether the navigation bar at the top of the calendar
79 The example consists of one class, \c Window, which creates and
80 lays out the QCalendarWidget and the other widgets that let the
81 user configure the QCalendarWidget.
83 \section1 Window Class Definition
85 Here is the definition of the \c Window class:
87 \snippet widgets/calendarwidget/window.h 0
89 \snippet widgets/calendarwidget/window.h 1
91 As is often the case with classes that represent self-contained
92 windows, most of the API is private. We will review the private
93 members as we stumble upon them in the implementation.
95 \section1 Window Class Implementation
97 Let's now review the class implementation, starting with the constructor:
99 \snippet widgets/calendarwidget/window.cpp 0
101 We start by creating the four \l{QGroupBox}es and their child
102 widgets (including the QCalendarWidget) using four private \c
103 create...GroupBox() functions, described below. Then we arrange
104 the group boxes in a QGridLayout.
106 We set the grid layout's resize policy to QLayout::SetFixedSize to
107 prevent the user from resizing the window. In that mode, the
108 window's size is set automatically by QGridLayout based on the
109 size hints of its contents widgets.
111 To ensure that the window isn't automatically resized every time
112 we change a property of the QCalendarWidget (e.g., hiding the
113 navigation bar, trhe vertical header, or the grid), we set the
114 minimum height of row 0 and the minimum width of column 0 to the
115 initial size of the QCalendarWidget.
117 Let's move on to the \c createPreviewGroupBox() function:
119 \snippet widgets/calendarwidget/window.cpp 9
121 The \uicontrol Preview group box contains only one widget: the
122 QCalendarWidget. We set it up, connect its
123 \l{QCalendarWidget::}{currentPageChanged()} signal to our \c
124 reformatCalendarPage() slot to make sure that every new page gets
125 the formatting specified by the user.
127 The \c createGeneralOptionsGroupBox() function is somewhat large
128 and several widgets are set up the same way; we look at parts of
129 its implementation here and skip the rest:
131 \snippet widgets/calendarwidget/window.cpp 10
134 We start with the setup of the \uicontrol{Week starts on} combobox.
135 This combobox controls which day should be displayed as the first
138 The QComboBox class lets us attach user data as a QVariant to
139 each item. The data can later be retrieved with QComboBox's
140 \l{QComboBox::}{itemData()} function. QVariant doesn't directly
141 support the Qt::DayOfWeek data type, but it supports \c int, and
142 C++ will happily convert any enum value to \c int.
145 \snippet widgets/calendarwidget/window.cpp 11
148 After creating the widgets, we connect the signals and slots. We
149 connect the comboboxes to private slots of \c Window or to
150 public slots provided by QComboBox.
153 \snippet widgets/calendarwidget/window.cpp 12
155 At the end of the function, we call the slots that update the calendar to ensure
156 that the QCalendarWidget is synchronized with the other widgets on startup.
158 Let's now take a look at the \c createDatesGroupBox() private function:
160 \snippet widgets/calendarwidget/window.cpp 13
162 In this function, we create the \uicontrol {Minimum Date}, \uicontrol {Maximum Date},
163 and \uicontrol {Current Date} editor widgets,
164 which control the calendar's minimum, maximum, and selected dates.
165 The calendar's minimum and maximum dates have already been
166 set in \c createPrivewGroupBox(); we can then set the widgets
167 default values to the calendars values.
169 \snippet widgets/calendarwidget/window.cpp 14
171 \snippet widgets/calendarwidget/window.cpp 15
173 We connect the \c currentDateEdit's
174 \l{QDateEdit::}{dateChanged()} signal directly to the calendar's
175 \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's
176 selected date changes, either as a result of a user action or
177 programmatically, our \c selectedDateChanged() slot updates
178 the \uicontrol {Current Date} editor. We also need to react when the user
179 changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors.
181 Here is the \c createTextFormatsGroup() function:
183 \snippet widgets/calendarwidget/window.cpp 16
185 We set up the \uicontrol {Weekday Color} and \uicontrol {Weekend Color} comboboxes
186 using \c createColorCombo(), which instantiates a QComboBox and
187 populates it with colors ("Red", "Blue", etc.).
189 \snippet widgets/calendarwidget/window.cpp 17
191 The \uicontrol {Header Text Format} combobox lets the user change the
192 text format (bold, italic, or plain) used for horizontal and
193 vertical headers. The \uicontrol {First Friday in blue} and \uicontrol {May 1
194 in red} check box affect the rendering of specific dates.
196 \snippet widgets/calendarwidget/window.cpp 18
198 We connect the check boxes and comboboxes to various private
199 slots. The \uicontrol {First Friday in blue} and \uicontrol {May 1 in red}
200 check boxes are both connected to \c reformatCalendarPage(),
201 which is also called when the calendar switches month.
204 \snippet widgets/calendarwidget/window.cpp 19
206 At the end of \c createTextFormatsGroupBox(), we call private
207 slots to synchronize the QCalendarWidget with the other widgets.
209 We're now done reviewing the four \c create...GroupBox()
210 functions. Let's now take a look at the other private functions
213 \snippet widgets/calendarwidget/window.cpp 20
215 In \c createColorCombo(), we create a combobox and populate it with
216 standard colors. The second argument to QComboBox::addItem()
217 is a QVariant storing user data (in this case, QColor objects).
219 This function was used to set up the \uicontrol {Weekday Color}
220 and \uicontrol {Weekend Color} comboboxes.
222 \snippet widgets/calendarwidget/window.cpp 1
224 When the user changes the \uicontrol {Week starts on} combobox's
225 value, \c firstDayChanged() is invoked with the index of the
226 combobox's new value. We retrieve the custom data item
227 associated with the new current item using
228 \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek.
230 \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c
231 verticalHeaderChanged() are very similar to \c firstDayChanged(),
234 \snippet widgets/calendarwidget/window.cpp 2
236 The \c selectedDateChanged() updates the \uicontrol{Current Date}
237 editor to reflect the current state of the QCalendarWidget.
239 \snippet widgets/calendarwidget/window.cpp 3
241 When the user changes the minimum date, we tell the
242 QCalenderWidget. We also update the \uicontrol {Maximum Date} editor,
243 because if the new minimum date is later than the current maximum
244 date, QCalendarWidget will automatically adapt its maximum date
245 to avoid a contradicting state.
247 \snippet widgets/calendarwidget/window.cpp 4
249 \c maximumDateChanged() is implemented similarly to \c
250 minimumDateChanged().
252 \snippet widgets/calendarwidget/window.cpp 5
254 Each combobox item has a QColor object as user data corresponding to the
255 item's text. After fetching the colors from the comboboxes, we
256 set the text format of each day of the week.
258 The text format of a column in the calendar is given as a
259 QTextCharFormat, which besides the foreground color lets us
260 specify various character formatting information. In this
261 example, we only show a subset of the possibilities.
263 \snippet widgets/calendarwidget/window.cpp 6
265 \c weekendFormatChanged() is the same as \c
266 weekdayFormatChanged(), except that it affects Saturday and
267 Sunday instead of Monday to Friday.
269 \snippet widgets/calendarwidget/window.cpp 7
271 The \c reformatHeaders() slot is called when the user
272 changes the text format of
273 the headers. We compare the current text of the \uicontrol {Header Text Format}
274 combobox to determine which format to apply. (An alternative would
275 have been to store \l{QTextCharFormat} values alongside the combobox
278 \snippet widgets/calendarwidget/window.cpp 8
280 In \c reformatCalendarPage(), we set the text format of the first
281 Friday in the month and May 1 in the current year. The text
282 formats that are actually used depend on which check boxes are
283 checked and what the weekday/weekend formats are.
285 QCalendarWidget lets us set the text format of individual dates
286 with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to
287 set the date formats when the calendar page changes - i.e. a new month is
288 displayed - and when the weekday/weekend format is changed.
289 We check which of the \c mayFirstCheckBox and \c firstDayCheckBox, if any,
290 are checked and set the text formats accordingly.