Towards a Declarative SAX Framework : Part 1 - A Simple SAX-to-C#-Mapping

#region Copyright
/*********************************************************************************
 * Copyright (c) 2004 by Martin Friedrich										 *
 * Permission to freely distribute, modify and compile these sources and		 *
 * binaries as long as this copyright notice is included.						 *
 * Use of code on your risk!													 *
 * *******************************************************************************/
#endregion

namespace SaxParserSupport 
{
	/// <summary>
	/// Defines the API for XML elements that can have child elements, i.e.
	/// elements of XSD complexTypes.
	/// </summary>
	public interface XMLElement : XMLSimpleElement 
	{
		/// <summary>
		/// Looks up the <tt>XMLSimpleElement</tt> class that represents the XML
		/// element whose tag name is given by <tt>name</tt>. For elements that are
		/// prefixed by a XML namespace, the fully qualified name must as given
		/// by the <tt>System.Xml.XmlReader.Name</tt> must be given. If no 
		/// <tt>XMLSimpleElement</tt> can be found, <tt>System.Xml.XmlException</tt> is
		/// thrown.
		/// <seealso cref="SaxParserSupport.XMLSimpleElement"/>
		/// <seealso cref="SaxParserSupport.XMLDocument"/>
		/// </summary>
		/// <param name="name">The tag name of an possible child element</param>
		/// <returns>An instance of class <tt>XMLSimpleElement</tt></returns>
		/// <exception cref="System.Xml.XmlException">No matching 
		/// <tt>XmlSimpleElement</tt> class found.</exception>
		XMLSimpleElement lookupElement( string name );

		/// <summary>
		/// Adds an instance of <tt>XMLSimpleElement</tt> that is to treated as a child
		/// element.
		/// </summary>
		/// <param name="el">The element to be added</param>
		void addElement( XMLSimpleElement el );

		/// <summary>
		/// Removes a child element.
		/// </summary>
		/// <param name="el">The child element to be removed</param>
		void removeElement( XMLSimpleElement el );

		/// <summary>
		/// Callback to be executed for mixed content XML elements on encountering
		/// chunks of text. In DOM terminoly, this is the case with TextNodes
		/// </summary>
		/// <param name="txt">Contains the current chunk of text.</param>
		void onText( string txt );

		/// <summary>
		/// Callback to be executed on encountering significant whitespace.
		/// </summary>
		/// <param name="txt">Contains the encountered whitespace sequence</param>
		void onSignificantWhitespace( string txt );

		/// <summary>
		/// Callback to be executed on encountering whitespace sequences.
		/// </summary>
		/// <param name="txt">Contains the whitespace sequence.</param>
		void onWhitespace( string txt );

	}
}