Long live Qt!

1 files changed, 305 insertions, 0 deletions

diff --git a/doc/src/examples/calendarwidget.qdoc b/doc/src/examples/calendarwidget.qdoc
new file mode 100644
index 0000000..f4417c2
--- /dev/null
+++ b/doc/src/examples/calendarwidget.qdoc
@@ -0,0 +1,305 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Calendar Widget Example
+    \example widgets/calendarwidget
+
+    The Calendar Widget example shows use of \c QCalendarWidget.
+
+    \image calendarwidgetexample.png
+
+    QCalendarWidget displays one calendar month
+    at a time and lets the user select a date.
+    The calendar consists of four components: a navigation
+    bar that lets the user change the month that is
+    displayed, a grid where each cell represents one day
+    in the month, and two headers that display weekday names
+    and week numbers.
+
+    The Calendar Widget example displays a QCalendarWidget and lets the user
+    configure its appearance and behavior using
+    \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In
+    addition, the user can influence the formatting of individual dates
+    and headers.
+
+    The properties of the QCalendarWidget are summarized in the table
+    below.
+
+    \table
+    \header \o Property
+            \o Description
+    \row \o \l{QCalendarWidget::}{selectedDate}
+         \o The currently selected date.
+    \row \o \l{QCalendarWidget::}{minimumDate}
+         \o The earliest date that can be selected.
+    \row \o \l{QCalendarWidget::}{maximumDate}
+         \o The latest date that can be selected.
+    \row \o \l{QCalendarWidget::}{firstDayOfWeek}
+         \o The day that is displayed as the first day of the week
+            (usually Sunday or Monday).
+    \row \o \l{QCalendarWidget::}{gridVisible}
+         \o Whether the grid should be shown.
+    \row \o \l{QCalendarWidget::}{selectionMode}
+         \o Whether the user can select a date or not.
+    \row \o \l{QCalendarWidget::}{horizontalHeaderFormat}
+         \o The format of the day names in the horizontal header
+            (e.g., "M", "Mon", or "Monday").
+    \row \o \l{QCalendarWidget::}{verticalHeaderFormat}
+         \o The format of the vertical header.
+    \row \o \l{QCalendarWidget::}{navigationBarVisible}
+         \o Whether the navigation bar at the top of the calendar
+            widget is shown.
+    \endtable
+
+    The example consists of one class, \c Window, which creates and
+    lays out the QCalendarWidget and the other widgets that let the
+    user configure the QCalendarWidget.
+
+    \section1 Window Class Definition
+
+    Here is the definition of the \c Window class:
+
+    \snippet examples/widgets/calendarwidget/window.h 0
+    \dots
+    \snippet examples/widgets/calendarwidget/window.h 1
+
+    As is often the case with classes that represent self-contained
+    windows, most of the API is private. We will review the private
+    members as we stumble upon them in the implementation.
+
+    \section1 Window Class Implementation
+
+    Let's now review the class implementation, starting with the constructor:
+
+    \snippet examples/widgets/calendarwidget/window.cpp 0
+
+    We start by creating the four \l{QGroupBox}es and their child
+    widgets (including the QCalendarWidget) using four private \c
+    create...GroupBox() functions, described below. Then we arrange
+    the group boxes in a QGridLayout.
+
+    We set the grid layout's resize policy to QLayout::SetFixedSize to
+    prevent the user from resizing the window. In that mode, the
+    window's size is set automatically by QGridLayout based on the
+    size hints of its contents widgets.
+
+    To ensure that the window isn't automatically resized every time
+    we change a property of the QCalendarWidget (e.g., hiding the
+    navigation bar, trhe vertical header, or the grid), we set the
+    minimum height of row 0 and the minimum width of column 0 to the
+    initial size of the QCalendarWidget.
+
+    Let's move on to the \c createPreviewGroupBox() function:
+
+    \snippet examples/widgets/calendarwidget/window.cpp 9
+
+    The \gui Preview group box contains only one widget: the
+    QCalendarWidget. We set it up, connect its
+    \l{QCalendarWidget::}{currentPageChanged()} signal to our \c
+    reformatCalendarPage() slot to make sure that every new page gets
+    the formatting specified by the user.
+
+    The \c createGeneralOptionsGroupBox() function is somewhat large
+    and several widgets are set up the same way; we look at parts of
+    its implementation here and skip the rest:
+
+    \snippet examples/widgets/calendarwidget/window.cpp 10
+    \dots
+
+    We start with the setup of the \gui{Week starts on} combobox.
+    This combobox controls which day should be displayed as the first
+    day of the week.
+
+    The QComboBox class lets us attach user data as a QVariant to
+    each item. The data can later be retrieved with QComboBox's
+    \l{QComboBox::}{itemData()} function. QVariant doesn't directly
+    support the Qt::DayOfWeek data type, but it supports \c int, and
+    C++ will happily convert any enum value to \c int.
+
+    \dots
+    \snippet examples/widgets/calendarwidget/window.cpp 11
+    \dots
+
+    After creating the widgets, we connect the signals and slots. We
+    connect the comboboxes to private slots of \c Window or to
+    public slots provided by QComboBox.
+
+    \dots
+    \snippet examples/widgets/calendarwidget/window.cpp 12
+
+    At the end of the function, we call the slots that update the calendar to ensure
+    that the QCalendarWidget is synchronized with the other widgets on startup.
+
+    Let's now take a look at the \c createDatesGroupBox() private function:
+
+    \snippet examples/widgets/calendarwidget/window.cpp 13
+
+    In this function, we create the \gui {Minimum Date}, \gui {Maximum Date},
+    and \gui {Current Date} editor widgets,
+    which control the calendar's minimum, maximum, and selected dates.
+    The calendar's minimum and maximum dates have already been
+    set in \c createPrivewGroupBox(); we can then set the widgets
+    default values to the calendars values.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 14
+    \dots
+    \snippet examples/widgets/calendarwidget/window.cpp 15
+
+    We connect the \c currentDateEdit's
+    \l{QDateEdit::}{dateChanged()} signal directly to the calendar's
+    \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's
+    selected date changes, either as a result of a user action or
+    programmatically, our \c selectedDateChanged() slot updates
+    the \gui {Current Date} editor. We also need to react when the user
+    changes the \gui{Minimum Date} and \gui{Maximum Date} editors.
+
+    Here is the \c createTextFormatsGroup() function:
+
+    \snippet examples/widgets/calendarwidget/window.cpp 16
+
+    We set up the \gui {Weekday Color} and \gui {Weekend Color} comboboxes
+    using \c createColorCombo(), which instantiates a QComboBox and
+    populates it with colors ("Red", "Blue", etc.).
+
+    \snippet examples/widgets/calendarwidget/window.cpp 17
+
+    The \gui {Header Text Format} combobox lets the user change the
+    text format (bold, italic, or plain) used for horizontal and
+    vertical headers. The \gui {First Friday in blue} and \gui {May 1
+    in red} check box affect the rendering of specific dates.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 18
+
+    We connect the check boxes and comboboxes to various private
+    slots. The \gui {First Friday in blue} and \gui {May 1 in red}
+    check boxes are both connected to \c reformatCalendarPage(),
+    which is also called when the calendar switches month.
+
+    \dots
+    \snippet examples/widgets/calendarwidget/window.cpp 19
+
+    At the end of \c createTextFormatsGroupBox(), we call private
+    slots to synchronize the QCalendarWidget with the other widgets.
+
+    We're now done reviewing the four \c create...GroupBox()
+    functions. Let's now take a look at the other private functions
+    and slots.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 20
+
+    In \c createColorCombo(), we create a combobox and populate it with
+    standard colors. The second argument to QComboBox::addItem()
+    is a QVariant storing user data (in this case, QColor objects).
+
+    This function was used to set up the \gui {Weekday Color}
+    and \gui {Weekend Color} comboboxes.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 1
+
+    When the user changes the \gui {Week starts on} combobox's
+    value, \c firstDayChanged() is invoked with the index of the
+    combobox's new value. We retrieve the custom data item
+    associated with the new current item using
+    \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek.
+
+    \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c
+    verticalHeaderChanged() are very similar to \c firstDayChanged(),
+    so they are omitted.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 2
+
+    The \c selectedDateChanged() updates the \gui{Current Date}
+    editor to reflect the current state of the QCalendarWidget.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 3
+
+    When the user changes the minimum date, we tell the
+    QCalenderWidget. We also update the \gui {Maximum Date} editor,
+    because if the new minimum date is later than the current maximum
+    date, QCalendarWidget will automatically adapt its maximum date
+    to avoid a contradicting state.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 4
+
+    \c maximumDateChanged() is implemented similarly to \c
+    minimumDateChanged().
+
+    \snippet examples/widgets/calendarwidget/window.cpp 5
+
+    Each combobox item has a QColor object as user data corresponding to the
+    item's text. After fetching the colors from the comboboxes, we
+    set the text format of each day of the week.
+
+    The text format of a column in the calendar is given as a
+    QTextCharFormat, which besides the foreground color lets us
+    specify various character formatting information. In this
+    example, we only show a subset of the possibilities.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 6
+
+    \c weekendFormatChanged() is the same as \c
+    weekdayFormatChanged(), except that it affects Saturday and
+    Sunday instead of Monday to Friday.
+
+    \snippet examples/widgets/calendarwidget/window.cpp 7
+
+    The \c reformatHeaders() slot is called when the user
+    changes the text format of
+    the headers. We compare the current text of the \gui {Header Text Format}
+    combobox to determine which format to apply. (An alternative would
+    have been to store \l{QTextCharFormat} values alongside the combobox
+    items.)
+
+    \snippet examples/widgets/calendarwidget/window.cpp 8
+
+    In \c reformatCalendarPage(), we set the text format of the first
+    Friday in the month and May 1 in the current year. The text
+    formats that are actually used depend on which check boxes are
+    checked.
+
+    QCalendarWidget lets us set the text format of individual dates
+    with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to
+    set the dates when the calendar page changes, i.e., a new month is
+    displayed. We check which of the \c mayFirstCheckBox and \c
+    firstDayCheckBox, if any, are checked
+    and set the text formats accordingly.
+*/