using System;
using Chernobyl.Collections.Generic;

namespace Chernobyl.StateMachine
{
    /// <summary>
    /// An interface for a state machine 
    /// (http://en.wikipedia.org/wiki/Finite-state_machine). This interface 
    /// defines both a state and a state machine in one type; this allows for
    /// states to have sub-states which also have sub-states and so on and so
    /// forth. Types implement this interface when they want to make it aware 
    /// that they have a state or can be a state of another state machine.
    /// </summary>
    public interface IState : ILinkedEnumerable<IState>
    {
        /// <summary>
        /// This event is raised when this state has become the active state. 
        /// This can happen if this instances' <see cref="ParentState"/> has been
        /// set and the <see cref="ParentState"/> <see cref="IState"/> has had 
        /// its <see cref="ChildState"/> set to this instance. It can also
        /// happen if this instance has decided to activate itself. This event 
        /// will only be raised once when the state has become active. It will not be 
        /// invoked a second time unless it is deactivated first.
        /// </summary>
        event EventHandler Entered;

        /// <summary>
        /// This event is raised when this state is no longer an active state.
        /// This can happen if this instances' <see cref="ParentState"/> has 
        /// been set and the <see cref="ParentState"/> <see cref="IState"/> has 
        /// had its <see cref="ChildState"/> set to this instance. It can also
        /// happen if this instance has decided to deactivate itself. This event 
        /// will only be raised once when the state has been deactivated. It will 
        /// not be raised a second time unless it was previously in an active 
        /// state.
        /// </summary>
        event EventHandler Left;

        /// <summary>
        /// The <see cref="IState"/> that this <see cref="IState"/> is a
        /// sub-state of or null if this <see cref="IState"/> is not sub-state
        /// of another state. When set this property will set the incoming
        /// <see cref="IState"/> instances <see cref="ChildState"/> property
        /// to this instance (unless the value set is null of course). If this 
        /// property is set to null (or in other words, this state is 
        /// deactivated), two things will occur: (1) the <see cref="Left"/> event
        /// will be raised and (2), immediately prior to raising the 
        /// <see cref="Left"/> event, this state will deactivate its child state 
        /// (or sub-state) which will deactivate its child states and so and so 
        /// forth. Deactivating sub-states is done prior to invoking the 
        /// <see cref="Left"/> event so that sub-states will be deactivated from 
        /// the lowest sub-state to the highest sub-state. For example, in a 
        /// state machine setup like so: state1 -> state2 -> state3 -> state4
        /// If state2 was deactivated, then state4 would be deactivated first
        /// (i.e., its <see cref="IState.Left"/> event would be raised first),
        /// then state3, and finally state2.
        /// </summary>
        IState ParentState { get; set; }

        /// <summary>
        /// The currently active sub-state of this <see cref="IState"/> or null
        /// if this <see cref="IState"/> doesn't currently have an active 
        /// sub-state. When set this property will set the incoming
        /// <see cref="IState"/> instances <see cref="ParentState"/> property
        /// to this instance (unless the value set is null, in which case, the 
        /// <see cref="IState.ChildState"/> this instances 
        /// <see cref="ParentState"/> is set to null).
        /// </summary>
        IState ChildState { get; set; }
    }

    /// <summary>
    /// An interface used to "mark" an <see cref="IState"/> type as being an 
    /// <see cref="IConfigurationState"/> or a state used during the initial 
    /// configuration of the application. This is the first state to be applied.
    /// </summary>
    public interface IConfigurationState : IState
    { }

    /// <summary>
    /// An interface used to "mark" an <see cref="IState"/> type as being an 
    /// <see cref="ILoadingState"/> or a state that is applied immediately after 
    /// the configuration state (see <see cref="IConfigurationState"/>) when 
    /// it is now safe to load content and handle other tasks that are dependent 
    /// on a fully configured Chernobyl.
    /// </summary>
    public interface ILoadingState : IState
    { }

    /// <summary>
    /// An interface used to "mark" an <see cref="IState"/> type as being an 
    /// <see cref="IRunningState"/> or a state used when the application is 
    /// started and running. This state is applied immediately after the loading 
    /// state (see <see cref="ILoadingState"/>).
    /// </summary>
    public interface IRunningState : IState
    { }
}