1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example richtext/calendar

    44     \title Calendar Example

    45 

    46     The Calendar example shows how to create rich text content and display it using

    47     a rich text editor.

    48 

    49     \image calendar-example.png

    50 

    51     Specifically, the example demonstrates the following:

    52 

    53     \list

    54       \o Use of a text editor with a text document

    55       \o Insertion of tables and frames into a document

    56       \o Navigation within a table

    57       \o Insert text in different styles

    58     \endlist

    59 

    60     The rich text editor used to display the document is used within a main window

    61     application.

    62 

    63     \section1 MainWindow Class Definition

    64 

    65     The \c MainWindow class provides a text editor widget and some controls to

    66     allow the user to change the month and year shown. The font size used for the

    67     text can also be adjusted.

    68 

    69     \snippet examples/richtext/calendar/mainwindow.h 0

    70 

    71     The private \c insertCalendar() function performs most of the work, relying on

    72     the \c fontSize and \c selectedDate variables to write useful information to

    73     the \c editor.

    74 

    75     \section1 MainWindow Class Implementation

    76 

    77     The \c MainWindow constructor sets up the user interface and initializes

    78     variables used to generate a calendar for each month.

    79 

    80     \snippet examples/richtext/calendar/mainwindow.cpp 0

    81 

    82     We begin by setting default values for the selected date that will be highlighted

    83     in the calendar and the font size to be used. Since we are using a QMainWindow

    84     for the user interface, we construct a widget for use as the central widget.

    85 

    86     The user interface will include a line of controls above the generated calendar;

    87     we construct a label and a combobox to allow the month to be selected, and a

    88     spin box for the year. These widgets are configured to provide a reasonable range

    89     of values for the user to try:

    90 

    91     \snippet examples/richtext/calendar/mainwindow.cpp 1

    92 

    93     We use the \c selectedDate object to obtain the current month and year, and we

    94     set these in the combobox and spin box:

    95 

    96     The font size is displayed in a spin box which we restrict to a sensible range

    97     of values:

    98 

    99     \snippet examples/richtext/calendar/mainwindow.cpp 2

   100 

   101     We construct an editor and use the \c insertCalendar() function to create

   102     a calendar for it. Each calendar is displayed in the same text editor; in

   103     this example we use a QTextBrowser since we do not allow the calendar to be

   104     edited.

   105 

   106     The controls used to set the month, year, and font size will not have any

   107     effect on the appearance of the calendar unless we make some signal-slot

   108     connections:

   109 

   110     \snippet examples/richtext/calendar/mainwindow.cpp 3

   111 

   112     The signals are connected to some simple slots in the \c MainWindow class

   113     which we will describe later.

   114 

   115     We create layouts to manage the widgets we constructed:

   116 

   117     \snippet examples/richtext/calendar/mainwindow.cpp 4

   118 

   119     Finally, the central widget is set for the window.

   120 

   121     Each calendar is created for the editor by the \c insertCalendar() function

   122     which uses the date and font size, defined by the private \a selectedDate

   123     and \c fontSize variables, to produce a suitable plan for the specified

   124     month and year.

   125 

   126     \snippet examples/richtext/calendar/mainwindow.cpp 5

   127 

   128     We begin by clearing the editor's rich text document, and obtain a text

   129     cursor from the editor that we will use to add content. We also create a

   130     QDate object based on the currently selected date.

   131 

   132     The calendar is made up of a table with a gray background color that contains

   133     seven columns: one for each day of the week. It is placed in the center of the

   134     page with equal space to the left and right of it. All of these properties are

   135     set in a QTextTableFormat object:

   136 

   137     \snippet examples/richtext/calendar/mainwindow.cpp 6

   138 

   139     Each cell in the table will be padded and spaced to make the text easier to

   140     read.

   141 

   142     We want the columns to have equal widths, so we provide a vector containing

   143     percentage widths for each of them and set the constraints in the

   144     QTextTableFormat:

   145 

   146     \snippet examples/richtext/calendar/mainwindow.cpp 7

   147 

   148     The constraints used for the column widths are only useful if the table has

   149     an appropriate number of columns. With the format for the table defined, we

   150     construct a new table with one row and seven columns at the current cursor

   151     position:

   152 

   153     \snippet examples/richtext/calendar/mainwindow.cpp 8

   154 

   155     We only need one row to start with; more can be added as we need them. Using

   156     this approach means that we do not need to perform any date calculations

   157     until we add cells to the table.

   158 

   159     When inserting objects into a document with the cursor's insertion functions,

   160     the cursor is automatically moved inside the newly inserted object. This means

   161     that we can immediately start modifying the table from within:

   162 

   163     \snippet examples/richtext/calendar/mainwindow.cpp 9

   164 

   165     Since the table has an outer frame, we obtain the frame and its format so that

   166     we can customize it. After making the changes we want, we set the frame's format

   167     using the modified format object. We have given the table an outer border one

   168     pixel wide.

   169 

   170     \snippet examples/richtext/calendar/mainwindow.cpp 10

   171 

   172     In a similar way, we obtain the cursor's current character format and

   173     create customized formats based on it.

   174 

   175     We do not set the format on the cursor because this would change the default

   176     character format; instead, we use the customized formats explicitly when we

   177     insert text. The following loop inserts the days of the week into the table

   178     as bold text:

   179 

   180     \snippet examples/richtext/calendar/mainwindow.cpp 11

   181 

   182     For each day of the week, we obtain an existing table cell in the first row

   183     (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since

   184     we start counting the days of the week at day 1 (Monday), we subtract 1 from

   185     \c weekDay to ensure that we obtain the cell for the correct column of the

   186     table.

   187 

   188     Before text can be inserted into a cell, we must obtain a cursor with the

   189     correct position in the document. The cell provides a function for this

   190     purpose, and we use this cursor to insert text using the \c boldFormat

   191     character format that we created earlier:

   192 

   193     \snippet examples/richtext/calendar/mainwindow.cpp 12

   194 

   195     Inserting text into document objects usually follows the same pattern.

   196     Each object can provide a new cursor that corresponds to the first valid

   197     position within itself, and this can be used to insert new content. We

   198     continue to use this pattern as we insert the days of the month into the

   199     table.

   200 

   201     Since every month has more than seven days, we insert a single row to begin

   202     and add days until we reach the end of the month. If the current date is

   203     encountered, it is inserted with a special format (created earlier) that

   204     makes it stand out:

   205 

   206     \snippet examples/richtext/calendar/mainwindow.cpp 13

   207 

   208     We add a new row to the table at the end of each week only if the next week

   209     falls within the currently selected month.

   210 

   211     For each calendar that we create, we change the window title to reflect the

   212     currently selected month and year:

   213 

   214     \snippet examples/richtext/calendar/mainwindow.cpp 14

   215 

   216     The \c insertCalendar() function relies on up-to-date values for the month,

   217     year, and font size. These are set in the following slots:

   218 

   219     \snippet examples/richtext/calendar/mainwindow.cpp 15

   220 

   221     The \c setFontSize() function simply changes the private \c fontSize variable

   222     before updating the calendar.

   223 

   224     \snippet examples/richtext/calendar/mainwindow.cpp 16

   225 

   226     The \c setMonth slot is called when the QComboBox used to select the month is

   227     updated. The value supplied is the currently selected row in the combobox.

   228     We add 1 to this value to obtain a valid month number, and create a new QDate

   229     based on the existing one. The calendar is then updated to use this new date.

   230 

   231     \snippet examples/richtext/calendar/mainwindow.cpp 17

   232 

   233     The \c setYear() slot is called when the QDateTimeEdit used to select the

   234     year is updated. The value supplied is a QDate object; this makes

   235     the construction of a new value for \c selectedDate simple. We update the

   236     calendar afterwards to use this new date.

   237 */