Update copyright headers
[qt:qt.git] / doc / src / examples / calendarwidget.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
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 The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
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.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \title Calendar Widget Example
30     \example widgets/calendarwidget
31
32     \brief The Calendar Widget example shows use of \c QCalendarWidget.
33
34     \image calendarwidgetexample.png
35
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
42     and week numbers.
43
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
48     and headers.
49
50     The properties of the QCalendarWidget are summarized in the table
51     below.
52
53     \table
54     \header \o Property
55             \o Description
56     \row \o \l{QCalendarWidget::}{selectedDate}
57          \o The currently selected date.
58     \row \o \l{QCalendarWidget::}{minimumDate}
59          \o The earliest date that can be selected.
60     \row \o \l{QCalendarWidget::}{maximumDate}
61          \o The latest date that can be selected.
62     \row \o \l{QCalendarWidget::}{firstDayOfWeek}
63          \o The day that is displayed as the first day of the week
64             (usually Sunday or Monday).
65     \row \o \l{QCalendarWidget::}{gridVisible}
66          \o Whether the grid should be shown.
67     \row \o \l{QCalendarWidget::}{selectionMode}
68          \o Whether the user can select a date or not.
69     \row \o \l{QCalendarWidget::}{horizontalHeaderFormat}
70          \o The format of the day names in the horizontal header
71             (e.g., "M", "Mon", or "Monday").
72     \row \o \l{QCalendarWidget::}{verticalHeaderFormat}
73          \o The format of the vertical header.
74     \row \o \l{QCalendarWidget::}{navigationBarVisible}
75          \o Whether the navigation bar at the top of the calendar
76             widget is shown.
77     \endtable
78
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.
82
83     \section1 Window Class Definition
84
85     Here is the definition of the \c Window class:
86
87     \snippet examples/widgets/calendarwidget/window.h 0
88     \dots
89     \snippet examples/widgets/calendarwidget/window.h 1
90
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.
94
95     \section1 Window Class Implementation
96
97     Let's now review the class implementation, starting with the constructor:
98
99     \snippet examples/widgets/calendarwidget/window.cpp 0
100
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.
105
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.
110
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.
116
117     Let's move on to the \c createPreviewGroupBox() function:
118
119     \snippet examples/widgets/calendarwidget/window.cpp 9
120
121     The \gui 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.
126
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:
130
131     \snippet examples/widgets/calendarwidget/window.cpp 10
132     \dots
133
134     We start with the setup of the \gui{Week starts on} combobox.
135     This combobox controls which day should be displayed as the first
136     day of the week.
137
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.
143
144     \dots
145     \snippet examples/widgets/calendarwidget/window.cpp 11
146     \dots
147
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.
151
152     \dots
153     \snippet examples/widgets/calendarwidget/window.cpp 12
154
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.
157
158     Let's now take a look at the \c createDatesGroupBox() private function:
159
160     \snippet examples/widgets/calendarwidget/window.cpp 13
161
162     In this function, we create the \gui {Minimum Date}, \gui {Maximum Date},
163     and \gui {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.
168
169     \snippet examples/widgets/calendarwidget/window.cpp 14
170     \dots
171     \snippet examples/widgets/calendarwidget/window.cpp 15
172
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 \gui {Current Date} editor. We also need to react when the user
179     changes the \gui{Minimum Date} and \gui{Maximum Date} editors.
180
181     Here is the \c createTextFormatsGroup() function:
182
183     \snippet examples/widgets/calendarwidget/window.cpp 16
184
185     We set up the \gui {Weekday Color} and \gui {Weekend Color} comboboxes
186     using \c createColorCombo(), which instantiates a QComboBox and
187     populates it with colors ("Red", "Blue", etc.).
188
189     \snippet examples/widgets/calendarwidget/window.cpp 17
190
191     The \gui {Header Text Format} combobox lets the user change the
192     text format (bold, italic, or plain) used for horizontal and
193     vertical headers. The \gui {First Friday in blue} and \gui {May 1
194     in red} check box affect the rendering of specific dates.
195
196     \snippet examples/widgets/calendarwidget/window.cpp 18
197
198     We connect the check boxes and comboboxes to various private
199     slots. The \gui {First Friday in blue} and \gui {May 1 in red}
200     check boxes are both connected to \c reformatCalendarPage(),
201     which is also called when the calendar switches month.
202
203     \dots
204     \snippet examples/widgets/calendarwidget/window.cpp 19
205
206     At the end of \c createTextFormatsGroupBox(), we call private
207     slots to synchronize the QCalendarWidget with the other widgets.
208
209     We're now done reviewing the four \c create...GroupBox()
210     functions. Let's now take a look at the other private functions
211     and slots.
212
213     \snippet examples/widgets/calendarwidget/window.cpp 20
214
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).
218
219     This function was used to set up the \gui {Weekday Color}
220     and \gui {Weekend Color} comboboxes.
221
222     \snippet examples/widgets/calendarwidget/window.cpp 1
223
224     When the user changes the \gui {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.
229
230     \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c
231     verticalHeaderChanged() are very similar to \c firstDayChanged(),
232     so they are omitted.
233
234     \snippet examples/widgets/calendarwidget/window.cpp 2
235
236     The \c selectedDateChanged() updates the \gui{Current Date}
237     editor to reflect the current state of the QCalendarWidget.
238
239     \snippet examples/widgets/calendarwidget/window.cpp 3
240
241     When the user changes the minimum date, we tell the
242     QCalenderWidget. We also update the \gui {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.
246
247     \snippet examples/widgets/calendarwidget/window.cpp 4
248
249     \c maximumDateChanged() is implemented similarly to \c
250     minimumDateChanged().
251
252     \snippet examples/widgets/calendarwidget/window.cpp 5
253
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.
257
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.
262
263     \snippet examples/widgets/calendarwidget/window.cpp 6
264
265     \c weekendFormatChanged() is the same as \c
266     weekdayFormatChanged(), except that it affects Saturday and
267     Sunday instead of Monday to Friday.
268
269     \snippet examples/widgets/calendarwidget/window.cpp 7
270
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 \gui {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
276     items.)
277
278     \snippet examples/widgets/calendarwidget/window.cpp 8
279
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.
284
285     QCalendarWidget lets us set the text format of individual dates
286     with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to
287     set the dates when the calendar page changes, i.e., a new month is
288     displayed. We check which of the \c mayFirstCheckBox and \c
289     firstDayCheckBox, if any, are checked
290     and set the text formats accordingly.
291 */