/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page tutorials-addressbook.html

    \startpage {index.html}{Qt Reference Documentation}

    \contentspage Tutorials

    \nextpage {tutorials/addressbook/part1}{Chapter 1}

    \title Address Book Tutorial

    \brief An introduction to GUI programming, showing how to put together a

    simple yet fully-functioning application.

    This tutorial gives an introduction to GUI programming using the Qt

    cross-platform framework.

    \image addressbook-tutorial-screenshot.png

    \omit

    It doesn't cover everything; the emphasis is on teaching the programming

    philosophy of GUI programming, and Qt's features are introduced as needed.

    Some commonly used features are never used in this tutorial.

    \endomit

    In the process, we will learn about some basic technologies provided by Qt,

    such as

    \list

    \o Widgets and layout managers

    \o Container classes

    \o Signals and slots

    \o Input and output devices

    \endlist

    If you are completely new to Qt, please read \l{How to Learn Qt} if you

    have not already done so.

    The tutorial's source code is located in Qt's \c examples/tutorials/addressbook

    directory.

    Tutorial chapters:

    \list 1

    \o \l{tutorials/addressbook/part1}{Designing the User Interface}

    \o \l{tutorials/addressbook/part2}{Adding Addresses}

    \o \l{tutorials/addressbook/part3}{Navigating between Entries}

    \o \l{tutorials/addressbook/part4}{Editing and Removing Addresses}

    \o \l{tutorials/addressbook/part5}{Adding a Find Function}

    \o \l{tutorials/addressbook/part6}{Loading and Saving}

    \o \l{tutorials/addressbook/part7}{Additional Features}

    \endlist

    Although this little application does not look much like a fully-fledged

    modern GUI application, it uses many of the basic techniques that are used

    in more complex applications. After you have worked through it, we

    recommend checking out the \l{mainwindows/application}{Application}

    example, which presents a small GUI application, with menus, toolbars, a

    status bar, and so on.

*/

/*!

    \page tutorials-addressbook-part1.html

    \contentspage {Address Book Tutorial}{Contents}

    \nextpage {tutorials/addressbook/part2}{Chapter 2}

    \example tutorials/addressbook/part1

    \title Address Book 1 - Designing the User Interface

    The first part of this tutorial covers the design of the basic graphical

    user interface (GUI) we use for the Address Book application.

    The first step to creating a GUI program is to design the user interface.

    In this chapter, our goal is to set up the labels and input fields needed

    to implement a basic address book application. The figure below is a

    screenshot of our expected output.

    \image addressbook-tutorial-part1-screenshot.png

    We require two QLabel objects, \c nameLabel and \c addressLabel, as well

    as two input fields, a QLineEdit object, \c nameLine, and a QTextEdit

    object, \c addressText, to enable the user to enter a contact's name and

    address. The widgets used and their positions are shown in the figure

    below.

    \image addressbook-tutorial-part1-labeled-screenshot.png

    There are three files used to implement this address book:

    \list

        \o \c{addressbook.h} - the definition file for the \c AddressBook

            class,

        \o \c{addressbook.cpp} - the implementation file for the

            \c AddressBook class, and

        \o \c{main.cpp} - the file containing a \c main() function, with

            an instance of \c AddressBook.

    \endlist

    \section1 Qt Programming - Subclassing

    When writing Qt programs, we usually subclass Qt objects to add

    functionality. This is one of the essential concepts behind creating

    custom widgets or collections of standard widgets. Subclassing to

    extend or change the behavior of a widget has the following advantages:

    \list

    \o We can write implementations of virtual or pure virtual functions to

    obtain exactly what we need, falling back on the base class's implementation

    when necessary.

    \o It allows us to encapsulate parts of the user interface within a class,

    so that the other parts of the application don't need to know about the

    individual widgets in the user interface.

    \o The subclass can be used to create multiple custom widgets in the same

    application or library, and the code for the subclass can be reused in other

    projects.

    \endlist

    Since Qt does not provide a specific address book widget, we subclass a

    standard Qt widget class and add features to it. The \c AddressBook class

    we create in this tutorial can be reused in situations where a basic address

    book widget is needed.

    \section1 Defining the AddressBook Class

    The \l{tutorials/addressbook/part1/addressbook.h}{\c addressbook.h} file is

    used to define the \c AddressBook class.

    We start by defining \c AddressBook as a QWidget subclass and declaring

    a constructor. We also use the Q_OBJECT macro to indicate that the class

    uses internationalization and Qt's signals and slots features, even

    if we do not use all of these features at this stage.

    \snippet tutorials/addressbook/part1/addressbook.h class definition

    The class holds declarations of \c nameLine and \c addressText, the

    private instances of QLineEdit and QTextEdit mentioned earlier.

    You will see, in the coming chapters, that data stored in \c nameLine and

    \c addressText is needed for many of the address book's functions.

    We do not need to include declarations of the QLabel objects we will use

    because we will not need to reference them once they have been created.

    The way Qt tracks the ownership of objects is explained in the next section.

    The Q_OBJECT macro itself implements some of the more advanced features of Qt.

    For now, it is useful to think of the Q_OBJECT macro as a shortcut which allows

    us to use the \l{QObject::}{tr()} and \l{QObject::}{connect()} functions.

    We have now completed the \c addressbook.h file and we move on to

    implement the corresponding \c addressbook.cpp file.

    \section1 Implementing the AddressBook Class

    The constructor of \c AddressBook accepts a QWidget parameter, \a parent.

    By convention, we pass this parameter to the base class's constructor.

    This concept of ownership, where a parent can have one or more children,

    is useful for grouping widgets in Qt. For example, if you delete a parent,

    all of its children will be deleted as well.

    \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields

    Within this constructor, we declare and instantiate two local QLabel objects,

    \c nameLabel and \c addressLabel, as well as instantiate \c nameLine and

    \c addressText. The

    \l{QObject::tr()}{tr()} function returns a translated version of the

    string, if there is one available; otherwise, it returns the string itself.

    Think of this function as an \c{<insert translation here>} marker to mark

    QString objects for translation. You will notice, in the coming chapters as

    well as in the \l{Qt Examples}, that we include it whenever we use a

    translatable string.

    When programming with Qt, it is useful to know how layouts work.

    Qt provides three main layout classes: QHBoxLayout, QVBoxLayout

    and QGridLayout to handle the positioning of widgets.

    \image addressbook-tutorial-part1-labeled-layout.png

    We use a QGridLayout to position our labels and input fields in a

    structured manner. QGridLayout divides the available space into a grid and

    places widgets in the cells we specify with row and column numbers. The

    diagram above shows the layout cells and the position of our widgets, and

    we specify this arrangement using the following code:

    \snippet tutorials/addressbook/part1/addressbook.cpp layout

    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 Management} documentation.

    In order to install the layout object onto the widget, we have to invoke

    the widget's \l{QWidget::setLayout()}{setLayout()} function:

    \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout

    Lastly, we set the widget's title to "Simple Address Book".

    \section1 Running the Application

    A separate file, \c main.cpp, is used for the \c main() function. Within

    this function, we instantiate a QApplication object, \c app. QApplication

    is responsible for various application-wide resources, such as the default

    font and cursor, and for running an event loop. Hence, there is always one

    QApplication object in every GUI application using Qt.

    \snippet tutorials/addressbook/part1/main.cpp main function

    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. 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.

*/

/*!

    \page tutorials-addressbook-part2.html

    \previouspage Address Book 1 - Designing the User Interface

    \contentspage {Address Book Tutorial}{Contents}

    \nextpage {tutorials/addressbook/part3}{Chapter 3}

    \example tutorials/addressbook/part2

    \title Address Book 2 - Adding Addresses

    The next step to creating our basic address book application is to allow

    a little bit of user interaction.

    \image addressbook-tutorial-part2-add-contact.png

    We will provide a push button that the user can click to add a new contact.

    Also, some form of data structure is needed to store these contacts in an

    organized way.

    \section1 Defining the AddressBook Class

    Now that we have the labels and input fields set up, we add push buttons to

    complete the process of adding a contact. This means that our

    \c addressbook.h file now has three QPushButton objects declared and three

    corresponding public slots.

    \snippet tutorials/addressbook/part2/addressbook.h slots

    A slot is a function that responds to a particular signal. We will discuss

    this concept in further detail when implementing the \c AddressBook class.

    However, for an overview of Qt's signals and slots concept, you can refer

    to the \l{Signals and Slots} document.

    Three QPushButton objects: \c addButton, \c submitButton and

    \c cancelButton, are now included in our private variable declarations,

    along with \c nameLine and \c addressText from the last chapter.

    \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration

    We need a container to store our address book contacts, so that we can

    traverse and display them. A QMap object, \c contacts, is used for this

    purpose as it holds a key-value pair: the contact's name as the \e key,

    and the contact's address as the \e{value}.

    \snippet tutorials/addressbook/part2/addressbook.h remaining private variables

    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 \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

    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 contact details.

    \dots

    \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1

    \dots

    \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2

    Then, we instantiate our push buttons: \c addButton, \c submitButton, and

    \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration

    The \c addButton is displayed by invoking the \l{QPushButton::show()}

    {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 \gui Add and this is

    handled by the \c addContact() function discussed below.

    \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots

    We connect the push buttons' \l{QPushButton::clicked()}{clicked()} signal

    to their respective slots. The figure below illustrates this.

    \image addressbook-tutorial-part2-signals-and-slots.png

    Next, we arrange our push buttons neatly to the right of our address book

    widget, using a QVBoxLayout to line them up vertically.

    \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout

    The \l{QBoxLayout::addStretch()}{addStretch()} function is used to ensure

    the push buttons are not evenly spaced, but arranged closer to the top of

    the widget. The figure below shows the difference between using

    \l{QBoxLayout::addStretch()}{addStretch()} and not using it.

    \image addressbook-tutorial-part2-stretch-effects.png

    We then add \c buttonLayout1 to \c mainLayout, using

    \l{QGridLayout::addLayout()}{addLayout()}. This gives us nested layouts

    as \c buttonLayout1 is now a child of \c mainLayout.

    \snippet tutorials/addressbook/part2/addressbook.cpp grid layout

    Our layout coordinates now look like this:

    \image addressbook-tutorial-part2-labeled-layout.png

    In the \c addContact() function, we store the last displayed contact

    details in \c oldName and \c oldAddress. Then we clear these input

    fields and turn off the read-only mode. The focus is set on \c nameLine

    and we display \c submitButton and \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp addContact

    The \c submitContact() function can be divided into three parts:

    \list 1

    \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 \gui Submit with empty input fields; otherwise, a

    QMessageBox is displayed to remind the user for a name and address.

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1

    \o We then proceed to check if the contact already exists. If it does not

    exist, we add the contact to \c contacts and we display a QMessageBox to

    inform the user that the contact has been added.

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2

    If the contact already exists, again, we display a QMessageBox to inform

    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.

    \o Once we have handled both cases mentioned above, we restore the push

    buttons to their normal state with the following code:

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3

    \endlist

    The screenshot below shows the QMessageBox object we use to display

    information messages to the user.

    \image addressbook-tutorial-part2-add-successful.png

    The \c cancel() function restores the last displayed contact details and

    enables \c addButton, as well as hides \c submitButton and

    \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp cancel

    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

*/

/*!

    \page tutorials-addressbook-part3.html

    \previouspage Address Book 2 - Adding Addresses

    \contentspage {Address Book Tutorial}{Contents}

    \nextpage {tutorials/addressbook/part4}{Chapter 4}

    \example tutorials/addressbook/part3

    \title Address Book 3 - Navigating between Entries

    The address book application is now half complete. We need to add some

    functions to navigate between contacts. But first, we have to decide

    what sort of a data structure we would like to use to hold these contacts.

    In Chapter 2, we used a QMap of key-value pairs with the contact's name

    as the \e key, and the contact's address as the \e value. This works well

    for our case. However, in order to navigate and display each entry, a

    little bit of enhancement is needed.

    We enhance the QMap by making it replicate a data structure similar to a

    circularly-linked list, where all elements are connected, including the

    first element and the last element. The figure below illustrates this data

    structure.

    \image addressbook-tutorial-part3-linkedlist.png

    \section1 Defining the AddressBook Class

    In order to add navigation functions to the address book application, we

    need to add two more slots to our \c AddressBook class: \c next() and

    \c previous(). These are added to our \c addressbook.h file:

    \snippet tutorials/addressbook/part3/addressbook.h navigation functions

    We also require another two QPushButton objects, so we declare \c nextButton

    and \c previousButton as private variables:

    \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons

    \section1 Implementing the AddressBook Class

    In the \c AddressBook constructor in \c addressbook.cpp, we instantiate

    \c nextButton and \c previousButton and disable them by default. This is

    because navigation is only enabled when there is more than one contact

    in the address book.

    \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons

    We then connect these push buttons to their respective slots:

    \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals

    The image below is our expected graphical user interface. Notice that it

    is getting closer to our final application.

    \image addressbook-tutorial-part3-screenshot.png

    We follow basic conventions for \c next() and \c previous() functions by

    placing the \c nextButton on the right and the \c previousButton on the

    left. In order to achieve this intuitive layout, we use QHBoxLayout to

    place the widgets side-by-side:

    \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout

    The QHBoxLayout object, \c buttonLayout2, is then added to \c mainLayout.

    \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout

    The figure below shows the coordinates of the widgets in \c mainLayout.

    \image addressbook-tutorial-part3-labeled-layout.png

    Within our \c addContact() function, we have to disable these buttons so

    that the user does not attempt to navigate while adding a contact.

    \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation

    Also, in our \c submitContact() function, we enable the navigation

    buttons, \c nextButton and \c previousButton, depending on the size

    of \c contacts. As mentioned earlier, navigation is only enabled when

    there is more than one contact in the address book. The following lines

    of code demonstrates how to do this:

    \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation

    We also include these lines of code in the \c cancel() function.

    Recall that we intend to emulate a circularly-linked list with our QMap

    object, \c contacts. So, in the \c next() function, we obtain an iterator

    for \c contacts and then:

    \list

        \o If the iterator is not at the end of \c contacts, we increment it

        by one.

        \o If the iterator is at the end of \c contacts, we move it to the

        beginning of \c contacts. This gives us the illusion that our QMap is

        working like a circularly-linked list.

    \endlist

    \snippet tutorials/addressbook/part3/addressbook.cpp next() function

    Once we have iterated to the correct object in \c contacts, we display

    its contents on \c nameLine and \c addressText.

    Similarly, for the \c previous() function, we obtain an iterator for

    \c contacts and then:

    \list

        \o If the iterator is at the end of \c contacts, we clear the

        display and return.

        \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.

    \endlist

    \snippet tutorials/addressbook/part3/addressbook.cpp previous() function

    Again, we display the contents of the current object in \c contacts.

*/

/*!

    \page tutorials-addressbook-part4.html

    \previouspage Address Book 3 - Navigating between Entries

    \contentspage {Address Book Tutorial}{Contents}