Event Flow - Revision history

Bablakeluke: /* Template */

2018-03-21T18:55:28Z

‎Template

Bablakeluke: /* Unhandled Events */

2018-03-21T18:52:41Z

‎Unhandled Events

Bablakeluke: /* Unhandled Events */

2018-03-21T18:52:34Z

‎Unhandled Events

Bablakeluke: /* Template */

2017-03-18T16:51:45Z

‎Template

188.222.158.94: /* Template */

2017-03-08T13:05:06Z

‎Template

188.222.158.94: /* Defining custom events */

2017-03-08T00:00:45Z

‎Defining custom events

188.222.158.94: /* Naming conventions */

2017-03-07T23:47:14Z

‎Naming conventions

188.222.158.94: Created page with "Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://ww..."

2017-03-07T23:45:12Z

Created page with "Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://ww..."

New page

Events occur when something important happens. You can dispatch a custom event or listen to any event using the standard EventTarget interface. PowerUI follows the [https://www.w3.org/TR/uievents/#event-flow standard W3C event flow] which occurs in three phases - ''capture'', ''target'' then ''bubble''.

== Unhandled Events ==

Whenever an event going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].

<syntaxhighlight lang="csharp">

// Adding a listener to the unhandled target:

PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *nothing!* (straight 'through' the UI).

});

</syntaxhighlight>

Note that due to the way how the event flow and bubbling works, you can get the opposite situation at the root of the DOM:

<syntaxhighlight lang="csharp">

// Adding a listener to the document:

UI.document.addEventListener("mousedown",delegate(MouseEvent e){

// They clicked on *anything!* (and the event bubbled to the document, or the window).

});

</syntaxhighlight>

== Source locations ==

Events occur in multiple different modules of PowerUI so the source is a little spread out. Here's the important parts:

* PowerUI/Source/Dom/Events - ''In here is the very bottom of the event hierarchy; the EventTarget, EventListener and 'Event' .''

* PowerUI/Source/Engine/Events - ''More abstract events - KeyboardEvent, UIEvent, MouseEvent can all be found in here. The bulk of them are in the Events.cs file.''

== Defining custom events ==

If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 4 things you need to define:

* The Event class itself (define an event and inherit from e.g. Dom.Event)
* A delegate which accepts just that Event type and returns void
* An EventListener which listens for your event type
* The addEventListener method on EventTarget which accepts your delegate and creates a listener of your custom type

=== Naming conventions ===

Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent:

<syntaxhighlight lang="csharp">

// Mission complete! Fire a complete event:
MissionEvent e=new MissionEvent("complete");

// Dispatch to e.g. the main UI document:
UI.document.dispatchEvent(e);

</syntaxhighlight>

This avoids having hundreds of very specific rare events which would become difficult to maintain. You want to make it easy for yourself to fire off an event because of how useful they are (i.e. you don't want to be put off because you have to define a whole new event type!)

=== Template ===

Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name.

''For example, find and replace {NAME} with Mission''

<syntaxhighlight lang="csharp">

/// <summary>Your event object itself.
/// Add whatever properties you'd like to this.
/// Optionally swap Dom.Event for something more appropriate.</summary>
public class {NAME}Event : Dom.Event{

public class {NAME}Event(string type):base(type){}

}

/// <summary>Handler for {NAME}Event events.</summary>
public delegate void {NAME}EventDelegate({NAME}Event e);

/// <summary>The event listener for {NAME}Event events.</summary>
public class {NAME}EventListener : EventListener{

public {NAME}EventDelegate Listener;

public {NAME}EventListener({NAME}EventDelegate listener){
Listener = listener;
}

public override object Internal{
get{
return Listener;
}
}

public override void handleEvent(Dom.Event e){
Listener(({NAME}Event)e);
}
}

namespace Dom{

public partial class EventTarget{

/// <summary>Add an event listener for a {NAME}Event type of event.</summary>
public void addEventListener(string name,{NAME}EventDelegate method){
addEventListener(name,new {NAME}EventListener(method));
}
}
}

</syntaxhighlight>

If you want something to look at then the best example is WindowEvent - it contains everything in a single file for you:

* PowerUI/Source/Extras/Window System/WindowEvent.cs

@@ Line 3: / Line 3: @@
 == Unhandled Events ==
-Whenever an event ia going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].
+Whenever an event is going to be wasted, such as clicking on nothing, PowerUI dispatches the event to a special handler so you can still respond to it. That handler is [http://powerui.kulestar.com/powerdocs-2_0/classPowerUI_1_1Input.html#a573d05035b63bd0f263775209b4109c6 PowerUI.Input.Unhandled].
 <syntaxhighlight lang="csharp">

← Older revision		Revision as of 16:51, 18 March 2017
Line 94:		Line 94:


−	If you want something to look at then the best example is ~~WindowEvent~~ - it contains everything in a single file for you:	+	If you want something to look at then the best example is WidgetEvent - it contains everything in a single file for you:

−	* PowerUI/Source/Extras/~~Window System~~/~~WindowEvent~~.cs	+	* PowerUI/Source/Extras/Widgets/WidgetEvent.cs

@@ Line 84: / Line 84: @@
          /// <summary>Add an event listener for a {NAME}Event type of event.</summary>
-         public void addEventListener(string name,Action<{NAME}> method){
+         public void addEventListener(string name,Action<{NAME}Event> method){
-             addEventListener(name,new EventListener<{NAME}>(method));
+             addEventListener(name,new EventListener<{NAME}Event>(method));
+         }

@@ Line 64: / Line 64: @@
 === Template ===
-Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name.
+Here's a convenient template which defines everything you need to declare a new event type which 'just works'. Just find-and-replace {NAME} with the name you'd like to use for your event name, and {LOWERNAME} with the lowercase version.
-''For example, find and replace {NAME} with Mission''
+''For example, find and replace {NAME} with Mission, and {LOWERNAME} with mission''
 <syntaxhighlight lang="csharp">
@@ Line 75: / Line 75: @@
 public class {NAME}Event : Dom.Event{
-     public class {NAME}Event(string type):base(type){}
+     public class {NAME}Event(string type):base("{LOWERNAME}" + type){}
+}

@@ Line 41: / Line 41: @@
 == Defining custom events ==
-If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 4 things you need to define:
+If you'd like to define a custom event, you could just create a class which inherits from some other Event type and be done, however, if you want perfect integration then there are 2 things you need to define:
 * The Event class itself (define an event and inherit from e.g. Dom.Event)
-* A delegate which accepts just that Event type and returns void
+* The addEventListener method on EventTarget which accepts your delegate and creates a listener for your custom type
 === Naming conventions ===
@@ Line 79: / Line 77: @@
      public class {NAME}Event(string type):base(type){}
+}
@@ Line 110: / Line 84: @@
          /// <summary>Add an event listener for a {NAME}Event type of event.</summary>
-         public void addEventListener(string name,{NAME}EventDelegate method){
+         public void addEventListener(string name,Action<{NAME}> method){
-             addEventListener(name,new {NAME}EventListener(method));
+             addEventListener(name,new EventListener<{NAME}>(method));
+         }
+     }
+}

@@ Line 50: / Line 50: @@
 === Naming conventions ===
-Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent:
+Events should represent a ''broad category of things'' - for example, a MouseEvent rather than LeftClickEvent / RightClickEvent. A ScoreEvent and a MissionEvent rather than a PointsGainedFromMissionEvent or a MissionStartedEvent and a MissionCompletedEvent. Use type to define what the event actually is:
 <syntaxhighlight lang="csharp">