Fixes: Doc - finishing up Part 3

RevBy:    TrustMe

3 files changed, 158 insertions, 96 deletions

diff --git a/doc/addressbook-sdk.qdoc b/doc/addressbook-sdk.qdoc
index ec9c46e6e9..572149c78b 100644
--- a/doc/addressbook-sdk.qdoc
+++ b/doc/addressbook-sdk.qdoc
@@ -460,10 +460,14 @@
     below illustrates what you will see as the button layout approaches the
     grid layout; drop it then.
 
-    \image addressbook-tutorial-part3-drop-into-gridlayout
+    \image addressbook-tutorial-part3-drop-in-gridlayout
 
     Finally, set a top level layout for the widget again.
 
+    \note 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.
+
 
     \section1 The AddressBook Class
 
@@ -477,16 +481,64 @@
 
     \snippet examples/addressbook-sdk/part3/addressbook.h members
 
-    To implement these slots, we begin by extracting the push buttons from
-    the form:
+    In the \c AddressBook constructor, we extract the push buttons from the
+    \c ui object and disable them by default. This is because navigation is
+    only enabled when there is more than one contact in the address book.
 
     \snippet examples/addressbook-sdk/part3/addressbook.cpp extract objects
 
-    Next, we make the necessary signal-slot connections.
+    Next, we connect the buttons to their respective slots:
 
     \snippet examples/addressbook-sdk/part3/addressbook.cpp signal slot
 
+    The screenshot below is our expected graphical user interface. Notice that
+    it is getting closer to our final application.
+
+    Within our \c addContact() function, we have to disable the \gui Next and
+    \gui Previous buttons so that the user does not attempt to navigate while
+    adding a contact.
+
+    \snippet examples/addressbook-sdk/part3/addressbook.cpp disable navigation
+
+    Also, in our \c submitContact() function, we enable the navigation buttons,
+    depending on the size of \c contacts. Asmentioned 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 examples/addressbook-sdk/part3/addressbook.cpp enable navigation
+
+    We also include these lins 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 examples/addressbook-sdk/part3/addressbook.cpp next
+
+    Once we have iterated to the current 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 teh 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 examples/addressbook-sdk/part3/addressbook.cpp previous
 
+    Again, we display the contents of the current object in \c contacts.
 
 */
diff --git a/doc/examples/addressbook-sdk/part3/addressbook.cpp b/doc/examples/addressbook-sdk/part3/addressbook.cpp
index 5eddb82198..304fd5f7a2 100644
--- a/doc/examples/addressbook-sdk/part3/addressbook.cpp
+++ b/doc/examples/addressbook-sdk/part3/addressbook.cpp
@@ -28,9 +28,11 @@ AddressBook::AddressBook(QWidget *parent)
 //! [extract objects]
     nextButton = new QPushButton;
     nextButton = ui->nextButton;
+    nextButton->setEnabled(false);
 
     previousButton = new QPushButton;
     previousButton = ui->previousButton;
+    nextButton->setEnabled(false);
 //! [extract objects]
 
     connect(addButton, SIGNAL(clicked()), this,
@@ -67,6 +69,10 @@ void AddressBook::addContact()
     addressText->setReadOnly(false);
 
     addButton->setEnabled(false);
+//! [disable navigation]
+    nextButton->setEnabled(false);
+    previousButton->setEnabled(false);
+//! [disable navigation]
     submitButton->show();
     cancelButton->show();
 }
@@ -101,6 +107,12 @@ void AddressBook::submitContact()
     nameLine->setReadOnly(true);
     addressText->setReadOnly(true);
     addButton->setEnabled(true);
+
+//! [enable navigation]
+    int number = contacts.size();
+    nextButton->setEnabled(number > 1);
+    previousButton->setEnabled(number > 1);
+//! [enable navigation]
     submitButton->hide();
     cancelButton->hide();
 }
@@ -112,8 +124,12 @@ void AddressBook::cancel()
 
     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();
 }
diff --git a/doc/examples/addressbook-sdk/part3/addressbook.ui b/doc/examples/addressbook-sdk/part3/addressbook.ui
index 6e313d6bbf..33f99cc409 100644
--- a/doc/examples/addressbook-sdk/part3/addressbook.ui
+++ b/doc/examples/addressbook-sdk/part3/addressbook.ui
@@ -13,97 +13,91 @@
   <property name="windowTitle">
    <string>AddressBook</string>
   </property>
-  <widget class="QWidget" name="layoutWidget">
-   <property name="geometry">
-    <rect>
-     <x>48</x>
-     <y>28</y>
-     <width>413</width>
-     <height>225</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>Next</string>
-        </property>
-       </widget>
-      </item>
-      <item>
-       <widget class="QPushButton" name="previousButton">
-        <property name="text">
-         <string>Previous</string>
-        </property>
-       </widget>
-      </item>
-     </layout>
-    </item>
-   </layout>
-  </widget>
+  <layout class="QHBoxLayout" name="horizontalLayout_2">
+   <item>
+    <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>
+   </item>
+  </layout>
  </widget>
  <layoutdefault spacing="6" margin="11"/>
  <resources/>