|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \title Calendar Widget Example |
|
44 \example widgets/calendarwidget |
|
45 |
|
46 The Calendar Widget example shows use of \c QCalendarWidget. |
|
47 |
|
48 \image calendarwidgetexample.png |
|
49 |
|
50 QCalendarWidget displays one calendar month |
|
51 at a time and lets the user select a date. |
|
52 The calendar consists of four components: a navigation |
|
53 bar that lets the user change the month that is |
|
54 displayed, a grid where each cell represents one day |
|
55 in the month, and two headers that display weekday names |
|
56 and week numbers. |
|
57 |
|
58 The Calendar Widget example displays a QCalendarWidget and lets the user |
|
59 configure its appearance and behavior using |
|
60 \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In |
|
61 addition, the user can influence the formatting of individual dates |
|
62 and headers. |
|
63 |
|
64 The properties of the QCalendarWidget are summarized in the table |
|
65 below. |
|
66 |
|
67 \table |
|
68 \header \o Property |
|
69 \o Description |
|
70 \row \o \l{QCalendarWidget::}{selectedDate} |
|
71 \o The currently selected date. |
|
72 \row \o \l{QCalendarWidget::}{minimumDate} |
|
73 \o The earliest date that can be selected. |
|
74 \row \o \l{QCalendarWidget::}{maximumDate} |
|
75 \o The latest date that can be selected. |
|
76 \row \o \l{QCalendarWidget::}{firstDayOfWeek} |
|
77 \o The day that is displayed as the first day of the week |
|
78 (usually Sunday or Monday). |
|
79 \row \o \l{QCalendarWidget::}{gridVisible} |
|
80 \o Whether the grid should be shown. |
|
81 \row \o \l{QCalendarWidget::}{selectionMode} |
|
82 \o Whether the user can select a date or not. |
|
83 \row \o \l{QCalendarWidget::}{horizontalHeaderFormat} |
|
84 \o The format of the day names in the horizontal header |
|
85 (e.g., "M", "Mon", or "Monday"). |
|
86 \row \o \l{QCalendarWidget::}{verticalHeaderFormat} |
|
87 \o The format of the vertical header. |
|
88 \row \o \l{QCalendarWidget::}{navigationBarVisible} |
|
89 \o Whether the navigation bar at the top of the calendar |
|
90 widget is shown. |
|
91 \endtable |
|
92 |
|
93 The example consists of one class, \c Window, which creates and |
|
94 lays out the QCalendarWidget and the other widgets that let the |
|
95 user configure the QCalendarWidget. |
|
96 |
|
97 \section1 Window Class Definition |
|
98 |
|
99 Here is the definition of the \c Window class: |
|
100 |
|
101 \snippet examples/widgets/calendarwidget/window.h 0 |
|
102 \dots |
|
103 \snippet examples/widgets/calendarwidget/window.h 1 |
|
104 |
|
105 As is often the case with classes that represent self-contained |
|
106 windows, most of the API is private. We will review the private |
|
107 members as we stumble upon them in the implementation. |
|
108 |
|
109 \section1 Window Class Implementation |
|
110 |
|
111 Let's now review the class implementation, starting with the constructor: |
|
112 |
|
113 \snippet examples/widgets/calendarwidget/window.cpp 0 |
|
114 |
|
115 We start by creating the four \l{QGroupBox}es and their child |
|
116 widgets (including the QCalendarWidget) using four private \c |
|
117 create...GroupBox() functions, described below. Then we arrange |
|
118 the group boxes in a QGridLayout. |
|
119 |
|
120 We set the grid layout's resize policy to QLayout::SetFixedSize to |
|
121 prevent the user from resizing the window. In that mode, the |
|
122 window's size is set automatically by QGridLayout based on the |
|
123 size hints of its contents widgets. |
|
124 |
|
125 To ensure that the window isn't automatically resized every time |
|
126 we change a property of the QCalendarWidget (e.g., hiding the |
|
127 navigation bar, trhe vertical header, or the grid), we set the |
|
128 minimum height of row 0 and the minimum width of column 0 to the |
|
129 initial size of the QCalendarWidget. |
|
130 |
|
131 Let's move on to the \c createPreviewGroupBox() function: |
|
132 |
|
133 \snippet examples/widgets/calendarwidget/window.cpp 9 |
|
134 |
|
135 The \gui Preview group box contains only one widget: the |
|
136 QCalendarWidget. We set it up, connect its |
|
137 \l{QCalendarWidget::}{currentPageChanged()} signal to our \c |
|
138 reformatCalendarPage() slot to make sure that every new page gets |
|
139 the formatting specified by the user. |
|
140 |
|
141 The \c createGeneralOptionsGroupBox() function is somewhat large |
|
142 and several widgets are set up the same way; we look at parts of |
|
143 its implementation here and skip the rest: |
|
144 |
|
145 \snippet examples/widgets/calendarwidget/window.cpp 10 |
|
146 \dots |
|
147 |
|
148 We start with the setup of the \gui{Week starts on} combobox. |
|
149 This combobox controls which day should be displayed as the first |
|
150 day of the week. |
|
151 |
|
152 The QComboBox class lets us attach user data as a QVariant to |
|
153 each item. The data can later be retrieved with QComboBox's |
|
154 \l{QComboBox::}{itemData()} function. QVariant doesn't directly |
|
155 support the Qt::DayOfWeek data type, but it supports \c int, and |
|
156 C++ will happily convert any enum value to \c int. |
|
157 |
|
158 \dots |
|
159 \snippet examples/widgets/calendarwidget/window.cpp 11 |
|
160 \dots |
|
161 |
|
162 After creating the widgets, we connect the signals and slots. We |
|
163 connect the comboboxes to private slots of \c Window or to |
|
164 public slots provided by QComboBox. |
|
165 |
|
166 \dots |
|
167 \snippet examples/widgets/calendarwidget/window.cpp 12 |
|
168 |
|
169 At the end of the function, we call the slots that update the calendar to ensure |
|
170 that the QCalendarWidget is synchronized with the other widgets on startup. |
|
171 |
|
172 Let's now take a look at the \c createDatesGroupBox() private function: |
|
173 |
|
174 \snippet examples/widgets/calendarwidget/window.cpp 13 |
|
175 |
|
176 In this function, we create the \gui {Minimum Date}, \gui {Maximum Date}, |
|
177 and \gui {Current Date} editor widgets, |
|
178 which control the calendar's minimum, maximum, and selected dates. |
|
179 The calendar's minimum and maximum dates have already been |
|
180 set in \c createPrivewGroupBox(); we can then set the widgets |
|
181 default values to the calendars values. |
|
182 |
|
183 \snippet examples/widgets/calendarwidget/window.cpp 14 |
|
184 \dots |
|
185 \snippet examples/widgets/calendarwidget/window.cpp 15 |
|
186 |
|
187 We connect the \c currentDateEdit's |
|
188 \l{QDateEdit::}{dateChanged()} signal directly to the calendar's |
|
189 \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's |
|
190 selected date changes, either as a result of a user action or |
|
191 programmatically, our \c selectedDateChanged() slot updates |
|
192 the \gui {Current Date} editor. We also need to react when the user |
|
193 changes the \gui{Minimum Date} and \gui{Maximum Date} editors. |
|
194 |
|
195 Here is the \c createTextFormatsGroup() function: |
|
196 |
|
197 \snippet examples/widgets/calendarwidget/window.cpp 16 |
|
198 |
|
199 We set up the \gui {Weekday Color} and \gui {Weekend Color} comboboxes |
|
200 using \c createColorCombo(), which instantiates a QComboBox and |
|
201 populates it with colors ("Red", "Blue", etc.). |
|
202 |
|
203 \snippet examples/widgets/calendarwidget/window.cpp 17 |
|
204 |
|
205 The \gui {Header Text Format} combobox lets the user change the |
|
206 text format (bold, italic, or plain) used for horizontal and |
|
207 vertical headers. The \gui {First Friday in blue} and \gui {May 1 |
|
208 in red} check box affect the rendering of specific dates. |
|
209 |
|
210 \snippet examples/widgets/calendarwidget/window.cpp 18 |
|
211 |
|
212 We connect the check boxes and comboboxes to various private |
|
213 slots. The \gui {First Friday in blue} and \gui {May 1 in red} |
|
214 check boxes are both connected to \c reformatCalendarPage(), |
|
215 which is also called when the calendar switches month. |
|
216 |
|
217 \dots |
|
218 \snippet examples/widgets/calendarwidget/window.cpp 19 |
|
219 |
|
220 At the end of \c createTextFormatsGroupBox(), we call private |
|
221 slots to synchronize the QCalendarWidget with the other widgets. |
|
222 |
|
223 We're now done reviewing the four \c create...GroupBox() |
|
224 functions. Let's now take a look at the other private functions |
|
225 and slots. |
|
226 |
|
227 \snippet examples/widgets/calendarwidget/window.cpp 20 |
|
228 |
|
229 In \c createColorCombo(), we create a combobox and populate it with |
|
230 standard colors. The second argument to QComboBox::addItem() |
|
231 is a QVariant storing user data (in this case, QColor objects). |
|
232 |
|
233 This function was used to set up the \gui {Weekday Color} |
|
234 and \gui {Weekend Color} comboboxes. |
|
235 |
|
236 \snippet examples/widgets/calendarwidget/window.cpp 1 |
|
237 |
|
238 When the user changes the \gui {Week starts on} combobox's |
|
239 value, \c firstDayChanged() is invoked with the index of the |
|
240 combobox's new value. We retrieve the custom data item |
|
241 associated with the new current item using |
|
242 \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek. |
|
243 |
|
244 \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c |
|
245 verticalHeaderChanged() are very similar to \c firstDayChanged(), |
|
246 so they are omitted. |
|
247 |
|
248 \snippet examples/widgets/calendarwidget/window.cpp 2 |
|
249 |
|
250 The \c selectedDateChanged() updates the \gui{Current Date} |
|
251 editor to reflect the current state of the QCalendarWidget. |
|
252 |
|
253 \snippet examples/widgets/calendarwidget/window.cpp 3 |
|
254 |
|
255 When the user changes the minimum date, we tell the |
|
256 QCalenderWidget. We also update the \gui {Maximum Date} editor, |
|
257 because if the new minimum date is later than the current maximum |
|
258 date, QCalendarWidget will automatically adapt its maximum date |
|
259 to avoid a contradicting state. |
|
260 |
|
261 \snippet examples/widgets/calendarwidget/window.cpp 4 |
|
262 |
|
263 \c maximumDateChanged() is implemented similarly to \c |
|
264 minimumDateChanged(). |
|
265 |
|
266 \snippet examples/widgets/calendarwidget/window.cpp 5 |
|
267 |
|
268 Each combobox item has a QColor object as user data corresponding to the |
|
269 item's text. After fetching the colors from the comboboxes, we |
|
270 set the text format of each day of the week. |
|
271 |
|
272 The text format of a column in the calendar is given as a |
|
273 QTextCharFormat, which besides the foreground color lets us |
|
274 specify various character formatting information. In this |
|
275 example, we only show a subset of the possibilities. |
|
276 |
|
277 \snippet examples/widgets/calendarwidget/window.cpp 6 |
|
278 |
|
279 \c weekendFormatChanged() is the same as \c |
|
280 weekdayFormatChanged(), except that it affects Saturday and |
|
281 Sunday instead of Monday to Friday. |
|
282 |
|
283 \snippet examples/widgets/calendarwidget/window.cpp 7 |
|
284 |
|
285 The \c reformatHeaders() slot is called when the user |
|
286 changes the text format of |
|
287 the headers. We compare the current text of the \gui {Header Text Format} |
|
288 combobox to determine which format to apply. (An alternative would |
|
289 have been to store \l{QTextCharFormat} values alongside the combobox |
|
290 items.) |
|
291 |
|
292 \snippet examples/widgets/calendarwidget/window.cpp 8 |
|
293 |
|
294 In \c reformatCalendarPage(), we set the text format of the first |
|
295 Friday in the month and May 1 in the current year. The text |
|
296 formats that are actually used depend on which check boxes are |
|
297 checked. |
|
298 |
|
299 QCalendarWidget lets us set the text format of individual dates |
|
300 with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to |
|
301 set the dates when the calendar page changes, i.e., a new month is |
|
302 displayed. We check which of the \c mayFirstCheckBox and \c |
|
303 firstDayCheckBox, if any, are checked |
|
304 and set the text formats accordingly. |
|
305 */ |