FCC/Applications/Share/WayneLib_WayneLibraries/StateEngine/StateEngineEvent.cs

/*===============================================================================
 * StateEngineEvent.cs
 * 
 * Change history
 * When         Who     Comment
 * ----------   ------  ----------------------------------
 * 2006-07-18   RMa     Added Priority and ArrivalTime.
 * 2006-03-02   RMa     FXCop updates: validate eventtype in constructor.
 * 2006-02-03   RMA     FXCop updates: Changed from Event -> StateEngineEvent. (Event is a keyword)
 * 2006-01-27   RMa     Removed interface Event. Use Event class instead.
 * 2006-01-09   RMa     Added ToString() method.
 * 2005-12-05   RMa     This header added.
 * 
---------------------------------------------------------------------------------*/
using System;
using System.Collections.Generic;

namespace Wayne.Lib.StateEngine
{
    /// <summary>
    /// Event class that implements the Event interface. It is the base 
    /// class to be used to send events to states in the state machine.   
    /// </summary>
    public class StateEngineEvent
    {
        #region Fields

        private bool handled;
        private object type;
        private DateTime arrivalTime = DateTime.MinValue;
        private int priority;
        private uint sequenceNumber;
    
        #endregion

        #region Construction
        /// <summary>
        /// Initializes a new instance of the StateEngine event with the default priority 0.
        /// </summary>
        /// <param name="eventType">Object identifying the event.</param>        
        public StateEngineEvent(object eventType)
            : this(eventType, 0)
        {
        }

        /// <summary>
        /// Initializes a new instance of the StateEngine event with the specified priority
        /// </summary>
        /// <param name="eventType">Object identifying the event.</param>
        /// <param name="priority">Priority specifier, Lower number specifies that it will be handled sooner than higher numbers. Default priority is 0.</param>
        public StateEngineEvent(object eventType, int priority)
        {
            this.type = eventType;
            this.priority = priority;
        }

        #endregion

        #region Properties

        /// <summary>
        /// Indicates if the event has been handled. If the state is handled, it is the application's responsiblity
        /// to set this flag. the State engine never changes it.
        /// </summary>
        public bool Handled
        {
            get { return handled; }
            set { handled = value; }
        }

        /// <summary>
        /// Defines the type of the event. Can be any reference or value
        /// type (through boxing). Recommended is use of a user-defined enumeration.
        /// The EventType is a arbitary type, preferrably enums, but any type can be used.
        /// </summary>
        public object Type
        {
            get { return type; }
        }

        /// <summary>
        /// Specifies the priority of this event. High priority is defined by lower integers. Highest priority is thereby Int.Min.
        /// Default priority is 0.
        /// </summary>
        public int Priority
        {
            get { return priority; }
            set { priority = value; }
        }

        /// <summary>
        /// Specifies the time the event was sent into the state machine. This is used to determine 
        /// the handling order when resending events to states.
        /// </summary>
        internal DateTime ArrivalTime
        {
            get { return arrivalTime; }
            set { arrivalTime = value; }
        }

        /// <summary>
        /// Specifies an arrival sequence number that is assigned when the event is sent to a state machine.
        /// </summary>
        internal  uint SequenceNumber
        {
            get { return sequenceNumber; }
            set { sequenceNumber = value; }
        }

        #endregion

        #region Debug methods

        /// <summary>
        /// Presents the class as a string.
        /// </summary>
        /// <returns></returns>
        public virtual string ToString(string format, IFormatProvider provider)
        {
            return String.Format(provider, "Event(type={0}), Prio={1}, Arrived={2}, Sq={3}", type, priority, arrivalTime.ToString("HH:mm:ss", System.Globalization.CultureInfo.InvariantCulture), sequenceNumber);
        }

        /// <summary>
        /// Presents the class as a string using the specified culture-specific format information.
        /// </summary>
        /// <returns></returns>
        public virtual string ToString(IFormatProvider provider)
        {
            return ToString("", provider);
        }

        /// <summary>
        /// Presents the class as a string using a format string.
        /// </summary>
        /// <returns></returns>
        public virtual string ToString(string format)
        {
            return ToString(format, System.Globalization.CultureInfo.InvariantCulture);
        }

        /// <summary>
        /// Presents the class as a string using a format string and the specified culture-specific format information.
        /// </summary>
        /// <returns></returns>
        public override string ToString()
        {
            return ToString("", System.Globalization.CultureInfo.InvariantCulture);
        }

        #endregion

    }
}