/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

  \example xmlpatterns/schema

  \title XML Schema Validation Example

  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

  for every definition two XML instance documents, one that is valid

  according to the schema and one that is not.

  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

*/