doc/src/examples/schema.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29   \example xmlpatterns/schema
  30   \title XML Schema Validation Example
  31
  32   The XML Schema Validation example shows how to use QtXmlPatterns to
  33   validate XML with a W3C XML Schema.
  34
  35   \tableofcontents
  36
  37   \section1 Introduction
  38
  39   The example application shows different XML schema definitions and
  40   for every definition two XML instance documents, one that is valid
  41   according to the schema and one that is not.
  42   The user can select the valid or invalid instance document, change
  43   it and validate it again.
  44
  45   \section2 The User Interface
  46
  47   The UI for this example was created using \l{Qt Designer Manual} {Qt
  48   Designer}:
  49
  50   \image schema-example.png
  51
  52   The UI consists of three parts, at the top the XML schema \l{QComboBox} {selection}
  53   and the schema \l{QTextBrowser} {viewer}, below the XML instance \l{QComboBox} {selection}
  54   and the instance \l{QTextEdit} {editor} and at the bottom the validation status \l{QLabel} {label}
  55   next to the validation \l{QPushButton} {button}.
  56
  57   \section2 Validating XML Instance Documents
  58
  59   You can select one of the three predefined XML schemas and for each schema
  60   an valid or invalid instance document. A click on the 'Validate' button will
  61   validate the content of the XML instance editor against the schema from the
  62   XML schema viewer. As you can modify the content of the instance editor, different
  63   instances can be tested and validation error messages analysed.
  64
  65   \section1 Code Walk-Through
  66
  67   The example's main() function creates the standard instance of
  68   QApplication. Then it creates an instance of the mainwindow class, shows it,
  69   and starts the Qt event loop:
  70
  71   \snippet examples/xmlpatterns/schema/main.cpp 0
  72
  73   \section2 The UI Class: MainWindow
  74
  75   The example's UI is a conventional Qt GUI application inheriting
  76   QMainWindow and the class generated by \l{Qt Designer Manual} {Qt
  77   Designer}:
  78
  79   \snippet examples/xmlpatterns/schema/mainwindow.h 0
  80
  81   The constructor fills the schema and instance \l{QComboBox} selections with the predefined
  82   schemas and instances and connects their \l{QComboBox::currentIndexChanged()} {currentIndexChanged()}
  83   signals to the window's \c{schemaSelected()} resp. \c{instanceSelected()} slot.
  84   Furthermore the signal-slot connections for the validation \l{QPushButton} {button}
  85   and the instance \l{QTextEdit} {editor} are set up.
  86
  87   The call to \c{schemaSelected(0)} and \c{instanceSelected(0)} will trigger the validation
  88   of the initial Contact Schema example.
  89
  90   \snippet examples/xmlpatterns/schema/mainwindow.cpp 0
  91
  92   In the \c{schemaSelected()} slot the content of the instance \l{QComboBox} {selection}
  93   is adapted to the selected schema and the corresponding schema is loaded from the
  94   \l{The Qt Resource System} {resource file} and displayed in the schema \l{QTextBrowser} {viewer}.
  95   At the end of the method a revalidation is triggered.
  96
  97   \snippet examples/xmlpatterns/schema/mainwindow.cpp 1
  98
  99   In the \c{instanceSelected()} slot the selected instance is loaded from the
 100   \l{The Qt Resource System} {resource file} and loaded into the instance \l{QTextEdit} {editor}
 101   an the revalidation is triggered again.
 102
 103   \snippet examples/xmlpatterns/schema/mainwindow.cpp 2
 104
 105   The \c{validate()} slot does the actual work in this example.
 106   At first it stores the content of the schema \l{QTextBrowser} {viewer} and the
 107   \l{QTextEdit} {editor} into temporary \l{QByteArray} {variables}.
 108   Then it instanciates a \c{MessageHandler} object which inherits from
 109   \l{QAbstractMessageHandler} {QAbstractMessageHandler} and is a convenience
 110   class to store error messages from the XmlPatterns system.
 111
 112   \snippet examples/xmlpatterns/schema/mainwindow.cpp 4
 113
 114   After the \l{QXmlSchema} {QXmlSchema} is instanciated and the message handler set
 115   on it, the \l{QXmlSchema::load()} {load()} method is called with the schema data as argument.
 116   If the schema is invalid or a parsing error has occured, \l{QXmlSchema::isValid()} {isValid()}
 117   returns \c{false} and the error is flagged in \c{errorOccurred}.
 118   If the loading was successful, a \l{QXmlSchemaValidator} {QXmlSchemaValidator} is
 119   instanciated and the schema passed in the constructor.
 120   A call to \l{QXmlSchemaValidator::validate()} {validate()} will validate the passed
 121   XML instance data against the XML schema. The return value of that method signals
 122   whether the validation was successful.
 123   Depending on the success the status \l{QLabel} {label} is set to 'validation successful'
 124   or the error message stored in the \c{MessageHandler}
 125
 126   The rest of the code does only some fancy coloring and eyecandy.
 127
 128   \snippet examples/xmlpatterns/schema/mainwindow.cpp 3
 129 */