1<!DOCTYPE refentry SYSTEM "tcldoc-1.0.dtd"> 2 3<refentry xmlns:xlink='http://www.w3.org/XLink'> 4 5 <refentryinfo> 6 <author xlink:href='http://www.zveno.com/staff/Steve.Ball/'> 7 <firstname>Steve</firstname> 8 <surname>Ball</surname> 9 </author> 10 <copyright> 11 <year>2002</year> 12 <holder xlink:href='http://www.zveno.com/'>Zveno Pty Ltd</holder> 13 </copyright> 14 <legalnotice> 15 <para>Zveno makes this software and all associated data and documentation ('Software') available free of charge for any purpose. Copies may be made of this Software but all of this notice must be included on any copy.</para> 16 <para>The Software was developed for research purposes and Zveno does not warrant that it is error free or fit for any purpose. Zveno disclaims any liability for all claims, expenses, losses, damages and costs any user may incur as a result of using, copying or modifying the Software.</para> 17 </legalnotice> 18 </refentryinfo> 19 20 <refmeta> 21 <refentrytitle>TclDOM</refentrytitle> 22 <manvolnum>n</manvolnum> 23 </refmeta> 24 25 <refnamediv> 26 <refname>::dom::DOMImplementation</refname> 27 <refname>::dom::create</refname> 28 <refname>::dom::parse</refname> 29 <refname>::dom::serialize</refname> 30 <refname>::dom::document</refname> 31 <refname>::dom::node</refname> 32 <refname>::dom::element</refname> 33 <refname>::dom::event</refname> 34 <refname>::dom::selectNode</refname> 35 36 <refpurpose>Tcl language binding for the W3C Document Object Model</refpurpose> 37 38 </refnamediv> 39 40 <refsynopsisdiv> 41 <tclcmdsynopsis> 42 <command>package require dom</command> 43 </tclcmdsynopsis> 44 45 <tclpkgsynopsis> 46 <package>dom</package> 47 <version>2.5</version> 48 </tclpkgsynopsis> 49 50 <tclnamespacesynopsis> 51 <tclnamespace>::dom</tclnamespace> 52 <tclnamespace>::dom::tcl</tclnamespace> 53 <tclnamespace>::dom::libxml2</tclnamespace> 54 </tclnamespacesynopsis> 55 56 <tclcmdsynopsis> 57 <command>::dom::DOMImplementation</command> 58 <arg><replaceable>method</replaceable></arg> 59 <group choice='opt' rep='repeat'><arg>args</arg></group> 60 </tclcmdsynopsis> 61 62 <tclcmdsynopsis> 63 <command>::dom::create</command> 64 <arg><replaceable>element</replaceable></arg> 65 </tclcmdsynopsis> 66 67 <tclcmdsynopsis> 68 <command>::dom::parse</command> 69 <arg><replaceable>xml</replaceable></arg> 70 <group choice='opt' rep='repeat'><arg>option</arg><arg>value</arg></group> 71 </tclcmdsynopsis> 72 73 <tclcmdsynopsis> 74 <command>::dom::serialize</command> 75 <arg><replaceable>token</replaceable></arg> 76 <group choice='opt' rep='repeat'><arg>option</arg><arg>value</arg></group> 77 </tclcmdsynopsis> 78 79 <tclcmdsynopsis> 80 <command>::dom::document</command> 81 <arg><replaceable>method</replaceable></arg> 82 <arg><replaceable>token</replaceable></arg> 83 <group choice='opt' rep='repeat'><arg>args</arg></group> 84 </tclcmdsynopsis> 85 86 <tclcmdsynopsis> 87 <command>::dom::node</command> 88 <arg><replaceable>method</replaceable></arg> 89 <arg><replaceable>token</replaceable></arg> 90 <group choice='opt' rep='repeat'><arg>args</arg></group> 91 </tclcmdsynopsis> 92 93 <tclcmdsynopsis> 94 <command>::dom::element</command> 95 <arg><replaceable>method</replaceable></arg> 96 <arg><replaceable>token</replaceable></arg> 97 <group choice='opt' rep='repeat'><arg>args</arg></group> 98 </tclcmdsynopsis> 99 100 <tclcmdsynopsis> 101 <command>::dom::event</command> 102 <arg><replaceable>method</replaceable></arg> 103 <arg><replaceable>token</replaceable></arg> 104 <group choice='opt' rep='repeat'><arg>args</arg></group> 105 </tclcmdsynopsis> 106 107 <tclcmdsynopsis> 108 <command>::dom::selectNode</command> 109 <arg><replaceable>token</replaceable></arg> 110 <arg><replaceable>xpath</replaceable></arg> 111 <group choice='opt' rep='repeat'><arg>option value</arg></group> 112 </tclcmdsynopsis> 113 </refsynopsisdiv> 114 115 <refsect1> 116 <title>Description</title> 117 118 <para>TclDOM is a Tcl language binding for the <ulink url='http://www.w3c.org/DOM/'>W3C Document Object Model</ulink> (DOM). DOM provides a view of a XML (or HTML) document as a tree structure. Currently, TclDOM only supports XML documents.</para> 119 120 <para>The package implements most of the DOM Level 1 interfaces and also some Level 2 and Level 3 interfaces. There are also a number of non-standard commands and methods provided for the convenience of application developers (these are documented).</para> 121 122 <para>The DOM specification should be read in conjunction with this reference manual, as it explains the meaning and purpose of the various interfaces. This manual is not a tutorial on how to use the DOM.</para> 123 124 <para>TclDOM also provides several implementations of the API, with a layered architecture. A generic layer provides a stable API to the application, and specific implementations may register themselves. Currently, three implementations exists: a pure-Tcl implementation, a C implementation (based on TclDOMPro) and another C implementation based on the Gnome libxml2 & gdome2 libraries.</para> 125 </refsect1> 126 127 <refsect1> 128 <title>Packages and Namespaces</title> 129 130 <para>The TclDOM generic layer defines the <tclpackage>dom</tclpackage> package and also a Tcl namespace using that name. The generic layer also uses the package name <tclpackage>dom::generic</tclpackage>.</para> 131 132 <para>Implementations define their own package name and Tcl namespace within the generic layer:</para> 133 <variablelist> 134 <varlistentry> 135 <term>Tcl implementation</term> 136 <listitem> 137 <para>Package <tclpackage>dom::tcl</tclpackage>, Tcl namespace <tclnamespace>::dom::tcl</tclnamespace>.</para> 138 </listitem> 139 </varlistentry> 140 <varlistentry> 141 <term>TclDOMPro</term> 142 <listitem> 143 <para>Package <tclpackage>dom::c</tclpackage>, Tcl namespace <tclnamespace>::dom::c</tclnamespace>.</para> 144 </listitem> 145 </varlistentry> 146 <varlistentry> 147 <term>libxml2</term> 148 <listitem> 149 <para>Package <tclpackage>dom::libxml2</tclpackage>, Tcl namespace <tclnamespace>::dom::libxml2</tclnamespace>.</para> 150 </listitem> 151 </varlistentry> 152 </variablelist> 153 </refsect1> 154 155 <refsect1> 156 <title>Tokens</title> 157 158 <para>The TclDOM API uses <emphasis>tokens</emphasis> as identifiers for nodes within the document tree. This technique has been used to allow alternate implementations of TclDOM to be efficient, while retaining compatibility with the pure-Tcl implementation.</para> 159 160 <para>The format of the token itself as well as the data structure referred to by the token are <emphasis>not</emphasis> public and an application should not rely on these. Instead, an application should use the accessor methods provided by the API.</para> 161 </refsect1> 162 163 <refsect1> 164 <title>DOM Interfaces</title> 165 166 <para>Each <emphasis>Interface</emphasis> in the DOM specification is implemented with a Tcl command in the <tclnamespace>dom</tclnamespace> namespace. A few interfaces have not been mapped to Tcl commands because Tcl already provides the required functionality, for example the <classname>CharacterData</classname> interface.</para> 167 168 <para><emphasis>method</emphasis>s for interfaces are methods (subcommands) of the corresponding Tcl command.</para> 169 170 <para>Each <emphasis>attribute</emphasis> of an interface is a configuration option for an object in the document tree.</para> 171 </refsect1> 172 173 <refsect1> 174 <title>Convenience Commands and Methods</title> 175 176 <para>DOM doesn't always provide an interface, method or attribute for every function required. For example, until DOM Level 3 for was no standard for creating, parsing and serializing a document. Sometimes using the standard DOM interface is awkward. TclDOM provides a number of non-standard features to overcome these problems.</para> 177 178 <para>A major convenience is that each method of the <classname>DOMImplementation</classname> interface is also defined as a command. For example, rather than using <tclcommand>dom::DOMImplementation create</tclcommand> to create a new document, the shorter command <tclcommand>dom::create</tclcommand> may be used.</para> 179 180 <para>Implementations may also provide direct access to specific features. Refer to the documentation for a DOM implementation.</para> 181 </refsect1> 182 183 <refsect1> 184 <title>Commands</title> 185 186 <refsect2> 187 <title><tclcommand>::dom::DOMImplementation</tclcommand></title> 188 <para>The <tclcommand>::dom::DOMImplementation</tclcommand> command implements the <classname>DOMImplementation</classname> DOM interface. It is used to provide implementation-specific features not explicitly defined in the DOM specification.</para> 189 190 <refsect3> 191 <title>Command Options</title> 192 <para>The following command options may be used. These are also available as commands.</para> 193 194 <variablelist> 195 196 <varlistentry> 197 <term><methodname>hasFeature</methodname></term> 198 <listitem> 199 <tclcmdsynopsis> 200 <arg>hasFeature</arg> 201 <arg><replaceable class='parameter'>feature</replaceable></arg> 202 </tclcmdsynopsis> 203 <para>Provides a test for existence of a feature. Returns <literal>1</literal> if a feature is implemented, <literal>0</literal> otherwise. Uses the default DOM implementation.</para> 204 </listitem> 205 </varlistentry> 206 207 <varlistentry> 208 <term><methodname>create</methodname></term> 209 <listitem> 210 <tclcmdsynopsis> 211 <arg>create</arg> 212 <arg choice='opt'><replaceable class='parameter'>type</replaceable></arg> 213 </tclcmdsynopsis> 214 <para>Creates the root node of a new DOM document, using the default DOM implementation. The document element type may be specified as an argument, in which case that element is created. The return value is a token referring to the root node of the newly created document.</para> 215 216 <note> 217 <para>Non-standard method. DOM Level 2 introduced the <methodname>createDocument</methodname> method.</para> 218 </note> 219 </listitem> 220 </varlistentry> 221 222 <varlistentry> 223 <term><methodname>createDocument</methodname></term> 224 <listitem> 225 <tclcmdsynopsis> 226 <arg>createDocument</arg> 227 <arg><replaceable>nsURI</replaceable></arg> 228 <arg><replaceable>type</replaceable></arg> 229 <arg choice='opt'><replaceable>doctype</replaceable></arg> 230 </tclcmdsynopsis> 231 <para>Creates the root node of a new DOM document, using the default DOM implementation. The document element namespace URI and local-name (element type) may be specified as an argument, in which case that element is created. If the document type is given then the newly created document is configured to use that document type. The return value is a token referring to the root node of the newly created document.</para> 232 </listitem> 233 </varlistentry> 234 235 <varlistentry> 236 <term><methodname>createDocumentType</methodname></term> 237 <listitem> 238 <tclcmdsynopsis> 239 <arg>createDocumentType</arg> 240 <arg><replaceable>token</replaceable></arg> 241 <arg><replaceable>name</replaceable></arg> 242 <arg><replaceable>publicid</replaceable></arg> 243 <arg><replaceable>systemid</replaceable></arg> 244 <arg><replaceable>internaldtd</replaceable></arg> 245 </tclcmdsynopsis> 246 <para>Creates a Document Type Declaration, using the default DOM implementation. The return value is a token for the newly created document type declaration.</para> 247 </listitem> 248 </varlistentry> 249 250 <varlistentry> 251 <term><methodname>createNode</methodname></term> 252 <listitem> 253 <tclcmdsynopsis> 254 <arg>createNode</arg> 255 <arg><replaceable>token</replaceable></arg> 256 <arg><replaceable>xpath</replaceable></arg> 257 </tclcmdsynopsis> 258 <para>May create a node in the document. <option><replaceable>token</replaceable></option> specifies a context for the XPath expression given by <option><replaceable>xpath</replaceable></option>. The expression must resolve to a node. If the node exists then no further action is taken. Otherwise the node is created. The token of the matched or newly created node is returned.</para> 259 260 <note> 261 <para>Non-standard method.</para> 262 </note> 263 </listitem> 264 </varlistentry> 265 266 <varlistentry> 267 <term><methodname>destroy</methodname></term> 268 <listitem> 269 <tclcmdsynopsis> 270 <arg>destroy</arg> 271 <arg><replaceable class='parameter'>token</replaceable></arg> 272 </tclcmdsynopsis> 273 <para>This method frees all data structures associated with a DOM node. The <option><replaceable class='parameter'>token</replaceable></option> argument must refer to a valid token for any node in the document tree. The node is removed from the tree before it is destroyed. If the node has children, they will also be destroyed.</para> 274 </listitem> 275 </varlistentry> 276 277 <varlistentry> 278 <term><methodname>isNode</methodname></term> 279 <listitem> 280 <tclcmdsynopsis> 281 <arg>isNode</arg> 282 <arg><replaceable>token</replaceable></arg> 283 </tclcmdsynopsis> 284 <para>Tests whether the given token is a valid token for some DOM node in the default DOM implementation.</para> 285 286 <note> 287 <para>Non-standard method.</para> 288 </note> 289 </listitem> 290 </varlistentry> 291 292 <varlistentry> 293 <term><methodname>parse</methodname></term> 294 <listitem> 295 <tclcmdsynopsis> 296 <arg>parse</arg> 297 <arg><replaceable class='parameter'>xml</replaceable></arg> 298 <group> 299 <arg><replaceable>option</replaceable></arg> 300 <arg><replaceable>value</replaceable></arg> 301 </group> 302 </tclcmdsynopsis> 303 <para>This method parses XML formatted text given by the <option><replaceable class='parameter'>xml</replaceable></option> argument and constructs a DOM tree for the document. The return result is the token of the root node of the newly created document.</para> 304 305 <para>This method requires an event-based XML parser to be loaded to perform the parsing operation. The <tclpackage>dom</tclpackage> package itself does not include an XML parser. Support for the use of <ulink url="http://tclxml.sourceforge.net/">TclXML</ulink> is provided. Any other Tcl event-based XML parser 306implementing the TclXML API may also be used. The <option>-parser</option> may be used to specify which XML parser to use.</para> 307 308 <para>In some circumstances, a DOM implementation may parse the XML document directly, for example libxml2. In this case, it may not be possible to interpose on the parsing operation.</para> 309 310 <para>Valid configuration options are:</para> 311 312 <variablelist> 313 <varlistentry> 314 <term><arg>-parser</arg> <arg><group><arg>{}</arg><arg>expat</arg><arg>tcl</arg></group></arg></term> 315 <listitem> 316 <para>This option specifies which XML parser to use to parse the XML data. If an empty string is given then the default behaviour described above is used. The value <option>expat</option> specifies that the Expat parser must be used. The value <option>tcl</option> specifies that the Tcl-only parser must be used. If an explicit value is given and that parser cannot be loaded then the command will fail, despite the fact that another parser may be available.</para> 317 </listitem> 318 </varlistentry> 319 <varlistentry> 320 <term><arg>-progresscommand</arg> <arg><replaceable>script</replaceable></arg></term> 321 <listitem> 322 <para>This option specifies a Tcl command to be invoked from time to time while the DOM tree is being constructed. The script will be invoked after a certain number of element start tags have been processed, given by the <option>-chunksize</option> option.</para> 323 </listitem> 324 </varlistentry> 325 <varlistentry> 326 <term><arg>-chunksize</arg> <arg><replaceable>integer</replaceable></arg></term> 327 <listitem> 328 <para>This option specifies how many element start tags to process before invoking the script given by the <option>-progresscommand</option> option.</para> 329 </listitem> 330 </varlistentry> 331 </variablelist> 332 </listitem> 333 </varlistentry> 334 335 <varlistentry> 336 <term><methodname>selectNode</methodname></term> 337 <listitem> 338 <tclcmdsynopsis> 339 <arg>selectNode</arg> 340 <arg><replaceable>token</replaceable></arg> 341 <arg><replaceable>xpath</replaceable></arg> 342 <group choice='opt' rep='repeat'><arg>option value</arg></group> 343 </tclcmdsynopsis> 344 <para>Resolves the XPath location path given by <option><replaceable>xpath</replaceable></option>. <option><replaceable>token</replaceable></option> is the initial context for the location path. Returns the resulting nodeset as a Tcl list.</para> 345 346 <para>The following options may be specified:</para> 347 <variablelist> 348 <varlistentry> 349 <term><option>-namespaces</option></term> 350 <listitem> 351 <para>The value for this option is a list of prefix-URI pairs. Each of these pairs defines an XML Namespace and its prefix for the purposes of evaluating the XPath expression. The document itself may use a different prefix for the same XML Namespace.</para> 352 <para>This option may be repeated, in which case the lists of namespace pairs are merged and all of the XML Namespaces registered.</para> 353 </listitem> 354 </varlistentry> 355 </variablelist> 356 357 <note> 358 <para>Non-standard method.</para> 359 </note> 360 </listitem> 361 </varlistentry> 362 363 <varlistentry> 364 <term><methodname>serialize</methodname></term> 365 <listitem> 366 <tclcmdsynopsis> 367 <arg>serialize</arg> 368 <arg><replaceable>token</replaceable></arg> 369 <group> 370 <arg><replaceable>option</replaceable></arg> 371 <arg><replaceable>value</replaceable></arg> 372 </group> 373 </tclcmdsynopsis> 374 <para>This method returns the XML formatted text corresponding to the node given by <option>token</option>. The text is guaranteed to be a well-formed XML document, unless the <option>-method</option> option specifies a non-XML output method.</para> 375 376 <para>Valid configuration options are:</para> 377 378 <variablelist> 379 <varlistentry> 380 <term><arg>-newline</arg> <arg><replaceable>elementlist</replaceable></arg></term> 381 <listitem> 382 <para>This option specifies a list of element types for which newline characters will be added before and after the start and end tags for those elements upon serialization.</para> 383 384 <para>White space is significant in XML, so the <tclpackage>dom</tclpackage> package never adds extra white spacefor purposes of "pretty-printing" the XML source document. On some platforms, such as VMS, this can actually cause serious problems due to line length limitations. This option provides the convenience of adding newlines to certain nominated element types for formatting the source into lines.</para> 385 386 <para>Examples:</para> 387 388 <para>Suppose the following DOM document is constructed:</para> 389 390 <informalexample> 391 <programlisting> 392set doc [::dom::DOMImplementation create] 393set top [::dom::document createElement $doc Root] 394set node [::dom::document createElement $top First] 395::dom::document createElement $node Second 396::dom::document createElement $top First 397</programlisting> 398 </informalexample> 399 400 <para>Without the <option>-newline</option> option the serialized document would be:</para> 401 402 <informalexample> 403 <programlisting> 404::dom::DOMImplementation serialize $doc 405<computeroutput><![CDATA[ 406<?xml version="1.0"?> 407<!DOCTYPE Root> 408<Root><First><Second/></First><First/></Root> 409]]> 410</computeroutput> 411</programlisting> 412 </informalexample> 413 414 <para>With the <option>-newline</option> option the serialized document would be:</para> 415 416 <informalexample> 417 <programlisting> 418::dom::DOMImplementation serialize $doc -newline First 419<computeroutput><![CDATA[ 420<?xml version="1.0"?> 421<!DOCTYPE Root> 422<Root> 423<First> 424<Second/> 425</First> 426<First/> 427</Root> 428]]> 429</computeroutput> 430</programlisting> 431 </informalexample> 432 </listitem> 433 </varlistentry> 434 </variablelist> 435 436 </listitem> 437 </varlistentry> 438 439 <varlistentry> 440 <term><methodname>trim</methodname></term> 441 <listitem> 442 <tclcmdsynopsis> 443 <arg>trim</arg> 444 <arg><replaceable>token</replaceable></arg> 445 </tclcmdsynopsis> 446 <para>This method removes any node containing only white space from the document tree of the node given by <option><replaceable>token</replaceable></option>.</para> 447 </listitem> 448 </varlistentry> 449 </variablelist> 450 </refsect3> 451 </refsect2> 452 453 <refsect2> 454 <title><tclcommand>::dom::document</tclcommand></title> 455 456 <para>This command implements the Document interface in the DOM specification. The most important aspect of this command are its factory methods for creating nodes.</para> 457 458 <para>The methods accepted by this command are as follows:</para> 459 460 <variablelist> 461 <varlistentry> 462 <term><methodname>cget</methodname></term> 463 <listitem> 464 <tclcmdsynopsis> 465 <methodname>cget</methodname> 466 <arg><replaceable>token</replaceable></arg> 467 <arg>-option</arg> 468 </tclcmdsynopsis> 469 <para>This method returns the value of the given configuration option.</para> 470 </listitem> 471 </varlistentry> 472 473 <varlistentry> 474 <term><methodname>configure</methodname></term> 475 <listitem> 476 <tclcmdsynopsis> 477 <methodname>configure</methodname> 478 <arg><replaceable>token</replaceable></arg> 479 <group rep='repeat'> 480 <arg><replaceable>option</replaceable></arg> 481 <arg><replaceable>value</replaceable></arg> 482 </group> 483 </tclcmdsynopsis> 484 <para>This method sets the value of the given configuration options.</para> 485 486 <para>Valid configuration options are:</para> 487 488 <variablelist> 489 <varlistentry> 490 <term><arg>-doctype</arg></term> 491 <listitem> 492 <para>Specifies the token of the Document Type Declaration node.</para> 493 494 <para>This is a read-only option. Use the factory method to create a Document Type Declaration node.</para> 495 </listitem> 496 </varlistentry> 497 <varlistentry> 498 <term><arg>-implementation</arg></term> 499 <listitem> 500 <para>Specifies the token of the document's implementation.</para> 501 502 <para>This is a read-only option.</para> 503 </listitem> 504 </varlistentry> 505 <varlistentry> 506 <term><arg>-documentElement</arg></term> 507 <listitem> 508 <para>Specifies the token of the document's document element node. A document node may only have one document element, but may have other types of children (such as comments).</para> 509 510 <para>This is a read-only option. Use the factory method to create the document element node.</para> 511 </listitem> 512 </varlistentry> 513 </variablelist> 514 </listitem> 515 </varlistentry> 516 517 <varlistentry> 518 <term><methodname>createElement</methodname></term> 519 <listitem> 520 <tclcmdsynopsis> 521 <methodname>createElement</methodname> 522 <arg><replaceable>token</replaceable></arg> 523 <arg><replaceable>type</replaceable></arg> 524 </tclcmdsynopsis> 525 <para>This method creates an element node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child element is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new element's type is given by the <option><replaceable>type</replaceable></option> argument. The new element is created with an empty attribute list.</para> 526 </listitem> 527 </varlistentry> 528 529 <varlistentry> 530 <term><methodname>createElementNS</methodname></term> 531 <listitem> 532 <tclcmdsynopsis> 533 <methodname>createElementNS</methodname> 534 <arg><replaceable>token</replaceable></arg> 535 <arg><replaceable>nsuri</replaceable></arg> 536 <arg><replaceable>qualname</replaceable></arg> 537 </tclcmdsynopsis> 538 <para>This method creates an element node in an XML Namespace as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child element is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new element is created in the XML Namespace given by the namespace URI <option><replaceable>nsuri</replaceable></option>. The new element's qualifed name (QName) is given by the <option><replaceable>qualname</replaceable></option> argument. Qualified names have the form <literal>prefix:local-part</literal>. The new element is created with an empty attribute list.</para> 539 </listitem> 540 </varlistentry> 541 542 <varlistentry> 543 <term><methodname>createDocumentFragment</methodname></term> 544 <listitem> 545 <tclcmdsynopsis> 546 <methodname>createDocumentFragment</methodname> 547 <arg><replaceable>token</replaceable></arg> 548 </tclcmdsynopsis> 549 <para>This method creates a documentFragment node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment.</para> 550 </listitem> 551 </varlistentry> 552 553 <varlistentry> 554 <term><methodname>createTextNode</methodname></term> 555 <listitem> 556 <tclcmdsynopsis> 557 <methodname>createTextNode</methodname> 558 <arg><replaceable>token</replaceable></arg> 559 <arg><replaceable>text</replaceable></arg> 560 </tclcmdsynopsis> 561 <para>This method creates a textNode node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child textNode is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new textNode is created with its value set to <option><replaceable>text</replaceable></option>.</para> 562 </listitem> 563 </varlistentry> 564 565 <varlistentry> 566 <term><methodname>createComment</methodname></term> 567 <listitem> 568 <tclcmdsynopsis> 569 <methodname>createComment</methodname> 570 <arg><replaceable>token</replaceable></arg> 571 <arg><replaceable>data</replaceable></arg> 572 </tclcmdsynopsis> 573 <para>This method creates a comment node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child comment is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new comment is created with its value set to <option><replaceable>data</replaceable></option>.</para> 574 </listitem> 575 </varlistentry> 576 577 <varlistentry> 578 <term><methodname>createCDATASection</methodname></term> 579 <listitem> 580 <tclcmdsynopsis> 581 <methodname>createCDATASection</methodname> 582 <arg><replaceable>token</replaceable></arg> 583 <arg><replaceable>text</replaceable></arg> 584 </tclcmdsynopsis> 585 <para>TclDOM does not distinguish between textNodes and CDATASection nodes. Accordingly, this method creates a textNode node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child textNode is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new node is created with its value set to <option><replaceable>text</replaceable></option> and has the attribute <option>-cdatasection</option> set to the value <literal>1</literal>.</para> 586 </listitem> 587 </varlistentry> 588 589 <varlistentry> 590 <term><methodname>createProcessingInstruction</methodname></term> 591 <listitem> 592 <tclcmdsynopsis> 593 <methodname>createProcessingInstruction</methodname> 594 <arg><replaceable>token</replaceable></arg> 595 <arg><replaceable>target</replaceable></arg> 596 <arg><replaceable>data</replaceable></arg> 597 </tclcmdsynopsis> 598 <para>This method creates a processingInstruction node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element, document or documentFragment. The new, child processingInstruction is added as the last child of <option><replaceable>token</replaceable></option>'s list of children. The new node is created with its name set to <option><replaceable>target</replaceable></option> and its value set to <option><replaceable>data</replaceable></option>.</para> 599 </listitem> 600 </varlistentry> 601 602 <varlistentry> 603 <term><methodname>createAttribute</methodname></term> 604 <listitem> 605 <tclcmdsynopsis> 606 <methodname>createAttribute</methodname> 607 <arg><replaceable>token</replaceable></arg> 608 <arg><replaceable>name</replaceable></arg> 609 </tclcmdsynopsis> 610 <para>This method creates an attribute node for the given element specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type element. The new attribute is created with its name set to <option><replaceable>name</replaceable></option> and an empty value.</para> 611 <note> 612 <para>This method is included for completeness with respect to the DOM specification. The preferred method for setting element attributes is to use the <tclcommand>::dom::element</tclcommand> command.</para> 613 </note> 614 </listitem> 615 </varlistentry> 616 617 <varlistentry> 618 <term><methodname>createEntity</methodname></term> 619 <listitem> 620 <tclcmdsynopsis> 621 <methodname>createEntity</methodname> 622 <arg><replaceable>token</replaceable></arg> 623 </tclcmdsynopsis> 624 <para>Not currently implemented.</para> 625 </listitem> 626 </varlistentry> 627 628 <varlistentry> 629 <term><methodname>createEntityReference</methodname></term> 630 <listitem> 631 <tclcmdsynopsis> 632 <methodname>createEntityReference</methodname> 633 <arg><replaceable>token</replaceable></arg> 634 <arg><replaceable>name</replaceable></arg> 635 </tclcmdsynopsis> 636 <para>Not currently implemented.</para> 637 </listitem> 638 </varlistentry> 639 640 <varlistentry> 641 <term><methodname>createDocTypeDecl</methodname></term> 642 <listitem> 643 <tclcmdsynopsis> 644 <methodname>createDocTypeDecl</methodname> 645 <arg><replaceable>token</replaceable></arg> 646 <arg><replaceable>name</replaceable></arg> 647 <arg><replaceable>extid</replaceable></arg> 648 <arg><replaceable>dtd</replaceable></arg> 649 <arg><replaceable>entities</replaceable></arg> 650 <arg><replaceable>notations</replaceable></arg> 651 </tclcmdsynopsis> 652 <para>This method creates a Document Type Declaration node as a child of the given node specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type document. <option><replaceable>name</replaceable></option> is the element type of the document element. If the document already has a document element then this name must match with that element type. <option><replaceable>extid</replaceable></option> is an external identifier to include in the document type declaration. <option><replaceable>dtd</replaceable></option> is an internal DTD subset to include in the document type declaration. This is specified as XML text. <option><replaceable>entities</replaceable></option> and <option><replaceable>notations</replaceable></option> are included for completeness with the DOM specification, but are not currently implemented.</para> 653 654 <para><emphasis>Non-standard:</emphasis> This method is not a standard method as specified by the DOM Recommendation, see <tclcommand>::dom::DOMImplementation <methodname>createDocumentType</methodname></tclcommand>.</para> 655 </listitem> 656 </varlistentry> 657 658 <varlistentry> 659 <term><methodname>createEvent</methodname></term> 660 <listitem> 661 <tclcmdsynopsis> 662 <methodname>createEvent</methodname> 663 <arg><replaceable>token</replaceable></arg> 664 <arg><replaceable>name</replaceable></arg> 665 </tclcmdsynopsis> 666 <para>This method creates an event node in the document specified by <option><replaceable>token</replaceable></option>. <option><replaceable>token</replaceable></option> must be a node of type document. The event type is specified by <option><replaceable>name</replaceable></option>.</para> 667 </listitem> 668 </varlistentry> 669 670 <varlistentry> 671 <term><methodname>getElementsByTagName</methodname></term> 672 <listitem> 673 <tclcmdsynopsis> 674 <methodname>getElementsByTagName</methodname> 675 <arg><replaceable>token</replaceable></arg> 676 <arg><replaceable>name</replaceable></arg> 677 </tclcmdsynopsis> 678 <para>This method searches the node given by the argument <option><replaceable>token</replaceable></option> for child elements with a type matching the argument <option><replaceable>name</replaceable></option>. The name <literal>*</literal> matches all elements. All descendants of <option><replaceable>token</replaceable></option> are searched. This method returns a "live-list"; the return result of this method is the name of a Tcl variable, the content of which is a Tcl list containing tokens for all elements that match.</para> 679 </listitem> 680 </varlistentry> 681 682 </variablelist> 683 </refsect2> 684 685 <refsect2> 686 <title><tclcommand>dom::node</tclcommand></title> 687 688 <para>This command implements generic functions for DOM nodes.</para> 689 690 <para>The methods accepted by this command are as follows:</para> 691 692 <variablelist> 693 <varlistentry> 694 <term><methodname>cget</methodname></term> 695 <listitem> 696 <tclcmdsynopsis> 697 <methodname>cget</methodname> 698 <arg><replaceable>token</replaceable></arg> 699 <arg>option</arg> 700 </tclcmdsynopsis> 701 702 <para>This method returns the value of the given configuration option for the node given by <option><replaceable>token</replaceable></option>.</para> 703 </listitem> 704 </varlistentry> 705 706 <varlistentry> 707 <term><methodname>configure</methodname></term> 708 <listitem> 709 <tclcmdsynopsis> 710 <methodname>configure</methodname> 711 <arg><replaceable>token</replaceable></arg> 712 <group rep='repeat'> 713 <arg><replaceable>option</replaceable></arg> 714 <arg><replaceable>value</replaceable></arg> 715 </group> 716 </tclcmdsynopsis> 717 718 <para>This method sets the value of the given configuration option for the node given by <option><replaceable>token</replaceable></option>.</para> 719 720 <para>Valid configuration options are as follows:</para> 721 722 <variablelist> 723 <varlistentry> 724 <term><arg>-nodeName</arg></term> 725 <listitem> 726 <para>Returns the node name. This is a read-only option.</para> 727 728 <para>The DOM specification gives the meaning of names for different types of nodes. For example, the <option>-nodeName</option> option of an element node is the element type.</para> 729 </listitem> 730 </varlistentry> 731 <varlistentry> 732 <term><arg>-nodeType</arg></term> 733 <listitem> 734 <para>Returns the type of the node given by <option><replaceable>token</replaceable></option>. This is a read-only option.</para> 735 </listitem> 736 </varlistentry> 737 <varlistentry> 738 <term><option>-parentNode</option></term> 739 <listitem> 740 <para>Returns the parent node of the node given by <option><replaceable>token</replaceable></option>. This is a read-only option.</para> 741 </listitem> 742 </varlistentry> 743 <varlistentry> 744 <term><option>-childNodes</option></term> 745 <listitem> 746 <para>Returns the name of a Tcl variable which contains a list of the children of the node given by <option><replaceable>token</replaceable></option>. The variable contains the "live" list of children. This is a read-only option.</para> 747 </listitem> 748 </varlistentry> 749 <varlistentry> 750 <term><option>-firstChild</option></term> 751 <listitem> 752 <para>Returns the first child node of the node given by <option><replaceable>token</replaceable></option>. This is a read-only option.</para> 753 </listitem> 754 </varlistentry> 755 <varlistentry> 756 <term><option>-lastChild</option></term> 757 <listitem> 758 <para>Returns the last child node of the node given by <option><replaceable>token</replaceable></option>. This is a read-only option.</para> 759 </listitem> 760 </varlistentry> 761 <varlistentry> 762 <term><option>-previousSibling</option></term> 763 <listitem> 764 <para>Returns the parent's child node which appears before this node. If this child is the first child of its parent then returns an empty string. This is a read-only option.</para> 765 </listitem> 766 </varlistentry> 767 <varlistentry> 768 <term><option>-nextSibling</option></term> 769 <listitem> 770 <para>Returns the parent's child node which appears after this node. If this child is the last child of its parent then returns an empty string. This is a read-only option.</para> 771 </listitem> 772 </varlistentry> 773 <varlistentry> 774 <term><option>-attributes</option></term> 775 <listitem> 776 <para>Returns the name of a Tcl array variable which contains the attribute list for an element node. If the node is not an element type node then returns an empty string. The indices of the array are attribute names, and the values of the array elements are their corresponding attribute values. This is a read-only option.</para> 777 </listitem> 778 </varlistentry> 779 <varlistentry> 780 <term><option>-nodeValue</option> <arg><replaceable>data</replaceable></arg></term> 781 <listitem> 782 <para>Specifies the value of a node. The DOM specification gives the meaning of values for different types of nodes. For example, the <option>-nodeValue</option> option of a textNode node is the node's text.</para> 783 </listitem> 784 </varlistentry> 785 </variablelist> 786 </listitem> 787 </varlistentry> 788 789 <valistentry> 790 <term><methodname>insertBefore</methodname></term> 791 <listitem> 792 <tclcmdsynopsis> 793 <methodname>insertBefore</methodname> 794 <arg><replaceable>token</replaceable></arg> 795 <arg><replaceable>newchild</replaceable></arg> 796 <arg choice='opt'><replaceable>refchild</replaceable></arg> 797 </tclcmdsynopsis> 798 <para>This method removes the node given by <option><replaceable>newchild</replaceable></option> from its parent. If no <option><replaceable>refchild</replaceable></option> argument is given then <option><replaceable>newchild</replaceable></option> is appended to <option><replaceable>token</replaceable></option>'s list of children. If the <option><replaceable>refchild</replaceable></option> argument is given then this method adds <option><replaceable>newchild</replaceable></option> as a child of <option><replaceable>token</replaceable></option>. The new child node is positioned before the node <option><replaceable>refchild</replaceable></option> in <option><replaceable>token</replaceable></option>'s list of children. Returns an empty string.</para> 799 </listitem> 800 </valistentry> 801 802 <valistentry> 803 <term><methodname>replaceChild</methodname></term> 804 <listitem> 805 <tclcmdsynopsis> 806 <methodname>replaceChild</methodname> 807 <arg><replaceable>token</replaceable></arg> 808 <arg><replaceable>newchild</replaceable></arg> 809 <arg><replaceable>oldchild</replaceable></arg> 810 </tclcmdsynopsis> 811 <para>This method removes the node given by <option><replaceable>newchild</replaceable></option> from its parent. It then also removes the node given by <option><replaceable>oldchild</replaceable></option> from <option><replaceable>token</replaceable></option>. <option><replaceable>newchild</replaceable></option> is then added as a child of <option><replaceable>token</replaceable></option> in <option><replaceable>oldchild</replaceable></option>'s original position in the list of children. The method returns the token <option><replaceable>oldchild</replaceable></option>, which will now have no parent.</para> 812 </listitem> 813 </valistentry> 814 815 <valistentry> 816 <term><methodname>removeChild</methodname></term> 817 <listitem> 818 <tclcmdsynopsis> 819 <methodname>removeChild</methodname> 820 <arg><replaceable>token</replaceable></arg> 821 <arg><replaceable>oldchild</replaceable></arg> 822 </tclcmdsynopsis> 823 <para>This method removes the node given by <option><replaceable>oldchild</replaceable></option> from its parent, <option><replaceable>token</replaceable></option>. The method returns the token <option><replaceable>oldchild</replaceable></option>, which will now have no parent.</para> 824 </listitem> 825 </valistentry> 826 827 <valistentry> 828 <term><methodname>appendChild</methodname></term> 829 <listitem> 830 <tclcmdsynopsis> 831 <methodname>appendChild</methodname> 832 <arg><replaceable>token</replaceable></arg> 833 <arg><replaceable>newchild</replaceable></arg> 834 </tclcmdsynopsis> 835 <para>This method removes the node given by <option><replaceable>newchild</replaceable></option> from its parent. <option><replaceable>newchild</replaceable></option> is then appended to the end of the list of children for node <option><replaceable>token</replaceable></option>. The method returns the token <option><replaceable>newchild</replaceable></option>.</para> 836 </listitem> 837 </valistentry> 838 839 <valistentry> 840 <term><methodname>hasChildNodes</methodname></term> 841 <listitem> 842 <tclcmdsynopsis> 843 <methodname>hasChildNodes</methodname> 844 <arg><replaceable>token</replaceable></arg> 845 </tclcmdsynopsis> 846 <para>Returns <literal>1</literal> if the given node has any child nodes, <literal>0</literal> otherwise.</para> 847 </listitem> 848 </valistentry> 849 850 <valistentry> 851 <term><methodname>cloneNode</methodname></term> 852 <listitem> 853 <tclcmdsynopsis> 854 <methodname>cloneNode</methodname> 855 <arg><replaceable>token</replaceable></arg> 856 <arg choice='opt'><replaceable>deep</replaceable></arg> 857 </tclcmdsynopsis> 858 <para>This method makes a copy the node given by <option><replaceable>token</replaceable></option>. If the argument <option><replaceable>deep</replaceable></option> is not specified or has the value <literal>0</literal> then only the node itself is copied, not its children. If the argument <option><replaceable>deep</replaceable></option> has the value <literal>1</literal> then <option><replaceable>token</replaceable></option>'s children are also copied recursively. This method returns the token of the newly created node. This new node will have no parent.</para> 859 </listitem> 860 </valistentry> 861 862 <valistentry> 863 <term><methodname>children</methodname></term> 864 <listitem> 865 <tclcmdsynopsis> 866 <methodname>children</methodname> 867 <arg><replaceable>token</replaceable></arg> 868 </tclcmdsynopsis> 869 <para>This is a convenience method which returns the list of child nodes for the given node as a (static) Tcl list.</para> 870 871 <para>This is not a standard DOM method for this interface.</para> 872 </listitem> 873 </valistentry> 874 875 <valistentry> 876 <term><methodname>parent</methodname></term> 877 <listitem> 878 <tclcmdsynopsis> 879 <methodname>parent</methodname> 880 <arg><replaceable>token</replaceable></arg> 881 </tclcmdsynopsis> 882 <para>This is a convenience method which returns the parent node for the given node.</para> 883 884 <para>This is not a standard DOM method for this interface.</para> 885 </listitem> 886 </valistentry> 887 </variablelist> 888 </refsect2> 889 890 <refsect2> 891 <title><tclcommand>dom::element</tclcommand></title> 892 893 <para>This command provides functions for element type nodes.</para> 894 895 <para>Valid methods for this command are as follows:</para> 896 897 <variablelist> 898 <varlistentry> 899 <term><methodname>cget</methodname></term> 900 <listitem> 901 <tclcmdsynopsis> 902 <methodname>cget</methodname> 903 <arg><replaceable>token</replaceable></arg> 904 <arg><replaceable>option</replaceable></arg> 905 </tclcmdsynopsis> 906 <para>This method returns the current setting of configuration options for an element. See the <methodname>configure</methodname> method for the list of valid configuration options.</para> 907 </listitem> 908 </varlistentry> 909 910 <varlistentry> 911 <term><methodname>configure</methodname></term> 912 <listitem> 913 <tclcmdsynopsis> 914 <methodname>configure</methodname> 915 <arg><replaceable>token</replaceable></arg> 916 <group rep='repeat'> 917 <arg><replaceable>option</replaceable></arg> 918 <arg><replaceable>value</replaceable></arg> 919 </group> 920 </tclcmdsynopsis> 921 <para>This method sets configuration options for an element. Note that element type nodes only have read-only options.</para> 922 923 <para>Valid configuration options are as follows:</para> 924 925 <variablelist> 926 <varlistentry> 927 <term><option>-tagName</option> <arg><replaceable>name</replaceable></arg></term> 928 <listitem>The tag name, or element type, of this element.</listitem> 929 </varlistentry> 930 <varlistentry> 931 <term><option>-empty</option> <arg><replaceable>boolean</replaceable></arg></term> 932 <listitem> 933 <para>Sets whether this element was specified as an empty element when the document was parsed. That is, XML empty element syntax such as <literal><Empty/></literal> was used.</para> 934 935 <para>This option has no effect upon output (serialization) of the XML document. Empty element syntax is automatically used where appropriate.</para> 936 </listitem> 937 </varlistentry> 938 </variablelist> 939 </listitem> 940 </varlistentry> 941 942 <varlistentry> 943 <term><methodname>getAttribute</methodname></term> 944 <listitem> 945 <tclcmdsynopsis> 946 <methodname>getAttribute</methodname> 947 <arg><replaceable>token</replaceable></arg> 948 <arg><replaceable>name</replaceable></arg> 949 </tclcmdsynopsis> 950 <para>This method returns the attribute value of the attribute given by <option><replaceable>name</replaceable></option>. If the attribute does not exist, then an empty string is returned.</para> 951 </listitem> 952 </varlistentry> 953 954 <varlistentry> 955 <term><methodname>setAttribute</methodname></term> 956 <listitem> 957 <tclcmdsynopsis> 958 <methodname>setAttribute</methodname> 959 <arg><replaceable>token</replaceable></arg> 960 <arg><replaceable>name</replaceable></arg> 961 <arg><replaceable>value</replaceable></arg> 962 </tclcmdsynopsis> 963 <para>This method sets the attribute value of the attribute given by <option><replaceable>name</replaceable></option>. If the attribute already exists then its value is replaced, otherwise the attribute is created.</para> 964 </listitem> 965 </varlistentry> 966 967 <varlistentry> 968 <term><methodname>removeAttribute</methodname></term> 969 <listitem> 970 <tclcmdsynopsis> 971 <methodname>removeAttribute</methodname> 972 <arg><replaceable>token</replaceable></arg> 973 <arg><replaceable>name</replaceable></arg> 974 </tclcmdsynopsis> 975 <para>This method deletes the attribute given by <option><replaceable>name</replaceable></option>. If the attribute does not exist then the method has no effect.</para> 976 </listitem> 977 </varlistentry> 978 979 <varlistentry> 980 <term><methodname>getAttributeNode</methodname></term> 981 <listitem> 982 <tclcmdsynopsis> 983 <methodname>getAttributeNode</methodname> 984 <arg><replaceable>token</replaceable></arg> 985 <arg><replaceable>name</replaceable></arg> 986 </tclcmdsynopsis> 987 <para>Not implemented.</para> 988 </listitem> 989 </varlistentry> 990 991 <varlistentry> 992 <term><methodname>setAttributeNode</methodname></term> 993 <listitem> 994 <tclcmdsynopsis> 995 <methodname>setAttributeNode</methodname> 996 <arg><replaceable>token</replaceable></arg> 997 <arg><replaceable>name</replaceable></arg> 998 </tclcmdsynopsis> 999 <para>Not implemented.</para> 1000 </listitem> 1001 </varlistentry> 1002 1003 <varlistentry> 1004 <term><methodname>removeAttributeNode</methodname></term> 1005 <listitem> 1006 <tclcmdsynopsis> 1007 <methodname>removeAttributeNode</methodname> 1008 <arg><replaceable>token</replaceable></arg> 1009 <arg><replaceable>name</replaceable></arg> 1010 </tclcmdsynopsis> 1011 <para>Not implemented.</para> 1012 </listitem> 1013 </varlistentry> 1014 1015 <varlistentry> 1016 <term><methodname>getElementsByTagName</methodname></term> 1017 <listitem> 1018 <tclcmdsynopsis> 1019 <methodname>getElementsByTagName</methodname> 1020 <arg><replaceable>token</replaceable></arg> 1021 <arg><replaceable>name</replaceable></arg> 1022 </tclcmdsynopsis> 1023 <para>This method searches the node given by the argument <option><replaceable>token</replaceable></option> for descendant child elements with a type matching the argument <option><replaceable>name</replaceable></option>. The wildcard character <literal>*</literal> matches any element type. The return result is a "live-list" which is represented by a Tcl variable. This method returns the name of the Tcl variable that contains the list of tokens that match.</para> 1024 </listitem> 1025 </varlistentry> 1026 1027 <varlistentry> 1028 <term><methodname>normalize</methodname></term> 1029 <listitem> 1030 <tclcmdsynopsis> 1031 <methodname>normalize</methodname> 1032 <arg><replaceable>token</replaceable></arg> 1033 </tclcmdsynopsis> 1034 <para>This method recursively coalesces textNodes within the children of the given node. textNodes which are adjacent in the DOM tree cannot be distinguished in the serialized XML document.</para> 1035 </listitem> 1036 </varlistentry> 1037 </variablelist> 1038 </refsect2> 1039 1040 <refsect2> 1041 <title><tclcommand>dom::processinginstruction</tclcommand></title> 1042 1043 <para>This command provides functions for processingInstruction type nodes.</para> 1044 1045 <para>Valid methods for this command are as follows:</para> 1046 1047 <variablelist> 1048 <varlistentry> 1049 <term><methodname>cget</methodname></term> 1050 <listitem> 1051 <tclcmdsynopsis> 1052 <methodname>cget</methodname> 1053 <arg><replaceable>token</replaceable></arg> 1054 <arg><replaceable>option</replaceable></arg> 1055 </tclcmdsynopsis> 1056 <para>This method returns the current setting of configuration options for an element. See the <methodname>configure</methodname> method for the list of valid configuration options.</para> 1057 </listitem> 1058 </varlistentry> 1059 1060 <varlistentry> 1061 <term><methodname>configure</methodname></term> 1062 <listitem> 1063 <tclcmdsynopsis> 1064 <methodname>configure</methodname> 1065 <arg><replaceable>token</replaceable></arg> 1066 <group rep='repeat'> 1067 <arg><replaceable>option</replaceable></arg> 1068 <arg><replaceable>value</replaceable></arg> 1069 </group> 1070 </tclcmdsynopsis> 1071 <para>This method sets configuration options for a processing instruction.</para> 1072 1073 <para>Valid configuration options are as follows:</para> 1074 1075 <variablelist> 1076 <varlistentry> 1077 <term><option>-target</option> <arg><replaceable>name</replaceable></arg></term> 1078 <listitem>This option sets the target of the processing instruction. This is a read-only configuration option.</listitem> 1079 </varlistentry> 1080 <varlistentry> 1081 <term><option>-data</option> <arg><replaceable>data</replaceable></arg></term> 1082 <listitem> 1083 <para>This option sets the data of the processing instruction.</para> 1084 </listitem> 1085 </varlistentry> 1086 </variablelist> 1087 </listitem> 1088 </varlistentry> 1089 </variablelist> 1090 </refsect2> 1091 1092 <refsect2> 1093 <title><tclcommand>dom::event</tclcommand></title> 1094 1095 <para>This command provides functions for event type nodes.</para> 1096 1097 <para>Valid methods for this command are as follows:</para> 1098 1099 <variablelist> 1100 <varlistentry> 1101 <term><methodname>cget</methodname></term> 1102 <listitem> 1103 <tclcmdsynopsis> 1104 <methodname>cget</methodname> 1105 <arg><replaceable>token</replaceable></arg> 1106 </tclcmdsynopsis> 1107 <para>This method retrieves configuration options for an event.</para> 1108 1109 <para>Valid configuration options are as follows:</para> 1110 1111 <variablelist> 1112 <varlistentry> 1113 <term><option>-altKey</option></term> 1114 <listitem>This option determines whether the ALT modifier key has been specified for this event.</listitem> 1115 </varlistentry> 1116 <varlistentry> 1117 <term><option>-timeStamp</option></term> 1118 <listitem> 1119 <para>This option gives the time at which the event was posted. The value is the number of milliseconds since the epoch, which is compatible with the Tcl <command>clock</command> command. </para> 1120 <note>The implementation of this method depends on the <methodname>Tcl_GetTime</methodname> function.This function only became publically available in Tcl 8.4. If a version of Tcl prior to 8.4 is being used, then this option will have the value <literal>0</literal>.</note> 1121 </listitem> 1122 </varlistentry> 1123 </variablelist> 1124 </listitem> 1125 </varlistentry> 1126 <varlistentry> 1127 <term><methodname>configure</methodname></term> 1128 <listitem> 1129 <tclcmdsynopsis> 1130 <methodname>configure</methodname> 1131 <arg><replaceable>token</replaceable></arg> 1132 <group rep='repeat'> 1133 <arg><replaceable>option</replaceable></arg> 1134 <arg><replaceable>value</replaceable></arg> 1135 </group> 1136 </tclcmdsynopsis> 1137 <para>This method sets the configuration options for an event. See the <methodname>cget</methodname> method for the list of valid configuration options.</para> 1138 </listitem> 1139 </varlistentry> 1140 </variablelist> 1141 </refsect2> 1142 </refsect1> 1143 1144 <refsect1> 1145 <title>Implementations</title> 1146 1147 <para>This section documents the various implmentations of the TclDOM API.</para> 1148 1149 <refsect2> 1150 <title>Tcl Implementation</title> 1151 1152 <para>The Tcl implementation is provided by the <tclpackage>dom::tcl</tclpackage> package.</para> 1153 1154 <para>It is a reference implementation, and implements the TclDOM API as described above.</para> 1155 1156 <para>A DOM tree using this implementation may be created using the <tclcommand>dom::tcl::create</tclcommand> command.</para> 1157 </refsect2> 1158 1159 <refsect2> 1160 <title>libxml2 Implementation</title> 1161 1162 <para>The TclDOM/libxml2 implementation is a wrapper for the <ulink url='http://xmlsoft.org/'>Gnome libxml2 library</ulink>. It is provided by the <tclpackage>dom::libxml2</tclpackage> package. It is a high-performance library, making use of Tcl objects for fast access to tree nodes.</para> 1163 1164 <para>A DOM tree using this implementation may be created using the <tclcommand>dom::libxml2::create</tclcommand> command.</para> 1165 1166 <para></para> 1167 1168 <refsect3> 1169 <title>Notes</title> 1170 1171 <itemizedlist> 1172 <listitem> 1173 <para>The <tclcommand>dom::libxml2::parse</tclcommand> command is linked directly to the libxml2 parser. It is not possible to specify TclXML configuration options (ie. callbacks). The following configuration options are valid:</para> 1174 1175 <variablelist> 1176 <varlistentry> 1177 <term><option>-- fill this in --</option></term> 1178 <listitem> 1179 <para>-- fill this in --</para> 1180 </listitem> 1181 </varlistentry> 1182 </variablelist> 1183 </listitem> 1184 1185 <listitem> 1186 <para>The implementation of most of the commands are incomplete. Missing methods and options will be documented here...</para> 1187 </listitem> 1188 </itemizedlist> 1189 </refsect3> 1190 1191 </refsect2> 1192 </refsect1> 1193 1194</refentry> 1195