Refine description of when CapturedMouseEvent events are dispatched

[fred-wang]

• Align the way oncapturedmousechange is specified with similar EventHandler attributes from the "Media Capture and Streams" spec (i.e. by referring to an event type).
• Elaborate in the CapturedMouseEvent section the way events are dispatched on CaptureController objects associated to a capture-session, defining a new capturedmousechange type for them. Also move there the requirements about when to fire the event.

---

Preview | Diff

[eladalon1983]

w3c/mediacapture-screen-share#269 will be discussed in the June interim session of the WebRTC WG. Having spoken to the people from Apple and Mozilla, I believe there's a good chance we'll merge that PR. (It would be helpful if you could attend the meeting and voice your support. IIANM, Igalia is a W3C member.) Based on that, I suggest that we wait with this PR. Wdys?

[fred-wang]

@eladalon1983 Thanks for contacting people. Sure, let's wait before considering this PR. I should be able to attend the meeting.

[fred-wang]

@eladalon1983 Can you please check this one again now that w3c/mediacapture-screen-share#269 is merged?

[eladalon1983]

Also move there the requirements about when to fire the event.

I guess these events are slightly unusual (though not terribly), in that the trigger for them is not something within the current spec. Could you please help me out by referring me to a precedent or principle about where events of this type should be defined?

[fred-wang]

Also move there the requirements about when to fire the event.

I guess these events are slightly unusual (though not terribly), in that the trigger for them is not something within the current spec. Could you please help me out by referring me to a precedent or principle about where events of this type should be defined?

So to explain this PR I was trying to follow what is done in MediaCapture spec:

First for the definition of the event handler attribute (oncapturedmousechange in our case), which says it's of type EventHandler and refers to the type (capturedmousechange in our case):

onended of type EventHandler
The event type of this event handler is ended.

In MediaCapture spec, the links to event types are located in the Event summary section with a table indicating on which object the event fires, the interface and when it events are fired. I was initially considering something similar for this spec, but I noticed that the section is "non-normative" and moreover we only have one event for now in our spec...

Looking to other references to this event summary table or to the word "fire" in MediaCapture spec, one can find several places where the events are said to be fired (e.g. here for ended).

In particular there is a generic Firing a track event named e inside the MediaStreamTrackEvent section which basically tells to build a MediaStreamTrackEvent object with some parameters (bubble, cancellable, track) and dispatch it at the target. So this is what I'm doing with CapturedMouseEvents. Again since we only have one event, I thought it was easier to just define when the event is fired here.

This PR is a small iteration to improve the current situation:

• Currently, we mention when restrictions on when the events are fired in the definition of the oncapturedmousechange listener (in particular these restrictions are wrong if events are programmatically generated by CaptureController.dispatchEvent) rather than in the description of the dispatcher (which is somewhere in the captured-session).
• Currently, we don't detail how the CapturedMouseEvent objects are constructed (i.e. parameters passed to the constructor).

I guess a further improvement would be to have a "Firing a capturedmousechange" definition in the CapturedMouseEvents section and a separate section "Extended behavior in the capture-session" which would rely on that definition and elaborate on when events are fired, their frequency, when we enter/exit a surface, the surfaceX/surfaceY values passed to the constructor, etc.