From 676d97d56a96c46cd9b9a2d6ba5d5f535f974d42 Mon Sep 17 00:00:00 2001 From: Tobias Koenig Date: Wed, 20 May 2009 21:11:14 +0200 Subject: Complete documentation of schema example and reference it from api docs --- doc/src/examples/schema.qdoc | 85 +++++++++++++++++++++++++++++ examples/xmlpatterns/schema/mainwindow.cpp | 10 ++++ src/xmlpatterns/api/qxmlschema.cpp | 2 + src/xmlpatterns/api/qxmlschemavalidator.cpp | 2 + 4 files changed, 99 insertions(+) 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} */ /*! -- cgit v0.12