Doc - finishing up Part 4 and setting up Parts 5, 6, and 7

RevBy:    TrustMe

doc/addressbook-sdk.qdoc

@@ -613,7 +613,88 @@
     disabled by default, as the address book starts up with zero contacts in
     memory.
 
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp extract objects
 
+    These buttons are then connected to their respective slots,
+    \c editContact() and \c removeContact.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp signal slot
+
+    Now we look at the \c editContact() and \c removeContact() functions in
+    detail.
+
+
+    \section2 The \c{editContact()} Function
+
+    This function stores the contact's old details in \c oldName and
+    \c oldAddress, before switching the mode to \c EditingMode. In this mode,
+    the \c submitButton and \c cancelButton are both enabled. Hence, the user
+    can change the contact's details and click either button.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp editContact
+
+    Since we will reuse the \c submitButton for both: adding a new contact and
+    editing an existing contact, we need to modify our existing
+    \c submitContact() function. So, we divide it in two with an \c{if-else}
+    statement.
+
+    First, we check \c currentMode to see if it is in \c AddingMode. If it is,
+    we proceed with our adding process.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part1
+    \dots
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part2
+
+    Otherwise, we check to see if \c currentMode is in \c EditingMode. If it
+    is, we compare \c oldName with \c name. If the name has changed, we remove
+    the old contact from \c contacts and insert the newly updated contact.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp submitContact part3
+
+    If only the contact's address changed, i.e., \c oldAddress is not the same
+    as \c address, we update the contact's address. Lastly, we set
+    \c currentMode to \c NavigationMode. This is an important step as it
+    re-enables all the disabled push buttons.
+
+    To remove a contact from the address book, we implement the
+    \c removeContact() function.
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp removeContact
+
+    This function first checks to see if the contact exists in \c contacts. If
+    it does, we display a QMessageBox, to confirm the removal with the user.
+    Once the user has confirmed, we call \c previous() to ensure that the
+    user interface shows another contact, and we remove the contact using
+    \l{QMap}'s \l{QMap::}{remove()} function. As a courtesy, we display a
+    QMessageBox to inform the user. Both the message boxes used in this
+    function are shown below:
+
+    # image
+
+
+    \section2 The \c{updateInterface()} Function
+
+    We mentioned this function earlier as a means to enable and disable the
+    push buttons, depending on the current mode. The function updates the
+    current mode according to the \c mode argument passed to it, assigning it
+    to \c currentMode, before checking its value.\
+
+    Each of the push buttons is then enabled or disabled, depending on the
+    current mode. The code for \c AddingMode and \c EditingMode is shown below:
+
+    \snippet examples/addressbook-sdk/part4/addressbook.cpp updateInterface part1
+
+    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 examples/addressbook-sdk/part4/addressbook.cpp updateInterface part2
+
+    By performing the task of setting the mode and updating the user interface
+    in the same function, we avoid the possibility of the user interface
+    getting "out of sync" with the internal state of the application.
 
 */
 
@@ -626,3 +707,22 @@
     \title Address Book 5 - Adding a Find Function}
 
 */
+
+/*!
+    \page tutorials-addressbook-sdk-part6.html
+    \previouspage Address Book 5 - Adding a Find Function
+    \contentspage {Address Book Tutorial}{Contents}
+    \nextpage \l{examples/addressbook-sdk/part7}{Chapter 7}
+    \example examples/addressbook-sdk/part6
+    \title Address Book 6 - Loading and Saving}
+
+*/
+
+/*!
+    \page tutorials-addressbook-sdk-part7.html
+    \previouspage Address Book 6 - Loading and Saving
+    \contentspage {Address Book Tutorial}{Contents}
+    \example examples/addressbook-sdk/part7
+    \title Address Book 7 - Additional Features}
+
+*/

doc/examples/addressbook-sdk/part4/addressbook.cpp

@@ -33,6 +33,7 @@ AddressBook::AddressBook(QWidget *parent)
     previousButton = ui->previousButton;
     previousButton->setEnabled(false);
 
+//! [extract objects]
     editButton = new QPushButton;
     editButton = ui->editButton;
     editButton->setEnabled(false);
@@ -40,6 +41,7 @@ AddressBook::AddressBook(QWidget *parent)
     removeButton = new QPushButton;
     removeButton = ui->removeButton;
     removeButton->setEnabled(false);
+//! [extract objects]
 
     connect(addButton, SIGNAL(clicked()), this,
                 SLOT(addContact()));
@@ -51,6 +53,12 @@ AddressBook::AddressBook(QWidget *parent)
                 SLOT(next()));
     connect(previousButton, SIGNAL(clicked()), this,
                 SLOT(previous()));
+//! [signal slot]
+    connect(editButton, SIGNAL(clicked()), this,
+                SLOT(editContact()));
+    connect(removeButton, SIGNAL(clicked()), this,
+                SLOT(removeContact()));
+//! [signal slot]
 
     setWindowTitle(tr("Simple Address Book"));
 }
@@ -79,43 +87,54 @@ void AddressBook::addContact()
     cancelButton->show();
 }
 
+//! [submitContact part1]
 void AddressBook::submitContact()
 {
+//! [submitContact part1]
     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();
+//! [submitContact part2]
+    if (currentMode == AddingMode) {
+
+        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));
+        } else {
+            QMessageBox::information(this, tr("Add Unsuccessful"),
+                tr("Sorry, \"%1\" is already in your address book.").arg(name));
+        }
+//! [submitContact part2]
+
+//! [submitContact part3]
+    } else if (currentMode == EditingMode) {
+
+        if (oldName != name) {
+            if (!contacts.contains(name)) {
+                QMessageBox::information(this, tr("Edit Successful"),
+                    tr("\"%1\" has been edited in your address book.").arg(oldName));
+                contacts.remove(oldName);
+                contacts.insert(name, address);
+            } else  {
+                QMessageBox::information(this, tr("Edit Unsuccessful"),
+                    tr("Sorry, \"%1\" is already in your address book.").arg(name));
+            }
+        } else if (oldAddress != address) {
+            QMessageBox::information(this, tr("Edit Successful"),
+                tr("\"%1\" has been edited in your address book.").arg(name));
+            contacts[name] = address;
+        }
+
+        updateInterface(NavigationMode);
     }
-
-    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();
 }
+//! [submitContact part3]
 
 void AddressBook::cancel()
 {
@@ -167,3 +186,88 @@ void AddressBook::previous()
     addressText->setText(i.value());
 }
 
+//! [editContact]
+void AddressBook::editContact()
+{
+    oldName = nameLine->text();
+    oldAddress = addressText->toPlainText();
+
+    updateInterface(EditingMode);
+}
+//! [editContact]
+
+//! [removeContact]
+void AddressBook::removeContact()
+{
+    QString name = nameLine->text();
+    QString address = addressText->toPlainText();
+
+    if (contacts.contains(name)) {
+        int button = QMessageBox::question(this,
+            tr("Confirm Remove"),
+            tr("Are you sure you want to remove \"%1\"?").arg(name),
+            QMessageBox::Yes | QMessageBox::No);
+
+        if (button == QMessageBox::Yes) {
+            previous();
+            contacts.remove(name);
+
+            QMessageBox::information(this, tr("Remove Successful"),
+                tr("\"%1\" has been removed from your address book.").arg(name));
+        }
+    }
+
+    updateInterface(NavigationMode);
+}
+//! [removeContact]
+
+//! [updateInterface part1]
+void AddressBook::updateInterface(Mode mode)
+{
+    currentMode = mode;
+
+    switch (currentMode) {
+
+    case AddingMode:
+    case EditingMode:
+
+        nameLine->setReadOnly(false);
+        nameLine->setFocus(Qt::OtherFocusReason);
+        addressTExt->setReadOnly(false);
+
+        addButton->setEnabled(false);
+        editButton->setEnabled(false);
+        removeButton->setEnabled(false);
+
+        nextButton->setEnabled(false);
+        previousButton->setEnabled(false);
+
+        submitButton->show();
+        cancelButton->show();
+        break;
+//! [updateInterface part1]
+
+//! [updateInterface part2]
+    case NavigationMode:
+
+        if (contacts.isEmpty()) {
+            nameLine->clear();
+            addressText->clear();
+        }
+
+        nameLine->setReadOnly(true);
+        addressText->setReadOnly(true);
+        addButton->setEnabled(true);
+
+        int number = contacts.size();
+        editButton->setEnabled(number >= 1);
+        removeButton->setEnabled(number >= 1);
+        nextButton->setEnabled(number > 1);
+        previousButton->setEnabled(number >1);
+
+        submitButton->hide();
+        cancelButton->hide();
+        break;
+    }
+}
+//! [updateInterface part2]