Complete documentation of schema example and reference it from api docs

1 files changed, 85 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
 */