doc/src/examples/calendarwidget.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 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 */