Events and Event Definitions

Event handling in RT3 is split into two categories, the events themselves - which can be generated by a variety of sources - and event definitions, which is a generic way to specify criteria under which a custom defined event may be raised.

An event is simply a new type of entity, AgRtEventEntity. It has its own associated metadata because it implements IAgEntity and all of the other standard entity interfaces. The primary interface for it is IAgRtEventEntity. When an event is triggered, it is placed in the AgRt3Application EventManager property, which is an instance of the AgRt3EventManager object.

There are three primary ways an event can be triggered. First, an entity provider itself can trigger an event by inserting an event entity into RT3. This will be picked up by AgRt3EntityManager and triggered. The second way is by defining an event definition, which we will discuss in more detail shortly. Third, you can simply call the trigger method on AgRt3EventManager, causing it to be triggered.

No matter the origin, all triggered events end up in the AgRt3EventManager. Specifically, they are in the TriggeredEvents property. If you wish to receive notification whenever an event is triggered or dismissed, subscribe to the events generated by AgRt3EventManager. You can also iterate over TriggeredEvents at any time for the current list. You can dismiss an event by passing a triggered event into the Dismiss method. Finally, for a full history of all events ever triggered and dismissed system-wide, you can access the EventLog property. The ClearLog method will clear the EventLog permanently and start it anew.

Event definitions are defined by the AgRt3EventDefinition object. They allow you to sort through incoming data and, if specified criteria are met, trigger an event. An event definition is essentially a query object that almost never contains any data; in fact, that is just how it is implemented. For example, suppose that you had a query that showed you all hostile tracks within friendly airspace. In addition, suppose that normally this is a very rare occurrence; thus the query will mostly be empty. When the query matches, however, you want to know about it immediately.

AgRt3EventDefinition EventDef = new AgRt3EventDefinition();
EventDef.Query = MyHostileQuery;
EventDef.InstanceName = "HostileAirspace";
EventDef.Enabled = true;
EventDef.Description = "Hostile Aircraft in Friendly Airspace.";
EventDef.Code = 13;
EntityManager.EventDefinitions.Add(EventDef);

In the example above, whenever the criterion of MyHostileQuery is met by any entities, an event will be triggered with the relevant information. In this example, Code is simply a free form value that can be can set to whatever value you’d like to help you keep track of events; it could also be completely ignored.

Actions

An action plugin is a reusable plugin that can be associated with a specific event definition and executed whenever that event is triggered. For example, an action might play a sound or send an e-mail when a specific event occurs. Since it is an arbitrary plugin point, anything can be turned into an action. A single event definition can have any number of actions associated with it. To add them, you push them into the Actions collection property of the AgRt3EventDefinition object.

EventDef.Actions.Add(SoundAction as AGI.Realtime.Tracking.IAgRt3Action)
EventDef.Actions.Add(EmailAction as AGI.Realtime.Tracking.IAgRt3Action)

The example above assumes you have already created and configured two actions, one to play a sound and one to send an email. Once they are configured, you add them to the list.

Implementing your own action is a matter of creating an object which implements IAgRt3Action and IAgAttrConfig. IAgRt3Action only has one method, Execute, which runs the arbitrary block of code that the action defines.

Fully documented sample Action plugins are located in <STK install folder>Help/RT3/Samples. When you are ready to start testing and debugging your plugin, see Registering an RT3 Plugin. To add a custom user interface, see Implementing a Custom User Interface for an RT3 Plugin.

STK 11.2.1 Programming Interface