Doc - starting on Part 5

RevBy:    TrustMe

doc/addressbook-sdk.qdoc

@@ -712,6 +712,37 @@
     \example examples/addressbook-sdk/part5
     \title Address Book 5 - Adding a Find Function}
 
+    In this chapter, we look at ways to locate contacts and addresses in the
+    address book application.
+
+    # image
+
+    As we keep adding contacts to our address book, it becomes tedious to
+    navigate them with the \gui Next and \gui Previous buttons. In this case,
+    a \gui Find function would be more efficient in looking up contacts. The
+    screenshot above shows the \gui Find button and its position on the panel
+    of buttons.
+
+    When the user clicks on the \gui Find button, it is useful to display a
+    dialog that can prompt the user for a contact's name. Qt provides QDialog,
+    which we subclass in this chapter, to implement a FindDialog class.
+
+    \section1 Designing FindDialog
+
+    #image
+
+    We begin by adding a new \c{.ui} file to our project. Right click on your
+    project and select \gui{Add New...}. In the \gui{New File} dialog, select
+    \gui{Qt Designer Form}. In the \gui{Qt Designer Form| dialog, select
+    \e{Dialog without buttons}. Name it \c{finddialog.ui} and add it to your
+    project. The \QD plugin within Qt Creator will now display your new form.
+
+    To replicate the screenshot above, we need a label, a line edit, and a push
+    button. Drag these onto your form. Set their text accordingly and name them
+    \c label, \c lineEdit, and \c findButton, respectively. Place these widgets
+    in a horizontal layout. Then set a top level layout - either horizontal or
+    vertical.
+
 */
 
 /*!

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

@@ -0,0 +1,237 @@
+#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;
+    previousButton->setEnabled(false);
+
+    editButton = new QPushButton;
+    editButton = ui->editButton;
+    editButton->setEnabled(false);
+
+    removeButton = new QPushButton;
+    removeButton = ui->removeButton;
+    removeButton->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()));
+    connect(editButton, SIGNAL(clicked()), this,
+                SLOT(editContact()));
+    connect(removeButton, SIGNAL(clicked()), this,
+                SLOT(removeContact()));
+
+    setWindowTitle(tr("Simple Address Book"));
+}
+
+AddressBook::~AddressBook()
+{
+    delete ui;
+}
+
+void AddressBook::addContact()
+{
+    oldName = nameLine->text();
+    oldAddress = addressText->toPlainText();
+
+    nameLine->clear();
+    addressText->clear();
+
+    updateInterface(AddingMode);
+}
+
+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."));
+    }
+
+    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));
+        }
+
+    } 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);
+}
+
+void AddressBook::cancel()
+{
+    nameLine->setText(oldName);
+    nameLine->setReadOnly(true);
+
+    updateInterface(NavigationMode);
+}
+
+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());
+}
+
+void AddressBook::editContact()
+{
+    oldName = nameLine->text();
+    oldAddress = addressText->toPlainText();
+
+    updateInterface(EditingMode);
+}
+
+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);
+}
+
+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;
+
+    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;
+    }
+}

doc/examples/addressbook-sdk/part5/addressbook.h

@@ -0,0 +1,54 @@
+#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 Mode { NavigationMode, AddingMode, EditingMode };
+    ~AddressBook();
+
+public slots:
+    void addContact();
+    void submitContact();
+    void cancel();
+    void editContact();
+    void removeContact();
+    void next();
+    void previous();
+
+private:
+    Ui::AddressBook *ui;
+
+    void updateInterface(Mode mode);
+    QPushButton *addButton;
+    QPushButton *submitButton;
+    QPushButton *cancelButton;
+    QPushButton *editButton;
+    QPushButton *removeButton;
+    QPushButton *nextButton;
+    QPushButton *previousButton;
+    QLineEdit *nameLine;
+    QTextEdit *addressText;
+
+    QMap<QString, QString> contacts;
+    QString oldName;
+    QString oldAddress;
+    Mode currentMode;
+};
+
+#endif // ADDRESSBOOK_H

doc/examples/addressbook-sdk/part5/addressbook.ui

@@ -0,0 +1,125 @@
+<?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>20</x>
+     <y>30</y>
+     <width>413</width>
+     <height>275</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>
+       <widget class="QPushButton" name="editButton">
+        <property name="text">
+         <string>Edit</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <widget class="QPushButton" name="removeButton">
+        <property name="text">
+         <string>Remove</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>

doc/examples/addressbook-sdk/part5/finddialog.ui

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>Dialog</class>
+ <widget class="QDialog" name="Dialog">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>476</width>
+    <height>87</height>
+   </rect>
+  </property>
+  <property name="windowTitle">
+   <string>Dialog</string>
+  </property>
+  <layout class="QHBoxLayout" name="horizontalLayout_2">
+   <item>
+    <layout class="QHBoxLayout" name="horizontalLayout">
+     <item>
+      <widget class="QLabel" name="label">
+       <property name="text">
+        <string>Enter the name of a contact:</string>
+       </property>
+      </widget>
+     </item>
+     <item>
+      <widget class="QLineEdit" name="lineEdit"/>
+     </item>
+     <item>
+      <widget class="QPushButton" name="findButton">
+       <property name="text">
+        <string>Find</string>
+       </property>
+      </widget>
+     </item>
+    </layout>
+   </item>
+  </layout>
+ </widget>
+ <resources/>
+ <connections/>
+</ui>

doc/examples/addressbook-sdk/part5/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();
+}

doc/examples/addressbook-sdk/part5/part5.pro

@@ -0,0 +1,10 @@
+# -------------------------------------------------
+# Project created by QtCreator 2009-06-08T17:25:28
+# -------------------------------------------------
+TARGET = part5
+TEMPLATE = app
+SOURCES += main.cpp \
+    addressbook.cpp
+HEADERS += addressbook.h
+FORMS += addressbook.ui \
+    finddialog.ui