/ 
Tk-XMLTree-0.01
/ Tk::XMLTree

NAME

Tk::XMLTree - An XML tree widget

SYNOPSIS

use Tk::XMLTree;

$top = MainWindow->new;

$xml_tree = $top->XMLTree(?options?);
$xml_tree = $top->ScrolledXMLTree(?options?);

$xml_tree->load_xml_file("file.xml");
$xml_tree->load_xml_string('<root><child /></root>');

DESCRIPTION

XMLTree graphically displays the tree structure of XML documents loaded from either an XML file or an XML string.

XMLTree enables Perl/Tk applications with a widget that allows visual representation and interaction with XML document trees.

Target applications may include XML viewers, editors and the like.

STANDARD OPTIONS

XMLTree is a subclass of Tk::Tree and therefore inherits all of its standard options.

Details on standard widget options can be found at Tk::options.

WIDGET-SPECIFIC OPTIONS

Name: pcdataMaxLength
Class: PCDATAMaxLength
Switch: -pcdatamaxlength

Set the maximum number of characters to be displayed for PCDATA elements. Content of such elements is trimmed to a length of pcdataMaxLength characters.

Default value: 80.

Name: pcdataLongSymbol
Class: PCDATALongSymbol
Switch: -pcdatalongsymbol

Set the symbol to append to PCDATA content with length greater than pcdataMaxLength characters.

Default value: ....

Name: pcdataPreserveSpace
Class: PCDATAPreserveSpace
Switch: -pcdatapreservespace

Specify whether space characters surrounding PCDATA elements should be preserved or not. Such characters are preserved if this option is set to 1 and not preserved if set to 0.

Default value: 0.

WIDGET METHODS

The XMLTree method creates a widget object. This object supports the configure and cget methods described in Tk::options which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

An XMLTree is not scrolled by default. The ScrolledXMLTree method creates a scrolled XMLTree.

The following additional methods are available for XMLTree widgets:

$xml_tree->load_xml_file($xml_filename)

Load an XML document from a file into the tree. If the tree is already loaded with an XML document, no reloading occurs and a warning message is issued.

Return value: none.

Example(s):

# load XML document from file document.xml into the tree
$xml_tree->load_xml_file('document.xml');
$xml_tree->load_xml_string($xml_string)

Load an XML document represented by a string into the tree. If the tree is already loaded with an XML document, no reloading occurs and a warning message is issued.

Return value: none.

Example(s):

# load XML document from xml string into the tree
$xml_tree->load_xml_string('<root><child /></root>');
$xml_tree->get_name()

Retrieve the name of the currently selected XML element.

Return value: name of selected element if it is mixed, undef if it is PCDATA.

Example(s):

# retrieve name of currently selected element
$element_name = $xml_tree->get_name();
$xml_tree->get_attrs()

Retrieve the attribute list of the currently selected XML element.

Return value: attributes of selected element if it is mixed, undef if it is PCDATA. Attributes are returned as an associative array, where each key/value pair represent an attribute name/value, respectively.

Example(s):

# retrieve attribute list of currently selected element
%attributes = $xml_tree->get_attrs();
$xml_tree->get_text()

Retrieve the content of the currently selected XML element.

Return value: Text content if selected element is PCDATA, undef if it is mixed.

Example(s):

# retrieve content text of currently selected element
$text = $xml_tree->get_text();
$xml_tree->is_mixed()

Indicate whether the currently selected element is mixed or not. If the element is not mixed then it is PCDATA.

Return value: TRUE if the currently selected element is mixed, FALSE if it is PCDATA.

Example(s):

# determine if selected element is mixed or not
print "element is " . ($xml_tree->is_mixed() ? 'mixed' : 'PCDATA');
$xml_tree->is_pcdata()

Indicate whether the currently selected element is PCDATA or not. If the element is not PCDATA then it is mixed.

Return value: TRUE if the currently selected element is PCDATA, FALSE if it is mixed.

Example(s):

# determine if selected element is PCDATA or not
print "element is " . ($xml_tree->is_pcdata() ? 'PCDATA' : 'mixed');

EXAMPLES

An XML viewer using Tk::XMLTree can be found in the examples directory included with this module.

VERSION

Tk::XMLTree version 0.01.

AUTHOR

Santos, José.

BUGS

Please report any bugs or feature requests to bug-tk-xmltree at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tk-XMLTree. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Documentation for this module can be found with the following perldoc command:

perldoc Tk::XMLTree

Additional information at:

COPYRIGHT AND LICENSE

Copyright (c) 2008 José Santos. All rights reserved.

This program is free software. It can redistributed and/or modified under the same terms as Perl itself.

ACKNOWLEDGEMENTS

Thanks to Cotonete, Droit, Pistacho and Barriguita.

DEDICATION

I dedicate Tk::XMLTree to my GrandMother.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 380:

Non-ASCII character seen before =encoding in 'José.'. Assuming CP1252