/*
 * Copyright (c) 2003 by Hyperwave AG. All rights reserved.
 * Event.js,v 1.12 2003/05/05 12:34:45 sraubal Exp
 */

/**
 * This class defines a generic event object. It provides two methods that allow
 * querying the source and the type of the event.<p>
 * Why is the source not automatically set during event dispatching? The answer lies
 * in the loss of flexibility - sometimes it migth be necessary to separate the 
 * dispatching mechanism and the object that is declared as the event source in an API.
 * <p>
 * Mind that You have to overwrite several methods and a field if You extend this 
 * class: 
 * Most important are the constructor (to correctyl comment the new properties) and the 
 * private <code>_init</code> method to implement the new properties. If You want to 
 * support the static usage, You have to overwrite the <code>onClassLoad</code> method, 
 * the <code>getInstance</code> method and the private static field <code>instance_</code>.
 * (Finally You need getter methods to access the new properties - of course.)
 *
 * @author sraubal
 * 
 * @see ojs.EventSource
 */
defineClass ( "ojs.Event",
              function ( class$ )
{
  
  /**
   * Creates a new immutable event object.<p>
   * This implementation CAN be treated as a SINGLETON (for memory usage reduction),
   * but when You do that, You must be aware of the fact that You manipulate the one 
   * and only static instance (aquired this instance via the <code>getInstance</code>
   * method. Calling the constructor returns a new instance that has nothing to do 
   * with the singleton object.
   * 
   * @param theParams.type_: String: the name of the event type
   * @param theParams.source_: ojs.EventSource: the Object that propagates this event
   *
   */
  class$.constructor = function( theParams )
  {
    if ( theParams == "__proto__")
      return;
  
    this._init(theParams);
  }

  // Copy this line if You subclass this class.
  var instance_;
  
  //-----------------------------------------------------------
  /**
   * Creates the singleton instance.<p>
   * "Override" this line with Your own type if You subclass this class.
   */
  class$.static_.onClassLoad = function( )
  {
    instance_ = new ojs.Event();
  }
  
  //-----------------------------------------------------------
  /**
   * Returns the singleton instance that represents all events sharing this class.
   * Mind that using the singleton approach means that You always work with the
   * same object (problems may occur e.g. if an event handler dispatches another event 
   * that is also represented by this singleton instance).<p>
   * "Override" this line with Your own type if You subclass this class.
   * 
   * @param theParams.type_: String: the name of the event type
   * @param theParams.source_: ojs.EventSource: an Object that propagates this event
   * 
   * @return ojs.Event: singleton instance of a simple Event
   */
  class$.static_.getInstance = function( theParams )
  {
    instance_._init(theParams);
  
    return instance_;
  }
  
  //-----------------------------------------------------------
  /**
   * Helper method us used by the constructor and the <code>getInstance</code> method
   * to fill the object with the properties.<p> 
   * This method has to be overwritten when a new event subclasses another one. It sets
   * the event specific properties that are not covered by superclasses and has to call
   * super_._init! See the following example:
   * <pre>
   * class$._init = function( theParams )
   * {
   *   class$.super_._init.call(this, theParams);
   *   
   *   this.myProperty_ = theParams.myProperty_;
   * }
   * </pre>
   * 
   * @param theParams.type_: String: the name of the event type
   * @param theParams.source_: ojs.EventSource: an Object that propagates this event
   * source of this one
   */
  class$._init = function( theParams )
  {
    this.type_ = (theParams && theParams.type_) ? theParams.type_ : "";
    this.source_ = (theParams && theParams.source_) ? theParams.source_ : null;
  }
  
  //-----------------------------------------------------------
  /**
   * Returns the type of the event. (Usually this string will be defined by a 
   * static constant in an event related class - probably in the source itself.)
   * 
   * @return String: type of event, an empty string if no type is defined
   */
  class$.getType = function()
  {
    return this.type_;
  }
  
  //-----------------------------------------------------------
  /**
   * Returns the source of the event. Most oft the time this will be the object
   * that dispatches the event, but this is no necessity.
   * 
   * @return ojs.EventSource: the source of the event
   */
  class$.getSource = function()
  {
    return this.source_;
  }

} );