Complete documentation of schema example and reference it from api docs

4 files changed, 99 insertions, 0 deletions

diff --git a/doc/src/examples/schema.qdoc b/doc/src/examples/schema.qdoc
index 2287796..80d158b 100644
--- a/doc/src/examples/schema.qdoc
+++ b/doc/src/examples/schema.qdoc
@@ -46,6 +46,8 @@
   This example shows how to use QtXmlPatterns to validate XML with
   a W3C XML Schema.
 
+  \tableofcontents
+
   \section1 Introduction
 
   The example application shows different XML schema definitions and
@@ -54,5 +56,88 @@
   The user can select the valid or invalid instance document, change
   it and validate it again.
 
+  \section2 The User Interface
+
+  The UI for this example was created using \l{Qt Designer Manual} {Qt
+  Designer}:
+
   \image schema-example.png
+
+  The UI consists of three parts, at the top the XML schema \l{QComboBox} {selection}
+  and the schema \l{QTextBrowser} {viewer}, below the XML instance \l{QComboBox} {selection}
+  and the instance \l{QTextEdit} {editor} and at the bottom the validation status \l{QLabel} {label}
+  next to the validation \l{QPushButton} {button}.
+
+  \section2 Validating XML Instance Documents
+
+  You can select one of the three predefined XML schemas and for each schema
+  an valid or invalid instance document. A click on the 'Validate' button will
+  validate the content of the XML instance editor against the schema from the
+  XML schema viewer. As you can modify the content of the instance editor, different
+  instances can be tested and validation error messages analysed.
+
+  \section1 Code Walk-Through
+
+  The example's main() function creates the standard instance of
+  QApplication. Then it creates an instance of the mainwindow class, shows it,
+  and starts the Qt event loop:
+
+  \snippet examples/xmlpatterns/schema/main.cpp 0
+
+  \section2 The UI Class: MainWindow
+
+  The example's UI is a conventional Qt GUI application inheriting
+  QMainWindow and the class generated by \l{Qt Designer Manual} {Qt
+  Designer}:
+
+  \snippet examples/xmlpatterns/schema/mainwindow.h 0
+
+  The constructor fills the schema and instance \l{QComboBox} selections with the predefined
+  schemas and instances and connects their \l{QComboBox::currentIndexChanged()} {currentIndexChanged()}
+  signals to the window's \c{schemaSelected()} resp. \c{instanceSelected()} slot.
+  Furthermore the signal-slot connections for the validation \l{QPushButton} {button}
+  and the instance \l{QTextEdit} {editor} are set up.
+
+  The call to \c{schemaSelected(0)} and \c{instanceSelected(0)} will trigger the validation
+  of the initial Contact Schema example.
+
+  \snippet examples/xmlpatterns/schema/mainwindow.cpp 0
+
+  In the \c{schemaSelected()} slot the content of the instance \l{QComboBox} {selection}
+  is adapted to the selected schema and the corresponding schema is loaded from the
+  \l{The Qt Resource System} {resource file} and displayed in the schema \l{QTextBrowser} {viewer}.
+  At the end of the method a revalidation is triggered.
+
+  \snippet examples/xmlpatterns/schema/mainwindow.cpp 1
+
+  In the \c{instanceSelected()} slot the selected instance is loaded from the
+  \l{The Qt Resource System} {resource file} and loaded into the instance \l{QTextEdit} {editor}
+  an the revalidation is triggered again.
+
+  \snippet examples/xmlpatterns/schema/mainwindow.cpp 2
+
+  The \c{validate()} slot does the actual work in this example.
+  At first it stores the content of the schema \l{QTextBrowser} {viewer} and the
+  \l{QTextEdit} {editor} into temporary \l{QByteArray} {variables}.
+  Then it instanciates a \c{MessageHandler} object which inherits from
+  \l{QAbstractMessageHandler} {QAbstractMessageHandler} and is a convenience
+  class to store error messages from the XmlPatterns system.
+
+  \snippet examples/xmlpatterns/schema/mainwindow.cpp 4
+
+  After the \l{QXmlSchema} {QXmlSchema} is instanciated and the message handler set
+  on it, the \l{QXmlSchema::load()} {load()} method is called with the schema data as argument.
+  If the schema is invalid or a parsing error has occured, \l{QXmlSchema::isValid()} {isValid()}
+  returns \c{false} and the error is flagged in \c{errorOccurred}.
+  If the loading was successful, a \l{QXmlSchemaValidator} {QXmlSchemaValidator} is
+  instanciated and the schema passed in the constructor.
+  A call to \l{QXmlSchemaValidator::validate()} {validate()} will validate the passed
+  XML instance data against the XML schema. The return value of that method signals
+  whether the validation was successful.
+  Depending on the success the status \l{QLabel} {label} is set to 'validation successful'
+  or the error message stored in the \c{MessageHandler}
+
+  The rest of the code does only some fancy coloring and eyecandy.
+
+  \snippet examples/xmlpatterns/schema/mainwindow.cpp 3
 */
diff --git a/examples/xmlpatterns/schema/mainwindow.cpp b/examples/xmlpatterns/schema/mainwindow.cpp
index 98276a3..bee7407 100644
--- a/examples/xmlpatterns/schema/mainwindow.cpp
+++ b/examples/xmlpatterns/schema/mainwindow.cpp
@@ -45,6 +45,7 @@
 #include "mainwindow.h"
 #include "xmlsyntaxhighlighter.h"
 
+//! [4]
 class MessageHandler : public QAbstractMessageHandler
 {
     public:
@@ -85,7 +86,9 @@ class MessageHandler : public QAbstractMessageHandler
         QString m_description;
         QSourceLocation m_sourceLocation;
 };
+//! [4]
 
+//! [0]
 MainWindow::MainWindow()
 {
     setupUi(this);
@@ -110,7 +113,9 @@ MainWindow::MainWindow()
     schemaSelected(0);
     instanceSelected(0);
 }
+//! [0]
 
+//! [1]
 void MainWindow::schemaSelected(int index)
 {
     instanceSelection->clear();
@@ -133,7 +138,9 @@ void MainWindow::schemaSelected(int index)
 
     validate();
 }
+//! [1]
 
+//! [2]
 void MainWindow::instanceSelected(int index)
 {
     QFile instanceFile(QString(":/instance_%1.xml").arg((2*schemaSelection->currentIndex()) + index));
@@ -143,7 +150,9 @@ void MainWindow::instanceSelected(int index)
 
     validate();
 }
+//! [2]
 
+//! [3]
 void MainWindow::validate()
 {
     const QByteArray schemaData = schemaView->toPlainText().toUtf8();
@@ -177,6 +186,7 @@ void MainWindow::validate()
                                                            QColor(Qt::green).lighter(160).name());
     validationStatus->setStyleSheet(styleSheet);
 }
+//! [3]
 
 void MainWindow::textChanged()
 {
diff --git a/src/xmlpatterns/api/qxmlschema.cpp b/src/xmlpatterns/api/qxmlschema.cpp
index 8e14f3f..62b6a0e 100644
--- a/src/xmlpatterns/api/qxmlschema.cpp
+++ b/src/xmlpatterns/api/qxmlschema.cpp
@@ -57,6 +57,8 @@
   The QXmlSchema class loads, compiles and validates W3C XML Schema files
   that can be used further for validation of XML instance documents via
   \l{QXmlSchemaValidator}.
+
+  \sa QXmlSchemaValidator, {xmlpatterns/schema}{XML Schema Validation Example}
 */
 
 /*!
diff --git a/src/xmlpatterns/api/qxmlschemavalidator.cpp b/src/xmlpatterns/api/qxmlschemavalidator.cpp
index 7a4ce03..a69b081 100644
--- a/src/xmlpatterns/api/qxmlschemavalidator.cpp
+++ b/src/xmlpatterns/api/qxmlschemavalidator.cpp
@@ -62,6 +62,8 @@
 
   The QXmlSchemaValidator class loads, parses an XML instance document and validates it
   against a W3C XML Schema that has been compiled with \l{QXmlSchema}.
+
+  \sa QXmlSchema, {xmlpatterns/schema}{XML Schema Validation Example}
 */
 
 /*!