[2] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[846] | 3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[561] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation (qt-info@nokia.com)
|
---|
[2] | 6 | **
|
---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
| 8 | **
|
---|
[846] | 9 | ** $QT_BEGIN_LICENSE:FDL$
|
---|
[2] | 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
[846] | 13 | ** Software or, alternatively, in accordance with the terms contained in a
|
---|
| 14 | ** written agreement between you and Nokia.
|
---|
[2] | 15 | **
|
---|
[846] | 16 | ** GNU Free Documentation License
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
---|
| 20 | ** file.
|
---|
[2] | 21 | **
|
---|
[561] | 22 | ** If you have questions regarding the use of this file, please contact
|
---|
| 23 | ** Nokia at qt-info@nokia.com.
|
---|
[2] | 24 | ** $QT_END_LICENSE$
|
---|
| 25 | **
|
---|
| 26 | ****************************************************************************/
|
---|
| 27 |
|
---|
| 28 | /*!
|
---|
| 29 | \title Calendar Widget Example
|
---|
| 30 | \example widgets/calendarwidget
|
---|
| 31 |
|
---|
| 32 | 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 | */
|
---|