Difference between revisions of "Event Flow"

Latest revision as of 18:55, 21 March 2018

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 standard W3C event flow which occurs in three phases - capture, target then bubble.

Unhandled Events

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 PowerUI.Input.Unhandled.

// Adding a listener to the unhandled target:

PowerUI.Input.Unhandled.addEventListener("mousedown",delegate(MouseEvent e){
    
    // They clicked on *nothing!* (straight 'through' the UI).
    
});

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:

// 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).
    
});

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 2 things you need to define:

• The Event class itself (define an event and inherit from e.g. Dom.Event)
• The addEventListener method on EventTarget which accepts your delegate and creates a listener for 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. Use type to define what the event actually is:

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

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

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, and {LOWERNAME} with the lowercase version.

For example, find and replace {NAME} with Mission, and {LOWERNAME} with mission

/// <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("{LOWERNAME}" + type){}
    
}

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

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/Widgets/WidgetEvent.cs