1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qabstractxmlreceiver.cpp -->
<title>Qt 4.8: QAbstractXmlReceiver Class Reference</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="modules.html">Modules</a></li>
<li><a href="qtxmlpatterns.html">QtXmlPatterns</a></li>
<li>QAbstractXmlReceiver</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#xquery-sequences">XQuery Sequences</a></li>
</ul>
</div>
<h1 class="title">QAbstractXmlReceiver Class Reference</h1>
<!-- $$$QAbstractXmlReceiver-brief -->
<p>The QAbstractXmlReceiver class provides a callback interface for transforming the output of a <a href="qxmlquery.html">QXmlQuery</a>. <a href="#details">More...</a></p>
<!-- @@@QAbstractXmlReceiver -->
<pre class="cpp"> <span class="preprocessor">#include <QAbstractXmlReceiver></span></pre><p><b>Inherited by: </b><a href="qxmlserializer.html">QXmlSerializer</a>.</p>
<p><b>Note:</b> All functions in this class are <a href="threads-reentrancy.html#reentrant">reentrant</a>.</p>
<p>This class was introduced in Qt 4.4.</p>
<ul>
<li><a href="qabstractxmlreceiver-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#QAbstractXmlReceiver">QAbstractXmlReceiver</a></b> ()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#dtor.QAbstractXmlReceiver">~QAbstractXmlReceiver</a></b> ()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#atomicValue">atomicValue</a></b> ( const QVariant & <i>value</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#attribute">attribute</a></b> ( const QXmlName & <i>name</i>, const QStringRef & <i>value</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#characters">characters</a></b> ( const QStringRef & <i>value</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#comment">comment</a></b> ( const QString & <i>value</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#endDocument">endDocument</a></b> () = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#endElement">endElement</a></b> () = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#endOfSequence">endOfSequence</a></b> () = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#namespaceBinding">namespaceBinding</a></b> ( const QXmlName & <i>name</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#processingInstruction">processingInstruction</a></b> ( const QXmlName & <i>target</i>, const QString & <i>value</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#startDocument">startDocument</a></b> () = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#startElement">startElement</a></b> ( const QXmlName & <i>name</i> ) = 0</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> virtual void </td><td class="memItemRight bottomAlign"><b><a href="qabstractxmlreceiver.html#startOfSequence">startOfSequence</a></b> () = 0</td></tr>
</table>
<a name="details"></a>
<!-- $$$QAbstractXmlReceiver-description -->
<div class="descr">
<h2>Detailed Description</h2>
<p>The QAbstractXmlReceiver class provides a callback interface for transforming the output of a <a href="qxmlquery.html">QXmlQuery</a>.</p>
<p>QAbstractXmlReceiver is an abstract base class that provides a callback interface for receiving an <a href="#xquery-sequence">XQuery sequence</a>, usually the output of an <a href="qxmlquery.html">QXmlQuery</a>, and transforming that sequence into a structure of your choosing, usually XML. Consider the example:</p>
<pre class="cpp"> <span class="type"><a href="qxmlquery.html">QXmlQuery</a></span> query;
query<span class="operator">.</span>setQuery(<span class="string">"doc('index.html')/html/body/p[1]"</span>);
<span class="type"><a href="qxmlserializer.html">QXmlSerializer</a></span> serializer(query<span class="operator">,</span> myOutputDevice);
query<span class="operator">.</span>evaluateTo(<span class="operator">&</span>serializer);</pre>
<p>First it constructs a <a href="qxmlquery.html">query</a> that gets the first paragraph from document <tt>index.html</tt>. Then it constructs an <a href="qxmlserializer.html">XML serializer</a> with the <a href="qxmlquery.html">query</a> and <a href="qiodevice.html">myOutputDevice</a> (Note the <a href="qxmlserializer.html">serializer</a> is an <i>XML receiver</i>, ie a subclass of QAbstractXmlReceiver). Finally, it <a href="qxmlquery.html#evaluateTo">evaluates</a> the <a href="qxmlquery.html">query</a>, producing an ordered sequence of calls to the <a href="qxmlserializer.html">serializer's</a> callback functions. The sequence of callbacks transforms the query output to XML and writes it to <a href="qiodevice.html">myOutputDevice</a>.</p>
<p>Although the example uses <a href="qxmlquery.html">QXmlQuery</a> to produce the sequence of callbacks to functions in QAbstractXmlReceiver, you can call the callback functions directly as long as your sequence of calls represents a valid <a href="#xquery-sequence">XQuery sequence</a>.</p>
<a name="xquery-sequence"></a><a name="xquery-sequences"></a>
<h3>XQuery Sequences</h3>
<p>An <a href="xmlprocessing.html">XQuery</a> <i>sequence</i> is an ordered collection of zero, one, or many <i>items</i>. Each <i>item</i> is either an <i>atomic value</i> or a <i>node</i>. An <i>atomic value</i> is a simple data value.</p>
<p>There are six kinds of <i>nodes</i>.</p>
<ul>
<li>An <i>Element Node</i> represents an XML element.</li>
<li>An <i>Attribute Node</i> represents an XML attribute.</li>
<li>A <i>Document Node</i> represents an entire XML document.</li>
<li>A <i>Text Node</i> represents character data (element content).</li>
<li>A <i>Processing Instruction Node</i> represents an XML processing instruction, which is used in an XML document to tell the application reading the document to perform some action. A typical example is to use a processing instruction to tell the application to use a particular XSLT stylesheet to display the document.</li>
<li>And a <i>Comment node</i> represents an XML comment.</li>
</ul>
<p>The <i>sequence</i> of <i>nodes</i> and <i>atomic values</i> obeys the following rules. Note that <i>Namespace Node</i> refers to a special <i>Attribute Node</i> with name <i>xmlns</i>.</p>
<ul>
<li>Each <i>node</i> appears in the <i>sequence</i> before its children and their descendants appear.</li>
<li>A <i>node</i>'s descendants appear in the <i>sequence</i> before any of its siblings appear.</li>
<li>A <i>Document Node</i> represents an entire document. Zero or more <i>Document Nodes</i> can appear in a <i>sequence</i>, but they can only be top level items (i.e., a <i>Document Node</i> can't be a child of another <i>node</i>.</li>
<li><i>Namespace Nodes</i> immediately follow the <i>Element Node</i> with which they are associated.</li>
<li><i>Attribute Nodes</i> immediately follow the <i>Namespace Nodes</i> of the element with which they are associated, or...</li>
<li>If there are no <i>Namespace Nodes</i> following an element, then the <i>Attribute Nodes</i> immediately follow the element.</li>
<li>An <i>atomic value</i> can only appear as a top level <i>item</i>, i.e., it can't appear as a child of a <i>node</i>.</li>
<li><i>Processing Instruction Nodes</i> do not have children, and their parent is either a <i>Document Node</i> or an <i>Element Node</i>.</li>
<li><i>Comment Nodes</i> do not have children, and their parent is either a <i>Document Node</i> or an <i>Element Node</i>.</li>
</ul>
<p>The <i>sequence</i> of <i>nodes</i> and <i>atomic values</i> is sent to an QAbstractXmlReceiver (<a href="qxmlserializer.html">QXmlSerializer</a> in the example above) as a sequence of calls to the receiver's callback functions. The mapping of callback functions to sequence items is as follows.</p>
<ul>
<li><a href="qabstractxmlreceiver.html#startDocument">startDocument</a>() and <a href="qabstractxmlreceiver.html#endDocument">endDocument</a>() are called for each <i>Document Node</i> in the <i>sequence</i>. <a href="qabstractxmlreceiver.html#endDocument">endDocument</a>() is not called until all the <i>Document Node's</i> children have appeared in the <i>sequence</i>.</li>
<li><a href="qabstractxmlreceiver.html#startElement">startElement</a>() and <a href="qabstractxmlreceiver.html#endElement">endElement</a>() are called for each <i>Element Node</i>. <a href="qabstractxmlreceiver.html#endElement">endElement</a>() is not called until all the <i>Element Node's</i> children have appeared in the <i>sequence</i>.</li>
<li><a href="qabstractxmlreceiver.html#attribute">attribute</a>() is called for each <i>Attribute Node</i>.</li>
<li><a href="qabstractxmlreceiver.html#comment">comment</a>() is called for each <i>Comment Node</i>.</li>
<li><a href="qabstractxmlreceiver.html#characters">characters</a>() is called for each <i>Text Node</i>.</li>
<li><a href="qabstractxmlreceiver.html#processingInstruction">processingInstruction</a>() is called for each <i>Processing Instruction Node</i>.</li>
<li><a href="qabstractxmlreceiver.html#namespaceBinding">namespaceBinding</a>() is called for each <i>Namespace Node</i>.</li>
<li><a href="qabstractxmlreceiver.html#atomicValue">atomicValue</a>() is called for each <i>atomic value</i>.</li>
</ul>
<p>For a complete explanation of <a href="xmlprocessing.html">XQuery</a> sequences, visit <a href="http://www.w3.org/TR/xpath-datamodel/">XQuery Data Model</a>.</p>
</div>
<p><b>See also </b><a href="http://www.w3.org/TR/xpath-datamodel/">W3C XQuery 1.0 and XPath 2.0 Data Model (XDM)</a>, <a href="qxmlserializer.html">QXmlSerializer</a>, and <a href="qxmlresultitems.html">QXmlResultItems</a>.</p>
<!-- @@@QAbstractXmlReceiver -->
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QAbstractXmlReceiver[overload1]$$$QAbstractXmlReceiver -->
<h3 class="fn"><a name="QAbstractXmlReceiver"></a>QAbstractXmlReceiver::<span class="name">QAbstractXmlReceiver</span> ()</h3>
<p>Constructs an abstract xml receiver.</p>
<!-- @@@QAbstractXmlReceiver -->
<!-- $$$~QAbstractXmlReceiver[overload1]$$$~QAbstractXmlReceiver -->
<h3 class="fn"><a name="dtor.QAbstractXmlReceiver"></a>QAbstractXmlReceiver::<span class="name">~QAbstractXmlReceiver</span> ()<tt> [virtual]</tt></h3>
<p>Destroys the xml receiver.</p>
<!-- @@@~QAbstractXmlReceiver -->
<!-- $$$atomicValue[overload1]$$$atomicValueconstQVariant& -->
<h3 class="fn"><a name="atomicValue"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">atomicValue</span> ( const <span class="type"><a href="qvariant.html">QVariant</a></span> & <i>value</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when an atomic value appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. The <i>value</i> is a simple <a href="qvariant.html">data value</a>. It is guaranteed to be <a href="qvariant.html#isValid">valid</a>.</p>
<!-- @@@atomicValue -->
<!-- $$$attribute[overload1]$$$attributeconstQXmlName&constQStringRef& -->
<h3 class="fn"><a name="attribute"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">attribute</span> ( const <span class="type"><a href="qxmlname.html">QXmlName</a></span> & <i>name</i>, const <span class="type"><a href="qstringref.html">QStringRef</a></span> & <i>value</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when an attribute node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. <i>name</i> is the <a href="qxmlname.html">attribute name</a> and the <i>value</i> string contains the attribute value.</p>
<!-- @@@attribute -->
<!-- $$$characters[overload1]$$$charactersconstQStringRef& -->
<h3 class="fn"><a name="characters"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">characters</span> ( const <span class="type"><a href="qstringref.html">QStringRef</a></span> & <i>value</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when a text node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. The <i>value</i> contains the text. Adjacent text nodes may not occur in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>, i.e., this callback must not be called twice in a row.</p>
<!-- @@@characters -->
<!-- $$$comment[overload1]$$$commentconstQString& -->
<h3 class="fn"><a name="comment"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">comment</span> ( const <span class="type"><a href="qstring.html">QString</a></span> & <i>value</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when a comment node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. The <i>value</i> is the comment text, which must not contain the string "--".</p>
<!-- @@@comment -->
<!-- $$$endDocument[overload1]$$$endDocument -->
<h3 class="fn"><a name="endDocument"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">endDocument</span> ()<tt> [pure virtual]</tt></h3>
<p>This callback is called when the end of a document node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>.</p>
<!-- @@@endDocument -->
<!-- $$$endElement[overload1]$$$endElement -->
<h3 class="fn"><a name="endElement"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">endElement</span> ()<tt> [pure virtual]</tt></h3>
<p>This callback is called when the end of an element node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>.</p>
<!-- @@@endElement -->
<!-- $$$endOfSequence[overload1]$$$endOfSequence -->
<h3 class="fn"><a name="endOfSequence"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">endOfSequence</span> ()<tt> [pure virtual]</tt></h3>
<p>This callback is called once only, right after the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a> ends.</p>
<!-- @@@endOfSequence -->
<!-- $$$namespaceBinding[overload1]$$$namespaceBindingconstQXmlName& -->
<h3 class="fn"><a name="namespaceBinding"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">namespaceBinding</span> ( const <span class="type"><a href="qxmlname.html">QXmlName</a></span> & <i>name</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when a namespace binding is in scope of an element. A namespace is defined by a URI. In the <a href="qxmlname.html">QXmlName</a> <i>name</i>, the value of <a href="qxmlname.html#namespaceUri">QXmlName::namespaceUri</a>() is that URI. The value of <a href="qxmlname.html#prefix">QXmlName::prefix</a>() is the prefix that the URI is bound to. The local name is insignificant and can be an arbitrary value.</p>
<!-- @@@namespaceBinding -->
<!-- $$$processingInstruction[overload1]$$$processingInstructionconstQXmlName&constQString& -->
<h3 class="fn"><a name="processingInstruction"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">processingInstruction</span> ( const <span class="type"><a href="qxmlname.html">QXmlName</a></span> & <i>target</i>, const <span class="type"><a href="qstring.html">QString</a></span> & <i>value</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when a processing instruction appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. A processing instruction is used in an XML document to tell the application reading the document to perform some action. A typical example is to use a processing instruction to tell the application to use a particular XSLT stylesheet to process the document.</p>
<pre class="cpp"> <?xml-stylesheet type="test/xsl" href="formatter.xsl"?></pre>
<p><i>target</i> is the <a href="qxmlname.html">name</a> of the processing instruction. Its <i>prefix</i> and <i>namespace URI</i> must both be empty. Its <i>local name</i> is the target. In the above example, the name is <i>xml-stylesheet</i>.</p>
<p>The <i>value</i> specifies the action to be taken. Note that the <i>value</i> must not contain the string "?>". In the above example, the <i>value</i> is <i>type="test/xsl" href="formatter.xsl</i>.</p>
<p>Generally, use of processing instructions should be avoided, because they are not namespace aware and in many contexts are stripped out anyway. Processing instructions can often be replaced with elements from a custom namespace.</p>
<!-- @@@processingInstruction -->
<!-- $$$startDocument[overload1]$$$startDocument -->
<h3 class="fn"><a name="startDocument"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">startDocument</span> ()<tt> [pure virtual]</tt></h3>
<p>This callback is called when a document node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>.</p>
<!-- @@@startDocument -->
<!-- $$$startElement[overload1]$$$startElementconstQXmlName& -->
<h3 class="fn"><a name="startElement"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">startElement</span> ( const <span class="type"><a href="qxmlname.html">QXmlName</a></span> & <i>name</i> )<tt> [pure virtual]</tt></h3>
<p>This callback is called when a new element node appears in the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a>. <i>name</i> is the valid <a href="qxmlname.html">name</a> of the node element.</p>
<!-- @@@startElement -->
<!-- $$$startOfSequence[overload1]$$$startOfSequence -->
<h3 class="fn"><a name="startOfSequence"></a><span class="type">void</span> QAbstractXmlReceiver::<span class="name">startOfSequence</span> ()<tt> [pure virtual]</tt></h3>
<p>This callback is called once only, right before the <a href="qabstractxmlreceiver.html#xquery-sequence">sequence</a> begins.</p>
<!-- @@@startOfSequence -->
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
