Changeset 561 for trunk/doc/src/tutorials/addressbook.qdoc

Timestamp:

Feb 11, 2010, 11:19:06 PM (15 years ago)

Author:

Dmitry A. Kuminov

Message:

trunk: Merged in qt 4.6.1 sources.

Location:

trunk

Files:

• . (modified) (1 prop)
• doc/src/tutorials/addressbook.qdoc (modified) (24 diffs)

trunk/doc/src/tutorials/addressbook.qdoc

@@ -2 +2 @@
 **
 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
-** Contact: Qt Software Information (qt-info@nokia.com)
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -21 +22 @@
 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
-** In addition, as a special exception, Nokia gives you certain
-** additional rights. These rights are described in the Nokia Qt LGPL
-** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
-** package.
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 **
 ** GNU General Public License Usage
@@ -34 +34 @@
 ** met: http://www.gnu.org/copyleft/gpl.html.
 **
-** If you are unsure which license is appropriate for your use, please
-** contact the sales department at qt-sales@nokia.com.
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
 ** $QT_END_LICENSE$
 **
@@ -44 +44 @@
 
     \startpage {index.html}{Qt Reference Documentation}
+    \contentspage Tutorials
     \nextpage {tutorials/addressbook/part1}{Chapter 1}
 
     \title Address Book Tutorial
-    \ingroup howto
-    \ingroup tutorials
     \brief An introduction to GUI programming, showing how to put together a
     simple yet fully-functioning application.
@@ -223 +222 @@
     Notice that \c addressLabel is positioned using Qt::AlignTop as an
     additional argument. This is to make sure it is not vertically centered in
-    cell (1,0). For a basic overview on Qt Layouts, refer to the \l{Layout Classes}
-    document.
+    cell (1,0). For a basic overview on Qt Layouts, refer to the 
+    \l{Layout Management} documentation.
 
     In order to install the layout object onto the widget, we have to invoke
@@ -243 +242 @@
     \snippet tutorials/addressbook/part1/main.cpp main function
 
-    We construct a new \c AddressBook widget on the heap using the \c new
-    keyword and invoke its \l{QWidget::show()}{show()} function to display it.
+    We construct a new \c AddressBook widget on the stack and invoke
+    its \l{QWidget::show()}{show()} function to display it.
     However, the widget will not be shown until the application's event loop
     is started. We start the event loop by calling the application's
     \l{QApplication::}{exec()} function; the result returned by this function
-    is used as the return value from the \c main() function.
+    is used as the return value from the \c main() function. At this point,
+    it becomes apparent why we instanciated \c AddressBook on the stack: It
+    will now go out of scope. Therefore, \c AddressBook and all its child widgets
+    will be deleted, thus preventing memory leaks.
 */
 
@@ -297 +299 @@
     We also declare two private QString objects, \c oldName and \c oldAddress.
     These objects are needed to hold the name and address of the contact that
-    was last displayed, before the user clicked "Add". So, when the user clicks
-    "Cancel", we can revert to displaying the details of the last contact.
+    was last displayed, before the user clicked \gui Add. So, when the user clicks
+    \gui Cancel, we can revert to displaying the details of the last contact.
 
     \section1 Implementing the AddressBook Class
@@ -304 +306 @@
     Within the constructor of \c AddressBook, we set the \c nameLine and
     \c addressText to read-only, so that we can only display but not edit
-    existing cotact details.
+    existing contact details.
 
     \dots
@@ -319 +321 @@
     {show()} function, while the \c submitButton and \c cancelButton are
     hidden by invoking \l{QPushButton::hide()}{hide()}. These two push
-    buttons will only be displayed when the user clicks "Add" and this is
+    buttons will only be displayed when the user clicks \gui Add and this is
     handled by the \c addContact() function discussed below.
 
@@ -363 +365 @@
     \o We extract the contact's details from \c nameLine and \c addressText
     and store them in QString objects. We also validate to make sure that the
-    user did not click "Submit" with empty input fields; otherwise, a
+    user did not click \gui Submit with empty input fields; otherwise, a
     QMessageBox is displayed to remind the user for a name and address.
 
@@ -375 +377 @@
 
     If the contact already exists, again, we display a QMessageBox to inform
-    the user about this, to prevent the user from adding duplicate contacts.
-    Our \c contacts object is based on key-value pairs of name and addresses,
+    the user about this, preventing the user from adding duplicate contacts.
+    Our \c contacts object is based on key-value pairs of name and address,
     hence, we want to ensure that \e key is unique.
 
@@ -397 +399 @@
     \snippet tutorials/addressbook/part2/addressbook.cpp cancel
 
-    The general idea to add a contact is to give the user the flexibility to
-    click "Submit" or "Cancel" at any time. The flowchart below further
-    explains this concept:
+    The general idea behind adding a contact is to give the user the
+    flexibility to click \gui Submit or \gui Cancel at any time. The flowchart below
+    further explains this concept:
 
     \image addressbook-tutorial-part2-add-flowchart.png
@@ -455 +457 @@
 
     The image below is our expected graphical user interface. Notice that it
-    is getting closer to our expected final output.
+    is getting closer to our final application.
 
     \image addressbook-tutorial-part3-screenshot.png
@@ -511 +513 @@
         \o If the iterator is at the end of \c contacts, we clear the
         display and return.
-        \o If the iterator is the beginning of \c contacts, we move it to
+        \o If the iterator is at the beginning of \c contacts, we move it to
         the end.
         \o We then decrement the iterator by one.
@@ -530 +532 @@
     \title Address Book 4 - Editing and Removing Addresses
 
-    In this chapter, we look at ways to modify the contents of contact stored
+    In this chapter, we look at ways to modify the contents of contacts stored
     in the address book application.
 
@@ -540 +542 @@
     when needed. However, this requires a little improvement, in the form of
     enums. In our previous chapters, we had two modes: \c{AddingMode} and
-    \c{NavigationMode} - but they weren't defined as enums. Instead, we
+    \c{NavigationMode} - but they were not defined as enums. Instead, we
     enabled and disabled the corresponding buttons manually, resulting in
     multiple lines of repeated code.
@@ -574 +576 @@
     \snippet tutorials/addressbook/part4/addressbook.h mode declaration
 
-    Lastly, we declare \c currentMode to keep track of the current mode of the
-    enum.
+    Lastly, we declare \c currentMode to keep track of the enum's current mode.
 
     \section1 Implementing the AddressBook Class
@@ -645 +646 @@
     \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1
 
-    For \c NavigationMode, however, we include conditions within the
-    parameters of the QPushButton::setEnabled(). This is to ensure that
-    the \c editButton and \c removeButton push buttons are enabled when there
-    is at least one contact in the address book; \c nextButton and \c previousButton
-    are only enabled when there is more than one contact in the address book.
+    For \c NavigationMode, however, we include conditions within the parameters
+    of the QPushButton::setEnabled() function. This is to ensure that
+    \c editButton and \c removeButton are enabled when there is at least one
+    contact in the address book; \c nextButton and \c previousButton are only
+    enabled when there is more than one contact in the address book.
 
     \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2
@@ -696 +697 @@
     \snippet tutorials/addressbook/part5/finddialog.h FindDialog header
 
-    We define a public function, \c getFindText() for use by classes that
-    instantiate \c FindDialog, which allows them to obtain the text
-    entered by the user. A public slot, \c findClicked(), is defined to
-    handle the search string when the user clicks the \gui Find button.
+    We define a public function, \c getFindText(), to be used by classes that
+    instantiate \c FindDialog. This function allows these classes to obtain the
+    search string entered by the user. A public slot, \c findClicked(), is also
+    defined to handle the search string when the user clicks the \gui Find
+    button.
 
     Lastly, we define the private variables, \c findButton, \c lineEdit
@@ -714 +716 @@
     \snippet tutorials/addressbook/part5/finddialog.cpp constructor
 
-    We set the layout and window title, as well as connect the signals
-    to their respective slots. Notice that \c{findButton}'s
-    \l{QPushButton::clicked()}{clicked()} signal is connected to to
-    \c findClicked() and \l{QDialog::accept()}{accept()}. The
-    \l{QDialog::accept()}{accept()} slot provided by QDialog hides
-    the dialog and sets the result code to \l{QDialog::}{Accepted}.
-    We use this function to help \c{AddressBook}'s \c findContact() function
-    know when the \c FindDialog object has been closed. This will be
-    further explained when discussing the \c findContact() function.
+    We set the layout and window title, as well as connect the signals to their
+    respective slots. Notice that \c{findButton}'s \l{QPushButton::clicked()}
+    {clicked()} signal is connected to to \c findClicked() and
+    \l{QDialog::accept()}{accept()}. The \l{QDialog::accept()}{accept()} slot
+    provided by QDialog hides the dialog and sets the result code to
+    \l{QDialog::}{Accepted}. We use this function to help \c{AddressBook}'s
+    \c findContact() function know when the \c FindDialog object has been
+    closed. We will explain this logic in further detail when discussing the
+    \c findContact() function.
 
     \image addressbook-tutorial-part5-signals-and-slots.png
@@ -816 +818 @@
     \image addressbook-tutorial-part6-screenshot.png
 
-    Although browsing and searching for contacts are useful features, our address
-    book is not really fully ready for use until we can saving existing contacts
-    and load them again at a later time.
-    Qt provides a number of classes for \l{Input/Output and Networking}{input and output},
-    but we have chosen to use two which are simple to use in combination: QFile and
-    QDataStream.
-
-    A QFile object represents a file on disk that can be read from and written to.
-    QFile is a subclass of the more general QIODevice class which represents many
-    different kinds of devices.
-
-    A QDataStream object is used to serialize binary data so that it can be stored
-    in a QIODevice and retrieved again later. Reading from a QIODevice and writing
-    to it is as simple as opening the stream - with the respective device as a
-    parameter - and reading from or writing to it.
+    Although browsing and searching for contacts are useful features, our
+    address book is not ready for use until we can save existing contacts and
+    load them again at a later time.
+
+    Qt provides a number of classes for \l{Input/Output and Networking}
+    {input and output}, but we have chosen to use two which are simple to use
+    in combination: QFile and QDataStream.
+
+    A QFile object represents a file on disk that can be read from and written
+    to. QFile is a subclass of the more general QIODevice class which
+    represents many different kinds of devices.
+
+    A QDataStream object is used to serialize binary data so that it can be
+    stored in a QIODevice and retrieved again later. Reading from a QIODevice
+    and writing to it is as simple as opening the stream - with the respective
+    device as a parameter - and reading from or writing to it.
+
 
     \section1 Defining the AddressBook Class
@@ -872 +876 @@
     \image addressbook-tutorial-part6-save.png
 
-    If \c fileName is not empty, we create a QFile object, \c file with
+    If \c fileName is not empty, we create a QFile object, \c file, with
     \c fileName. QFile works with QDataStream as QFile is a QIODevice.
 
@@ -902 +906 @@
 
     If \c fileName is not empty, again, we use a QFile object, \c file, and
-    attempt to open it in \l{QIODevice::}{ReadOnly} mode. In a similar way
-    to our implementation of \c saveToFile(), if this attempt is unsuccessful,
-    we display a QMessageBox to inform the user.
+    attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our
+    implementation of \c saveToFile(), if this attempt is unsuccessful, we
+    display a QMessageBox to inform the user.
 
     \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2
@@ -910 +914 @@
     Otherwise, we instantiate a QDataStream object, \c in, set its version as
     above and read the serialized data into the \c contacts data structure.
-    Note that we empty \c contacts before reading data into it to simplify the
-    file reading process. A more advanced method would be to read the contacts
-    into temporary QMap object, and copy only the contacts that do not already
-    exist in \c contacts.
+    The \c contacts object is emptied before data is read into it to simplify
+    the file reading process. A more advanced method would be to read the
+    contacts into a temporary QMap object, and copy over non-duplicate contacts
+    into \c contacts.
 
     \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3