summaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorGabriel de Dietrich <gabriel.dietrich-de@nokia.com>2012-08-17 13:23:19 +0200
committerQt by Nokia <qt-info@nokia.com>2012-08-20 12:20:55 +0200
commit806dda08d685bc5f9ed71dfe8b61f21848d48066 (patch)
treea63533a1c4a335ae17adc105abb0ae4e62e2f26e /doc/src
parent9f942014e31842b512c3198de035d041c59f54a9 (diff)
Moving .qdoc files under examples/widgets/doc
Updated those .qdoc files to refer to the new relative examples emplacement. Images and snippets to be moved later. Also grouped all widgets related examples under widgets. Change-Id: Ib29696e2d8948524537f53e8dda88f9ee26a597f Reviewed-by: J-P Nurmi <j-p.nurmi@nokia.com>
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/examples/addressbook.qdoc442
-rw-r--r--doc/src/examples/affine.qdoc48
-rw-r--r--doc/src/examples/analogclock.qdoc154
-rw-r--r--doc/src/examples/animatedtiles.qdoc36
-rw-r--r--doc/src/examples/appchooser.qdoc38
-rw-r--r--doc/src/examples/application.qdoc396
-rw-r--r--doc/src/examples/basicdrawing.qdoc454
-rw-r--r--doc/src/examples/basicgraphicslayouts.qdoc164
-rw-r--r--doc/src/examples/basiclayouts.qdoc190
-rw-r--r--doc/src/examples/basicsortfiltermodel.qdoc37
-rw-r--r--doc/src/examples/blurpicker.qdoc33
-rw-r--r--doc/src/examples/borderlayout.qdoc36
-rw-r--r--doc/src/examples/boxes.qdoc49
-rw-r--r--doc/src/examples/calculator.qdoc375
-rw-r--r--doc/src/examples/calendar.qdoc223
-rw-r--r--doc/src/examples/calendarwidget.qdoc291
-rw-r--r--doc/src/examples/charactermap.qdoc274
-rw-r--r--doc/src/examples/chart.qdoc82
-rw-r--r--doc/src/examples/chip.qdoc38
-rw-r--r--doc/src/examples/classwizard.qdoc190
-rw-r--r--doc/src/examples/codeeditor.qdoc197
-rw-r--r--doc/src/examples/coloreditorfactory.qdoc155
-rw-r--r--doc/src/examples/combowidgetmapper.qdoc167
-rw-r--r--doc/src/examples/composition.qdoc44
-rw-r--r--doc/src/examples/concentriccircles.qdoc231
-rw-r--r--doc/src/examples/configdialog.qdoc36
-rw-r--r--doc/src/examples/customsortfiltermodel.qdoc289
-rw-r--r--doc/src/examples/deform.qdoc51
-rw-r--r--doc/src/examples/diagramscene.qdoc834
-rw-r--r--doc/src/examples/digitalclock.qdoc74
-rw-r--r--doc/src/examples/dirview.qdoc36
-rw-r--r--doc/src/examples/dockwidgets.qdoc163
-rw-r--r--doc/src/examples/dragdroprobot.qdoc365
-rw-r--r--doc/src/examples/dynamiclayouts.qdoc34
-rw-r--r--doc/src/examples/easing.qdoc37
-rw-r--r--doc/src/examples/editabletreemodel.qdoc446
-rw-r--r--doc/src/examples/elasticnodes.qdoc430
-rw-r--r--doc/src/examples/elidedlabel.qdoc162
-rw-r--r--doc/src/examples/embeddeddialogs.qdoc37
-rw-r--r--doc/src/examples/eventtransitions.qdoc72
-rw-r--r--doc/src/examples/extension.qdoc138
-rw-r--r--doc/src/examples/factorial.qdoc88
-rw-r--r--doc/src/examples/fademessage.qdoc37
-rw-r--r--doc/src/examples/fetchmore.qdoc111
-rw-r--r--doc/src/examples/findfiles.qdoc249
-rw-r--r--doc/src/examples/flowlayout.qdoc145
-rw-r--r--doc/src/examples/fontsampler.qdoc35
-rw-r--r--doc/src/examples/frozencolumn.qdoc133
-rw-r--r--doc/src/examples/gradients.qdoc55
-rw-r--r--doc/src/examples/groupbox.qdoc140
-rw-r--r--doc/src/examples/icons.qdoc780
-rw-r--r--doc/src/examples/imagecomposition.qdoc165
-rw-r--r--doc/src/examples/imageviewer.qdoc326
-rw-r--r--doc/src/examples/interview.qdoc37
-rw-r--r--doc/src/examples/licensewizard.qdoc218
-rw-r--r--doc/src/examples/lighting.qdoc33
-rw-r--r--doc/src/examples/lineedits.qdoc161
-rw-r--r--doc/src/examples/maemovibration.qdoc164
-rw-r--r--doc/src/examples/mainwindow.qdoc36
-rw-r--r--doc/src/examples/mdi.qdoc37
-rw-r--r--doc/src/examples/menus.qdoc218
-rw-r--r--doc/src/examples/moveblocks.qdoc214
-rw-r--r--doc/src/examples/movie.qdoc39
-rw-r--r--doc/src/examples/orderform.qdoc364
-rw-r--r--doc/src/examples/padnavigator.qdoc583
-rw-r--r--doc/src/examples/painterpaths.qdoc418
-rw-r--r--doc/src/examples/pathstroke.qdoc47
-rw-r--r--doc/src/examples/pingpong.qdoc93
-rw-r--r--doc/src/examples/pixelator.qdoc255
-rw-r--r--doc/src/examples/recentfiles.qdoc36
-rw-r--r--doc/src/examples/rogue.qdoc208
-rw-r--r--doc/src/examples/screenshot.qdoc247
-rw-r--r--doc/src/examples/scribble.qdoc417
-rw-r--r--doc/src/examples/sdi.qdoc36
-rw-r--r--doc/src/examples/shapedclock.qdoc131
-rw-r--r--doc/src/examples/simpledommodel.qdoc280
-rw-r--r--doc/src/examples/simpletreemodel.qdoc333
-rw-r--r--doc/src/examples/simplewidgetmapper.qdoc125
-rw-r--r--doc/src/examples/sipdialog.qdoc127
-rw-r--r--doc/src/examples/sliders.qdoc255
-rw-r--r--doc/src/examples/spinboxdelegate.qdoc141
-rw-r--r--doc/src/examples/spinboxes.qdoc191
-rw-r--r--doc/src/examples/spreadsheet.qdoc37
-rw-r--r--doc/src/examples/standarddialogs.qdoc35
-rw-r--r--doc/src/examples/stardelegate.qdoc296
-rw-r--r--doc/src/examples/states.qdoc36
-rw-r--r--doc/src/examples/stickman.qdoc102
-rw-r--r--doc/src/examples/styles.qdoc472
-rw-r--r--doc/src/examples/stylesheet.qdoc36
-rw-r--r--doc/src/examples/sub-attaq.qdoc40
-rw-r--r--doc/src/examples/syntaxhighlighter.qdoc252
-rw-r--r--doc/src/examples/tabdialog.qdoc134
-rw-r--r--doc/src/examples/tablet.qdoc369
-rw-r--r--doc/src/examples/tetrix.qdoc431
-rw-r--r--doc/src/examples/textedit.qdoc36
-rw-r--r--doc/src/examples/tooltips.qdoc394
-rw-r--r--doc/src/examples/trafficlight.qdoc85
-rw-r--r--doc/src/examples/transformations.qdoc371
-rw-r--r--doc/src/examples/trivialwizard.qdoc82
-rw-r--r--doc/src/examples/twowaybutton.qdoc68
-rw-r--r--doc/src/examples/wiggly.qdoc167
-rw-r--r--doc/src/examples/windowflags.qdoc216
102 files changed, 0 insertions, 18915 deletions
diff --git a/doc/src/examples/addressbook.qdoc b/doc/src/examples/addressbook.qdoc
deleted file mode 100644
index 9b4ede5775..0000000000
--- a/doc/src/examples/addressbook.qdoc
+++ /dev/null
@@ -1,442 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/addressbook
- \title Address Book Example
-
- The address book example shows how to use proxy models to display
- different views onto data from a single model.
-
- \image addressbook-example.png Screenshot of the Address Book example
-
- This example provides an address book that allows contacts to be
- grouped alphabetically into 9 groups: ABC, DEF, GHI, ... , VW,
- ..., XYZ. This is achieved by using multiple views on the same
- model, each of which is filtered using an instance of the
- QSortFilterProxyModel class.
-
-
- \section1 Overview
-
- The address book contains 5 classes: \c MainWindow,
- \c AddressWidget, \c TableModel, \c NewAddressTab and
- \c AddDialog. The \c MainWindow class uses \c AddressWidget as
- its central widget and provides \uicontrol File and \uicontrol Tools menus.
-
- \image addressbook-classes.png Diagram for Address Book Example
-
- The \c AddressWidget class is a QTabWidget subclass that is used
- to manipulate the 10 tabs displayed in the example: the 9
- alphabet group tabs and an instance of \c NewAddressTab.
- The \c NewAddressTab class is a subclass of QWidget that
- is only used whenever the address book is empty, prompting the
- user to add some contacts. \c AddressWidget also interacts with
- an instance of \c TableModel to add, edit and remove entries to
- the address book.
-
- \c TableModel is a subclass of QAbstractTableModel that provides
- the standard model/view API to access data. It also holds a
- QList of \l{QPair}s corresponding to the contacts added.
- However, this data is not all visible in a single tab. Instead,
- QTableView is used to provide 9 different views of the same
- data, according to the alphabet groups.
-
- QSortFilterProxyModel is the class responsible for filtering
- the contacts for each group of contacts. Each proxy model uses
- a QRegExp to filter out contacts that do not belong in the
- corresponding alphabetical group. The \c AddDialog class is
- used to obtain information from the user for the address book.
- This QDialog subclass is instantiated by \c NewAddressTab to
- add contacts, and by \c AddressWidget to add and edit contacts.
-
- We begin by looking at the \c TableModel implementation.
-
-
- \section1 TableModel Class Definition
-
- The \c TableModel class provides standard API to access data in
- its QList of \l{QPair}s by subclassing QAbstractTableModel. The
- basic functions that must be implemented in order to do so are:
- \c rowCount(), \c columnCount(), \c data(), \c headerData().
- For TableModel to be editable, it has to provide implementations
- \c insertRows(), \c removeRows(), \c setData() and \c flags()
- functions.
-
- \snippet itemviews/addressbook/tablemodel.h 0
-
- Two constructors are used, a default constructor which uses
- \c TableModel's own \c {QList<QPair<QString, QString>>} and one
- that takes \c {QList<QPair<QString, QString>} as an argument,
- for convenience.
-
-
- \section1 TableModel Class Implementation
-
- We implement the two constructors as defined in the header file.
- The second constructor initializes the list of pairs in the
- model, with the parameter value.
-
- \snippet itemviews/addressbook/tablemodel.cpp 0
-
- The \c rowCount() and \c columnCount() functions return the
- dimensions of the model. Whereas, \c rowCount()'s value will vary
- depending on the number of contacts added to the address book,
- \c columnCount()'s value is always 2 because we only need space
- for the \b Name and \b Address columns.
-
- \note The \c Q_UNUSED() macro prevents the compiler from
- generating warnings regarding unused parameters.
-
- \snippet itemviews/addressbook/tablemodel.cpp 1
-
- The \c data() function returns either a \b Name or
- \b {Address}, based on the contents of the model index
- supplied. The row number stored in the model index is used to
- reference an item in the list of pairs. Selection is handled
- by the QItemSelectionModel, which will be explained with
- \c AddressWidget.
-
- \snippet itemviews/addressbook/tablemodel.cpp 2
-
- The \c headerData() function displays the table's header,
- \b Name and \b Address. If you require numbered entries
- for your address book, you can use a vertical header which we
- have hidden in this example (see the \c AddressWidget
- implementation).
-
- \snippet itemviews/addressbook/tablemodel.cpp 3
-
- The \c insertRows() function is called before new data is added,
- otherwise the data will not be displayed. The
- \c beginInsertRows() and \c endInsertRows() functions are called
- to ensure all connected views are aware of the changes.
-
- \snippet itemviews/addressbook/tablemodel.cpp 4
-
- The \c removeRows() function is called to remove data. Again,
- \l{QAbstractItemModel::}{beginRemoveRows()} and
- \l{QAbstractItemModel::}{endRemoveRows()} are called to ensure
- all connected views are aware of the changes.
-
- \snippet itemviews/addressbook/tablemodel.cpp 5
-
- The \c setData() function is the function that inserts data into
- the table, item by item and not row by row. This means that to
- fill a row in the address book, \c setData() must be called
- twice, as each row has 2 columns. It is important to emit the
- \l{QAbstractItemModel::}{dataChanged()} signal as it tells all
- connected views to update their displays.
-
- \snippet itemviews/addressbook/tablemodel.cpp 6
-
- The \c flags() function returns the item flags for the given
- index.
-
- \snippet itemviews/addressbook/tablemodel.cpp 7
-
- We set the Qt::ItemIsEditable flag because we want to allow the
- \c TableModel to be edited. Although for this example we don't
- use the editing features of the QTableView object, we enable
- them here so that we can reuse the model in other programs.
-
- The last function in \c {TableModel}, \c getList() returns the
- QList<QPair<QString, QString>> object that holds all the
- contacts in the address book. We use this function later to
- obtain the list of contacts to check for existing entries, write
- the contacts to a file and read them back. Further explanation is
- given with \c AddressWidget.
-
- \snippet itemviews/addressbook/tablemodel.cpp 8
-
-
- \section1 AddressWidget Class Definition
-
- The \c AddressWidget class is technically the main class
- involved in this example as it provides functions to add, edit
- and remove contacts, to save the contacts to a file and to load
- them from a file.
-
- \snippet itemviews/addressbook/addresswidget.h 0
-
- \c AddressWidget extends QTabWidget in order to hold 10 tabs
- (\c NewAddressTab and the 9 alphabet group tabs) and also
- manipulates \c table, the \c TableModel object, \c proxyModel,
- the QSortFilterProxyModel object that we use to filter the
- entries, and \c tableView, the QTableView object.
-
-
- \section1 AddressWidget Class Implementation
-
- The \c AddressWidget constructor accepts a parent widget and
- instantiates \c NewAddressTab, \c TableModel and
- QSortFilterProxyModel. The \c NewAddressTab object, which is
- used to indicate that the address book is empty, is added
- and the rest of the 9 tabs are set up with \c setupTabs().
-
- \snippet itemviews/addressbook/addresswidget.cpp 0
-
- The \c setupTabs() function is used to set up the 9 alphabet
- group tabs, table views and proxy models in
- \c AddressWidget. Each proxy model in turn is set to filter
- contact names according to the relevant alphabet group using a
- \l{Qt::CaseInsensitive}{case-insensitive} QRegExp object. The
- table views are also sorted in ascending order using the
- corresponding proxy model's \l{QSortFilterProxyModel::}{sort()}
- function.
-
- Each table view's \l{QTableView::}{selectionMode} is set to
- QAbstractItemView::SingleSelection and
- \l{QTableView::}{selectionBehavior} is set to
- QAbstractItemView::SelectRows, allowing the user to select
- all the items in one row at the same time. Each QTableView object
- is automatically given a QItemSelectionModel that keeps track
- of the selected indexes.
-
- \snippet itemviews/addressbook/addresswidget.cpp 1
-
- The QItemSelectionModel class provides a
- \l{QItemSelectionModel::selectionChanged()}{selectionChanged}
- signal that is connected to \c{AddressWidget}'s
- \c selectionChanged() signal. This signal to signal connection
- is necessary to enable the \uicontrol{Edit Entry...} and
- \uicontrol{Remove Entry} actions in \c MainWindow's Tools menu. This
- connection is further explained in \c MainWindow's
- implementation.
-
- Each table view in the address book is added as a tab to the
- QTabWidget with the relevant label, obtained from the QStringList
- of groups.
-
- \image addressbook-signals.png Signals and Slots Connections
-
- We provide 2 \c addEntry() functions: 1 which is intended to be
- used to accept user input, and the other which performs the actual
- task of adding new entries to the address book. We divide the
- responsibility of adding entries into two parts to allow
- \c newAddressTab to insert data without having to popup a dialog.
-
- The first \c addEntry() function is a slot connected to the
- \c MainWindow's \uicontrol{Add Entry...} action. This function creates an
- \c AddDialog object and then calls the second \c addEntry()
- function to actually add the contact to \c table.
-
- \snippet itemviews/addressbook/addresswidget.cpp 2
-
- Basic validation is done in the second \c addEntry() function to
- prevent duplicate entries in the address book. As mentioned with
- \c TableModel, this is part of the reason why we require the
- getter method \c getList().
-
- \snippet itemviews/addressbook/addresswidget.cpp 3
-
- If the model does not already contain an entry with the same name,
- we call \c setData() to insert the name and address into the
- first and second columns. Otherwise, we display a QMessageBox
- to inform the user.
-
- \note The \c newAddressTab is removed once a contact is added
- as the address book is no longer empty.
-
- Editing an entry is a way to update the contact's address only,
- as the example does not allow the user to change the name of an
- existing contact.
-
- Firstly, we obtain the active tab's QTableView object using
- QTabWidget::currentWidget(). Then we extract the
- \c selectionModel from the \c tableView to obtain the selected
- indexes.
-
- \snippet itemviews/addressbook/addresswidget.cpp 4a
-
- Next we extract data from the row the user intends to
- edit. This data is displayed in an instance of \c AddDialog
- with a different window title. The \c table is only
- updated if changes have been made to data in \c aDialog.
-
- \snippet itemviews/addressbook/addresswidget.cpp 4b
-
- \image addressbook-editdialog.png Screenshot of Dialog to Edit a Contact
-
- Entries are removed using the \c removeEntry() function.
- The selected row is removed by accessing it through the
- QItemSelectionModel object, \c selectionModel. The
- \c newAddressTab is re-added to the \c AddressWidget only if
- the user removes all the contacts in the address book.
-
- \snippet itemviews/addressbook/addresswidget.cpp 5
-
- The \c writeToFile() function is used to save a file containing
- all the contacts in the address book. The file is saved in a
- custom \c{.dat} format. The contents of the QList of \l{QPair}s
- are written to \c file using QDataStream. If the file cannot be
- opened, a QMessageBox is displayed with the related error message.
-
- \snippet itemviews/addressbook/addresswidget.cpp 6
-
- The \c readFromFile() function loads a file containing all the
- contacts in the address book, previously saved using
- \c writeToFile(). QDataStream is used to read the contents of a
- \c{.dat} file into a list of pairs and each of these is added
- using \c addEntry().
-
- \snippet itemviews/addressbook/addresswidget.cpp 7
-
-
- \section1 NewAddressTab Class Definition
-
- The \c NewAddressTab class provides an informative tab telling
- the user that the address book is empty. It appears and
- disappears according to the contents of the address book, as
- mentioned in \c{AddressWidget}'s implementation.
-
- \image addressbook-newaddresstab.png Screenshot of NewAddressTab
-
- The \c NewAddressTab class extends QWidget and contains a QLabel
- and QPushButton.
-
- \snippet itemviews/addressbook/newaddresstab.h 0
-
-
- \section1 NewAddressTab Class Implementation
-
- The constructor instantiates the \c addButton,
- \c descriptionLabel and connects the \c{addButton}'s signal to
- the \c{addEntry()} slot.
-
- \snippet itemviews/addressbook/newaddresstab.cpp 0
-
- The \c addEntry() function is similar to \c AddressWidget's
- \c addEntry() in the sense that both functions instantiate an
- \c AddDialog object. Data from the dialog is extracted and sent
- to \c AddressWidget's \c addEntry() slot by emitting the
- \c sendDetails() signal.
-
- \snippet itemviews/addressbook/newaddresstab.cpp 1
-
- \image signals-n-slots-aw-nat.png
-
-
- \section1 AddDialog Class Definition
-
- The \c AddDialog class extends QDialog and provides the user
- with a QLineEdit and a QTextEdit to input data into the
- address book.
-
- \snippet itemviews/addressbook/adddialog.h 0
-
- \image addressbook-adddialog.png
-
-
- \section1 AddDialog Class Implementation
-
- The \c AddDialog's constructor sets up the user interface,
- creating the necessary widgets and placing them into layouts.
-
- \snippet itemviews/addressbook/adddialog.cpp 0
-
- To give the dialog the desired behavior, we connect the \uicontrol OK
- and \uicontrol Cancel buttons to the dialog's \l{QDialog::}{accept()} and
- \l{QDialog::}{reject()} slots. Since the dialog only acts as a
- container for name and address information, we do not need to
- implement any other functions for it.
-
-
- \section1 MainWindow Class Definition
-
- The \c MainWindow class extends QMainWindow and implements the
- menus and actions necessary to manipulate the address book.
-
- \table
- \row \li \inlineimage addressbook-filemenu.png
- \li \inlineimage addressbook-toolsmenu.png
- \endtable
-
- \snippet itemviews/addressbook/mainwindow.h 0
-
- The \c MainWindow class uses an \c AddressWidget as its central
- widget and provides the File menu with \uicontrol Open, \uicontrol Close and
- \uicontrol Exit actions, as well as the \uicontrol Tools menu with
- \uicontrol{Add Entry...}, \uicontrol{Edit Entry...} and \uicontrol{Remove Entry}
- actions.
-
-
- \section1 MainWindow Class Implementation
-
- The constructor for \c MainWindow instantiates AddressWidget,
- sets it as its central widget and calls the \c createMenus()
- function.
-
- \snippet itemviews/addressbook/mainwindow.cpp 0
-
- The \c createMenus() function sets up the \uicontrol File and
- \uicontrol Tools menus, connecting the actions to their respective slots.
- Both the \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} actions are
- disabled by default as such actions cannot be carried out on an empty
- address book. They are only enabled when one or more contacts
- are added.
-
- \snippet itemviews/addressbook/mainwindow.cpp 1a
- \dots
- \codeline
- \snippet itemviews/addressbook/mainwindow.cpp 1b
-
- Apart from connecting all the actions' signals to their
- respective slots, we also connect \c AddressWidget's
- \c selectionChanged() signal to its \c updateActions() slot.
-
- The \c openFile() function allows the user to choose a file with
- the \l{QFileDialog::getOpenFileName()}{open file dialog}. The chosen
- file has to be a custom \c{.dat} file that contains address book
- contacts. This function is a slot connected to \c openAct in the
- \uicontrol File menu.
-
- \snippet itemviews/addressbook/mainwindow.cpp 2
-
- The \c saveFile() function allows the user to save a file with
- the \l{QFileDialog::getSaveFileName()}{save file dialog}. This function
- is a slot connected to \c saveAct in the \uicontrol File menu.
-
- \snippet itemviews/addressbook/mainwindow.cpp 3
-
- The \c updateActions() function enables and disables
- \uicontrol{Edit Entry...} and \uicontrol{Remove Entry} depending on the contents of
- the address book. If the address book is empty, these actions
- are disabled; otherwise, they are enabled. This function is a slot
- is connected to the \c AddressWidget's \c selectionChanged()
- signal.
-
- \snippet itemviews/addressbook/mainwindow.cpp 4
-
-
- \section1 main() Function
-
- The main function for the address book instantiates QApplication
- and opens a \c MainWindow before running the event loop.
-
- \snippet itemviews/addressbook/main.cpp 0
-*/
diff --git a/doc/src/examples/affine.qdoc b/doc/src/examples/affine.qdoc
deleted file mode 100644
index c69794d511..0000000000
--- a/doc/src/examples/affine.qdoc
+++ /dev/null
@@ -1,48 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/affine
- \title Affine Transformations
-
- In this example we show Qt's ability to perform affine transformations
- on painting operations.
-
- \image affine-demo.png
-
- Transformations can be performed on any kind of graphics drawn using QPainter.
- The transformations used to display the vector graphics, images, and text can be adjusted
- in the following ways:
-
- \list
- \li Dragging the red circle in the centre of each drawing moves it to a new position.
- \li Dragging the displaced red circle causes the current drawing to be rotated about the
- central circle. Rotation can also be controlled with the \uicontrol Rotate slider.
- \li Scaling is controlled with the \uicontrol Scale slider.
- \li Each drawing can be sheared with the \uicontrol Shear slider.
- \endlist
-*/
diff --git a/doc/src/examples/analogclock.qdoc b/doc/src/examples/analogclock.qdoc
deleted file mode 100644
index 4385da07b6..0000000000
--- a/doc/src/examples/analogclock.qdoc
+++ /dev/null
@@ -1,154 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/analogclock
- \title Analog Clock Example
-
- The Analog Clock example shows how to draw the contents of a custom
- widget.
-
- \image analogclock-example.png Screenshot of the Analog Clock example
-
- This example also demonstrates how the transformation and scaling
- features of QPainter can be used to make drawing custom widgets
- easier.
-
- \section1 AnalogClock Class Definition
-
- The \c AnalogClock class provides a clock widget with hour and minute
- hands that is automatically updated every few seconds.
- We subclass \l QWidget and reimplement the standard
- \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face:
-
- \snippet examples/widgets/analogclock/analogclock.h 0
-
- \section1 AnalogClock Class Implementation
-
- \snippet examples/widgets/analogclock/analogclock.cpp 1
-
- When the widget is constructed, we set up a one-second timer to
- keep track of the current time, and we connect it to the standard
- \l{QWidget::update()}{update()} slot so that the clock face is
- updated when the timer emits the \l{QTimer::timeout()}{timeout()}
- signal.
-
- Finally, we resize the widget so that it is displayed at a
- reasonable size.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 8
- \snippet examples/widgets/analogclock/analogclock.cpp 10
-
- The \c paintEvent() function is called whenever the widget's
- contents need to be updated. This happens when the widget is
- first shown, and when it is covered then exposed, but it is also
- executed when the widget's \l{QWidget::update()}{update()} slot
- is called. Since we connected the timer's
- \l{QTimer::timeout()}{timeout()} signal to this slot, it will be
- called at least once every five seconds.
-
- Before we set up the painter and draw the clock, we first define
- two lists of \l {QPoint}s and two \l{QColor}s that will be used
- for the hour and minute hands. The minute hand's color has an
- alpha component of 191, meaning that it's 75% opaque.
-
- We also determine the length of the widget's shortest side so that we
- can fit the clock face inside the widget. It is also useful to determine
- the current time before we start drawing.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 11
- \snippet examples/widgets/analogclock/analogclock.cpp 12
- \snippet examples/widgets/analogclock/analogclock.cpp 13
- \snippet examples/widgets/analogclock/analogclock.cpp 14
-
- The contents of custom widgets are drawn with a QPainter.
- Painters can be used to draw on any QPaintDevice, but they are
- usually used with widgets, so we pass the widget instance to the
- painter's constructor.
-
- We call QPainter::setRenderHint() with QPainter::Antialiasing to
- turn on antialiasing. This makes drawing of diagonal lines much
- smoother.
-
- The translation moves the origin to the center of the widget, and
- the scale operation ensures that the following drawing operations
- are scaled to fit within the widget. We use a scale factor that
- let's us use x and y coordinates between -100 and 100, and that
- ensures that these lie within the length of the widget's shortest
- side.
-
- To make our code simpler, we will draw a fixed size clock face that will
- be positioned and scaled so that it lies in the center of the widget.
-
- The painter takes care of all the transformations made during the
- paint event, and ensures that everything is drawn correctly. Letting
- the painter handle transformations is often easier than performing
- manual calculations just to draw the contents of a custom widget.
-
- \image analogclock-viewport.png
-
- We draw the hour hand first, using a formula that rotates the coordinate
- system counterclockwise by a number of degrees determined by the current
- hour and minute. This means that the hand will be shown rotated clockwise
- by the required amount.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 15
- \snippet examples/widgets/analogclock/analogclock.cpp 16
-
- We set the pen to be Qt::NoPen because we don't want any outline,
- and we use a solid brush with the color appropriate for
- displaying hours. Brushes are used when filling in polygons and
- other geometric shapes.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 17
- \snippet examples/widgets/analogclock/analogclock.cpp 19
-
- We save and restore the transformation matrix before and after the
- rotation because we want to place the minute hand without having to
- take into account any previous rotations.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 20
- \codeline
- \snippet examples/widgets/analogclock/analogclock.cpp 21
-
- We draw markers around the edge of the clock for each hour. We
- draw each marker then rotate the coordinate system so that the
- painter is ready for the next one.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 22
- \snippet examples/widgets/analogclock/analogclock.cpp 23
-
- The minute hand is rotated in a similar way to the hour hand.
-
- \snippet examples/widgets/analogclock/analogclock.cpp 25
- \codeline
- \snippet examples/widgets/analogclock/analogclock.cpp 26
-
- Again, we draw markers around the edge of the clock, but this
- time to indicate minutes. We skip multiples of 5 to avoid drawing
- minute markers on top of hour markers.
-*/
diff --git a/doc/src/examples/animatedtiles.qdoc b/doc/src/examples/animatedtiles.qdoc
deleted file mode 100644
index 4fe25388cf..0000000000
--- a/doc/src/examples/animatedtiles.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example animation/animatedtiles
- \title Animated Tiles Example
-
- The Animated Tiles example animates items in a graphics scene.
-
- \image animatedtiles-example.png
-*/
-
diff --git a/doc/src/examples/appchooser.qdoc b/doc/src/examples/appchooser.qdoc
deleted file mode 100644
index 092db7c29e..0000000000
--- a/doc/src/examples/appchooser.qdoc
+++ /dev/null
@@ -1,38 +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$
-**
-****************************************************************************/
-
-/*!
- \example animation/appchooser
- \title Application Chooser Example
-
- The Application Chooser example shows how to use the Qt state
- machine and the animation framework to select between
- applications.
-
- \image appchooser-example.png
-
-*/
diff --git a/doc/src/examples/application.qdoc b/doc/src/examples/application.qdoc
deleted file mode 100644
index 9cfdc08134..0000000000
--- a/doc/src/examples/application.qdoc
+++ /dev/null
@@ -1,396 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/application
- \title Application Example
-
- The Application example shows how to implement a standard GUI
- application with menus, toolbars, and a status bar. The example
- itself is a simple text editor program built around QPlainTextEdit.
-
- \image application.png Screenshot of the Application example
-
- Nearly all of the code for the Application example is in the \c
- MainWindow class, which inherits QMainWindow. QMainWindow
- provides the framework for windows that have menus, toolbars,
- dock windows, and a status bar. The application provides
- \menu{File}, \menu{Edit}, and \menu{Help} entries in the menu
- bar, with the following popup menus:
-
- \image application-menus.png The Application example's menu system
-
- The status bar at the bottom of the main window shows a
- description of the menu item or toolbar button under the cursor.
-
- To keep the example simple, recently opened files aren't shown in
- the \menu{File} menu, even though this feature is desired in 90%
- of applications. The \l{mainwindows/recentfiles}{Recent Files}
- example shows how to implement this. Furthermore, this example
- can only load one file at a time. The \l{mainwindows/sdi}{SDI}
- and \l{mainwindows/mdi}{MDI} examples shows how to lift these
- restrictions.
-
- \section1 MainWindow Class Definition
-
- Here's the class definition:
-
- \snippet examples/mainwindows/application/mainwindow.h 0
-
- The public API is restricted to the constructor. In the \c
- protected section, we reimplement QWidget::closeEvent() to detect
- when the user attempts to close the window, and warn the user
- about unsaved changes. In the \c{private slots} section, we
- declare slots that correspond to menu entries, as well as a
- mysterious \c documentWasModified() slot. Finally, in the \c
- private section of the class, we have various members that will
- be explained in due time.
-
- \section1 MainWindow Class Implementation
-
- \snippet examples/mainwindows/application/mainwindow.cpp 0
-
- We start by including \c <QtGui>, a header file that contains the
- definition of all classes in the \l QtCore and \l QtGui
- libraries. This saves us from the trouble of having to include
- every class individually. We also include \c mainwindow.h.
-
- You might wonder why we don't include \c <QtGui> in \c
- mainwindow.h and be done with it. The reason is that including
- such a large header from another header file can rapidly degrade
- performances. Here, it wouldn't do any harm, but it's still
- generally a good idea to include only the header files that are
- strictly necessary from another header file.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 1
- \snippet examples/mainwindows/application/mainwindow.cpp 2
-
- In the constructor, we start by creating a QPlainTextEdit widget as a
- child of the main window (the \c this object). Then we call
- QMainWindow::setCentralWidget() to tell that this is going to be
- the widget that occupies the central area of the main window,
- between the toolbars and the status bar.
-
- Then we call \c createActions(), \c createMenus(), \c
- createToolBars(), and \c createStatusBar(), four private
- functions that set up the user interface. After that, we call \c
- readSettings() to restore the user's preferences.
-
- We establish a signal-slot connection between the QPlainTextEdit's
- document object and our \c documentWasModified() slot. Whenever
- the user modifies the text in the QPlainTextEdit, we want to update
- the title bar to show that the file was modified.
-
- At the end, we set the window title using the private
- \c setCurrentFile() function. We'll come back to this later.
-
- \target close event handler
- \snippet examples/mainwindows/application/mainwindow.cpp 3
- \snippet examples/mainwindows/application/mainwindow.cpp 4
-
- When the user attempts to close the window, we call the private
- function \c maybeSave() to give the user the possibility to save
- pending changes. The function returns true if the user wants the
- application to close; otherwise, it returns false. In the first
- case, we save the user's preferences to disk and accept the close
- event; in the second case, we ignore the close event, meaning
- that the application will stay up and running as if nothing
- happened.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 5
- \snippet examples/mainwindows/application/mainwindow.cpp 6
-
- The \c newFile() slot is invoked when the user selects
- \menu{File|New} from the menu. We call \c maybeSave() to save any
- pending changes and if the user accepts to go on, we clear the
- QPlainTextEdit and call the private function \c setCurrentFile() to
- update the window title and clear the
- \l{QWidget::windowModified}{windowModified} flag.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 7
- \snippet examples/mainwindows/application/mainwindow.cpp 8
-
- The \c open() slot is invoked when the user clicks
- \menu{File|Open}. We pop up a QFileDialog asking the user to
- choose a file. If the user chooses a file (i.e., \c fileName is
- not an empty string), we call the private function \c loadFile()
- to actually load the file.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 9
- \snippet examples/mainwindows/application/mainwindow.cpp 10
-
- The \c save() slot is invoked when the user clicks
- \menu{File|Save}. If the user hasn't provided a name for the file
- yet, we call \c saveAs(); otherwise, we call the private function
- \c saveFile() to actually save the file.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 11
- \snippet examples/mainwindows/application/mainwindow.cpp 12
-
- In \c saveAs(), we start by popping up a QFileDialog asking the
- user to provide a name. If the user clicks \uicontrol{Cancel}, the
- returned file name is empty, and we do nothing.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 13
- \snippet examples/mainwindows/application/mainwindow.cpp 14
-
- The application's About box is done using one statement, using
- the QMessageBox::about() static function and relying on its
- support for an HTML subset.
-
- The \l{QObject::tr()}{tr()} call around the literal string marks
- the string for translation. It is a good habit to call
- \l{QObject::tr()}{tr()} on all user-visible strings, in case you
- later decide to translate your application to other languages.
- The \l{Internationalization with Qt} overview covers
- \l{QObject::tr()}{tr()} in more detail.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 15
- \snippet examples/mainwindows/application/mainwindow.cpp 16
-
- The \c documentWasModified() slot is invoked each time the text
- in the QPlainTextEdit changes because of user edits. We call
- QWidget::setWindowModified() to make the title bar show that the
- file was modified. How this is done varies on each platform.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 17
- \snippet examples/mainwindows/application/mainwindow.cpp 18
- \dots
- \snippet examples/mainwindows/application/mainwindow.cpp 22
-
- The \c createActions() private function, which is called from the
- \c MainWindow constructor, creates \l{QAction}s. The code is very
- repetitive, so we show only the actions corresponding to
- \menu{File|New}, \menu{File|Open}, and \menu{Help|About Qt}.
-
- A QAction is an object that represents one user action, such as
- saving a file or invoking a dialog. An action can be put in a
- QMenu or a QToolBar, or both, or in any other widget that
- reimplements QWidget::actionEvent().
-
- An action has a text that is shown in the menu, an icon, a
- shortcut key, a tooltip, a status tip (shown in the status bar),
- a "What's This?" text, and more. It emits a
- \l{QAction::triggered()}{triggered()} signal whenever the user
- invokes the action (e.g., by clicking the associated menu item or
- toolbar button). We connect this signal to a slot that performs
- the actual action.
-
- The code above contains one more idiom that must be explained.
- For some of the actions, we specify an icon as a QIcon to the
- QAction constructor. The QIcon constructor takes the file name
- of an image that it tries to load. Here, the file name starts
- with \c{:}. Such file names aren't ordinary file names, but
- rather path in the executable's stored resources. We'll come back
- to this when we review the \c application.qrc file that's part of
- the project.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 23
- \snippet examples/mainwindows/application/mainwindow.cpp 24
-
- The \uicontrol{Edit|Cut} and \uicontrol{Edit|Copy} actions must be available
- only when the QPlainTextEdit contains selected text. We disable them
- by default and connect the QPlainTextEdit::copyAvailable() signal to
- the QAction::setEnabled() slot, ensuring that the actions are
- disabled when the text editor has no selection.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 25
- \snippet examples/mainwindows/application/mainwindow.cpp 27
-
- Creating actions isn't sufficient to make them available to the
- user; we must also add them to the menu system. This is what \c
- createMenus() does. We create a \menu{File}, an \menu{Edit}, and
- a \menu{Help} menu. QMainWindow::menuBar() lets us access the
- window's menu bar widget. We don't have to worry about creating
- the menu bar ourselves; the first time we call this function, the
- QMenuBar is created.
-
- Just before we create the \menu{Help} menu, we call
- QMenuBar::addSeparator(). This has no effect for most widget
- styles (e.g., Windows and Mac OS X styles), but for Motif-based
- styles this makes sure that \menu{Help} is pushed to the right
- side of the menu bar. Try running the application with various
- styles and see the results:
-
- \snippet doc/src/snippets/code/doc_src_examples_application.qdoc 0
-
- Let's now review the toolbars:
-
- \snippet examples/mainwindows/application/mainwindow.cpp 30
-
- Creating toolbars is very similar to creating menus. The same
- actions that we put in the menus can be reused in the toolbars.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 32
- \snippet examples/mainwindows/application/mainwindow.cpp 33
-
- QMainWindow::statusBar() returns a pointer to the main window's
- QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the
- widget is automatically created the first time the function is
- called.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 34
- \snippet examples/mainwindows/application/mainwindow.cpp 36
-
- The \c readSettings() function is called from the constructor to
- load the user's preferences and other application settings. The
- QSettings class provides a high-level interface for storing
- settings permanently on disk. On Windows, it uses the (in)famous
- Windows registry; on Mac OS X, it uses the native XML-based
- CFPreferences API; on Unix/X11, it uses text files.
-
- The QSettings constructor takes arguments that identify your
- company and the name of the product. This ensures that the
- settings for different applications are kept separately.
-
- We use QSettings::value() to extract the value of the "pos" and
- "size" settings. The second argument to QSettings::value() is
- optional and specifies a default value for the setting if there
- exists none. This value is used the first time the application is
- run.
-
- When restoring the position and size of a window, it's important
- to call QWidget::resize() before QWidget::move(). The reason why
- is given in the \l{Window Geometry} overview.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 37
- \snippet examples/mainwindows/application/mainwindow.cpp 39
-
- The \c writeSettings() function is called from \c closeEvent().
- Writing settings is similar to reading them, except simpler. The
- arguments to the QSettings constructor must be the same as in \c
- readSettings().
-
- \snippet examples/mainwindows/application/mainwindow.cpp 40
- \snippet examples/mainwindows/application/mainwindow.cpp 41
-
- The \c maybeSave() function is called to save pending changes. If
- there are pending changes, it pops up a QMessageBox giving the
- user to save the document. The options are QMessageBox::Yes,
- QMessageBox::No, and QMessageBox::Cancel. The \uicontrol{Yes} button is
- made the default button (the button that is invoked when the user
- presses \uicontrol{Return}) using the QMessageBox::Default flag; the
- \uicontrol{Cancel} button is made the escape button (the button that is
- invoked when the user presses \uicontrol{Esc}) using the
- QMessageBox::Escape flag.
-
- The \c maybeSave() function returns \c true in all cases, except
- when the user clicks \uicontrol{Cancel}. The caller must check the
- return value and stop whatever it was doing if the return value
- is \c false.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 42
- \snippet examples/mainwindows/application/mainwindow.cpp 43
-
- In \c loadFile(), we use QFile and QTextStream to read in the
- data. The QFile object provides access to the bytes stored in a
- file.
-
- We start by opening the file in read-only mode. The QFile::Text
- flag indicates that the file is a text file, not a binary file.
- On Unix and Mac OS X, this makes no difference, but on Windows,
- it ensures that the "\\r\\n" end-of-line sequence is converted to
- "\\n" when reading.
-
- If we successfully opened the file, we use a QTextStream object
- to read in the data. QTextStream automatically converts the 8-bit
- data into a Unicode QString and supports various encodings. If no
- encoding is specified, QTextStream assumes the file is written
- using the system's default 8-bit encoding (for example, Latin-1;
- see QTextCodec::codecForLocale() for details).
-
- Since the call to QTextStream::readAll() might take some time, we
- set the cursor to be Qt::WaitCursor for the entire application
- while it goes on.
-
- At the end, we call the private \c setCurrentFile() function,
- which we'll cover in a moment, and we display the string "File
- loaded" in the status bar for 2 seconds (2000 milliseconds).
-
- \snippet examples/mainwindows/application/mainwindow.cpp 44
- \snippet examples/mainwindows/application/mainwindow.cpp 45
-
- Saving a file is very similar to loading one. Here, the
- QFile::Text flag ensures that on Windows, "\\n" is converted into
- "\\r\\n" to conform to the Windows convension.
-
- \snippet examples/mainwindows/application/mainwindow.cpp 46
- \snippet examples/mainwindows/application/mainwindow.cpp 47
-
- The \c setCurrentFile() function is called to reset the state of
- a few variables when a file is loaded or saved, or when the user
- starts editing a new file (in which case \c fileName is empty).
- We update the \c curFile variable, clear the
- QTextDocument::modified flag and the associated \c
- QWidget:windowModified flag, and update the window title to
- contain the new file name (or \c untitled.txt).
-
- The \c strippedName() function call around \c curFile in the
- QWidget::setWindowTitle() call shortens the file name to exclude
- the path. Here's the function:
-
- \snippet examples/mainwindows/application/mainwindow.cpp 48
- \snippet examples/mainwindows/application/mainwindow.cpp 49
-
- \section1 The main() Function
-
- The \c main() function for this application is typical of
- applications that contain one main window:
-
- \snippet examples/mainwindows/application/main.cpp 0
-
- \section1 The Resource File
-
- As you will probably recall, for some of the actions, we
- specified icons with file names starting with \c{:} and mentioned
- that such file names aren't ordinary file names, but path in the
- executable's stored resources. These resources are compiled
-
- The resources associated with an application are specified in a
- \c .qrc file, an XML-based file format that lists files on the
- disk. Here's the \c application.qrc file that's used by the
- Application example:
-
- \quotefile mainwindows/application/application.qrc
-
- The \c .png files listed in the \c application.qrc file are files
- that are part of the Application example's source tree. Paths are
- relative to the directory where the \c application.qrc file is
- located (the \c mainwindows/application directory).
-
- The resource file must be mentioned in the \c application.pro
- file so that \c qmake knows about it:
-
- \snippet examples/mainwindows/application/application.pro 0
-
- \c qmake will produce make rules to generate a file called \c
- qrc_application.cpp that is linked into the application. This
- file contains all the data for the images and other resources as
- static C++ arrays of compressed binary data. See
- \l{resources.html}{The Qt Resource System} for more information
- about resources.
-*/
diff --git a/doc/src/examples/basicdrawing.qdoc b/doc/src/examples/basicdrawing.qdoc
deleted file mode 100644
index 1c4053f847..0000000000
--- a/doc/src/examples/basicdrawing.qdoc
+++ /dev/null
@@ -1,454 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/basicdrawing
- \title Basic Drawing Example
-
- The Basic Drawing example shows how to display basic graphics
- primitives in a variety of styles using the QPainter class.
-
- QPainter performs low-level painting on widgets and other paint
- devices. The class can draw everything from simple lines to
- complex shapes like pies and chords. It can also draw aligned text
- and pixmaps. Normally, it draws in a "natural" coordinate system,
- but it can in addition do view and world transformation.
-
- \image basicdrawing-example.png
-
- The example provides a render area, displaying the currently
- active shape, and lets the user manipulate the rendered shape and
- its appearance using the QPainter parameters: The user can change
- the active shape (\uicontrol Shape), and modify the QPainter's pen (\uicontrol
- {Pen Width}, \uicontrol {Pen Style}, \uicontrol {Pen Cap}, \uicontrol {Pen Join}),
- brush (\uicontrol {Brush Style}) and render hints (\uicontrol
- Antialiasing). In addition the user can rotate a shape (\uicontrol
- Transformations); behind the scenes we use QPainter's ability to
- manipulate the coordinate system to perform the rotation.
-
- The Basic Drawing example consists of two classes:
-
- \list
- \li \c RenderArea is a custom widget that renders multiple
- copies of the currently active shape.
- \li \c Window is the application's main window displaying a
- \c RenderArea widget in addition to several parameter widgets.
- \endlist
-
- First we will review the \c Window class, then we will take a
- look at the \c RenderArea class.
-
- \section1 Window Class Definition
-
- The Window class inherits QWidget, and is the application's main
- window displaying a \c RenderArea widget in addition to several
- parameter widgets.
-
- \snippet examples/painting/basicdrawing/window.h 0
-
- We declare the various widgets, and three private slots updating
- the \c RenderArea widget: The \c shapeChanged() slot updates the
- \c RenderArea widget when the user changes the currently active
- shape. We call the \c penChanged() slot when either of the
- QPainter's pen parameters changes. And the \c brushChanged() slot
- updates the \c RenderArea widget when the user changes the
- painter's brush style.
-
- \section1 Window Class Implementation
-
- In the constructor we create and initialize the various widgets
- appearing in the main application window.
-
- \snippet examples/painting/basicdrawing/window.cpp 1
-
- First we create the \c RenderArea widget that will render the
- currently active shape. Then we create the \uicontrol Shape combobox,
- and add the associated items (i.e. the different shapes a QPainter
- can draw).
-
- \snippet examples/painting/basicdrawing/window.cpp 2
-
- QPainter's pen is a QPen object; the QPen class defines how a
- painter should draw lines and outlines of shapes. A pen has
- several properties: Width, style, cap and join.
-
- A pen's width can be \e zero or greater, but the most common width
- is zero. Note that this doesn't mean 0 pixels, but implies that
- the shape is drawn as smoothly as possible although perhaps not
- mathematically correct.
-
- We create a QSpinBox for the \uicontrol {Pen Width} parameter.
-
- \snippet examples/painting/basicdrawing/window.cpp 3
-
- The pen style defines the line type. The default style is solid
- (Qt::SolidLine). Setting the style to none (Qt::NoPen) tells the
- painter to not draw lines or outlines. The pen cap defines how
- the end points of lines are drawn. And the pen join defines how
- two lines join when multiple connected lines are drawn. The cap
- and join only apply to lines with a width of 1 pixel or greater.
-
- We create \l {QComboBox}es for each of the \uicontrol {Pen Style}, \uicontrol
- {Pen Cap} and \uicontrol {Pen Join} parameters, and adds the associated
- items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and
- Qt::PenJoinStyle enums respectively).
-
- \snippet examples/painting/basicdrawing/window.cpp 4
-
- The QBrush class defines the fill pattern of shapes drawn by a
- QPainter. The default brush style is Qt::NoBrush. This style tells
- the painter to not fill shapes. The standard style for filling is
- Qt::SolidPattern.
-
- We create a QComboBox for the \uicontrol {Brush Style} parameter, and add
- the associated items (i.e. the values of the Qt::BrushStyle enum).
-
- \snippet examples/painting/basicdrawing/window.cpp 5
- \snippet examples/painting/basicdrawing/window.cpp 6
-
- Antialiasing is a feature that "smoothes" the pixels to create
- more even and less jagged lines, and can be applied using
- QPainter's render hints. QPainter::RenderHints are used to specify
- flags to QPainter that may or may not be respected by any given
- engine.
-
- We simply create a QCheckBox for the \uicontrol Antialiasing option.
-
- \snippet examples/painting/basicdrawing/window.cpp 7
-
- The \uicontrol Transformations option implies a manipulation of the
- coordinate system that will appear as if the rendered shape is
- rotated in three dimensions.
-
- We use the QPainter::translate(), QPainter::rotate() and
- QPainter::scale() functions to implement this feature represented
- in the main application window by a simple QCheckBox.
-
- \snippet examples/painting/basicdrawing/window.cpp 8
-
- Then we connect the parameter widgets with their associated slots
- using the static QObject::connect() function, ensuring that the \c
- RenderArea widget is updated whenever the user changes the shape,
- or any of the other parameters.
-
- \snippet examples/painting/basicdrawing/window.cpp 9
- \snippet examples/painting/basicdrawing/window.cpp 10
-
- Finally, we add the various widgets to a layout, and call the \c
- shapeChanged(), \c penChanged(), and \c brushChanged() slots to
- initialize the application. We also turn on antialiasing.
-
- \snippet examples/painting/basicdrawing/window.cpp 11
-
- The \c shapeChanged() slot is called whenever the user changes the
- currently active shape.
-
- First we retrieve the shape the user has chosen using the
- QComboBox::itemData() function. This function returns the data for
- the given role in the given index in the combobox. We use
- QComboBox::currentIndex() to retrieve the index of the shape, and
- the role is defined by the Qt::ItemDataRole enum; \c IdRole is an
- alias for Qt::UserRole.
-
- Note that Qt::UserRole is only the first role that can be used for
- application-specific purposes. If you need to store different data
- in the same index, you can use different roles by simply
- incrementing the value of Qt::UserRole, for example: 'Qt::UserRole
- + 1' and 'Qt::UserRole + 2'. However, it is a good programming
- practice to give each role their own name: 'myFirstRole =
- Qt::UserRole + 1' and 'mySecondRole = Qt::UserRole + 2'. Even
- though we only need a single role in this particular example, we
- add the following line of code to the beginning of the \c
- window.cpp file.
-
- \snippet examples/painting/basicdrawing/window.cpp 0
-
- The QComboBox::itemData() function returns the data as a QVariant,
- so we need to cast the data to \c RenderArea::Shape. If there is
- no data for the given role, the function returns
- QVariant::Invalid.
-
- In the end we call the \c RenderArea::setShape() slot to update
- the \c RenderArea widget.
-
- \snippet examples/painting/basicdrawing/window.cpp 12
-
- We call the \c penChanged() slot whenever the user changes any of
- the pen parameters. Again we use the QComboBox::itemData()
- function to retrieve the parameters, and then we call the \c
- RenderArea::setPen() slot to update the \c RenderArea widget.
-
- \snippet examples/painting/basicdrawing/window.cpp 13
-
- The brushChanged() slot is called whenever the user changes the
- brush parameter which we retrieve using the QComboBox::itemData()
- function as before.
-
- \snippet examples/painting/basicdrawing/window.cpp 14
-
- If the brush parameter is a gradient fill, special actions are
- required.
-
- The QGradient class is used in combination with QBrush to specify
- gradient fills. Qt currently supports three types of gradient
- fills: linear, radial and conical. Each of these is represented by
- a subclass of QGradient: QLinearGradient, QRadialGradient and
- QConicalGradient.
-
- So if the brush style is Qt::LinearGradientPattern, we first
- create a QLinearGradient object with interpolation area between
- the coordinates passed as arguments to the constructor. The
- positions are specified using logical coordinates. Then we set the
- gradient's colors using the QGradient::setColorAt() function. The
- colors is defined using stop points which are composed by a
- position (between 0 and 1) and a QColor. The set of stop points
- describes how the gradient area should be filled. A gradient can
- have an arbitrary number of stop points.
-
- In the end we call \c RenderArea::setBrush() slot to update the \c
- RenderArea widget's brush with the QLinearGradient object.
-
- \snippet examples/painting/basicdrawing/window.cpp 15
-
- A similar pattern of actions, as the one used for QLinearGradient,
- is used in the cases of Qt::RadialGradientPattern and
- Qt::ConicalGradientPattern.
-
- The only difference is the arguments passed to the constructor:
- Regarding the QRadialGradient constructor the first argument is
- the center, and the second the radial gradient's radius. The third
- argument is optional, but can be used to define the focal point of
- the gradient inside the circle (the default focal point is the
- circle center). Regarding the QConicalGradient constructor, the
- first argument specifies the center of the conical, and the second
- specifies the start angle of the interpolation.
-
- \snippet examples/painting/basicdrawing/window.cpp 16
-
- If the brush style is Qt::TexturePattern we create a QBrush from a
- QPixmap. Then we call \c RenderArea::setBrush() slot to update the
- \c RenderArea widget with the newly created brush.
-
- \snippet examples/painting/basicdrawing/window.cpp 17
-
- Otherwise we simply create a brush with the given style and a
- green color, and then call \c RenderArea::setBrush() slot to
- update the \c RenderArea widget with the newly created brush.
-
- \section1 RenderArea Class Definition
-
- The \c RenderArea class inherits QWidget, and renders multiple
- copies of the currently active shape using a QPainter.
-
- \snippet examples/painting/basicdrawing/renderarea.h 0
-
- First we define a public \c Shape enum to hold the different
- shapes that can be rendered by the widget (i.e the shapes that can
- be rendered by a QPainter). Then we reimplement the constructor as
- well as two of QWidget's public functions: \l
- {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l
- {QWidget::sizeHint()}{sizeHint()}.
-
- We also reimplement the QWidget::paintEvent() function to be able
- to draw the currently active shape according to the specified
- parameters.
-
- We declare several private slots: The \c setShape() slot changes
- the \c RenderArea's shape, the \c setPen() and \c setBrush() slots
- modify the widget's pen and brush, and the \c setAntialiased() and
- \c setTransformed() slots modify the widget's respective
- properties.
-
- \section1 RenderArea Class Implementation
-
- In the constructor we initialize some of the widget's variables.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 0
-
- We set its shape to be a \uicontrol Polygon, its antialiased property to
- be false and we load an image into the widget's pixmap
- variable. In the end we set the widget's background role, defining
- the brush from the widget's \l {QWidget::palette}{palette} that
- will be used to render the background. QPalette::Base is typically
- white.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 2
-
- The \c RenderArea inherits QWidget's \l
- {QWidget::sizeHint()}{sizeHint} property holding the recommended
- size for the widget. If the value of this property is an invalid
- size, no size is recommended.
-
- The default implementation of the QWidget::sizeHint() function
- returns an invalid size if there is no layout for the widget, and
- returns the layout's preferred size otherwise.
-
- Our reimplementation of the function returns a QSize with a 400
- pixels width and a 200 pixels height.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 1
-
- \c RenderArea also inherits QWidget's
- \l{QWidget::minimumSizeHint()}{minimumSizeHint} property holding
- the recommended minimum size for the widget. Again, if the value
- of this property is an invalid size, no size is recommended.
-
- The default implementation of QWidget::minimumSizeHint() returns
- an invalid size if there is no layout for the widget, and returns
- the layout's minimum size otherwise.
-
- Our reimplementation of the function returns a QSize with a 100
- pixels width and a 100 pixels height.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 3
- \codeline
- \snippet examples/painting/basicdrawing/renderarea.cpp 4
- \codeline
- \snippet examples/painting/basicdrawing/renderarea.cpp 5
-
- The public \c setShape(), \c setPen() and \c setBrush() slots are
- called whenever we want to modify a \c RenderArea widget's shape,
- pen or brush. We set the shape, pen or brush according to the
- slot parameter, and call QWidget::update() to make the changes
- visible in the \c RenderArea widget.
-
- The QWidget::update() slot does not cause an immediate
- repaint; instead it schedules a paint event for processing when Qt
- returns to the main event loop.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 6
- \codeline
- \snippet examples/painting/basicdrawing/renderarea.cpp 7
-
- With the \c setAntialiased() and \c setTransformed() slots we
- change the state of the properties according to the slot
- parameter, and call the QWidget::update() slot to make the changes
- visible in the \c RenderArea widget.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 8
-
- Then we reimplement the QWidget::paintEvent() function. The first
- thing we do is to create the graphical objects we will need to
- draw the various shapes.
-
- We create a vector of four \l {QPoint}s. We use this vector to
- render the \uicontrol Points, \uicontrol Polyline and \uicontrol Polygon
- shapes. Then we create a QRect, defining a rectangle in the plane,
- which we use as the bounding rectangle for all the shapes excluding
- the \uicontrol Path and the \uicontrol Pixmap.
-
- We also create a QPainterPath. The QPainterPath class provides a
- container for painting operations, enabling graphical shapes to be
- constructed and reused. A painter path is an object composed of a
- number of graphical building blocks, such as rectangles, ellipses,
- lines, and curves. For more information about the QPainterPath
- class, see the \l {painting/painterpaths}{Painter Paths}
- example. In this example, we create a painter path composed of one
- straight line and a Bezier curve.
-
- In addition we define a start angle and an arc length that we will
- use when drawing the \uicontrol Arc, \uicontrol Chord and \uicontrol Pie shapes.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 9
-
- We create a QPainter for the \c RenderArea widget, and set the
- painters pen and brush according to the \c RenderArea's pen and
- brush. If the \uicontrol Antialiasing parameter option is checked, we
- also set the painter's render hints. QPainter::Antialiasing
- indicates that the engine should antialias edges of primitives if
- possible.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 10
-
- Finally, we render the multiple copies of the \c RenderArea's
- shape. The number of copies is depending on the size of the \c
- RenderArea widget, and we calculate their positions using two \c
- for loops and the widgets height and width.
-
- For each copy we first save the current painter state (pushes the
- state onto a stack). Then we translate the coordinate system,
- using the QPainter::translate() function, to the position
- determined by the variables of the \c for loops. If we omit this
- translation of the coordinate system all the copies of the shape
- will be rendered on top of each other in the top left cormer of
- the \c RenderArea widget.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 11
-
- If the \uicontrol Transformations parameter option is checked, we do an
- additional translation of the coordinate system before we rotate
- the coordinate system 60 degrees clockwise using the
- QPainter::rotate() function and scale it down in size using the
- QPainter::scale() function. In the end we translate the coordinate
- system back to where it was before we rotated and scaled it.
-
- Now, when rendering the shape, it will appear as if it was rotated
- in three dimensions.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 12
-
- Next, we identify the \c RenderArea's shape, and render it using
- the associated QPainter drawing function:
-
- \list
- \li QPainter::drawLine(),
- \li QPainter::drawPoints(),
- \li QPainter::drawPolyline(),
- \li QPainter::drawPolygon(),
- \li QPainter::drawRect(),
- \li QPainter::drawRoundedRect(),
- \li QPainter::drawEllipse(),
- \li QPainter::drawArc(),
- \li QPainter::drawChord(),
- \li QPainter::drawPie(),
- \li QPainter::drawPath(),
- \li QPainter::drawText() or
- \li QPainter::drawPixmap()
- \endlist
-
- Before we started rendering, we saved the current painter state
- (pushes the state onto a stack). The rationale for this is that we
- calculate each shape copy's position relative to the same point in
- the coordinate system. When translating the coordinate system, we
- lose the knowledge of this point unless we save the current
- painter state \e before we start the translating process.
-
- \snippet examples/painting/basicdrawing/renderarea.cpp 13
-
- Then, when we are finished rendering a copy of the shape we can
- restore the original painter state, with its associated coordinate
- system, using the QPainter::restore() function. In this way we
- ensure that the next shape copy will be rendered in the correct
- position.
-
- We could translate the coordinate system back using
- QPainter::translate() instead of saving the painter state. But
- since we in addition to translating the coordinate system (when
- the \uicontrol Transformation parameter option is checked) both rotate
- and scale the coordinate system, the easiest solution is to save
- the current painter state.
-*/
diff --git a/doc/src/examples/basicgraphicslayouts.qdoc b/doc/src/examples/basicgraphicslayouts.qdoc
deleted file mode 100644
index b7023cf9ca..0000000000
--- a/doc/src/examples/basicgraphicslayouts.qdoc
+++ /dev/null
@@ -1,164 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/basicgraphicslayouts
- \title Basic Graphics Layouts Example
-
- The Basic Graphics Layouts example shows how to use the layout classes
- in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout.
- In addition to that it shows how to write your own custom layout item.
-
- \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example
-
- \section1 Window Class Definition
-
- The \c Window class is a subclass of QGraphicsWidget. It has a
- constructor with a QGraphicsWidget \a parent as its parameter.
-
- \snippet examples/graphicsview/basicgraphicslayouts/window.h 0
-
- \section1 Window Class Implementation
-
- The constructor of \c Window instantiates a QGraphicsLinearLayout object,
- \c windowLayout, with vertical orientation. We instantiate another
- QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout.
- Next, we create a \c LayoutItem object, \c item and add it to \c linear
- with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide
- \c item with a \l{QGraphicsLinearLayout::setStretchFactor()}
- {stretchFactor}.
-
- \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 0
-
- We repeat the process:
-
- \list
- \li create a new \c LayoutItem,
- \li add the item \c linear, and
- \li provide a stretch factor.
- \endlist
-
- \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 1
-
- We then add \c linear to \c windowLayout, nesting two
- QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we
- also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with
- some cells spanning to other rows.
-
- We create seven \c LayoutItem objects and place them into \c grid with
- the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code
- snippet below:
-
- \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 2
-
- The first item we add to \c grid is placed in the top left cell,
- spanning four rows. The next two items are placed in the second column,
- and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()}
- and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that
- they do not expand vertically. As a result, these items will not
- fit vertically in their cells. So, we specify that they should be
- vertically aligned in the center of the cell using Qt::AlignVCenter.
-
- Finally, \c grid itself is added to \c windowLayout. Unlike
- QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row
- and a column for its argument, specifying which cell the item should be
- positioned in. Also, if the \c rowSpan and \c columnSpan arguments
- are omitted, they will default to 1.
-
- Note that we do not specify a parent for each \c LayoutItem that we
- construct, as all these items will be added to \c windowLayout. When we
- add an item to a layout, it will be automatically reparented to the widget
- on which the layout is installed.
-
- \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 3
-
- Now that we have set up \c grid and added it to \c windowLayout, we
- install \c windowLayout onto the window object using
- QGraphicsWidget::setLayout() and we set the window title.
-
- \section1 LayoutItem Class Definition
-
- The \c LayoutItem class is a subclass of QGraphicsLayoutItem and
- QGraphicsItem. It has a constructor, a destructor, and some required
- reimplementations.
- Since it inherits QGraphicsLayoutItem it must reimplement
- {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and
- {QGraphicsLayoutItem::sizeHint()}{sizeHint()}.
- In addition to that it inherits QGraphicsItem, so it must reimplement
- {QGraphicsItem::boundingRect()}{boundingRect()} and
- {QGraphicsItem::paint()}{paint()}.
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.h 0
-
- The \c LayoutItem class also has a private instance of QPixmap, \c m_pix.
-
- \section1 LayoutItem Class Implementation
-
- In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the
- \c{block.png} image is loaded into it.
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 0
-
- We use the Q_UNUSED() macro to prevent the compiler from generating
- warnings regarding unused parameters.
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 1
-
- The idea behind the \c paint() function is to paint the
- background rect then paint a rect around the pixmap.
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 2
-
- The reimplementation of \l{QGraphicsItem::}{boundingRect()}
- will set the top left corner at (0,0), and the size of it will be
- the size of the layout items
- \l{QGraphicsLayoutItem::}{geometry()}. This is the area that
- we paint within.
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3
-
-
- The reimplementation of \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()}
- simply calls its baseclass implementation. However, since this will change
- the boundingRect we must also call
- \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}.
- Finally, we move the item according to \c geom.topLeft().
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 4
-
-
- Since we don't want the size of the item to be smaller than the pixmap, we
- must make sure that we return a size hint that is larger than \c m_pix.
- We also add some extra space around for borders that we will paint later.
- Alternatively, you could scale the pixmap to prevent the item from
- becoming smaller than the pixmap.
- The preferred size is the same as the minimum size hint, while we set
- maximum to be a large value
-
- \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 5
-
-*/ \ No newline at end of file
diff --git a/doc/src/examples/basiclayouts.qdoc b/doc/src/examples/basiclayouts.qdoc
deleted file mode 100644
index 37d9fcb70a..0000000000
--- a/doc/src/examples/basiclayouts.qdoc
+++ /dev/null
@@ -1,190 +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$
-**
-****************************************************************************/
-
-/*!
- \example layouts/basiclayouts
- \title Basic Layouts Example
-
- The Basic Layouts example shows how to use the standard layout
- managers that are available in Qt: QBoxLayout, QGridLayout and
- QFormLayout.
-
- \image basiclayouts-example.png Screenshot of the Basic Layouts example
-
- The QBoxLayout class lines up widgets horizontally or vertically.
- QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout.
- QGridLayout lays out widgets in cells by dividing the available space
- into rows and columns. QFormLayout, on the other hand, lays out its
- children in a two-column form with labels in the left column and
- input fields in the right column.
-
- \section1 Dialog Class Definition
-
- \snippet examples/layouts/basiclayouts/dialog.h 0
-
- The \c Dialog class inherits QDialog. It is a custom widget that
- displays its child widgets using the geometry managers:
- QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout.
-
- We declare four private functions to simplify the class
- constructor: The \c createMenu(), \c createHorizontalGroupBox(),
- \c createGridGroupBox() and \c createFormGroupBox() functions create
- several widgets that the example uses to demonstrate how the layout
- affects their appearances.
-
- \section1 Dialog Class Implementation
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 0
-
- In the constructor, we first use the \c createMenu() function to
- create and populate a menu bar and the \c createHorizontalGroupBox()
- function to create a group box containing four buttons with a
- horizontal layout. Next we use the \c createGridGroupBox() function
- to create a group box containing several line edits and a small text
- editor which are displayed in a grid layout. Finally, we use the
- \c createFormGroupBox() function to create a group box with
- three labels and three input fields: a line edit, a combo box and
- a spin box.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 1
-
- We also create a big text editor and a dialog button box. The
- QDialogButtonBox class is a widget that presents buttons in a
- layout that is appropriate to the current widget style. The
- preferred buttons can be specified as arguments to the
- constructor, using the QDialogButtonBox::StandardButtons enum.
-
- Note that we don't have to specify a parent for the widgets when
- we create them. The reason is that all the widgets we create here
- will be added to a layout, and when we add a widget to a layout,
- it is automatically reparented to the widget the layout is
- installed on.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 2
-
- The main layout is a QVBoxLayout object. QVBoxLayout is a
- convenience class for a box layout with vertical orientation.
-
- In general, the QBoxLayout class takes the space it gets (from its
- parent layout or from the parent widget), divides it up into a
- series of boxes, and makes each managed widget fill one box. If
- the QBoxLayout's orientation is Qt::Horizontal the boxes are
- placed in a row. If the orientation is Qt::Vertical, the boxes are
- placed in a column. The corresponding convenience classes are
- QHBoxLayout and QVBoxLayout, respectively.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 3
-
- When we call the QLayout::setMenuBar() function, the layout places
- the provided menu bar at the top of the parent widget, and outside
- the widget's \l {QWidget::contentsRect()}{content margins}. All
- child widgets are placed below the bottom edge of the menu bar.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 4
-
- We use the QBoxLayout::addWidget() function to add the widgets to
- the end of layout. Each widget will get at least its minimum size
- and at most its maximum size. It is possible to specify a stretch
- factor in the \l {QBoxLayout::addWidget()}{addWidget()} function,
- and any excess space is shared according to these stretch
- factors. If not specified, a widget's stretch factor is 0.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 5
-
- We install the main layout on the \c Dialog widget using the
- QWidget::setLayout() function, and all of the layout's widgets are
- automatically reparented to be children of the \c Dialog widget.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 6
-
- In the private \c createMenu() function we create a menu bar, and
- add a pull-down \uicontrol File menu containing an \uicontrol Exit option.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 7
-
- When we create the horizontal group box, we use a QHBoxLayout as
- the internal layout. We create the buttons we want to put in the
- group box, add them to the layout and install the layout on the
- group box.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 8
-
- In the \c createGridGroupBox() function we use a QGridLayout which
- lays out widgets in a grid. It takes the space made available to
- it (by its parent layout or by the parent widget), divides it up
- into rows and columns, and puts each widget it manages into the
- correct cell.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 9
-
- For each row in the grid we create a label and an associated line
- edit, and add them to the layout. The QGridLayout::addWidget()
- function differ from the corresponding function in QBoxLayout: It
- needs the row and column specifying the grid cell to put the
- widget in.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 10
-
- QGridLayout::addWidget() can in addition take arguments
- specifying the number of rows and columns the cell will be
- spanning. In this example, we create a small editor which spans
- three rows and one column.
-
- For both the QBoxLayout::addWidget() and QGridLayout::addWidget()
- functions it is also possible to add a last argument specifying
- the widget's alignment. By default it fills the whole cell. But we
- could, for example, align a widget with the right edge by
- specifying the alignment to be Qt::AlignRight.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 11
-
- Each column in a grid layout has a stretch factor. The stretch
- factor is set using QGridLayout::setColumnStretch() and determines
- how much of the available space the column will get over and above
- its necessary minimum.
-
- In this example, we set the stretch factors for columns 1 and 2.
- The stretch factor is relative to the other columns in this grid;
- columns with a higher stretch factor take more of the available
- space. So column 2 in our grid layout will get more of the
- available space than column 1, and column 0 will not grow at all
- since its stretch factor is 0 (the default).
-
- Columns and rows behave identically; there is an equivalent
- stretch factor for rows, as well as a QGridLayout::setRowStretch()
- function.
-
- \snippet examples/layouts/basiclayouts/dialog.cpp 12
-
- In the \c createFormGroupBox() function, we use a QFormLayout
- to neatly arrange objects into two columns - name and field.
- There are three QLabel objects for names with three
- corresponding input widgets as fields: a QLineEdit, a QComboBox
- and a QSpinBox. Unlike QBoxLayout::addWidget() and
- QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets
- to the layout.
-*/
diff --git a/doc/src/examples/basicsortfiltermodel.qdoc b/doc/src/examples/basicsortfiltermodel.qdoc
deleted file mode 100644
index 0ecf4a0629..0000000000
--- a/doc/src/examples/basicsortfiltermodel.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/basicsortfiltermodel
- \title Basic Sort/Filter Model Example
-
- The Basic Sort/Filter Model example illustrates how to use
- QSortFilterProxyModel to perform basic sorting and filtering.
-
- \image basicsortfiltermodel-example.png Screenshot of the Basic Sort/Filter Model Example
-
-*/
diff --git a/doc/src/examples/blurpicker.qdoc b/doc/src/examples/blurpicker.qdoc
deleted file mode 100644
index bd57acb061..0000000000
--- a/doc/src/examples/blurpicker.qdoc
+++ /dev/null
@@ -1,33 +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$
-**
-****************************************************************************/
-
-/*!
- \example effects/blurpicker
- \title Blur Picker Effect Example
-
- \image blurpickereffect-example.png
-*/
diff --git a/doc/src/examples/borderlayout.qdoc b/doc/src/examples/borderlayout.qdoc
deleted file mode 100644
index aaff2dda1d..0000000000
--- a/doc/src/examples/borderlayout.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example layouts/borderlayout
- \title Border Layout Example
-
- The Border Layout example shows how to create a custom layout that arranges
- child widgets according to a simple set of rules.
-
- \image borderlayout-example.png
-*/
diff --git a/doc/src/examples/boxes.qdoc b/doc/src/examples/boxes.qdoc
deleted file mode 100644
index aa34a61bc3..0000000000
--- a/doc/src/examples/boxes.qdoc
+++ /dev/null
@@ -1,49 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/boxes
- \title Boxes
-
- This demo shows Qt's ability to combine advanced OpenGL rendering with the
- the \l{Graphics View Framework}.
-
- \image boxes-demo.png
-
- Elements in the demo can be controlled using the mouse in the following
- ways:
- \list
- \li Dragging the mouse while pressing the left mouse button rotates the
- box in the center.
- \li Dragging the mouse while pressing the right mouse button rotates the
- satellite boxes.
- \li Scrolling the mouse wheel zooms in and out of the scene.
- \endlist
-
- The options pane can be used to fine-tune various parameters in the demo,
- including colors and pixel shaders.
-*/
diff --git a/doc/src/examples/calculator.qdoc b/doc/src/examples/calculator.qdoc
deleted file mode 100644
index 914b8c5299..0000000000
--- a/doc/src/examples/calculator.qdoc
+++ /dev/null
@@ -1,375 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/calculator
- \title Calculator Example
-
- The example shows how to use signals and slots to implement the
- functionality of a calculator widget, and how to use QGridLayout
- to place child widgets in a grid.
-
- \image calculator-example.png Screenshot of the Calculator example
-
- The example consists of two classes:
-
- \list
- \li \c Calculator is the calculator widget, with all the
- calculator functionality.
- \li \c Button is the widget used for each of the calculator
- button. It derives from QToolButton.
- \endlist
-
- We will start by reviewing \c Calculator, then we will take a
- look at \c Button.
-
- \section1 Calculator Class Definition
-
- \snippet examples/widgets/calculator/calculator.h 0
-
- The \c Calculator class provides a simple calculator widget. It
- inherits from QDialog and has several private slots associated
- with the calculator's buttons. QObject::eventFilter() is
- reimplemented to handle mouse events on the calculator's display.
-
- Buttons are grouped in categories according to their behavior.
- For example, all the digit buttons (labeled \uicontrol 0 to \uicontrol 9)
- append a digit to the current operand. For these, we connect
- multiple buttons to the same slot (e.g., \c digitClicked()). The
- categories are digits, unary operators (\uicontrol{Sqrt}, \uicontrol{x\unicode{178}},
- \uicontrol{1/x}), additive operators (\uicontrol{+}, \uicontrol{-}), and
- multiplicative operators (\uicontrol{\unicode{215}}, \uicontrol{\unicode{247}}). The other buttons
- have their own slots.
-
- \snippet examples/widgets/calculator/calculator.h 1
- \snippet examples/widgets/calculator/calculator.h 2
-
- The private \c createButton() function is used as part of the
- widget construction. \c abortOperation() is called whenever a
- division by zero occurs or when a square root operation is
- applied to a negative number. \c calculate() applies a binary
- operator (\uicontrol{+}, \uicontrol{-}, \uicontrol{\unicode{215}}, or \uicontrol{\unicode{247}}).
-
- \snippet examples/widgets/calculator/calculator.h 3
- \snippet examples/widgets/calculator/calculator.h 4
- \snippet examples/widgets/calculator/calculator.h 5
- \snippet examples/widgets/calculator/calculator.h 6
- \snippet examples/widgets/calculator/calculator.h 7
- \snippet examples/widgets/calculator/calculator.h 8
-
- These variables, together with the contents of the calculator
- display (a QLineEdit), encode the state of the calculator:
-
- \list
- \li \c sumInMemory contains the value stored in the calculator's memory
- (using \uicontrol{MS}, \uicontrol{M+}, or \uicontrol{MC}).
- \li \c sumSoFar stores the value accumulated so far. When the user
- clicks \uicontrol{=}, \c sumSoFar is recomputed and shown on the
- display. \uicontrol{Clear All} resets \c sumSoFar to zero.
- \li \c factorSoFar stores a temporary value when doing
- multiplications and divisions.
- \li \c pendingAdditiveOperator stores the last additive operator
- clicked by the user.
- \li \c pendingMultiplicativeOperator stores the last multiplicative operator
- clicked by the user.
- \li \c waitingForOperand is \c true when the calculator is
- expecting the user to start typing an operand.
- \endlist
-
- Additive and multiplicative operators are treated differently
- because they have different precedences. For example, \uicontrol{1 + 2 \unicode{247}
- 3} is interpreted as \uicontrol{1 + (2 \unicode{247} 3)} because \uicontrol{\unicode{247}} has higher
- precedence than \uicontrol{+}.
-
- The table below shows the evolution of the calculator state as
- the user enters a mathematical expression.
-
- \table
- \header \li User Input \li Display \li Sum so Far \li Add. Op. \li Factor so Far \li Mult. Op. \li Waiting for Operand?
- \row \li \li 0 \li 0 \li \li \li \li \c true
- \row \li \uicontrol{1} \li 1 \li 0 \li \li \li \li \c false
- \row \li \uicontrol{1 +} \li 1 \li 1 \li \uicontrol{+} \li \li \li \c true
- \row \li \uicontrol{1 + 2} \li 2 \li 1 \li \uicontrol{+} \li \li \li \c false
- \row \li \uicontrol{1 + 2 \unicode{247}} \li 2 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c true
- \row \li \uicontrol{1 + 2 \unicode{247} 3} \li 3 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c false
- \row \li \uicontrol{1 + 2 \unicode{247} 3 -} \li 1.66667 \li 1.66667 \li \uicontrol{-} \li \li \li \c true
- \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4} \li 4 \li 1.66667 \li \uicontrol{-} \li \li \li \c false
- \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4 =} \li -2.33333 \li 0 \li \li \li \li \c true
- \endtable
-
- Unary operators, such as \uicontrol Sqrt, require no special handling;
- they can be applied immediately since the operand is already
- known when the operator button is clicked.
-
- \snippet examples/widgets/calculator/calculator.h 9
- \codeline
- \snippet examples/widgets/calculator/calculator.h 10
-
- Finally, we declare the variables associated with the display and the
- buttons used to display numerals.
-
- \section1 Calculator Class Implementation
-
- \snippet examples/widgets/calculator/calculator.cpp 0
-
- In the constructor, we initialize the calculator's state. The \c
- pendingAdditiveOperator and \c pendingMultiplicativeOperator
- variables don't need to be initialized explicitly, because the
- QString constructor initializes them to empty strings.
-
- \snippet examples/widgets/calculator/calculator.cpp 1
- \snippet examples/widgets/calculator/calculator.cpp 2
-
- We create the QLineEdit representing the calculator's display and
- set up some of its properties. In particular, we set it to be
- read-only.
-
- We also enlarge \c{display}'s font by 8 points.
-
- \snippet examples/widgets/calculator/calculator.cpp 4
-
- For each button, we call the private \c createButton() function with
- the proper text label and a slot to connect to the button.
-
- \snippet examples/widgets/calculator/calculator.cpp 5
- \snippet examples/widgets/calculator/calculator.cpp 6
-
- The layout is handled by a single QGridLayout. The
- QLayout::setSizeConstraint() call ensures that the \c Calculator
- widget is always shown as its optimal size (its
- \l{QWidget::sizeHint()}{size hint}), preventing the user from
- resizing the calculator. The size hint is determined by the size
- and \l{QWidget::sizePolicy()}{size policy} of the child widgets.
-
- Most child widgets occupy only one cell in the grid layout. For
- these, we only need to pass a row and a column to
- QGridLayout::addWidget(). The \c display, \c backspaceButton, \c
- clearButton, and \c clearAllButton widgets occupy more than one
- column; for these we must also pass a row span and a column
- span.
-
- \snippet examples/widgets/calculator/calculator.cpp 7
-
- Pressing one of the calculator's digit buttons will emit the
- button's \l{QToolButton::clicked()}{clicked()} signal, which will
- trigger the \c digitClicked() slot.
-
- First, we find out which button sent the signal using
- QObject::sender(). This function returns the sender as a QObject
- pointer. Since we know that the sender is a \c Button object, we
- can safely cast the QObject. We could have used a C-style cast or
- a C++ \c static_cast<>(), but as a defensive programming
- technique we use a \l qobject_cast(). The advantage is that if
- the object has the wrong type, a null pointer is returned.
- Crashes due to null pointers are much easier to diagnose than
- crashes due to unsafe casts. Once we have the button, we extract
- the operator using QToolButton::text().
-
- The slot needs to consider two situations in particular. If \c
- display contains "0" and the user clicks the \uicontrol{0} button, it
- would be silly to show "00". And if the calculator is in
- a state where it is waiting for a new operand,
- the new digit is the first digit of that new operand; in that case,
- any result of a previous calculation must be cleared first.
-
- At the end, we append the new digit to the value in the display.
-
- \snippet examples/widgets/calculator/calculator.cpp 8
- \snippet examples/widgets/calculator/calculator.cpp 9
-
- The \c unaryOperatorClicked() slot is called whenever one of the
- unary operator buttons is clicked. Again a pointer to the clicked
- button is retrieved using QObject::sender(). The operator is
- extracted from the button's text and stored in \c
- clickedOperator. The operand is obtained from \c display.
-
- Then we perform the operation. If \uicontrol Sqrt is applied to a
- negative number or \uicontrol{1/x} to zero, we call \c
- abortOperation(). If everything goes well, we display the result
- of the operation in the line edit and we set \c waitingForOperand
- to \c true. This ensures that if the user types a new digit, the
- digit will be considered as a new operand, instead of being
- appended to the current value.
-
- \snippet examples/widgets/calculator/calculator.cpp 10
- \snippet examples/widgets/calculator/calculator.cpp 11
-
- The \c additiveOperatorClicked() slot is called when the user
- clicks the \uicontrol{+} or \uicontrol{-} button.
-
- Before we can actually do something about the clicked operator,
- we must handle any pending operations. We start with the
- multiplicative operators, since these have higher precedence than
- additive operators:
-
- \snippet examples/widgets/calculator/calculator.cpp 12
- \snippet examples/widgets/calculator/calculator.cpp 13
-
- If \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} has been clicked earlier, without clicking
- \uicontrol{=} afterward, the current value in the display is the right
- operand of the \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} operator and we can finally
- perform the operation and update the display.
-
- \snippet examples/widgets/calculator/calculator.cpp 14
- \snippet examples/widgets/calculator/calculator.cpp 15
-
- If \uicontrol{+} or \uicontrol{-} has been clicked earlier, \c sumSoFar is
- the left operand and the current value in the display is the
- right operand of the operator. If there is no pending additive
- operator, \c sumSoFar is simply set to be the text in the
- display.
-
- \snippet examples/widgets/calculator/calculator.cpp 16
- \snippet examples/widgets/calculator/calculator.cpp 17
-
- Finally, we can take care of the operator that was just clicked.
- Since we don't have the right-hand operand yet, we store the clicked
- operator in the \c pendingAdditiveOperator variable. We will
- apply the operation later, when we have a right operand, with \c
- sumSoFar as the left operand.
-
- \snippet examples/widgets/calculator/calculator.cpp 18
-
- The \c multiplicativeOperatorClicked() slot is similar to \c
- additiveOperatorClicked(). We don't need to worry about pending
- additive operators here, because multiplicative operators have
- precedence over additive operators.
-
- \snippet examples/widgets/calculator/calculator.cpp 20
-
- Like in \c additiveOperatorClicked(), we start by handing any
- pending multiplicative and additive operators. Then we display \c
- sumSoFar and reset the variable to zero. Resetting the variable
- to zero is necessary to avoid counting the value twice.
-
- \snippet examples/widgets/calculator/calculator.cpp 22
-
- The \c pointClicked() slot adds a decimal point to the content in
- \c display.
-
- \snippet examples/widgets/calculator/calculator.cpp 24
-
- The \c changeSignClicked() slot changes the sign of the value in
- \c display. If the current value is positive, we prepend a minus
- sign; if the current value is negative, we remove the first
- character from the value (the minus sign).
-
- \snippet examples/widgets/calculator/calculator.cpp 26
-
- The \c backspaceClicked() removes the rightmost character in the
- display. If we get an empty string, we show "0" and set \c
- waitingForOperand to \c true.
-
- \snippet examples/widgets/calculator/calculator.cpp 28
-
- The \c clear() slot resets the current operand to zero. It is
- equivalent to clicking \uicontrol Backspace enough times to erase the
- entire operand.
-
- \snippet examples/widgets/calculator/calculator.cpp 30
-
- The \c clearAll() slot resets the calculator to its initial state.
-
- \snippet examples/widgets/calculator/calculator.cpp 32
-
- The \c clearMemory() slot erases the sum kept in memory, \c
- readMemory() displays the sum as an operand, \c setMemory()
- replace the sum in memory with the current sum, and \c
- addToMemory() adds the current value to the value in memory. For
- \c setMemory() and \c addToMemory(), we start by calling \c
- equalClicked() to update \c sumSoFar and the value in the
- display.
-
- \snippet examples/widgets/calculator/calculator.cpp 34
-
- The private \c createButton() function is called from the
- constructor to create calculator buttons.
-
- \snippet examples/widgets/calculator/calculator.cpp 36
-
- The private \c abortOperation() function is called whenever a
- calculation fails. It resets the calculator state and displays
- "####".
-
- \snippet examples/widgets/calculator/calculator.cpp 38
-
- The private \c calculate() function performs a binary operation.
- The right operand is given by \c rightOperand. For additive
- operators, the left operand is \c sumSoFar; for multiplicative
- operators, the left operand is \c factorSoFar. The function
- return \c false if a division by zero occurs.
-
- \section1 Button Class Definition
-
- Let's now take a look at the \c Button class:
-
- \snippet examples/widgets/calculator/button.h 0
-
- The \c Button class has a convenience constructor that takes a
- text label and a parent widget, and it reimplements QWidget::sizeHint()
- to provide more space around the text than the amount QToolButton
- normally provides.
-
- \section1 Button Class Implementation
-
- \snippet examples/widgets/calculator/button.cpp 0
-
- The buttons' appearance is determined by the layout of the
- calculator widget through the size and
- \l{QWidget::sizePolicy}{size policy} of the layout's child
- widgets. The call to the
- \l{QWidget::setSizePolicy()}{setSizePolicy()} function in the
- constructor ensures that the button will expand horizontally to
- fill all the available space; by default, \l{QToolButton}s don't
- expand to fill available space. Without this call, the different
- buttons in a same column would have different widths.
-
- \snippet examples/widgets/calculator/button.cpp 1
- \snippet examples/widgets/calculator/button.cpp 2
-
- In \l{QWidget::sizeHint()}{sizeHint()}, we try to return a size
- that looks good for most buttons. We reuse the size hint of the
- base class (QToolButton) but modify it in the following ways:
-
- \list
- \li We add 20 to the \l{QSize::height()}{height} component of the size hint.
- \li We make the \l{QSize::width()}{width} component of the size
- hint at least as much as the \l{QSize::width()}{height}.
- \endlist
-
- This ensures that with most fonts, the digit and operator buttons
- will be square, without truncating the text on the
- \uicontrol{Backspace}, \uicontrol{Clear}, and \uicontrol{Clear All} buttons.
-
- The screenshot below shows how the \c Calculator widget would
- look like if we \e didn't set the horizontal size policy to
- QSizePolicy::Expanding in the constructor and if we didn't
- reimplement QWidget::sizeHint().
-
- \image calculator-ugly.png The Calculator example with default size policies and size hints
-
-*/
diff --git a/doc/src/examples/calendar.qdoc b/doc/src/examples/calendar.qdoc
deleted file mode 100644
index aea9805669..0000000000
--- a/doc/src/examples/calendar.qdoc
+++ /dev/null
@@ -1,223 +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$
-**
-****************************************************************************/
-
-/*!
- \example richtext/calendar
- \title Calendar Example
-
- The Calendar example shows how to create rich text content and display it using
- a rich text editor.
-
- \image calendar-example.png
-
- Specifically, the example demonstrates the following:
-
- \list
- \li Use of a text editor with a text document
- \li Insertion of tables and frames into a document
- \li Navigation within a table
- \li Insert text in different styles
- \endlist
-
- The rich text editor used to display the document is used within a main window
- application.
-
- \section1 MainWindow Class Definition
-
- The \c MainWindow class provides a text editor widget and some controls to
- allow the user to change the month and year shown. The font size used for the
- text can also be adjusted.
-
- \snippet examples/richtext/calendar/mainwindow.h 0
-
- The private \c insertCalendar() function performs most of the work, relying on
- the \c fontSize and \c selectedDate variables to write useful information to
- the \c editor.
-
- \section1 MainWindow Class Implementation
-
- The \c MainWindow constructor sets up the user interface and initializes
- variables used to generate a calendar for each month.
-
- \snippet examples/richtext/calendar/mainwindow.cpp 0
-
- We begin by setting default values for the selected date that will be highlighted
- in the calendar and the font size to be used. Since we are using a QMainWindow
- for the user interface, we construct a widget for use as the central widget.
-
- The user interface will include a line of controls above the generated calendar;
- we construct a label and a combobox to allow the month to be selected, and a
- spin box for the year. These widgets are configured to provide a reasonable range
- of values for the user to try:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 1
-
- We use the \c selectedDate object to obtain the current month and year, and we
- set these in the combobox and spin box:
-
- The font size is displayed in a spin box which we restrict to a sensible range
- of values:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 2
-
- We construct an editor and use the \c insertCalendar() function to create
- a calendar for it. Each calendar is displayed in the same text editor; in
- this example we use a QTextBrowser since we do not allow the calendar to be
- edited.
-
- The controls used to set the month, year, and font size will not have any
- effect on the appearance of the calendar unless we make some signal-slot
- connections:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 3
-
- The signals are connected to some simple slots in the \c MainWindow class
- which we will describe later.
-
- We create layouts to manage the widgets we constructed:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 4
-
- Finally, the central widget is set for the window.
-
- Each calendar is created for the editor by the \c insertCalendar() function
- which uses the date and font size, defined by the private \a selectedDate
- and \c fontSize variables, to produce a suitable plan for the specified
- month and year.
-
- \snippet examples/richtext/calendar/mainwindow.cpp 5
-
- We begin by clearing the editor's rich text document, and obtain a text
- cursor from the editor that we will use to add content. We also create a
- QDate object based on the currently selected date.
-
- The calendar is made up of a table with a gray background color that contains
- seven columns: one for each day of the week. It is placed in the center of the
- page with equal space to the left and right of it. All of these properties are
- set in a QTextTableFormat object:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 6
-
- Each cell in the table will be padded and spaced to make the text easier to
- read.
-
- We want the columns to have equal widths, so we provide a vector containing
- percentage widths for each of them and set the constraints in the
- QTextTableFormat:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 7
-
- The constraints used for the column widths are only useful if the table has
- an appropriate number of columns. With the format for the table defined, we
- construct a new table with one row and seven columns at the current cursor
- position:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 8
-
- We only need one row to start with; more can be added as we need them. Using
- this approach means that we do not need to perform any date calculations
- until we add cells to the table.
-
- When inserting objects into a document with the cursor's insertion functions,
- the cursor is automatically moved inside the newly inserted object. This means
- that we can immediately start modifying the table from within:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 9
-
- Since the table has an outer frame, we obtain the frame and its format so that
- we can customize it. After making the changes we want, we set the frame's format
- using the modified format object. We have given the table an outer border one
- pixel wide.
-
- \snippet examples/richtext/calendar/mainwindow.cpp 10
-
- In a similar way, we obtain the cursor's current character format and
- create customized formats based on it.
-
- We do not set the format on the cursor because this would change the default
- character format; instead, we use the customized formats explicitly when we
- insert text. The following loop inserts the days of the week into the table
- as bold text:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 11
-
- For each day of the week, we obtain an existing table cell in the first row
- (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since
- we start counting the days of the week at day 1 (Monday), we subtract 1 from
- \c weekDay to ensure that we obtain the cell for the correct column of the
- table.
-
- Before text can be inserted into a cell, we must obtain a cursor with the
- correct position in the document. The cell provides a function for this
- purpose, and we use this cursor to insert text using the \c boldFormat
- character format that we created earlier:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 12
-
- Inserting text into document objects usually follows the same pattern.
- Each object can provide a new cursor that corresponds to the first valid
- position within itself, and this can be used to insert new content. We
- continue to use this pattern as we insert the days of the month into the
- table.
-
- Since every month has more than seven days, we insert a single row to begin
- and add days until we reach the end of the month. If the current date is
- encountered, it is inserted with a special format (created earlier) that
- makes it stand out:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 13
-
- We add a new row to the table at the end of each week only if the next week
- falls within the currently selected month.
-
- For each calendar that we create, we change the window title to reflect the
- currently selected month and year:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 14
-
- The \c insertCalendar() function relies on up-to-date values for the month,
- year, and font size. These are set in the following slots:
-
- \snippet examples/richtext/calendar/mainwindow.cpp 15
-
- The \c setFontSize() function simply changes the private \c fontSize variable
- before updating the calendar.
-
- \snippet examples/richtext/calendar/mainwindow.cpp 16
-
- The \c setMonth slot is called when the QComboBox used to select the month is
- updated. The value supplied is the currently selected row in the combobox.
- We add 1 to this value to obtain a valid month number, and create a new QDate
- based on the existing one. The calendar is then updated to use this new date.
-
- \snippet examples/richtext/calendar/mainwindow.cpp 17
-
- The \c setYear() slot is called when the QDateTimeEdit used to select the
- year is updated. The value supplied is a QDate object; this makes
- the construction of a new value for \c selectedDate simple. We update the
- calendar afterwards to use this new date.
-*/
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.
-*/
diff --git a/doc/src/examples/charactermap.qdoc b/doc/src/examples/charactermap.qdoc
deleted file mode 100644
index 5fbcae1fad..0000000000
--- a/doc/src/examples/charactermap.qdoc
+++ /dev/null
@@ -1,274 +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$
-**
-****************************************************************************/
-
-/*!
-\example widgets/charactermap
-\title Character Map Example
-
-The Character Map example shows how to create a custom widget that can
-both display its own content and respond to user input.
-
-The example displays an array of characters which the user can click on
-to enter text in a line edit. The contents of the line edit can then be
-copied into the clipboard, and pasted into other applications. The
-purpose behind this sort of tool is to allow users to enter characters
-that may be unavailable or difficult to locate on their keyboards.
-
-\image charactermap-example.png Screenshot of the Character Map example
-
-The example consists of the following classes:
-
-\list
-\li \c CharacterWidget displays the available characters in the current
- font and style.
-\li \c MainWindow provides a standard main window that contains font and
- style information, a view onto the characters, a line edit, and a push
- button for submitting text to the clipboard.
-\endlist
-
-\section1 CharacterWidget Class Definition
-
-The \c CharacterWidget class is used to display an array of characters in
-a user-specified font and style. For flexibility, we subclass QWidget and
-reimplement only the functions that we need to provide basic rendering
-and interaction features.
-
-The class definition looks like this:
-
-\snippet examples/widgets/charactermap/characterwidget.h 0
-
-The widget does not contain any other widgets, so it must provide its own
-size hint to allow its contents to be displayed correctly.
-We reimplement \l{QWidget::paintEvent()} to draw custom content. We also
-reimplement \l{QWidget::mousePressEvent()} to allow the user to interact
-with the widget.
-
-The updateFont() and updateStyle() slots are used to update the font and
-style of the characters in the widget whenever the user changes the
-settings in the application.
-The class defines the characterSelected() signal so that other parts
-of the application are informed whenever the user selects a character in
-the widget.
-As a courtesy, the widget provides a tooltip that shows the current
-character value. We reimplement the \l{QWidget::mouseMoveEvent()} event
-handler and define showToolTip() to enable this feature.
-
-The \c columns, \c displayFont and \c currentKey private data members
-are used to record the number of columns to be shown, the current font,
-and the currently highlighted character in the widget.
-
-\section1 CharacterWidget Class Implementation
-
-Since the widget is to be used as a simple canvas, the constructor just
-calls the base class constructor and defines some default values for
-private data members.
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 0
-
-We initialize \c currentKey with a value of -1 to indicate
-that no character is initially selected. We enable mouse tracking to
-allow us to follow the movement of the cursor across the widget.
-
-The class provides two functions to allow the font and style to be set up.
-Each of these modify the widget's display font and call update():
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 1
-\codeline
-\snippet examples/widgets/charactermap/characterwidget.cpp 2
-
-We use a fixed size font for the display. Similarly, a fixed size hint is
-provided by the sizeHint() function:
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 3
-
-Three standard event functions are implemented so that the widget
-can respond to clicks, provide tooltips, and render the available
-characters. The paintEvent() shows how the contents of the widget are
-arranged and displayed:
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 6
-
-A QPainter is created for the widget and, in all cases, we ensure that the
-widget's background is painted. The painter's font is set to the
-user-specified display font.
-
-The area of the widget that needs to be redrawn is used to determine which
-characters need to be displayed:
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 7
-
-Using integer division, we obtain the row and column numbers of each
-characters that should be displayed, and we draw a square on the widget
-for each character displayed.
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 8
-\snippet examples/widgets/charactermap/characterwidget.cpp 9
-
-The symbols for each character in the array are drawn within each square,
-with the symbol for the most recently selected character displayed in red:
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 10
-
-We do not need to take into account the difference between the area
-displayed in the viewport and the area we are drawing on because
-everything outside the visible area will be clipped.
-
-The mousePressEvent() defines how the widget responds to mouse clicks.
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 5
-
-We are only interested when the user clicks with the left mouse button
-over the widget. When this happens, we calculate which character was
-selected and emit the characterSelected() signal.
-The character's number is found by dividing the x and y-coordinates of
-the click by the size of each character's grid square. Since the number
-of columns in the widget is defined by the \c columns variable, we
-simply multiply the row index by that value and add the column number
-to obtain the character number.
-
-If any other mouse button is pressed, the event is passed on to the
-QWidget base class. This ensures that the event can be handled properly
-by any other interested widgets.
-
-The mouseMoveEvent() maps the mouse cursor's position in global
-coordinates to widget coordinates, and determines the character that
-was clicked by performing the calculation
-
-\snippet examples/widgets/charactermap/characterwidget.cpp 4
-
-The tooltip is given a position defined in global coordinates.
-
-\section1 MainWindow Class Definition
-
-The \c MainWindow class provides a minimal user interface for the example,
-with only a constructor, slots that respond to signals emitted by standard
-widgets, and some convenience functions that are used to set up the user
-interface.
-
-The class definition looks like this:
-
-\snippet examples/widgets/charactermap/mainwindow.h 0
-
-The main window contains various widgets that are used to control how
-the characters will be displayed, and defines the findFonts() function
-for clarity and convenience. The findStyles() slot is used by the widgets
-to determine the styles that are available, insertCharacter() inserts
-a user-selected character into the window's line edit, and
-updateClipboard() synchronizes the clipboard with the contents of the
-line edit.
-
-\section1 MainWindow Class Implementation
-
-In the constructor, we set up the window's central widget and fill it with
-some standard widgets (two comboboxes, a line edit, and a push button).
-We also construct a CharacterWidget custom widget, and add a QScrollArea
-so that we can view its contents:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 0
-
-QScrollArea provides a viewport onto the \c CharacterWidget when we set
-its widget and handles much of the work needed to provide a scrolling
-viewport.
-
-The font combo box is automatically popuplated with a list of available
-fonts. We list the available styles for the current font in the style
-combobox using the following function:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 1
-
-The line edit and push button are used to supply text to the clipboard:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 2
-
-We also obtain a clipboard object so that we can send text entered by the
-user to other applications.
-
-Most of the signals emitted in the example come from standard widgets.
-We connect these signals to slots in this class, and to the slots provided
-by other widgets.
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 4
-
-The font combobox's
-\l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is
-connected to the findStyles() function so that the list of available styles
-can be shown for each font that is used. Since both the font and the style
-can be changed by the user, the font combobox's currentFontChanged() signal
-and the style combobox's
-\l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected
-directly to the character widget.
-
-The final two connections allow characters to be selected in the character
-widget, and text to be inserted into the clipboard:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 5
-
-The character widget emits the characterSelected() custom signal when
-the user clicks on a character, and this is handled by the insertCharacter()
-function in this class. The clipboard is changed when the push button emits
-the clicked() signal, and we handle this with the updateClipboard() function.
-
-The remaining code in the constructor sets up the layout of the central widget,
-and provides a window title:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 6
-
-The font combobox is automatically populated with a list of available font
-families. The styles that can be used with each font are found by the
-findStyles() function. This function is called whenever the user selects a
-different font in the font combobox.
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 7
-
-We begin by recording the currently selected style, and we clear the
-style combobox so that we can insert the styles associated with the
-current font family.
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 8
-
-We use the font database to collect the styles that are available for the
-current font, and insert them into the style combobox. The current item is
-reset if the original style is not available for this font.
-
-The last two functions are slots that respond to signals from the character
-widget and the main window's push button. The insertCharacter() function is
-used to insert characters from the character widget when the user clicks a
-character:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 9
-
-The character is inserted into the line edit at the current cursor position.
-
-The main window's "To clipboard" push button is connected to the
-updateClipboard() function so that, when it is clicked, the clipboard is
-updated to contain the contents of the line edit:
-
-\snippet examples/widgets/charactermap/mainwindow.cpp 10
-
-We copy all the text from the line edit to the clipboard, but we do not clear
-the line edit.
-*/
diff --git a/doc/src/examples/chart.qdoc b/doc/src/examples/chart.qdoc
deleted file mode 100644
index 947eddf1c9..0000000000
--- a/doc/src/examples/chart.qdoc
+++ /dev/null
@@ -1,82 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/chart
- \title Chart Example
-
- The Chart example shows how to create a custom view for the model/view framework.
-
- \image chart-example.png
-
- In this example, the items in a table model are represented as slices in a pie chart,
- relying on the flexibility of the model/view architecture to handle custom editing
- and selection features.
-
- \b{Note that you only need to create a new view class if your data requires a
- specialized representation.} You should first consider using a standard QListView,
- QTableView, or QTreeView with a custom QItemDelegate subclass if you need to
- represent data in a special way.
-
- \omit
- \section1 PieView Class Definition
-
- The \c PieView class is a subclass of QAbstractItemView. The base class provides
- much of the functionality required by view classes, so we only need to provide
- implementations for three public functions: visualRect(), scrollTo(), and
- indexAt(). However, the view needs to maintain strict control over its look and
- feel, so we also provide implementations for a number of other functions:
-
- \snippet examples/itemviews/chart/pieview.h 0
-
-
-
- \section1 PieView Class Implementation
-
- The paint event renders the data from the standard item model as a pie chart.
- We interpret the data in the following way:
-
- \list
- \li Column 0 contains data in two different roles:
- The \l{Qt::ItemDataRole}{DisplayRole} contains a label, and the
- \l{Qt::ItemDataRole}{DecorationRole} contains the color of the pie slice.
- \li Column 1 contains a quantity which we will convert to the angular extent of
- the slice.
- \endlist
-
- The figure is always drawn with the chart on the left and the key on
- the right. This means that we must try and obtain an area that is wider
- than it is tall. We do this by imposing a particular aspect ratio on
- the chart and applying it to the available vertical space. This ensures
- that we always obtain the maximum horizontal space for the aspect ratio
- used.
- We also apply fixed size margin around the figure.
-
- We use logical coordinates to draw the chart and key, and position them
- on the view using viewports.
- \endomit
-*/
diff --git a/doc/src/examples/chip.qdoc b/doc/src/examples/chip.qdoc
deleted file mode 100644
index 966c16900a..0000000000
--- a/doc/src/examples/chip.qdoc
+++ /dev/null
@@ -1,38 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/chip
- \title 40000 Chips
-
- This demo shows how to visualize a huge scene with 40000 chip items
- using Graphics View. It also shows Graphics View's powerful navigation
- and interaction features, allowing you to zoom and rotate each of four
- views independently, and you can select and move items around the scene.
-
- \image chip-demo.png
-*/
diff --git a/doc/src/examples/classwizard.qdoc b/doc/src/examples/classwizard.qdoc
deleted file mode 100644
index eec9b6ac51..0000000000
--- a/doc/src/examples/classwizard.qdoc
+++ /dev/null
@@ -1,190 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/classwizard
- \title Class Wizard Example
-
- The License Wizard example shows how to implement linear
- wizards using QWizard.
-
- \image classwizard.png Screenshot of the Class Wizard example
-
- Most wizards have a linear structure, with page 1 followed by
- page 2 and so on until the last page. Some wizards are more
- complex in that they allow different traversal paths based on the
- information provided by the user. The
- \l{dialogs/licensewizard}{License Wizard} example shows how to
- create such wizards.
-
- The Class Wizard example consists of the following classes:
-
- \list
- \li \c ClassWizard inherits QWizard and provides a
- three-step wizard that generates the skeleton of a C++ class
- based on the user's input.
- \li \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c
- OutputFilesPage, and \c ConclusionPage are QWizardPage
- subclasses that implement the wizard pages.
- \endlist
-
- \section1 ClassWizard Class Definition
-
- \image classwizard-flow.png The Class Wizard pages
-
- We will see how to subclass QWizard to implement our own wizard.
- The concrete wizard class is called \c ClassWizard and provides
- five pages:
-
- \list
- \li The first page is an introduction page, telling the user what
- the wizard is going to do.
- \li The second page asks for a class name and a base class, and
- allows the user to specify whether the class should have a \c
- Q_OBJECT macro and what constructors it should provide.
- \li The third page allows the user to set some options related to the code
- style, such as the macro used to protect the header file from
- multiple inclusion (e.g., \c MYDIALOG_H).
- \li The fourth page allows the user to specify the names of the
- output files.
- \li The fifth page is a conclusion page.
- \endlist
-
- Although the program is just an example, if you press \uicontrol Finish
- (\uicontrol Done on Mac OS X), actual C++ source files will actually be
- generated.
-
- \section1 The ClassWizard Class
-
- Here's the \c ClassWizard definition:
-
- \snippet examples/dialogs/classwizard/classwizard.h 0
-
- The class reimplements QDialog's \l{QDialog::}{accept()} slot.
- This slot is called when the user clicks \uicontrol{Finish}.
-
- Here's the constructor:
-
- \snippet examples/dialogs/classwizard/classwizard.cpp 1
-
- We instantiate the five pages and insert them into the wizard
- using QWizard::addPage(). The order in which they are inserted
- is also the order in which they will be shown later on.
-
- We call QWizard::setPixmap() to set the banner and the
- background pixmaps for all pages. The banner is used as a
- background for the page header when the wizard's style is
- \l{QWizard::}{ModernStyle}; the background is used as the
- dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements
- of a Wizard Page} for more information.)
-
- \snippet examples/dialogs/classwizard/classwizard.cpp 3
- \snippet examples/dialogs/classwizard/classwizard.cpp 4
- \dots
- \snippet examples/dialogs/classwizard/classwizard.cpp 5
- \snippet examples/dialogs/classwizard/classwizard.cpp 6
-
- If the user clicks \uicontrol Finish, we extract the information from
- the various pages using QWizard::field() and generate the files.
- The code is long and tedious (and has barely anything to do with
- noble art of designing wizards), so most of it is skipped here.
- See the actual example in the Qt distribution for the details if
- you're curious.
-
- \section1 The IntroPage Class
-
- The pages are defined in \c classwizard.h and implemented in \c
- classwizard.cpp, together with \c ClassWizard. We will start with
- the easiest page:
-
- \snippet examples/dialogs/classwizard/classwizard.h 1
- \codeline
- \snippet examples/dialogs/classwizard/classwizard.cpp 7
-
- A page inherits from QWizardPage. We set a
- \l{QWizardPage::}{title} and a
- \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting
- any \l{QWizardPage::}{subTitle}, we ensure that no header is
- displayed for this page. (On Windows, it is customary for wizards
- to display a watermark pixmap on the first and last pages, and to
- have a header on the other pages.)
-
- Then we create a QLabel and add it to a layout.
-
- \section1 The ClassInfoPage Class
-
- The second page is defined and implemented as follows:
-
- \snippet examples/dialogs/classwizard/classwizard.h 2
- \codeline
- \snippet examples/dialogs/classwizard/classwizard.cpp 9
- \dots
- \snippet examples/dialogs/classwizard/classwizard.cpp 12
- \dots
- \snippet examples/dialogs/classwizard/classwizard.cpp 13
-
- First, we set the page's \l{QWizardPage::}{title},
- \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo
- pixmap}. The logo pixmap is displayed in the page's header in
- \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}.
-
- Then we create the child widgets, create \l{Registering and Using
- Fields}{wizard fields} associated with them, and put them into
- layouts. The \c className field is created with an asterisk (\c
- *) next to its name. This makes it a \l{mandatory field}, that
- is, a field that must be filled before the user can press the
- \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values
- can be accessed from any other page using QWizardPage::field(),
- or from the wizard code using QWizard::field().
-
- \section1 The CodeStylePage Class
-
- The third page is defined and implemented as follows:
-
- \snippet examples/dialogs/classwizard/classwizard.h 3
- \codeline
- \snippet examples/dialogs/classwizard/classwizard.cpp 14
- \dots
- \snippet examples/dialogs/classwizard/classwizard.cpp 15
- \codeline
- \snippet examples/dialogs/classwizard/classwizard.cpp 16
-
- The code in the constructor is very similar to what we did for \c
- ClassInfoPage, so we skipped most of it.
-
- The \c initializePage() function is what makes this class
- interesting. It is reimplemented from QWizardPage and is used to
- initialize some of the page's fields with values from the
- previous page (namely, \c className and \c baseClass). For
- example, if the class name on page 2 is \c SuperDuperWidget, the
- default macro name on page 3 is \c SUPERDUPERWIDGET_H.
-
- The \c OutputFilesPage and \c ConclusionPage classes are very
- similar to \c CodeStylePage, so we won't review them here.
-
- \sa QWizard, {License Wizard Example}, {Trivial Wizard Example}
-*/
diff --git a/doc/src/examples/codeeditor.qdoc b/doc/src/examples/codeeditor.qdoc
deleted file mode 100644
index 695ac5c4ce..0000000000
--- a/doc/src/examples/codeeditor.qdoc
+++ /dev/null
@@ -1,197 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/codeeditor
- \title Code Editor Example
-
- The Code Editor example shows how to create a simple editor that
- has line numbers and that highlights the current line.
-
- \image codeeditor-example.png
-
- As can be seen from the image, the editor displays the line
- numbers in an area to the left of the area for editing. The editor
- will highlight the line containing the cursor.
-
- We implement the editor in \c CodeEditor, which is a widget that
- inherits QPlainTextEdit. We keep a separate widget in \c
- CodeEditor (\c LineNumberArea) onto which we draw the line
- numbers.
-
- QPlainTextEdit inherits from QAbstractScrollArea, and editing
- takes place within its \l{QAbstractScrollArea::}{viewport()}'s
- margins. We make room for our line number area by setting the left
- margin of the viewport to the size we need to draw the line
- numbers.
-
- When it comes to editing code, we prefer QPlainTextEdit over
- QTextEdit because it is optimized for handling plain text. See
- the QPlainTextEdit class description for details.
-
- QPlainTextEdit lets us add selections in addition to the
- selection the user can make with the mouse or keyboard. We use
- this functionality to highlight the current line. More on this
- later.
-
- We will now move on to the definitions and implementations of \c
- CodeEditor and \c LineNumberArea. Let's start with the \c
- LineNumberArea class.
-
- \section1 The LineNumberArea Class
-
- We paint the line numbers on this widget, and place it over the \c
- CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin
- area.
-
- We need to use protected functions in QPlainTextEdit while
- painting the area. So to keep things simple, we paint the area in
- the \c CodeEditor class. The area also asks the editor to
- calculate its size hint.
-
- Note that we could simply paint the line numbers directly on the
- code editor, and drop the LineNumberArea class. However, the
- QWidget class helps us to \l{QWidget::}{scroll()} its contents.
- Also, having a separate widget is the right choice if we wish to
- extend the editor with breakpoints or other code editor features.
- The widget would then help in the handling of mouse events.
-
- \snippet widgets/codeeditor/codeeditor.h extraarea
-
- \section1 CodeEditor Class Definition
-
- Here is the code editor's class definition:
-
- \snippet widgets/codeeditor/codeeditor.h codeeditordefinition
-
- In the editor we resize and draw the line numbers on the \c
- LineNumberArea. We need to do this when the number of lines in the
- editor changes, and when the editor's viewport() is scrolled. Of
- course, it is also done when the editor's size changes. We do
- this in \c updateLineNumberWidth() and \c updateLineNumberArea().
-
- Whenever, the cursor's position changes, we highlight the current
- line in \c highlightCurrentLine().
-
- \section1 CodeEditor Class Implementation
-
- We will now go through the code editors implementation, starting
- off with the constructor.
-
- \snippet widgets/codeeditor/codeeditor.cpp constructor
-
- In the constructor we connect our slots to signals in
- QPlainTextEdit. It is necessary to calculate the line number area
- width and highlight the first line when the editor is created.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth
-
- The \c lineNumberAreaWidth() function calculates the width of the
- \c LineNumberArea widget. We take the number of digits in the last
- line of the editor and multiply that with the maximum width of a
- digit.
-
- \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth
-
- When we update the width of the line number area, we simply call
- QAbstractScrollArea::setViewportMargins().
-
- \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest
-
- This slot is invoked when the editors viewport has been scrolled.
- The QRect given as argument is the part of the editing area that
- is do be updated (redrawn). \c dy holds the number of pixels the
- view has been scrolled vertically.
-
- \snippet widgets/codeeditor/codeeditor.cpp resizeEvent
-
- When the size of the editor changes, we also need to resize the
- line number area.
-
- \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged
-
- When the cursor position changes, we highlight the current line,
- i.e., the line containing the cursor.
-
- QPlainTextEdit gives the possibility to have more than one
- selection at the same time. we can set the character format
- (QTextCharFormat) of these selections. We clear the cursors
- selection before setting the new new
- QPlainTextEdit::ExtraSelection, else several lines would get
- highlighted when the user selects multiple lines with the mouse.
- \omit ask someone how this works \endomit
-
- One sets the selection with a text cursor. When using the
- FullWidthSelection property, the current cursor text block (line)
- will be selected. If you want to select just a portion of the text
- block, the cursor should be moved with QTextCursor::movePosition()
- from a position set with \l{QTextCursor::}{setPosition()}.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0
-
- The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea
- whenever it receives a paint event. We start off by painting the
- widget's background.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1
-
- We will now loop through all visible lines and paint the line
- numbers in the extra area for each line. Notice that in a plain
- text edit each line will consist of one QTextBlock; though, if
- line wrapping is enabled, a line may span several rows in the text
- edit's viewport.
-
- We get the top and bottom y-coordinate of the first text block,
- and adjust these values by the height of the current text block in
- each iteration in the loop.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2
-
- Notice that we check if the block is visible in addition to check
- if it is in the areas viewport - a block can, for example, be
- hidden by a window placed over the text edit.
-
- \section1 Suggestions for Extending the Code Editor
-
- No self-respecting code editor is without a syntax
- highligther; the \l{Syntax Highlighter Example} shows how to
- create one.
-
- In addition to line numbers, you can add more to the extra area,
- for instance, break points.
-
- QSyntaxHighlighter gives the possibility to add user data to each
- text block with
- \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be
- used to implement parenthesis matching. In the \c
- highlightCurrentLine(), the data of the currentBlock() can be
- fetched with QTextBlock::userData(). Matching parentheses can be
- highlighted with an extra selection. The "Matching Parentheses
- with QSyntaxHighlighter" article in Qt Quarterly 31 implements
- this. You find it here: \l{http://doc.qt.nokia.com/qq/}.
-
-*/
diff --git a/doc/src/examples/coloreditorfactory.qdoc b/doc/src/examples/coloreditorfactory.qdoc
deleted file mode 100644
index 1806446fb7..0000000000
--- a/doc/src/examples/coloreditorfactory.qdoc
+++ /dev/null
@@ -1,155 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/coloreditorfactory
- \title Color Editor Factory Example
-
- This example shows how to create an editor that can be used by
- a QItemDelegate.
-
- \image coloreditorfactoryimage.png
-
- When editing data in a QListView, QTableView, or QTreeView,
- editors are created and displayed by a \l{Delegate
- Classes}{delegate}. QItemDelegate, which is the default delegate
- used by Qt's \l{View Classes}{item views}, uses a
- QItemEditorFactory to create editors for it. A unique instance
- provided by QItemEditorFactory is by default installed on all
- item delegates.
-
- An item editor factory contains a collection of
- QItemEditorCreatorBase instances, which are specialized factories
- that produce editors for one particular QVariant data type (all
- models in Qt store their data in \l{QVariant}s). An editor can be any
- Qt or custom widget.
-
- In this example, we will create an editor (implemented in the \c
- ColorListEditor class) that can edit the QColor data type and be
- used by \l{QItemDelegate}s. We do this by creating a new
- QItemEditorCreatorBase that produces \c ColorListEditors and
- register it with a new factory, which we set as the default editor
- item factory (the unique factory instance). To test our editor, we
- have implemented the \c Window class, which displays a
- QTableWidget in which \l{QColor}s can be edited.
-
- \section1 Window Class Implementation
-
- In the Window class, we create the item editor creator
- base for our color editor and add it to the default factory.
- We also create a QTableWidget in which our editor can be
- tested. It is filled with some data and displayed in a window.
-
- We take a closer look at the constructor:
-
- \snippet examples/itemviews/coloreditorfactory/window.cpp 0
-
- The QStandardItemEditorCreator is a convenience class that
- inherits QItemEditorCreatorBase. Its constructor takes a template
- class, of which instances are returned from
- \l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a
- constructor that takes a QWidget as its only parameter; the
- template class must provide this. This way, there is no need to
- subclass QStandardItemEditorCreator.
-
- After the new factory has been set, all standard item delegates
- will use it (i.e, also delegates that were created before the new
- default factory was set).
-
- The \c createGUI() function sets up the table and fills it
- with data.
-
- \section1 ColorListEditor Definition
-
- The ColorListEditor inherits QComboBox and lets the user
- select a QColor from its popup list.
-
- \snippet examples/itemviews/coloreditorfactory/colorlisteditor.h 0
-
- QItemDelegate manages the interaction between the editor and
- the model, i.e., it retrieves data to edit from the model and
- store data from the editor in the model. The data that is edited
- by an editor is stored in the editor's user data property, and the
- delegate uses Qt's \l{Qt's Property System}{property system} to
- access it by name. We declare our user data property with the
- Q_PROPERTY macro. The property is set to be the user type with the
- USER keyword.
-
- \section1 ColorListEditor Implementation
-
- The constructor of \c ColorListEditor simply calls \c
- populateList(), which we will look at later. We move on to the
- \c color() function:
-
- \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 0
-
- We return the data that is selected in the combobox. The data
- is stored in the Qt::DecorationRole as the color is then also
- displayed in the popup list (as shown in the image above).
-
- \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 1
-
- The \c findData() function searches the items in the combobox
- and returns the index of the item that has \c color in the
- Qt::Decoration role.
-
- \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 2
-
- Qt knows some predefined colors by name. We simply loop
- through these to fill our editor with items.
-
- \section1 Further Customization of Item View Editors
-
- You can customize Qt's \l{Model/View Programming}{model view
- framework} in many ways. The procedure shown in this example is
- usually sufficient to provide custom editors. Further
- customization is achieved by subclassing QItemEditorFactory
- and QItemEditorCreatorBase. It is also possible to subclass
- QItemDelegate if you don't wish to use a factory at all.
-
- Possible suggestions are:
-
- \list
- \li If the editor widget has no user property defined, the delegate
- asks the factory for the property name, which it in turn
- asks the item editor creator for. In this case, you can use
- the QItemEditorCreator class, which takes the property
- name to use for editing as a constructor argument.
- \li If the editor requires other constructors or other
- initialization than provided by QItemEditorCreatorBase, you
- must reimplement
- QItemEditorCreatorBase::createWidget().
- \li You could also subclass QItemEditorFactory if you only want
- to provide editors for certain kinds of data or use another
- method of creating the editors than using creator bases.
- \endlist
-
- In this example, we use a standard QVariant data type. You can
- also use custom types. In the \l{Star Delegate Example}, we
- show how to store a custom data type in a QVariant and paint
- and edit it in a class that inherits QItemDelegate.
-*/
diff --git a/doc/src/examples/combowidgetmapper.qdoc b/doc/src/examples/combowidgetmapper.qdoc
deleted file mode 100644
index dae95ddb26..0000000000
--- a/doc/src/examples/combowidgetmapper.qdoc
+++ /dev/null
@@ -1,167 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/combowidgetmapper
- \title Combo Widget Mapper Example
-
- The Combo Widget Mapper example shows how to use a custom delegate to
- map information from a model to specific widgets on a form.
-
- \image combowidgetmapper-example.png
-
- In the \l{Simple Widget Mapper Example}, we showed the basic use of a
- widget mapper to relate data exposed by a model to simple input widgets
- in a user interface. However, sometimes we want to use input widgets that
- expose data as choices to the user, such as QComboBox, and we need a way
- to relate their input to the values stored in the model.
-
- This example is very similar to the \l{Simple Widget Mapper Example}.
- Again, we create a \c Window class with an almost identical user interface,
- except that, instead of providing a spin box so that each person's age
- can be entered, we provide a combo box to allow their addresses to be
- classified as "Home", "Work" or "Other".
-
- \section1 Window Class Definition
-
- The class provides a constructor, a slot to keep the buttons up to date,
- and a private function to set up the model:
-
- \snippet examples/itemviews/combowidgetmapper/window.h Window definition
-
- In addition to the QDataWidgetMapper object and the controls used to make
- up the user interface, we use a QStandardItemModel to hold our data and
- a QStringListModel to hold information about the types of address that
- can be applied to each person's data.
-
- \section1 Window Class Implementation
-
- The constructor of the \c Window class can be explained in three parts.
- In the first part, we set up the widgets used for the user interface:
-
- \snippet examples/itemviews/combowidgetmapper/window.cpp Set up widgets
-
- Note that we set up the mapping the combo box in the same way as for other
- widgets, but that we apply its own model to it so that it will display
- data from its own model, the \c typeModel, rather than from the model
- containing data about each person.
-
- Next, we set up the widget mapper, relating each input widget to a column
- in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:
-
- \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the mapper
-
- For the combo box, we pass an extra argument to tell the widget mapper
- which property to relate to values from the model. As a result, the user
- is able to select an item from the combo box, and the corresponding
- value stored in the widget's \c currentIndex property will be stored in
- the model.
-
- \omit
- However, we also set a delegate on the mapper. As with \l{Delegate Classes},
- this changes the way that data is presented to the user. In this case, the
- delegate acts as a proxy between the mapper and the input widgets,
- translating the data into a suitable form for the combo box but not
- interfering with the other input widgets. The implementation is shown later.
- \endomit
-
- The rest of the constructor is very similar to that of the
- \l{Simple Widget Mapper Example}:
-
- \snippet examples/itemviews/combowidgetmapper/window.cpp Set up connections and layouts
-
- The model is initialized in the window's \c{setupModel()} function. Here,
- we create a standard model with 5 rows and 3 columns. In each row, we
- insert a name, address, and a value that indicates the type of address.
- The address types are stored in a string list model.
-
- \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the model
-
- As we insert each row into the model, like a record in a database, we
- store values that correspond to items in \c typeModel for each person's
- address type. When the widget mapper reads these values from the final
- column of each row, it will need to use them as references to values in
- \c typeModel, as shown in the following diagram. This is where the
- delegate is used.
-
- \image widgetmapper-combo-mapping.png
-
- We show the implementation of the \c{updateButtons()} slot for
- completeness:
-
- \snippet examples/itemviews/combowidgetmapper/window.cpp Slot for updating the buttons
-
- \omit
- \section1 Delegate Class Definition and Implementation
-
- The delegate we use to mediate interaction between the widget mapper and
- the input widgets is a small QItemDelegate subclass:
-
- \snippet examples/itemviews/combowidgetmapper/delegate.h Delegate class definition
-
- This provides implementations of the two standard functions used to pass
- data between editor widgets and the model (see the \l{Delegate Classes}
- documentation for a more general description of these functions).
-
- Since we only provide an empty implementation of the constructor, we
- concentrate on the other two functions.
-
- The \l{QItemDelegate::}{setEditorData()} implementation takes the data
- referred to by the model index supplied and processes it according to
- the presence of a \c currentIndex property in the editor widget:
-
- \snippet examples/itemviews/combowidgetmapper/delegate.cpp setEditorData implementation
-
- If, like QComboBox, the editor widget has this property, it is set using
- the value from the model. Since we are passing around QVariant values,
- the strings stored in the model are automatically converted to the integer
- values needed for the \c currentIndex property.
-
- As a result, instead of showing "0", "1" or "2" in the combo box, one of
- its predefined set of items is shown. We call QItemDelegate::setEditorData()
- for widgets without the \c currentIndex property.
-
- The \l{QItemDelegate::}{setModelData()} implementation performs the reverse
- process, taking the value stored in the widget's \c currentIndex property
- and storing it back in the model:
-
- \snippet examples/itemviews/combowidgetmapper/delegate.cpp setModelData implementation
- \endomit
-
- \section1 Summary and Further Reading
-
- The use of a separate model for the combo box provides a menu of choices
- that are separate from the data stored in the main model. Using a named
- mapping that relates the combo box's \c currentIndex property to a column
- in the model effectively allows us to store a look-up value in the model.
-
- However, when reading the model outside the context of the widget mapper,
- we need to know about the \c typeModel to make sense of these look-up
- values. It would be useful to be able to store both the data and the
- choices held by the \c typeModel in one place.
- This is covered by the \l{SQL Widget Mapper Example}.
-*/
diff --git a/doc/src/examples/composition.qdoc b/doc/src/examples/composition.qdoc
deleted file mode 100644
index 6aca01d255..0000000000
--- a/doc/src/examples/composition.qdoc
+++ /dev/null
@@ -1,44 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/composition
- \title Composition Modes
-
- This demo shows some of the more advanced composition modes supported by Qt.
-
- \image composition-demo.png
-
- The two most common forms of composition are \b{Source} and \b{SourceOver}.
- \b{Source} is used to draw opaque objects onto a paint device. In this mode,
- each pixel in the source replaces the corresponding pixel in the destination.
- In \b{SourceOver} composition mode, the source object is transparent and is
- drawn on top of the destination.
-
- In addition to these standard modes, Qt defines the complete set of composition modes
- as defined by X. Porter and Y. Duff. See the QPainter documentation for details.
-*/
diff --git a/doc/src/examples/concentriccircles.qdoc b/doc/src/examples/concentriccircles.qdoc
deleted file mode 100644
index 22b0be8fb8..0000000000
--- a/doc/src/examples/concentriccircles.qdoc
+++ /dev/null
@@ -1,231 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/concentriccircles
- \title Concentric Circles Example
-
- The Concentric Circles example shows the improved rendering
- quality that can be obtained using floating point precision and
- anti-aliasing when drawing custom widgets. The example also shows
- how to do simple animations.
-
- The application's main window displays several widgets which are
- drawn using the various combinations of precision and
- anti-aliasing.
-
- \image concentriccircles-example.png
-
- Anti-aliasing is one of QPainter's render hints. The
- QPainter::RenderHints are used to specify flags to QPainter that
- may, or may not, be respected by any given
- engine. QPainter::Antialiasing indicates that the engine should
- anti-alias the edges of primitives if possible, i.e. put
- additional pixels around the original ones to smooth the edges.
-
- The difference between floating point precision and integer
- precision is a matter of accuracy, and is visible in the
- application's main window: Even though the logic that is
- calculating the circles' geometry is the same, floating points
- ensure that the white spaces between each circle are of the same
- size, while integers make two and two circles appear as if they
- belong together. The reason is that the integer based precision
- rely on rounding off non-integer calculations.
-
- The example consists of two classes:
-
- \list
- \li \c CircleWidget is a custom widget which renders several animated
- concentric circles.
- \li \c Window is the application's main window displaying four \c
- {CircleWidget}s drawn using different combinations of precision
- and aliasing.
- \endlist
-
- First we will review the CircleWidget class, then we will take a
- look at the Window class.
-
- \section1 CircleWidget Class Definition
-
- The CircleWidget class inherits QWidget, and is a custom widget
- which renders several animated concentric circles.
-
- \snippet examples/painting/concentriccircles/circlewidget.h 0
-
- We declare the \c floatBased and \c antialiased variables to hold
- whether an instance of the class should be rendered with integer
- or float based precision, and whether the rendering should be
- anti-aliased or not. We also declare functions setting each of
- these variables.
-
- In addition we reimplement the QWidget::paintEvent() function to
- apply the various combinations of precision and anti-aliasing when
- rendering, and to support the animation. We reimplement the
- QWidget::minimumSizeHint() and QWidget::sizeHint() functions to
- give the widget a reasonable size within our application.
-
- We declare the private \c nextAnimationFrame() slot, and the
- associated \c frameNo variable holding the number of "animation
- frames" for the widget, to facilitate the animation.
-
- \section1 CircleWidget Class Implementation
-
- In the constructor we make the widget's rendering integer based
- and aliased by default:
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 0
-
- We initialize the widget's \c frameNo variable, and set the
- widget's background color using the QWidget::setBackgroundColor()
- function which takes a \l {QPalette::ColorRole}{color role} as
- argument; the QPalette::Base color role is typically white.
-
- Then we set the widgets size policy using the
- QWidget::setSizePolicy() function. QSizePolicy::Expanding means
- that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a
- sensible size, but that the widget can be shrunk and still be
- useful. The widget can also make use of extra space, so it should
- get as much space as possible.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 1
- \codeline
- \snippet examples/painting/concentriccircles/circlewidget.cpp 2
-
- The public \c setFloatBased() and \c setAntialiased() functions
- update the widget's rendering preferences, i.e. whether the widget
- should be rendered with integer or float based precision, and
- whether the rendering should be anti-aliased or not.
-
- The functions also generate a paint event by calling the
- QWidget::update() function, forcing a repaint of the widget with
- the new rendering preferences.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 3
- \codeline
- \snippet examples/painting/concentriccircles/circlewidget.cpp 4
-
- The default implementations of the QWidget::minimumSizeHint() and
- QWidget::sizeHint() functions return invalid sizes if there is no
- layout for the widget, otherwise they return the layout's minimum and
- preferred size, respectively.
-
- We reimplement the functions to give the widget minimum and
- preferred sizes which are reasonable within our application.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 5
-
- The nextAnimationFrame() slot simply increments the \c frameNo
- variable's value, and calls the QWidget::update() function which
- schedules a paint event for processing when Qt returns to the main
- event loop.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 6
-
- A paint event is a request to repaint all or part of the
- widget. The \c paintEvent() function is an event handler that can
- be reimplemented to receive the widget's paint events. We
- reimplement the event handler to apply the various combinations of
- precision and anti-aliasing when rendering the widget, and to
- support the animation.
-
- First, we create a QPainter for the widget, and set its
- antialiased flag to the widget's preferred aliasing. We also
- translate the painters coordinate system, preparing to draw the
- widget's cocentric circles. The translation ensures that the
- center of the circles will be equivalent to the widget's center.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 7
-
- When painting a circle, we use the number of "animation frames" to
- determine the alpha channel of the circle's color. The alpha
- channel specifies the color's transparency effect, 0 represents a
- fully transparent color, while 255 represents a fully opaque
- color.
-
- \snippet examples/painting/concentriccircles/circlewidget.cpp 8
-
- If the calculated alpha channel is fully transparent, we don't
- draw anything since that would be equivalent to drawing a white
- circle on a white background. Instead we skip to the next circle
- still creating a white space. If the calculated alpha channel is
- fully opaque, we set the pen (the QColor passed to the QPen
- constructor is converted into the required QBrush by default) and
- draw the circle. If the widget's preferred precision is float
- based, we specify the circle's bounding rectangle using QRectF and
- double values, otherwise we use QRect and integers.
-
- The animation is controlled by the public \c nextAnimationFrame()
- slot: Whenever the \c nextAnimationFrame() slot is called the
- number of frames is incremented and a paint event is
- scheduled. Then, when the widget is repainted, the alpha-blending
- of the circles' colors change and the circles appear as animated.
-
- \section1 Window Class Definition
-
- The Window class inherits QWidget, and is the application's main
- window rendering four \c {CircleWidget}s using different
- combinations of precision and aliasing.
-
- \snippet examples/painting/concentriccircles/window.h 0
-
- We declare the various components of the main window, i.e., the text
- labels and a double array that will hold reference to the four \c
- {CircleWidget}s. In addition we declare the private \c
- createLabel() function to simplify the constructor.
-
- \section1 Window Class Implementation
-
- \snippet examples/painting/concentriccircles/window.cpp 0
-
- In the constructor, we first create the various labels and put
- them in a QGridLayout.
-
- \snippet examples/painting/concentriccircles/window.cpp 1
-
- Then we create a QTimer. The QTimer class is a high-level
- programming interface for timers, and provides repetitive and
- single-shot timers.
-
- We create a timer to facilitate the animation of our concentric
- circles; when we create the four CircleWidget instances (and add
- them to the layout), we connect the QTimer::timeout() signal to
- each of the widgets' \c nextAnimationFrame() slots.
-
- \snippet examples/painting/concentriccircles/window.cpp 2
-
- Before we set the layout and window title for our main window, we
- make the timer start with a timeout interval of 100 milliseconds,
- using the QTimer::start() function. That means that the
- QTimer::timeout() signal will be emitted, forcing a repaint of the
- four \c {CircleWidget}s, every 100 millisecond which is the reason
- the circles appear as animated.
-
- \snippet examples/painting/concentriccircles/window.cpp 3
-
- The private \c createLabel() function is implemented to simlify
- the constructor.
-*/
diff --git a/doc/src/examples/configdialog.qdoc b/doc/src/examples/configdialog.qdoc
deleted file mode 100644
index 9acea72a3b..0000000000
--- a/doc/src/examples/configdialog.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/configdialog
- \title Config Dialog Example
-
- The Config Dialog examples shows how a configuration dialog can be created by
- using an icon view with a stacked widget.
-
- \image configdialog-example.png
-*/
diff --git a/doc/src/examples/customsortfiltermodel.qdoc b/doc/src/examples/customsortfiltermodel.qdoc
deleted file mode 100644
index 61230a7b9a..0000000000
--- a/doc/src/examples/customsortfiltermodel.qdoc
+++ /dev/null
@@ -1,289 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/customsortfiltermodel
- \title Custom Sort/Filter Model Example
-
- The Custom Sort/Filter Model example illustrates how to subclass
- QSortFilterProxyModel to perform advanced sorting and filtering.
-
- \image customsortfiltermodel-example.png Screenshot of the Custom Sort/Filter Model Example
-
- The QSortFilterProxyModel class provides support for sorting and
- filtering data passed between another model and a view.
-
- The model transforms the structure of a source model by mapping
- the model indexes it supplies to new indexes, corresponding to
- different locations, for views to use. This approach allows a
- given source model to be restructured as far as views are
- concerned, without requiring any transformations on the underlying
- data and without duplicating the data in memory.
-
- The Custom Sort/Filter Model example consists of two classes:
-
- \list
-
- \li The \c MySortFilterProxyModel class provides a custom proxy
- model.
-
- \li The \c Window class provides the main application window,
- using the custom proxy model to sort and filter a standard
- item model.
-
- \endlist
-
- We will first take a look at the \c MySortFilterProxyModel class
- to see how the custom proxy model is implemented, then we will
- take a look at the \c Window class to see how the model is
- used. Finally we will take a quick look at the \c main() function.
-
- \section1 MySortFilterProxyModel Class Definition
-
- The \c MySortFilterProxyModel class inherits the
- QSortFilterProxyModel class.
-
- Since QAbstractProxyModel and its subclasses are derived from
- QAbstractItemModel, much of the same advice about subclassing
- normal models also applies to proxy models.
-
- On the other hand, it is worth noting that many of
- QSortFilterProxyModel's default implementations of functions are
- written so that they call the equivalent functions in the relevant
- source model. This simple proxying mechanism may need to be
- overridden for source models with more complex behavior; in this
- example we derive from the QSortFilterProxyModel class to ensure
- that our filter can recognize a valid range of dates, and to
- control the sorting behavior.
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.h 0
-
- We want to be able to filter our data by specifying a given period
- of time. For that reason, we implement the custom \c
- setFilterMinimumDate() and \c setFilterMaximumDate() functions as
- well as the corresponding \c filterMinimumDate() and \c
- filterMaximumDate() functions. We reimplement
- QSortFilterProxyModel's \l
- {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()}
- function to only accept rows with valid dates, and
- QSortFilterProxyModel::lessThan() to be able to sort the senders
- by their email addresses. Finally, we implement a \c dateInRange()
- convenience function that we will use to determine if a date is
- valid.
-
- \section1 MySortFilterProxyModel Class Implementation
-
- The \c MySortFilterProxyModel constructor is trivial, passing the
- parent parameter on to the base class constructor:
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 0
-
- The most interesting parts of the \c MySortFilterProxyModel
- implementation are the reimplementations of
- QSortFilterProxyModel's \l
- {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()}
- and \l {QSortFilterProxyModel::lessThan()}{lessThan()}
- functions. Let's first take a look at our customized \c lessThan()
- function.
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 4
-
- We want to sort the senders by their email addresses. The \l
- {QSortFilterProxyModel::}{lessThan()} function is used as the <
- operator when sorting. The default implementation handles a
- collection of types including QDateTime and String, but in order
- to be able to sort the senders by their email addresses we must
- first identify the address within the given string:
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6
-
- We use QRegExp to define a pattern for the addresses we are looking
- for. The QRegExp::indexIn() function attempts to find a match in
- the given string and returns the position of the first match, or
- -1 if there was no match. If the given string contains the
- pattern, we use QRegExp's \l {QRegExp::cap()}{cap()} function to
- retrieve the actual address. The \l {QRegExp::cap()}{cap()}
- function returns the text captured by the \e nth
- subexpression. The entire match has index 0 and the parenthesized
- subexpressions have indexes starting from 1 (excluding
- non-capturing parentheses).
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3
-
- The \l
- {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()}
- function, on the other hand, is expected to return true if the
- given row should be included in the model. In our example, a row
- is accepted if either the subject or the sender contains the given
- regular expression, and the date is valid.
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 7
-
- We use our custom \c dateInRange() function to determine if a date
- is valid.
-
- To be able to filter our data by specifying a given period of
- time, we also implement functions for getting and setting the
- minimum and maximum dates:
-
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 1
- \codeline
- \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 2
-
- The get functions, \c filterMinimumDate() and \c
- filterMaximumDate(), are trivial and implemented as inline
- function in the header file.
-
- This completes our custom proxy model. Let's see how we can use it
- in an application.
-
- \section1 Window Class Definition
-
- The \c CustomFilter class inherits QWidget, and provides this
- example's main application window:
-
- \snippet examples/itemviews/customsortfiltermodel/window.h 0
-
- We implement two private slots, \c textFilterChanged() and \c
- dateFilterChanged(), to respond to the user changing the filter
- pattern, case sensitivity or any of the dates. In addition, we
- implement a public \c setSourceModel() convenience function to set
- up the model/ view relation.
-
- \section1 Window Class Implementation
-
- In this example, we have chosen to create and set the source model
- in the \c main () function (which we will come back to later). So
- when constructing the main application window, we assume that a
- source model already exists and start by creating an instance of
- our custom proxy model:
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 0
-
- We set the \l
- {QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter}
- property that holds whether the proxy model is dynamically sorted
- and filtered. By setting this property to true, we ensure that the
- model is sorted and filtered whenever the contents of the source
- model change.
-
- The main application window shows views of both the source model
- and the proxy model. The source view is quite simple:
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 1
-
- The QTreeView class provides a default model/view implementation
- of a tree view; our view implements a tree representation of items
- in the application's source model.
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 2
-
- The QTreeView class provides a default model/view implementation
- of a tree view; our view implements a tree representation of items
- in the application's source model. We add our view widget to a
- layout that we install on a corresponding group box.
-
- The proxy model view, on the other hand, contains several widgets
- controlling the various aspects of transforming the source model's
- data structure:
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 3
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 4
-
- Note that whenever the user changes one of the filtering options,
- we must explicitly reapply the filter. This is done by connecting
- the various editors to functions that update the proxy model.
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 5
-
- The sorting will be handled by the view. All we have to do is to
- enable sorting for our proxy view by setting the
- QTreeView::sortingEnabled property (which is false by
- default). Then we add all the filtering widgets and the proxy view
- to a layout that we install on a corresponding group box.
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 6
-
- Finally, after putting our two group boxes into another layout
- that we install on our main application widget, we customize the
- application window.
-
- As mentioned above, we create the source model in the \c main ()
- function, calling the \c Window::setSourceModel() function to make
- the application use it:
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 7
-
- The QSortFilterProxyModel::setSourceModel() function makes the
- proxy model process the data in the given model, in this case out
- mail model. The \l {QAbstractItemView::}{setModel()} that the
- view widget inherits from the QAbstractItemModel class, sets the
- model for the view to present. Note that the latter function will
- also create and set a new selection model.
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 8
-
- The \c textFilterChanged() function is called whenever the user
- changes the filter pattern or the case sensitivity.
-
- We first retrieve the preferred syntax (the QRegExp::PatternSyntax
- enum is used to interpret the meaning of the given pattern), then
- we determine the preferred case sensitivity. Based on these
- preferences and the current filter pattern, we set the proxy
- model's \l {QSortFilterProxyModel::}{filterRegExp} property. The
- \l {QSortFilterProxyModel::}{filterRegExp} property holds the
- regular expression used to filter the contents of the source
- model. Note that calling QSortFilterProxyModel's \l
- {QSortFilterProxyModel::}{setFilterRegExp()} function also updates
- the model.
-
- \snippet examples/itemviews/customsortfiltermodel/window.cpp 9
-
- The \c dateFilterChanged() function is called whenever the user
- modifies the range of valid dates. We retrieve the new dates from
- the user interface, and call the corresponding functions (provided
- by our custom proxy model) to set the proxy model's minimum and
- maximum dates. As we explained above, calling these functions also
- updates the model.
-
- \section1 The Main() Function
-
- In this example, we have separated the application from the source
- model by creating the model in the \c main () function. First we
- create the application, then we create the source model:
-
- \snippet examples/itemviews/customsortfiltermodel/main.cpp 0
-
- The \c createMailModel() function is a convenience function
- provided to simplify the constructor. All it does is to create and
- return a model describing a collection of emails. The model is an
- instance of the QStandardItemModel class, i.e., a generic model
- for storing custom data typically used as a repository for
- standard Qt data types. Each mail description is added to the
- model using \c addMail(), another convenience function. See \l
- {itemviews/customsortfiltermodel/main.cpp}{main.cpp} for details.
-*/
diff --git a/doc/src/examples/deform.qdoc b/doc/src/examples/deform.qdoc
deleted file mode 100644
index 8195f90ffa..0000000000
--- a/doc/src/examples/deform.qdoc
+++ /dev/null
@@ -1,51 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/deform
- \title Vector Deformation
-
- This example shows how to use advanced vector techniques to draw text
- using a \c QPainterPath.
-
- \image deform-demo.png
-
- We define a vector deformation field in the shape of a lens and apply
- this to all points in a path. This means that what is rendered on
- screen is not pixel manipulation, but modified vector representations of
- the glyphs themselves. This is visible from the high quality of the
- antialiased edges for the deformed glyphs.
-
- To get a fairly complex path we allow the user to type in text and
- convert the text to paths. This is done using the
- QPainterPath::addText() function.
-
- The lens is drawn using a single call to QPainter::drawEllipse(),
- using a QRadialGradient to fill it with a specialized color
- table, giving the effect of the sun's reflection and a drop
- shadow. The lens is cached as a pixmap for better performance.
-*/
diff --git a/doc/src/examples/diagramscene.qdoc b/doc/src/examples/diagramscene.qdoc
deleted file mode 100644
index ac9ca2f294..0000000000
--- a/doc/src/examples/diagramscene.qdoc
+++ /dev/null
@@ -1,834 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/diagramscene
- \title Diagram Scene Example
-
- This example shows use of Qt's graphics framework.
-
- \image diagramscene.png
-
- The Diagram Scene example is an application in which you can
- create a flowchart diagram. It is possible to add flowchart shapes
- and text and connect the shapes by arrows as shown in the image
- above. The shapes, arrows, and text can be given different
- colors, and it is possible to change the font, style, and
- underline of the text.
-
- The Qt graphics view framework is designed to manage and display
- custom 2D graphics items. The main classes of the framework are
- QGraphicsItem, QGraphicsScene and QGraphicsView. The graphics
- scene manages the items and provides a surface for them.
- QGraphicsView is a widget that is used to render a scene on the
- screen. See the \l{Graphics View Framework} for a more detailed
- description of the framework.
-
- In this example we show how to create such custom graphics
- scenes and items by implementing classes that inherit
- QGraphicsScene and QGraphicsItem.
-
- In particular we show how to:
-
- \list
- \li Create custom graphics items.
- \li Handle mouse events and movement of items.
- \li Implement a graphics scene that can manage our custom items.
- \li Custom painting of items.
- \li Create a movable and editable text item.
- \endlist
-
- The example consists of the following classes:
- \list
- \li \c MainWindow creates the widgets and display
- them in a QMainWindow. It also manages the interaction
- between the widgets and the graphics scene, view and
- items.
- \li \c DiagramItem inherits QGraphicsPolygonItem and
- represents a flowchart shape.
- \li \c TextDiagramItem inherits QGraphicsTextItem and
- represents text items in the diagram. The class adds
- support for moving the item with the mouse, which is not
- supported by QGraphicsTextItem.
- \li \c Arrow inherits QGraphicsLineItem and is an arrow
- that connect two DiagramItems.
- \li \c DiagramScene inherits QGraphicsDiagramScene and
- provides support for \c DiagramItem, \c Arrow and
- \c DiagramTextItem (In addition to the support already
- handled by QGraphicsScene).
- \endlist
-
- \section1 MainWindow Class Definition
-
- \snippet examples/graphicsview/diagramscene/mainwindow.h 0
-
- The \c MainWindow class creates and lays out the widgets in a
- QMainWindow. The class forwards input from the widgets to the
- DiagramScene. It also updates its widgets when the diagram
- scene's text item changes, or a diagram item or a diagram text item
- is inserted into the scene.
-
- The class also deletes items from the scene and handles the
- z-ordering, which decides the order in which items are drawn when
- they overlap each other.
-
- \section1 MainWindow Class Implementation
-
-
- We start with a look at the constructor:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 0
-
- In the constructor we call methods to create the widgets and
- layouts of the example before we create the diagram scene.
- The toolbars must be created after the scene as they connect
- to its signals. We then lay the widgets out in the window.
-
- We connect to the \c itemInserted() and \c textInserted() slots of
- the diagram scenes as we want to uncheck the buttons in the tool
- box when an item is inserted. When an item is selected in
- the scene we receive the \c itemSelected() signal. We use this to
- update the widgets that display font properties if the item
- selected is a \c DiagramTextItem.
-
- The \c createToolBox() function creates and lays out the widgets
- of the \c toolBox QToolBox. We will not examine it with a
- high level of detail as it does not deal with graphics framework
- specific functionality. Here is its implementation:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 21
-
- This part of the function sets up the tabbed widget item that
- contains the flowchart shapes. An exclusive QButtonGroup always
- keeps one button checked; we want the group to allow all buttons
- to be unchecked.
- We still use a button group since we can associate user
- data, which we use to store the diagram type, with each button.
- The \c createCellWidget() function sets up the buttons in the
- tabbed widget item and is examined later.
-
- The buttons of the background tabbed widget item is set up in the
- same way, so we skip to the creation of the tool box:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 22
-
- We set the preferred size of the toolbox as its maximum. This
- way, more space is given to the graphics view.
-
- Here is the \c createActions() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 23
-
- We show an example of the creation of an action. The
- functionality the actions trigger is discussed in the slots we
- connect the actions to. You can see the \l{Application
- Example}{application example} if you need a high-level
- introduction to actions.
-
- The is the \c createMenus() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 24
-
- We create the three menus' of the example.
-
- The \c createToolbars() function sets up the examples tool
- bars. The three \l{QToolButton}s in the \c colorToolBar, the \c
- fontColorToolButton, \c fillColorToolButton, and \c
- lineColorToolButton, are interesting as we create icons for them
- by drawing on a QPixmap with a QPainter. We show how the \c
- fillColorToolButton is created. This button lets the user select a
- color for the diagram items.
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 25
- \dots
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 26
-
- We set the menu of the tool button with
- \l{QToolButton::}{setMenu()}. We need the \c fillAction QAction
- object to always be pointing to the selected action of the menu.
- The menu is created with the \c createColorMenu() function and, as
- we shall see later, contains one menu item for each color that the
- items can have. When the user presses the button, which trigger
- the \l{QToolButton::}{clicked()} signal, we can set the color of
- the selected item to the color of \c fillAction. It is with \c
- createColorToolButtonIcon() we create the icon for the button.
-
- \dots
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 27
-
- Here is the \c createBackgroundCellWidget() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 28
-
- This function creates \l{QWidget}s containing a tool button
- and a label. The widgets created with this function are used for
- the background tabbed widget item in the tool box.
-
- Here is the \c createCellWidget() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 29
-
- This function returns a QWidget containing a QToolButton with
- an image of one of the \c DiagramItems, i.e., flowchart shapes.
- The image is created by the \c DiagramItem through the \c image()
- function. The QButtonGroup class lets us attach an id (int) with
- each button; we store the diagram's type, i.e., the
- DiagramItem::DiagramType enum. We use the stored diagram type when
- we create new diagram items for the scene. The widgets created
- with this function is used in the tool box.
-
- Here is the \c createColorMenu() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 30
-
- This function creates a color menu that is used as the
- drop-down menu for the tool buttons in the \c colorToolBar. We
- create an action for each color that we add to the menu. We fetch
- the actions data when we set the color of items, lines, and text.
-
- Here is the \c createColorToolButtonIcon() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 31
-
- This function is used to create the QIcon of the \c
- fillColorToolButton, \c fontColorToolButton, and \c
- lineColorToolButton. The \a imageFile string is either the text,
- flood-fill, or line symbol that is used for the buttons. Beneath
- the image we draw a filled rectangle using \a color.
-
- Here is the \c createColorIcon() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 32
-
- This function creates an icon with a filled rectangle in the
- color of \a color. It is used for creating icons for the color
- menus in the \c fillColorToolButton, \c fontColorToolButton, and
- \c lineColorToolButton.
-
- Here is the \c backgroundButtonGroupClicked() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 1
-
- In this function we set the QBrush that is used to draw the
- background of the diagramscene. The background can be a grid of
- squares of blue, gray, or white tiles, or no grid at all. We have
- \l{QPixmap}s of the tiles from png files that we create the brush
- with.
-
- When one of the buttons in the background tabbed widget item is
- clicked we change the brush; we find out which button it is by
- checking its text.
-
- Here is the implementation of \c buttonGroupClicked():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 2
-
- This slot is called when a button in \c buttonGroup is checked.
- When a button is checked the user can click on the graphics view
- and a \c DiagramItem of the selected type will be inserted into
- the \c DiagramScene. We must loop through the buttons in the group
- to uncheck other buttons as only one button is allowed to be
- checked at a time.
-
- \c QButtonGroup assigns an id to each button. We have set the id
- of each button to the diagram type, as given by DiagramItem::DiagramType
- that will be inserted into the scene when it is clicked. We can
- then use the button id when we set the diagram type with
- \c setItemType(). In the case of text we assigned an id that has a
- value that is not in the DiagramType enum.
-
- Here is the implementation of \c deleteItem():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 3
-
- This slot deletes the selected item, if any, from the scene. It
- deletes the arrows first in order to avoid to delete them twice. If
- the item to be deleted is a \c DiagramItem, we also need to delete
- arrows connected to it; we don't want arrows in the scene that
- aren't connected to items in both ends.
-
- This is the implementation of pointerGroupClicked():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 4
-
- The \c pointerTypeGroup decides whether the scene is in ItemMove
- or InsertLine mode. This button group is exclusive, i.e., only
- one button is checked at any time. As with the \c buttonGroup above
- we have assigned an id to the buttons that matches values of the
- DiagramScene::Mode enum, so that we can use the id to set the
- correct mode.
-
- Here is the \c bringToFront() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 5
-
- Several items may collide, i.e., overlap, with each other in
- the scene. This slot is called when the user requests that an
- item should be placed on top of the items it collides with.
- \l{QGraphicsItem}{QGrapicsItems} have a z-value that decides the
- order in which items are stacked in the scene; you can think of it
- as the z-axis in a 3D coordinate system. When items collide the
- items with higher z-values will be drawn on top of items with
- lower values. When we bring an item to the front we can loop
- through the items it collides with and set a z-value that is
- higher than all of them.
-
- Here is the \c sendToBack() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 6
-
- This slot works in the same way as \c bringToFront() described
- above, but sets a z-value that is lower than items the item that
- should be send to the back collides with.
-
- This is the implementation of \c itemInserted():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 7
-
- This slot is called from the \c DiagramScene when an item has been
- added to the scene. We set the mode of the scene back to the mode
- before the item was inserted, which is ItemMove or InsertText
- depending on which button is checked in the \c pointerTypeGroup.
- We must also uncheck the button in the in the \c buttonGroup.
-
- Here is the implementation of \c textInserted():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 8
-
- We simply set the mode of the scene back to the mode it had before
- the text was inserted.
-
- Here is the \c currentFontChanged() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 9
-
- When the user requests a font change, by using one of the
- widgets in the \c fontToolBar, we create a new QFont object and
- set its properties to match the state of the widgets. This is done
- in \c handleFontChange(), so we simply call that slot.
-
- Here is the \c fontSizeChanged() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 10
-
- When the user requests a font change, by using one of the
- widgets in the \c fontToolBar, we create a new QFont object and
- set its properties to match the state of the widgets. This is done
- in \c handleFontChange(), so we simply call that slot.
-
- Here is the implementation of \c sceneScaleChanged():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 11
-
- The user can increase or decrease the scale, with the \c
- sceneScaleCombo, the scene is drawn in.
- It is not the scene itself that changes its scale, but only the
- view.
-
- Here is the \c textColorChanged() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 12
-
- This slot is called when an item in the drop-down menu of the \c
- fontColorToolButton is pressed. We need to change the icon on
- the button to the color of the selected QAction. We keep a pointer
- to the selected action in \c textAction. It is in \c
- textButtonTriggered() we change the text color to the color of \c
- textAction, so we call that slot.
-
- Here is the \c itemColorChanged() implementation:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 13
-
- This slot handles requests for changing the color of \c
- DiagramItems in the same manner as \c textColorChanged() does for
- \c DiagramTextItems.
-
- Here is the implementation of \c lineColorChanged():
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 14
-
- This slot handles requests for changing the color of \c Arrows in
- the same manner that \c textColorChanged() does it for \c
- DiagramTextItems.
-
- Here is the \c textButtonTriggered() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 15
-
- \c textAction points to the QAction of the currently selected menu item
- in the \c fontColorToolButton's color drop-down menu. We have set
- the data of the action to the QColor the action represents, so we
- can simply fetch this when we set the color of text with \c
- setTextColor().
-
- Here is the \c fillButtonTriggered() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 16
-
- \c fillAction points to the selected menu item in the drop-down
- menu of \c fillColorToolButton(). We can therefore use the data of
- this action when we set the item color with \c setItemColor().
-
- Here is the \c lineButtonTriggered() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 17
-
- \c lineAction point to the selected item in the drop-down menu of
- \c lineColorToolButton. We use its data when we set the arrow
- color with \c setLineColor().
-
- Here is the \c handleFontChange() function:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 18
-
- \c handleFontChange() is called when any of the widgets that show
- font properties changes. We create a new QFont object and set its
- properties based on the widgets. We then call the \c setFont()
- function of \c DiagramScene; it is the scene that set the font of
- the \c DiagramTextItems it manages.
-
- Here is the \c itemSelected() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 19
-
- This slot is called when an item in the \c DiagramScene is
- selected. In the case of this example it is only text items that
- emit signals when they are selected, so we do not need to check
- what kind of graphics \a item is.
-
- We set the state of the widgets to match the properties of the
- font of the selected text item.
-
- This is the \c about() slot:
-
- \snippet examples/graphicsview/diagramscene/mainwindow.cpp 20
-
- This slot displays an about box for the example when the user
- selects the about menu item from the help menu.
-
- \section1 DiagramScene Class Definition
-
- The \c DiagramScene class inherits QGraphicsScene and adds
- functionality to handle \c DiagramItems, \c Arrows, and \c
- DiagramTextItems in addition to the items handled by its super
- class.
-
-
- \snippet examples/graphicsview/diagramscene/diagramscene.h 0
-
- In the \c DiagramScene a mouse click can give three different
- actions: the item under the mouse can be moved, an item may be
- inserted, or an arrow may be connected between to diagram items.
- Which action a mouse click has depends on the mode, given by the
- Mode enum, the scene is in. The mode is set with the \c setMode()
- function.
-
- The scene also sets the color of its items and the font of its
- text items. The colors and font used by the scene can be set with
- the \c setLineColor(), \c setTextColor(), \c setItemColor() and \c
- setFont() functions. The type of \c DiagramItem, given by the
- DiagramItem::DiagramType function, to be created when an item is
- inserted is set with the \c setItemType() slot.
-
- The \c MainWindow and \c DiagramScene share responsibility for
- the examples functionality. \c MainWindow handles the following
- tasks: the deletion of items, text, and arrows; moving diagram
- items to the back and front; and setting the scale of the scene.
-
- \section1 DiagramScene Class Implementation
-
-
- We start with the constructor:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 0
-
- The scene uses \c myItemMenu to set the context menu when it
- creates \c DiagramItems. We set the default mode to \c
- DiagramScene::MoveItem as this gives the default behavior of
- QGraphicsScene.
-
- Here is the \c setLineColor() function:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 1
-
- The \c isItemChange function returns true if an \c Arrow item is
- selected in the scene in which case we want to change its color.
- When the \c DiagramScene creates and adds new arrows to the scene
- it will also use the new \a color.
-
- Here is the \c setTextColor() function:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 2
-
- This function sets the color of \c DiagramTextItems equal to the
- way \c setLineColor() sets the color of \c Arrows.
-
- Here is the \c setItemColor() function:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 3
-
- This function sets the color the scene will use when creating
- \c DiagramItems. It also changes the color of a selected \c
- DiagramItem.
-
- This is the implementation of \c setFont():
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 4
-
- Set the font to use for new and selected, if a text item is
- selected, \c DiagramTextItems.
-
- This is the implementation of \c editorLostFocus() slot:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 5
-
- \c DiagramTextItems emit a signal when they loose focus, which is
- connected to this slot. We remove the item if it has no text.
- If not, we would leak memory and confuse the user as the items
- will be edited when pressed on by the mouse.
-
- The \c mousePressEvent() function handles mouse press event's
- different depending on which mode the \c DiagramScene is in. We
- examine its implementation for each mode:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 6
-
- We simply create a new \c DiagramItem and add it to the scene at
- the position the mouse was pressed. Note that the origin of its
- local coordinate system will be under the mouse pointer position.
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 7
-
- The user adds \c Arrows to the scene by stretching a line between
- the items the arrow should connect. The start of the line is fixed
- in the place the user clicked the mouse and the end follows the
- mouse pointer as long as the button is held down. When the user
- releases the mouse button an \c Arrow will be added to the scene
- if there is a \c DiagramItem under the start and end of the line.
- We will see how this is implemented later; here we simply add the
- line.
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 8
-
- The \c DiagramTextItem is editable when the
- Qt::TextEditorInteraction flag is set, else it is movable by the
- mouse. We always want the text to be drawn on top of the other
- items in the scene, so we set the value to a number higher
- than other items in the scene.
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 9
-
- We are in MoveItem mode if we get to the default switch; we
- can then call the QGraphicsScene implementation, which
- handles movement of items with the mouse. We make this call even
- if we are in another mode making it possible to add an item and
- then keep the mouse button pressed down and start moving
- the item. In the case of text items, this is not possible as they
- do not propagate mouse events when they are editable.
-
- This is the \c mouseMoveEvent() function:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 10
-
- We must draw the line if we are in InsertMode and the mouse button
- is pressed down (the line is not 0). As discussed in \c
- mousePressEvent() the line is drawn from the position the mouse
- was pressed to the current position of the mouse.
-
- If we are in MoveItem mode, we call the QGraphicsScene
- implementation, which handles movement of items.
-
- In the \c mouseReleaseEvent() function we need to check if an arrow
- should be added to the scene:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 11
-
- First we need to get the items (if any) under the line's start
- and end points. The line itself is the first item at these points,
- so we remove it from the lists. As a precaution, we check if the
- lists are empty, but this should never happen.
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 12
-
- Now we check if there are two different \c DiagramItems under
- the lines start and end points. If there are we can create an \c
- Arrow with the two items. The arrow is then added to each item and
- finally the scene. The arrow must be updated to adjust its start
- and end points to the items. We set the z-value of the arrow to
- -1000.0 because we always want it to be drawn under the items.
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 13
-
- Here is the \c isItemChange() function:
-
- \snippet examples/graphicsview/diagramscene/diagramscene.cpp 14
-
- The scene has single selection, i.e., only one item can be
- selected at any given time. The foreach will then loop one time
- with the selected item or none if no item is selected. \c
- isItemChange() is used to check whether a selected item exists
- and also is of the specified diagram \a type.
-
- \section1 DiagramItem Class Definition
-
-
- \snippet examples/graphicsview/diagramscene/diagramitem.h 0
-
- The \c DiagramItem represents a flowchart shape in the \c
- DiagramScene. It inherits QGraphicsPolygonItem and has a polygon
- for each shape. The enum DiagramType has a value for each of the
- flowchart shapes.
-
- The class has a list of the arrows that are connected to it.
- This is necessary because only the item knows when it is being
- moved (with the \c itemChanged() function) at which time the
- arrows must be updated. The item can also draw itself onto a
- QPixmap with the \c image() function. This is used for the tool
- buttons in \c MainWindow, see \c createColorToolButtonIcon() in
- \c MainWindow.
-
- The Type enum is a unique identifier of the class. It is used by
- \c qgraphicsitem_cast(), which does dynamic casts of graphics
- items. The UserType constant is the minimum value a custom
- graphics item type can be.
-
- \section1 DiagramItem Class Implementation
-
-
- We start with a look at the constructor:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 0
-
- In the constructor we create the items polygon according to
- \a diagramType. \l{QGraphicsItem}s are not movable or selectable
- by default, so we must set these properties.
-
- Here is the \c removeArrow() function:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 1
-
- \c removeArrow() is used to remove \c Arrow items when they
- or \c DiagramItems they are connected to are removed from the
- scene.
-
- Here is the \c removeArrows() function:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 2
-
- This function is called when the item is removed from the scene
- and removes all arrows that are connected to this item. The arrow
- must be removed from the \c arrows list of both its start and end
- item.
-
- Here is the \c addArrow() function:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 3
-
- This function simply adds the \a arrow to the items \c arrows list.
-
- Here is the \c image() function:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 4
-
- This function draws the polygon of the item onto a QPixmap. In
- this example we use this to create icons for the tool buttons in
- the tool box.
-
- Here is the \c contextMenuEvent() function:
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 5
-
- We show the context menu. As right mouse clicks, which shows the
- menu, don't select items by default we set the item selected with
- \l{QGraphicsItem::}{setSelected()}. This is necessary since an
- item must be selected to change its elevation with the
- \c bringToFront and \c sendToBack actions.
-
- This is the implementation of \c itemChange():
-
- \snippet examples/graphicsview/diagramscene/diagramitem.cpp 6
-
- If the item has moved, we need to update the positions of the
- arrows connected to it. The implementation of QGraphicsItem does
- nothing, so we just return \a value.
-
- \section1 DiagramTextItem Class Definition
-
- The \c TextDiagramItem class inherits QGraphicsTextItem and
- adds the possibility to move editable text items. Editable
- QGraphicsTextItems are designed to be fixed in place and editing
- starts when the user single clicks on the item. With \c
- DiagramTextItem the editing starts with a double click leaving
- single click available to interact with and move it.
-
- \snippet examples/graphicsview/diagramscene/diagramtextitem.h 0
-
- We use \c itemChange() and \c focusOutEvent() to notify the
- \c DiagramScene when the text item loses focus and gets selected.
-
- We reimplement the functions that handle mouse events to make it
- possible to alter the mouse behavior of QGraphicsTextItem.
-
- \section1 DiagramTextItem Implementation
-
- We start with the constructor:
-
- \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 0
-
- We simply set the item movable and selectable, as these flags are
- off by default.
-
- Here is the \c itemChange() function:
-
- \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 1
-
- When the item is selected we emit the selectedChanged signal. The
- \c MainWindow uses this signal to update the widgets that display
- font properties to the font of the selected text item.
-
- Here is the \c focusOutEvent() function:
-
- \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 2
-
- \c DiagramScene uses the signal emitted when the text item looses
- focus to remove the item if it is empty, i.e., it contains no
- text.
-
- This is the implementation of \c mouseDoubleClickEvent():
-
- \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 5
-
- When we receive a double click event, we make the item editable by calling
- QGraphicsTextItem::setTextInteractionFlags(). We then forward the
- double-click to the item itself.
-
- \section1 Arrow Class Definition
-
- The \c Arrow class is a graphics item that connects two \c
- DiagramItems. It draws an arrow head to one of the items. To
- achieve this the item needs to paint itself and also re implement
- methods used by the graphics scene to check for collisions and
- selections. The class inherits QGraphicsLine item, and draws the
- arrowhead and moves with the items it connects.
-
- \snippet examples/graphicsview/diagramscene/arrow.h 0
-
- The item's color can be set with \c setColor().
-
- \c boundingRect() and \c shape() are reimplemented
- from QGraphicsLineItem and are used by the scene
- to check for collisions and selections.
-
- Calling \c updatePosition() causes the arrow to recalculate its
- position and arrow head angle. \c paint() is reimplemented so that
- we can paint an arrow rather than just a line between items.
-
- \c myStartItem and \c myEndItem are the diagram items that the
- arrow connects. The arrow is drawn with its head to the end item.
- \c arrowHead is a polygon with three vertices's we use to draw the
- arrow head.
-
- \section1 Arrow Class Implementation
-
- The constructor of the \c Arrow class looks like this:
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 0
-
- We set the start and end diagram items of the arrow. The arrow
- head will be drawn where the line intersects the end item.
-
- Here is the \c boundingRect() function:
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 1
-
- We need to reimplement this function because the arrow is
- larger than the bounding rectangle of the QGraphicsLineItem. The
- graphics scene uses the bounding rectangle to know which regions
- of the scene to update.
-
- Here is the \c shape() function:
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 2
-
- The shape function returns a QPainterPath that is the exact
- shape of the item. The QGraphicsLineItem::shape() returns a path
- with a line drawn with the current pen, so we only need to add
- the arrow head. This function is used to check for collisions and
- selections with the mouse.
-
- Here is the \c updatePosition() slot:
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 3
-
- This slot updates the arrow by setting the start and end
- points of its line to the center of the items it connects.
-
- Here is the \c paint() function:
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 4
-
- If the start and end items collide we do not draw the arrow; the
- algorithm we use to find the point the arrow should be drawn at
- may fail if the items collide.
-
- We first set the pen and brush we will use for drawing the arrow.
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 5
-
- We then need to find the position at which to draw the
- arrowhead. The head should be drawn where the line and the end
- item intersects. This is done by taking the line between each
- point in the polygon and check if it intersects with the line of
- the arrow. Since the line start and end points are set to the
- center of the items the arrow line should intersect one and only
- one of the lines of the polygon. Note that the points in the
- polygon are relative to the local coordinate system of the item.
- We must therefore add the position of the end item to make the
- coordinates relative to the scene.
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 6
-
- We calculate the angle between the x-axis and the line of the
- arrow. We need to turn the arrow head to this angle so that it
- follows the direction of the arrow. If the angle is negative we
- must turn the direction of the arrow.
-
- We can then calculate the three points of the arrow head polygon.
- One of the points is the end of the line, which now is the
- intersection between the arrow line and the end polygon. Then we
- clear the \c arrowHead polygon from the previous calculated arrow
- head and set these new points.
-
- \snippet examples/graphicsview/diagramscene/arrow.cpp 7
-
- If the line is selected, we draw two dotted lines that are
- parallel with the line of the arrow. We do not use the default
- implementation, which uses \l{QGraphicsItem::}{boundingRect()}
- because the QRect bounding rectangle is considerably larger than
- the line.
-*/
diff --git a/doc/src/examples/digitalclock.qdoc b/doc/src/examples/digitalclock.qdoc
deleted file mode 100644
index 39d015efd1..0000000000
--- a/doc/src/examples/digitalclock.qdoc
+++ /dev/null
@@ -1,74 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/digitalclock
- \title Digital Clock Example
-
- The Digital Clock example shows how to use QLCDNumber to display a
- number with LCD-like digits.
-
- \image digitalclock-example.png Screenshot of the Digital Clock example
-
- This example also demonstrates how QTimer can be used to update a widget
- at regular intervals.
-
- \section1 DigitalClock Class Definition
-
- The \c DigitalClock class provides a clock widget showing the time with
- hours and minutes separated by a blinking colon. We subclass QLCDNumber
- and implement a private slot called \c showTime() to update the clock
- display:
-
- \snippet examples/widgets/digitalclock/digitalclock.h 0
-
- \section1 DigitalClock Class Implementation
-
- \snippet examples/widgets/digitalclock/digitalclock.cpp 0
-
- In the constructor, we first change the look of the LCD numbers. The
- QLCDNumber::Filled style produces raised segments filled with the
- foreground color (typically black). We also set up a one-second timer
- to keep track of the current time, and we connect
- its \l{QTimer::timeout()}{timeout()} signal to the private \c showTime() slot
- so that the display is updated every second. Then, we
- call the \c showTime() slot; without this call, there would be a one-second
- delay at startup before the time is shown.
-
- \snippet examples/widgets/digitalclock/digitalclock.cpp 1
- \snippet examples/widgets/digitalclock/digitalclock.cpp 2
-
- The \c showTime() slot is called whenever the clock display needs
- to be updated.
-
- The current time is converted into a string with the format "hh:mm".
- When QTime::second() is a even number, the colon in the string is
- replaced with a space. This makes the colon appear and vanish every
- other second.
-
- Finally, we call QLCDNumber::display() to update the widget.
-*/
diff --git a/doc/src/examples/dirview.qdoc b/doc/src/examples/dirview.qdoc
deleted file mode 100644
index a4b799678a..0000000000
--- a/doc/src/examples/dirview.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/dirview
- \title Dir View Example
-
- The Dir View example shows a tree view onto the local filing system. It uses the
- QDirModel class to provide file and directory information.
-
- \image dirview-example.png
-*/
diff --git a/doc/src/examples/dockwidgets.qdoc b/doc/src/examples/dockwidgets.qdoc
deleted file mode 100644
index 8c64c78ae4..0000000000
--- a/doc/src/examples/dockwidgets.qdoc
+++ /dev/null
@@ -1,163 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/dockwidgets
- \title Dock Widgets Example
-
- The Dock Widgets example shows how to add dock windows to an
- application. It also shows how to use Qt's rich text engine.
-
- \image dockwidgets-example.png Screenshot of the Dock Widgets example
-
- The application presents a simple business letter template, and has
- a list of customer names and addresses and a list of standard
- phrases in two dock windows. The user can click a customer to have
- their name and address inserted into the template, and click one or
- more of the standard phrases. Errors can be corrected by clicking
- the Undo button. Once the letter has been prepared it can be printed
- or saved as HTML.
-
- \section1 MainWindow Class Definition
-
- Here's the class definition:
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.h 0
-
- We will now review each function in turn.
-
- \section1 MainWindow Class Implementation
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 0
-
- We start by including \c <QtGui>, a header file that contains the
- definition of all classes in the \l QtCore and \l QtGui
- libraries. This saves us from having to include
- every class individually and is especially convenient if we add new
- widgets. We also include \c mainwindow.h.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 1
-
- In the constructor, we start by creating a QTextEdit widget. Then we call
- QMainWindow::setCentralWidget(). This function passes ownership of
- the QTextEdit to the \c MainWindow and tells the \c MainWindow that
- the QTextEdit will occupy the \c MainWindow's central area.
-
- Then we call \c createActions(), \c createMenus(), \c
- createToolBars(), \c createStatusBar(), and \c createDockWindows()
- to set up the user interface. Finally we call \c setWindowTitle() to
- give the application a title, and \c newLetter() to create a new
- letter template.
-
- We won't quote the \c createActions(), \c createMenus(), \c
- createToolBars(), and \c createStatusBar() functions since they
- follow the same pattern as all the other Qt examples.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 9
-
- We create the customers dock window first, and in addition to a
- window title, we also pass it a \c this pointer so that it becomes a
- child of \c MainWindow. Normally we don't have to pass a parent
- because widgets are parented automatically when they are laid out:
- but dock windows aren't laid out using layouts.
-
- We've chosen to restrict the customers dock window to the left and
- right dock areas. (So the user cannot drag the dock window to the
- top or bottom dock areas.) The user can drag the dock window out of
- the dock areas entirely so that it becomes a free floating window.
- We can change this (and whether the dock window is moveable or
- closable) using QDockWidget::setFeatures().
-
- Once we've created the dock window we create a list widget with the
- dock window as parent, then we populate the list and make it the
- dock window's widget. Finally we add the dock widget to the \c
- MainWindow using \c addDockWidget(), choosing to put it in the right
- dock area.
-
- We undertake a similar process for the paragraphs dock window,
- except that we don't restrict which dock areas it can be dragged to.
-
- Finally we set up the signal-slot connections. If the user clicks a
- customer or a paragraph their \c currentTextChanged() signal will be
- emitted and we connect these to \c insertCustomer() and
- addParagraph() passing the text that was clicked.
-
- We briefly discuss the rest of the implementation, but have now
- covered everything relating to dock windows.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 2
-
- In this function we clear the QTextEdit so that it is empty. Next we
- create a QTextCursor on the QTextEdit. We move the cursor to the
- start of the document and create and format a frame. We then create
- some character formats and a table format. We insert a table into
- the document and insert the company's name and address into a table
- using the table and character formats we created earlier. Then we
- insert the skeleton of the letter including two markers \c NAME and
- \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 6
-
- If the user clicks a customer we split the customer details into
- pieces. We then look for the \c NAME marker using the \c find()
- function. This function selects the text it finds, so when we call
- \c insertText() with the customer's name the name replaces the marker.
- We then look for the \c ADDRESS marker and replace it with each line
- of the customer's address. Notice that we wrapped all the insertions
- between a \c beginEditBlock() and \c endEditBlock() pair. This means
- that the entire name and address insertion is treated as a single
- operation by the QTextEdit, so a single undo will revert all the
- insertions.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 7
-
- This function works in a similar way to \c insertCustomer(). First
- we look for the marker, in this case, \c {Yours sincerely,}, and then
- replace it with the standard paragraph that the user clicked. Again
- we use a \c beginEditBlock() ... \c endEditBlock() pair so that the
- insertion can be undone as a single operation.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 3
-
- Qt's QTextDocument class makes printing documents easy. We simply
- take the QTextEdit's QTextDocument, set up the printer and print the
- document.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 4
-
- QTextEdit can output its contents in HTML format, so we prompt the
- user for the name of an HTML file and if they provide one we simply
- write the QTextEdit's contents in HTML format to the file.
-
- \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 5
-
- If the focus is in the QTextEdit, pressing \uicontrol Ctrl+Z undoes as
- expected. But for the user's convenience we provide an
- application-wide undo function that simply calls the QTextEdit's
- undo: this means that the user can undo regardless of where the
- focus is in the application.
-*/
diff --git a/doc/src/examples/dragdroprobot.qdoc b/doc/src/examples/dragdroprobot.qdoc
deleted file mode 100644
index c6563a5286..0000000000
--- a/doc/src/examples/dragdroprobot.qdoc
+++ /dev/null
@@ -1,365 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/dragdroprobot
- \title Drag and Drop Robot Example
-
- The Drag and Drop Robot example shows how to implement Drag and Drop in a
- QGraphicsItem subclass, as well as how to animate items using Qt's
- \l{Animation Framework}.
-
- \image dragdroprobot-example.png
-
- Graphics View provides the QGraphicsScene class for managing and
- interacting with a large number of custom-made 2D graphical items derived
- from the QGraphicsItem class, and a QGraphicsView widget for visualizing
- the items, with support for zooming and rotation.
-
- This example consists of a \c Robot class, a \c ColorItem class, and a main
- function: the \c Robot class describes a simple robot consisting of several
- \c RobotPart derived limbs, including \c RobotHead and \c RobotLimb, the \c
- ColorItem class provides a draggable colored ellipse, and the \c main()
- function provides the main application window.
-
- We will first review the \c Robot class to see how to assemble the
- different parts so that they can be individually rotated and animated using
- QPropertyAnimation, and we will then review the \c ColorItem class to
- demonstrate how to implement Drag and Drop between items. Finally we will
- review the main() function to see how we can put all the pieces together,
- to form the final application.
-
- \section1 Robot Class Definition
-
- The robot consists of three main classes: the \c RobotHead, the \c
- RobotTorso, and the \c RobotLimb, which is used for the upper and lower
- arms and legs. All parts derive from the \c RobotPart class, which in turn
- inherits \c QGraphicsObject. The \c Robot class itself has no visual
- appearance and serves only as a root node for the robot.
-
- Let's start with the \c RobotPart class declaration.
-
- \snippet examples/graphicsview/dragdroprobot/robot.h 0
-
- This base class inherits QGraphicsObject. QGraphicsObject provides signals
- and slots through inheriting QObject, and it also declares QGraphicsItem's
- properties using Q_PROPERTY, which makes the properties accessible for
- QPropertyAnimation.
-
- RobotPart also implements the three most important event handlers for
- accepting drop events:
- \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()},
- \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()}, and
- \l{QGraphicsItem::dropEvent()}{dropEvent()}.
-
- The color is stored as a member variable, along with the \c dragOver
- variable, which we will use later to indicate visually that the limb can
- accept colors that are is dragged onto it.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 0
-
- \c RobotPart's constructor initializes the dragOver member and sets the
- color to Qt::lightGray. In the constructor body we enable support for
- accepting drop events by calling
- \l{QGraphicsItem::setAcceptDrops()}{setAcceptDrops(true)}.
-
- The rest of this class's implementation is to support Drag and Drop.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 1
-
- The \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} handler is called
- when a Drag and Drop element is dragged into the robot part's area.
-
- The handler implementation determines whether or not this item as a whole
- can accept the mime data assiciated with the incoming drag object. \c
- RobotPart provides a base behavior for all parts that accepts color drops.
- So if the incoming drag object contains a color, the event is accepted, we
- set \c dragOver to \c true and call update() to help provide positive
- visual feedback to the user; otherwise the event is ignored, which in turn
- allows the event to propagate to parent elements.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 2
-
- The \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()} handler is called
- when a Drag and Drop element is dragged away from the robot part's area.
- Our implementation simply resets \e dragOver to false and calls
- \l{QGraphicsItem::update()}{update()} to help provide visual feedback that
- the drag has left this item.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 3
-
- The \l{QGraphicsItem::dropEvent()}{dropEvent()} handler is called when a
- Drag and Drop element is dropped onto an item (i.e., when the mouse button
- is released over the item while dragging).
-
- We reset \c dragOver to false, assign the item's new color, and call
- \l{QGraphicsItem::update()}{update()}.
-
- The declaration and implementation of \c RobotHead, \c RobotTorso, and \c
- RobotLimb are practically identical. We will review \c RobotHead in detail,
- as this class has one minor difference, and leave the other classes as an
- exercise for the reader.
-
- \snippet examples/graphicsview/dragdroprobot/robot.h 1
-
- The \c RobotHead class inherits \c RobotPart and provides the necessary
- implementations of \l{QGraphicsItem::boundingRect()}{boundingRect()} and
- \l{QGraphicsItem::paint()}{paint()}. It also reimplements
- \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} and dropEvent() to
- provide special handling of image drops.
-
- The class contains a private pixmap member that we can use to implement
- support for accepting image drops.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 4
-
- \c RobotHead has a rather plain constructor that simply forwards to
- \c RobotPart's constructor.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 5
-
- The \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation
- returns the extents for the head. Because we want the center of rotation to
- be the bottom center of the item, we have chosen a bounding rectangle that
- starts at (-15, -50) and extends to 30 units wide and 50 units tall. When
- rotating the head, the "neck" will stay still while the top of the head
- tilts from side to side.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 6
-
- In \l{QGraphicsItem::paint()}{paint()} we draw the actual head. The
- implementation is split into two sections; if an image has been dropped
- onto the head, we draw the image, otherwise we draw a round rectangular
- robot head with simple vector graphics.
-
- For performance reasons, depending on the complexity of what is painted, it
- can often be faster to draw the head as an image rather than using a
- sequence of vector operations.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 7
-
- The robot head can accept image drops. In order to support this, its
- reimplementation of \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()}
- checks if the drag object contains image data, and if it does, then the
- event is accepted. Otherwise we fall back to the base \c RobotPart
- implementation.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 8
-
- To follow up on image support, we must also implement
- \l{QGraphicsItem::dropEvent()}{dropEvent()}. We check if the drag object
- contains image data, and if it does, we store this data as a member pixmap
- and call \l{QGraphicsItem::update()}{update()}. This pixmap is used inside
- the \l{QGraphicsItem::paint()}{paint()} implementation that we reviewed
- before.
-
- \c RobotTorso and \c RobotLimb are similar to \c RobotHead, so let's
- skip directly to the \c Robot class.
-
- \snippet examples/graphicsview/dragdroprobot/robot.h 4
-
- The \c Robot class also inherits \c RobotPart, and like the other parts it
- also implements \l{QGraphicsItem::boundingRect()}{boundingRect()} and
- \l{QGraphicsItem::paint()}{paint()}. It provides a rather special
- implementation, though:
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 9
-
- Because the \c Robot class is only used as a base node for the rest of the
- robot, it has no visual representation. Its
- \l{QGraphicsItem::boundingRect()}{boundingRect()} implementation can
- therefore return a null QRectF, and its paint() function does nothing.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 10
-
- The constructor starts by setting the flag
- \l{QGraphicsItem::ItemHasNoContents}{ItemHasNoContents}, which is a minor
- optimization for items that have no visual appearance.
-
- We then construct all the robot parts (head, torso, and upper/lower arms
- and legs). The stacking order is very important, and we use the
- parent-child hierarchy to ensure the elements rotate and move properly. We
- construct the torso first, as this is the root element. We then construct
- the head and pass the torso to \c HeadItem's constructor. This will make
- the head a child of the torso; if you rotate the torso, the head will
- follow. The same pattern is applied to the rest of the limbs.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 11
-
- Each robot part is carefully positioned. For example, the upper left arm is
- moved precisely to the top-left area of the torso, and the upper right arm
- is moved to the top-right area.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 12
-
- The next section creates all animation objects. This snippet shows the two
- animations that operate on the head's scale and rotation. The two
- QPropertyAnimation instances simply set the object, property, and
- respective start and end values.
-
- All animations are controlled by one top-level parallel animation group.
- The scale and rotation animations are added to this group.
-
- The rest of the animations are defined in a similar way.
-
- \snippet examples/graphicsview/dragdroprobot/robot.cpp 13
-
- Finally we set an easing curve and duration on each animation, ensure the
- toplevel animation group loops forever, and start the toplevel animation.
-
- \section1 ColorItem Class Definition
-
- The \c ColorItem class represents a circular item that can be pressed to
- drag colors onto robot parts.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.h 0
-
- This class is very simple. It does not use animations, and has no need for
- properties nor signals and slots, so to save resources, it's most natural
- that it inherits QGraphicsItem (as opposed to QGraphicsObject).
-
- It declares the mandatory \l{QGraphicsItem::boundingRect()}{boundingRect()}
- and \l{QGraphicsItem::paint()}{paint()} functions, and adds
- reimplementations of
- \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()},
- \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()}, and
- \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()}. It contains a
- single private color member.
-
- Let's take a look at its implementation.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 0
-
- \c ColorItem's constructor assigns an opaque random color to its color
- member by making use of qrand(). For improved usability, it assigns a
- tooltip that provides a useful hint to the user, and it also sets a
- suitable cursor. This ensures that the cursor will chance to
- Qt::OpenHandCursor when the mouse pointer hovers over the item.
-
- Finally, we call
- \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons()} to
- ensure that this item can only process Qt::LeftButton. This simplifies the
- mouse event handlers greatly, as we can always assume that only the left
- mouse button is pressed and released.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 1
-
- The item's bounding rect is a fixed 30x30 units centered around the item's
- origin (0, 0), and adjusted by 0.5 units in all directions to allow a
- scalable pen to draw its outline. For a final visual touch the bounds
- also compensate with a few units down and to the right to make room
- for a simple dropshadow.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 2
-
- The \l{QGraphicsItem::paint()}{paint()} implementation draws an ellipse
- with a 1-unit black outline, a plain color fill, and a dark gray
- dropshadow.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 3
-
- The \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} handler is
- called when you press the mouse button inside the item's area. Our
- implementation simply sets the cursor to Qt::ClosedHandCursor.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 4
-
- The \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} handler is
- called when you release the mouse button after having pressed it inside an
- item's area. Our implementation sets the cursor back to Qt::OpenHandCursor.
- The mouse press and release event handlers together provide useful visual
- feedback to the user: when you move the mouse pointer over a \c CircleItem,
- the cursor changes to an open hand. Pressing the item will show a closed
- hand cursor. Releasing will restore to an open hand cursor again.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 5
-
- The \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()} handler is called
- when you move the mouse around after pressing the mouse button inside the
- \c ColorItem's area. This implementation provides the most important piece
- of logic for \c CircleItem: the code that starts and manages drags.
-
- The implementation starts by checking if the mouse has been dragged far
- enough to eliminate mouse jitter noise. We only want to start a drag if the
- mouse has been dragged farther than the application start drag distance.
-
- Continuing, we create a QDrag object, passing the event
- \l{QGraphicsSceneEvent::widget()}{widget} (i.e., the QGraphicsView
- viewport) to its constructor. Qt will ensure that this object is deleted at
- the right time. We also create a QMimeData instance that can contain our
- color or image data, and assign this to the drag object.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 6
-
- This snippet has a somewhat random outcome: once in a while, a special
- image is assigned to the drag object's mime data. The pixmap is also
- assiged as the drag object's pixmap. This will ensure that you can see the
- image that is being dragged as a pixmap under the mouse cursor.
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 7
-
- Otherwise, and this is the most common outcome, a simple color is assigned
- to the drag object's mime data. We render this \c ColorItem into a new
- pixmap to give the user visual feedback that the color is being "dragged".
-
- \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 8
-
- Finally we execute the drag. QDrag::exec() will reenter the event loop, and
- only exit if the drag has either been dropped, or canceled. In any case we
- reset the cursor to Qt::OpenHandCursor.
-
- \section1 The main() Function
-
- Now that the \c Robot and \c ColorItem classes are complete, we can put all
- the pieces together inside the main() function.
-
- \snippet examples/graphicsview/dragdroprobot/main.cpp 0
-
- We start off by constructing QApplication, and initializing the random
- number generator. This ensures that the color items have different colors
- every time the application starts.
-
- \snippet examples/graphicsview/dragdroprobot/main.cpp 1
-
- We construct a fixed size scene, and create 10 \c ColorItem instances
- arranged in a circle. Each item is added to the scene.
-
- In the center of this circle we create one \c Robot instance. The
- robot is scaled and moved up a few units. It is then added to the scene.
-
- \snippet examples/graphicsview/dragdroprobot/main.cpp 2
-
- Finally we create a QGraphicsView window, and assign the scene to it.
-
- For increased visual quality, we enable antialiasing. We also choose to use
- bounding rectangle updates to simplify visual update handling.
- The view is given a fixed sand-colored background, and a window title.
-
- We then show the view. The animations start immediately after
- control enters the event loop.
-*/
-
diff --git a/doc/src/examples/dynamiclayouts.qdoc b/doc/src/examples/dynamiclayouts.qdoc
deleted file mode 100644
index 318f719503..0000000000
--- a/doc/src/examples/dynamiclayouts.qdoc
+++ /dev/null
@@ -1,34 +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$
-**
-****************************************************************************/
-
-/*!
- \example layouts/dynamiclayouts
- \title Dynamic Layouts Example
-
- The Dynamic Layouts example shows how to move widgets around in
- existing layouts.
-*/
diff --git a/doc/src/examples/easing.qdoc b/doc/src/examples/easing.qdoc
deleted file mode 100644
index 7fb7f59531..0000000000
--- a/doc/src/examples/easing.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example animation/easing
- \title Easing Curves Example
-
- The Easing Curves example shows how to use easing curves to
- control the speed of an animation.
-
- \image easing-example.png
-
-*/
diff --git a/doc/src/examples/editabletreemodel.qdoc b/doc/src/examples/editabletreemodel.qdoc
deleted file mode 100644
index 958080ad58..0000000000
--- a/doc/src/examples/editabletreemodel.qdoc
+++ /dev/null
@@ -1,446 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/editabletreemodel
- \title Editable Tree Model Example
-
- This example shows how to implement a simple item-based tree model that can
- be used with other classes the model/view framework.
-
- \image itemviews-editabletreemodel.png
-
- The model supports editable items, custom headers, and the ability to
- insert and remove rows and columns. With these features, it is also
- possible to insert new child items, and this is shown in the supporting
- example code.
-
- \note The model only shows the basic principles used when creating an
- editable, hierarchical model. You may wish to use the \l{ModelTest}
- project to test production models.
-
- \section1 Overview
-
- As described in the \l{Model Subclassing Reference}, models must
- provide implementations for the standard set of model functions:
- \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()},
- \l{QAbstractItemModel::}{headerData()},
- \l{QAbstractItemModel::}{columnCount()}, and
- \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models,
- such as this one, need to provide implementations of
- \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}.
-
- An editable model needs to provide implementations of
- \l{QAbstractItemModel::}{setData()} and
- \l{QAbstractItemModel::}{setHeaderData()}, and must return a suitable
- combination of flags from its \l{QAbstractItemModel::}{flags()} function.
-
- Since this example allows the dimensions of the model to be changed,
- we must also implement \l{QAbstractItemModel::}{insertRows()},
- \l{QAbstractItemModel::}{insertColumns()},
- \l{QAbstractItemModel::}{removeRows()}, and
- \l{QAbstractItemModel::}{removeColumns()}.
-
- \section1 Design
-
- As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example,
- the model simply acts as a wrapper around a collection
- of instances of a \c TreeItem class. Each \c TreeItem is designed to
- hold data for a row of items in a tree view, so it contains a list of
- values corresponding to the data shown in each column.
-
- Since QTreeView provides a row-oriented view onto a model, it is
- natural to choose a row-oriented design for data structures that
- will supply data via a model to this kind of view. Although this makes
- the tree model less flexible, and possibly less useful for use with
- more sophisticated views, it makes it less complex to design and easier
- to implement.
-
- \target Relations-between-internal-items
- \table
- \row \li \inlineimage itemviews-editabletreemodel-items.png
- \li \b{Relations between internal items}
-
- When designing a data structure for use with a custom model, it is useful
- to expose each item's parent via a function like
- \l{TreeItem::parent}{TreeItem::parent()} because it will make
- writing the model's own \l{QAbstractItemModel::}{parent()} function easier.
- Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is
- helpful when implementing the model's \l{QAbstractItemModel::}{index()}
- function. As a result, each \c TreeItem maintains information about
- its parent and children, making it possible for us to traverse the tree
- structure.
-
- The diagram shows how \c TreeItem instances are connected via their
- \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()}
- functions.
-
- In the example shown, two top-level items, \b{A} and
- \b{B}, can be obtained from the root item by calling its child()
- function, and each of these items return the root node from their
- parent() functions, though this is only shown for item \b{A}.
- \endtable
-
- Each \c TreeItem stores data for each column in the row it represents
- in its \c itemData private member (a list of QVariant objects).
- Since there is a one-to-one mapping between each column in the view
- and each entry in the list, we provide a simple
- \l{TreeItem::data}{data()} function to read entries in the \c itemData
- list and a \l{TreeItem::setData}{setData()} function to allow them to
- be modified.
- As with other functions in the item, this simplifies the implemention
- of the model's \l{QAbstractItemModel::}{data()} and
- \l{QAbstractItemModel::}{setData()} functions.
-
- We place an item at the root of the tree of items. This root item
- corresponds to the null model index, \l{QModelIndex::}{QModelIndex()},
- that is used to represent the parent of a top-level item when handling
- model indexes.
- Although the root item does not have a visible representation in any of
- the standard views, we use its internal list of QVariant objects to
- store a list of strings that will be passed to views for use as
- horizontal header titles.
-
- \table
- \row \li \inlineimage itemviews-editabletreemodel-model.png
- \li \b{Accessing data via the model}
-
- In the case shown in the diagram, the piece of information represented
- by \b{a} can be obtained using the standard model/view API:
-
- \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 0
-
- Since each items holds pieces of data for each column in a given row,
- there can be many model indexes that map to the same \c TreeItem object.
- For example, the information represented by \b{b} can be obtained
- using the following code:
-
- \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 1
-
- The same underlying \c TreeItem would be accessed to obtain information
- for the other model indexes in the same row as \b{b}.
- \endtable
-
- In the model class, \c TreeModel, we relate \c TreeItem objects to
- model indexes by passing a pointer for each item when we create its
- corresponding model index with QAbstractItemModel::createIndex() in
- our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()}
- implementations.
- We can retrieve pointers stored in this way by calling the
- \l{QModelIndex::}{internalPointer()} function on the relevant model
- index - we create our own \l{TreeModel::getItem}{getItem()} function to
- do this work for us, and call it from our \l{TreeModel::data}{data()}
- and \l{TreeModel::parent}{parent()} implementations.
-
- Storing pointers to items is convenient when we control how they are
- created and destroyed since we can assume that an address obtained from
- \l{QModelIndex::}{internalPointer()} is a valid pointer.
- However, some models need to handle items that are obtained from other
- components in a system, and in many cases it is not possible to fully
- control how items are created or destroyed. In such situations, a pure
- pointer-based approach needs to be supplemented by safeguards to ensure
- that the model does not attempt to access items that have been deleted.
-
- \table
- \row \li \b{Storing information in the underlying data structure}
-
- Several pieces of data are stored as QVariant objects in the \c itemData
- member of each \c TreeItem instance
-
- The diagram shows how pieces of information,
- represented by the labels \b{a}, \b{b} and \b{c} in the
- previous two diagrams, are stored in items \b{A}, \b{B} and
- \b{C} in the underlying data structure. Note that pieces of
- information from the same row in the model are all obtained from the
- same item. Each element in a list corresponds to a piece of information
- exposed by each column in a given row in the model.
-
- \li \inlineimage itemviews-editabletreemodel-values.png
- \endtable
-
- Since the \c TreeModel implementation has been designed for use with
- QTreeView, we have added a restriction on the way it uses \c TreeItem
- instances: each item must expose the same number of columns of data.
- This makes viewing the model consistent, allowing us to use the root
- item to determine the number of columns for any given row, and only
- adds the requirement that we create items containing enough data for
- the total number of columns. As a result, inserting and removing
- columns are time-consuming operations because we need to traverse the
- entire tree to modify every item.
-
- An alternative approach would be to design the \c TreeModel class so
- that it truncates or expands the list of data in individual \c TreeItem
- instances as items of data are modified. However, this "lazy" resizing
- approach would only allow us to insert and remove columns at the end of
- each row and would not allow columns to be inserted or removed at
- arbitrary positions in each row.
-
- \target Relating-items-using-model-indexes
- \table
- \row
- \li \inlineimage itemviews-editabletreemodel-indexes.png
- \li \b{Relating items using model indexes}
-
- As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example,
- the \c TreeModel needs to be able to take a model index, find the
- corresponding \c TreeItem, and return model indexes that correspond to
- its parents and children.
-
- In the diagram, we show how the model's \l{TreeModel::parent}{parent()}
- implementation obtains the model index corresponding to the parent of
- an item supplied by the caller, using the items shown in a
- \l{Relations-between-internal-items}{previous diagram}.
-
- A pointer to item \b{C} is obtained from the corresponding model index
- using the \l{QModelIndex::internalPointer()} function. The pointer was
- stored internally in the index when it was created. Since the child
- contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()}
- function to obtain a pointer to item \b{B}. The parent model index is
- created using the QAbstractItemModel::createIndex() function, passing
- the pointer to item \b{B} as the internal pointer.
- \endtable
-
- \section1 TreeItem Class Definition
-
- The \c TreeItem class provides simple items that contain several
- pieces of data, and which can provide information about their parent
- and child items:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.h 0
-
- We have designed the API to be similar to that provided by
- QAbstractItemModel by giving each item functions to return the number
- of columns of information, read and write data, and insert and remove
- columns. However, we make the relationship between items explicit by
- providing functions to deal with "children" rather than "rows".
-
- Each item contains a list of pointers to child items, a pointer to its
- parent item, and a list of QVariant objects that correspond to
- information held in columns in a given row in the model.
-
- \section1 TreeItem Class Implementation
-
- Each \c TreeItem is constructed with a list of data and an optional
- parent item:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 0
-
- Initially, each item has no children. These are added to the item's
- internal \c childItems member using the \c insertChildren() function
- described later.
-
- The destructor ensures that each child added to the item is deleted
- when the item itself is deleted:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 1
-
- \target TreeItem::parent
- Since each item stores a pointer to its parent, the \c parent() function
- is trivial:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 9
-
- \target TreeItem::child
- Three functions provide information about the children of an item.
- \c child() returns a specific child from the internal list of children:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 2
-
- The \c childCount() function returns the total number of children:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 3
-
- The \c childNumber() function is used to determine the index of the child
- in its parent's list of children. It accesses the parent's \c childItems
- member directly to obtain this information:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 4
-
- The root item has no parent item; for this item, we return zero to be
- consistent with the other items.
-
- The \c columnCount() function simply returns the number of elements in
- the internal \c itemData list of QVariant objects:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 5
-
- \target TreeItem::data
- Data is retrieved using the \c data() function, which accesses the
- appropriate element in the \c itemData list:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 6
-
- \target TreeItem::setData
- Data is set using the \c setData() function, which only stores values
- in the \c itemData list for valid list indexes, corresponding to column
- values in the model:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 11
-
- To make implementation of the model easier, we return true to indicate
- whether the data was set successfully, or false if an invalid column
-
- Editable models often need to be resizable, enabling rows and columns to
- be inserted and removed. The insertion of rows beneath a given model index
- in the model leads to the insertion of new child items in the corresponding
- item, handled by the \c insertChildren() function:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 7
-
- This ensures that new items are created with the required number of columns
- and inserted at a valid position in the internal \c childItems list.
- Items are removed with the \c removeChildren() function:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 10
-
- As discussed above, the functions for inserting and removing columns are
- used differently to those for inserting and removing child items because
- they are expected to be called on every item in the tree. We do this by
- recursively calling this function on each child of the item:
-
- \snippet examples/itemviews/editabletreemodel/treeitem.cpp 8
-
- \section1 TreeModel Class Definition
-
- The \c TreeModel class provides an implementation of the QAbstractItemModel
- class, exposing the necessary interface for a model that can be edited and
- resized.
-
- \snippet examples/itemviews/editabletreemodel/treemodel.h 0
-
- The constructor and destructor are specific to this model.
-
- \snippet examples/itemviews/editabletreemodel/treemodel.h 1
-
- Read-only tree models only need to provide the above functions. The
- following public functions provide support for editing and resizing:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.h 2
-
- To simplify this example, the data exposed by the model is organized into
- a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()}
- function. Many real world models will not process the raw data at all, but
- simply work with an existing data structure or library API.
-
- \section1 TreeModel Class Implementation
-
- The constructor creates a root item and initializes it with the header
- data supplied:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 0
-
- We call the internal \l{TreeModel::setupModelData}{setupModelData()}
- function to convert the textual data supplied to a data structure we can
- use with the model. Other models may be initialized with a ready-made
- data structure, or use an API to a library that maintains its own data.
-
- The destructor only has to delete the root item; all child items will
- be recursively deleted by the \c TreeItem destructor.
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 1
-
- \target TreeModel::getItem
- Since the model's interface to the other model/view components is based
- on model indexes, and the internal data structure is item-based, many of
- the functions implemented by the model need to be able to convert any
- given model index to its corresponding item. For convenience and
- consistency, we have defined a \c getItem() function to perform this
- repetitive task:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 4
-
- This function assumes that each model index it is passed corresponds to
- a valid item in memory. If the index is invalid, or its internal pointer
- does not refer to a valid item, the root item is returned instead.
-
- The model's \c rowCount() implementation is simple: it first uses the
- \c getItem() function to obtain the relevant item, then returns the
- number of children it contains:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 8
-
- By contrast, the \c columnCount() implementation does not need to look
- for a particular item because all items are defined to have the same
- number of columns associated with them.
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 2
-
- As a result, the number of columns can be obtained directly from the root
- item.
-
- To enable items to be edited and selected, the \c flags() function needs
- to be implemented so that it returns a combination of flags that includes
- the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as
- Qt::ItemIsEnabled:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 3
-
- \target TreeModel::index
- The model needs to be able to generate model indexes to allow other
- components to request data and information about its structure. This task
- is performed by the \c index() function, which is used to obtain model
- indexes corresponding to children of a given parent item:
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 5
-
- In this model, we only return model indexes for child items if the parent
- index is invalid (corresponding to the root item) or if it has a zero
- column number.
-
- We use the custom \l{TreeModel::getItem}{getItem()} function to obtain
- a \c TreeItem instance that corresponds to the model index supplied, and
- request its child item that corresponds to the specified row.
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 6
-
- Since each item contains information for an entire row of data, we create
- a model index to uniquely identify it by calling
- \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers
- and a pointer to the item. In the \l{TreeModel::data}{data()} function,
- we will use the item pointer and column number to access the data
- associated with the model index; in this model, the row number is not
- needed to identify data.
-
- \target TreeModel::parent
- The \c parent() function supplies model indexes for parents of items
- by finding the corresponding item for a given model index, using its
- \l{TreeItem::parent}{parent()} function to obtain its parent item,
- then creating a model index to represent the parent. (See
- \l{Relating-items-using-model-indexes}{the above diagram}).
-
- \snippet examples/itemviews/editabletreemodel/treemodel.cpp 7
-
- Items without parents, including the root item, are handled by returning
- a null model index. Otherwise, a model index is created and returned as
- in the \l{TreeModel::index}{index()} function, with a suitable row number,
- but with a zero column number to be consistent with the scheme used in
- the \l{TreeModel::index}{index()} implementation.
-
- \target TreeModel::data
- \target TreeModel::setupModelData
-
-*/
diff --git a/doc/src/examples/elasticnodes.qdoc b/doc/src/examples/elasticnodes.qdoc
deleted file mode 100644
index bd25008f60..0000000000
--- a/doc/src/examples/elasticnodes.qdoc
+++ /dev/null
@@ -1,430 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/elasticnodes
- \title Elastic Nodes Example
-
- The Elastic Nodes example shows how to implement edges between nodes in a
- graph, with basic interaction. You can click to drag a node around, and
- zoom in and out using the mouse wheel or the keyboard. Hitting the space
- bar will randomize the nodes. The example is also resolution independent;
- as you zoom in, the graphics remain crisp.
-
- \image elasticnodes-example.png
-
- Graphics View provides the QGraphicsScene class for managing and
- interacting with a large number of custom-made 2D graphical items derived
- from the QGraphicsItem class, and a QGraphicsView widget for visualizing
- the items, with support for zooming and rotation.
-
- This example consists of a \c Node class, an \c Edge class, a \c
- GraphWidget test, and a \c main function: the \c Node class represents
- draggable yellow nodes in a grid, the \c Edge class represents the lines
- between the nodes, the \c GraphWidget class represents the application
- window, and the \c main() function creates and shows this window, and runs
- the event loop.
-
- \section1 Node Class Definition
-
- The \c Node class serves three purposes:
-
- \list
- \li Painting a yellow gradient "ball" in two states: sunken and raised.
- \li Managing connections to other nodes.
- \li Calculating forces pulling and pushing the nodes in the grid.
- \endlist
-
- Let's start by looking at the \c Node class declaration.
-
- \snippet examples/graphicsview/elasticnodes/node.h 0
-
- The \c Node class inherits QGraphicsItem, and reimplements the two
- mandatory functions \l{QGraphicsItem::boundingRect()}{boundingRect()} and
- \l{QGraphicsItem::paint()}{paint()} to provide its visual appearance. It
- also reimplements \l{QGraphicsItem::shape()}{shape()} to ensure its hit
- area has an elliptic shape (as opposed to the default bounding rectangle).
-
- For edge management purposes, the node provides a simple API for adding
- edges to a node, and for listing all connected edges.
-
- The \l{QGraphicsItem::advance()}{advance()} reimplementation is called
- whenever the scene's state advances by one step. The calculateForces()
- function is called to calculate the forces that push and pull on this node
- and its neighbors.
-
- The \c Node class also reimplements
- \l{QGraphicsItem::itemChange()}{itemChange()} to react to state changes (in
- this case, position changes), and
- \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} and
- \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} to update the
- item's visual appearance.
-
- We will start reviewing the \c Node implementation by looking at its
- constructor:
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 0
-
- In the constructor, we set the
- \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} flag to allow the item to
- move in response to mouse dragging, and
- \l{QGraphicsItem::ItemSendsGeometryChanges}{ItemSendsGeometryChanges} to
- enable \l{QGraphicsItem::itemChange()}{itemChange()} notifications for
- position and transformation changes. We also enable
- \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache} to speed up
- rendering performance. To ensure that the nodes are always stacked on top
- of edges, we finally set the item's Z value to -1.
-
- \c Node's constructor takes a \c GraphWidget pointer and stores this as a
- member variable. We will revisit this pointer later on.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 1
-
- The addEdge() function adds the input edge to a list of attached edges. The
- edge is then adjusted so that the end points for the edge match the
- positions of the source and destination nodes.
-
- The edges() function simply returns the list of attached edges.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 2
-
- There are two ways to move a node. The \c calculateForces() function
- implements the elastic effect that pulls and pushes on nodes in the grid.
- In addition, the user can directly move one node around with the mouse.
- Because we do not want the two approaches to operate at the same time on
- the same node, we start \c calculateForces() by checking if this \c Node is
- the current mouse grabber item (i.e., QGraphicsScene::mouseGrabberItem()).
- Because we need to find all neighboring (but not necessarily connected)
- nodes, we also make sure the item is part of a scene in the first place.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 3
-
- The "elastic" effect comes from an algorithm that applies pushing and
- pulling forces. The effect is impressive, and surprisingly simple to
- implement.
-
- The algorithm has two steps: the first is to calculate the forces that push
- the nodes apart, and the second is to subtract the forces that pull the
- nodes together. First we need to find all the nodes in the graph. We call
- QGraphicsScene::items() to find all items in the scene, and then use
- qgraphicsitem_cast() to look for \c Node instances.
-
- We make use of \l{QGraphicsItem::mapFromItem()}{mapFromItem()} to create a
- temporary vector pointing from this node to each other node, in \l{The
- Graphics View Coordinate System}{local coordinates}. We use the decomposed
- components of this vector to determine the direction and strength of force
- that should apply to the node. The forces accumulate for each node, and are
- then adjusted so that the closest nodes are given the strongest force, with
- rapid degradation when distance increases. The sum of all forces is stored
- in \c xvel (X-velocity) and \c yvel (Y-velocity).
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 4
-
- The edges between the nodes represent forces that pull the nodes together.
- By visiting each edge that is connected to this node, we can use a similar
- approach as above to find the direction and strength of all pulling forces.
- These forces are subtracted from \c xvel and \c yvel.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 5
-
- In theory, the sum of pushing and pulling forces should stabilize to
- precisely 0. In practice, however, they never do. To circumvent errors in
- numerical precision, we simply force the sum of forces to be 0 when they
- are less than 0.1.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 6
-
- The final step of \c calculateForces() determines the node's new position.
- We add the force to the node's current position. We also make sure the new
- position stays inside of our defined boundaries. We don't actually move the
- item in this function; that's done in a separate step, from \c advance().
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 7
-
- The \c advance() function updates the item's current position. It is called
- from \c GraphWidget::timerEvent(). If the node's position changed, the
- function returns true; otherwise false is returned.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 8
-
- The \c Node's bounding rectangle is a 20x20 sized rectangle centered around
- its origin (0, 0), adjusted by 2 units in all directions to compensate for
- the node's outline stroke, and by 3 units down and to the right to make
- room for a simple drop shadow.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 9
-
- The shape is a simple ellipse. This ensures that you must click inside the
- node's elliptic shape in order to drag it around. You can test this effect
- by running the example, and zooming far in so that the nodes are very
- large. Without reimplementing \l{QGraphicsItem::shape()}{shape()}, the
- item's hit area would be identical to its bounding rectangle (i.e.,
- rectangular).
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 10
-
- This function implements the node's painting. We start by drawing a simple
- dark gray elliptic drop shadow at (-7, -7), that is, (3, 3) units down and
- to the right from the top-left corner (-10, -10) of the ellipse.
-
- We then draw an ellipse with a radial gradient fill. This fill is either
- Qt::yellow to Qt::darkYellow when raised, or the opposite when sunken. In
- sunken state we also shift the center and focal point by (3, 3) to
- emphasize the impression that something has been pushed down.
-
- Drawing filled ellipses with gradients can be quite slow, especially when
- using complex gradients such as QRadialGradient. This is why this example
- uses \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}, a
- simple yet effective measure that prevents unnecessary redrawing.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 11
-
- We reimplement \l{QGraphicsItem::itemChange()}{itemChange()} to adjust the
- position of all connected edges, and to notify the scene that an item has
- moved (i.e., "something has happened"). This will trigger new force
- calculations.
-
- This notification is the only reason why the nodes need to keep a pointer
- back to the \c GraphWidget. Another approach could be to provide such
- notification using a signal; in such case, \c Node would need to inherit
- from QGraphicsObject.
-
- \snippet examples/graphicsview/elasticnodes/node.cpp 12
-
- Because we have set the \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable}
- flag, we don't need to implement the logic that moves the node according to
- mouse input; this is already provided for us. We still need to reimplement
- the mouse press and release handlers, though, to update the nodes' visual
- appearance (i.e., sunken or raised).
-
- \section1 Edge Class Definition
-
- The \c Edge class represents the arrow-lines between the nodes in this
- example. The class is very simple: it maintains a source- and destination
- node pointer, and provides an \c adjust() function that makes sure the line
- starts at the position of the source, and ends at the position of the
- destination. The edges are the only items that change continuously as
- forces pull and push on the nodes.
-
- Let's take a look at the class declaration:
-
- \snippet examples/graphicsview/elasticnodes/edge.h 0
-
- \c Edge inherits from QGraphicsItem, as it's a simple class that has no use
- for signals, slots, and properties (compare to QGraphicsObject).
-
- The constructor takes two node pointers as input. Both pointers are
- mandatory in this example. We also provide get-functions for each node.
-
- The \c adjust() function repositions the edge, and the item also implements
- \l{QGraphicsItem::boundingRect()}{boundingRect()} and
- \l{QGraphicsItem::paint()}{paint()}.
-
- We will now review its implementation.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 0
-
- The \c Edge constructor initializes its \c arrowSize data member to 10 units;
- this determines the size of the arrow which is drawn in
- \l{QGraphicsItem::paint()}{paint()}.
-
- In the constructor body, we call
- \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons(0)}.
- This ensures that the edge items are not considered for mouse input at all
- (i.e., you cannot click the edges). Then, the source and destination
- pointers are updated, this edge is registered with each node, and we call
- \c adjust() to update this edge's start end end position.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 1
-
- The source and destination get-functions simply return the respective
- pointers.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 2
-
- In \c adjust(), we define two points: \c sourcePoint, and \c destPoint,
- pointing at the source and destination nodes' origins respectively. Each
- point is calculated using \l{The Graphics View Coordinate System}{local
- coordinates}.
-
- We want the tip of the edge's arrows to point to the exact outline of the
- nodes, as opposed to the center of the nodes. To find this point, we first
- decompose the vector pointing from the center of the source to the center
- of the destination node into X and Y, and then normalize the components by
- dividing by the length of the vector. This gives us an X and Y unit delta
- that, when multiplied by the radius of the node (which is 10), gives us the
- offset that must be added to one point of the edge, and subtracted from the
- other.
-
- If the length of the vector is less than 20 (i.e., if two nodes overlap),
- then we fix the source and destination pointer at the center of the source
- node. In practice this case is very hard to reproduce manually, as the
- forces between the two nodes is then at its maximum.
-
- It's important to notice that we call
- \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} in this
- function. The reason is that the variables \c sourcePoint and \c destPoint
- are used directly when painting, and they are returned from the
- \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation. We must
- always call
- \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} before
- changing what \l{QGraphicsItem::boundingRect()}{boundingRect()} returns,
- and before these variables can be used by
- \l{QGraphicsItem::paint()}{paint()}, to keep Graphics View's internal
- bookkeeping clean. It's safest to call this function once, immediately
- before any such variable is modified.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 3
-
- The edge's bounding rectangle is defined as the smallest rectangle that
- includes both the start and the end point of the edge. Because we draw an
- arrow on each edge, we also need to compensate by adjusting with half the
- arrow size and half the pen width in all directions. The pen is used to
- draw the outline of the arrow, and we can assume that half of the outline
- can be drawn outside of the arrow's area, and half will be drawn inside.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 4
-
- We start the reimplementation of \l{QGraphicsItem::paint()}{paint()} by
- checking a few preconditions. Firstly, if either the source or destination
- node is not set, then we return immediately; there is nothing to draw.
-
- At the same time, we check if the length of the edge is approximately 0,
- and if it is, then we also return.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 5
-
- We draw the line using a pen that has round joins and caps. If you run the
- example, zoom in and study the edge in detail, you will see that there are
- no sharp/square edges.
-
- \snippet examples/graphicsview/elasticnodes/edge.cpp 6
-
- We proceed to drawing one arrow at each end of the edge. Each arrow is
- drawn as a polygon with a black fill. The coordinates for the arrow are
- determined using simple trigonometry.
-
- \section1 GraphWidget Class Definition
-
- \c GraphWidget is a subclass of QGraphicsView, which provides the main
- window with scrollbars.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.h 0
-
- The class provides a basic constructor that initializes the scene, an \c
- itemMoved() function to notify changes in the scene's node graph, a few
- event handlers, a reimplementation of
- \l{QGraphicsView::drawBackground()}{drawBackground()}, and a helper
- function for scaling the view by using the mouse wheel or keyboard.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 0
-
- \c GraphicsWidget's constructor creates the scene, and because most items
- move around most of the time, it sets QGraphicsScene::NoIndex. The scene
- then gets a fixed \l{QGraphicsScene::sceneRect}{scene rectangle}, and is
- assigned to the \c GraphWidget view.
-
- The view enables QGraphicsView::CacheBackground to cache rendering of its
- static, and somewhat complex, background. Because the graph renders a close
- collection of small items that all move around, it's unnecessary for
- Graphics View to waste time finding accurate update regions, so we set the
- QGraphicsView::BoundingRectViewportUpdate viewport update mode. The default
- would work fine, but this mode is noticably faster for this example.
-
- To improve rendering quality, we set QPainter::Antialiasing.
-
- The transformation anchor decides how the view should scroll when you
- transform the view, or in our case, when we zoom in or out. We have chosen
- QGraphicsView::AnchorUnderMouse, which centers the view on the point under
- the mouse cursor. This makes it easy to zoom towards a point in the scene
- by moving the mouse over it, and then rolling the mouse wheel.
-
- Finally we give the window a minimum size that matches the scene's default
- size, and set a suitable window title.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 1
-
- The last part of the constructor creates the grid of nodes and edges, and
- gives each node an initial position.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 2
-
- \c GraphWidget is notified of node movement through this \c itemMoved()
- function. Its job is simply to restart the main timer in case it's not
- running already. The timer is designed to stop when the graph stabilizes,
- and start once it's unstable again.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 3
-
- This is \c GraphWidget's key event handler. The arrow keys move the center
- node around, the '+' and '-' keys zoom in and out by calling \c
- scaleView(), and the enter and space keys randomize the positions of the
- nodes. All other key events (e.g., page up and page down) are handled by
- QGraphicsView's default implementation.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 4
-
- The timer event handler's job is to run the whole force calculation
- machinery as a smooth animation. Each time the timer is triggered, the
- handler will find all nodes in the scene, and call \c
- Node::calculateForces() on each node, one at a time. Then, in a final step
- it will call \c Node::advance() to move all nodes to their new positions.
- By checking the return value of \c advance(), we can decide if the grid
- stabilized (i.e., no nodes moved). If so, we can stop the timer.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 5
-
- In the wheel event handler, we convert the mouse wheel delta to a scale
- factor, and pass this factor to \c scaleView(). This approach takes into
- account the speed that the wheel is rolled. The faster you roll the mouse
- wheel, the faster the view will zoom.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 6
-
- The view's background is rendered in a reimplementation of
- QGraphicsView::drawBackground(). We draw a large rectangle filled with a
- linear gradient, add a drop shadow, and then render text on top. The text
- is rendered twice for a simple drop-shadow effect.
-
- This background rendering is quite expensive; this is why the view enables
- QGraphicsView::CacheBackground.
-
- \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 7
-
- The \c scaleView() helper function checks that the scale factor stays
- within certain limits (i.e., you cannot zoom too far in nor too far out),
- and then applies this scale to the view.
-
- \section1 The main() Function
-
- In contrast to the complexity of the rest of this example, the \c main()
- function is very simple: We create a QApplication instance, seed the
- randomizer using qsrand(), and then create and show an instance of \c
- GraphWidget. Because all nodes in the grid are moved initially, the \c
- GraphWidget timer will start immediately after control has returned to the
- event loop.
-*/
diff --git a/doc/src/examples/elidedlabel.qdoc b/doc/src/examples/elidedlabel.qdoc
deleted file mode 100644
index 6833aedc13..0000000000
--- a/doc/src/examples/elidedlabel.qdoc
+++ /dev/null
@@ -1,162 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/elidedlabel
- \group all-examples
- \title Elided Label Example
-
- This example creates a widget similar to QLabel, that elides the last
- visible line, if the text is too long to fit the widget's geometry.
-
- \image elidedlabel-example.png Elided Label example on XPressMusic 5800
-
- When text of varying length has to be displayed in a uniformly sized
- area, for instance within a list or grid view where all list items have the
- same size, it can be useful to give the user a visual clue when not all
- text is visible. QLabel can elide text that doesn't fit within it, but only
- in one line. The \c ElidedLabel widget shown in this example word wraps its
- text by its width, and elides the last visible line if some text is left
- out. \c TestWidget gives control to the features of \c ElidedWidget and
- forms the example application.
-
-
- \section1 ElidedLabel Class Definition
-
- Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of
- the \c ElidedLabel class:
-
-
- \snippet examples/widgets/elidedlabel/elidedlabel.h 0
-
- The \c isElided property depends the font, text content and geometry of the
- widget. Whenever any of these change, the \c elisionChanged() signal might
- trigger. We cache the current elision value in \c elided, so that it
- doesn't have to be recomputed every time it's asked for.
-
-
- \section1 ElidedLabel Class Implementation
-
- Except for initializing the member variables, the constructor sets the size
- policy to be horizontally expanding, since it's meant to fill the width of
- its container and grow vertically.
-
- \snippet examples/widgets/elidedlabel/elidedlabel.cpp 0
-
- Changing the \c content require a repaint of the widget.
-
- \snippet examples/widgets/elidedlabel/elidedlabel.cpp 1
-
- QTextLayout is used in the \c paintEvent() to divide the \c content into
- lines, that wrap on word boundaries. Each line, except the last visible
- one, is drawn \c lineSpacing pixels below the previous one. The \c draw()
- method of QTextLine will draw the line using the coordinate point as the
- top left corner.
-
- \snippet examples/widgets/elidedlabel/elidedlabel.cpp 2
-
- Unfortunately, QTextLayout does not elide text, so the last visible line
- has to be treated differently. This last line is elided if it is too wide.
- The \c drawText() method of QPainter draws the text starting from the base
- line, which is \c ascecnt() pixels below the last drawn line.
-
- Finally, one more line is created to see if everything fit on this line.
-
- \snippet examples/widgets/elidedlabel/elidedlabel.cpp 3
-
- If the text was elided and wasn't before or vice versa, cache it in
- \c elided and emit the change.
-
- \snippet examples/widgets/elidedlabel/elidedlabel.cpp 4
-
-
- \section1 TestWidget Class Definition
-
- \c TestWidget is a QWidget and is the main window of the example. It
- contains an \c ElidedLabel which can be resized with two QSlider widgets.
-
- \snippet examples/widgets/elidedlabel/testwidget.h 0
-
- \section1 TestWidget Class Implementation
-
- The constructor initializes the whole widget. Strings of different length
- are stored in \c textSamples. The user is able to switch between these.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 0
-
- An \c ElidedLabel is created to contain the first of the sample strings.
- The frame is made visible to make it easier to see the actual size of the
- widget.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 1
-
- The buttons and the elision label are created. By connecting the
- \c elisionChanged() signal to the \c setVisible() slot of the \c label,
- it will act as an indicator to when the text is elided or not. This signal
- could, for instance, be used to make a "More" button visible, or similar.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 2
-
- The \c widthSlider and \c heightSlider specify the size of the
- \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be
- inverted to act appropriately.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 3
-
- The components are all stored in a QGridLayout, which is made the layout of
- the \c TestWidget.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 4
-
- On the Maemo platform, windows are stuck in landscape mode by default. With
- this attribute set, the window manager is aware that this window can be
- rotated.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 5
-
- The \c widthSlider and \c heightSlider have the exact same length as the
- dimensions of the \c elidedText. The maximum value for both of them is
- thus their lengths, and each tick indicates one pixel.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 6
-
- The \c switchText() slot simply cycles through all the available sample
- texts.
-
- \snippet examples/widgets/elidedlabel/testwidget.cpp 7
-
- These slots set the width and height of the \c elided text, in response to
- changes in the sliders.
-
- \section1 The \c main() Function
-
- The \c main() function creates an instance of \c TestWidget fullscreen and
- enters the message loop.
-
- \snippet examples/widgets/elidedlabel/main.cpp 0
-*/
-
diff --git a/doc/src/examples/embeddeddialogs.qdoc b/doc/src/examples/embeddeddialogs.qdoc
deleted file mode 100644
index 24b3abdb37..0000000000
--- a/doc/src/examples/embeddeddialogs.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/embeddeddialogs
- \title Embedded Dialogs
-
- This example shows how to embed standard dialogs into
- Graphics View. It also shows how you can customize the
- proxy class and add window shadows.
-
- \image embeddeddialogs-demo.png
-*/
diff --git a/doc/src/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc
deleted file mode 100644
index eb2e10b051..0000000000
--- a/doc/src/examples/eventtransitions.qdoc
+++ /dev/null
@@ -1,72 +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$
-**
-****************************************************************************/
-
-/*!
- \example statemachine/eventtransitions
- \title Event Transitions Example
-
- The Event Transitions example shows how to use event transitions, a
- feature of \l{The State Machine Framework}.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 0
-
- The \c Window class's constructors begins by creating a button.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 1
-
- Two states, \c s1 and \c s2, are created; upon entry they will assign
- "Outside" and "Inside" to the button's text, respectively.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 2
-
- When the button receives an event of type QEvent::Enter and the state
- machine is in state \c s1, the machine will transition to state \c s2.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 3
-
- When the button receives an event of type QEvent::Leave and the state
- machine is in state \c s2, the machine will transition back to state \c
- s1.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 4
-
- Next, the state \c s3 is created. \c s3 will be entered when the button
- receives an event of type QEvent::MouseButtonPress and the state machine
- is in state \c s2. When the button receives an event of type
- QEvent::MouseButtonRelease and the state machine is in state \c s3, the
- machine will transition back to state \c s2.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 5
-
- Finally, the states are added to the machine as top-level states, the
- initial state is set to be \c s1 ("Outside"), and the machine is started.
-
- \snippet examples/statemachine/eventtransitions/main.cpp 6
-
- The main() function constructs a Window object and shows it.
-
-*/
diff --git a/doc/src/examples/extension.qdoc b/doc/src/examples/extension.qdoc
deleted file mode 100644
index 9e63b70e3f..0000000000
--- a/doc/src/examples/extension.qdoc
+++ /dev/null
@@ -1,138 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/extension
- \title Extension Example
-
- The Extension example shows how to add an extension to a QDialog
- using the QAbstractButton::toggled() signal and the
- QWidget::setVisible() slot.
-
- \image extension-example.png Screenshot of the Extension example
-
- The Extension application is a dialog that allows the user to
- perform a simple search as well as a more advanced search.
-
- The simple search has two options: \uicontrol {Match case} and \uicontrol
- {Search from start}. The advanced search options include the
- possibilities to search for \uicontrol {Whole words}, \uicontrol {Search
- backward} and \uicontrol {Search selection}. Only the simple search is
- visible when the application starts. The advanced search options
- are located in the application's extension part, and can be made
- visible by pressing the \uicontrol More button:
-
- \image extension_more.png Screenshot of the Extension example
-
- \section1 FindDialog Class Definition
-
- The \c FindDialog class inherits QDialog. The QDialog class is the
- base class of dialog windows. A dialog window is a top-level
- window mostly used for short-term tasks and brief communications
- with the user.
-
- \snippet examples/dialogs/extension/finddialog.h 0
-
- The \c FindDialog widget is the main application widget, and
- displays the application's search options and controlling
- buttons.
-
- In addition to a constructor, we declare the several child
- widgets: We need a QLineEdit with an associated QLabel to let the
- user type a word to search for, we need several \l
- {QCheckBox}{QCheckBox}es to facilitate the search options, and we
- need three \l {QPushButton}{QPushButton}s: the \uicontrol Find button to
- start a search and the \uicontrol More button to enable an advanced search.
- Finally, we need a QWidget representing the application's extension
- part.
-
- \section1 FindDialog Class Implementation
-
- In the constructor we first create the standard child widgets for
- the simple search: the QLineEdit with the associated QLabel, two
- of the \l {QCheckBox}{QCheckBox}es and all the \l
- {QPushButton}{QPushButton}s.
-
- \snippet examples/dialogs/extension/finddialog.cpp 0
-
- We give the options and buttons a shortcut key using the &
- character. In the \uicontrol {Find what} option's case, we also need to
- use the QLabel::setBuddy() function to make the shortcut key work
- as expected; then, when the user presses the shortcut key
- indicated by the label, the keyboard focus is transferred to the
- label's buddy widget, the QLineEdit.
-
- We set the \uicontrol Find button's default property to true, using the
- QPushButton::setDefault() function. Then the push button will be
- pressed if the user presses the Enter (or Return) key. Note that a
- QDialog can only have one default button.
-
- \snippet examples/dialogs/extension/finddialog.cpp 2
-
- Then we create the extension widget, and the \l
- {QCheckBox}{QCheckBox}es associated with the advanced search
- options.
-
- \snippet examples/dialogs/extension/finddialog.cpp 3
-
- Now that the extension widget is created, we can connect the \uicontrol
- More button's \l{QAbstractButton::toggled()}{toggled()} signal to
- the extension widget's \l{QWidget::setVisible()}{setVisible()} slot.
-
- The QAbstractButton::toggled() signal is emitted whenever a
- checkable button changes its state. The signal's argument is true
- if the button is checked, or false if the button is unchecked. The
- QWidget::setVisible() slot sets the widget's visible status. If
- the status is true the widget is shown, otherwise the widget is
- hidden.
-
- Since we made the \uicontrol More button checkable when we created it,
- the connection makes sure that the extension widget is shown
- depending on the state of \uicontrol More button.
-
- We also put the check boxes associated with the advanced
- search options into a layout we install on the extension widget.
-
- \snippet examples/dialogs/extension/finddialog.cpp 4
-
- Before we create the main layout, we create several child layouts
- for the widgets: First we align the QLabel and its buddy, the
- QLineEdit, using a QHBoxLayout. Then we vertically align the
- QLabel and QLineEdit with the check boxes associated with the
- simple search, using a QVBoxLayout. We also create a QVBoxLayout
- for the buttons. In the end we lay out the two latter layouts and
- the extension widget using a QGridLayout.
-
- \snippet examples/dialogs/extension/finddialog.cpp 5
-
- Finally, we hide the extension widget using the QWidget::hide()
- function, making the application only show the simple search
- options when it starts. When the user wants to access the advanced
- search options, the dialog only needs to change the visibility of
- the extension widget. Qt's layout management takes care of the
- dialog's appearance.
-*/
diff --git a/doc/src/examples/factorial.qdoc b/doc/src/examples/factorial.qdoc
deleted file mode 100644
index ead9695c1c..0000000000
--- a/doc/src/examples/factorial.qdoc
+++ /dev/null
@@ -1,88 +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$
-**
-****************************************************************************/
-
-/*!
- \example statemachine/factorial
- \title Factorial States Example
-
- The Factorial States example shows how to use \l{The State Machine
- Framework} to calculate the factorial of an integer.
-
- The statechart for calculating the factorial looks as follows:
-
- \image factorial-example.png
- \omit
- \caption This is a caption
- \endomit
-
- In other words, the state machine calculates the factorial of 6 and prints
- the result.
-
- \snippet examples/statemachine/factorial/main.cpp 0
-
- The Factorial class is used to hold the data of the computation, \c x and
- \c fac. It also provides a signal that's emitted whenever the value of \c
- x changes.
-
- \snippet examples/statemachine/factorial/main.cpp 1
-
- The FactorialLoopTransition class implements the guard (\c x > 1) and
- calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial
- loop.
-
- \snippet examples/statemachine/factorial/main.cpp 2
-
- The FactorialDoneTransition class implements the guard (\c x <= 1) that
- terminates the factorial computation. It also prints the final result to
- standard output.
-
- \snippet examples/statemachine/factorial/main.cpp 3
-
- The application's main() function first creates the application object, a
- Factorial object and a state machine.
-
- \snippet examples/statemachine/factorial/main.cpp 4
-
- The \c compute state is created, and the initial values of \c x and \c fac
- are defined. A FactorialLoopTransition object is created and added to the
- state.
-
- \snippet examples/statemachine/factorial/main.cpp 5
-
- A final state, \c done, is created, and a FactorialDoneTransition object
- is created with \c done as its target state. The transition is then added
- to the \c compute state.
-
- \snippet examples/statemachine/factorial/main.cpp 6
-
- The machine's initial state is set to be the \c compute state. We connect
- the QStateMachine::finished() signal to the QCoreApplication::quit() slot,
- so the application will quit when the state machine's work is
- done. Finally, the state machine is started, and the application's event
- loop is entered.
-
- */
diff --git a/doc/src/examples/fademessage.qdoc b/doc/src/examples/fademessage.qdoc
deleted file mode 100644
index 48f98c03ad..0000000000
--- a/doc/src/examples/fademessage.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example effects/fademessage
- \title Fade Message Effect Example
-
- \div { style="text-align: center"}
- \inlineimage fademessageeffect-example.png
- \inlineimage fademessageeffect-example-faded.png
- \enddiv
-
-*/
diff --git a/doc/src/examples/fetchmore.qdoc b/doc/src/examples/fetchmore.qdoc
deleted file mode 100644
index cd07f3c7ab..0000000000
--- a/doc/src/examples/fetchmore.qdoc
+++ /dev/null
@@ -1,111 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/fetchmore
- \title Fetch More Example
-
- The Fetch More example shows how two add items to an item view
- model on demand.
-
- \image fetchmore-example.png
-
- The user of the example can enter a directory in the \uicontrol
- Directory line edit. The contents of the directory will
- be listed in the list view below.
-
- When you have large - or perhaps even infinite - data sets, you
- will need to add items to the model in batches, and preferably only
- when the items are needed by the view (i.e., when they are visible
- in the view).
-
- In this example, we implement \c FileListModel - an item view
- model containing the entries of a directory. We also have \c
- Window, which sets up the GUI and feeds the model with
- directories.
-
- Let's take a tour of \c {FileListModel}'s code.
-
- \section1 FileListModel Class Definition
-
- The \c FileListModel inherits QAbstractListModel and contains the
- contents of a directory. It will add items to itself only when
- requested to do so by the view.
-
- \snippet examples/itemviews/fetchmore/filelistmodel.h 0
-
- The secret lies in the reimplementation of
- \l{QAbstractItemModel::}{fetchMore()} and
- \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel.
- These functions are called by the item view when it needs more
- items.
-
- The \c setDirPath() function sets the directory the model will
- work on. We emit \c numberPopulated() each time we add a batch of
- items to the model.
-
- We keep all directory entries in \c fileList. \c fileCount is the
- number of items that have been added to the model.
-
- \section1 FileListModel Class Implementation
-
- We start by checking out the \c setDirPath().
-
- \snippet examples/itemviews/fetchmore/filelistmodel.cpp 0
-
- We use a QDir to get the contents of the directory. We need to
- inform QAbstractItemModel that we want to remove all items - if
- any - from the model.
-
- \snippet examples/itemviews/fetchmore/filelistmodel.cpp 1
-
- The \c canFetchMore() function is called by the view when it needs
- more items. We return true if there still are entries that we have
- not added to the model; otherwise, we return false.
-
- And now, the \c fetchMore() function itself:
-
- \snippet examples/itemviews/fetchmore/filelistmodel.cpp 2
-
- We first calculate the number of items to fetch.
- \l{QAbstractItemModel::}{beginInsertRows()} and
- \l{QAbstractItemModel::}{endInsertRows()} are mandatory for
- QAbstractItemModel to keep up with the row insertions. Finally, we
- emit \c numberPopulated(), which is picked up by \c Window.
-
- To complete the tour, we also look at \c rowCount() and \c data().
-
- \snippet examples/itemviews/fetchmore/filelistmodel.cpp 4
-
- Notice that the row count is only the items we have added so far,
- i.e., not the number of entries in the directory.
-
- In \c data(), we return the appropriate entry from the \c
- fileList. We also separate the batches with a different background
- color.
-*/
-
diff --git a/doc/src/examples/findfiles.qdoc b/doc/src/examples/findfiles.qdoc
deleted file mode 100644
index 6654070d72..0000000000
--- a/doc/src/examples/findfiles.qdoc
+++ /dev/null
@@ -1,249 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/findfiles
- \title Find Files Example
-
- The Find Files example shows how to use QProgressDialog to provide
- feedback on the progress of a slow operation. The example also
- shows how to use QFileDialog to facilitate browsing, how to use
- QTextStream's streaming operators to read a file, and how to use
- QTableWidget to provide standard table display facilities for
- applications. In addition, files can be opened using the
- QDesktopServices class.
-
- \image findfiles-example.png Screenshot of the Find Files example
-
- With the Find Files application the user can search for files in a
- specified directory, matching a specified file name (using wild
- cards if appropriate) and containing a specified text.
-
- The user is provided with a \uicontrol Browse option, and the result of
- the search is displayed in a table with the names of the files
- found and their sizes. In addition the application provides a
- total count of the files found.
-
- \section1 Window Class Definition
-
- The \c Window class inherits QWidget, and is the main application
- widget. It shows the search options, and displays the search
- results.
-
- \snippet examples/dialogs/findfiles/window.h 0
-
- We need two private slots: The \c browse() slot is called whenever
- the user wants to browse for a directory to search in, and the \c
- find() slot is called whenever the user requests a search to be
- performed by pressing the \uicontrol Find button.
-
- In addition we declare several private functions: We use the \c
- findFiles() function to search for files matching the user's
- specifications, we call the \c showFiles() function to display the
- results, and we use \c createButton(), \c createComboBox() and \c
- createFilesTable() when we are constructing the widget.
-
- \section1 Window Class Implementation
-
- In the constructor we first create the application's widgets.
-
- \snippet examples/dialogs/findfiles/window.cpp 0
-
- We create the application's buttons using the private \c
- createButton() function. Then we create the comboboxes associated
- with the search specifications, using the private \c
- createComboBox() function. We also create the application's labels
- before we use the private \c createFilesTable() function to create
- the table displaying the search results.
-
- \snippet examples/dialogs/findfiles/window.cpp 1
-
- Then we add all the widgets to a main layout using QGridLayout. We
- have, however, put the \c Find and \c Quit buttons and a
- stretchable space in a separate QHBoxLayout first, to make the
- buttons appear in the \c Window widget's bottom right corner.
-
- \snippet examples/dialogs/findfiles/window.cpp 2
-
- The \c browse() slot presents a file dialog to the user, using the
- QFileDialog class. QFileDialog enables a user to traverse the file
- system in order to select one or many files or a directory. The
- easiest way to create a QFileDialog is to use the convenience
- static functions.
-
- Here we use the static QFileDialog::getExistingDirectory()
- function which returns an existing directory selected by the
- user. Then we display the directory in the directory combobox
- using the QComboBox::addItem() function, and updates the current
- index.
-
- QComboBox::addItem() adds an item to the combobox with the given
- text (if it is not already present in the list), and containing
- the specified userData. The item is appended to the list of
- existing items.
-
- \snippet examples/dialogs/findfiles/window.cpp 3
-
- The \c find() slot is called whenever the user requests a new
- search by pressing the \uicontrol Find button.
-
- First we eliminate any previous search results by setting the
- table widgets row count to zero. Then we retrieve the
- specified file name, text and directory path from the respective
- comboboxes.
-
- \snippet examples/dialogs/findfiles/window.cpp 4
-
- We use the directory's path to create a QDir; the QDir class
- provides access to directory structures and their contents. We
- create a list of the files (contained in the newly created QDir)
- that match the specified file name. If the file name is empty
- the list will contain all the files in the directory.
-
- Then we search through all the files in the list, using the private
- \c findFiles() function, eliminating the ones that don't contain
- the specified text. And finally, we display the results using the
- private \c showFiles() function.
-
- If the user didn't specify any text, there is no reason to search
- through the files, and we display the results immediately.
-
- \image findfiles_progress_dialog.png Screenshot of the Progress Dialog
-
- \snippet examples/dialogs/findfiles/window.cpp 5
-
- In the private \c findFiles() function we search through a list of
- files, looking for the ones that contain a specified text. This
- can be a very slow operation depending on the number of files as
- well as their sizes. In case there are a large number of files, or
- there exists some large files on the list, we provide a
- QProgressDialog.
-
- The QProgressDialog class provides feedback on the progress of a
- slow operation. It is used to give the user an indication of how
- long an operation is going to take, and to demonstrate that the
- application has not frozen. It can also give the user an
- opportunity to abort the operation.
-
- \snippet examples/dialogs/findfiles/window.cpp 6
-
- We run through the files, one at a time, and for each file we
- update the QProgressDialog value. This property holds the current
- amount of progress made. We also update the progress dialog's
- label.
-
- Then we call the QCoreApplication::processEvents() function using
- the QApplication object. In this way we interleave the display of
- the progress made with the process of searching through the files
- so the application doesn't appear to be frozen.
-
- The QApplication class manages the GUI application's control flow
- and main settings. It contains the main event loop, where all
- events from the window system and other sources are processed and
- dispatched. QApplication inherits QCoreApplication. The
- QCoreApplication::processEvents() function processes all pending
- events according to the specified QEventLoop::ProcessEventFlags
- until there are no more events to process. The default flags are
- QEventLoop::AllEvents.
-
- \snippet examples/dialogs/findfiles/window.cpp 7
-
- After updating the QProgressDialog, we create a QFile using the
- QDir::absoluteFilePath() function which returns the absolute path
- name of a file in the directory. We open the file in read-only
- mode, and read one line at a time using QTextStream.
-
- The QTextStream class provides a convenient interface for reading
- and writing text. Using QTextStream's streaming operators, you can
- conveniently read and write words, lines and numbers.
-
- For each line we read we check if the QProgressDialog has been
- canceled. If it has, we abort the operation, otherwise we check if
- the line contains the specified text. When we find the text within
- one of the files, we add the file's name to a list of found files
- that contain the specified text, and start searching a new file.
-
- Finally, we return the list of the files found.
-
- \snippet examples/dialogs/findfiles/window.cpp 8
-
- Both the \c findFiles() and \c showFiles() functions are called from
- the \c find() slot. In the \c showFiles() function we run through
- the provided list of file names, adding each file name to the
- first column in the table widget and retrieving the file's size using
- QFile and QFileInfo for the second column.
-
- We also update the total number of files found.
-
- \snippet examples/dialogs/findfiles/window.cpp 9
-
- The private \c createButton() function is called from the
- constructor. We create a QPushButton with the provided text,
- connect it to the provided slot, and return a pointer to the
- button.
-
- \snippet examples/dialogs/findfiles/window.cpp 10
-
- The private \c createComboBox() function is also called from the
- contructor. We create a QComboBox with the given text, and make it
- editable.
-
- When the user enters a new string in an editable combobox, the
- widget may or may not insert it, and it can insert it in several
- locations, depending on the QComboBox::InsertPolicy. The default
- policy is is QComboBox::InsertAtBottom.
-
- Then we add the provided text to the combobox, and specify the
- widget's size policies, before we return a pointer to the
- combobox.
-
- \snippet examples/dialogs/findfiles/window.cpp 11
-
- The private \c createFilesTable() function is called from the
- constructor. In this function we create the QTableWidget that
- will display the search results. We set its horizontal headers and
- their resize mode.
-
- QTableWidget inherits QTableView which provides a default
- model/view implementation of a table view. The
- QTableView::horizontalHeader() function returns the table view's
- horizontal header as a QHeaderView. The QHeaderView class provides
- a header row or header column for item views, and the
- QHeaderView::setResizeMode() function sets the constraints on how
- the section in the header can be resized.
-
- Finally, we hide the QTableWidget's vertical headers using the
- QWidget::hide() function, and remove the default grid drawn for
- the table using the QTableView::setShowGrid() function.
-
- \snippet examples/dialogs/findfiles/window.cpp 12
-
- The \c openFileOfItem() slot is invoked when the user double
- clicks on a cell in the table. The QDesktopServices::openUrl()
- knows how to open a file given the file name.
-*/
-
diff --git a/doc/src/examples/flowlayout.qdoc b/doc/src/examples/flowlayout.qdoc
deleted file mode 100644
index eaa0f7baf0..0000000000
--- a/doc/src/examples/flowlayout.qdoc
+++ /dev/null
@@ -1,145 +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$
-**
-****************************************************************************/
-
-/*!
- \example layouts/flowlayout
- \title Flow Layout Example
-
- The Flow Layout example demonstrates a custom layout that arranges child
- widgets from left to right and top to bottom in a top-level widget.
-
- \image flowlayout-example.png Screenshot of the Flow Layout example
-
- The items are first laid out horizontally and then vertically when each line
- in the layout runs out of space.
-
- The Flowlayout class mainly uses QLayout and QWidgetItem, while the
- Window uses QWidget and QLabel. We will only document the definition
- and implementation of \c FlowLayout below.
-
- \section1 FlowLayout Class Definition
-
- The \c FlowLayout class inherits QLayout. It is a custom layout class
- that arranges its child widgets horizontally and vertically.
-
- \snippet examples/layouts/flowlayout/flowlayout.h 0
-
- We reimplement functions inherited from QLayout. These functions add items to
- the layout and handle their orientation and geometry.
-
- We also declare two private methods, \c doLayout() and \c smartSpacing().
- \c doLayout() lays out the layout items, while the \c
- smartSpacing() function calculates the spacing between them.
-
- \section1 FlowLayout Class Implementation
-
- We start off by looking at the constructor:
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 1
-
- In the constructor we call \c setContentsMargins() to set the left, top,
- right and bottom margin. By default, QLayout uses values provided by
- the current style (see QStyle::PixelMetric).
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 2
-
- In this example we reimplement \c addItem(), which is a pure virtual
- function. When using \c addItem() the ownership of the layout items is
- transferred to the layout, and it is therefore the layout's
- responsibility to delete them.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 3
-
- \c addItem() is implemented to add items to the layout.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 4
-
- We implement \c horizontalSpacing() and \c verticalSpacing() to get
- hold of the spacing between the widgets inside the layout. If the value
- is less than or equal to 0, this value will be used. If not,
- \c smartSpacing() will be called to calculate the spacing.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 5
-
- We then implement \c count() to return the number of items in the
- layout. To navigate the list of items we use \c itemAt() and
- takeAt() to remove and return items from the list. If an item is
- removed, the remaining items will be renumbered. All three
- functions are pure virtual functions from QLayout.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 6
-
- \c expandingDirections() returns the \l{Qt::Orientation}s in which the
- layout can make use of more space than its \c sizeHint().
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 7
-
- To adjust to widgets of which height is dependent on width, we implement \c
- heightForWidth(). The function \c hasHeightForWidth() is used to test for this
- dependency, and \c heightForWidth() passes the width on to \c doLayout() which
- in turn uses the width as an argument for the layout rect, i.e., the bounds in
- which the items are laid out. This rect does not include the layout margin().
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 8
-
- \c setGeometry() is normally used to do the actual layout, i.e., calculate
- the geometry of the layout's items. In this example, it calls \c doLayout()
- and passes the layout rect.
-
- \c sizeHint() returns the preferred size of the layout and \c minimumSize()
- returns the minimum size of the layout.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 9
-
- \c doLayout() handles the layout if \c horizontalSpacing() or \c
- verticalSpacing() don't return the default value. It uses
- \c getContentsMargins() to calculate the area available to the
- layout items.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 10
-
- It then sets the proper amount of spacing for each widget in the
- layout, based on the current style.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 11
-
- The position of each item in the layout is then calculated by
- adding the items width and the line height to the initial x and y
- coordinates. This in turn lets us find out whether the next item
- will fit on the current line or if it must be moved down to the next.
- We also find the height of the current line based on the widgets height.
-
- \snippet examples/layouts/flowlayout/flowlayout.cpp 12
-
- \c smartSpacing() is designed to get the default spacing for either
- the top-level layouts or the sublayouts. The default spacing for
- top-level layouts, when the parent is a QWidget, will be determined
- by querying the style. The default spacing for sublayouts, when
- the parent is a QLayout, will be determined by querying the spacing
- of the parent layout.
-
-*/
diff --git a/doc/src/examples/fontsampler.qdoc b/doc/src/examples/fontsampler.qdoc
deleted file mode 100644
index 8d7f0e0460..0000000000
--- a/doc/src/examples/fontsampler.qdoc
+++ /dev/null
@@ -1,35 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/fontsampler
- \title Font Sampler Example
-
- The Font Sampler example shows how to preview and print multi-page documents.
-
- \image fontsampler-example.png
-*/
diff --git a/doc/src/examples/frozencolumn.qdoc b/doc/src/examples/frozencolumn.qdoc
deleted file mode 100644
index 1bb759b6fd..0000000000
--- a/doc/src/examples/frozencolumn.qdoc
+++ /dev/null
@@ -1,133 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/frozencolumn
- \title Frozen Column Example
-
- This example demonstrates how to freeze a column within a QTableView.
-
- \image frozencolumn-example.png "Screenshot of the example"
-
- We use Qt's model/view framework to implement a table with its first
- column frozen. This technique can be aplied to several columns or rows,
- as long as they are on the edge of the table.
-
- The model/view framework allows for one model to be displayed in different
- ways using multiple views. For this example, we use two views on the same
- model - two \l {QTableView}{table views} sharing one model. The frozen
- column is a child of the main tableview, and we provide the desired visual
- effect using an overlay technique which will be described step by step in
- the coming sections.
-
- \image frozencolumn-tableview.png
-
-
- \section1 FreezeTableWidget Class Definition
-
- The \c FreezeTableWidget class has a constructor and a destructor. Also, it
- has two private members: the table view that we will use as an overlay, and
- the shared model for both table views. Two slots are added to help keep the
- section sizes in sync, as well as a function to readjust the frozen
- column's geometry. In addition, we reimplement two functions:
- \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.h Widget definition
-
- \note QAbstractItemView is \l{QTableView}'s ancestor.
-
-
- \section1 FreezeTableWidget Class Implementation
-
- The constructor takes \a model as an argument and creates a table view that
- we will use to display the frozen column. Then, within the constructor, we
- invoke the \c init() function to set up the frozen column. Finally, we
- connect the \l{QHeaderView::sectionResized()} signals (for horizontal and
- vertical headers) to the appropriate slots. This ensures that our frozen
- column's sections are in sync with the headers. We also connect the
- vertical scrollbars together so that the frozen column scrolls vertically
- with the rest of our table.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp constructor
-
-
- In the \c init() function, we ensure that the overlay table view
- responsible for displaying the frozen column, is set up properly. This
- means that this table view, \c frozenTableView, has to have the same model
- as the main table view. However, the difference here is: \c frozenTableView's
- only visible column is its first column; we hide the others using
- \l{QTableView::}{setColumnHidden()}
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part1
-
-
- In terms of the frozen column's z-order, we stack it on top of the
- viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the
- viewport. For appearance's sake, we prevent the column from stealing focus
- from the main tableview. Also, we make sure that both views share the same
- selection model, so only one cell can be selected at a time. A few other
- tweaks are done to make our application look good and behave consistently
- with the main tableview. Note that we called \c updateFrozenTableGeometry()
- to make the column occupy the correct spot.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part2
-
- When you resize the frozen column, the same column on the main table view
- must resize accordingly, to provide seamless integration. This is
- accomplished by getting the new size of the column from the \c newSize
- value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both
- the horizontal and vertical header.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp sections
-
- Since the width of the frozen column is modified, we adjust the geometry of
- the widget accordingly by invoking \c updateFrozenTableGeometry(). This
- function is further explained below.
-
- In our reimplementation of QTableView::resizeEvent(), we call
- \c updateFrozenTableGeometry() after invoking the base class
- implementation.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp resize
-
- When navigating around the table with the keyboard, we need to ensure that
- the current selection does not disappear behind the frozen column. To
- synchronize this, we reimplement QTableView::moveCursor() and adjust the
- scrollbar positions if needed, after calling the base class implementation.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp navigate
-
- The frozen column's geometry calculation is based on the geometry of the
- table underneath, so it always appears in the right place. Using the
- QFrame::frameWidth() function helps to calculate this geometry correctly,
- no matter which style is used. We rely on the geometry of the viewport and
- headers to set the boundaries for the frozen column.
-
- \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp geometry
-
-*/
-
diff --git a/doc/src/examples/gradients.qdoc b/doc/src/examples/gradients.qdoc
deleted file mode 100644
index 75f78b56ea..0000000000
--- a/doc/src/examples/gradients.qdoc
+++ /dev/null
@@ -1,55 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/gradients
- \title Gradients
-
- In this example we show the various types of gradients that can
- be used in Qt.
-
- \image gradients-demo.png
-
- There are three types of gradients:
-
- \list
- \li \b{Linear} gradients interpolate colors between start and end points.
- \li \b{Radial} gradients interpolate colors between a focal point and the
- points on a circle surrounding it.
- \li \b{Conical} gradients interpolate colors around a center point.
- \endlist
-
- The panel on the right contains a color table editor that defines
- the colors in the gradient. The three topmost controls determine the red,
- green and blue components while the last defines the alpha of the
- gradient. You can move points, and add new ones, by clicking with the left
- mouse button, and remove points by clicking with the right button.
-
- There are three default configurations available at the bottom of
- the page that are provided as suggestions on how a color table could be
- configured.
-*/
diff --git a/doc/src/examples/groupbox.qdoc b/doc/src/examples/groupbox.qdoc
deleted file mode 100644
index f2e4ec995e..0000000000
--- a/doc/src/examples/groupbox.qdoc
+++ /dev/null
@@ -1,140 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/groupbox
- \title Group Box Example
-
- The Group Box example shows how to use the different kinds of group
- boxes in Qt.
-
- Group boxes are container widgets that organize buttons into groups,
- both logically and on screen. They manage the interactions between
- the user and the application so that you do not have to enforce
- simple constraints.
-
- Group boxes are usually used to organize check boxes and radio
- buttons into exclusive groups.
-
- \image groupbox-example.png
-
- The Group Boxes example consists of a single \c Window class that
- is used to show four group boxes: an exclusive radio button group,
- a non-exclusive checkbox group, an exclusive radio button group
- with an enabling checkbox, and a group box with normal push buttons.
-
- \section1 Window Class Definition
-
- The \c Window class is a subclass of \c QWidget that is used to
- display a number of group boxes. The class definition contains
- functions to construct each group box and populate it with different
- selections of button widgets:
-
- \snippet examples/widgets/groupbox/window.h 0
-
- In the example, the widget will be used as a top-level window, so
- the constructor is defined so that we do not have to specify a parent
- widget.
-
- \section1 Window Class Implementation
-
- The constructor creates a grid layout and fills it with each of the
- group boxes that are to be displayed:
-
- \snippet examples/widgets/groupbox/window.cpp 0
-
- The functions used to create each group box each return a
- QGroupBox to be inserted into the grid layout.
-
- \snippet examples/widgets/groupbox/window.cpp 1
-
- The first group box contains and manages three radio buttons. Since
- the group box contains only radio buttons, it is exclusive by
- default, so only one radio button can be checked at any given time.
- We check the first radio button to ensure that the button group
- contains one checked button.
-
- \snippet examples/widgets/groupbox/window.cpp 3
-
- We use a vertical layout within the group box to present the
- buttons in the form of a vertical list, and return the group
- box to the constructor.
-
- The second group box is itself checkable, providing a convenient
- way to disable all the buttons inside it. Initially, it is
- unchecked, so the group box itself must be checked before any of
- the radio buttons inside can be checked.
-
- \snippet examples/widgets/groupbox/window.cpp 4
-
- The group box contains three exclusive radio buttons, and an
- independent checkbox. For consistency, one radio button must be
- checked at all times, so we ensure that the first one is initially
- checked.
-
- \snippet examples/widgets/groupbox/window.cpp 5
-
- The buttons are arranged in the same way as those in the first
- group box.
-
- \snippet examples/widgets/groupbox/window.cpp 6
-
- The third group box is constructed with a "flat" style that is
- better suited to certain types of dialog.
-
- \snippet examples/widgets/groupbox/window.cpp 7
-
- This group box contains only checkboxes, so it is non-exclusive by
- default. This means that each checkbox can be checked independently
- of the others.
-
- \snippet examples/widgets/groupbox/window.cpp 8
-
- Again, we use a vertical layout within the group box to present
- the buttons in the form of a vertical list.
-
- \snippet examples/widgets/groupbox/window.cpp 9
-
- The final group box contains only push buttons and, like the
- second group box, it is checkable.
-
- \snippet examples/widgets/groupbox/window.cpp 10
-
- We create a normal button, a toggle button, and a flat push button:
-
- \snippet examples/widgets/groupbox/window.cpp 11
-
- Push buttons can be used to display popup menus. We create one, and
- attach a simple menu to it:
-
- \snippet examples/widgets/groupbox/window.cpp 12
-
- Finally, we lay out the widgets vertically, and return the group box
- that we created:
-
- \snippet examples/widgets/groupbox/window.cpp 13
-*/
diff --git a/doc/src/examples/icons.qdoc b/doc/src/examples/icons.qdoc
deleted file mode 100644
index daabb1651c..0000000000
--- a/doc/src/examples/icons.qdoc
+++ /dev/null
@@ -1,780 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/icons
- \title Icons Example
-
- The Icons example shows how QIcon can generate pixmaps reflecting
- an icon's state, mode and size. These pixmaps are generated from
- the set of pixmaps made available to the icon, and are used by Qt
- widgets to show an icon representing a particular action.
-
- \image icons-example.png Screenshot of the Icons example
-
- Contents:
-
- \tableofcontents
-
- \section1 QIcon Overview
-
- The QIcon class provides scalable icons in different modes and
- states. An icon's state and mode are depending on the intended use
- of the icon. Qt currently defines four modes:
-
- \table
- \header \li Mode \li Description
- \row
- \li QIcon::Normal
- \li Display the pixmap when the user is not interacting with the
- icon, but the functionality represented by the icon is
- available.
- \row
- \li QIcon::Active
- \li Display the pixmap when the functionality represented by the
- icon is available and the user is interacting with the icon,
- for example, moving the mouse over it or clicking it.
- \row
- \li QIcon::Disabled
- \li Display the pixmap when the functionality represented by
- the icon is not available.
- \row
- \li QIcon::Selected
- \li Display the pixmap when the icon is selected.
- \endtable
-
- QIcon's states are QIcon::On and QIcon::Off, which will display
- the pixmap when the widget is in the respective state. The most
- common usage of QIcon's states are when displaying checkable tool
- buttons or menu entries (see QAbstractButton::setCheckable() and
- QAction::setCheckable()). When a tool button or menu entry is
- checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's
- \l{QIcon::}{Off}. You can, for example, use the QIcon's states to
- display differing pixmaps depending on whether the tool button or
- menu entry is checked or not.
-
- A QIcon can generate smaller, larger, active, disabled, and
- selected pixmaps from the set of pixmaps it is given. Such
- pixmaps are used by Qt widgets to show an icon representing a
- particular action.
-
- \section1 Overview of the Icons Application
-
- With the Icons application you get a preview of an icon's
- generated pixmaps reflecting its different states, modes and size.
-
- When an image is loaded into the application, it is converted into
- a pixmap and becomes a part of the set of pixmaps available to the
- icon. An image can be excluded from this set by checking off the
- related checkbox. The application provides a sub directory
- containing sets of images explicitly designed to illustrate how Qt
- renders an icon in different modes and states.
-
- The application allows you to manipulate the icon size with some
- predefined sizes and a spin box. The predefined sizes are style
- dependent, but most of the styles have the same values: Only the
- Macintosh style differ by using 32 pixels, instead of 16 pixels,
- for toolbar buttons. You can navigate between the available styles
- using the \uicontrol View menu.
-
- \image icons-view-menu.png Screenshot of the View menu
-
- The \uicontrol View menu also provide the option to make the application
- guess the icon state and mode from an image's file name. The \uicontrol
- File menu provide the options of adding an image and removing all
- images. These last options are also available through a context
- menu that appears if you press the right mouse button within the
- table of image files. In addition, the \uicontrol File menu provide an
- \uicontrol Exit option, and the \uicontrol Help menu provide information about
- the example and about Qt.
-
- \image icons_find_normal.png Screenshot of the Find Files
-
- The screenshot above shows the application with one image file
- loaded. The \uicontrol {Guess Image Mode/State} is enabled and the
- style is Plastique.
-
- When QIcon is provided with only one available pixmap, that
- pixmap is used for all the states and modes. In this case the
- pixmap's icon mode is set to normal, and the generated pixmaps
- for the normal and active modes will look the same. But in
- disabled and selected mode, Qt will generate a slightly different
- pixmap.
-
- The next screenshot shows the application with an additional file
- loaded, providing QIcon with two available pixmaps. Note that the
- new image file's mode is set to disabled. When rendering the \uicontrol
- Disabled mode pixmaps, Qt will now use the new image. We can see
- the difference: The generated disabled pixmap in the first
- screenshot is slightly darker than the pixmap with the originally
- set disabled mode in the second screenshot.
-
- \image icons_find_normal_disabled.png Screenshot of the Find Files
-
- When Qt renders the icon's pixmaps it searches through the set of
- available pixmaps following a particular algorithm. The algorithm
- is documented in QIcon, but we will describe some particular cases
- below.
-
- \image icons_monkey_active.png Screenshot of the Find Files
-
- In the screenshot above, we have set \c monkey_on_32x32 to be an
- Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To
- render the other six mode/state combinations, QIcon uses the
- search algorithm described in the table below:
-
- \table 100%
- \header \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state)
- \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8
- \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1
- \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0
- \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1
- \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0
- \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1'
- \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0'
- \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1''
- \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li D0''
- \endtable
-
- In the table, "0" and "1" stand for Off" and "On", respectively.
- Single quotes indicates that QIcon generates a disabled ("grayed
- out") version of the pixmap; similarly, double quuote indicate
- that QIcon generates a selected ("blued out") version of the
- pixmap.
-
- The alternatives used in the screenshot above are shown in bold.
- For example, the Disabled/Off pixmap is derived by graying out
- the Normal/Off pixmap (\c monkey_off_64x64).
-
- In the next screenshots, we loaded the whole set of monkey
- images. By checking or unchecking file names from the image list,
- we get different results:
-
- \table
- \row
- \li \inlineimage icons_monkey.png Screenshot of the Monkey Files
- \li \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files
- \endtable
-
- For any given mode/state combination, it is possible to specify
- several images at different resolutions. When rendering an
- icon, QIcon will automatically pick the most suitable image
- and scale it down if necessary. (QIcon never scales up images,
- because this rarely looks good.)
-
- The screenshots below shows what happens when we provide QIcon
- with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c
- qt_extended_48x48.png) and try to render the QIcon at various
- resolutions:
-
- \table
- \row
- \li
- \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8
- \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16
- \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17
- \row
- \li
- \li 8 x 8
- \li \b {16 x 16}
- \li 17 x 17
- \row
- \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32
- \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33
- \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48
- \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64
- \row
- \li \b {32 x 32}
- \li 33 x 33
- \li \b {48 x 48}
- \li 64 x 64
- \endtable
-
- For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and
- scales it down if necessary. For sizes between 17 x 17 and 32 x
- 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses
- \c qt_extended_48x48.png.
-
- \section1 Line-by-Line Walkthrough
-
- The Icons example consists of four classes:
-
- \list
- \li \c MainWindow inherits QMainWindow and is the main application
- window.
- \li \c IconPreviewArea is a custom widget that displays all
- combinations of states and modes for a given icon.
- \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the
- user enter icon sizes (e.g., "48 x 48").
- \li \c ImageDelegate is a subclass of QItemDelegate that provides
- comboboxes for letting the user set the mode and state
- associated with an image.
- \endlist
-
- We will start by reviewing the \c IconPreviewArea class before we
- take a look at the \c MainWindow class. Finally, we will review the
- \c IconSizeSpinBox and \c ImageDelegate classes.
-
- \section2 IconPreviewArea Class Definition
-
- An \c IconPreviewArea widget consists of a group box containing a grid of
- QLabel widgets displaying headers and pixmaps.
-
- \image icons_preview_area.png Screenshot of IconPreviewArea.
-
- \snippet examples/widgets/icons/iconpreviewarea.h 0
-
- The \c IconPreviewArea class inherits QWidget. It displays the
- generated pixmaps corresponding to an icon's possible states and
- modes at a given size.
-
- We need two public functions to set the current icon and the
- icon's size. In addition the class has three private functions: We
- use the \c createHeaderLabel() and \c createPixmapLabel()
- functions when constructing the preview area, and we need the \c
- updatePixmapLabels() function to update the preview area when
- the icon or the icon's size has changed.
-
- The \c NumModes and \c NumStates constants reflect \l{QIcon}'s
- number of currently defined modes and states.
-
- \section2 IconPreviewArea Class Implementation
-
- \snippet examples/widgets/icons/iconpreviewarea.cpp 0
-
- In the constructor we create the labels displaying the headers and
- the icon's generated pixmaps, and add them to a grid layout.
-
- When creating the header labels, we make sure the enums \c
- NumModes and \c NumStates defined in the \c .h file, correspond
- with the number of labels that we create. Then if the enums at
- some point are changed, the \c Q_ASSERT() macro will alert that this
- part of the \c .cpp file needs to be updated as well.
-
- If the application is built in debug mode, the \c Q_ASSERT()
- macro will expand to
-
- \snippet doc/src/snippets/code/doc_src_examples_icons.cpp 0
-
- In release mode, the macro simply disappear. The mode can be set
- in the application's \c .pro file. One way to do so is to add an
- option to \c qmake when building the application:
-
- \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 1
-
- or
-
- \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 2
-
- Another approach is to add this line directly to the \c .pro
- file.
-
- \snippet examples/widgets/icons/iconpreviewarea.cpp 1
- \codeline
- \snippet examples/widgets/icons/iconpreviewarea.cpp 2
-
- The public \c setIcon() and \c setSize() functions change the icon
- or the icon size, and make sure that the generated pixmaps are
- updated.
-
- \snippet examples/widgets/icons/iconpreviewarea.cpp 3
- \codeline
- \snippet examples/widgets/icons/iconpreviewarea.cpp 4
-
- We use the \c createHeaderLabel() and \c createPixmapLabel()
- functions to create the preview area's labels displaying the
- headers and the icon's generated pixmaps. Both functions return
- the QLabel that is created.
-
- \snippet examples/widgets/icons/iconpreviewarea.cpp 5
-
- We use the private \c updatePixmapLabel() function to update the
- generated pixmaps displayed in the preview area.
-
- For each mode, and for each state, we retrieve a pixmap using the
- QIcon::pixmap() function, which generates a pixmap corresponding
- to the given state, mode and size.
-
- \section2 MainWindow Class Definition
-
- The \c MainWindow widget consists of three main elements: an
- images group box, an icon size group box and a preview area.
-
- \image icons-example.png Screenshot of the Icons example
-
- \snippet examples/widgets/icons/mainwindow.h 0
-
- The MainWindow class inherits from QMainWindow. We reimplement the
- constructor, and declare several private slots:
-
- \list
- \li The \c about() slot simply provides information about the example.
- \li The \c changeStyle() slot changes the application's GUI style and
- adjust the style dependent size options.
- \li The \c changeSize() slot changes the size of the preview area's icon.
- \li The \c changeIcon() slot updates the set of pixmaps available to the
- icon displayed in the preview area.
- \li The \c addImage() slot allows the user to load a new image into the
- application.
- \endlist
-
- In addition we declare several private functions to simplify the
- constructor.
-
- \section2 MainWindow Class Implementation
-
- \snippet examples/widgets/icons/mainwindow.cpp 0
-
- In the constructor we first create the main window's central
- widget and its child widgets, and put them in a grid layout. Then
- we create the menus with their associated entries and actions.
-
- Before we resize the application window to a suitable size, we set
- the window title and determine the current style for the
- application. We also enable the icon size spin box by clicking the
- associated radio button, making the current value of the spin box
- the icon's initial size.
-
- \snippet examples/widgets/icons/mainwindow.cpp 1
-
- The \c about() slot displays a message box using the static
- QMessageBox::about() function. In this example it displays a
- simple box with information about the example.
-
- The \c about() function looks for a suitable icon in four
- locations: It prefers its parent's icon if that exists. If it
- doesn't, the function tries the top-level widget containing
- parent, and if that fails, it tries the active window. As a last
- resort it uses the QMessageBox's Information icon.
-
- \snippet examples/widgets/icons/mainwindow.cpp 2
-
- In the \c changeStyle() slot we first check the slot's
- parameter. If it is false we immediately return, otherwise we find
- out which style to change to, i.e. which action that triggered the
- slot, using the QObject::sender() function.
-
- This function returns the sender as a QObject pointer. Since we
- know that the sender is a QAction object, we can safely cast the
- QObject. We could have used a C-style cast or a C++ \c
- static_cast(), but as a defensive programming technique we use a
- \l qobject_cast(). The advantage is that if the object has the
- wrong type, a null pointer is returned. Crashes due to null
- pointers are much easier to diagnose than crashes due to unsafe
- casts.
-
- \snippet examples/widgets/icons/mainwindow.cpp 3
- \snippet examples/widgets/icons/mainwindow.cpp 4
-
- Once we have the action, we extract the style name using
- QAction::data(). Then we create a QStyle object using the static
- QStyleFactory::create() function.
-
- Although we can assume that the style is supported by the
- QStyleFactory: To be on the safe side, we use the \c Q_ASSERT()
- macro to check if the created style is valid before we use the
- QApplication::setStyle() function to set the application's GUI
- style to the new style. QApplication will automatically delete
- the style object when a new style is set or when the application
- exits.
-
- The predefined icon size options provided in the application are
- style dependent, so we need to update the labels in the icon size
- group box and in the end call the \c changeSize() slot to update
- the icon's size.
-
- \snippet examples/widgets/icons/mainwindow.cpp 5
-
- The \c changeSize() slot sets the size for the preview area's
- icon.
-
- To determine the new size we first check if the spin box is
- enabled. If it is, we extract the extent of the new size from the
- box. If it's not, we search through the predefined size options,
- extract the QStyle::PixelMetric and use the QStyle::pixelMetric()
- function to determine the extent. Then we create a QSize object
- based on the extent, and use that object to set the size of the
- preview area's icon.
-
- \snippet examples/widgets/icons/mainwindow.cpp 12
-
- The first thing we do when the \c addImage() slot is called, is to
- show a file dialog to the user. The easiest way to create a file
- dialog is to use QFileDialog's static functions. Here we use the
- \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function
- that will return one or more existing files selected by the user.
-
- For each of the files the file dialog returns, we add a row to the
- table widget. The table widget is listing the images the user has
- loaded into the application.
-
- \snippet examples/widgets/icons/mainwindow.cpp 13
- \snippet examples/widgets/icons/mainwindow.cpp 14
-
- We retrieve the image name using the QFileInfo::baseName()
- function that returns the base name of the file without the path,
- and create the first table widget item in the row. Then we add the
- file's complete name to the item's data. Since an item can hold
- several information pieces, we need to assign the file name a role
- that will distinguish it from other data. This role can be Qt::UserRole
- or any value above it.
-
- We also make sure that the item is not editable by removing the
- Qt::ItemIsEditable flag. Table items are editable by default.
-
- \snippet examples/widgets/icons/mainwindow.cpp 15
- \snippet examples/widgets/icons/mainwindow.cpp 16
- \snippet examples/widgets/icons/mainwindow.cpp 17
-
- Then we create the second and third items in the row making the
- default mode Normal and the default state Off. But if the \uicontrol
- {Guess Image Mode/State} option is checked, and the file name
- contains "_act", "_dis", or "_sel", the modes are changed to
- Active, Disabled, or Selected. And if the file name contains
- "_on", the state is changed to On. The sample files in the
- example's \c images subdirectory respect this naming convension.
-
- \snippet examples/widgets/icons/mainwindow.cpp 18
- \snippet examples/widgets/icons/mainwindow.cpp 19
-
- In the end we add the items to the associated row, and use the
- QTableWidget::openPersistentEditor() function to create
- comboboxes for the mode and state columns of the items.
-
- Due to the connection between the table widget's \l
- {QTableWidget::itemChanged()}{itemChanged()} signal and the \c
- changeIcon() slot, the new image is automatically converted into a
- pixmap and made part of the set of pixmaps available to the icon
- in the preview area. So, corresponding to this fact, we need to
- make sure that the new image's check box is enabled.
-
- \snippet examples/widgets/icons/mainwindow.cpp 6
- \snippet examples/widgets/icons/mainwindow.cpp 7
-
- The \c changeIcon() slot is called when the user alters the set
- of images listed in the QTableWidget, to update the QIcon object
- rendered by the \c IconPreviewArea.
-
- We first create a QIcon object, and then we run through the
- QTableWidget, which lists the images the user has loaded into the
- application.
-
- \snippet examples/widgets/icons/mainwindow.cpp 8
- \snippet examples/widgets/icons/mainwindow.cpp 9
- \snippet examples/widgets/icons/mainwindow.cpp 10
-
- We also extract the image file's name using the
- QTableWidgetItem::data() function. This function takes a
- Qt::DataItemRole as an argument to retrieve the right data
- (remember that an item can hold several pieces of information)
- and returns it as a QVariant. Then we use the
- QVariant::toString() function to get the file name as a QString.
-
- To create a pixmap from the file, we need to first create an
- image and then convert this image into a pixmap using
- QPixmap::fromImage(). Once we have the final pixmap, we add it,
- with its associated mode and state, to the QIcon's set of
- available pixmaps.
-
- \snippet examples/widgets/icons/mainwindow.cpp 11
-
- After running through the entire list of images, we change the
- icon of the preview area to the one we just created.
-
- \snippet examples/widgets/icons/mainwindow.cpp 20
-
- In the \c removeAllImages() slot, we simply set the table widget's
- row count to zero, automatically removing all the images the user
- has loaded into the application. Then we update the set of pixmaps
- available to the preview area's icon using the \c changeIcon()
- slot.
-
- \image icons_images_groupbox.png Screenshot of the images group box
-
- The \c createImagesGroupBox() function is implemented to simplify
- the constructor. The main purpose of the function is to create a
- QTableWidget that will keep track of the images the user has
- loaded into the application.
-
- \snippet examples/widgets/icons/mainwindow.cpp 21
-
- First we create a group box that will contain the table widget.
- Then we create a QTableWidget and customize it to suit our
- purposes.
-
- We call QAbstractItemView::setSelectionMode() to prevent the user
- from selecting items.
-
- The QAbstractItemView::setItemDelegate() call sets the item
- delegate for the table widget. We create a \c ImageDelegate that
- we make the item delegate for our view.
-
- The QItemDelegate class can be used to provide an editor for an item view
- class that is subclassed from QAbstractItemView. Using a delegate
- for this purpose allows the editing mechanism to be customized and
- developed independently from the model and view.
-
- In this example we derive \c ImageDelegate from QItemDelegate.
- QItemDelegate usually provides line editors, while our subclass
- \c ImageDelegate, provides comboboxes for the mode and state
- fields.
-
- \snippet examples/widgets/icons/mainwindow.cpp 22
- \snippet examples/widgets/icons/mainwindow.cpp 23
-
- Then we customize the QTableWidget's horizontal header, and hide
- the vertical header.
-
- \snippet examples/widgets/icons/mainwindow.cpp 24
- \snippet examples/widgets/icons/mainwindow.cpp 25
-
- At the end, we connect the QTableWidget::itemChanged() signal to
- the \c changeIcon() slot to ensuret that the preview area is in
- sync with the image table.
-
- \image icons_size_groupbox.png Screenshot of the icon size group box
-
- The \c createIconSizeGroupBox() function is called from the
- constructor. It creates the widgets controlling the size of the
- preview area's icon.
-
- \snippet examples/widgets/icons/mainwindow.cpp 26
-
- First we create a group box that will contain all the widgets;
- then we create the radio buttons and the spin box.
-
- The spin box is not a regular QSpinBox but an \c IconSizeSpinBox.
- The \c IconSizeSpinBox class inherits QSpinBox and reimplements
- two functions: QSpinBox::textFromValue() and
- QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to
- handle icon sizes, e.g., "32 x 32", instead of plain integer
- values.
-
- \snippet examples/widgets/icons/mainwindow.cpp 27
-
- Then we connect all of the radio buttons
- \l{QRadioButton::toggled()}{toggled()} signals and the spin box's
- \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c
- changeSize() slot to make sure that the size of the preview
- area's icon is updated whenever the user changes the icon size.
- In the end we put the widgets in a layout that we install on the
- group box.
-
- \snippet examples/widgets/icons/mainwindow.cpp 28
-
- In the \c createActions() function we create and customize all the
- actions needed to implement the functionality associated with the
- menu entries in the application.
-
- In particular we create the \c styleActionGroup based on the
- currently available GUI styles using
- QStyleFactory. QStyleFactory::keys() returns a list of valid keys,
- typically including "windows", "motif", "cde", and
- "plastique". Depending on the platform, "windowsxp" and
- "macintosh" may be available.
-
- We create one action for each key, and adds the action to the
- action group. Also, for each action, we call QAction::setData()
- with the style name. We will retrieve it later using
- QAction::data().
-
- \snippet examples/widgets/icons/mainwindow.cpp 29
-
- In the \c createMenu() function, we add the previously created
- actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus. We put each menu in the
- application's menu bar, which we retrieve using
- QMainWindow::menuBar().
-
- \snippet examples/widgets/icons/mainwindow.cpp 30
-
- QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy}
- property that controls how the widget should behave when the user
- requests a context menu (e.g., by right-clicking). We set the
- QTableWidget's context menu policy to Qt::ActionsContextMenu,
- meaning that the \l{QAction}s associated with the widget should
- appear in its context menu.
-
- Then we add the \uicontrol{Add Image} and \uicontrol{Remove All Images}
- actions to the table widget. They will then appear in the table
- widget's context menu.
-
- \snippet examples/widgets/icons/mainwindow.cpp 31
-
- In the \c checkCurrentStyle() function we go through the group of
- style actions, looking for the current GUI style.
-
- For each action, we first extract the style name using
- QAction::data(). Since this is only a QStyleFactory key (e.g.,
- "macintosh"), we cannot compare it directly to the current
- style's class name. We need to create a QStyle object using the
- static QStyleFactory::create() function and compare the class
- name of the created QStyle object with that of the current style.
- As soon as we are done with a QStyle candidate, we delete it.
-
- For all QObject subclasses that use the \c Q_OBJECT macro, the
- class name of an object is available through its
- \l{QObject::metaObject()}{meta-object}.
-
- We can assume that the style is supported by
- QStyleFactory, but to be on the safe side we use the \c
- Q_ASSERT() macro to make sure that QStyleFactory::create()
- returned a valid pointer.
-
- \section2 IconSizeSpinBox Class Definition
-
- \snippet examples/widgets/icons/iconsizespinbox.h 0
-
- The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain
- QSpinBox can only handle integers. But since we want to display
- the spin box's values in a more sophisticated way, we need to
- subclass QSpinBox and reimplement the QSpinBox::textFromValue()
- and QSpinBox::valueFromText() functions.
-
- \image icons_size_spinbox.png Screenshot of the icon size spinbox
-
- \section2 IconSizeSpinBox Class Implementation
-
- \snippet examples/widgets/icons/iconsizespinbox.cpp 0
-
- The constructor is trivial.
-
- \snippet examples/widgets/icons/iconsizespinbox.cpp 2
-
- QSpinBox::textFromValue() is used by the spin box whenever it
- needs to display a value. The default implementation returns a
- base 10 representation of the \c value parameter.
-
- Our reimplementation returns a QString of the form "32 x 32".
-
- \snippet examples/widgets/icons/iconsizespinbox.cpp 1
-
- The QSpinBox::valueFromText() function is used by the spin box
- whenever it needs to interpret text typed in by the user. Since
- we reimplement the \c textFromValue() function we also need to
- reimplement the \c valueFromText() function to interpret the
- parameter text and return the associated int value.
-
- We parse the text using a regular expression (a QRegExp). We
- define an expression that matches one or several digits,
- optionally followed by whitespace, an "x" or the times symbol,
- whitespace and one or several digits again.
-
- The first digits of the regular expression are captured using
- parentheses. This enables us to use the QRegExp::cap() or
- QRegExp::capturedTexts() functions to extract the matched
- characters. If the first and second numbers of the spin box value
- differ (e.g., "16 x 24"), we use the first number.
-
- When the user presses \uicontrol Enter, QSpinBox first calls
- QSpinBox::valueFromText() to interpret the text typed by the
- user, then QSpinBox::textFromValue() to present it in a canonical
- format (e.g., "16 x 16").
-
- \section2 ImageDelegate Class Definition
-
- \snippet examples/widgets/icons/imagedelegate.h 0
-
- The \c ImageDelegate class is a subclass of QItemDelegate. The
- QItemDelegate class provides display and editing facilities for
- data items from a model. A single QItemDelegate object is
- responsible for all items displayed in a item view (in our case,
- a QTableWidget).
-
- A QItemDelegate can be used to provide an editor for an item view
- class that is subclassed from QAbstractItemView. Using a delegate
- for this purpose allows the editing mechanism to be customized and
- developed independently from the model and view.
-
- \snippet examples/widgets/icons/imagedelegate.h 1
-
- The default implementation of QItemDelegate creates a QLineEdit.
- Since we want the editor to be a QComboBox, we need to subclass
- QItemDelegate and reimplement the QItemDelegate::createEditor(),
- QItemDelegate::setEditorData() and QItemDelegate::setModelData()
- functions.
-
- \snippet examples/widgets/icons/imagedelegate.h 2
-
- The \c emitCommitData() slot is used to emit the
- QImageDelegate::commitData() signal with the appropriate
- argument.
-
- \section2 ImageDelegate Class Implementation
-
- \snippet examples/widgets/icons/imagedelegate.cpp 0
-
- The constructor is trivial.
-
- \snippet examples/widgets/icons/imagedelegate.cpp 1
-
- The default QItemDelegate::createEditor() implementation returns
- the widget used to edit the item specified by the model and item
- index for editing. The parent widget and style option are used to
- control the appearance of the editor widget.
-
- Our reimplementation create and populate a combobox instead of
- the default line edit. The contents of the combobox depends on
- the column in the table for which the editor is requested. Column
- 1 contains the QIcon modes, whereas column 2 contains the QIcon
- states.
-
- In addition, we connect the combobox's \l
- {QComboBox::activated()}{activated()} signal to the \c
- emitCommitData() slot to emit the
- QAbstractItemDelegate::commitData() signal whenever the user
- chooses an item using the combobox. This ensures that the rest of
- the application notices the change and updates itself.
-
- \snippet examples/widgets/icons/imagedelegate.cpp 2
-
- The QItemDelegate::setEditorData() function is used by
- QTableWidget to transfer data from a QTableWidgetItem to the
- editor. The data is stored as a string; we use
- QComboBox::findText() to locate it in the combobox.
-
- Delegates work in terms of models, not items. This makes it
- possible to use them with any item view class (e.g., QListView,
- QListWidget, QTreeView, etc.). The transition between model and
- items is done implicitly by QTableWidget; we don't need to worry
- about it.
-
- \snippet examples/widgets/icons/imagedelegate.cpp 3
-
- The QItemDelegate::setEditorData() function is used by QTableWidget
- to transfer data back from the editor to the \l{QTableWidgetItem}.
-
- \snippet examples/widgets/icons/imagedelegate.cpp 4
-
- The \c emitCommitData() slot simply emit the
- QAbstractItemDelegate::commitData() signal for the editor that
- triggered the slot. This signal must be emitted when the editor
- widget has completed editing the data, and wants to write it back
- into the model.
-*/
diff --git a/doc/src/examples/imagecomposition.qdoc b/doc/src/examples/imagecomposition.qdoc
deleted file mode 100644
index d7700858a0..0000000000
--- a/doc/src/examples/imagecomposition.qdoc
+++ /dev/null
@@ -1,165 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/imagecomposition
- \title Image Composition Example
-
- The Image Composition example lets the user combine images
- together using any composition mode supported by QPainter, described
- in detail in \l{QPainter#Composition Modes}{Composition Modes}.
-
- \image imagecomposition-example.png
-
- \section1 Setting Up The Resource File
-
- The Image Composition example requires two source images,
- \e butterfly.png and \e checker.png that are embedded within
- \e imagecomposition.qrc. The file contains the following code:
-
- \quotefile examples/painting/imagecomposition/imagecomposition.qrc
-
- For more information on resource files, see \l{The Qt Resource System}.
-
- \section1 ImageComposer Class Definition
-
- The \c ImageComposer class is a subclass of QWidget that implements three
- private slots, \c chooseSource(), \c chooseDestination(), and
- \c recalculateResult().
-
- \snippet examples/painting/imagecomposition/imagecomposer.h 0
-
- In addition, \c ImageComposer consists of five private functions,
- \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and
- \c imagePos(), as well as private instances of QToolButton, QComboBox,
- QLabel, and QImage.
-
- \snippet examples/painting/imagecomposition/imagecomposer.h 1
-
- \section1 ImageComposer Class Implementation
-
- We declare a QSize object, \c resultSize, as a static constant with width
- and height equal to 200.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 0
-
- Within the constructor, we instantiate a QToolButton object,
- \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize}
- property to \c resultSize. The \c operatorComboBox is instantiated and
- then populated using the \c addOp() function. This function accepts a
- QPainter::CompositionMode, \a mode, and a QString, \a name, representing
- the name of the composition mode.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 1
-
- The \c destinationButton is instantiated and its
- \l{QAbstractButton::setIconSize()}{iconSize} property is set to
- \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel
- are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()}
- {minimumWidth} is set.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 2
-
- We connect the following signals to their corresponding slots:
- \list
- \li \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is
- connected to \c chooseSource(),
- \li \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()}
- signal is connected to \c recalculateResult(), and
- \li \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal
- is connected to \c chooseDestination().
- \endlist
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 3
-
- A QGridLayout, \c mainLayout, is used to place all the widgets. Note
- that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint}
- property is set to QLayout::SetFixedSize, which means that
- \c{ImageComposer}'s size cannot be resized at all.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 4
-
- We create a QImage, \c resultImage, and we invoke \c loadImage() twice
- to load both the image files in our \e imagecomposition.qrc file. Then,
- we set the \l{QWidget::setWindowTitle()}{windowTitle} property to
- "Image Composition".
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 5
-
- The \c chooseSource() and \c chooseDestination() functions are
- convenience functions that invoke \c chooseImage() with specific
- parameters.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 6
- \codeline
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 7
-
- The \c chooseImage() function loads an image of the user's choice,
- depending on the \a title, \a image, and \a button.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 10
-
- The \c recalculateResult() function is used to calculate amd display the
- result of combining the two images together with the user's choice of
- composition mode.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 8
-
- The \c addOp() function adds an item to the \c operatorComboBox using
- \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function
- accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The
- rectangle is filled with Qt::Transparent and both the \c sourceImage and
- \c destinationImage are painted, before displaying it on \c resultLabel.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 9
-
- The \c loadImage() function paints a transparent background using
- \l{QPainter::fillRect()}{fillRect()} and draws \c image in a
- centralized position using \l{QPainter::drawImage()}{drawImage()}.
- This \c image is then set as the \c{button}'s icon.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 11
-
- The \c currentMode() function returns the composition mode currently
- selected in \c operatorComboBox.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 12
-
- We use the \c imagePos() function to ensure that images loaded onto the
- QToolButton objects, \c sourceButton and \c destinationButton, are
- centralized.
-
- \snippet examples/painting/imagecomposition/imagecomposer.cpp 13
-
- \section1 The \c main() Function
-
- The \c main() function instantiates QApplication and \c ImageComposer
- and invokes its \l{QWidget::show()}{show()} function.
-
- \snippet examples/painting/imagecomposition/main.cpp 0
-
- */
diff --git a/doc/src/examples/imageviewer.qdoc b/doc/src/examples/imageviewer.qdoc
deleted file mode 100644
index 554543e252..0000000000
--- a/doc/src/examples/imageviewer.qdoc
+++ /dev/null
@@ -1,326 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/imageviewer
- \title Image Viewer Example
-
- The example shows how to combine QLabel and QScrollArea to
- display an image. QLabel is typically used for displaying text,
- but it can also display an image. QScrollArea provides a
- scrolling view around another widget. If the child widget exceeds
- the size of the frame, QScrollArea automatically provides scroll
- bars.
-
- The example demonstrates how QLabel's ability to scale its
- contents (QLabel::scaledContents), and QScrollArea's ability to
- automatically resize its contents (QScrollArea::widgetResizable),
- can be used to implement zooming and scaling features. In
- addition the example shows how to use QPainter to print an image.
-
- \image imageviewer-example.png Screenshot of the Image Viewer example
-
- With the Image Viewer application, the users can view an image of
- their choice. The \uicontrol File menu gives the user the possibility
- to:
-
- \list
- \li \uicontrol{Open...} - Open an image file
- \li \uicontrol{Print...} - Print an image
- \li \uicontrol{Exit} - Exit the application
- \endlist
-
- Once an image is loaded, the \uicontrol View menu allows the users to:
-
- \list
- \li \uicontrol{Zoom In} - Scale the image up by 25%
- \li \uicontrol{Zoom Out} - Scale the image down by 25%
- \li \uicontrol{Normal Size} - Show the image at its original size
- \li \uicontrol{Fit to Window} - Stretch the image to occupy the entire window
- \endlist
-
- In addition the \uicontrol Help menu provides the users with information
- about the Image Viewer example in particular, and about Qt in
- general.
-
- \section1 ImageViewer Class Definition
-
- \snippet examples/widgets/imageviewer/imageviewer.h 0
-
- The \c ImageViewer class inherits from QMainWindow. We reimplement
- the constructor, and create several private slots to facilitate
- the menu entries. In addition we create four private functions.
-
- We use \c createActions() and \c createMenus() when constructing
- the \c ImageViewer widget. We use the \c updateActions() function
- to update the menu entries when a new image is loaded, or when
- the \uicontrol {Fit to Window} option is toggled. The zoom slots use \c
- scaleImage() to perform the zooming. In turn, \c
- scaleImage() uses \c adjustScrollBar() to preserve the focal point after
- scaling an image.
-
- \section1 ImageViewer Class Implementation
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 0
-
- In the constructor we first create the label and the scroll area.
-
- We set \c {imageLabel}'s size policy to \l
- {QSizePolicy::Ignored}{ignored}, making the users able to scale
- the image to whatever size they want when the \uicontrol {Fit to Window}
- option is turned on. Otherwise, the default size polizy (\l
- {QSizePolicy::Preferred}{preferred}) will make scroll bars appear
- when the scroll area becomes smaller than the label's minimum size
- hint.
-
- We ensure that the label will scale its contents to fill all
- available space, to enable the image to scale properly when
- zooming. If we omitted to set the \c {imageLabel}'s \l
- {QLabel::scaledContents}{scaledContents} property, zooming in
- would enlarge the QLabel, but leave the pixmap at
- its original size, exposing the QLabel's background.
-
- We make \c imageLabel the scroll area's child widget, and we make
- \c scrollArea the central widget of the QMainWindow. At the end
- we create the associated actions and menus, and customize the \c
- {ImageViewer}'s appearance.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 1
- \snippet examples/widgets/imageviewer/imageviewer.cpp 2
-
- In the \c open() slot, we show a file dialog to the user. The
- easiest way to create a QFileDialog is to use the static
- convenience functions. QFileDialog::getOpenFileName() returns an
- existing file selected by the user. If the user presses \uicontrol
- Cancel, QFileDialog returns an empty string.
-
- Unless the file name is a empty string, we check if the file's
- format is an image format by constructing a QImage which tries to
- load the image from the file. If the constructor returns a null
- image, we use a QMessageBox to alert the user.
-
- The QMessageBox class provides a modal dialog with a short
- message, an icon, and some buttons. As with QFileDialog the
- easiest way to create a QMessageBox is to use its static
- convenience functions. QMessageBox provides a range of different
- messages arranged along two axes: severity (question,
- information, warning and critical) and complexity (the number of
- necessary response buttons). In this particular example an
- information message with an \uicontrol OK button (the default) is
- sufficient, since the message is part of a normal operation.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 3
- \snippet examples/widgets/imageviewer/imageviewer.cpp 4
-
- If the format is supported, we display the image in \c imageLabel
- by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable
- the \uicontrol Print and \uicontrol {Fit to Window} menu entries and update
- the rest of the view menu entries. The \uicontrol Open and \uicontrol Exit
- entries are enabled by default.
-
- If the \uicontrol {Fit to Window} option is turned off, the
- QScrollArea::widgetResizable property is \c false and it is
- our responsibility (not QScrollArea's) to give the QLabel a
- reasonable size based on its contents. We call
- \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is
- essentially the same as
-
- \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 0
-
- In the \c print() slot, we first make sure that an image has been
- loaded into the application:
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 5
- \snippet examples/widgets/imageviewer/imageviewer.cpp 6
-
- If the application is built in debug mode, the \c Q_ASSERT() macro
- will expand to
-
- \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 1
-
- In release mode, the macro simply disappear. The mode can be set
- in the application's \c .pro file. One way to do so is to add an
- option to \uicontrol qmake when building the application:
-
- \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 2
-
- or
-
- \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 3
-
- Another approach is to add this line directly to the \c .pro
- file.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 7
- \snippet examples/widgets/imageviewer/imageviewer.cpp 8
-
- Then we present a print dialog allowing the user to choose a
- printer and to set a few options. We construct a painter with a
- QPrinter as the paint device. We set the painter's window
- and viewport in such a way that the image is as large as possible
- on the paper, but without altering its
- \l{Qt::KeepAspectRatio}{aspect ratio}.
-
- In the end we draw the pixmap at position (0, 0).
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 9
- \snippet examples/widgets/imageviewer/imageviewer.cpp 10
-
- We implement the zooming slots using the private \c scaleImage()
- function. We set the scaling factors to 1.25 and 0.8,
- respectively. These factor values ensure that a \uicontrol {Zoom In}
- action and a \uicontrol {Zoom Out} action will cancel each other (since
- 1.25 * 0.8 == 1), and in that way the normal image size can be
- restored using the zooming features.
-
- The screenshots below show an image in its normal size, and the
- same image after zooming in:
-
- \table
- \row
- \li \inlineimage imageviewer-original_size.png
- \li \inlineimage imageviewer-zoom_in_1.png
- \li \inlineimage imageviewer-zoom_in_2.png
- \endtable
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 11
- \snippet examples/widgets/imageviewer/imageviewer.cpp 12
-
- When zooming, we use the QLabel's ability to scale its contents.
- Such scaling doesn't change the actual size hint of the contents.
- And since the \l {QLabel::adjustSize()}{adjustSize()} function
- use those size hint, the only thing we need to do to restore the
- normal size of the currently displayed image is to call \c
- adjustSize() and reset the scale factor to 1.0.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 13
- \snippet examples/widgets/imageviewer/imageviewer.cpp 14
-
- The \c fitToWindow() slot is called each time the user toggled
- the \uicontrol {Fit to Window} option. If the slot is called to turn on
- the option, we tell the scroll area to resize its child widget
- with the QScrollArea::setWidgetResizable() function. Then we
- disable the \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal
- Size} menu entries using the private \c updateActions() function.
-
- If the \l {QScrollArea::widgetResizable} property is set to \c
- false (the default), the scroll area honors the size of its child
- widget. If this property is set to \c true, the scroll area will
- automatically resize the widget in order to avoid scroll bars
- where they can be avoided, or to take advantage of extra space.
- But the scroll area will honor the minimum size hint of its child
- widget independent of the widget resizable property. So in this
- example we set \c {imageLabel}'s size policy to \l
- {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that
- scroll bars appear when the scroll area becomes smaller than the
- label's minimum size hint.
-
- The screenshots below shows an image in its normal size, and the
- same image with the \uicontrol {Fit to window} option turned on.
- Enlarging the window will stretch the image further, as shown in
- the third screenshot.
-
- \table
- \row
- \li \inlineimage imageviewer-original_size.png
- \li \inlineimage imageviewer-fit_to_window_1.png
- \li \inlineimage imageviewer-fit_to_window_2.png
- \endtable
-
- If the slot is called to turn off the option, the
- {QScrollArea::setWidgetResizable} property is set to \c false. We
- also restore the image pixmap to its normal size by adjusting the
- label's size to its content. And in the end we update the view
- menu entries.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 15
- \snippet examples/widgets/imageviewer/imageviewer.cpp 16
-
- We implement the \c about() slot to create a message box
- describing what the example is designed to show.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 17
- \snippet examples/widgets/imageviewer/imageviewer.cpp 18
-
- In the private \c createAction() function, we create the
- actions providing the application features.
-
- We assign a short-cut key to each action and connect them to the
- appropriate slots. We only enable the \c openAct and \c exitAct at
- the time of creation, the others are updated once an image has
- been loaded into the application. In addition we make the \c
- fitToWindowAct \l {QAction::checkable}{checkable}.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 19
- \snippet examples/widgets/imageviewer/imageviewer.cpp 20
-
- In the private \c createMenu() function, we add the previously
- created actions to the \uicontrol File, \uicontrol View and \uicontrol Help menus.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus. The QMenuBar class provides
- a horizontal menu bar that consists of a list of pull-down menu
- items. So at the end we put the menus in the \c {ImageViewer}'s
- menu bar which we retrieve with the QMainWindow::menuBar()
- function.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 21
- \snippet examples/widgets/imageviewer/imageviewer.cpp 22
-
- The private \c updateActions() function enables or disables the
- \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal Size} menu
- entries depending on whether the \uicontrol {Fit to Window} option is
- turned on or off.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 23
- \snippet examples/widgets/imageviewer/imageviewer.cpp 24
-
- In \c scaleImage(), we use the \c factor parameter to calculate
- the new scaling factor for the displayed image, and resize \c
- imageLabel. Since we set the
- \l{QLabel::scaledContents}{scaledContents} property to \c true in
- the constructor, the call to QWidget::resize() will scale the
- image displayed in the label. We also adjust the scroll bars to
- preserve the focal point of the image.
-
- At the end, if the scale factor is less than 33.3% or greater
- than 300%, we disable the respective menu entry to prevent the
- image pixmap from becoming too large, consuming too much
- resources in the window system.
-
- \snippet examples/widgets/imageviewer/imageviewer.cpp 25
- \snippet examples/widgets/imageviewer/imageviewer.cpp 26
-
- Whenever we zoom in or out, we need to adjust the scroll bars in
- consequence. It would have been tempting to simply call
-
- \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 4
-
- but this would make the top-left corner the focal point, not the
- center. Therefore we need to take into account the scroll bar
- handle's size (the \l{QScrollBar::pageStep}{page step}).
-*/
diff --git a/doc/src/examples/interview.qdoc b/doc/src/examples/interview.qdoc
deleted file mode 100644
index 35721ccfae..0000000000
--- a/doc/src/examples/interview.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/interview
- \title Interview
-
- The Interview example explores the flexibility and scalability of the
- model/view framework by presenting an infinitely deep data structure using a model
- and three different types of view.
-
- \image interview-demo.png
-*/
diff --git a/doc/src/examples/licensewizard.qdoc b/doc/src/examples/licensewizard.qdoc
deleted file mode 100644
index f0ad723d50..0000000000
--- a/doc/src/examples/licensewizard.qdoc
+++ /dev/null
@@ -1,218 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/licensewizard
- \title License Wizard Example
-
- The License Wizard example shows how to implement complex wizards in
- Qt.
-
- \image licensewizard-example.png Screenshot of the License Wizard example
-
- Most wizards have a linear structure, with page 1 followed by
- page 2 and so on until the last page. The
- \l{dialogs/classwizard}{Class Wizard} example shows how to create
- such wizards.
-
- Some wizards are more complex in that they allow different
- traversal paths based on the information provided by the user.
- The License Wizard example illustrates this. It provides five
- wizard pages; depending on which options are selected, the user
- can reach different pages.
-
- \image licensewizard-flow.png The License Wizard pages
-
- The example consists of the following classes:
-
- \list
- \li \c LicenseWizard inherits QWizard and implements a non-linear
- five-page wizard that leads the user through the process of
- choosing a license agreement.
- \li \c IntroPage, \c EvaluatePage, \c RegisterPage, \c
- DetailsPage, and \c ConclusionPage are QWizardPage subclasses
- that implement the wizard pages.
- \endlist
-
- \section1 The LicenseWizard Class
-
- The \c LicenseWizard class derives from QWizard and provides a
- five-page wizard that guides the user through the process of
- registering their copy of a fictitious software product. Here's
- the class definition:
-
- \snippet examples/dialogs/licensewizard/licensewizard.h 1
-
- The class's public API is limited to a constructor and an enum.
- The enum defines the IDs associated with the various pages:
-
- \table
- \header \li Class name \li Enum value \li Page ID
- \row \li \c IntroPage \li \c Page_Intro \li 0
- \row \li \c EvaluatePage \li \c Page_Evaluate \li 1
- \row \li \c RegisterPage \li \c Page_Register \li 2
- \row \li \c DetailsPage \li \c Page_Details \li 3
- \row \li \c ConclusionPage \li \c Page_Conclusion \li 4
- \endtable
-
- For this example, the IDs are arbitrary. The only constraints are
- that they must be unique and different from -1. IDs allow us to
- refer to pages.
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 2
-
- In the constructor, we create the five pages, insert them into
- the wizard using QWizard::setPage(), and set \c Page_Intro to be
- the first page.
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 3
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 4
-
- We set the style to \l{QWizard::}{ModernStyle} on all platforms
- except Mac OS X,
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 5
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 6
-
- We configure the QWizard to show a \uicontrol Help button, which is
- connected to our \c showHelp() slot. We also set the
- \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e.,
- \c EvaluatePage, \c RegisterPage, and \c DetailsPage).
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 9
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 11
- \dots
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 13
-
- In \c showHelp(), we display help texts that are appropriate for
- the current page. If the user clicks \uicontrol Help twice for the same
- page, we say, "Sorry, I already gave what help I could. Maybe you
- should try asking a human?"
-
- \section1 The IntroPage Class
-
- The pages are defined in \c licensewizard.h and implemented in \c
- licensewizard.cpp, together with \c LicenseWizard.
-
- Here's the definition and implementation of \c{IntroPage}:
-
- \snippet examples/dialogs/licensewizard/licensewizard.h 4
- \codeline
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 16
-
- A page inherits from QWizardPage. We set a
- \l{QWizardPage::}{title} and a
- \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting
- any \l{QWizardPage::}{subTitle}, we ensure that no header is
- displayed for this page. (On Windows, it is customary for wizards
- to display a watermark pixmap on the first and last pages, and to
- have a header on the other pages.)
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 17
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 19
-
- The \c nextId() function returns the ID for \c EvaluatePage if
- the \uicontrol{Evaluate the product for 30 days} option is checked;
- otherwise it returns the ID for \c RegisterPage.
-
- \section1 The EvaluatePage Class
-
- The \c EvaluatePage is slightly more involved:
-
- \snippet examples/dialogs/licensewizard/licensewizard.h 5
- \codeline
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 20
- \dots
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 21
- \dots
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 22
-
- First, we set the page's \l{QWizardPage::}{title}
- and \l{QWizardPage::}{subTitle}.
-
- Then we create the child widgets, create \l{Registering and Using
- Fields}{wizard fields} associated with them, and put them into
- layouts. The fields are created with an asterisk (\c
- *) next to their name. This makes them \l{mandatory fields}, that
- is, fields that must be filled before the user can press the
- \uicontrol Next button (\uicontrol Continue on Mac OS X). The fields' values
- can be accessed from any other page using QWizardPage::field().
-
- Resetting the page amounts to clearing the two text fields.
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 23
-
- The next page is always the \c ConclusionPage.
-
- \section1 The ConclusionPage Class
-
- The \c RegisterPage and \c DetailsPage are very similar to \c
- EvaluatePage. Let's go directly to the \c ConclusionPage:
-
- \snippet examples/dialogs/licensewizard/licensewizard.h 6
-
- This time, we reimplement QWizardPage::initializePage() and
- QWidget::setVisible(), in addition to
- \l{QWizardPage::}{nextId()}. We also declare a private slot:
- \c printButtonClicked().
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 18
-
- The default implementation of QWizardPage::nextId() returns
- the page with the next ID, or -1 if the current page has the
- highest ID. This behavior would work here, because \c
- Page_Conclusion equals 5 and there is no page with a higher ID,
- but to avoid relying on such subtle behavior, we reimplement
- \l{QWizardPage::}{nextId()} to return -1.
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 27
-
- We use QWizard::hasVisitedPage() to determine the type of
- license agreement the user has chosen. If the user filled the \c
- EvaluatePage, the license text refers to an Evaluation License
- Agreement. If the user filled the \c DetailsPage, the license
- text is a First-Time License Agreement. If the user provided an
- upgrade key and skipped the \c DetailsPage, the license text is
- an Update License Agreement.
-
- \snippet examples/dialogs/licensewizard/licensewizard.cpp 28
-
- We want to display a \uicontrol Print button in the wizard when the \c
- ConclusionPage is up. One way to accomplish this is to reimplement
- QWidget::setVisible():
-
- \list
- \li If the page is shown, we set the \l{QWizard::}{CustomButton1} button's
- text to \uicontrol{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1}
- option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()}
- signal to our \c printButtonClicked() slot.
- \li If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1}
- option and disconnect the \c printButtonClicked() slot.
- \endlist
-
- \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example}
-*/
diff --git a/doc/src/examples/lighting.qdoc b/doc/src/examples/lighting.qdoc
deleted file mode 100644
index aafa70f38c..0000000000
--- a/doc/src/examples/lighting.qdoc
+++ /dev/null
@@ -1,33 +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$
-**
-****************************************************************************/
-
-/*!
- \example effects/lighting
- \title Lighting Effect Example
-
- \image lightingeffect-example.png
-*/
diff --git a/doc/src/examples/lineedits.qdoc b/doc/src/examples/lineedits.qdoc
deleted file mode 100644
index 70d85cff69..0000000000
--- a/doc/src/examples/lineedits.qdoc
+++ /dev/null
@@ -1,161 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/lineedits
- \title Line Edits Example
-
- The Line Edits example demonstrates the many ways that QLineEdit can be used, and
- shows the effects of various properties and validators on the input and output
- supplied by the user.
-
- \image lineedits-example.png
-
- The example consists of a single \c Window class, containing a selection of
- line edits with different input constraints and display properties that can be
- changed by selecting items from comboboxes. Presenting these together helps
- developers choose suitable properties to use with line edits, and makes it easy
- to compare the effects of each validator on user input.
-
- \section1 Window Class Definition
-
- The \c Window class inherits QWidget and contains a constructor and several
- slots:
-
- \snippet examples/widgets/lineedits/window.h 0
-
- The slots are used to update the type of validator used for a given line edit when
- a new validator has been selected in the associated combobox. The line edits
- are stored in the window for use in these slots.
-
- \section1 Window Class Implementation
-
- The \c Window constructor is used to set up the line edits, validators,
- and comboboxes, connect signals from the comboboxes to slots in the \c Window
- class, and arrange the child widgets in layouts.
-
- We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox,
- and line edit so that we can demonstrate the QLineEdit::echoMode property:
-
- \snippet examples/widgets/lineedits/window.cpp 0
-
- At this point, none of these widgets have been arranged in layouts. Eventually,
- the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a
- vertical layout inside the \c echoGroup group box.
-
- Similarly, we construct group boxes and collections of widgets to show the
- effects of QIntValidator and QDoubleValidator on a line edit's contents:
-
- \snippet examples/widgets/lineedits/window.cpp 1
-
- Text alignment is demonstrated by another group of widgets:
-
- \snippet examples/widgets/lineedits/window.cpp 2
-
- QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}.
- These only allow the user to type characters into the line edit that
- follow a simple specification. We construct a group of widgets to
- demonstrate a selection of predefined masks:
-
- \snippet examples/widgets/lineedits/window.cpp 3
-
- Another useful feature of QLineEdit is its ability to make its contents
- read-only. This property is used to control access to a line edit in the
- following group of widgets:
-
- \snippet examples/widgets/lineedits/window.cpp 4
-
- Now that all the child widgets have been constructed, we connect signals
- from the comboboxes to slots in the \c Window object:
-
- \snippet examples/widgets/lineedits/window.cpp 5
-
- Each of these connections use the QComboBox::activated() signal that
- supplies an integer to the slot. This will be used to efficiently
- make changes to the appropriate line edit in each slot.
-
- We place each combobox, line edit, and label in a layout for each group
- box, beginning with the layout for the \c echoGroup group box:
-
- \snippet examples/widgets/lineedits/window.cpp 6
-
- The other layouts are constructed in the same way:
-
- \snippet examples/widgets/lineedits/window.cpp 7
-
- Finally, we place each group box in a grid layout for the \c Window object
- and set the window title:
-
- \snippet examples/widgets/lineedits/window.cpp 8
-
- The slots respond to signals emitted when the comboboxes are changed by the
- user.
-
- When the combobox for the \uicontrol{Echo} group box is changed, the \c echoChanged()
- slot is called:
-
- \snippet examples/widgets/lineedits/window.cpp 9
-
- The slot updates the line edit in the same group box to use an echo mode that
- corresponds to the entry described in the combobox.
-
- When the combobox for the \uicontrol{Validator} group box is changed, the
- \c validatorChanged() slot is called:
-
- \snippet examples/widgets/lineedits/window.cpp 10
-
- The slot either creates a new validator for the line edit to use, or it removes
- the validator in use by calling QLineEdit::setValidator() with a zero pointer.
- We clear the line edit in this case to ensure that the new validator is
- initially given valid input to work with.
-
- When the combobox for the \uicontrol{Alignment} group box is changed, the
- \c alignmentChanged() slot is called:
-
- \snippet examples/widgets/lineedits/window.cpp 11
-
- This changes the way that text is displayed in the line edit to correspond with
- the description selected in the combobox.
-
- The \c inputMaskChanged() slot handles changes to the combobox in the
- \uicontrol{Input Mask} group box:
-
- \snippet examples/widgets/lineedits/window.cpp 12
-
- Each entry in the relevant combobox is associated with an input mask. We set
- a new mask by calling the QLineEdit::setMask() function with a suitable string;
- the mask is disabled if an empty string is used.
-
- The \c accessChanged() slot handles changes to the combobox in the
- \uicontrol{Access} group box:
-
- \snippet examples/widgets/lineedits/window.cpp 13
-
- Here, we simply associate the \uicontrol{False} and \uicontrol{True} entries in the combobox
- with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This
- allows the user to enable and disable input to the line edit.
-*/
diff --git a/doc/src/examples/maemovibration.qdoc b/doc/src/examples/maemovibration.qdoc
deleted file mode 100644
index 78bb7f5334..0000000000
--- a/doc/src/examples/maemovibration.qdoc
+++ /dev/null
@@ -1,164 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/maemovibration
- \group all-examples
- \title Maemo Vibration Example
-
- The Maemo Vibration example shows how to tell the Maemo Mode Control Entity
- (MCE) to vibrate a maemo device.
-
- The MCE is a system service on Maemo that, among other things, provides an
- D-Bus interface to trigger vibrations. The vibrations are specified as
- patterns and are defined in a system configuration file.
-
- The example program reads the configuration file to look for possible
- vibration patterns and display a button for each. Pressing a button will
- make the device vibrate accordingly, until the application closes, or
- another pattern is started.
-
- \image maemovibration-example.png Screenshot of the Maemo Vibration Example
-
- The code makes use of two classes:
-
- \list
- \li \c MceVibrator connects to the MCE service and can start a certain
- vibrator pattern. It also is responsible to parse the configuration
- file.
-
- \li \c ButtonWidget provides a button for each pattern. Pressing the button
- activates the pattern in question.
- \endlist
-
-
- \section1 MceVibrator Class Definition
-
- \snippet examples/widgets/maemovibration/mcevibrator.h 0
-
- The \c MceVibrator class inherits from QObject and provides a specialized
- and Qt friendly interface to the MCE vibration facilty. The slot \c vibrate()
- can be called to make the device vibrate according to a specific pattern
- name. We will connect it to a signal of a \c ButtonWidget object later. The
- static method \c ParsePatternNames() can be called to find out which patterns
- are available to us.
-
- \list
- \li \c mceInterface is our D-Bus handle to the MCE service. We use it to
- invoke methods on the MCE request object.
-
- \li \c lastPatternName contains the pattern that was activated last time. We
- have to keep track of this, because the last pattern has to be
- deactivated before activating a new pattern.
- \endlist
-
-
- \section1 MceVibrator Class Implementation
-
- To connect to the service, we initialize the D-Bus interface handle. The
- system header \c "mce/dbus-names.h" contains definitions of the D-Bus
- service name and request object path and interface. These are passed to the
- constructor of the handle, and Qt will automatically establish a connection
- to it, if it is possible.
-
- The MCE expects us to first enable the vibrator before we can use it. This
- is done with the call to the \c MCE_ENABLE_VIBRATOR D-Bus method.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 0
-
- From now on we can activate vibration patterns. Each time a vibration
- pattern is activated, the last pattern has to be deactivated first. In the
- vibrate slot we use the MCE interface to call the activation method.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 1
-
- The calls to the private method deactivate simply makes sure to deactivate
- the last pattern used, if there was one.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 2
-
- Calling either the activate or deactivate MCE D-Bus method with invalid
- pattern names are ignored.
-
- Finally, the destructor disables the vibrator. When the destructor of the
- MCE interface handle is called, the connection is also closed.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 3
-
- The MCE configuration file contains options for many different things. We
- are only interested in one line that contains the vibration patterns. It
- has the following format:
-
-
- \code
- VibratorPatterns=semicolon;separated;list;of;values
- \endcode
-
- The static method \c ParsePatternNames looks for this line and returns a
- QStringList containing the values, which are the pattern names we can use.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 4
-
- The helper function \c checkError() saves us some code duplication. None of the
- called methods return anything of use to us, so we're only interested in
- getting error messages for debugging.
-
- \snippet examples/widgets/maemovibration/mcevibrator.cpp 5
-
-
- \section1 ButtonWidget Class Definition
-
- \snippet examples/widgets/maemovibration/buttonwidget.h 0
-
- The \c ButtonWidget class inherits from QWidget and provides the main user
- interface for the application. It creates a grid of buttons, one for each
- string in the stringlist passed to the constructor. Pressing a button emits
- the \c clicked() signal, where the string is the text of the button that
- was pressed.
-
- This class is taken from the QSignalMapper documentation. The only change
- is the number of columns in the grid from three to two, to make the button
- labels fit.
-
-
- \section1 ButtonWidget Class Implementation
-
- \snippet examples/widgets/maemovibration/buttonwidget.cpp 0
-
-
- \section1 \c main() Function
-
- The main function begins with looking up the patterns available to us.
-
- \snippet examples/widgets/maemovibration/main.cpp 0
-
- Then we create one instance of both classes, and connects the
- \c ButtonWidget's clicked signal to the \c MceVibrator's \c vibrate() slot.
- This works, since the button texts are the same as the pattern names.
-
- \snippet examples/widgets/maemovibration/main.cpp 1
-*/
diff --git a/doc/src/examples/mainwindow.qdoc b/doc/src/examples/mainwindow.qdoc
deleted file mode 100644
index b4f6aebed1..0000000000
--- a/doc/src/examples/mainwindow.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/mainwindow
- \title Main Window
-
- The Main Window example shows Qt's extensive support for tool bars,
- dock windows, menus, and other standard application features.
-
- \image mainwindow-demo.png
-*/
diff --git a/doc/src/examples/mdi.qdoc b/doc/src/examples/mdi.qdoc
deleted file mode 100644
index e8b1b5c9ef..0000000000
--- a/doc/src/examples/mdi.qdoc
+++ /dev/null
@@ -1,37 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/mdi
- \title MDI Example
-
- The MDI example shows how to implement a Multiple Document Interface using Qt's
- QMdiArea class.
-
- \image mdi-example.png
-
-*/
diff --git a/doc/src/examples/menus.qdoc b/doc/src/examples/menus.qdoc
deleted file mode 100644
index 575a1f0219..0000000000
--- a/doc/src/examples/menus.qdoc
+++ /dev/null
@@ -1,218 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/menus
- \title Menus Example
-
- The Menus example demonstrates how menus can be used in a main
- window application.
-
- A menu widget can be either a pull-down menu in a menu bar or a
- standalone context menu. Pull-down menus are shown by the menu bar
- when the user clicks on the respective item or presses the
- specified shortcut key. Context menus are usually invoked by some
- special keyboard key or by right-clicking.
-
- \image menus-example.png
-
- A menu consists of a list of \e action items. In applications,
- many common commands can be invoked via menus, toolbar buttons as
- well as keyboard shortcuts. Since the user expects the commands to
- be performed in the same way, regardless of the user interface
- used, it is useful to represent each command as an action.
-
- The Menus example consists of one single class, \c MainWindow, derived
- from the QMainWindow class. When choosing one of the
- action items in our application, it will display the item's path
- in its central widget.
-
- \section1 MainWindow Class Definition
-
- QMainWindow provides a main application window, with a menu bar,
- tool bars, dock widgets and a status bar around a large central
- widget.
-
- \snippet examples/mainwindows/menus/mainwindow.h 0
-
- In this example, we will see how to implement pull-down menus as
- well as a context menu. In order to implement a custom context
- menu we must reimplement QWidget's \l
- {QWidget::}{contextMenuEvent()} function to receive the context
- menu events for our main window.
-
- \snippet examples/mainwindows/menus/mainwindow.h 1
-
- We must also implement a collection of private slots to respond to
- the user activating any of our menu entries. Note that these
- slots are left out of this documentation since they are trivial,
- i.e., most of them are only displaying the action's path in the
- main window's central widget.
-
- \snippet examples/mainwindows/menus/mainwindow.h 2
-
- We have chosen to simplify the constructor by implementing two
- private convenience functions to create the various actions, to
- add them to menus and to insert the menus into our main window's
- menu bar.
-
- \snippet examples/mainwindows/menus/mainwindow.h 3
-
- Finally, we declare the various menus and actions as well as a
- simple information label in the application wide scope.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus while the QAction class
- provides an abstract user interface action that can be inserted
- into widgets.
-
- In some situations it is useful to group actions together, e.g.,
- we have a \uicontrol {Left Align} action, a \uicontrol {Right Align} action, a
- \uicontrol {Justify} action, and a \uicontrol {Center} action, and we want
- only one of these actions to be active at any one time. One simple
- way of achieving this is to group the actions together in an
- action group using the QActionGroup class.
-
- \section1 MainWindow Class Implementation
-
- In the constructor, we start off by creating a regular QWidget and
- make it our main window's central widget. Note that the main
- window takes ownership of the widget pointer and deletes it at the
- appropriate time.
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 0
- \codeline
- \snippet examples/mainwindows/menus/mainwindow.cpp 1
-
- Then we create the information label as well as a top and bottom
- filler that we add to a layout which we install on the central
- widget. QMainWindow objects come with their own customized layout
- and setting a layout on a the actual main window, or creating a
- layout with a main window as a parent, is considered an error. You
- should always set your own layout on the central widget instead.
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 2
-
- To create the actions and menus we call our two convenience
- functions: \c createActions() and \c createMenus(). We will get
- back to these shortly.
-
- QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function
- returns the status bar for the main window (if the status bar does
- not exist, this function will create and return an empty status
- bar). We initialize the status bar and window title, resize the
- window to an appropriate size as well as ensure that the main
- window cannot be resized to a smaller size than the given
- one.
-
- Now, let's take a closer look at the \c createActions() convenience
- function that creates the various actions:
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 4
- \dots
-
- A QAction object may contain an icon, a text, a shortcut, a status
- tip, a "What's This?" text, and a tooltip. Most of these can be
- set in the constructor, but they can also be set independently
- using the provided convenience functions.
-
- In the \c createActions() function, we first create a \c newAct
- action. We make \uicontrol Ctrl+N its shortcut using the
- QAction::setShortcut() function, and we set its status tip using the
- QAction::setStatusTip() function (the status tip is displayed on all
- status bars provided by the action's top-level parent widget). We
- also connect its \l {QAction::}{triggered()} signal to the \c
- newFile() slot.
-
- The rest of the actions are created in a similar manner. Please
- see the source code for details.
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 7
-
-
- Once we have created the \uicontrol {Left Align}, \uicontrol {Right Align},
- \uicontrol {Justify}, and a \uicontrol {Center} actions, we can also create
- the previously mentioned action group.
-
- Each action is added to the group using QActionGroup's \l
- {QActionGroup::}{addAction()} function. Note that an action also
- can be added to a group by creating it with the group as its
- parent. Since an action group is exclusive by default, only one of
- the actions in the group is checked at any one time (this can be
- altered using the QActionGroup::setExclusive() function).
-
- When all the actions are created, we use the \c createMenus()
- function to add the actions to the menus and to insert the menus
- into the menu bar:
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 8
-
- QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a
- new QMenu with the given title, to the menu bar (note that the
- menu bar takes ownership of the menu). We use QWidget's \l
- {QWidget::addAction()}{addAction()} function to add each action to
- the corresponding menu.
-
- Alternatively, the QMenu class provides several \l
- {QMenu::addAction()}{addAction()} convenience functions that create
- and add new actions from given texts and/or icons. You can also
- provide a member that will automatically connect to the new
- action's \l {QAction::triggered()}{triggered()} signal, and a
- shortcut represented by a QKeySequence instance.
-
- The QMenu::addSeparator() function creates and returns a new
- separator action, i.e. an action for which QAction::isSeparator()
- returns true, and adds the new action to the menu's list of
- actions.
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 12
-
- Note the \uicontrol Format menu. First of all, it is added as a submenu
- to the \uicontrol Edit Menu using QMenu's \l
- {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the
- alignment actions: In the \c createActions() function we added the
- \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct
- actions to an action group. Nevertheless, we must add each action
- to the menu separately while the action group does its magic
- behind the scene.
-
- \snippet examples/mainwindows/menus/mainwindow.cpp 3
-
- To provide a custom context menu, we must reimplement QWidget's \l
- {QWidget::}{contextMenuEvent()} function to receive the widget's
- context menu events (note that the default implementation simply
- ignores these events).
-
- Whenever we receive such an event, we create a menu containing the
- \uicontrol Cut, \uicontrol Copy and \uicontrol Paste actions. Context menus can be
- executed either asynchronously using the \l {QMenu::}{popup()}
- function or synchronously using the \l {QMenu::}{exec()}
- function. In this example, we have chosen to show the menu using
- its \l {QMenu::}{exec()} function. By passing the event's position
- as argument we ensure that the context menu appears at the
- expected position.
-*/
diff --git a/doc/src/examples/moveblocks.qdoc b/doc/src/examples/moveblocks.qdoc
deleted file mode 100644
index 38551abd28..0000000000
--- a/doc/src/examples/moveblocks.qdoc
+++ /dev/null
@@ -1,214 +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$
-**
-****************************************************************************/
-
-/*!
- \example animation/moveblocks
- \title Move Blocks Example
-
- The Move Blocks example shows how to animate items in a
- QGraphicsScene using a QStateMachine with a custom transition.
-
- \image moveblocks-example.png
-
- The example animates the blue blocks that you can see in the image
- above. The animation moves the blocks between four preset positions.
-
- The example consists of the following classes:
-
- \list
- \li \c StateSwitcher inherits QState and can add
- \c {StateSwitchTransition}s to other states.
- When entered, it will randomly transition to one of these
- states.
- \li \c StateSwitchTransition is a custom transition that
- triggers on \c{StateSwitchEvent}s.
- \li \c StateSwitchEvent is a QEvent that triggers \c{StateSwitchTransition}s.
- \li \c QGraphicsRectWidget is a QGraphicsWidget that simply
- paints its background in a solid \l{Qt::}{blue} color.
- \endlist
-
- The blocks are instances of \c QGraphicsRectWidget and are
- animated in a QGraphicsScene. We do this by building a state
- graph, which we insert animations into. The graph is then executed
- in a QStateMachine. All this is done in \c main().
- Let's look at the \c main() function first.
-
- \section1 The \c main() Function
-
- After QApplication has been initialized, we set up the
- QGraphicsScene with its \c{QGraphicsRectWidget}s.
-
- \snippet examples/animation/moveblocks/main.cpp 1
-
- After adding the scene to a QGraphicsView, it is time to build the
- state graph. Let's first look at a statechart of what we are
- trying to build.
-
- \image move-blocks-chart.png
-
- Note that the \c group has seven sub states, but we have only
- included three of them in the diagram. The code that builds this
- graph will be examined line-by-line, and will show how the graph
- works. First off, we construct the \c group state:
-
- \snippet examples/animation/moveblocks/main.cpp 2
-
- The timer is used to add a delay between each time the blocks are
- moved. The timer is started when \c group is entered. As we will
- see later, \c group has a transition back to the \c StateSwitcher
- when the timer times out. \c group is the initial state in the
- machine, so an animation will be scheduled when the example is
- started.
-
- \snippet examples/animation/moveblocks/main.cpp 3
- \dots
- \snippet examples/animation/moveblocks/main.cpp 4
-
- \c createGeometryState() returns a QState that will set the
- geometry of our items upon entry. It also assigns \c group as the
- parent of this state.
-
- A QPropertyAnimation inserted into a transition will use the
- values assigned to a QState (with QState::assignProperty()), i.e.,
- the animation will interpolate between the current values of the
- properties and the values in the target state. We add animated
- transitions to the state graph later.
-
- \snippet examples/animation/moveblocks/main.cpp 5
-
- We move the items in parallel. Each item is added to \c
- animationGroup, which is the animation that is inserted into the
- transitions.
-
- \snippet examples/animation/moveblocks/main.cpp 6
-
- The sequential animation group, \c subGroup, helps us insert a
- delay between the animation of each item.
-
- \snippet examples/animation/moveblocks/main.cpp 7
- \dots
- \snippet examples/animation/moveblocks/main.cpp 8
-
- A StateSwitchTransition is added to the state switcher
- in \c StateSwitcher::addState(). We also add the animation in this
- function. Since QPropertyAnimation uses the values from the
- states, we can insert the same QPropertyAnimation instance in all
- \c {StateSwitchTransition}s.
-
- As mentioned previously, we add a transition to the state switcher
- that triggers when the timer times out.
-
- \snippet examples/animation/moveblocks/main.cpp 9
-
- Finally, we can create the state machine, add our initial state,
- and start execution of the state graph.
-
- \section2 The \c createGeometryState() Function
-
- In \c createGeometryState(), we set up the geometry for each
- graphics item.
-
- \snippet examples/animation/moveblocks/main.cpp 13
-
- As mentioned before, QAbstractTransition will set up an animation
- added with \l{QAbstractTransition::}{addAnimation()} using
- property values set with \l{QState::}{assignProperty()}.
-
- \section1 The StateSwitcher Class
-
- \c StateSwitcher has state switch transitions to each \l{QState}s
- we created with \c createGeometryState(). Its job is to transition
- to one of these states at random when it is entered.
-
- All functions in \c StateSwitcher are inlined. We'll step through
- its definition.
-
- \snippet examples/animation/moveblocks/main.cpp 10
-
- \c StateSwitcher is a state designed for a particular purpose and
- will always be a top-level state. We use \c m_stateCount to keep
- track of how many states we are managing, and \c m_lastIndex to
- remember which state was the last state to which we transitioned.
-
- \snippet examples/animation/moveblocks/main.cpp 11
-
- We select the next state we are going to transition to, and post a
- \c StateSwitchEvent, which we know will trigger the \c
- StateSwitchTransition to the selected state.
-
- \snippet examples/animation/moveblocks/main.cpp 12
-
- This is where the magic happens. We assign a number to each state
- added. This number is given to both a StateSwitchTransition and to
- StateSwitchEvents. As we have seen, state switch events will
- trigger a transition with the same number.
-
- \section1 The StateSwitchTransition Class
-
- \c StateSwitchTransition inherits QAbstractTransition and triggers
- on \c{StateSwitchEvent}s. It contains only inline functions, so
- let's take a look at its \l{QAbstractTransition::}{eventTest()}
- function, which is the only function that we define..
-
- \snippet examples/animation/moveblocks/main.cpp 14
-
- \c eventTest is called by QStateMachine when it checks whether a
- transition should be triggered--a return value of true means that
- it will. We simply check if our assigned number is equal to the
- event's number (in which case we fire away).
-
- \section1 The StateSwitchEvent Class
-
- \c StateSwitchEvent inherits QEvent, and holds a number that has
- been assigned to a state and state switch transition by
- \c StateSwitcher. We have already seen how it is used to trigger
- \c{StateSwitchTransition}s in \c StateSwitcher.
-
- \snippet examples/animation/moveblocks/main.cpp 15
-
- We only have inlined functions in this class, so a look at its
- definition will do.
-
- \section1 The QGraphicsRectWidget Class
-
- QGraphicsRectWidget inherits QGraphicsWidget and simply paints its
- \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()},
- which is the only function we define. Here is the
- QGraphicsRectWidget class definition:
-
- \snippet examples/animation/moveblocks/main.cpp 16
-
- \section1 Moving On
-
- The technique shown in this example works equally well for all
- \l{QPropertyAnimation}s. As long as the value to be animated is a
- Qt property, you can insert an animation of it into a state graph.
-
- QState::addAnimation() takes a QAbstractAnimation, so any type
- of animation can be inserted into the graph.
-*/
-
diff --git a/doc/src/examples/movie.qdoc b/doc/src/examples/movie.qdoc
deleted file mode 100644
index 7573d796c3..0000000000
--- a/doc/src/examples/movie.qdoc
+++ /dev/null
@@ -1,39 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/movie
- \title Movie Example
-
- The Movie example demonstrates how to use QMovie and QLabel to
- display animations. Now that Qt comes with the \l{Phonon multimedia
- framework} {Phonon multimedia framework}, QMovie is mostly
- useful if one wants to play a simple animation without the added
- complexity of a multimedia framework to install and deploy.
-
- \image movie-example.png
-*/
diff --git a/doc/src/examples/orderform.qdoc b/doc/src/examples/orderform.qdoc
deleted file mode 100644
index c9ef75640f..0000000000
--- a/doc/src/examples/orderform.qdoc
+++ /dev/null
@@ -1,364 +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$
-**
-****************************************************************************/
-
-/*!
- \example richtext/orderform
- \title Order Form Example
-
- The Order Form example shows how to generate rich text documents by
- combining a simple template with data input by the user in a dialog. Data
- is extracted from a \c DetailsDialog object and displayed on a QTextEdit
- with a QTextCursor, using various formats. Each form generated is added
- to a QTabWidget for easy access.
-
- \image orderform-example.png
-
- \section1 DetailsDialog Definition
-
- The \c DetailsDialog class is a subclass of QDialog, implementing a slot
- \c verify() to allow contents of the \c DetailsDialog to be verified later.
- This is further explained in \c DetailsDialog Implementation.
-
- \snippet examples/richtext/orderform/detailsdialog.h 0
-
- The constructor of \c DetailsDialog accepts parameters \a title and
- \a parent. The class defines four \e{getter} functions: \c orderItems(),
- \c senderName(), \c senderAddress(), and \c sendOffers() to allow data
- to be accessed externally.
-
- The class definition includes input widgets for the required
- fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a
- QDialogButtonBox are defined; the former to provide the user with the
- option to receive information on products and offers, and the latter
- to ensure that buttons used are arranged according to the user's native
- platform. In addition, a QTableWidget, \c itemsTable, is used to hold
- order details.
-
- The screenshot below shows the \c DetailsDialog we intend to create.
-
- \image orderform-example-detailsdialog.png
-
- \section1 DetailsDialog Implementation
-
- The constructor of \c DetailsDialog instantiates the earlier defined fields
- and their respective labels. The label for \c offersCheckBox is set and the
- \c setupItemsTable() function is invoked to setup and populate
- \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated
- with \uicontrol OK and \uicontrol Cancel buttons. This \c buttonBox's \c accepted() and
- \c rejected() signals are connected to the \c verify() and \c reject()
- slots in \c DetailsDialog.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 0
-
- A QGridLayout is used to place all the objects on the \c DetailsDialog.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 1
-
- The \c setupItemsTable() function instantiates the QTableWidget object,
- \c itemsTable, and sets the number of rows based on the QStringList
- object, \c items, which holds the type of items ordered. The number of
- columns is set to 2, providing a "name" and "quantity" layout. A \c for
- loop is used to populate the \c itemsTable and the \c name item's flag
- is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration
- purposes, the \c quantity item is set to a 1 and all items in the
- \c itemsTable have this value for quantity; but this can be modified by
- editing the contents of the cells at run time.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 2
-
- The \c orderItems() function extracts data from the \c itemsTable and
- returns it in the form of a QList<QPair<QString,int>> where each QPair
- corresponds to an item and the quantity ordered.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 3
-
- The \c senderName() function is used to return the value of the QLineEdit
- used to store the name field for the order form.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 4
-
- The \c senderAddress() function is used to return the value of the
- QTextEdit containing the address for the order form.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 5
-
- The \c sendOffers() function is used to return a \c true or \c false
- value that is used to determine if the customer in the order form
- wishes to receive more information on the company's offers and promotions.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 6
-
- The \c verify() function is an additionally implemented slot used to
- verify the details entered by the user into the \c DetailsDialog. If
- the details entered are incomplete, a QMessageBox is displayed
- providing the user the option to discard the \c DetailsDialog. Otherwise,
- the details are accepted and the \c accept() function is invoked.
-
- \snippet examples/richtext/orderform/detailsdialog.cpp 7
-
- \section1 MainWindow Definition
-
- The \c MainWindow class is a subclass of QMainWindow, implementing two
- slots - \c openDialog() and \c printFile(). It also contains a private
- instance of QTabWidget, \c letters.
-
- \snippet examples/richtext/orderform/mainwindow.h 0
-
- \section1 MainWindow Implementation
-
- The \c MainWindow constructor sets up the \c fileMenu and the required
- actions, \c newAction and \c printAction. These actions' \c triggered()
- signals are connected to the additionally implemented openDialog() slot
- and the default close() slot. The QTabWidget, \c letters, is
- instantiated and set as the window's central widget.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 0
-
- The \c createLetter() function creates a new QTabWidget with a QTextEdit,
- \c editor, as the parent. This function accepts four parameters that
- correspond to we obtained through \c DetailsDialog, in order to "fill"
- the \c editor.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 1
-
- We then obtain the cursor for the \c editor using QTextEdit::textCursor().
- The \c cursor is then moved to the start of the document using
- QTextCursor::Start.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 2
-
- Recall the structure of a \l{Rich Text Document Structure}
- {Rich Text Document}, where sequences of frames and
- tables are always separated by text blocks, some of which may contain no
- information.
-
- In the case of the Order Form Example, the document structure for this portion
- is described by the table below:
-
- \table
- \row
- \li {1, 8} frame with \e{referenceFrameFormat}
- \row
- \li block \li \c{A company}
- \row
- \li block
- \row
- \li block \li \c{321 City Street}
- \row
- \li block
- \row
- \li block \li \c{Industry Park}
- \row
- \li block
- \row
- \li block \li \c{Another country}
- \endtable
-
- This is accomplished with the following code:
-
- \snippet examples/richtext/orderform/mainwindow.cpp 3
-
- Note that \c topFrame is the \c {editor}'s top-level frame and is not shown
- in the document structure.
-
- We then set the \c{cursor}'s position back to its last position in
- \c topFrame and fill in the customer's name (provided by the constructor)
- and address - using a \c foreach loop to traverse the QString, \c address.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 4
-
- The \c cursor is now back in \c topFrame and the document structure for
- the above portion of code is:
-
- \table
- \row
- \li block \li \c{Donald}
- \row
- \li block \li \c{47338 Park Avenue}
- \row
- \li block \li \c{Big City}
- \endtable
-
- For spacing purposes, we invoke \l{QTextCursor::insertBlock()}
- {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is
- obtained and displayed. We use \l{QTextFrameFormat::setWidth()}
- {setWidth()} to increase the width of \c bodyFrameFormat and we insert
- a new frame with that width.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 5
-
- The following code inserts standard text into the order form.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 6
- \snippet examples/richtext/orderform/mainwindow.cpp 7
-
- This part of the document structure now contains the date, a frame with
- \c bodyFrameFormat, as well as the standard text.
-
- \table
- \row
- \li block
- \row
- \li block
- \row
- \li block \li \c{Date: 25 May 2007}
- \row
- \li block
- \row
- \li {1, 4} frame with \e{bodyFrameFormat}
- \row
- \li block \li \c{I would like to place an order for the following items:}
- \row
- \li block
- \row
- \li block
- \endtable
-
- A QTextTableFormat object, \c orderTableFormat, is used to hold the type
- of item and the quantity ordered.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 8
-
- We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the
- \c orderTable.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 9
-
- Then, we iterate through the QList of QPair objects to populate
- \c orderTable.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 10
-
- The resulting document structure for this section is:
-
- \table
- \row
- \li {1, 11} \c{orderTable} with \e{orderTableFormat}
- \row
- \li block \li \c{Product}
- \row
- \li block \li \c{Quantity}
- \row
- \li block \li \c{T-shirt}
- \row
- \li block \li \c{4}
- \row
- \li block \li \c{Badge}
- \row
- \li block \li \c{3}
- \row
- \li block \li \c{Reference book}
- \row
- \li block \li \c{2}
- \row
- \li block \li \c{Coffee cup}
- \row
- \li block \li \c{5}
- \endtable
-
- The \c cursor is then moved back to \c{topFrame}'s
- \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text
- is inserted.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 11
- \snippet examples/richtext/orderform/mainwindow.cpp 12
-
- Another QTextTable is inserted, to display the customer's
- preference regarding offers.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 13
-
- The document structure for this portion is:
-
- \table
- \row
- \li block
- \row
- \li block\li \c{Please update my...}
- \row
- \li {1, 5} block
- \row
- \li {1, 4} \c{offersTable}
- \row
- \li block \li \c{I want to receive...}
- \row
- \li block \li \c{I do not want to receive...}
- \row
- \li block \li \c{X}
- \endtable
-
- The \c cursor is moved to insert "Sincerely" along with the customer's
- name. More blocks are inserted for spacing purposes. The \c printAction
- is enabled to indicate that an order form can now be printed.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 14
-
- The bottom portion of the document structure is:
-
- \table
- \row
- \li block
- \row
- \li {1, 5} block\li \c{Sincerely,}
- \row
- \li block
- \row
- \li block
- \row
- \li block
- \row
- \li block \li \c{Donald}
- \endtable
-
- The \c createSample() function is used for illustration purposes, to create
- a sample order form.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 15
-
- The \c openDialog() function opens a \c DetailsDialog object. If the
- details in \c dialog are accepted, the \c createLetter() function is
- invoked using the parameters extracted from \c dialog.
-
- \snippet examples/richtext/orderform/mainwindow.cpp 16
-
- In order to print out the order form, a \c printFile() function is
- included, as shown below:
-
- \snippet examples/richtext/orderform/mainwindow.cpp 17
-
- This function also allows the user to print a selected area with
- QTextCursor::hasSelection(), instead of printing the entire document.
-
- \section1 \c main() Function
-
- The \c main() function instantiates \c MainWindow and sets its size to
- 640x480 pixels before invoking the \c show() function and
- \c createSample() function.
-
- \snippet examples/richtext/orderform/main.cpp 0
-
-*/
diff --git a/doc/src/examples/padnavigator.qdoc b/doc/src/examples/padnavigator.qdoc
deleted file mode 100644
index 840c16b0c9..0000000000
--- a/doc/src/examples/padnavigator.qdoc
+++ /dev/null
@@ -1,583 +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$
-**
-****************************************************************************/
-
-/*!
- \example graphicsview/padnavigator
- \title Pad Navigator Example
-
- The Pad Navigator Example shows how you can use Graphics View together with
- embedded widgets and Qt's \l{State Machine Framework} to create a simple
- but useful, dynamic, animated user interface.
-
- \image padnavigator-example.png
-
- The interface consists of a flippable, rotating pad with icons that can be
- selected using the arrow keys on your keyboard or keypad. Pressing enter
- will flip the pad around and reveal its back side, which has a form
- embedded into a QGraphicsProxyWidget. You can interact with the form, and
- press the enter key to flip back to the front side of the pad at any time.
-
- Graphics View provides the QGraphicsScene class for managing and
- interacting with a large number of custom-made 2D graphical items derived
- from the QGraphicsItem class, and a QGraphicsView widget for visualizing
- the items, with support for zooming and rotation.
-
- This example consists of a \c RoundRectItem class, a \c FlippablePad class,
- a \c PadNavigator class, a \c SplashItem class, and a \c main() function.
-
- \section1 RoundRectItem Class Definition
-
- The \c RoundRectItem class is used by itself to display the icons on the
- pad, and as a base class for \c FlippablePad, the class for the pad itself.
- The role of the class is to paint a round rectangle of a specified size and
- gradient color, and optionally to paint a pixmap icon on top. To support \c
- FlippablePad it also allows filling its contents with a plain window
- background color.
-
- Let's start by reviewing the \c RoundRectItem class declaration.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.h 0
-
- \c RoundRectItem inherits QGraphicsObject, which makes it easy to control
- its properties using QPropertyAnimation. Its constructor takes a rectangle
- to determine its bounds, and a color.
-
- Besides implementing the mandatory \l{QGraphicsItem::paint()}{paint()} and
- \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions,
- it also provides the \c pixmap and \c fill properties.
-
- The \c pixmap property sets an optional pixmap that is drawn on top of the
- round rectangle. The \c fill property will, when true, fill the round
- rectangle contents with a fixed QPalette::Window background color.
- Otherwise the contents are filled using a gradient based on the color
- passed to \c RoundRectItem's constructor.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.h 1
-
- The private data members are:
-
- \list
- \li \c pix: The optional pixmap that is drawn on top of the rectangle.
- \li \c fillRect: Corresponds to the \c fill property.
- \li \c color: The configurable gradient color fill of the rectangle.
- \li \c bounds: The bounds of the rectangle.
- \li \c gradient: A precalculated gradient used to fill the rectangle.
- \endlist
-
- We will now review the \c RoundRectItem implementation. Let's start by
- looking at its constructor:
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 0
-
- The constructor initializes its member variables and forwards the \c parent
- argument to QGraphicsObject's constructor. It then constructs the linear
- gradient that is used in \l{QGraphicsItem::paint()}{paint()} to draw the
- round rectangle's gradient background. The linear gradient's starting point
- is at the top-left corner of the bounds, and the end is at the bottom-left
- corner. The start color is identical to the color passed as an argument,
- and a slightly darker color is chosen for the final stop.
-
- We store this gradient as a member variable to avoid having to recreate the
- gradient every time the item is repainted.
-
- Finally we set the cache mode
- \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}. This mode
- causes the item's rendering to be cached into an off-screen pixmap that
- remains persistent as we move and transform the item. This mode is ideal
- for this example, and works particularly well with OpenGL and OpenGL ES.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 1
-
- The \c pixmap property implementation simple returns the member pixmap, or
- sets it and then calls \l{QGraphicsItem::update()}{update()}.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 2
-
- As the \l{QGraphicsItem::paint()}{paint()} implementation below draws a
- simple drop shadow down and to the right of the item, we return a slightly
- adjusted rectangle from \l{QGraphicsItem::boundingRect()}{boundingRect()}.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 3
-
- The \l{QGraphicsItem::paint()}{paint()} implementation starts by rendering
- a semi transparent black round rectangle drop shadow, two units down and to
- the right of the main item.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 4
-
- We then draw the "foreground" round rectangle itself. The fill depends on
- the \c fill property; if true, we will with a plain QPalette::Window color.
- We get the current brush from QApplication::palette(). We assign a single
- unit wide pen for the stroke, assign the brush, and then draw the
- rectangle.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 5
-
- If a pixmap has been assigned to the \e pixmap property, we draw this
- pixmap in the center of the rectangle item. The pixmaps are scaled to match
- the size of the icons; in arguably a better approach would have been to
- store the icons with the right size in the first places.
-
- \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 6
-
- Finally, for completeness we include the \c fill property implementation.
- It returns the \c fill member variable's value, and when assigned to, it
- calls \l{QGraphicsItem::update()}{update()}.
-
- As mentioned already, \c RoundRectItem is the base class for \c
- FlippablePad, which is the class representing the tilting pad itself. We
- will proceed to reviewing \c FlippablePad.
-
- \section1 FlippablePad Class Definition
-
- \c FlippablePad is, in addition to its inherited \c RoundRectItem
- responsibilities, responsible for creating and managing a grid of icons.
-
- \snippet examples/graphicsview/padnavigator/flippablepad.h 0
-
- Its declaration is very simple: It inherits \c RoundRectItem and does not
- need any special polymorphic behavior. It's suitable to declare its own
- constructor, and a getter-function that allows \c PadNavigator to access
- the icons in the grid by (row, column).
-
- The example has no "real" behavior or logic of any kind, and because of
- that, the icons do not need to provide any \e behavior or special
- interactions management. In a real application, however, it would be
- natural for the \c FlippablePad and its icons to handle more of the
- navigation logic. In this example, we have chosen to leave this to
- the \c PadNavigator class, which we will get back to below.
-
- We will now review the \c FlippablePad implementation. This implementation
- starts with two helper functions: \c boundsFromSize() and \c
- posForLocation():
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 0
-
- \c boundsForSize() takes a QSize argument, and returns the bounding
- rectangle of the flippable pad item. The QSize determines how many rows and
- columns the icon grid should have. Each icon is given 150x150 units of
- space, and this determines the bounds.
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 1
-
- \c posForLocation() returns the position of an icon given its row and
- column position. Like \c boundsForSize(), the function assumes each icon is
- given 150x150 units of space, and that all icons are centered around the
- flippable pad item's origin (0, 0).
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 2
-
- The \c FlippablePad constructor passes suitable bounds (using \c
- boundsForSize()) and specific color to \c RoundRectItem's constructor.
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 3
-
- It then loads pixmaps from compiled-in resources to use for its icons.
- QDirIterator is very useful in this context, as it allows us to fetch all
- resource "*.png" files inside the \c :/images directory without explicitly
- naming the files.
-
- We also make sure not to load more pixmaps than we need.
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 4
-
- Now that we have the pixmaps, we can create icons, position then and assign
- pixmaps. We start by finding a suitable size and color for the icons, and
- initializing a convenient grid structure for storing the icons. This \c
- iconGrid is also used later to find the icon for a specific (column, row)
- location.
-
- For each row and column in our grid, we proceed to constructing each icon
- as an instance of \c RoundRectItem. The item is placed by using the \c
- posForLocation() helper function. To make room for the slip-behind
- selection item, we give each icon a \l{QGraphicsItem::zValue()}{Z-value} of
- 1. The pixmaps are distributed to the icons in round-robin fasion.
-
- Again, this approach is only suitable for example purposes. In a real-life
- application where each icon represents a specific action, it would be more
- natural to assign the pixmaps directly, or that the icons themselves
- provide suitable pixmaps.
-
- \snippet examples/graphicsview/padnavigator/flippablepad.cpp 5
-
- Finally, the \c iconAt() function returns a pointer to the icon at a
- specific row and column. It makes a somewhat bold assumption that the input
- is valid, which is fair because the \c PadNavigator class only calls this
- function with correct input.
-
- We will now review the \c SplashItem class.
-
- \section1 SplashItem Class Definition
-
- The \c SplashItem class represents the "splash window", a semitransparent
- white overlay with text that appears immediately after the application has
- started, and disappears after pressing any key. The animation is controlled
- by \c PadNavigator; this class is very simple by itself.
-
- \snippet examples/graphicsview/padnavigator/splashitem.h 0
-
- The class declaration shows that \c SplashItem inherits QGraphicsObject to
- allow it to be controlled by QPropertyAnimation. It reimplements the
- mandatory \l{QGraphicsItem::paint()}{paint()} and
- \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions,
- and keeps a \c text member variable which will contain the information text
- displayed on this splash item.
-
- Let's look at its implementation.
-
- \snippet examples/graphicsview/padnavigator/splashitem.cpp 0
-
- The constructor forwards to QGraphicsObject as expected, assigns a text
- message to the \c text member variable, and enables
- \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}. This cache
- mode is suitable because the splash item only moves and is never
- transformed, and because it contains text, it's important that it has a
- pixel perfect visual appearance (in constrast to
- \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}, where the
- visual appearance is not as good).
-
- We use caching to avoid having to relayout and rerender the text for each
- frame. An alterative approach would be to use the new QStaticText class.
-
- \snippet examples/graphicsview/padnavigator/splashitem.cpp 1
-
- \c SplashItem's bounding rectangle is fixed at (400x175).
-
- \snippet examples/graphicsview/padnavigator/splashitem.cpp 2
-
- The \l{QGraphicsItem::paint()}{paint()} implementation draws a clipped
- round rectangle with a thick 2-unit border and a semi-transparent white
- background. It proceeds to finding a suitable text area by adjusting the
- splash item's bounding rectangle with 10 units in each side. The text is
- rendered inside this rectangle, with top-left alignment, and with word
- wrapping enabled.
-
- The main class now remains. We will proceed to reviewing \c PadNavigator.
-
- \section1 PadNavigator Class Definition
-
- \c PadNavigator represents the main window of our Pad Navigator Example
- application. It creates and controls a somewhat complex state machine, and
- several animations. Its class declaration is very simple:
-
- \snippet examples/graphicsview/padnavigator/padnavigator.h 0
-
- It inherits QGraphicsView and reimplements only one function:
- \l{QGraphicsView::resizeEvent()}{resizeEvent()}, to ensure the scene is
- scaled to fit inside the view when resizing the main window.
-
- The \c PadNavigator constructor takes a QSize argument that determines the
- number or rows and columns in the grid.
-
- It also keeps a private member instance, \c form, which is the generated
- code for the pad's back side item's QGraphicsProxyWidget-embedded form.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 0
-
- \c PadNavigator's constructor is a bit long. In short, its job is to create
- all items, including the \c FlippablePad, the \c SplashItem and the
- QGraphicsProxyWidget \c backItem, and then to set up all animations, states
- and transitions that control the behavior of the application.
-
- It starts out simple, by forwarding to QGraphicsView's constructor.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 1
-
- The first item to be created is \c SplashItem. This is going to be a top-level
- item in the scene, next to \c FlippablePad, and stacked on top of it, so we
- assign it a \l{QGraphicsItem::zValue()}{Z-value} of 1.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 2
-
- Now we construct the \c FlippablePad item, passing its column-row count to
- its constructor.
-
- The pad is controlled by three transformations, and we create one
- QGraphicsRotation object for each of these.
-
- \list
- \li \c flipRotation: Rotates the grid around its Qt::YAxis. This rotation is
- animated from 0 to 180, and eventually back, when enter is pressed on the
- keyboard, flipping the pad around.
- \li \c xRotation: Rotates the grid around its Qt::XAxis. This is used to
- tilt the pad vertically corresponding to which item is currently selected.
- This way, the selected item is always kept in front.
- \li \c yRotation: Rotates the grid around its Qt::YAxis. This is used to
- tilt the pad horizontally corresponding to which item is selected. This
- way, the selected item is always kept in front.
- \endlist
-
- The combination of all three rotations is assigned via
- QGraphicsItem::setTransformations().
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 3
-
- Now we construct the QGraphicsProxyWidget-embedded \c backItem. The proxy
- widget is created as a child of the pad. We create a new QWidget and
- populate it with the \c form member. To ensure the \c hostName line edit is
- the first to receive input focus when this item is shown, we call
- \l{QWidget::setFocus()}{setFocus()} immediately. This will not give the
- widget focus right away; it will only prepare the item to automatically
- receive focus once it is shown.
-
- The QWidget based form is embedded into the proxy widget. The proxy is
- hidden initially; we only want to show it when the pad is rotated at least
- 90 degrees, and we also rotate the proxy itself by 180 degrees. This way we
- give the impression that the proxy widget is "behind" the flipped pad, when
- in fact, it's actually \e{on top of it}.
-
- We enable \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache} to
- ensure the flip animation can run smoothly.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 4
-
- We now create the selection item. This is simply another instance of \c
- RoundRectItem that is slightly larger than the icons on the pad. We create
- it as an immediate child of the \c FlippablePad, so the selection item is a
- sibling to all the icons. By giving it a
- \l{QGraphicsItem::zValue()}{Z-value} of 0.5 we ensure it will slide between
- the pad and its icons.
-
- What follows now is a series of animation initializations.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 5
-
- We begin with the animations that apply to the splash item. The first
- animation, \c smoothSplashMove, ensures that the "y" property of \c splash
- will be animated with a 250-millisecond duration
- \l{QEasingCurve::InQuad}{InQuad} easing function. \c smoothSplashOpacity
- ensures the opacity of \c splash eases in and out in 250 milliseconds.
-
- The values are assigned by \c PadNavigator's state machine, which is
- created later.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 6
-
- These are the animations that control the selection item's movement and the
- \c xRotation and \c yRotation QGraphicsRotation objects that tilt the pad.
- All animations have a duration of 125 milliseconds, and they all use the
- \l{QEasingCurve::InOutQuad}{InOutQuad} easing function.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 7
-
- We now create the animations that control the flip-effect when you press
- the enter key. The main goal is to rotate the pad by 180 degrees or back,
- but we also need to make sure the selection item's tilt rotations are reset
- back to 0 when the pad is flipped, and restored back to their original
- values when flipped back:
-
- \list
- \li \c smoothFlipRotation: Animates the main 180 degree rotation of the pad.
- \li \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating.
- \li \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back.
- \li \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back.
- \li \c flipAnimation: A parallel animation group that ensures all the above animations are run in parallel.
- \endlist
-
- All animations are given a 500 millisecond duration and an
- \l{QEasingCurve::InOutQuad}{InOutQuad} easing function.
-
- It's worth taking a close look at \c smoothFlipScale. This animation's
- start and end values are both 1.0, but at animation step 0.5 the
- animation's value is 0.7. This means that after 50% of the animation's
- duration, or 250 milliseconds, the pad will be scaled down to 0.7x of its
- original size, which gives a great visual effect while flipping.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 8
-
- This section uses a trick to ensure that certain properties are assigned
- precisely when the flip animation passes 50%, or 90 degrees, rotation. In
- short, the pad's icons and selection item are all hidden, the pad's \c fill
- property is enabled, and \c backItem is shown when flipping over. When
- flipping back, the reverse properties are applied.
-
- The way this is achieved is by running a sequential animation in parallel
- to the other animations. This sequence, dubbed \c setVariablesSequence,
- starts with a 250 millisecond pause, and then executes several animations
- with a duration of 0. Each animation will ensure that properties are set
- immediate at this point.
-
- This approach can also be used to call functions or set any other
- properties at a specific time while an animation is running.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 9
-
- We will now create the state machine. The whole \c PadNavigator state
- machinery is controlled by one single state machine that has a
- straight-forward state structure. The state engine itself is created
- as a child of the \c PadNavigator itself. We then create three top level
- states:
-
- \list
- \li \c splashState: The initial state where the splash item is visible.
- \li \c frontState: The base state where the splash is gone and we can see
- the front side of the pad, and navigate the selection item.
- \li \c backState: The flipped state where the \c backItem is visible, and we
- can interact with the QGraphicsProxyWidget-embedded form.
- \endlist
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 10
-
- Each state assigns specific properties to objects on entry. Most
- interesting perhaps is the assignment of the value 0.0 to the pad's \c
- flipRotation angle property when in \c frontState, and 180.0 when in \c
- backState. At the end of this section we register default animations with
- the state engine; these animations will apply to their respective objects
- and properties for any state transition. Otherwise it's common to assign
- animations to specific transitions.
-
- The \c splashState state is set as the initial state. This is required
- before we start the state engine. We proceed with creating some
- transitions.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 11
-
- QEventTransition defines a very flexible transition type. You can use this
- class to trigger a transition based on an object receiving an event of a
- specific type. In this case, we would like to transition from \c
- splashState into \c frontState if \c PadNavigator receives any key press
- event (QEvent::KeyPress).
-
- We register the \c splashItem's animations to this transition to ensure they
- are used to animate the item's movement and opacity.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 12
-
- We use QKeyEventTransition to capture specific key events. In this case, we
- detect that the user presses Qt::Key_Return or Qt::Key_Enter, and use this
- to trigger transitions between \c frontState and backState. We register \c
- flipAnimation, our complex parallel animation group, with these
- transitions.
-
- We continue by defining the states for each of the icons in the grid.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 13
-
- We will use state groups to control transitions between icons. Each icon
- represents a \e substate of \c frontState. We will then define transitions
- between the states by detecting key presses, using QKeyEventTransition.
-
- We start by creating all the substates, and at the same time we create a
- temporary grid structure for the states to make it easier to find which
- states represents icons that are up, down, left and to the right each
- other.
-
- Once the first substate is known, we set this up as the initial substate of
- \c frontState. We will use the (0, 0), or top-left, icon for the initial
- substate. We initialze the selection item's position to be exactly where
- the top-left icon is.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 14
-
- We can now create four transitions for each icon. Each transition ensures
- that we move to the state corresponding to which arrow key has been
- pressed. It's clear from this techinique that we could design any other
- specific transitions to and from each of the sub states depending on these
- and other keys.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 15
-
- Also, for each of the icons, we assign suitable values to the \c xRotation
- and \c yRotation objects' "angle"-properties. If you recall, these
- properties "tilt" the pad corresponding to which item is currently
- selected. We ensure each icon is invisible when the pad is flipped, and
- visible when the pad is not flipped. To ensure the visible property is
- assigned at the right time, we add property-controlling animations to the
- \c setVariableSequence animation defined earlier.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 16
-
- We are now finished with all states, transitions, and animations. We now
- create the scene that will contain all our items. The scene gets a defined
- background pixmap, and we disable item indexing (as most items in this
- scene are animated). We add our \c pad item to the scene, and use its
- bounding rectangle to fixate the scene rectangle. This rectangle is used by
- the view to find a suitable size for the application window.
-
- Then the scene is assigned to the view, or in our case, \c PadNavigator
- itself.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 17
-
- Now that the scene has received its final size, we can position the splash
- item at the very top, find its fade-out position, and add it to the scene.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 18
-
- The view toggles a few necessary properties:
-
- \list
- \li It disables its scroll bars - this application has no use for scroll bars.
- \li It assigns a minimum size. This is necessary to avoid numerical errors
- in our fit-in-view \c resizeEvent() implementation.
- \li It sets \l{QGraphicsView::FullViewportUpdate}{FullViewportUpdate}, to
- ensure QGraphicsView doesn't spend time figuring out precisely what needs
- to be redrawn. This application is very simple - if anything changes,
- everything is updated.
- \li It enables background caching - this makes no performance difference
- with OpenGL, but without OpenGL it avoids unnecessary re-scaling of the
- background pixmap.
- \li It sets render hints that increase rendering quality.
- \li If OpenGL is supported, a QGLWidget viewport is assigned to the view.
- \endlist
-
- Finally, we start the state engine.
-
- \snippet examples/graphicsview/padnavigator/padnavigator.cpp 19
-
- The \l{QGraphicsView::resizeEvent()}{resizeEvent()} implementation calls
- the base implementation, and then calls QGraphicsView::fitInView() to scale
- the scene so that it fits perfectly inside the view.
-
- By resizing the main application window, you can see this effect yourself.
- The scene contents grow when you make the window larger, and shrink when
- you make it smaller, while keeping the aspect ratio intact.
-
- \section1 The main() Function
-
- \snippet examples/graphicsview/padnavigator/main.cpp 0
-
- The \c main function creates the QApplication instance, uses
- Q_INIT_RESOURCE to ensure our compiled-in resources aren't removed by the
- linker, and then creates a 3x3 \c PadNavigator instance and shows it.
-
- Our flippable pad shows up with a suitable splash item once control returns
- to the event loop.
-
- \section1 Performance Notes
-
- The example uses OpenGL if this is available, to achieve optimal
- performance; otherwise perspective tranformations can be quite costly.
-
- Although this example does use QGraphicsProxyWidget to demonstrate
- integration of Qt widget components integrated into Graphics View, using
- QGraphicsProxyWidget comes with a performance penalty, and is therefore not
- recommended for embedded development.
-
- This example uses extensive item caching to avoid rerendering of static
- elements, at the expense of graphics memory.
-*/
diff --git a/doc/src/examples/painterpaths.qdoc b/doc/src/examples/painterpaths.qdoc
deleted file mode 100644
index 1bee28f029..0000000000
--- a/doc/src/examples/painterpaths.qdoc
+++ /dev/null
@@ -1,418 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/painterpaths
- \title Painter Paths Example
-
- The Painter Paths example shows how painter paths can be used to
- build complex shapes for rendering.
-
- \image painterpaths-example.png
-
- The QPainterPath class provides a container for painting
- operations, enabling graphical shapes to be constructed and
- reused.
-
- A painter path is an object composed of a number of graphical
- building blocks (such as rectangles, ellipses, lines, and curves),
- and can be used for filling, outlining, and clipping. The main
- advantage of painter paths over normal drawing operations is that
- complex shapes only need to be created once, but they can be drawn
- many times using only calls to QPainter::drawPath().
-
- The example consists of two classes:
-
- \list
- \li The \c RenderArea class which is a custom widget displaying
- a single painter path.
- \li The \c Window class which is the applications main window
- displaying several \c RenderArea widgets, and allowing the user
- to manipulate the painter paths' filling, pen, color
- and rotation angle.
- \endlist
-
- First we will review the \c Window class, then we will take a look
- at the \c RenderArea class.
-
- \section1 Window Class Definition
-
- The \c Window class inherits QWidget, and is the applications main
- window displaying several \c RenderArea widgets, and allowing the
- user to manipulate the painter paths' filling, pen, color and
- rotation angle.
-
- \snippet examples/painting/painterpaths/window.h 0
-
- We declare three private slots to respond to user input regarding
- filling and color: \c fillRuleChanged(), \c fillGradientChanged()
- and \c penColorChanged().
-
- When the user changes the pen width and the rotation angle, the
- new value is passed directly on to the \c RenderArea widgets using
- the QSpinBox::valueChanged() signal. The reason why we must
- implement slots to update the filling and color, is that QComboBox
- doesn't provide a similar signal passing the new value as
- argument; so we need to retrieve the new value, or values, before
- we can update the \c RenderArea widgets.
-
- \snippet examples/painting/painterpaths/window.h 1
-
- We also declare a couple of private convenience functions: \c
- populateWithColors() populates a given QComboBox with items
- corresponding to the color names Qt knows about, and \c
- currentItemData() returns the current item for a given QComboBox.
-
- \snippet examples/painting/painterpaths/window.h 2
-
- Then we declare the various components of the main window
- widget. We also declare a convenience constant specifying the
- number of \c RenderArea widgets.
-
- \section1 Window Class Implementation
-
- In the implementation of the \c Window class we first declare the
- constant \c Pi with six significant figures:
-
- \snippet examples/painting/painterpaths/window.cpp 0
-
- In the constructor, we then define the various painter paths and
- create corresponding \c RenderArea widgets which will render the
- graphical shapes:
-
- \snippet examples/painting/painterpaths/window.cpp 1
-
- We construct a rectangle with sharp corners using the
- QPainterPath::moveTo() and QPainterPath::lineTo()
- functions.
-
- QPainterPath::moveTo() moves the current point to the point passed
- as argument. A painter path is an object composed of a number of
- graphical building blocks, i.e. subpaths. Moving the current point
- will also start a new subpath (implicitly closing the previously
- current path when the new one is started). The
- QPainterPath::lineTo() function adds a straight line from the
- current point to the given end point. After the line is drawn, the
- current point is updated to be at the end point of the line.
-
- We first move the current point starting a new subpath, and we
- draw three of the rectangle's sides. Then we call the
- QPainterPath::closeSubpath() function which draws a line to the
- beginning of the current subpath. A new subpath is automatically
- begun when the current subpath is closed. The current point of the
- new path is (0, 0). We could also have called
- QPainterPath::lineTo() to draw the last line as well, and then
- explicitly start a new subpath using the QPainterPath::moveTo()
- function.
-
- QPainterPath also provide the QPainterPath::addRect() convenience
- function, which adds a given rectangle to the path as a closed
- subpath. The rectangle is added as a clockwise set of lines. The
- painter path's current position after the rect has been added is
- at the top-left corner of the rectangle.
-
- \snippet examples/painting/painterpaths/window.cpp 2
-
- Then we construct a rectangle with rounded corners. As before, we
- use the QPainterPath::moveTo() and QPainterPath::lineTo()
- functions to draw the rectangle's sides. To create the rounded
- corners we use the QPainterPath::arcTo() function.
-
- QPainterPath::arcTo() creates an arc that occupies the given
- rectangle (specified by a QRect or the rectangle's coordinates),
- beginning at the given start angle and extending the given degrees
- counter-clockwise. Angles are specified in degrees. Clockwise arcs
- can be specified using negative angles. The function connects the
- current point to the starting point of the arc if they are not
- already connected.
-
- \snippet examples/painting/painterpaths/window.cpp 3
-
- We also use the QPainterPath::arcTo() function to construct the
- ellipse path. First we move the current point starting a new
- path. Then we call QPainterPath::arcTo() with starting angle 0.0
- and 360.0 degrees as the last argument, creating an ellipse.
-
- Again, QPainterPath provides a convenience function (
- QPainterPath::addEllipse()) which creates an ellipse within a
- given bounding rectangle and adds it to the painter path. If the
- current subpath is closed, a new subpath is started. The ellipse
- is composed of a clockwise curve, starting and finishing at zero
- degrees (the 3 o'clock position).
-
- \snippet examples/painting/painterpaths/window.cpp 4
-
- When constructing the pie chart path we continue to use a
- combination of the mentioned functions: First we move the current
- point, starting a new subpath. Then we create a line from the
- center of the chart to the arc, and the arc itself. When we close
- the subpath, we implicitly construct the last line back to the
- center of the chart.
-
- \snippet examples/painting/painterpaths/window.cpp 5
-
- Constructing a polygon is equivalent to constructing a rectangle.
-
- QPainterPath also provide the QPainterPath::addPolygon()
- convenience function which adds the given polygon to the path as a
- new subpath. Current position after the polygon has been added is
- the last point in polygon.
-
- \snippet examples/painting/painterpaths/window.cpp 6
-
- Then we create a path consisting of a group of subpaths: First we
- move the current point, and create a circle using the
- QPainterPath::arcTo() function with starting angle 0.0, and 360
- degrees as the last argument, as we did when we created the
- ellipse path. Then we move the current point again, starting a
- new subpath, and construct three sides of a square using the
- QPainterPath::lineTo() function.
-
- Now, when we call the QPainterPath::closeSubpath() function the
- last side is created. Remember that the
- QPainterPath::closeSubpath() function draws a line to the
- beginning of the \e current subpath, i.e the square.
-
- QPainterPath provide a convenience function,
- QPainterPath::addPath() which adds a given path to the path that
- calls the function.
-
- \snippet examples/painting/painterpaths/window.cpp 7
-
- When creating the text path, we first create the font. Then we set
- the font's style strategy which tells the font matching algorithm
- what type of fonts should be used to find an appropriate default
- family. QFont::ForceOutline forces the use of outline fonts.
-
- To construct the text, we use the QPainterPath::addText() function
- which adds the given text to the path as a set of closed subpaths
- created from the supplied font. The subpaths are positioned so
- that the left end of the text's baseline lies at the specified
- point.
-
- \snippet examples/painting/painterpaths/window.cpp 8
-
- To create the Bezier path, we use the QPainterPath::cubicTo()
- function which adds a Bezier curve between the current point and
- the given end point with the given control point. After the curve
- is added, the current point is updated to be at the end point of
- the curve.
-
- In this case we omit to close the subpath so that we only have a
- simple curve. But there is still a logical line from the curve's
- endpoint back to the beginning of the subpath; it becomes visible
- when filling the path as can be seen in the applications main
- window.
-
- \snippet examples/painting/painterpaths/window.cpp 9
-
- The final path that we construct shows that you can use
- QPainterPath to construct rather complex shapes using only the
- previous mentioned QPainterPath::moveTo(), QPainterPath::lineTo()
- and QPainterPath::closeSubpath() functions.
-
- \snippet examples/painting/painterpaths/window.cpp 10
-
- Now that we have created all the painter paths that we need, we
- create a corresponding \c RenderArea widget for each. In the end,
- we make sure that the number of render areas is correct using the
- Q_ASSERT() macro.
-
- \snippet examples/painting/painterpaths/window.cpp 11
-
- Then we create the widgets associated with the painter paths' fill
- rule.
-
- There are two available fill rules in Qt: The Qt::OddEvenFill rule
- determine whether a point is inside the shape by drawing a
- horizontal line from the point to a location outside the shape,
- and count the number of intersections. If the number of
- intersections is an odd number, the point is inside the
- shape. This rule is the default.
-
- The Qt::WindingFill rule determine whether a point is inside the
- shape by drawing a horizontal line from the point to a location
- outside the shape. Then it determines whether the direction of the
- line at each intersection point is up or down. The winding number
- is determined by summing the direction of each intersection. If
- the number is non zero, the point is inside the shape.
-
- The Qt::WindingFill rule can in most cases be considered as the
- intersection of closed shapes.
-
- \snippet examples/painting/painterpaths/window.cpp 12
-
- We also create the other widgets associated with the filling, the
- pen and the rotation angle.
-
- \snippet examples/painting/painterpaths/window.cpp 16
-
- We connect the comboboxes \l {QComboBox::activated()}{activated()}
- signals to the associated slots in the \c Window class, while we
- connect the spin boxes \l
- {QSpinBox::valueChanged()}{valueChanged()} signal directly to the
- \c RenderArea widget's respective slots.
-
- \snippet examples/painting/painterpaths/window.cpp 17
-
- We add the \c RenderArea widgets to a separate layout which we
- then add to the main layout along with the rest of the widgets.
-
- \snippet examples/painting/painterpaths/window.cpp 18
-
- Finally, we initialize the \c RenderArea widgets by calling the \c
- fillRuleChanged(), \c fillGradientChanged() and \c
- penColorChanged() slots, and we set the initial pen width and
- window title.
-
- \snippet examples/painting/painterpaths/window.cpp 19
- \codeline
- \snippet examples/painting/painterpaths/window.cpp 20
- \codeline
- \snippet examples/painting/painterpaths/window.cpp 21
-
- The private slots are implemented to retrieve the new value, or
- values, from the associated comboboxes and update the RenderArea
- widgets.
-
- First we determine the new value, or values, using the private \c
- currentItemData() function and the qvariant_cast() template
- function. Then we call the associated slot for each of the \c
- RenderArea widgets to update the painter paths.
-
- \snippet examples/painting/painterpaths/window.cpp 22
-
- The \c populateWithColors() function populates the given combobox
- with items corresponding to the color names Qt knows about
- provided by the static QColor::colorNames() function.
-
- \snippet examples/painting/painterpaths/window.cpp 23
-
- The \c currentItemData() function simply return the current item
- of the given combobox.
-
- \section1 RenderArea Class Definition
-
- The \c RenderArea class inherits QWidget, and is a custom widget
- displaying a single painter path.
-
- \snippet examples/painting/painterpaths/renderarea.h 0
-
- We declare several public slots updating the \c RenderArea
- widget's associated painter path. In addition we reimplement the
- QWidget::minimumSizeHint() and QWidget::sizeHint() functions to
- give the \c RenderArea widget a reasonable size within our
- application, and we reimplement the QWidget::paintEvent() event
- handler to draw its painter path.
-
- \snippet examples/painting/painterpaths/renderarea.h 1
-
- Each instance of the \c RenderArea class has a QPainterPath, a
- couple of fill colors, a pen width, a pen color and a rotation
- angle.
-
- \section1 RenderArea Class Implementation
-
- The constructor takes a QPainterPath as argument (in addition to
- the optional QWidget parent):
-
- \snippet examples/painting/painterpaths/renderarea.cpp 0
-
- In the constructor we initialize the \c RenderArea widget with the
- QPainterPath parameter as well as initializing the pen width and
- rotation angle. We also set the widgets \l
- {QWidget::backgroundRole()}{background role}; QPalette::Base is
- typically white.
-
- \snippet examples/painting/painterpaths/renderarea.cpp 1
- \codeline
- \snippet examples/painting/painterpaths/renderarea.cpp 2
-
- Then we reimplement the QWidget::minimumSizeHint() and
- QWidget::sizeHint() functions to give the \c RenderArea widget a
- reasonable size within our application.
-
- \snippet examples/painting/painterpaths/renderarea.cpp 3
- \codeline
- \snippet examples/painting/painterpaths/renderarea.cpp 4
- \codeline
- \snippet examples/painting/painterpaths/renderarea.cpp 5
- \codeline
- \snippet examples/painting/painterpaths/renderarea.cpp 6
- \codeline
- \snippet examples/painting/painterpaths/renderarea.cpp 7
-
- The various public slots updates the \c RenderArea widget's
- painter path by setting the associated property and make a call to
- the QWidget::update() function, forcing a repaint of the widget
- with the new rendering preferences.
-
- The QWidget::update() slot does not cause an immediate repaint;
- instead it schedules a paint event for processing when Qt returns
- to the main event loop.
-
- \snippet examples/painting/painterpaths/renderarea.cpp 8
-
- A paint event is a request to repaint all or parts of the
- widget. The paintEvent() function is an event handler that can be
- reimplemented to receive the widget's paint events. We reimplement
- the event handler to render the \c RenderArea widget's painter
- path.
-
- First, we create a QPainter for the \c RenderArea instance, and
- set the painter's render hints. The QPainter::RenderHints are used
- to specify flags to QPainter that may, or may not, be respected by
- any given engine. QPainter::Antialiasing indicates that the engine
- should anti-alias the edges of primitives if possible, i.e. put
- additional pixels around the original ones to smooth the edges.
-
- \snippet examples/painting/painterpaths/renderarea.cpp 9
-
- Then we scale the QPainter's coordinate system to ensure that the
- painter path is rendered in the right size, i.e that it grows with
- the \c RenderArea widget when the application is resized. When we
- constructed the various painter paths, they were all rnedered
- within a square with a 100 pixel width which is equivalent to \c
- RenderArea::sizeHint(). The QPainter::scale() function scales the
- coordinate system by the \c RenderArea widget's \e current width
- and height divided by 100.
-
- Now, when we are sure that the painter path has the right size, we
- can translate the coordinate system to make the painter path
- rotate around the \c RenderArea widget's center. After we have
- performed the rotation, we must remember to translate the
- coordinate system back again.
-
- \snippet examples/painting/painterpaths/renderarea.cpp 10
-
- Then we set the QPainter's pen with the instance's rendering
- preferences. We create a QLinearGradient and set its colors
- corresponding to the \c RenderArea widget's fill colors. Finally,
- we set the QPainter's brush (the gradient is automatically
- converted into a QBrush), and draw the \c RenderArea widget's
- painter path using the QPainter::drawPath() function.
-*/
diff --git a/doc/src/examples/pathstroke.qdoc b/doc/src/examples/pathstroke.qdoc
deleted file mode 100644
index 89a0182934..0000000000
--- a/doc/src/examples/pathstroke.qdoc
+++ /dev/null
@@ -1,47 +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$
-**
-****************************************************************************/
-
-/*!
- \example painting/pathstroke
- \title Path Stroking
-
- In this example we show some of the various types of pens that can be
- used in Qt.
-
- \image pathstroke-demo.png
-
- Qt defines cap styles for how the end points are treated and join
- styles for how path segments are joined together. A standard set of
- predefined dash patterns are also included that can be used with
- QPen.
-
- In addition to the predefined patterns available in
- QPen we also demonstrate direct use of the
- QPainterPathStroker class which can be used to define
- custom dash patterns. You can see this by enabling the
- \e{Custom Pattern} option.
-*/
diff --git a/doc/src/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc
deleted file mode 100644
index 87358684c0..0000000000
--- a/doc/src/examples/pingpong.qdoc
+++ /dev/null
@@ -1,93 +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$
-**
-****************************************************************************/
-
-/*!
- \example statemachine/pingpong
- \title Ping Pong States Example
-
- The Ping Pong States example shows how to use parallel states together
- with custom events and transitions in \l{The State Machine Framework}.
-
- This example implements a statechart where two states communicate by
- posting events to the state machine. The state chart looks as follows:
-
- \image pingpong-example.png
- \omit
- \caption This is a caption
- \endomit
-
- The \c pinger and \c ponger states are parallel states, i.e. they are
- entered simultaneously and will take transitions independently of
- eachother.
-
- The \c pinger state will post the first \c ping event upon entry; the \c
- ponger state will respond by posting a \c pong event; this will cause the
- \c pinger state to post a new \c ping event; and so on.
-
- \snippet examples/statemachine/pingpong/main.cpp 0
-
- Two custom events are defined, \c PingEvent and \c PongEvent.
-
- \snippet examples/statemachine/pingpong/main.cpp 1
-
- The \c Pinger class defines a state that posts a \c PingEvent to the state
- machine when the state is entered.
-
- \snippet examples/statemachine/pingpong/main.cpp 2
-
- The \c PingTransition class defines a transition that is triggered by
- events of type \c PingEvent, and that posts a \c PongEvent (with a delay
- of 500 milliseconds) to the state machine when the transition is
- triggered.
-
- \snippet examples/statemachine/pingpong/main.cpp 3
-
- The \c PongTransition class defines a transition that is triggered by
- events of type \c PongEvent, and that posts a \c PingEvent (with a delay
- of 500 milliseconds) to the state machine when the transition is
- triggered.
-
- \snippet examples/statemachine/pingpong/main.cpp 4
-
- The main() function begins by creating a state machine and a parallel
- state group.
-
- \snippet examples/statemachine/pingpong/main.cpp 5
-
- Next, the \c pinger and \c ponger states are created, with the parallel
- state group as their parent state. Note that the transitions are \e
- targetless. When such a transition is triggered, the source state won't be
- exited and re-entered; only the transition's onTransition() function will
- be called, and the state machine's configuration will remain the same,
- which is precisely what we want in this case.
-
- \snippet examples/statemachine/pingpong/main.cpp 6
-
- Finally, the group is added to the state machine, the machine is started,
- and the application event loop is entered.
-
- */
diff --git a/doc/src/examples/pixelator.qdoc b/doc/src/examples/pixelator.qdoc
deleted file mode 100644
index 35031a09d8..0000000000
--- a/doc/src/examples/pixelator.qdoc
+++ /dev/null
@@ -1,255 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/pixelator
- \title Pixelator Example
-
- The Pixelator example shows how delegates can be used to customize the way that
- items are rendered in standard item views.
-
- \image pixelator-example.png
-
- By default, QTreeView, QTableView, and QListView use a standard item delegate
- to display and edit a set of common data types that are sufficient for many
- applications. However, an application may need to represent items of data in a
- particular way, or provide support for rendering more specialized data types,
- and this often requires the use of a custom delegate.
-
- In this example, we show how to use custom delegates to modify the appearance
- of standard views. To do this, we implement the following components:
-
- \list
- \li A model which represents each pixel in an image as an item of data, where each
- item contains a value for the brightness of the corresponding pixel.
- \li A custom delegate that uses the information supplied by the model to represent
- each pixel as a black circle on a white background, where the radius of the
- circle corresponds to the darkness of the pixel.
- \endlist
-
- This example may be useful for developers who want to implement their own table
- models or custom delegates. The process of creating custom delegates for editing
- item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate}
- example.
-
- \section1 ImageModel Class Definition
-
- The \c ImageModel class is defined as follows:
-
- \snippet examples/itemviews/pixelator/imagemodel.h 0
-
- Since we only require a simple, read-only table model, we only need to implement
- functions to indicate the dimensions of the image and supply data to other
- components.
-
- \section1 ImageModel Class Implementation
-
- The constructor is trivial:
-
- \snippet examples/itemviews/pixelator/imagemodel.cpp 0
-
- The \c setImage() function sets the image that will be used by the model:
-
- \snippet examples/itemviews/pixelator/imagemodel.cpp 1
-
- The QAbstractItemModel::reset() call tells the view(s) that the model
- has changed.
-
- The \c rowCount() and \c columnCount() functions return the height and width of
- the image respectively:
-
- \snippet examples/itemviews/pixelator/imagemodel.cpp 2
- \snippet examples/itemviews/pixelator/imagemodel.cpp 3
-
- Since the image is a simple two-dimensional structure, the \c parent arguments
- to these functions are unused. They both simply return the relevant size from
- the underlying image object.
-
- The \c data() function returns data for the item that corresponds to a given
- model index in a format that is suitable for a particular role:
-
- \snippet examples/itemviews/pixelator/imagemodel.cpp 4
-
- In this implementation, we only check that the model index is valid, and that
- the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function
- returns the grayscale value of the relevant pixel in the image; otherwise, a null
- model index is returned.
-
- This model can be used with QTableView to display the integer brightness values
- for the pixels in the image. However, we will implement a custom delegate to
- display this information in a more artistic way.
-
- The \c headerData() function is also reimplemented:
-
- \snippet examples/itemviews/pixelator/imagemodel.cpp 5
-
- We return (1, 1) as the size hint for a header item. If we
- didn't, the headers would default to a larger size, preventing
- us from displaying really small items (which can be specified
- using the \uicontrol{Pixel size} combobox).
-
- \section1 PixelDelegate Class Definition
-
- The \c PixelDelegate class is defined as follows:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.h 0
-
- This class provides only basic features for a delegate so, unlike the
- \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass
- QAbstractItemDelegate instead of QItemDelegate.
-
- We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and
- \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class.
- However, we also provide a delegate-specific \c setPixelSize() function so
- that we can change the delegate's behavior via the signals and slots mechanism.
-
- \section1 PixelDelegate Class Implementation
-
- The \c PixelDelegate constructor is used to set up a default value for
- the size of each "pixel" that it renders. The base class constructor is
- also called to ensure that the delegate is set up with a parent object,
- if one is supplied:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 0
-
- Each item is rendered by the delegate's
- \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this
- function with a ready-to-use QPainter object, style information that the
- delegate should use to correctly draw the item, and an index to the item in
- the model:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 1
-
- The first task the delegate has to perform is to draw the item's background
- correctly. Usually, selected items appear differently to non-selected items,
- so we begin by testing the state passed in the style option and filling the
- background if necessary.
-
- The radius of each circle is calculated in the following lines of code:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 3
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 4
-
- First, the largest possible radius of the circle is determined by taking the
- smallest dimension of the style option's \c rect attribute.
- Using the model index supplied, we obtain a value for the brightness of the
- relevant pixel in the image. The radius of the circle is calculated by
- scaling the brightness to fit within the item and subtracting it from the
- largest possible radius.
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 5
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 6
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 7
-
- We save the painter's state, turn on antialiasing (to obtain smoother
- curves), and turn off the pen.
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 8
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 9
-
- The foreground of the item (the circle representing a pixel) must be
- rendered using an appropriate brush. For unselected items, we will use a
- solid black brush; selected items are drawn using a predefined brush from
- the style option's palette.
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 10
-
- Finally, we paint the circle within the rectangle specified by the style
- option and we call \l{QPainter::}{restore()} on the painter.
-
- The \c paint() function does not have to be particularly complicated; it is
- only necessary to ensure that the state of the painter when the function
- returns is the same as it was when it was called. This usually
- means that any transformations applied to the painter must be preceded by
- a call to QPainter::save() and followed by a call to QPainter::restore().
-
- The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function
- returns a size for the item based on the predefined pixel size, initially set
- up in the constructor:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 11
-
- The delegate's size is updated whenever the pixel size is changed.
- We provide a custom slot to do this:
-
- \snippet examples/itemviews/pixelator/pixeldelegate.cpp 12
-
- \section1 Using The Custom Delegate
-
- In this example, we use a main window to display a table of data, using the
- custom delegate to render each cell in a particular way. Much of the
- \c MainWindow class performs tasks that are not related to item views. Here,
- we only quote the parts that are relevant. You can look at the rest of the
- implementation by following the links to the code at the top of this
- document.
-
- In the constructor, we set up a table view, turn off its grid, and hide its
- headers:
-
- \snippet examples/itemviews/pixelator/mainwindow.cpp 0
- \dots
- \snippet examples/itemviews/pixelator/mainwindow.cpp 1
-
- This enables the items to be drawn without any gaps between them. Removing
- the headers also prevents the user from adjusting the sizes of individual
- rows and columns.
-
- We also set the minimum section size to 1 on the headers. If we
- didn't, the headers would default to a larger size, preventing
- us from displaying really small items (which can be specified
- using the \uicontrol{Pixel size} combobox).
-
- The custom delegate is constructed with the main window as its parent, so
- that it will be deleted correctly later, and we set it on the table view.
-
- \snippet examples/itemviews/pixelator/mainwindow.cpp 2
-
- Each item in the table view will be rendered by the \c PixelDelegate
- instance.
-
- We construct a spin box to allow the user to change the size of each "pixel"
- drawn by the delegate:
-
- \snippet examples/itemviews/pixelator/mainwindow.cpp 3
-
- This spin box is connected to the custom slot we implemented in the
- \c PixelDelegate class. This ensures that the delegate always draws each
- pixel at the currently specified size:
-
- \snippet examples/itemviews/pixelator/mainwindow.cpp 4
- \dots
- \snippet examples/itemviews/pixelator/mainwindow.cpp 5
-
- We also connect the spin box to a slot in the \c MainWindow class. This
- forces the view to take into account the new size hints for each item;
- these are provided by the delegate in its \c sizeHint() function.
-
- \snippet examples/itemviews/pixelator/mainwindow.cpp 6
-
- We explicitly resize the columns and rows to match the
- \uicontrol{Pixel size} combobox.
-*/
diff --git a/doc/src/examples/recentfiles.qdoc b/doc/src/examples/recentfiles.qdoc
deleted file mode 100644
index e2e876b088..0000000000
--- a/doc/src/examples/recentfiles.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/recentfiles
- \title Recent Files Example
-
- The Recent Files example shows how a standard File menu can be extended to show
- the most recent files loaded by a main window application.
-
- \image recentfiles-example.png
-*/
diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc
deleted file mode 100644
index 44e371c667..0000000000
--- a/doc/src/examples/rogue.qdoc
+++ /dev/null
@@ -1,208 +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$
-**
-****************************************************************************/
-
-/*!
- \example statemachine/rogue
- \title Rogue Example
-
- The Rogue example shows how to use the Qt state machine for event
- handling.
-
- \image rogue-example.png
-
- This example implements a simple text based game. Do you see the
- \c{@} in the screenshot? That's you, the rogue. The \c{#}
- characters are walls, and the dots represent floor. In a real
- game, other ASCII characters would represent all kinds of objects
- and creatures, for instance, ancient dragons (\c{D}s) or food
- rations (\c{%}s). But let's not get carried away. In this game,
- the rogue is simply running around in an empty room.
-
- The rogue is moved with the keypad (2, 4, 8, 6). That aside, we
- have implemented a \c quit command that triggers if the player
- types \c {q}. The player is then asked if he/she really wants to
- quit.
-
- Most games have commands that need more than one key press (we
- think of consecutive presses, i.e., not of several keys being
- pressed at the same time). In this game, only the \c quit command
- falls under this category, but for the sake of argument, let's
- imagine a fully-fledged game with a rich set of commands. If we
- were to implement these by catching key events in
- \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of
- class member variables to track the sequence of keys already typed
- (or find some other way of deducing the current state of a
- command). This can easily lead to spaghetti, which is--as we all
- well know, I'm sure--unpleasant. With a state machine, on the
- other hand, separate states can wait for a single key press, and
- that makes our lives a lot simpler.
-
- The example consists of two classes:
-
- \list
- \li \c Window draws the text display of the game and sets
- up the state machine. The window also has a status bar
- above the area in which the rouge moves.
- \li \c MovementTransition is a transition that carries out
- a single move of the rogue.
- \endlist
-
- Before we embark on a code walkthrough, it is necessary to take a
- closer look at the design of the machine. Here is a state chart
- that shows what we want to achieve:
-
- \image rogue-statechart.png
-
- The input state waits for a key press to start a new command.
- When receiving a key it recognizes, it transitions to one of the
- two commands of the game; though, as we will see, movement is
- handled by the transition itself. The quit state waits for the
- player to answer yes or no (by typing \c y or \c n) when asked
- whether he/she really wants to quit the game.
-
- The chart demonstrates how we use one state to wait for a single
- key press. The press received may trigger one of the transitions
- connected to the state.
-
- \section1 Window Class Definition
-
- The \c Window class is a widget that draws the text display of the
- game. It also sets up the state machine, i.e., creates and
- connects the states in the machine. It is the key events from this
- widget that are used by the machine.
-
- \snippet examples/statemachine/rogue/window.h 0
-
- \c Direction specifies the direction in which the rogue is to
- move. We use this in \c movePlayer(), which moves the rogue and
- repaints the window. The game has a status line above the area in
- which the rogue moves. The \c status property contains the text of
- this line. We use a property because the QState class allows
- setting any Qt \l{Qt's Property System}{property} when entered.
- More on this later.
-
- \snippet examples/statemachine/rogue/window.h 1
-
- The \c map is an array with the characters that are currently
- displayed. We set up the array in \c setupMap(), and update it
- when the rogue is moved. \c pX and \c pY is the current position
- of the rogue. \c WIDTH and \c HEIGHT are macros specifying the
- dimensions of the map.
-
- The \c paintEvent() function is left out of this walkthrough. We
- also do not discuss other code that does not concern the state
- machine (the \c setupMap(), \c status(), \c setStatus(), \c
- movePlayer(), and \c sizeHint() functions). If you wish to take a
- look at the code, click on the link for the \c window.cpp file at
- the top of this page.
-
- \section1 Window Class Implementation
-
- Here is the constructor of \c Window:
-
- \snippet examples/statemachine/rogue/window.cpp 0
- \dots
- \snippet examples/statemachine/rogue/window.cpp 1
-
- The player starts off at position (5, 5). We then set up the map
- and statemachine. Let's proceed with the \c buildMachine()
- function:
-
- \snippet examples/statemachine/rogue/window.cpp 2
-
- We enter \c inputState when the machine is started and from the \c
- quitState if the user wants to continue playing. We then set the
- status to a helpful reminder of how to play the game.
-
- First, the \c Movement transition is added to the input state.
- This will enable the rogue to be moved with the keypad. Notice
- that we don't set a target state for the movement transition. This
- will cause the transition to be triggered (and the
- \l{QAbstractTransition::}{onTransition()} function to be invoked),
- but the machine will not leave the \c inputState. If we had set \c
- inputState as the target state, we would first have left and then
- entered the \c inputState again.
-
- \snippet examples/statemachine/rogue/window.cpp 3
-
- When we enter \c quitState, we update the status bar of the
- window.
-
- \c QKeyEventTransition is a utility class that removes the hassle
- of implementing transitions for \l{QKeyEvent}s. We simply need to
- specify the key on which the transition should trigger and the
- target state of the transition.
-
- \snippet examples/statemachine/rogue/window.cpp 4
-
- The transition from \c inputState allows triggering the quit state
- when the player types \c {q}.
-
- \snippet examples/statemachine/rogue/window.cpp 5
-
- The machine is set up, so it's time to start it.
-
- \section1 The MovementTransition Class
-
- \c MovementTransition is triggered when the player request the
- rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in
- the \c inputState.
-
- \snippet examples/statemachine/rogue/movementtransition.h 0
-
- In the constructor, we tell QEventTransition to only send
- \l{QEvent::}{KeyPress} events to the
- \l{QAbstractTransition::}{eventTest()} function:
-
- \snippet examples/statemachine/rogue/movementtransition.h 1
-
- The KeyPress events come wrapped in \l{QStateMachine::WrappedEvent}s. \c event
- must be confirmed to be a wrapped event because Qt uses other
- events internally. After that, it is simply a matter of checking
- which key has been pressed.
-
- Let's move on to the \c onTransition() function:
-
- \snippet examples/statemachine/rogue/movementtransition.h 2
-
- When \c onTransition() is invoked, we know that we have a
- \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, and can ask \c
- Window to move the player.
-
- \section1 The Roguelike Tradition
-
- You might have been wondering why the game features a rogue. Well,
- these kinds of text based dungeon exploration games date back to a
- game called, yes, "Rogue". Although outflanked by the technology
- of modern 3D computer games, roguelikes have a solid community of
- hard-core, devoted followers.
-
- Playing these games can be surprisingly addictive (despite the
- lack of graphics). Angband, the perhaps most well-known rougelike,
- is found here: \l{http://rephial.org/}.
-*/
-
diff --git a/doc/src/examples/screenshot.qdoc b/doc/src/examples/screenshot.qdoc
deleted file mode 100644
index 4723d3d43c..0000000000
--- a/doc/src/examples/screenshot.qdoc
+++ /dev/null
@@ -1,247 +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$
-**
-****************************************************************************/
-
-/*!
- \example desktop/screenshot
- \title Screenshot Example
-
- The Screenshot example shows how to take a screenshot of the
- desktop using QApplication and QDesktopWidget. It also shows how
- to use QTimer to provide a single-shot timer, and how to
- reimplement the QWidget::resizeEvent() event handler to make sure
- that an application resizes smoothly and without data loss.
-
- \image screenshot-example.png
-
- With the application the users can take a screenshot of their
- desktop. They are provided with a couple of options:
-
- \list
- \li Delaying the screenshot, giving them time to rearrange
- their desktop.
- \li Hiding the application's window while the screenshot is taken.
- \endlist
-
- In addition the application allows the users to save their
- screenshot if they want to.
-
- \section1 Screenshot Class Definition
-
- \snippet examples/desktop/screenshot/screenshot.h 0
-
- The \c Screenshot class inherits QWidget and is the application's
- main widget. It displays the application options and a preview of
- the screenshot.
-
- We reimplement the QWidget::resizeEvent() function to make sure
- that the preview of the screenshot scales properly when the user
- resizes the application widget. We also need several private slots
- to facilitate the options:
-
- \list
- \li The \c newScreenshot() slot prepares a new screenshot.
- \li The \c saveScreenshot() slot saves the last screenshot.
- \li The \c shootScreen() slot takes the screenshot.
- \li The \c updateCheckBox() slot enables or disables the
- \uicontrol {Hide This Window} option.
- \endlist
-
- We also declare some private functions: We use the \c
- createOptionsGroupBox(), \c createButtonsLayout() and \c
- createButton() functions when we construct the widget. And we call
- the private \c updateScreenshotLabel() function whenever a new
- screenshot is taken or when a resize event changes the size of the
- screenshot preview label.
-
- In addition we need to store the screenshot's original pixmap. The
- reason is that when we display the preview of the screenshot, we
- need to scale its pixmap, storing the original we make sure that
- no data are lost in that process.
-
- \section1 Screenshot Class Implementation
-
- \snippet examples/desktop/screenshot/screenshot.cpp 0
-
- In the constructor we first create the QLabel displaying the
- screenshot preview.
-
- We set the QLabel's size policy to be QSizePolicy::Expanding both
- horizontally and vertically. This means that the QLabel's size
- hint is a sensible size, but the widget can be shrunk and still be
- useful. Also, the widget can make use of extra space, so it should
- get as much space as possible. Then we make sure the QLabel is
- aligned in the center of the \c Screenshot widget, and set its
- minimum size.
-
- We create the applications's buttons and the group box containing
- the application's options, and put it all into a main
- layout. Finally we take the initial screenshot, and set the initial
- delay and the window title, before we resize the widget to a
- suitable size.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 1
-
- The \c resizeEvent() function is reimplemented to receive the
- resize events dispatched to the widget. The purpose is to scale
- the preview screenshot pixmap without deformation of its content,
- and also make sure that the application can be resized smoothly.
-
- To achieve the first goal, we scale the screenshot pixmap using
- Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large
- as possible inside the current size of the screenshot preview
- label, preserving the aspect ratio. This means that if the user
- resizes the application window in only one direction, the preview
- screenshot keeps the same size.
-
- To reach our second goal, we make sure that the preview screenshot
- only is repainted (using the private \c updateScreenshotLabel()
- function) when it actually changes its size.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 2
-
- The private \c newScreenshot() slot is called when the user
- requests a new screenshot; but the slot only prepares a new
- screenshot.
-
- First we see if the \uicontrol {Hide This Window} option is checked, if
- it is we hide the \c Screenshot widget. Then we disable the \uicontrol
- {New Screenshot} button, to make sure the user only can request
- one screenshot at a time.
-
- We create a timer using the QTimer class which provides repetitive
- and single-shot timers. We set the timer to time out only once,
- using the static QTimer::singleShot() function. This function
- calls the private \c shootScreen() slot after the time interval
- specified by the \uicontrol {Screenshot Delay} option. It is \c
- shootScreen() that actually performs the screenshot.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 3
-
- The \c saveScreenshot() slot is called when the user push the \uicontrol
- Save button, and it presents a file dialog using the QFileDialog
- class.
-
- QFileDialog enables a user to traverse the file system in order to
- select one or many files or a directory. The easiest way to create
- a QFileDialog is to use the convenience static
- functions.
-
- We define the default file format to be png, and we make the file
- dialog's initial path the path the application is run from. We
- create the file dialog using the static
- QFileDialog::getSaveFileName() function which returns a file name
- selected by the user. The file does not have to exist. If the file
- name is valid, we use the QPixmap::save() function to save the
- screenshot's original pixmap in that file.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 4
-
- The \c shootScreen() slot is called to take the screenshot. If the
- user has chosen to delay the screenshot, we make the application
- beep when the screenshot is taken using the static
- QApplication::beep() function.
-
- The QApplication class manages the GUI application's control flow
- and main settings. It contains the main event loop, where all
- events from the window system and other sources are processed and
- dispatched.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 5
-
- Using the static function QApplication::primaryScreen(), we
- obtain the QScreen object for the application's main screen.
-
- We take the screenshot using the QScreen::grabWindow()
- function. The function grabs the contents of the window passed as
- an argument, makes a pixmap out of it and returns that pixmap.
- The window id can be obtained with QWidget::winId() or QWindow::winId().
- Here, however, we just pass 0 as the window id, indicating that we
- want to grab the entire screen.
-
- We update the screenshot preview label using the private \c
- updateScreenshotLabel() function. Then we enable the \uicontrol {New
- Screenshot} button, and finally we make the \c Screenshot widget
- visible if it was hidden during the screenshot.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 6
-
- The \uicontrol {Hide This Window} option is enabled or disabled
- depending on the delay of the screenshot. If there is no delay,
- the application window cannot be hidden and the option's checkbox
- is disabled.
-
- The \c updateCheckBox() slot is called whenever the user changes
- the delay using the \uicontrol {Screenshot Delay} option.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 7
-
- The private \c createOptionsGroupBox() function is called from the
- constructor.
-
- First we create a group box that will contain all of the options'
- widgets. Then we create a QSpinBox and a QLabel for the \uicontrol
- {Screenshot Delay} option, and connect the spinbox to the \c
- updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol
- {Hide This Window} option, add all the options' widgets to a
- QGridLayout and install the layout on the group box.
-
- Note that we don't have to specify any parents for the widgets
- when we create them. The reason is that when we add a widget to a
- layout and install the layout on another widget, the layout's
- widgets are automatically reparented to the widget the layout is
- installed on.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 8
-
- The private \c createButtonsLayout() function is called from the
- constructor. We create the application's buttons using the private
- \c createButton() function, and add them to a QHBoxLayout.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 9
-
- The private \c createButton() function is called from the \c
- createButtonsLayout() function. It simply creates a QPushButton
- with the provided text, connects it to the provided receiver and
- slot, and returns a pointer to the button.
-
- \snippet examples/desktop/screenshot/screenshot.cpp 10
-
- The private \c updateScreenshotLabel() function is called whenever
- the screenshot changes, or when a resize event changes the size of
- the screenshot preview label. It updates the screenshot preview's
- label using the QLabel::setPixmap() and QPixmap::scaled()
- functions.
-
- QPixmap::scaled() returns a copy of the given pixmap scaled to a
- rectangle of the given size according to the given
- Qt::AspectRatioMode and Qt::TransformationMode.
-
- We scale the original pixmap to fit the current screenshot label's
- size, preserving the aspect ratio and giving the resulting pixmap
- smoothed edges.
-*/
-
diff --git a/doc/src/examples/scribble.qdoc b/doc/src/examples/scribble.qdoc
deleted file mode 100644
index 4c4df891b2..0000000000
--- a/doc/src/examples/scribble.qdoc
+++ /dev/null
@@ -1,417 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/scribble
- \title Scribble Example
-
- The Scribble example shows how to reimplement some of QWidget's
- event handlers to receive the events generated for the
- application's widgets.
-
- We reimplement the mouse event handlers to implement drawing, the
- paint event handler to update the application and the resize event
- handler to optimize the application's appearance. In addition we
- reimplement the close event handler to intercept the close events
- before terminating the application.
-
- The example also demonstrates how to use QPainter to draw an image
- in real time, as well as to repaint widgets.
-
- \image scribble-example.png Screenshot of the Scribble example
-
- With the Scribble application the users can draw an image. The
- \uicontrol File menu gives the users the possibility to open and edit an
- existing image file, save an image and exit the application. While
- drawing, the \uicontrol Options menu allows the users to to choose the
- pen color and pen width, as well as clear the screen. In addition
- the \uicontrol Help menu provides the users with information about the
- Scribble example in particular, and about Qt in general.
-
- The example consists of two classes:
-
- \list
- \li \c ScribbleArea is a custom widget that displays a QImage and
- allows to the user to draw on it.
- \li \c MainWindow provides a menu above the \c ScribbleArea.
- \endlist
-
- We will start by reviewing the \c ScribbleArea class. Then we will
- review the \c MainWindow class, which uses \c ScribbleArea.
-
- \section1 ScribbleArea Class Definition
-
- \snippet examples/widgets/scribble/scribblearea.h 0
-
- The \c ScribbleArea class inherits from QWidget. We reimplement
- the \c mousePressEvent(), \c mouseMoveEvent() and \c
- mouseReleaseEvent() functions to implement the drawing. We
- reimplement the \c paintEvent() function to update the scribble
- area, and the \c resizeEvent() function to ensure that the QImage
- on which we draw is at least as large as the widget at any time.
-
- We need several public functions: \c openImage() loads an image
- from a file into the scribble area, allowing the user to edit the
- image; \c save() writes the currently displayed image to file; \c
- clearImage() slot clears the image displayed in the scribble
- area. We need the private \c drawLineTo() function to actually do
- the drawing, and \c resizeImage() to change the size of a
- QImage. The \c print() slot handles printing.
-
- We also need the following private variables:
-
- \list
- \li \c modified is \c true if there are unsaved
- changes to the image displayed in the scribble area.
- \li \c scribbling is \c true while the user is pressing
- the left mouse button within the scribble area.
- \li \c penWidth and \c penColor hold the currently
- set width and color for the pen used in the application.
- \li \c image stores the image drawn by the user.
- \li \c lastPoint holds the position of the cursor at the last
- mouse press or mouse move event.
- \endlist
-
- \section1 ScribbleArea Class Implementation
-
- \snippet examples/widgets/scribble/scribblearea.cpp 0
-
- In the constructor, we set the Qt::WA_StaticContents
- attribute for the widget, indicating that the widget contents are
- rooted to the top-left corner and don't change when the widget is
- resized. Qt uses this attribute to optimize paint events on
- resizes. This is purely an optimization and should only be used
- for widgets whose contents are static and rooted to the top-left
- corner.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 1
- \snippet examples/widgets/scribble/scribblearea.cpp 2
-
- In the \c openImage() function, we load the given image. Then we
- resize the loaded QImage to be at least as large as the widget in
- both directions using the private \c resizeImage() function and
- we set the \c image member variable to be the loaded image. At
- the end, we call QWidget::update() to schedule a repaint.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 3
- \snippet examples/widgets/scribble/scribblearea.cpp 4
-
- The \c saveImage() function creates a QImage object that covers
- only the visible section of the actual \c image and saves it using
- QImage::save(). If the image is successfully saved, we set the
- scribble area's \c modified variable to \c false, because there is
- no unsaved data.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 5
- \snippet examples/widgets/scribble/scribblearea.cpp 6
- \codeline
- \snippet examples/widgets/scribble/scribblearea.cpp 7
- \snippet examples/widgets/scribble/scribblearea.cpp 8
-
- The \c setPenColor() and \c setPenWidth() functions set the
- current pen color and width. These values will be used for future
- drawing operations.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 9
- \snippet examples/widgets/scribble/scribblearea.cpp 10
-
- The public \c clearImage() slot clears the image displayed in the
- scribble area. We simply fill the entire image with white, which
- corresponds to RGB value (255, 255, 255). As usual when we modify
- the image, we set \c modified to \c true and schedule a repaint.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 11
- \snippet examples/widgets/scribble/scribblearea.cpp 12
-
- For mouse press and mouse release events, we use the
- QMouseEvent::button() function to find out which button caused
- the event. For mose move events, we use QMouseEvent::buttons()
- to find which buttons are currently held down (as an OR-combination).
-
- If the users press the left mouse button, we store the position
- of the mouse cursor in \c lastPoint. We also make a note that the
- user is currently scribbling. (The \c scribbling variable is
- necessary because we can't assume that a mouse move and mouse
- release event is always preceded by a mouse press event on the
- same widget.)
-
- If the user moves the mouse with the left button pressed down or
- releases the button, we call the private \c drawLineTo() function
- to draw.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 13
- \snippet examples/widgets/scribble/scribblearea.cpp 14
-
- In the reimplementation of the \l
- {QWidget::paintEvent()}{paintEvent()} function, we simply create
- a QPainter for the scribble area, and draw the image.
-
- At this point, you might wonder why we don't just draw directly
- onto the widget instead of drawing in a QImage and copying the
- QImage onto screen in \c paintEvent(). There are at least three
- good reasons for this:
-
- \list
- \li The window system requires us to be able to redraw the widget
- \e{at any time}. For example, if the window is minimized and
- restored, the window system might have forgotten the contents
- of the widget and send us a paint event. In other words, we
- can't rely on the window system to remember our image.
-
- \li Qt normally doesn't allow us to paint outside of \c
- paintEvent(). In particular, we can't paint from the mouse
- event handlers. (This behavior can be changed using the
- Qt::WA_PaintOnScreen widget attribute, though.)
-
- \li If initialized properly, a QImage is guaranteed to use 8-bit
- for each color channel (red, green, blue, and alpha), whereas
- a QWidget might have a lower color depth, depending on the
- monitor configuration. This means that if we load a 24-bit or
- 32-bit image and paint it onto a QWidget, then copy the
- QWidget into a QImage again, we might lose some information.
- \endlist
-
- \snippet examples/widgets/scribble/scribblearea.cpp 15
- \snippet examples/widgets/scribble/scribblearea.cpp 16
-
- When the user starts the Scribble application, a resize event is
- generated and an image is created and displayed in the scribble
- area. We make this initial image slightly larger than the
- application's main window and scribble area, to avoid always
- resizing the image when the user resizes the main window (which
- would be very inefficient). But when the main window becomes
- larger than this initial size, the image needs to be resized.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 17
- \snippet examples/widgets/scribble/scribblearea.cpp 18
-
- In \c drawLineTo(), we draw a line from the point where the mouse
- was located when the last mouse press or mouse move occurred, we
- set \c modified to true, we generate a repaint event, and we
- update \c lastPoint so that next time \c drawLineTo() is called,
- we continue drawing from where we left.
-
- We could call the \c update() function with no parameter, but as
- an easy optimization we pass a QRect that specifies the rectangle
- inside the scribble are needs updating, to avoid a complete
- repaint of the widget.
-
- \snippet examples/widgets/scribble/scribblearea.cpp 19
- \snippet examples/widgets/scribble/scribblearea.cpp 20
-
- QImage has no nice API for resizing an image. There's a
- QImage::copy() function that could do the trick, but when used to
- expand an image, it fills the new areas with black, whereas we
- want white.
-
- So the trick is to create a brand new QImage with the right size,
- to fill it with white, and to draw the old image onto it using
- QPainter. The new image is given the QImage::Format_RGB32
- format, which means that each pixel is stored as 0xffRRGGBB
- (where RR, GG, and BB are the red, green and blue
- color channels, ff is the hexadecimal value 255).
-
- Printing is handled by the \c print() slot:
-
- \snippet examples/widgets/scribble/scribblearea.cpp 21
-
- We construct a high resolution QPrinter object for the required
- output format, using a QPrintDialog to ask the user to specify a
- page size and indicate how the output should be formatted on the page.
-
- If the dialog is accepted, we perform the task of printing to the paint
- device:
-
- \snippet examples/widgets/scribble/scribblearea.cpp 22
-
- Printing an image to a file in this way is simply a matter of
- painting onto the QPrinter. We scale the image to fit within the
- available space on the page before painting it onto the paint
- device.
-
- \section1 MainWindow Class Definition
-
- \snippet examples/widgets/scribble/mainwindow.h 0
-
- The \c MainWindow class inherits from QMainWindow. We reimplement
- the \l{QWidget::closeEvent()}{closeEvent()} handler from QWidget.
- The \c open(), \c save(), \c penColor() and \c penWidth()
- slots correspond to menu entries. In addition we create four
- private functions.
-
- We use the boolean \c maybeSave() function to check if there are
- any unsaved changes. If there are unsaved changes, we give the
- user the opportunity to save these changes. The function returns
- \c false if the user clicks \uicontrol Cancel. We use the \c saveFile()
- function to let the user save the image currently displayed in
- the scribble area.
-
- \section1 MainWindow Class Implementation
-
- \snippet examples/widgets/scribble/mainwindow.cpp 0
-
- In the constructor, we create a scribble area which we make the
- central widget of the \c MainWindow widget. Then we create the
- associated actions and menus.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 1
- \snippet examples/widgets/scribble/mainwindow.cpp 2
-
- Close events are sent to widgets that the users want to close,
- usually by clicking \uicontrol{File|Exit} or by clicking the \uicontrol X
- title bar button. By reimplementing the event handler, we can
- intercept attempts to close the application.
-
- In this example, we use the close event to ask the user to save
- any unsaved changes. The logic for that is located in the \c
- maybeSave() function. If \c maybeSave() returns true, there are
- no modifications or the users successfully saved them, and we
- accept the event. The application can then terminate normally. If
- \c maybeSave() returns false, the user clicked \uicontrol Cancel, so we
- "ignore" the event, leaving the application unaffected by it.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 3
- \snippet examples/widgets/scribble/mainwindow.cpp 4
-
- In the \c open() slot we first give the user the opportunity to
- save any modifications to the currently displayed image, before a
- new image is loaded into the scribble area. Then we ask the user
- to choose a file and we load the file in the \c ScribbleArea.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 5
- \snippet examples/widgets/scribble/mainwindow.cpp 6
-
- The \c save() slot is called when the users choose the \uicontrol {Save
- As} menu entry, and then choose an entry from the format menu. The
- first thing we need to do is to find out which action sent the
- signal using QObject::sender(). This function returns the sender
- as a QObject pointer. Since we know that the sender is an action
- object, we can safely cast the QObject. We could have used a
- C-style cast or a C++ \c static_cast<>(), but as a defensive
- programming technique we use a qobject_cast(). The advantage is
- that if the object has the wrong type, a null pointer is
- returned. Crashes due to null pointers are much easier to diagnose
- than crashes due to unsafe casts.
-
- Once we have the action, we extract the chosen format using
- QAction::data(). (When the actions are created, we use
- QAction::setData() to set our own custom data attached to the
- action, as a QVariant. More on this when we review \c
- createActions().)
-
- Now that we know the format, we call the private \c saveFile()
- function to save the currently displayed image.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 7
- \snippet examples/widgets/scribble/mainwindow.cpp 8
-
- We use the \c penColor() slot to retrieve a new color from the
- user with a QColorDialog. If the user chooses a new color, we
- make it the scribble area's color.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 9
- \snippet examples/widgets/scribble/mainwindow.cpp 10
-
- To retrieve a new pen width in the \c penWidth() slot, we use
- QInputDialog. The QInputDialog class provides a simple
- convenience dialog to get a single value from the user. We use
- the static QInputDialog::getInt() function, which combines a
- QLabel and a QSpinBox. The QSpinBox is initialized with the
- scribble area's pen width, allows a range from 1 to 50, a step of
- 1 (meaning that the up and down arrow increment or decrement the
- value by 1).
-
- The boolean \c ok variable will be set to \c true if the user
- clicked \uicontrol OK and to \c false if the user pressed \uicontrol Cancel.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 11
- \snippet examples/widgets/scribble/mainwindow.cpp 12
-
- We implement the \c about() slot to create a message box
- describing what the example is designed to show.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 13
- \snippet examples/widgets/scribble/mainwindow.cpp 14
-
- In the \c createAction() function we create the actions
- representing the menu entries and connect them to the appropriate
- slots. In particular we create the actions found in the \uicontrol
- {Save As} sub-menu. We use QImageWriter::supportedImageFormats()
- to get a list of the supported formats (as a QList<QByteArray>).
-
- Then we iterate through the list, creating an action for each
- format. We call QAction::setData() with the file format, so we
- can retrieve it later as QAction::data(). We could also have
- deduced the file format from the action's text, by truncating the
- "...", but that would have been inelegant.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 15
- \snippet examples/widgets/scribble/mainwindow.cpp 16
-
- In the \c createMenu() function, we add the previously created
- format actions to the \c saveAsMenu. Then we add the rest of the
- actions as well as the \c saveAsMenu sub-menu to the \uicontrol File,
- \uicontrol Options and \uicontrol Help menus.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus. The QMenuBar class provides
- a horizontal menu bar with a list of pull-down \l{QMenu}s. At the
- end we put the \uicontrol File and \uicontrol Options menus in the \c
- {MainWindow}'s menu bar, which we retrieve using the
- QMainWindow::menuBar() function.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 17
- \snippet examples/widgets/scribble/mainwindow.cpp 18
-
- In \c mayBeSave(), we check if there are any unsaved changes. If
- there are any, we use QMessageBox to give the user a warning that
- the image has been modified and the opportunity to save the
- modifications.
-
- As with QColorDialog and QFileDialog, the easiest way to create a
- QMessageBox is to use its static functions. QMessageBox provides
- a range of different messages arranged along two axes: severity
- (question, information, warning and critical) and complexity (the
- number of necessary response buttons). Here we use the \c
- warning() function sice the message is rather important.
-
- If the user chooses to save, we call the private \c saveFile()
- function. For simplicitly, we use PNG as the file format; the
- user can always press \uicontrol Cancel and save the file using another
- format.
-
- The \c maybeSave() function returns \c false if the user clicks
- \uicontrol Cancel; otherwise it returns \c true.
-
- \snippet examples/widgets/scribble/mainwindow.cpp 19
- \snippet examples/widgets/scribble/mainwindow.cpp 20
-
- In \c saveFile(), we pop up a file dialog with a file name
- suggestion. The static QFileDialog::getSaveFileName() function
- returns a file name selected by the user. The file does not have
- to exist.
-*/
diff --git a/doc/src/examples/sdi.qdoc b/doc/src/examples/sdi.qdoc
deleted file mode 100644
index b686888797..0000000000
--- a/doc/src/examples/sdi.qdoc
+++ /dev/null
@@ -1,36 +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$
-**
-****************************************************************************/
-
-/*!
- \example mainwindows/sdi
- \title SDI Example
-
- The SDI example shows how to create a Single Document Interface. It uses a number of
- top-level windows to display the contents of different text files.
-
- \image sdi-example.png
-*/
diff --git a/doc/src/examples/shapedclock.qdoc b/doc/src/examples/shapedclock.qdoc
deleted file mode 100644
index b83178b44d..0000000000
--- a/doc/src/examples/shapedclock.qdoc
+++ /dev/null
@@ -1,131 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/shapedclock
- \title Shaped Clock Example
-
- The Shaped Clock example shows how to apply a widget mask to a top-level
- widget to produce a shaped window.
-
- \image shapedclock-example.png
-
- Widget masks are used to customize the shapes of top-level widgets by restricting
- the available area for painting. On some window systems, setting certain window flags
- will cause the window decoration (title bar, window frame, buttons) to be disabled,
- allowing specially-shaped windows to be created. In this example, we use this feature
- to create a circular window containing an analog clock.
-
- Since this example's window does not provide a \uicontrol File menu or a close
- button, we provide a context menu with an \uicontrol Exit entry so that the example
- can be closed. Click the right mouse button over the window to open this menu.
-
- \section1 ShapedClock Class Definition
-
- The \c ShapedClock class is based on the \c AnalogClock class defined in the
- \l{Analog Clock Example}{Analog Clock} example. The whole class definition is
- presented below:
-
- \snippet examples/widgets/shapedclock/shapedclock.h 0
-
- The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found
- in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()}
- so that we don't have to resize the widget explicitly. We also provide an event
- handler for resize events. This allows us to update the mask if the clock is resized.
-
- Since the window containing the clock widget will have no title bar, we provide
- implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and
- \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged
- around the screen. The \c dragPosition variable lets us keep track of where the user
- last clicked on the widget.
-
- \section1 ShapedClock Class Implementation
-
- The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock
- constructor. We set up a timer and connect it to the widget's update() slot:
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 0
-
- We inform the window manager that the widget is not to be decorated with a window
- frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need
- to provide a way for the user to move the clock around the screen.
-
- Mouse button events are delivered to the \c mousePressEvent() handler:
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 1
-
- If the left mouse button is pressed over the widget, we record the displacement in
- global (screen) coordinates between the top-left position of the widget's frame (even
- when hidden) and the point where the mouse click occurred. This displacement will be
- used if the user moves the mouse while holding down the left button. Since we acted
- on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function.
-
- \image shapedclock-dragging.png
-
- The \c mouseMoveEvent() handler is called if the mouse is moved over the widget.
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 2
-
- If the left button is held down while the mouse is moved, the top-left corner of the
- widget is moved to the point given by subtracting the \c dragPosition from the current
- cursor position in global coordinates. If we drag the widget, we also accept the event.
-
- The \c paintEvent() function is given for completeness. See the
- \l{Analog Clock Example}{Analog Clock} example for a description of the process used
- to render the clock.
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 3
-
- In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent()
- to determine the region of the widget that is visible to the user:
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 4
-
- Since the clock face is a circle drawn in the center of the widget, this is the region
- we use as the mask.
-
- Although the lack of a window frame may make it difficult for the user to resize the
- widget on some platforms, it will not necessarily be impossible. The \c resizeEvent()
- function ensures that the widget mask will always be updated if the widget's dimensions
- change, and additionally ensures that it will be set up correctly when the widget is
- first displayed.
-
- Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable
- default size when it is first shown:
-
- \snippet examples/widgets/shapedclock/shapedclock.cpp 5
-
- \section1 Notes on Widget Masks
-
- Since QRegion allows arbitrarily complex regions to be created, widget masks can be
- made to suit the most unconventionally-shaped windows, and even allow widgets to be
- displayed with holes in them.
-
- Widget masks can also be constructed by using the contents of pixmap to define the
- opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be
- obtained with QPixmap::mask().
-*/
diff --git a/doc/src/examples/simpledommodel.qdoc b/doc/src/examples/simpledommodel.qdoc
deleted file mode 100644
index b49750d5a5..0000000000
--- a/doc/src/examples/simpledommodel.qdoc
+++ /dev/null
@@ -1,280 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/simpledommodel
- \title Simple DOM Model Example
-
- The Simple DOM Model example shows how an existing class can be adapted for use with
- the model/view framework.
-
- \image simpledommodel-example.png
-
- Qt provides two complementary sets of classes for reading XML files: The classes based
- around QXmlReader provide a SAX-style API for incremental reading of large files, and
- the classes based around QDomDocument enable developers to access the contents of XML
- files using a Document Object Model (DOM) API.
-
- In this example, we create a model that uses the DOM API to expose the structure and
- contents of XML documents to views via the standard QAbstractModel interface.
-
- \section1 Design and Concepts
-
- Reading an XML document with Qt's DOM classes is a straightforward process. Typically,
- the contents of a file are supplied to QDomDocument, and nodes are accessed using the
- functions provided by QDomNode and its subclasses.
-
- \omit
- For example, the following code
- snippet reads the contents of a file into a QDomDocument object and traverses the
- document, reading all the plain text that can be found:
-
- \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0
-
- In principle, the functions provided by QDomNode can be used to navigate from any
- given starting point in a document to the piece of data requested by another component.
- Since QDomDocument maintains information about the structure of a document, we can
- use this to implement the required virtual functions in a QAbstractItemModel subclass.
- \endomit
-
- The aim is to use the structure provided by QDomDocument by wrapping QDomNode objects
- in item objects similar to the \c TreeItem objects used in the
- \l{Simple Tree Model Example}{Simple Tree Model} example.
-
- \section1 DomModel Class Definition
-
- Let us begin by examining the \c DomModel class:
-
- \snippet examples/itemviews/simpledommodel/dommodel.h 0
-
- The class definition contains all the basic functions that are needed for a
- read-only model. Only the constructor and \c document() function are specific to
- this model. The private \c domDocument variable is used to hold the document
- that is exposed by the model; the \c rootItem variable contains a pointer to
- the root item in the model.
-
- \section1 DomItem Class Definition
-
- The \c DomItem class is used to hold information about a specific QDomNode in
- the document:
-
- \snippet examples/itemviews/simpledommodel/domitem.h 0
-
- Each \c DomItem provides a wrapper for a QDomNode obtained from the underlying
- document which contains a reference to the node, it's location in the parent node's
- list of child nodes, and a pointer to a parent wrapper item.
-
- The \c parent(), \c child(), and \c row() functions are convenience functions for
- the \c DomModel to use that provide basic information about the item to be discovered
- quickly. The node() function provides access to the underlying QDomNode object.
-
- As well as the information supplied in the constructor, the class maintains a cache
- of information about any child items. This is used to provide a collection of
- persistent item objects that the model can identify consistently and improve the
- performance of the model when accessing child items.
-
- \section1 DomItem Class Implementation
-
- Since the \c DomItem class is only a thin wrapper around QDomNode objects, with a
- few additional features to help improve performance and memory usage, we can provide
- a brief outline of the class before discussing the model itself.
-
- The constructor simply records details of the QDomNode that needs to be wrapped:
-
- \snippet examples/itemviews/simpledommodel/domitem.cpp 0
- \snippet examples/itemviews/simpledommodel/domitem.cpp 1
-
- As a result, functions to provide the parent wrapper, the row number occupied by
- the item in its parent's list of children, and the underlying QDomNode for each item
- are straightforward to write:
-
- \snippet examples/itemviews/simpledommodel/domitem.cpp 4
- \codeline
- \snippet examples/itemviews/simpledommodel/domitem.cpp 6
- \codeline
- \snippet examples/itemviews/simpledommodel/domitem.cpp 3
-
- It is necessary to maintain a collection of items which can be consistently identified
- by the model. For that reason, we maintain a hash of child wrapper items that, to
- minimize memory usage, is initially empty. The model uses the item's \c child()
- function to help create model indexes, and this constructs wrappers for the children
- of the item's QDomNode, relating the row number of each child to the newly-constructed
- wrapper:
-
- \snippet examples/itemviews/simpledommodel/domitem.cpp 5
-
- If a QDomNode was previously wrapped, the cached wrapper is returned; otherwise, a
- new wrapper is constructed and stored for valid children, and zero is returned for
- invalid ones.
-
- The class's destructor deletes all the child items of the wrapper:
-
- \snippet examples/itemviews/simpledommodel/domitem.cpp 2
-
- These, in turn, will delete their children and free any QDomNode objects in use.
-
- \section1 DomModel Class Implementation
-
- The structure provided by the \c DomItem class makes the implementation of \c DomModel
- similar to the \c TreeModel shown in the
- \l{Simple Tree Model Example}{Simple Tree Model} example.
-
- The constructor accepts an existing document and a parent object for the model:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 0
-
- A shallow copy of the document is stored for future reference, and a root item is
- created to provide a wrapper around the document. We assign the root item a row
- number of zero only to be consistent since the root item will have no siblings.
-
- Since the model only contains information about the root item, the destructor only
- needs to delete this one item:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 1
-
- All of the child items in the tree will be deleted by the \c DomItem destructor as
- their parent items are deleted.
-
- \section2 Basic Properties of The Model
-
- Some aspects of the model do not depend on the structure of the underlying document,
- and these are simple to implement.
-
- The number of columns exposed by the model is returned by the \c columnCount()
- function:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 2
-
- This value is fixed, and does not depend on the location or type of the underlying
- node in the document. We will use these three columns to display different kinds of
- data from the underlying document.
-
- Since we only implement a read-only model, the \c flags() function is straightforward
- to write:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 5
-
- Since the model is intended for use in a tree view, the \c headerData() function only
- provides a horizontal header:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 6
-
- The model presents the names of nodes in the first column, element attributes in the
- second, and any node values in the third.
-
- \section2 Navigating The Document
-
- The index() function creates a model index for the item with the given row, column,
- and parent in the model:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 7
-
- The function first has to relate the parent index to an item that contains a node
- from the underlying document. If the parent index is invalid, it refers to the root
- node in the document, so we retrieve the root item that wraps it; otherwise, we
- obtain a pointer to the relevant item using the QModelIndex::internalPointer()
- function. We are able to extract a pointer in this way because any valid model index
- will have been created by this function, and we store pointers to item objects in
- any new indexes that we create with QAbstractItemModel::createIndex():
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 8
-
- A child item for the given row is provided by the parent item's \c child() function.
- If a suitable child item was found then we call
- \l{QAbstractItemModel::createIndex()}{createIndex()} to produce a model index for the
- requested row and column, passing a pointer to the child item for it to store
- internally. If no suitable child item is found, an invalid model index is returned.
-
- Note that the items themselves maintain ownership of their child items. This means
- that the model does not need to keep track of the child items that have been created,
- and can let the items themselves tidy up when they are deleted.
-
- The number of rows beneath a given item in the model is returned by the \c rowCount()
- function, and is the number of child nodes contained by the node that corresponds to
- the specified model index:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 10
-
- To obtain the relevant node in the underlying document, we access the item via the
- internal pointer stored in the model index. If an invalid index is supplied, the
- root item is used instead. We use the item's \c node() function to access the node
- itself, and simply count the number of child nodes it contains.
-
- Since the model is used to represent a hierarchical data structure, it needs to
- provide an implementation for the \c parent() function. This returns a model index
- that corresponds to the parent of a child model index supplied as its argument:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 9
-
- For valid indexes other than the index corresponding to the root item, we obtain
- a pointer to the relevant item using the method described in the \c index() function,
- and use the item's \c parent() function to obtain a pointer to the parent item.
-
- If no valid parent item exists, or if the parent item is the root item, we can simply
- follow convention and return an invalid model index. For all other parent items, we
- create a model index containing the appropriate row and column numbers, and a pointer
- to the parent item we just obtained.
-
- Data is provided by the \c data() function. For simplicity, we only provide data for
- the \l{Qt::DisplayRole}{display role}, returning an invalid variant for all other
- requests:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 3
-
- As before, we obtain an item pointer for the index supplied, and use it to obtain
- the underlying document node. Depending on the column specified, the data we return
- is obtained in different ways:
-
- \snippet examples/itemviews/simpledommodel/dommodel.cpp 4
-
- For the first column, we return the node's name. For the second column, we read any
- attributes that the node may have, and return a string that contains a space-separated
- list of attribute-value assignments. For the third column, we return any value that
- the node may have; this allows the contents of text nodes to be displayed in a view.
-
- If data from any other column is requested, an invalid variant is returned.
-
- \section1 Implementation Notes
-
- Ideally, we would rely on the structure provided by QDomDocument to help us write
- the \l{QAbstractItemModel::parent()}{parent()} and
- \l{QAbstractItemModel::index()}{index()} functions that are required when subclassing
- QAbstractItemModel. However, since Qt's DOM classes use their own system for
- dynamically allocating memory for DOM nodes, we cannot guarantee that the QDomNode
- objects returned for a given piece of information will be the same for subsequent
- accesses to the document.
-
- We use item wrappers for each QDomNode to provide consistent pointers that the model
- can use to navigate the document structure.
- \omit
- Since these items contain value references to the QDomNode objects themselves, this
- has the side effect that the DOM nodes themselves can be used to reliably navigate
- the document [not sure about this - QDom* may return different QDomNode objects for
- the same piece of information]. However, this advantage is redundant since we need to
- use wrapper items to obtain it. [Possible use of QDomNode cache in the model itself.]
- \endomit
-*/
diff --git a/doc/src/examples/simpletreemodel.qdoc b/doc/src/examples/simpletreemodel.qdoc
deleted file mode 100644
index ed584a3307..0000000000
--- a/doc/src/examples/simpletreemodel.qdoc
+++ /dev/null
@@ -1,333 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/simpletreemodel
- \title Simple Tree Model Example
-
- The Simple Tree Model example shows how to create a basic, read-only
- hierarchical model to use with Qt's standard view classes. For a
- description of simple non-hierarchical list and table models, see the
- \l{Model/View Programming} overview.
-
- \image simpletreemodel-example.png
-
- Qt's model/view architecture provides a standard way for views to
- manipulate information in a data source, using an abstract model
- of the data to simplify and standardize the way it is accessed.
- Simple models represent data as a table of items, and allow views
- to access this data via an
- \l{Model/View Programming#Models}{index-based} system. More generally,
- models can be used to represent data in the form of a tree structure
- by allowing each item to act as a parent to a table of child items.
-
- Before attempting to implement a tree model, it is worth considering whether
- the data is supplied by an external source, or whether it is going to be
- maintained within the model itself. In this example, we will implement an
- internal structure to hold data rather than discuss how to package data from
- an external source.
-
- \section1 Design and Concepts
-
- The data structure that we use to represent the structure of the data takes
- the form of a tree built from \c TreeItem objects. Each \c TreeItem
- represents an item in a tree view, and contains several columns of data.
-
- \target SimpleTreeModelStructure
- \table
- \row \li \inlineimage treemodel-structure.png
- \li \b{Simple Tree Model Structure}
-
- The data is stored internally in the model using \c TreeItem objects that
- are linked together in a pointer-based tree structure. Generally, each
- \c TreeItem has a parent item, and can have a number of child items.
- However, the root item in the tree structure has no parent item and it
- is never referenced outside the model.
-
- Each \c TreeItem contains information about its place in the tree
- structure; it can return its parent item and its row number. Having
- this information readily available makes implementing the model easier.
-
- Since each item in a tree view usually contains several columns of data
- (a title and a summary in this example), it is natural to store this
- information in each item. For simplicity, we will use a list of QVariant
- objects to store the data for each column in the item.
- \endtable
-
- The use of a pointer-based tree structure means that, when passing a
- model index to a view, we can record the address of the corresponding
- item in the index (see QAbstractItemModel::createIndex()) and retrieve
- it later with QModelIndex::internalPointer(). This makes writing the
- model easier and ensures that all model indexes that refer to the same
- item have the same internal data pointer.
-
- With the appropriate data structure in place, we can create a tree model
- with a minimal amount of extra code to supply model indexes and data to
- other components.
-
- \section1 TreeItem Class Definition
-
- The \c TreeItem class is defined as follows:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.h 0
-
- The class is a basic C++ class. It does not inherit from QObject or
- provide signals and slots. It is used to hold a list of QVariants,
- containing column data, and information about its position in the tree
- structure. The functions provide the following features:
-
- \list
- \li The \c appendChildItem() is used to add data when the model is first
- constructed and is not used during normal use.
- \li The \c child() and \c childCount() functions allow the model to obtain
- information about any child items.
- \li Information about the number of columns associated with the item is
- provided by \c columnCount(), and the data in each column can be
- obtained with the data() function.
- \li The \c row() and \c parent() functions are used to obtain the item's
- row number and parent item.
- \endlist
-
- The parent item and column data are stored in the \c parentItem and
- \c itemData private member variables. The \c childItems variable contains
- a list of pointers to the item's own child items.
-
- \section1 TreeItem Class Implementation
-
- The constructor is only used to record the item's parent and the data
- associated with each column.
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 0
-
- A pointer to each of the child items belonging to this item will be
- stored in the \c childItems private member variable. When the class's
- destructor is called, it must delete each of these to ensure that
- their memory is reused:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 1
-
- Since each of the child items are constructed when the model is initially
- populated with data, the function to add child items is straightforward:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 2
-
- Each item is able to return any of its child items when given a suitable
- row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram},
- the item marked with the letter "A" corresponds to the child of the root item
- with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1},
- and the "C" item is a child of the root item with \c{row = 1}.
-
- The \c child() function returns the child that corresponds to
- the specified row number in the item's list of child items:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 3
-
- The number of child items held can be found with \c childCount():
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 4
-
- The \c TreeModel uses this function to determine the number of rows that
- exist for a given parent item.
-
- The \c row() function reports the item's location within its parent's
- list of items:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 8
-
- Note that, although the root item (with no parent item) is automatically
- assigned a row number of 0, this information is never used by the model.
-
- The number of columns of data in the item is trivially returned by the
- \c columnCount() function.
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 5
-
- Column data is returned by the \c data() function, taking advantage of
- QList's ability to provide sensible default values if the column number
- is out of range:
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 6
-
- The item's parent is found with \c parent():
-
- \snippet examples/itemviews/simpletreemodel/treeitem.cpp 7
-
- Note that, since the root item in the model will not have a parent, this
- function will return zero in that case. We need to ensure that the model
- handles this case correctly when we implement the \c TreeModel::parent()
- function.
-
- \section1 TreeModel Class Definition
-
- The \c TreeModel class is defined as follows:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.h 0
-
- This class is similar to most other subclasses of QAbstractItemModel that
- provide read-only models. Only the form of the constructor and the
- \c setupModelData() function are specific to this model. In addition, we
- provide a destructor to clean up when the model is destroyed.
-
- \section1 TreeModel Class Implementation
-
- For simplicity, the model does not allow its data to be edited. As a
- result, the constructor takes an argument containing the data that the
- model will share with views and delegates:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 0
-
- It is up to the constructor to create a root item for the model. This
- item only contains vertical header data for convenience. We also use it
- to reference the internal data structure that contains the model data,
- and it is used to represent an imaginary parent of top-level items in
- the model.
-
- The model's internal data structure is populated with items by the
- \c setupModelData() function. We will examine this function separately
- at the end of this document.
-
- The destructor ensures that the root item and all of its descendants
- are deleted when the model is destroyed:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 1
-
- Since we cannot add data to the model after it is constructed and set
- up, this simplifies the way that the internal tree of items is managed.
-
- Models must implement an \c index() function to provide indexes for
- views and delegates to use when accessing data. Indexes are created
- for other components when they are referenced by their row and column
- numbers, and their parent model index. If an invalid model
- index is specified as the parent, it is up to the model to return an
- index that corresponds to a top-level item in the model.
-
- When supplied with a model index, we first check whether it is valid.
- If it is not, we assume that a top-level item is being referred to;
- otherwise, we obtain the data pointer from the model index with its
- \l{QModelIndex::internalPointer()}{internalPointer()} function and use
- it to reference a \c TreeItem object. Note that all the model indexes
- that we construct will contain a pointer to an existing \c TreeItem,
- so we can guarantee that any valid model indexes that we receive will
- contain a valid data pointer.
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 6
-
- Since the row and column arguments to this function refer to a
- child item of the corresponding parent item, we obtain the item using
- the \c TreeItem::child() function. The
- \l{QAbstractItemModel::createIndex()}{createIndex()} function is used
- to create a model index to be returned. We specify the row and column
- numbers, and a pointer to the item itself. The model index can be used
- later to obtain the item's data.
-
- The way that the \c TreeItem objects are defined makes writing the
- \c parent() function easy:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 7
-
- We only need to ensure that we never return a model index corresponding
- to the root item. To be consistent with the way that the \c index()
- function is implemented, we return an invalid model index for the
- parent of any top-level items in the model.
-
- When creating a model index to return, we must specify the row and
- column numbers of the parent item within its own parent. We can
- easily discover the row number with the \c TreeItem::row() function,
- but we follow a convention of specifying 0 as the column number of
- the parent. The model index is created with
- \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way
- as in the \c index() function.
-
- The \c rowCount() function simply returns the number of child items
- for the \c TreeItem that corresponds to a given model index, or the
- number of top-level items if an invalid index is specified:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 8
-
- Since each item manages its own column data, the \c columnCount()
- function has to call the item's own \c columnCount() function to
- determine how many columns are present for a given model index.
- As with the \c rowCount() function, if an invalid model index is
- specified, the number of columns returned is determined from the
- root item:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 2
-
- Data is obtained from the model via \c data(). Since the item manages
- its own columns, we need to use the column number to retrieve the data
- with the \c TreeItem::data() function:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 3
-
- Note that we only support the \l{Qt::ItemDataRole}{DisplayRole}
- in this implementation, and we also return invalid QVariant objects for
- invalid model indexes.
-
- We use the \c flags() function to ensure that views know that the
- model is read-only:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 4
-
- The \c headerData() function returns data that we conveniently stored
- in the root item:
-
- \snippet examples/itemviews/simpletreemodel/treemodel.cpp 5
-
- This information could have been supplied in a different way: either
- specified in the constructor, or hard coded into the \c headerData()
- function.
-
- \section1 Setting Up the Data in the Model
-
- We use the \c setupModelData() function to set up the initial data in
- the model. This function parses a text file, extracting strings of
- text to use in the model, and creates item objects that record both
- the data and the overall model structure.
- Naturally, this function works in a way that is very specific to
- this model. We provide the following description of its behavior,
- and refer the reader to the example code itself for more information.
-
- We begin with a text file in the following format:
-
- \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 0
- \dots
- \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 1
-
- We process the text file with the following two rules:
-
- \list
- \li For each pair of strings on each line, create an item (or node)
- in a tree structure, and place each string in a column of data
- in the item.
- \li When the first string on a line is indented with respect to the
- first string on the previous line, make the item a child of the
- previous item created.
- \endlist
-
- To ensure that the model works correctly, it is only necessary to
- create instances of \c TreeItem with the correct data and parent item.
-*/
diff --git a/doc/src/examples/simplewidgetmapper.qdoc b/doc/src/examples/simplewidgetmapper.qdoc
deleted file mode 100644
index 2b24dbcecd..0000000000
--- a/doc/src/examples/simplewidgetmapper.qdoc
+++ /dev/null
@@ -1,125 +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$
-**
-****************************************************************************/
-
-/*!
- \example itemviews/simplewidgetmapper
- \title Simple Widget Mapper Example
-
- The Simple Widget Mapper example shows how to use a widget mapper to display
- data from a model in a collection of widgets.
-
- \image simplewidgetmapper-example.png
-
- The QDataWidgetMapper class allows information obtained from a
- \l{Model Classes}{model} to be viewed and edited in a collection of
- widgets instead of in an \l{View Classes}{item view}.
- Any model derived from QAbstractItemModel can be used as the source of
- data and almost any input widget can be used to display it.
-
- The example itself is very simple: we create \c Window, a QWidget subclass
- that we use to hold the widgets used to present the data, and show it. The
- \c Window class will provide buttons that the user can click to show
- different records from the model.
-
- \section1 Window Class Definition
-
- The class provides a constructor, a slot to keep the buttons up to date,
- and a private function to set up the model:
-
- \snippet examples/itemviews/simplewidgetmapper/window.h Window definition
-
- In addition to the QDataWidgetMapper object and the controls used to make
- up the user interface, we use a QStandardItemModel to hold our data.
- We could use a custom model, but this standard implementation is sufficient
- for our purposes.
-
- \section1 Window Class Implementation
-
- The constructor of the \c Window class can be explained in three parts.
- In the first part, we set up the widgets used for the user interface:
-
- \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up widgets
-
- We also set up the buddy relationships between various labels and the
- corresponding input widgets.
-
- Next, we set up the widget mapper, relating each input widget to a column
- in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:
-
- \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the mapper
-
- We also connect the mapper to the \uicontrol{Next} and \uicontrol{Previous} buttons
- via its \l{QDataWidgetMapper::}{toNext()} and
- \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's
- \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the
- \c{updateButtons()} slot in the window which we'll show later.
-
- In the final part of the constructor, we set up the layout, placing each
- of the widgets in a grid (we could also use a QFormLayout for this):
-
- \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the layout
-
- Lastly, we set the window title and initialize the mapper by setting it to
- refer to the first row in the model.
-
- The model is initialized in the window's \c{setupModel()} function. Here,
- we create a standard model with 5 rows and 3 columns, and we insert some
- sample names, addresses and ages into each row:
-
- \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the model
-
- As a result, each row can be treated like a record in a database, and the
- widget mapper will read the data from each row, using the column numbers
- specified earlier to access the correct data for each widget. This is
- shown in the following diagram:
-
- \image widgetmapper-simple-mapping.png
-
- Since the user can navigate using the buttons in the user interface, the
- example is fully-functional at this point, but to make it a bit more
- user-friendly, we implement the \c{updateButtons()} slot to show when the
- user is viewing the first or last records:
-
- \snippet examples/itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons
-
- If the mapper is referring to the first row in the model, the \uicontrol{Previous}
- button is disabled. Similarly, the \uicontrol{Next} button is disabled if the
- mapper reaches the last row in the model.
-
- \section1 More Complex Mappings
-
- The QDataWidgetMapper class makes it easy to relate information from a
- model to widgets in a user interface. However, it is sometimes necessary
- to use input widgets which offer choices to the user, such as QComboBox,
- in conjunction with a widget mapper.
-
- In these situations, although the mapping to input widgets remains simple,
- more work needs to be done to expose additional data to the widget mapper.
- This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper}
- and \l{SQL Widget Mapper Example}{SQL Widget Mapper}
- examples.
-*/
diff --git a/doc/src/examples/sipdialog.qdoc b/doc/src/examples/sipdialog.qdoc
deleted file mode 100644
index b5f18cb4be..0000000000
--- a/doc/src/examples/sipdialog.qdoc
+++ /dev/null
@@ -1,127 +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$
-**
-****************************************************************************/
-
-/*!
- \example dialogs/sipdialog
- \title SIP Dialog Example
- \ingroup qtce
-
- The SIP Dialog example shows how to create a dialog that is aware of
- the Windows Mobile SIP (Software Input Panel) and reacts to it.
-
- \table
- \row \li \inlineimage sipdialog-closed.png
- \li \inlineimage sipdialog-opened.png
- \endtable
-
- Sometimes it is necessary for a dialog to take the SIP into account,
- as the SIP may hide important input widgets. The SIP Dialog Example
- shows how a \c Dialog object, \c dialog, can be resized accordingly
- if the SIP is opened, by embedding the contents of \c dialog in a
- QScrollArea.
-
- \section1 Dialog Class Definition
-
- The \c Dialog class is a subclass of QDialog that implements a public
- slot, \c desktopResized(), and a public function, \c reactToSIP(). Also,
- it holds a private instance of QRect, \c desktopGeometry.
-
- \snippet dialogs/sipdialog/dialog.h Dialog header
-
- \section1 Dialog Class Implementation
-
- In the constructor of \c Dialog, we start by obtaining the
- available geometry of the screen with
- \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The
- parameter used is \c 0 to indicate that we require the primary screen.
-
- \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1
-
- We set the window's title to "SIP Dialog Example" and declare a QScrollArea
- object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with
- \c scrollArea as its parent. The title of \c groupBox is also set to
- "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used
- as \c{groupBox}'s layout.
-
- We create a QLineEdit, a QLabel and a QPushButton and we set the
- \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels,
- respectively.
-
- \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2
-
- Also, all three widgets' text are set accordingly. The
- \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of
- \c gridLayout is set based on the height of \c desktopGeometry. This
- is to adapt to the different form factors of Windows Mobile. Then, we
- add our widgets to the layout.
-
- \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3
-
- The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout
- object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout
- is set to \c layout and the scroll area's horizontal scroll bar is turned
- off.
-
- \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4
-
- The following signals are connected to their respective slots:
- \list
- \li \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to
- \l{QApplication}'s \l{QApplication::closeAllWindows()}
- {closeAllWindows()} slot,
- \li \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()}
- {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot.
- \endlist
-
- \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5
-
- The \c desktopResized() function accepts an integer, \a screen,
- corresponding to the screen's index. We only invoke \c reactToSIP()
- if \a screen is the primary screen (e.g. index = 0).
-
- \snippet dialogs/sipdialog/dialog.cpp desktopResized() function
-
- The \c reactToSIP() function resizes \c dialog accordingly if the
- desktop's available geometry changed vertically, as this change signifies
- that the SIP may have been opened or closed.
-
- \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function
-
- If the height has decreased, we unset the maximized window state.
- Otherwise, we set the maximized window state. Lastly, we update
- \c desktopGeometry to the desktop's available geometry.
-
- \section1 The \c main() function
-
- The \c main() function for the SIP Dialog example instantiates \c Dialog
- and invokes its \l{QDialog::exec()}{exec()} function.
-
- \snippet dialogs/sipdialog/main.cpp main() function
-
- \note Although this example uses a dialog, the techniques used here apply to
- all top-level widgets respectively.
-*/
diff --git a/doc/src/examples/sliders.qdoc b/doc/src/examples/sliders.qdoc
deleted file mode 100644
index 383efc6140..0000000000
--- a/doc/src/examples/sliders.qdoc
+++ /dev/null
@@ -1,255 +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$
-**
-****************************************************************************/
-
-/*!
- \example widgets/sliders
- \title Sliders Example
-
- Qt provides three types of slider-like widgets: QSlider,
- QScrollBar and QDial. They all inherit most of their
- functionality from QAbstractSlider, and can in theory replace
- each other in an application since the differences only concern
- their look and feel. This example shows what they look like, how
- they work and how their behavior and appearance can be
- manipulated through their properties.
-
- The example also demonstrates how signals and slots can be used to
- synchronize the behavior of two or more widgets.
-
- \image sliders-example.png Screenshot of the Sliders example
-
- The Sliders example consists of two classes:
-
- \list
-
- \li \c SlidersGroup is a custom widget. It combines a QSlider, a
- QScrollBar and a QDial.
-
- \li \c Window is the main widget combining a QGroupBox and a
- QStackedWidget. In this example, the QStackedWidget provides a
- stack of two \c SlidersGroup widgets. The QGroupBox contain
- several widgets that control the behavior of the slider-like
- widgets.
-
- \endlist
-
- First we will review the \c Window class, then we
- will take a look at the \c SlidersGroup class.
-
- \section1 Window Class Definition
-
- \snippet examples/widgets/sliders/window.h 0
-
- The \c Window class inherits from QWidget. It displays the slider
- widgets and allows the user to set their minimum, maximum and
- current values and to customize their appearance, key bindings
- and orientation. We use a private \c createControls() function to
- create the widgets that provide these controlling mechanisms and
- to connect them to the slider widgets.
-
- \section1 Window Class Implementation
-
- \snippet examples/widgets/sliders/window.cpp 0
-
- In the constructor we first create the two \c SlidersGroup
- widgets that display the slider widgets horizontally and
- vertically, and add them to the QStackedWidget. QStackedWidget
- provides a stack of widgets where only the top widget is visible.
- With \c createControls() we create a connection from a
- controlling widget to the QStackedWidget, making the user able to
- choose between horizontal and vertical orientation of the slider
- widgets. The rest of the controlling mechanisms is implemented by
- the same function call.
-
- \snippet examples/widgets/sliders/window.cpp 1
- \snippet examples/widgets/sliders/window.cpp 2
-
- Then we connect the \c horizontalSliders, \c verticalSliders and
- \c valueSpinBox to each other, so that the slider widgets and the
- control widget will behave synchronized when the current value of
- one of them changes. The \c valueChanged() signal is emitted with
- the new value as argument. The \c setValue() slot sets the
- current value of the widget to the new value, and emits \c
- valueChanged() if the new value is different from the old one.
-
- We put the group of control widgets and the stacked widget in a
- horizontal layout before we initialize the minimum, maximum and
- current values. The initialization of the current value will
- propagate to the slider widgets through the connection we made
- between \c valueSpinBox and the \c SlidersGroup widgets. The
- minimum and maximum values propagate through the connections we
- created with \c createControls().
-
- \snippet examples/widgets/sliders/window.cpp 3
- \snippet examples/widgets/sliders/window.cpp 4
-
- In the private \c createControls() function, we let a QGroupBox
- (\c controlsGroup) display the control widgets. A group box can
- provide a frame, a title and a keyboard shortcut, and displays
- various other widgets inside itself. The group of control widgets
- is composed by two checkboxes, three spin boxes (with labels) and
- one combobox.
-
- After creating the labels, we create the two checkboxes.
- Checkboxes are typically used to represent features in an
- application that can be enabled or disabled. When \c
- invertedAppearance is enabled, the slider values are inverted.
- The table below shows the appearance for the different
- slider-like widgets:
-
- \table
- \header \li \li{2,1} QSlider \li{2,1} QScrollBar \li{2,1} QDial
- \header \li \li Normal \li Inverted \li Normal \li Inverted \li Normal \li Inverted
- \row \li Qt::Horizontal \li Left to right \li Right to left \li Left to right \li Right to left \li Clockwise \li Counterclockwise
- \row \li Qt::Vertical \li Bottom to top \li Top to bottom \li Top to bottom \li Bottom to top \li Clockwise \li Counterclockwise
- \endtable
-
- It is common to invert the appearance of a vertical QSlider. A
- vertical slider that controls volume, for example, will typically
- go from bottom to top (the non-inverted appearance), whereas a
- vertical slider that controls the position of an object on screen
- might go from top to bottom, because screen coordinates go from
- top to bottom.
-
- When the \c invertedKeyBindings option is enabled (corresponding
- to the QAbstractSlider::invertedControls property), the slider's
- wheel and key events are inverted. The normal key bindings mean
- that scrolling the mouse wheel "up" or using keys like page up
- will increase the slider's current value towards its maximum.
- Inverted, the same wheel and key events will move the value
- toward the slider's minimum. This can be useful if the \e
- appearance of a slider is inverted: Some users might expect the
- keys to still work the same way on the value, whereas others
- might expect \uicontrol PageUp to mean "up" on the screen.
-
- Note that for horizontal and vertical scroll bars, the key
- bindings are inverted by default: \uicontrol PageDown increases the
- current value, and \uicontrol PageUp decreases it.
-
- \snippet examples/widgets/sliders/window.cpp 5
- \snippet examples/widgets/sliders/window.cpp 6
-
- Then we create the spin boxes. QSpinBox allows the user to choose
- a value by clicking the up and down buttons or pressing the \key
- Up and \uicontrol Down keys on the keyboard to modify the value
- currently displayed. The user can also type in the value
- manually. The spin boxes control the minimum, maximum and current
- values for the QSlider, QScrollBar, and QDial widgets.
-
- We create a QComboBox that allows the user to choose the
- orientation of the slider widgets. The QComboBox widget is a
- combined button and popup list. It provides a means of presenting
- a list of options to the user in a way that takes up the minimum
- amount of screen space.
-
- \snippet examples/widgets/sliders/window.cpp 7
- \snippet examples/widgets/sliders/window.cpp 8
-
- We synchronize the behavior of the control widgets and the slider
- widgets through their signals and slots. We connect each control
- widget to both the horizontal and vertical group of slider
- widgets. We also connect \c orientationCombo to the
- QStackedWidget, so that the correct "page" is shown. Finally, we
- lay out the control widgets in a QGridLayout within the \c
- controlsGroup group box.
-
- \section1 SlidersGroup Class Definition
-
- \snippet examples/widgets/sliders/slidersgroup.h 0
-
- The \c SlidersGroup class inherits from QGroupBox. It provides a
- frame and a title, and contains a QSlider, a QScrollBar and a
- QDial.
-
- We provide a \c valueChanged() signal and a public \c setValue()
- slot with equivalent functionality to the ones in QAbstractSlider
- and QSpinBox. In addition, we implement several other public
- slots to set the minimum and maximum value, and invert the slider
- widgets' appearance as well as key bindings.
-
- \section1 SlidersGroup Class Implementation
-
- \snippet examples/widgets/sliders/slidersgroup.cpp 0
-
- First we create the slider-like widgets with the appropriate
- properties. In particular we set the focus policy for each
- widget. Qt::FocusPolicy is an enum type that defines the various
- policies a widget can have with respect to acquiring keyboard
- focus. The Qt::StrongFocus policy means that the widget accepts
- focus by both tabbing and clicking.
-
- Then we connect the widgets with each other, so that they will
- stay synchronized when the current value of one of them changes.
-
- \snippet examples/widgets/sliders/slidersgroup.cpp 1
- \snippet examples/widgets/sliders/slidersgroup.cpp 2
-
- We connect \c {dial}'s \c valueChanged() signal to the
- \c{SlidersGroup}'s \c valueChanged() signal, to notify the other
- widgets in the application (i.e., the control widgets) of the
- changed value.
-
- \snippet examples/widgets/sliders/slidersgroup.cpp 3
- \codeline
- \snippet examples/widgets/sliders/slidersgroup.cpp 4
-
- Finally, depending on the \l {Qt::Orientation}{orientation} given
- at the time of construction, we choose and create the layout for
- the slider widgets within the group box.
-
- \snippet examples/widgets/sliders/slidersgroup.cpp 5
- \snippet examples/widgets/sliders/slidersgroup.cpp 6
-
- The \c setValue() slot sets the value of the QSlider. We don't
- need to explicitly call
- \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and
- QDial widgets, since QSlider will emit the
- \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when
- its value changes, triggering a domino effect.
-
- \snippet examples/widgets/sliders/slidersgroup.cpp 7
- \snippet examples/widgets/sliders/slidersgroup.cpp 8
- \codeline
- \snippet examples/widgets/sliders/slidersgroup.cpp 9
- \snippet examples/widgets/sliders/slidersgroup.cpp