UEvent

UEvent is a general message event component that can be used in unity and native .Net environment. It can provide powerful decoupling capability through event mechanism.

[中文文档]

Official QQ Group：1070645638

<!-- TOC -->

• UEvent
  • 1 Introduction
    • 1.1 Environment
    • 1.2 Folder
    • 1.3 Feature
    • 1.4 Structure
    • 1.5 Rules / Recommendations
    • 1.6 Start
  • 2 Component
    • 2.1 Event Manager
    • 2.2 Event Dispatcher
    • 2.3 Event Listener
    • 2.4 Object Listener
    • 2.5 Unity MonoListener
    • 2.6 Event Handler
      • 2.6.1 EventHandler
      • 2.6.2 EventHandler<T>
  • 3 Optional Attribute
    • 3.1 EventEnumAttribute
    • 3.2 ListenAttribute
    • 3.3 ListenTypeAttribute
    • 3.4 ListenGroupAttribute
  • 4 API
    • 4.1 Event Definition
    • 4.2 Auto Listener
    • 4.3 Manual Listener
    • 4.4 Listen Event
    • 4.5 Listen Event Type
    • 4.6 Listen Group
    • 4.7 Maunal Register / Deregister Event
    • 4.8 Dispatch Event
    • 4.9 Dispatch Event (Thread Safety for Unity)
    • 4.10 Dispatch to Target
    • 4.11 Dispatch to Group
    • 4.12 Full API
  • 5 Compatibility Features
    • 5.1 Performance Optimization
      • 5.1.1 Preloading
    • 5.2 Compatibility List
    • 5.3 >string Event
    • 5.4 class / struct Event

<!-- /TOC -->

1 Introduction

1.1 Environment

1.2 Folder

• Samples: Example folder. It can be deleted in the you project to reduce space consumption.
• CSharp: The core fully implemented by .Net, can be used independently in .Net environment.
• Unity: The additional functions implemented by unity class library, you need to work with the code in the core folder when working in unity environment.

1.3 Feature

• Support to define multiple groups of events through enumeration, and monitor by single event or by event type.
• At the same time, it supports enum / string / class / struct type event definition to minimize changes and be compatible with different projects.
• Support receiving event priority.
• Support event grouping or sending for specific target objects.
• Support specific listener to interrupt the entire listen event queue.
• It also supports common methods and delegated methods.
• Provide the ObjectListener and MonoListener base classes, so that any class can automatically register/remove listeners, and you can also implement the IEventListener interface yourself.

1.4 Structure

• EventManager -> EventDispatcher-> EventHandler
• Internal implementation : EventListener -> EventDispatcher
• External implementation : UserEventListener

1.5 Rules / Recommendations

• For each type of event, use an enumerated type such as AppEvent, GameEvent, etc. Each event type corresponds to an event dispatcher instance.
• It is possible to use only one event type per project, but it is not recommended.
• Method-type listener needs to specify the binding object, while delegate-type listener does not need to specify the object.
• For the listen method of the delegate type, if there are parameters, the parameters use the general object[] form, so eventType may need to be specified for processing.
• It is recommended to group events through multiple event enumerations, and group monitoring methods through the ListenGroupAttribute.
• When the first parameter of the method that receives the event is named eventType, the event type is automatically sent, and the other parameters are shifted backward in turn. It can be used to handle situations where multiple events trigger the same method.
• enum / string type events use the UEvent interface, class / struct type events use the UEvent<T> interface, the interface does not do Complete type constraints, but be sure to call in accordance with the convention to avoid unexpected problems.
• Although multiple types of events are supported at the same time, it is still strongly recommended to use only one type of event format in a project.

1.6 Start

Copy Events folder into UnityProject/Assets/Plugins/.

---

2 Component

2.1 Event Manager

Used to manage all event dispatchers.

2.2 Event Dispatcher

Used to manage listener registration/de-registeration and event dispatcher for a specific event type.

2.3 Event Listener

Used to manage the event listener registration/de-registration of a specified object.

2.4 Object Listener

The user class implements the event mechanism by inheriting the class or initializing the class by itself, which can automatically register and de-register the object, and provide quick-call listener registration, removal, and event distribution interfaces.

2.5 Unity MonoListener

Same as ObjectListener's interface，uesd for MonoBehaviour GameObject.

2.6 Event Handler

2.6.1 EventHandler

|Property|Description|Remarks| |-|-|-| |Type|Event definition object type|Event definition enum/string/class/struct and other objects Type, equivalent to typeof(X)| |EventType|The value of the listener event|1. For enum/string type events, it represents the specific enum value; 2. For class/struct events, it also appears as Type in the grouping definition of the listener, but it is actually An instance of this type is represented when the event is sent, and the content of the event can be included. | |Group|Monitor group|| |Target|Event target object|| |Priority|Priority|| |Interrupt|Whether to interrupt the event queue|| |Method|Listen method|For the non-parameter delegated listening, the delegate will be automatically converted to MehtodInfo for execution| |Parameters|Parameters of the listen method|| |Action|Listen delegate Action||

2.6.2 EventHandler<T>

|Property|Description|Remarks| |-|-|-| |ActionT|Listen delegate Action<T>|| |ActionArgs|Listen delegate Action<obj[]>|| |ActionTArgs|Listen delegate Action<T, object[]>||

---

3 Optional Attribute

3.1 EventEnumAttribute

This attribute is a reserved function, and it may be used to automatically acquire event definitions scattered in different assemblies by reflection in the later stage. Currently, it has no function.

3.2 ListenAttribute

It is used to mark the method that needs to listen the specified event in class. The event listener will automatically search for all methods containing this attribute and register for listen.

• Property
  • Type : Event type
  • Priority : Priority
  • Interrupt : Interrupt event queue
• Attention
  • Priority does not limit the value range, and controls itself according to the actual needs of the project. After setting a non-zero value, the event will be triggered from high to low.
  • You can mark to listen to multiple events.
  • Must be an instance object.
  • Must be a non-static method.

3.3 ListenTypeAttribute

The method with this attribute can receive all events of the specified event type, traverse all enumerations and register all listeners.

• Property
  • Type : Event enum type
  • Priority : Priority
  • Interrupt : Interrupt event queue

3.4 ListenGroupAttribute

The event will only be triggered when the event sent through the DispatchGroup interface corresponds to the group in the attribute tag.

• Property
  • Type : Event type
  • Group : Event group type
  • Priority : Priority
  • Interrupt : Interrupt event queue
• Attention
  • Monitors added using other attribute tags are not grouped by default.
  • If the group is empty, it is equivalent to ListenAttribute, and it can accept listeners from any same event without a group.

---

4 API

4.1 Event Definition

/* 
UEvent recommends using enumeration types to define events, and implement event grouping functions through different enumerations.
If you need to use string / class / struct types to define events, see the `Compatibility Features` section for details.
*/

// EventEnumAttributte is a reserved label and has no function temporarily.
[EventEnum]
public enum GameEventType
{
	GameStart,
	GameFinish,
}

4.2 Auto Listener

// Any C# class gains monitoring capabilities.
public class TestClass : EventListener
{
}

// Unity MonoBehaviour object with listen capabilities.
public class UnityTestClass : MonoEventListener
{
}

4.3 Manual Listener

// Ge