/*!
  @header ECXMLControlEvent
  @abstract Module of Encore
 
  @availability OS X, GNUstep
  @copyright 2004, 2005, 2006 Oliver Langer

  Author: Oliver Langer

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  <pre>
  -------------------------------------------------------------------------
  Modification history

  27.11.05 ola     initial version
  22.08.06 ola     license changed
  -------------------------------------------------------------------------
  </pre>
*/

#if !defined(__ECXMLControlEvent_H)
#define __ECXMLControlEvent_H

#include <Foundation/Foundation.h>
#include <Encore/ECObject.h>

/*!
 * @class ECXMLControlEvent
 * @abstract An event holder carrying the XML event and the current context
 */
@interface ECXMLControlEvent : ECObject {
  id eventId;
  NSString *elementName;
  
  NSString *attributeName;
  NSString *attributeValue;
  
  NSMutableDictionary *attributes;
}

/*!
 * @method eventId_elementStarted
 * @result identifying object for the event that marks the opening of an element
 * @discussion You may not call retain or release on the returned reference
 */
+ (const id) eventId_elementStarted;


/*!
 * @method eventId_elementEnded
 * @result identifying object for the event that marks the ending of an element
 * @discussion You may not call retain or release on the returned reference
 */
+ (const id) eventId_elementEnded;


/*!
 * @method eventId_addAttribute
 * @result identifying object for the event that marks the passing of an
 *   attribute value
 * @discussion You may not call retain or release on the returned reference
 */
+ (const id) eventId_addAttribute;


/*!
 * @method eventId_addAllAttributes
 * @result identifying object for the event that marks passing of all attributes
 * @discussion You may not call retain or release on the returned reference
 */
+ (const id) eventId_addAllAttributes;


/*!
 * @method initElementEndedEventWithName
 * @abstract Used to create an event that indicates the closing of an xml
 *   element type
 * @param anElementName name of the ending xml element type
 * @result self
 */
- initElementEndedEventWithName: (NSString *) anElementName;
  

/*!
 * @method initElementStartedEventWithName
 * @abstract Used to create an event that indicates the begining of an xml
 *   element type
 * @param anElementName name of the begining xml element type
 * @result self
 */
- initElementStartedEventWithName: (NSString *) anElementName
  withAttributes: (NSDictionary *) theAttributes;


/*!
 * @method initAddAttributeEventWithName
 * @abstract Creates an event used to add one attribute which is specified
 *   within an xml element.
 * @param anElementName xml element name
 * @param anAttributeName name of the attribute
 * @param anAttributeValue related value of attribute
 * @result self
 */
- initAddAttributeEventWithName: (NSString *) anElementName
  withAttributeName: (NSString *) anAttributeName
  withAttributeValue: (NSString *) anAttributeValue;
  
  
- (void) dealloc;


/*!
 * @method attributeName
 * @abstract Used to return the currently selected attribute name
 *   in case of an "eventId_addAttribute" event
 * @result name of the currently selected attribute or nil
 */
- (NSString *) attributeName;


/*!
 * @method attributeValue
 * @abstract Used to return the currently selected attribute value
 *   in case of an "eventId_addAttribute" event
 * @result value of the currently selected attribute or nil
 */
- (NSString *) attributeValue;


/*!
 * @method eventId
 * @result identifier for the event
 */
- eventId;


/*!
 * @method elementName
 * @abstract returns the name of the xml element type in case of an
 * {@link eventId_elementStarted} or {@link eventId_elementEnded} event
 * @result the name of the xml element type or nil
 */
- (NSString *) elementName;


/*!
 * @method attributes
 * @result the attributes given by the event {@link eventId_elementStarted} or
 *  nil. Note that you may change this set but while doing so you should take
 * care of any side-effects.
 */
- (NSMutableDictionary *) attributes;

@end
#endif