Doc - Starting with Part 4

Reviewed-by: TrustMe

7 files changed, 411 insertions, 2 deletions

diff --git a/doc/addressbook-sdk.qdoc b/doc/addressbook-sdk.qdoc
index 572149c78b..2ca6e9746d 100644
--- a/doc/addressbook-sdk.qdoc
+++ b/doc/addressbook-sdk.qdoc
@@ -542,3 +542,58 @@
     Again, we display the contents of the current object in \c contacts.
 
 */
+
+/*!
+    \page tutorials-addressbook-sdk-part4.html
+    \previouspage Address Book 3 - Navigating between Entries
+    \contentspage {Address Book Tutorial}{Contents}
+    \nextpage \l{examples/addressbook-sdk/part5}{Chapter 5}
+    \example examples/addressbook-sdk/part4
+    \title Address Book 4 - Editing and Removing Addresses}
+
+    In this chapter, we look at ways to modify the contents of contacts stored
+    in the address book application.
+
+    #screenshot
+
+    We now have an address book that not only holds contacts in an organized
+    manner, but also allows navigation. It would be convenient to include edit
+    and remove functions so that a contact's details can be changed 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 were not defined as enums. Instead, we enabled
+    and disabled the corresponding buttons manually, resulting in multiple
+    lines of repeated code.
+
+    In this chapter, we define the \c Mode enum with three different values:
+    \list
+        \o \c{NavigationMode},
+        \o \c{AddingMode}, and
+        \o \c{EditingMode}.
+    \endlist
+
+    \section1 Placing Widgets on the Form
+
+    \section1 The AddressBook Class
+
+    We update the header file to contain the \c Mode enum:
+
+    \snippet examples/addressbook-sdk/part4/addressbook.h enum
+
+    We also add two new slots, \c editContact() and \c removeContact(), to our
+    current list of public slots.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.h slot definition
+
+*/
+
+/*!
+    \page tutorials-addressbook-sdk-part5.html
+    \previouspage Address Book 4 - Editing and Removing Addresses
+    \contentspage {Address Book Tutorial}{Contents}
+    \nextpage \l{examples/addressbook-sdk/part6}{Chapter 6}
+    \example examples/addressbook-sdk/part5
+    \title Address Book 5 - Adding a Find Function}
+
+*/
diff --git a/doc/examples/addressbook-sdk/part3/main.cpp b/doc/examples/addressbook-sdk/part3/main.cpp
index 3378b4adce..437a1c8352 100644
--- a/doc/examples/addressbook-sdk/part3/main.cpp
+++ b/doc/examples/addressbook-sdk/part3/main.cpp
@@ -1,4 +1,3 @@
-//! [main function]
 #include <QtGui/QApplication>
 #include "addressbook.h"
 
@@ -9,4 +8,3 @@ int main(int argc, char *argv[])
     w.show();
     return a.exec();
 }
-//! [main function]
diff --git a/doc/examples/addressbook-sdk/part4/addressbook.cpp b/doc/examples/addressbook-sdk/part4/addressbook.cpp
new file mode 100644
index 0000000000..e14c86f426
--- /dev/null
+++ b/doc/examples/addressbook-sdk/part4/addressbook.cpp
@@ -0,0 +1,161 @@
+#include "addressbook.h"
+#include "ui_addressbook.h"
+
+AddressBook::AddressBook(QWidget *parent)
+    : QWidget(parent), ui(new Ui::AddressBook)
+{
+    ui->setupUi(this);
+
+    nameLine = new QLineEdit;
+    nameLine = ui->nameLine;
+    nameLine->setReadOnly(true);
+
+    addressText = new QTextEdit;
+    addressText = ui->addressText;
+    addressText->setReadOnly(true);
+
+    addButton = new QPushButton;
+    addButton = ui->addButton;
+
+    submitButton = new QPushButton;
+    submitButton = ui->submitButton;
+    submitButton->hide();
+
+    cancelButton = new QPushButton;
+    cancelButton = ui->cancelButton;
+    cancelButton->hide();
+
+    nextButton = new QPushButton;
+    nextButton = ui->nextButton;
+    nextButton->setEnabled(false);
+
+    previousButton = new QPushButton;
+    previousButton = ui->previousButton;
+    nextButton->setEnabled(false);
+
+    connect(addButton, SIGNAL(clicked()), this,
+                SLOT(addContact()));
+    connect(submitButton, SIGNAL(clicked()), this,
+                SLOT(submitContact()));
+    connect(cancelButton, SIGNAL(clicked()), this,
+                SLOT(cancel()));
+    connect(nextButton, SIGNAL(clicked()), this,
+                SLOT(next()));
+    connect(previousButton, SIGNAL(clicked()), this,
+                SLOT(previous()));
+
+    setWindowTitle(tr("Simple Address Book"));
+}
+
+AddressBook::~AddressBook()
+{
+    delete ui;
+}
+
+void AddressBook::addContact()
+{
+    oldName = nameLine->text();
+    oldAddress = addressText->toPlainText();
+
+    nameLine->clear();
+    addressText->clear();
+
+    nameLine->setReadOnly(false);
+    nameLine->setFocus(Qt::OtherFocusReason);
+    addressText->setReadOnly(false);
+
+    addButton->setEnabled(false);
+    nextButton->setEnabled(false);
+    previousButton->setEnabled(false);
+    submitButton->show();
+    cancelButton->show();
+}
+
+void AddressBook::submitContact()
+{
+    QString name = nameLine->text();
+    QString address = addressText->toPlainText();
+
+    if (name == "" || address == "") {
+        QMessageBox::information(this, tr("Empty Field"),
+            tr("Please enter a name and address."));
+        return;
+    }
+
+    if (!contacts.contains(name)) {
+        contacts.insert(name, address);
+        QMessageBox::information(this, tr("Add Successful"),
+            tr("\"%1\" has been added to your address book.").arg(name));
+        return;
+    } else {
+        QMessageBox::information(this, tr("Add Unsuccessful"),
+            tr("Sorry, \"%1\" is already in your address book.").arg(name));
+        return;
+    }
+
+    if (contacts.isEmpty()) {
+        nameLine->clear();
+        addressText->clear();
+    }
+
+    nameLine->setReadOnly(true);
+    addressText->setReadOnly(true);
+    addButton->setEnabled(true);
+
+    int number = contacts.size();
+    nextButton->setEnabled(number > 1);
+    previousButton->setEnabled(number > 1);
+    submitButton->hide();
+    cancelButton->hide();
+}
+
+void AddressBook::cancel()
+{
+    nameLine->setText(oldName);
+    nameLine->setReadOnly(true);
+
+    addressText->setText(oldAddress);
+    addressText->setReadOnly(true);
+    addButton->setEnabled(true);
+
+    int number = contacts.size();
+    nextButton->setEnabled(number > 1);
+    previousButton->setEnabled(number > 1);
+
+    submitButton->hide();
+    cancelButton->hide();
+}
+
+void AddressBook::next()
+{
+    QString name = nameLine->text();
+    QMap<QString, QString>::iterator i = contacts.find(name);
+
+    if (i != contacts.end())
+        i++;
+    if (i == contacts.end())
+        i = contacts.begin();
+
+    nameLine->setText(i.key());
+    addressText->setText(i.value());
+}
+
+void AddressBook::previous()
+{
+    QString name = nameLine->text();
+    QMap<QString, QString>::iterator i = contacts.find(name);
+
+    if (i == contacts.end()) {
+        nameLine->clear();
+        addressText->clear();
+        return;
+    }
+
+    if (i == contacts.begin())
+        i = contacts.end();
+
+    i--;
+    nameLine->setText(i.key());
+    addressText->setText(i.value());
+}
+
diff --git a/doc/examples/addressbook-sdk/part4/addressbook.h b/doc/examples/addressbook-sdk/part4/addressbook.h
new file mode 100644
index 0000000000..7bc76f45f7
--- /dev/null
+++ b/doc/examples/addressbook-sdk/part4/addressbook.h
@@ -0,0 +1,58 @@
+//! [class definition]
+#ifndef ADDRESSBOOK_H
+#define ADDRESSBOOK_H
+
+#include <QtGui/QWidget>
+#include <QtGui/QPushButton>
+#include <QtGui/QLineEdit>
+#include <QtGui/QTextEdit>
+#include <QtGui/QMessageBox>
+
+
+namespace Ui
+{
+    class AddressBook;
+}
+
+class AddressBook : public QWidget
+{
+    Q_OBJECT
+
+public:
+    AddressBook(QWidget *parent = 0);
+//! [enum]
+    enum Mode { NavigationMode, AddingMode, EditingMode };
+//! [enum]
+    ~AddressBook();
+
+public slots:
+    void addContact();
+    void submitContact();
+    void cancel();
+//! [slot definition]
+    void editContact();
+    void removeContact();
+//! [slot definition]
+    void next();
+    void previous();
+
+private:
+    Ui::AddressBook *ui;
+
+    QPushButton *addButton;
+    QPushButton *submitButton;
+    QPushButton *cancelButton;
+//! [members]
+    QPushButton *nextButton;
+    QPushButton *previousButton;
+//! [members]
+    QLineEdit *nameLine;
+    QTextEdit *addressText;
+
+    QMap<QString, QString> contacts;
+    QString oldName;
+    QString oldAddress;
+};
+
+#endif // ADDRESSBOOK_H
+//! [class definition]
diff --git a/doc/examples/addressbook-sdk/part4/addressbook.ui b/doc/examples/addressbook-sdk/part4/addressbook.ui
new file mode 100644
index 0000000000..ee9bbe4d65
--- /dev/null
+++ b/doc/examples/addressbook-sdk/part4/addressbook.ui
@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>AddressBook</class>
+ <widget class="QWidget" name="AddressBook">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>600</width>
+    <height>400</height>
+   </rect>
+  </property>
+  <property name="windowTitle">
+   <string>AddressBook</string>
+  </property>
+  <widget class="QWidget" name="layoutWidget">
+   <property name="geometry">
+    <rect>
+     <x>10</x>
+     <y>10</y>
+     <width>413</width>
+     <height>260</height>
+    </rect>
+   </property>
+   <layout class="QGridLayout" name="gridLayout">
+    <item row="0" column="0">
+     <widget class="QLabel" name="nameLabel">
+      <property name="text">
+       <string>Name:</string>
+      </property>
+     </widget>
+    </item>
+    <item row="0" column="1">
+     <widget class="QLineEdit" name="nameLine"/>
+    </item>
+    <item row="1" column="0">
+     <widget class="QLabel" name="addressLabel">
+      <property name="text">
+       <string>Address:</string>
+      </property>
+      <property name="alignment">
+       <set>Qt::AlignLeading|Qt::AlignLeft|Qt::AlignTop</set>
+      </property>
+     </widget>
+    </item>
+    <item row="1" column="1">
+     <widget class="QTextEdit" name="addressText"/>
+    </item>
+    <item row="1" column="2">
+     <layout class="QVBoxLayout" name="verticalLayout">
+      <item>
+       <widget class="QPushButton" name="addButton">
+        <property name="text">
+         <string>Add</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <widget class="QPushButton" name="submitButton">
+        <property name="text">
+         <string>Submit</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <widget class="QPushButton" name="cancelButton">
+        <property name="text">
+         <string>Cancel</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <spacer name="verticalSpacer">
+        <property name="orientation">
+         <enum>Qt::Vertical</enum>
+        </property>
+        <property name="sizeHint" stdset="0">
+         <size>
+          <width>20</width>
+          <height>40</height>
+         </size>
+        </property>
+       </spacer>
+      </item>
+     </layout>
+    </item>
+    <item row="2" column="1">
+     <layout class="QHBoxLayout" name="horizontalLayout">
+      <item>
+       <widget class="QPushButton" name="nextButton">
+        <property name="text">
+         <string>Previous</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <widget class="QPushButton" name="previousButton">
+        <property name="text">
+         <string>Next</string>
+        </property>
+       </widget>
+      </item>
+     </layout>
+    </item>
+   </layout>
+  </widget>
+ </widget>
+ <layoutdefault spacing="6" margin="11"/>
+ <resources/>
+ <connections/>
+</ui>
diff --git a/doc/examples/addressbook-sdk/part4/main.cpp b/doc/examples/addressbook-sdk/part4/main.cpp
new file mode 100644
index 0000000000..437a1c8352
--- /dev/null
+++ b/doc/examples/addressbook-sdk/part4/main.cpp
@@ -0,0 +1,10 @@
+#include <QtGui/QApplication>
+#include "addressbook.h"
+
+int main(int argc, char *argv[])
+{
+    QApplication a(argc, argv);
+    AddressBook w;
+    w.show();
+    return a.exec();
+}
diff --git a/doc/examples/addressbook-sdk/part4/part4.pro b/doc/examples/addressbook-sdk/part4/part4.pro
new file mode 100644
index 0000000000..8c34931ed3
--- /dev/null
+++ b/doc/examples/addressbook-sdk/part4/part4.pro
@@ -0,0 +1,16 @@
+#-------------------------------------------------
+#
+# Project created by QtCreator 2009-06-05T16:03:06
+#
+#-------------------------------------------------
+
+TARGET = part4
+TEMPLATE = app
+
+
+SOURCES += main.cpp\
+        addressbook.cpp
+
+HEADERS  += addressbook.h
+
+FORMS    += addressbook.ui