OrbitControls: Introduce listenToPointerEvents().

[Mugen87]

Related issue: #20575 (comment)

Description

Introduce listenToPointerEvents() which must be used to add event listeners for point events. The second parameter of OrbitControls is now deprecated (but still functional).

To me, the change has one minor flaw. listenToPointerEvents() does not only register event listeners to pointer events but to contextmenu, wheel and touch* events, too.

However, as far as I understand the point is to create an instance of OrbitControls without adding event listeners in the ctor. Still, the name of listenToPointerEvents() is not quite right...

[Mugen87]

https://raw.githack.com/Mugen87/three.js/dev43/examples/index.html

[mrdoob]

/cc @gaearon @drcmda

[mrdoob]

To me, the change has one minor flaw. listenToPointerEvents() does not only register event listeners to pointer events but to contextmenu, wheel and touch* events, too.

Ah, I forgot about the wheel one...

Still, the name of listenToPointerEvents() is not quite right...

Does addPointerEvents( renderer.domElement ) sound better?

[Mugen87]

It's actually the term pointer that feels not right^^. I mean considering the fact that the method adds an event listener to contextmenu and wheel. The touch events might not be that important since we eventually can replace them with pointer events some day.

[Mugen87]

Maybe as suggested in #20575 and use connect()? listenToKeyEvents() could be renamed to connectKeys() or something similar.

[drcmda]

This is fantastic, thanks!

[drcmda]

@Mugen87 is there a reason key events are not added by default but through a connect function? i wonder, couldn't these two just be combined?

[mrdoob]

How about listenToUserEvents( element )?

[Mugen87]

How about listenToUserEvents( element )?

In this case we would have OrbitControls.listenToUserEvents() and OrbitControls.listenToKeyEvents(). For simplicity, how about this combination:

controls.listenToEvents( renderer.domElement ); // default method for setup event listeners
controls.listenToKeyEvents( window ); // additional method for specific events.

The connect(), connectKey() and disconnect() pattern seems out of question, right^^?

@Mugen87 is there a reason key events are not added by default but through a connect function? i wonder, couldn't these two just be combined?

Yes, key event listeners are better placed at window whereas pointer events better fit to renderer.domElement.

[haywirez]

Don't forget about domElement.style.touchAction = 'none', I think it should be moved to the listenToUserEvents() setup call as well.

[Mugen87]

This PR is heavily outdated. I'll file a new one when we have agreed on the new API of OrbitControls.