# 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. ![license](https://camo.githubusercontent.com/d3ce70178932e28ce1b29927b501afa69805074b7cdf631f38b53328992b1f37/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c73393531322f554576656e74) [![openupm](https://camo.githubusercontent.com/6e64fd43a868f0738bd0c7f1bf219792cee63260b2812b8fba1493b93005ab29/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e6c73393531322e756576656e743f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.ls9512.uevent/) ![topLanguage](https://camo.githubusercontent.com/553a0aafacd4064ade78d8cdeac7bd8ccaa7d04a96b69a26aba189e899747870/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f746f702f6c73393531322f554576656e74) ![size](https://camo.githubusercontent.com/7c2a22fca7ff440c1cd4f5152db7d65085aca59fb0fb83e9a55dd1a44702452c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6c73393531322f554576656e74) ![issue](https://camo.githubusercontent.com/49cdcc0e7f65a91375d9a981424f8f87b307c30e27c4f9df537bcf9071e3c517/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6c73393531322f554576656e74) ![last](https://camo.githubusercontent.com/88dd1cca648605096db0c390fb4ffbd888e1830ba4968095e46da2c17aab59d5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f6c73393531322f554576656e74) [[中文文档]](https://github.com/ls9512/UEvent/blob/master/README_CN.md) > Official QQ Group：[1070645638](https://jq.qq.com/?_wv=1027&k=ezkLnUln) * 1. [Introduction](https://github.com/ls9512/UEvent/raw/master/#Introduction) * 1.1. [Environment](https://github.com/ls9512/UEvent/raw/master/#Environment) * 1.2. [Folder](https://github.com/ls9512/UEvent/raw/master/#Folder) * 1.3. [Feature](https://github.com/ls9512/UEvent/raw/master/#Feature) * 1.4. [Structure](https://github.com/ls9512/UEvent/raw/master/#Structure) * 1.5. [Rules / Recommendations](https://github.com/ls9512/UEvent/raw/master/#RulesRecommendations) * 1.6. [Start](https://github.com/ls9512/UEvent/raw/master/#Start) * 2. [Component](https://github.com/ls9512/UEvent/raw/master/#Component) * 2.1. [Event Manager](https://github.com/ls9512/UEvent/raw/master/#EventManager) * 2.2. [Event Dispatcher](https://github.com/ls9512/UEvent/raw/master/#EventDispatcher) * 2.3. [Event Listener](https://github.com/ls9512/UEvent/raw/master/#EventListener) * 2.4. [Object Listener](https://github.com/ls9512/UEvent/raw/master/#ObjectListener) * 2.5. [Unity MonoListener](https://github.com/ls9512/UEvent/raw/master/#UnityMonoListener) * 2.6. [Event Handler](https://github.com/ls9512/UEvent/raw/master/#EventHandler) * 2.6.1. [EventHandler](https://github.com/ls9512/UEvent/raw/master/#EventHandler-1) * 2.6.2. [EventHandler\](https://github.com/ls9512/UEvent/raw/master/#EventHandlerT) * 3. [Optional Attribute](https://github.com/ls9512/UEvent/raw/master/#OptionalAttribute) * 3.1. [ EventEnumAttribute](https://github.com/ls9512/UEvent/raw/master/#EventEnumAttribute) * 3.2. [ListenAttribute](https://github.com/ls9512/UEvent/raw/master/#ListenAttribute) * 3.3. [ListenTypeAttribute](https://github.com/ls9512/UEvent/raw/master/#ListenTypeAttribute) * 3.4. [ListenGroupAttribute](https://github.com/ls9512/UEvent/raw/master/#ListenGroupAttribute) * 4. [API](https://github.com/ls9512/UEvent/raw/master/#API) * 4.1. [Event Definition](https://github.com/ls9512/UEvent/raw/master/#EventDefinition) * 4.2. [Auto Listener](https://github.com/ls9512/UEvent/raw/master/#AutoListener) * 4.3. [Manual Listener](https://github.com/ls9512/UEvent/raw/master/#ManualListener) * 4.4. [Listen Event](https://github.com/ls9512/UEvent/raw/master/#ListenEvent) * 4.5. [Listen Event Type](https://github.com/ls9512/UEvent/raw/master/#ListenEventType) * 4.6. [Listen Group](https://github.com/ls9512/UEvent/raw/master/#ListenGroup) * 4.7. [Maunal Register / Deregister Event](https://github.com/ls9512/UEvent/raw/master/#MaunalRegisterDeregisterEvent) * 4.8. [Dispatch Event](https://github.com/ls9512/UEvent/raw/master/#DispatchEvent) * 4.9. [Dispatch Event (Thread Safety for Unity)](https://github.com/ls9512/UEvent/raw/master/#DispatchEventThreadSafetyforUnity) * 4.10. [Dispatch to Target](https://github.com/ls9512/UEvent/raw/master/#DispatchtoTarget) * 4.11. [Dispatch to Group](https://github.com/ls9512/UEvent/raw/master/#DispatchtoGroup) * 4.12. [Full API](https://github.com/ls9512/UEvent/raw/master/#FullAPI) * 5. [Compatibility Features](https://github.com/ls9512/UEvent/raw/master/#CompatibilityFeatures) * 5.1. [Compatibility List](https://github.com/ls9512/UEvent/raw/master/#CompatibilityList) * 5.2. [string Event](https://github.com/ls9512/UEvent/raw/master/#stringEvent) * 5.3. [class / struct Event](https://github.com/ls9512/UEvent/raw/master/#classstructEvent) ## 1. Introduction ### 1.1. Environment ![Unity: 2019.4.3f1](https://camo.githubusercontent.com/7bbb7a5cb9da19d7f6469ba859167b9bb9e208bec0f5a02f181756e87d290020/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e6974792d323031372b2d626c7565) ![.NET 4.x](https://camo.githubusercontent.com/27d8a87432cf1bcbbf21e48af6eb9f42894f062e8bbd0583a7f83fc025c240e5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2e4e45542d342e782d626c7565) ### 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\** 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\ |Property|Description|Remarks| |-|-|-| |ActionT|Listen delegate Action\|| |ActionArgs|Listen delegate Action\|| |ActionTArgs|Listen delegate Action\|| *** ## 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 * **Interrup**t : 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 ``` cs /* 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 ``` cs // Any C# class gains monitoring capabilities. public class TestClass : EventListener { } // Unity MonoBehaviour object with listen capabilities. public class UnityTestClass : MonoEventListener { } ``` ### 4.3. Manual Listener ``` cs // Generate a listener for the specified object, executed when the general object is generated. var listener = new EventListener(this); // Register all the listening methods of the listener, generally executed when the object takes effect. EventListener.Register(); // Unregister all listening methods, generally executed when the object fails. EventListener.DeRegister(); ``` ### 4.4. Listen Event ``` cs // Listen to a single event, no priority. [Listen(GameEvent.GameStart)] public void TestMethod() { } // Listen to a single event, set priority and interrupt. [Listen(GameEvent.GameStart, 2, false)] public void TestMethod() { } // Monitor multiple events, no priority. [Listen(GameEvent.GameStart, GameEvent.GameEnd)] public void TestMethod() { } ``` ### 4.5. Listen Event Type ``` cs [ListenType(typeof(GameEvent))] public void TestMethod() { } ``` ### 4.6. Listen Group ``` cs [ListenGroup(GameEvent.GameStart, "Player")] public void TestMethod() { } ``` ### 4.7. Maunal Register / Deregister Event ``` cs // Add listener UEvent.Listen(eventType, this, methodInfo, group, priorty, interrupt); UEvent.Listen(eventType, action, group, priorty, interrupt); // Whether to include listener UEvent.Contains()(eventType); // Get listener with event type and target. UEvent.Get(eventType); UEvent.Get(eventType, target); // Remove listener UEvent.Remove(eventType, this, method); UEvent.Remove(eventType, action); ``` ### 4.8. Dispatch Event ``` cs UEvent.Dispatch(eventType, args); ``` ### 4.9. Dispatch Event (Thread Safety for Unity) ``` cs // This interface will delegate events to the Unity main thread for execution, only available in Unity extensions. UEvent.DispatchSafe(eventType, args); ``` ### 4.10. Dispatch to Target ``` cs UEvent.DispatchTo(eventType, target, args); ``` ### 4.11. Dispatch to Group ``` cs // If the `Group` parameter is empty, it is equivalent to calling the `Dispatch` interface, and the event will be sent to any listener method without a group. UEvent.DispatchGroup(eventType, group, args); ``` ### 4.12. Full API If you want to get the complete function of **UEvent** or call the internal interface, you can call it by using the following methods. The interface is slightly different from the quick call interface mentioned above. You can get **EventDispatcher** first through **EventManager**, then call the specific internal interface, for example: ``` cs EventManager.GetDispatcher().AddListener(eventType, action, group, priorty, interrupt); EventManager.GetDispatcher().RemoveListener(eventType, action); ``` *** ## 5. Compatibility Features ### 5.1. Compatibility List In order to be compatible with the existing event type definition methods in various projects, partial support for string / class / struct type events is provided, which can realize basic functions such as automatic/manual binding and event sending, but some functions will also be lost , See the function support list for details: |Function|Support| |---|---| |Auto / Manual listen|√| |Send event|√| |Listen priority|√| |Interrupt event queue|√| |Event group type|×| |Listen group **ListenGroupAttribute**|√| |Listen event group type **ListenTypeAttribute**|×| ### 5.2. string Event ``` cs // Define event type public static class StringEventDefine { public const string Event01 = "Event01"; public const string Event02 = "Event02"; } // Register listener UEvent.Listen(StringEventDefine.Event01, Receive); // Dispatch event UEvent.Dispatch(StringEventDefine.Event01, "Message"); // Remove listener UEvent.Remove(StringEventDefine.Event01, Receive); // Receive method public void Receive(string message) { Console.WriteLine(message); } ``` ### 5.3. class / struct Event ``` cs // Define event type public class ClassEventDefine { public string Message; } // Register listener UEvent.Listen(Receive); // Dispatch event UEvent.Dispatch(new ClassEventDefine() { Message = "Message" }); // Remove listener UEvent.Remove(Receive); // Receive method public void Receive(ClassEventDefine evt) { Console.WriteLine(evt.Message); } ```