Class PerformanceEventBus

Namespace

CSF.Screenplay.Performances

Assembly

CSF.Screenplay.dll

Implementation of an event bus for performance-related events.

public class PerformanceEventBus : IHasPerformanceEvents, IRelaysPerformanceEvents

Inheritance

object

PerformanceEventBus

Implements

IHasPerformanceEvents

IRelaysPerformanceEvents

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This object should be used as a singleton across the lifetime of a Screenplay. As an event bus object, it is both a subscriber (a sink) which can receive events. It is also a publisher, which emits events.

The purpose of this object is to aggregate events from many instances of Performance and Actor over the duration/lifetime of the Screenplay. This way, consumers have only a single object to which they should subscribe in order to receive those events.

As you will see from the API of this object, the implementations of IHasPerformanceEvents and IRelaysPerformanceEvents are not symmetrical. Many events are published by subscribing to the events upon an Actor.

Methods

InvokeActorCreated(string, Guid)

Invokes an event indicating that a new Actor has been created and added to the IPerformance.

public void InvokeActorCreated(string actorName, Guid performanceIdentity)

Parameters

actorName string

The actor's human-readable name.

performanceIdentity Guid

A unique identifier for the current IPerformance.

InvokeActorSpotlit(string, Guid)

Invokes an event indicating that an Actor has been placed into the Spotlight of an IStage.

public void InvokeActorSpotlit(string actorName, Guid performanceIdentity)

Parameters

actorName string

The actor's human-readable name.

performanceIdentity Guid

A unique identifier for the current IPerformance.

InvokeGainedAbility(string, Guid, object)

Invokes an event indicating that a new Actor has gained an ability.

public void InvokeGainedAbility(string actorName, Guid performanceIdentity, object ability)

Parameters

actorName string

The actor's human-readable name.

performanceIdentity Guid

A unique identifier for the current IPerformance.

ability object

The ability that the actor has gained.

Remarks

Use this method only when an actor gains one or more abilities before the the SubscribeTo(Actor) method has been used to subscribe to the actor. Once the actor has been subscribed-to by an implementation of this instance, their newly-added abilities will automatically be captured.

In some circumstances where the actor is fully created and has their abilities granted BEFORE there has been an opportunity to subscribe to them, then this method is required to retrospectively trigger the abilitiy-granted event. This is applicable for actors who are created by an IPersona, which might grant the actors one or more abilities immediately, as part of their creation.

InvokePerformanceBegun(Guid, IList<IdentifierAndName>)

Invokes an event indicating that a IPerformance has begun.

public void InvokePerformanceBegun(Guid performanceIdentity, IList<IdentifierAndName> namingHierarchy)

Parameters

performanceIdentity Guid

The performance identity

namingHierarchy IList<IdentifierAndName>

The performance's hierarchical name

InvokePerformanceFinished(Guid, IList<IdentifierAndName>, bool?)

Invokes an event indicating that a IPerformance has finished.

public void InvokePerformanceFinished(Guid performanceIdentity, IList<IdentifierAndName> namingHierarchy, bool? success)

Parameters

performanceIdentity Guid

The performance identity

namingHierarchy IList<IdentifierAndName>

The performance's hierarchical name

success bool?

A value indicating whether or not the performance was a success

InvokeScreenplayEnded()

Invokes an event indicating that a Screenplay has ended.

public void InvokeScreenplayEnded()

InvokeScreenplayStarted()

Invokes an event indicating that a Screenplay has started.

public void InvokeScreenplayStarted()

InvokeSpotlightTurnedOff(Guid)

Invokes an event indicating that the Spotlight of the IStage has been 'turned off'.

public void InvokeSpotlightTurnedOff(Guid performanceIdentity)

Parameters

performanceIdentity Guid

A unique identifier for the current IPerformance.

SubscribeTo(Actor)

Subscribes to (and relays) events from the specified actor.

public void SubscribeTo(Actor actor)

Parameters

actor Actor

The actor to which this relay should subscribe.

UnsubscribeFrom(Actor)

Unsubscribes from events from the specified actor.

public void UnsubscribeFrom(Actor actor)

Parameters

actor Actor

The actor from which this relay should unsubscribe.

Remarks

This method is typically used when the actor instance is about to be disposed, such as at the end of a IPerformance.

UnsubscribeFromAllActors(Guid)

Unsubscribes from all of the events for all of the actors who are part of the the IPerformance, indicated by its identity.

public void UnsubscribeFromAllActors(Guid performanceIdentity)

Parameters

performanceIdentity Guid

The identity of a performance.

Remarks

Using this method is equivalent to calling UnsubscribeFrom(Actor) for every Actor which is participating in the specified performance.

Use this method when ending a performance, as a convenience to unsubscribe from all of its actors at once.

Events

ActorCreated

Occurs when a new Actor is created and added to the IPerformance.

public event EventHandler<ActorEventArgs> ActorCreated

Event Type

EventHandler<ActorEventArgs>

ActorSpotlit

Occurs when an Actor is placed into the Spotlight of an IStage.

public event EventHandler<ActorEventArgs> ActorSpotlit

Event Type

EventHandler<ActorEventArgs>

BeginPerformable

Occurs when an Actor begins the execution of a performable object.

public event EventHandler<PerformableEventArgs> BeginPerformable

Event Type

EventHandler<PerformableEventArgs>

EndPerformable

Occurs when an Actor ends the execution of a performable object.

public event EventHandler<PerformableEventArgs> EndPerformable

Event Type

EventHandler<PerformableEventArgs>

GainedAbility

Occurs when an Actor gains a new ability.

public event EventHandler<GainAbilityEventArgs> GainedAbility

Event Type

EventHandler<GainAbilityEventArgs>

PerformableFailed

Occurs when a performable object fails with an exception.

public event EventHandler<PerformableFailureEventArgs> PerformableFailed

Event Type

EventHandler<PerformableFailureEventArgs>

PerformableResult

Occurs when an Actor receives a result from a perfperformable objectrmance.

public event EventHandler<PerformableResultEventArgs> PerformableResult

Event Type

EventHandler<PerformableResultEventArgs>

PerformanceBegun

Occurs when a IPerformance begins executing.

public event EventHandler<PerformanceEventArgs> PerformanceBegun

Event Type

EventHandler<PerformanceEventArgs>

PerformanceFinished

Occurs when a IPerformance has finished executing.

public event EventHandler<PerformanceFinishedEventArgs> PerformanceFinished

Event Type

EventHandler<PerformanceFinishedEventArgs>

ScreenplayEnded

Occurs when a Screenplay has ended.

public event EventHandler ScreenplayEnded

Event Type

EventHandler

ScreenplayStarted

Occurs when a Screenplay starts.

public event EventHandler ScreenplayStarted

Event Type

EventHandler

SpotlightTurnedOff

Occurs when the Spotlight of an IStage is 'turned off'; the Actor who is currently spotlit is removed without being replaced.

public event EventHandler<PerformanceScopeEventArgs> SpotlightTurnedOff

Event Type

EventHandler<PerformanceScopeEventArgs>