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