Events

Events enable a class or object to notify other classes or objects when something of interest occurs. Many aspects of events are similar to those of delegates so you can think of an event like it is a simpler delegate specialized for some particular use.

Events provide a way for SIMPL# code to send notifications to SIMPL+. A SIMPL+ Module can subscribe to a SIMPL# event, and when SIMPL# raises that event, the subscribed SIMPL+ event handler function will be called.

When a SIMPL# event is fired, the originating (publishing) class instance is passed to the subscribed SIMPL+ event. This instance is called the ‘sender’. Note that an event can have multiple subscribers or none at all. Events that have no subscribers are never raised. there is also no limit to the number of events that could be published or subscribed to.

Events in SIMPL# can also be implemented with delegates. The delegate is defined in the publishing class and the subscribing class(es) create a method which matches the signature of the delegate. When the event is raised, the methods of the subscribing class are invoked through the delegate.

A method that handles an event is called an event handler. An event handler is declared as you would declare a delegate.

NOTE: Event Handler functions are asynchronous calls

To be able to use events you need to have at least the following components of code:

• Event declaration: This is the declaration of the event (in the publisher class ) that invokes the event handlers.

• Event registration: This is the subscribing code that connects the event handlers to the event.

• Code that raises the event: This is the code in the publisher that calls the event, causing it to invoke its event handlers.

Declaring an Event

The publisher must provide the event and often provides the code to raise the event.

Creating an event is simple—we only need the delegate's type and a name:

public event EventHandler MyEvent;

Notice the event should be declared public so that other classes and structs can register event handlers with it. The event will accept event handlers with the return type and signature matching the delegate type EventHandler.

Raising an Event

Raising an event is very similar to invoking a function, use the name of the event, followed by the parameter list (must match the delegate type of the event) enclosed in parentheses.

Standard Event Usage  -Basic Example

The standard, most simple form of event usage is based on the C#'sEventHandler class.

When the event is triggered, the sender (this), along with C#’s EventArgs class is passed.

SIMPL#:

	namespace SIMPLSharpLibrary1
	{
		public class ControlSystem
		{
			public event EventHandler MyEvent;

			public void TriggerEvent1Handler()
			{
				MyEvent(this, new EventArgs());
			}
		}
	}

SIMPL+:

	ControlSystem myClass;

	function Init()
	{
		RegisterEvent (myClass, MyEvent, MyEvnt_Hndlr);
	}

	eventhandler MyEvnt_Hndlr(ControlSystem sender, EventArgsargs)
	{
		if ( sender = myClass )
		{
		  //do something
		}
	}

Example 2 – deriving from EventArgs

In the example below, a class is declared deriving from C#’s EventArgs class. That class can then be populated and passed to the SIMPL+ event handler function.

SIMPL#:

	namespace SIMPLSharpLibrary1
	{
		public class MyEventArgs : EventArgs
		{
			public int ID { get; set; }

			public MyEventArgs(int id)
			{
				ID = id;
			}
		}

		public delegate void CustomHandler(object sender, MyEventArgs e);

		public class ControlSystem
		{
			public event CustomHandler MyEvent;

			public void TriggerEvent1Handler()
			{
				  MyEvent(this, new MyEventArgs(1));
			}
		}
	}

SIMPL+:

	ControlSystem myClass;

	function Init()
	{
		RegisterEvent (myClass, MyEvent, MyEvnt_Handler);
	}
		
	eventhandler MyEvnt_Hndlr(ControlSystem sender, MyEventArgsargs)
	{

	}

Example 3:

The example below shows an event implementation with delegates:

SIMPL#:

	namespace SIMPLSharpLibrary2
	{
		///<summary>
		///TestBoundary has 2 members : myBoundaryand currentValue.
		///An event will be  triggered whenever currentValue goes over myBoundary.
		///</summary>

		public class TestBoundary
		{
			private short myBoundary = 75;
			private short currentValue = 70;

			/// <summary>
			/// Definitionfor Event onOutsideBoundary
			/// </summary>
			public event BoundaryHandler onOutsideBoundary;

			/// <summary>
			/// Function Signature of the event handler for onOutsideBoundary
			/// </summary>
			/// <param name="o">reference to Object that raised the event</param>
			/// <param name="e">object of class EventArgs</param>
			public delegate void BoundaryHandler(object o, EventArgs e);

			/// <summary>
			/// Constructor
			/// </summary>
			public TestBoundary()
			{
				currentValue= 72;
			}

			/// <summary>
			/// Property for private member upperLimit
			/// </summary>
			public int MyBoundary
			{
				get { return myBoundary; }
				set { myBoundary = (short)value; }
			}

			/// <summary>
			/// Checks the new value against myBoundary
			/// and executes the event if necessary.
			/// </summary>
			public short CurrentValue
			{
				get { return currentValue; }
				set {
					if ( value > myBoundary)
					{
						if (onOutsideBoundary != null)
						{
							onOutsideBoundary(null, null);
						}
					}
					currentValue= value;
				}
			}
		}
	}

SIMPL+:

	#DEFAULT_VOLATILE
	#ENABLE_STACK_CHECKING
	#ENABLE_TRACE
	#ENCODING_ASCII
	
	#USER_SIMPLSHARP_LIBRARY "SIMPLSharpLibrary2"
	 
	ANALOG_INPUT InputValue;

	DIGITAL_OUTPUT EventTriggered;
				 
	TestBoundary myTestBoundary;

	Function Init()
	{
		RegisterEvent(myTestBoundary, onOutsideBoundary, BoundaryHandler);
	}

	eventhandler BoundaryHandler(TestBoundary sender, EventArgs args)
	{
		EventTriggered= 1;
		delay(500);
		EventTriggered= 0;
	}

	CHANGE InputValue
	{
		myTestBoundary.CurrentValue = InputValue;
	}

	Function main()
	{
		Init();
	}

Copyright (C) 2013 to the present, Crestron Electronics, Inc. All rights reserved. No part of this work may be reproduced in any form, machine or natural, without the express written consent of Crestron Electronics.