Ignore:
Timestamp:
May 5, 2011, 5:36:53 AM (14 years ago)
Author:
Dmitry A. Kuminov
Message:

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

Location:
trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk

  • trunk/doc/src/tutorials/addressbook.qdoc

    r651 r846  
    11/****************************************************************************
    22**
    3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
     3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
    44** All rights reserved.
    55** Contact: Nokia Corporation (qt-info@nokia.com)
    … …  
    77** This file is part of the documentation of the Qt Toolkit.
    88**
    9 ** $QT_BEGIN_LICENSE:LGPL$
     9** $QT_BEGIN_LICENSE:FDL$
    1010** Commercial Usage
    1111** Licensees holding valid Qt Commercial licenses may use this file in
    1212** accordance with the Qt Commercial License Agreement provided with the
    13 ** Software or, alternatively, in accordance with the terms contained in
    14 ** a written agreement between you and Nokia.
     13** Software or, alternatively, in accordance with the terms contained in a
     14** written agreement between you and Nokia.
    1515**
    16 ** GNU Lesser General Public License Usage
    17 ** Alternatively, this file may be used under the terms of the GNU Lesser
    18 ** General Public License version 2.1 as published by the Free Software
    19 ** Foundation and appearing in the file LICENSE.LGPL included in the
    20 ** packaging of this file.  Please review the following information to
    21 ** ensure the GNU Lesser General Public License version 2.1 requirements
    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
    23 **
    24 ** In addition, as a special exception, Nokia gives you certain additional
    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
    27 **
    28 ** GNU General Public License Usage
    29 ** Alternatively, this file may be used under the terms of the GNU
    30 ** General Public License version 3.0 as published by the Free Software
    31 ** Foundation and appearing in the file LICENSE.GPL included in the
    32 ** packaging of this file.  Please review the following information to
    33 ** ensure the GNU General Public License version 3.0 requirements will be
    34 ** met: http://www.gnu.org/copyleft/gpl.html.
     16** GNU Free Documentation License
     17** Alternatively, this file may be used under the terms of the GNU Free
     18** Documentation License version 1.3 as published by the Free Software
     19** Foundation and appearing in the file included in the packaging of this
     20** file.
    3521**
    3622** If you have questions regarding the use of this file, please contact
    … …  
    4329    \page tutorials-addressbook.html
    4430
    45     \startpage {index.html}{Qt Reference Documentation}
    46     \contentspage Tutorials
    47     \nextpage {tutorials/addressbook/part1}{Chapter 1}
    48 
    4931    \title Address Book Tutorial
    5032    \brief An introduction to GUI programming, showing how to put together a
    5133    simple yet fully-functioning application.
    5234
    53     This tutorial gives an introduction to GUI programming using the Qt
     35    This tutorial is an introduction to GUI programming with the Qt
    5436    cross-platform framework.
    5537
    … …  
    6244    \endomit
    6345
    64     In the process, we will learn about some basic technologies provided by Qt,
    65     such as
     46    In this tutorial, you will learn about some of the basic
     47    components of Qt, including:
    6648
    6749    \list
    … …  
    7254    \endlist
    7355
    74     If you are completely new to Qt, please read \l{How to Learn Qt} if you
    75     have not already done so.
    76 
    77     The tutorial's source code is located in Qt's \c examples/tutorials/addressbook
    78     directory.
    79 
    80     Tutorial chapters:
     56    If you are new to Qt, we recommend reading \l{How to Learn Qt} first.
     57
     58    Tutorial contents:
    8159
    8260    \list 1
    … …  
    9068    \endlist
    9169
    92     Although this little application does not look much like a fully-fledged
    93     modern GUI application, it uses many of the basic techniques that are used
    94     in more complex applications. After you have worked through it, we
    95     recommend checking out the \l{mainwindows/application}{Application}
    96     example, which presents a small GUI application, with menus, toolbars, a
    97     status bar, and so on.
     70    The tutorial source code is located in \c{examples/tutorials/addressbook}.
     71
     72    Although this little application does not look much like a
     73    fully-fledged modern GUI application, it uses many of the basic
     74    elements that are used in more complex applications. After you
     75    have worked through this tutorial, we recommend reading the
     76    \l{mainwindows/application}{Application} example, which presents a
     77    small GUI application, with menus, toolbars, a status bar, and so
     78    on. 
    9879*/
    9980
    10081/*!
    10182    \page tutorials-addressbook-part1.html
    102     \contentspage {Address Book Tutorial}{Contents}
    103     \nextpage {tutorials/addressbook/part2}{Chapter 2}
     83
    10484    \example tutorials/addressbook/part1
    105     \title Address Book 1 - Designing the User Interface
    106 
    107     The first part of this tutorial covers the design of the basic graphical
    108     user interface (GUI) we use for the Address Book application.
    109 
    110     The first step to creating a GUI program is to design the user interface.
    111     In this chapter, our goal is to set up the labels and input fields needed
    112     to implement a basic address book application. The figure below is a
    113     screenshot of our expected output.
     85    \title Part 1 - Designing the User Interface
     86
     87    This first part covers the design of the basic graphical user
     88    interface (GUI) for our address book application.
     89
     90    The first step in creating a GUI program is to design the user
     91    interface.  Here the our goal is to set up the labels and input
     92    fields to implement a basic address book. The figure below is a
     93    screenshot of the expected output.
    11494
    11595    \image addressbook-tutorial-part1-screenshot.png
    … …  
    170150    \snippet tutorials/addressbook/part1/addressbook.h class definition
    171151
    172     The class holds declarations of \c nameLine and \c addressText, the
    173     private instances of QLineEdit and QTextEdit mentioned earlier.
    174     You will see, in the coming chapters, that data stored in \c nameLine and
    175     \c addressText is needed for many of the address book's functions.
    176 
    177     We do not need to include declarations of the QLabel objects we will use
    178     because we will not need to reference them once they have been created.
    179     The way Qt tracks the ownership of objects is explained in the next section.
     152    The class holds declarations of \c nameLine and \c addressText,
     153    the private instances of QLineEdit and QTextEdit mentioned
     154    earlier.  The data stored in \c nameLine and \c addressText will
     155    be needed for many of the address book functions.
     156
     157    We don't include declarations of the QLabel objects we will use
     158    because we will not need to reference them once they have been
     159    created.  The way Qt tracks the ownership of objects is explained
     160    in the next section.
    180161
    181162    The Q_OBJECT macro itself implements some of the more advanced features of Qt.
    … …  
    196177    \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields
    197178
    198     Within this constructor, we declare and instantiate two local QLabel objects,
    199     \c nameLabel and \c addressLabel, as well as instantiate \c nameLine and
    200     \c addressText. The
    201     \l{QObject::tr()}{tr()} function returns a translated version of the
    202     string, if there is one available; otherwise, it returns the string itself.
    203     Think of this function as an \c{<insert translation here>} marker to mark
    204     QString objects for translation. You will notice, in the coming chapters as
    205     well as in the \l{Qt Examples}, that we include it whenever we use a
    206     translatable string.
     179    In this constructor, the QLabel objects \c nameLabel and \c
     180    addressLabel are instantiated, as well as \c nameLine and \c
     181    addressText. The \l{QObject::tr()}{tr()} function returns a
     182    translated version of the string, if there is one
     183    available. Otherwise it returns the string itself. This function
     184    marks its QString parameter as one that should be translated into
     185    other languages. It should be used wherever a translatable string
     186    appears.
    207187
    208188    When programming with Qt, it is useful to know how layouts work.
    … …  
    255235/*!
    256236    \page tutorials-addressbook-part2.html
    257     \previouspage Address Book 1 - Designing the User Interface
    258     \contentspage {Address Book Tutorial}{Contents}
    259     \nextpage {tutorials/addressbook/part3}{Chapter 3}
     237
    260238    \example tutorials/addressbook/part2
    261     \title Address Book 2 - Adding Addresses
    262 
    263     The next step to creating our basic address book application is to allow
    264     a little bit of user interaction.
     239    \title Part 2 - Adding Addresses
     240
     241    The next step in creating the address book is to implement some
     242    user interactions.
    265243
    266244    \image addressbook-tutorial-part2-add-contact.png
    … …  
    284262    to the \l{Signals and Slots} document.
    285263
    286     Three QPushButton objects: \c addButton, \c submitButton and
    287     \c cancelButton, are now included in our private variable declarations,
    288     along with \c nameLine and \c addressText from the last chapter.
     264    Three QPushButton objects (\c addButton, \c submitButton, and
     265    \c cancelButton) are now included in our private variable declarations,
     266    along with \c nameLine and \c addressText.
    289267
    290268    \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration
    … …  
    408386/*!
    409387    \page tutorials-addressbook-part3.html
    410     \previouspage Address Book 2 - Adding Addresses
    411     \contentspage {Address Book Tutorial}{Contents}
    412     \nextpage {tutorials/addressbook/part4}{Chapter 4}
     388
    413389    \example tutorials/addressbook/part3
    414     \title Address Book 3 - Navigating between Entries
    415 
    416     The address book application is now half complete. We need to add some
    417     functions to navigate between contacts. But first, we have to decide
    418     what sort of a data structure we would like to use to hold these contacts.
    419 
    420     In Chapter 2, we used a QMap of key-value pairs with the contact's name
    421     as the \e key, and the contact's address as the \e value. This works well
    422     for our case. However, in order to navigate and display each entry, a
    423     little bit of enhancement is needed.
     390    \title Part 3 - Navigating between Entries
     391
     392    The address book is now about half complete. We should add the
     393    capability to navigate among the contacts, but first we must
     394    decide what sort of a data structure we need for containing these
     395    contacts.
     396
     397    In the previous section, we used a QMap of key-value pairs with
     398    the contact's name as the \e key, and the contact's address as the
     399    \e value. This works well for our case. However, in order to
     400    navigate and display each entry, a little bit of enhancement is
     401    needed.
    424402
    425403    We enhance the QMap by making it replicate a data structure similar to a
    … …  
    432410    \section1 Defining the AddressBook Class
    433411
    434     In order to add navigation functions to the address book application, we
    435     need to add two more slots to our \c AddressBook class: \c next() and
    436     \c previous(). These are added to our \c addressbook.h file:
     412    To add navigation functions to the address book, we must add two
     413    more slots to the \c AddressBook class: \c next() and \c
     414    previous() to the \c addressbook.h file:
    437415
    438416    \snippet tutorials/addressbook/part3/addressbook.h navigation functions
    … …  
    456434    \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals
    457435
    458     The image below is our expected graphical user interface. Notice that it
    459     is getting closer to our final application.
     436    The image below is the expected graphical user interface.
    460437
    461438    \image addressbook-tutorial-part3-screenshot.png
    … …  
    526503/*!
    527504    \page tutorials-addressbook-part4.html
    528     \previouspage Address Book 3 - Navigating between Entries
    529     \contentspage {Address Book Tutorial}{Contents}
    530     \nextpage {tutorials/addressbook/part5}{Chapter 5}
     505
    531506    \example tutorials/addressbook/part4
    532     \title Address Book 4 - Editing and Removing Addresses
    533 
    534     In this chapter, we look at ways to modify the contents of contacts stored
    535     in the address book application.
     507    \title Part 4 - Editing and Removing Addresses
     508
     509    Now we look at ways to modify the contents of contacts stored in
     510    the address book.
    536511
    537512    \image addressbook-tutorial-screenshot.png
    538513
    539     We now have an address book that not only holds contacts in an organized
    540     manner, but also allows navigation. It would be convenient to include
    541     edit and remove functions so that a contact's details can be changed
    542     when needed. However, this requires a little improvement, in the form of
    543     enums. In our previous chapters, we had two modes: \c{AddingMode} and
    544     \c{NavigationMode} - but they were not defined as enums. Instead, we
    545     enabled and disabled the corresponding buttons manually, resulting in
    546     multiple lines of repeated code.
    547 
    548     In this chapter, we define the \c Mode enum with three different values:
     514    We now have an address book that not only holds contacts in an
     515    organized manner, but also allows navigation. It would be
     516    convenient to include edit and remove functions so that a
     517    contact's details can be changed when needed. However, this
     518    requires a little improvement, in the form of enums. We defined
     519    two modes: \c{AddingMode} and \c{NavigationMode}, but they were
     520    not defined as enum values. Instead, we enabled and disabled the
     521    corresponding buttons manually, resulting in multiple lines of
     522    repeated code.
     523
     524    Here we define the \c Mode enum with three different values:
    549525
    550526    \list
    … …  
    580556    \section1 Implementing the AddressBook Class
    581557
    582     We now have to implement the mode-changing features of the address book
    583     application. The \c editButton and \c removeButton are instantiated and
    584     disabled by default, as the address book starts up with zero contacts in
    585     memory.
     558    We now implement the mode-changing features of the address
     559    book. The \c editButton and \c removeButton are instantiated and
     560    disabled by default. The address book starts with zero contacts
     561    in memory.
    586562
    587563    \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons
    … …  
    654630    \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2
    655631
    656     By performing the task of setting the mode and updating the user interface in
    657     the same function, we avoid the possibility of the user interface getting "out
    658     of sync" with the internal state of the application.
    659 */
     632    By setting the mode and updating the user interface in the same
     633    function, we avoid the possibility of the user interface getting
     634    out of sync with the internal state of the application.
     635  */
    660636
    661637/*!
    662638    \page tutorials-addressbook-part5.html
    663     \previouspage Address Book 4 - Editing and Removing Addresses
    664     \contentspage {Address Book Tutorial}{Contents}
    665     \nextpage {tutorials/addressbook/part6}{Chapter 6}
     639
    666640    \example tutorials/addressbook/part5
    667     \title Address Book 5 - Adding a Find Function
    668 
    669     In this chapter, we look at ways to locate contacts and addresses in
    670     the address book application.
     641    \title Part 5 - Adding a Find Function
     642
     643    Here we look at ways to locate contacts and addresses in the
     644    address book.
    671645
    672646    \image addressbook-tutorial-part5-screenshot.png
    673647
    674     As we keep adding contacts to our address book application, it becomes
    675     tedious to navigate them with the \e Next and \e Previous buttons. In this
    676     case, a \e Find function would be more efficient in looking up contacts.
    677     The screenshot above shows the \e Find button and its position on the panel
    678     of buttons.
    679 
    680     When the user clicks on the \e Find button, it is useful to display a
    681     dialog that can prompt the user for a contact's name. Qt provides QDialog,
    682     which we subclass in this chapter, to implement a \c FindDialog class.
     648    As we add contacts to our address book, it becomes tedious to
     649    navigate the list with the \e Next and \e Previous buttons. A \e
     650    Find function would be more efficient.  The screenshot above shows
     651    the \e Find button and its position on the panel of buttons.
     652
     653    When the user clicks on the \e Find button, it is useful to
     654    display a dialog that prompts for a contact's name. Qt provides
     655    QDialog, which we subclass here to implement a \c FindDialog
     656    class.
    683657
    684658    \section1 Defining the FindDialog Class
    … …  
    807781/*!
    808782    \page tutorials-addressbook-part6.html
    809     \previouspage Address Book 5 - Adding a Find Function
    810     \contentspage {Address Book Tutorial}{Contents}
    811     \nextpage {tutorials/addressbook/part7}{Chapter 7}
     783
    812784    \example tutorials/addressbook/part6
    813     \title Address Book 6 - Loading and Saving
    814 
    815     This chapter covers the file handling features of Qt that we use to write
    816     loading and saving routines for the address book application.
     785    \title Part 6 - Loading and Saving
     786
     787    This part covers the Qt file handling features we use to write
     788    loading and saving routines for the address book.
    817789
    818790    \image addressbook-tutorial-part6-screenshot.png
    819791
    820     Although browsing and searching for contacts are useful features, our
    821     address book is not ready for use until we can save existing contacts and
    822     load them again at a later time.
     792    Although browsing and searching the contact list are useful
     793    features, our address book is not complete until we can save
     794    existing contacts and load them again at a later time.
    823795
    824796    Qt provides a number of classes for \l{Input/Output and Networking}
    … …  
    931903/*!
    932904    \page tutorials-addressbook-part7.html
    933     \previouspage Address Book 6 - Loading and Saving
    934     \contentspage {Address Book Tutorial}{Contents}
     905
    935906    \example tutorials/addressbook/part7
    936     \title Address Book 7 - Additional Features
    937 
    938     This chapter covers some additional features that make the address book
    939     application more convenient for everyday use.
     907    \title Part 7 - Additional Features
     908
     909    This part covers some additional features that make the address
     910    book more convenient for the frequent user.
    940911
    941912    \image addressbook-tutorial-part7-screenshot.png
    942913
    943     Although our address book application is useful in its own right, it would
    944     be useful if we could exchange contact data with other applications.
    945     The vCard format is a popular file format that can be used for this purpose.
    946     In this chapter, we extend our address book client to allow contacts to
    947     be exported to vCard \c{.vcf} files.
     914    Although our address book is useful in isolation, it would be
     915    better if we could exchange contact data with other applications.
     916    The vCard format is a popular file format that can be used for
     917    this purpose.  Here we extend our address book client to allow
     918    contacts to be exported to vCard \c{.vcf} files.
    948919
    949920    \section1 Defining the AddressBook Class
Note: See TracChangeset for help on using the changeset viewer.