examples/widgets/doc/src/calendar.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     \example richtext/calendar
  30     \title Calendar Example
  31
  32     \brief The Calendar example shows how to create rich text content and display it using
  33     a rich text editor.
  34
  35     \image calendar-example.png
  36
  37     Specifically, the example demonstrates the following:
  38
  39     \list
  40       \li Use of a text editor with a text document
  41       \li Insertion of tables and frames into a document
  42       \li Navigation within a table
  43       \li Insert text in different styles
  44     \endlist
  45
  46     The rich text editor used to display the document is used within a main window
  47     application.
  48
  49     \section1 MainWindow Class Definition
  50
  51     The \c MainWindow class provides a text editor widget and some controls to
  52     allow the user to change the month and year shown. The font size used for the
  53     text can also be adjusted.
  54
  55     \snippet richtext/calendar/mainwindow.h 0
  56
  57     The private \c insertCalendar() function performs most of the work, relying on
  58     the \c fontSize and \c selectedDate variables to write useful information to
  59     the \c editor.
  60
  61     \section1 MainWindow Class Implementation
  62
  63     The \c MainWindow constructor sets up the user interface and initializes
  64     variables used to generate a calendar for each month.
  65
  66     \snippet richtext/calendar/mainwindow.cpp 0
  67
  68     We begin by setting default values for the selected date that will be highlighted
  69     in the calendar and the font size to be used. Since we are using a QMainWindow
  70     for the user interface, we construct a widget for use as the central widget.
  71
  72     The user interface will include a line of controls above the generated calendar;
  73     we construct a label and a combobox to allow the month to be selected, and a
  74     spin box for the year. These widgets are configured to provide a reasonable range
  75     of values for the user to try:
  76
  77     \snippet richtext/calendar/mainwindow.cpp 1
  78
  79     We use the \c selectedDate object to obtain the current month and year, and we
  80     set these in the combobox and spin box:
  81
  82     The font size is displayed in a spin box which we restrict to a sensible range
  83     of values:
  84
  85     \snippet richtext/calendar/mainwindow.cpp 2
  86
  87     We construct an editor and use the \c insertCalendar() function to create
  88     a calendar for it. Each calendar is displayed in the same text editor; in
  89     this example we use a QTextBrowser since we do not allow the calendar to be
  90     edited.
  91
  92     The controls used to set the month, year, and font size will not have any
  93     effect on the appearance of the calendar unless we make some signal-slot
  94     connections:
  95
  96     \snippet richtext/calendar/mainwindow.cpp 3
  97
  98     The signals are connected to some simple slots in the \c MainWindow class
  99     which we will describe later.
 100
 101     We create layouts to manage the widgets we constructed:
 102
 103     \snippet richtext/calendar/mainwindow.cpp 4
 104
 105     Finally, the central widget is set for the window.
 106
 107     Each calendar is created for the editor by the \c insertCalendar() function
 108     which uses the date and font size, defined by the private \a selectedDate
 109     and \c fontSize variables, to produce a suitable plan for the specified
 110     month and year.
 111
 112     \snippet richtext/calendar/mainwindow.cpp 5
 113
 114     We begin by clearing the editor's rich text document, and obtain a text
 115     cursor from the editor that we will use to add content. We also create a
 116     QDate object based on the currently selected date.
 117
 118     The calendar is made up of a table with a gray background color that contains
 119     seven columns: one for each day of the week. It is placed in the center of the
 120     page with equal space to the left and right of it. All of these properties are
 121     set in a QTextTableFormat object:
 122
 123     \snippet richtext/calendar/mainwindow.cpp 6
 124
 125     Each cell in the table will be padded and spaced to make the text easier to
 126     read.
 127
 128     We want the columns to have equal widths, so we provide a vector containing
 129     percentage widths for each of them and set the constraints in the
 130     QTextTableFormat:
 131
 132     \snippet richtext/calendar/mainwindow.cpp 7
 133
 134     The constraints used for the column widths are only useful if the table has
 135     an appropriate number of columns. With the format for the table defined, we
 136     construct a new table with one row and seven columns at the current cursor
 137     position:
 138
 139     \snippet richtext/calendar/mainwindow.cpp 8
 140
 141     We only need one row to start with; more can be added as we need them. Using
 142     this approach means that we do not need to perform any date calculations
 143     until we add cells to the table.
 144
 145     When inserting objects into a document with the cursor's insertion functions,
 146     the cursor is automatically moved inside the newly inserted object. This means
 147     that we can immediately start modifying the table from within:
 148
 149     \snippet richtext/calendar/mainwindow.cpp 9
 150
 151     Since the table has an outer frame, we obtain the frame and its format so that
 152     we can customize it. After making the changes we want, we set the frame's format
 153     using the modified format object. We have given the table an outer border one
 154     pixel wide.
 155
 156     \snippet richtext/calendar/mainwindow.cpp 10
 157
 158     In a similar way, we obtain the cursor's current character format and
 159     create customized formats based on it.
 160
 161     We do not set the format on the cursor because this would change the default
 162     character format; instead, we use the customized formats explicitly when we
 163     insert text. The following loop inserts the days of the week into the table
 164     as bold text:
 165
 166     \snippet richtext/calendar/mainwindow.cpp 11
 167
 168     For each day of the week, we obtain an existing table cell in the first row
 169     (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since
 170     we start counting the days of the week at day 1 (Monday), we subtract 1 from
 171     \c weekDay to ensure that we obtain the cell for the correct column of the
 172     table.
 173
 174     Before text can be inserted into a cell, we must obtain a cursor with the
 175     correct position in the document. The cell provides a function for this
 176     purpose, and we use this cursor to insert text using the \c boldFormat
 177     character format that we created earlier:
 178
 179     \snippet richtext/calendar/mainwindow.cpp 12
 180
 181     Inserting text into document objects usually follows the same pattern.
 182     Each object can provide a new cursor that corresponds to the first valid
 183     position within itself, and this can be used to insert new content. We
 184     continue to use this pattern as we insert the days of the month into the
 185     table.
 186
 187     Since every month has more than seven days, we insert a single row to begin
 188     and add days until we reach the end of the month. If the current date is
 189     encountered, it is inserted with a special format (created earlier) that
 190     makes it stand out:
 191
 192     \snippet richtext/calendar/mainwindow.cpp 13
 193
 194     We add a new row to the table at the end of each week only if the next week
 195     falls within the currently selected month.
 196
 197     For each calendar that we create, we change the window title to reflect the
 198     currently selected month and year:
 199
 200     \snippet richtext/calendar/mainwindow.cpp 14
 201
 202     The \c insertCalendar() function relies on up-to-date values for the month,
 203     year, and font size. These are set in the following slots:
 204
 205     \snippet richtext/calendar/mainwindow.cpp 15
 206
 207     The \c setFontSize() function simply changes the private \c fontSize variable
 208     before updating the calendar.
 209
 210     \snippet richtext/calendar/mainwindow.cpp 16
 211
 212     The \c setMonth slot is called when the QComboBox used to select the month is
 213     updated. The value supplied is the currently selected row in the combobox.
 214     We add 1 to this value to obtain a valid month number, and create a new QDate
 215     based on the existing one. The calendar is then updated to use this new date.
 216
 217     \snippet richtext/calendar/mainwindow.cpp 17
 218
 219     The \c setYear() slot is called when the QDateTimeEdit used to select the
 220     year is updated. The value supplied is a QDate object; this makes
 221     the construction of a new value for \c selectedDate simple. We update the
 222     calendar afterwards to use this new date.
 223 */