806dda08d6
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>
443 lines
17 KiB
Plaintext
443 lines
17 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** 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
|
|
*/
|