examples/widgets/doc/src/calendarwidget.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 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.
  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     \ingroup examples-widgets
  32     \brief The Calendar Widget example shows use of 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 \li Property
  55             \li Description
  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
  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 widgets/calendarwidget/window.h 0
  88     \dots
  89     \snippet 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 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 widgets/calendarwidget/window.cpp 9
 120
 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.
 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 widgets/calendarwidget/window.cpp 10
 132     \dots
 133
 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
 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 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 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 widgets/calendarwidget/window.cpp 13
 161
 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.
 168
 169     \snippet widgets/calendarwidget/window.cpp 14
 170     \dots
 171     \snippet 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 \uicontrol {Current Date} editor. We also need to react when the user
 179     changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors.
 180
 181     Here is the \c createTextFormatsGroup() function:
 182
 183     \snippet widgets/calendarwidget/window.cpp 16
 184
 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.).
 188
 189     \snippet widgets/calendarwidget/window.cpp 17
 190
 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.
 195
 196     \snippet widgets/calendarwidget/window.cpp 18
 197
 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.
 202
 203     \dots
 204     \snippet 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 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 \uicontrol {Weekday Color}
 220     and \uicontrol {Weekend Color} comboboxes.
 221
 222     \snippet widgets/calendarwidget/window.cpp 1
 223
 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.
 229
 230     \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c
 231     verticalHeaderChanged() are very similar to \c firstDayChanged(),
 232     so they are omitted.
 233
 234     \snippet widgets/calendarwidget/window.cpp 2
 235
 236     The \c selectedDateChanged() updates the \uicontrol{Current Date}
 237     editor to reflect the current state of the QCalendarWidget.
 238
 239     \snippet widgets/calendarwidget/window.cpp 3
 240
 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.
 246
 247     \snippet widgets/calendarwidget/window.cpp 4
 248
 249     \c maximumDateChanged() is implemented similarly to \c
 250     minimumDateChanged().
 251
 252     \snippet 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 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 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 \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
 276     items.)
 277
 278     \snippet 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 and what the weekday/weekend formats are.
 284
 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.
 291 */