diff options
Diffstat (limited to 'doc/src/examples/calendarwidget.qdoc')
| -rw-r--r-- | doc/src/examples/calendarwidget.qdoc | 291 |
1 files changed, 0 insertions, 291 deletions
diff --git a/doc/src/examples/calendarwidget.qdoc b/doc/src/examples/calendarwidget.qdoc deleted file mode 100644 index 45423cc2c6..0000000000 --- a/doc/src/examples/calendarwidget.qdoc +++ /dev/null @@ -1,291 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \li Property - \li Description - \row \li \l{QCalendarWidget::}{selectedDate} - \li The currently selected date. - \row \li \l{QCalendarWidget::}{minimumDate} - \li The earliest date that can be selected. - \row \li \l{QCalendarWidget::}{maximumDate} - \li The latest date that can be selected. - \row \li \l{QCalendarWidget::}{firstDayOfWeek} - \li The day that is displayed as the first day of the week - (usually Sunday or Monday). - \row \li \l{QCalendarWidget::}{gridVisible} - \li Whether the grid should be shown. - \row \li \l{QCalendarWidget::}{selectionMode} - \li Whether the user can select a date or not. - \row \li \l{QCalendarWidget::}{horizontalHeaderFormat} - \li The format of the day names in the horizontal header - (e.g., "M", "Mon", or "Monday"). - \row \li \l{QCalendarWidget::}{verticalHeaderFormat} - \li The format of the vertical header. - \row \li \l{QCalendarWidget::}{navigationBarVisible} - \li 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 \uicontrol 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 \uicontrol{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 \uicontrol {Minimum Date}, \uicontrol {Maximum Date}, - and \uicontrol {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 \uicontrol {Current Date} editor. We also need to react when the user - changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors. - - Here is the \c createTextFormatsGroup() function: - - \snippet examples/widgets/calendarwidget/window.cpp 16 - - We set up the \uicontrol {Weekday Color} and \uicontrol {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 \uicontrol {Header Text Format} combobox lets the user change the - text format (bold, italic, or plain) used for horizontal and - vertical headers. The \uicontrol {First Friday in blue} and \uicontrol {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 \uicontrol {First Friday in blue} and \uicontrol {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 \uicontrol {Weekday Color} - and \uicontrol {Weekend Color} comboboxes. - - \snippet examples/widgets/calendarwidget/window.cpp 1 - - When the user changes the \uicontrol {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 \uicontrol{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 \uicontrol {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 \uicontrol {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. -*/ |