API change for Issue 480 to add mouse wheel events

[BobV]

I've taken a first stab at implementing real support for mouse wheel events.

DOM.java:
- Add public static int eventGetMouseWheelVelocity(Event evt);
- Won't break anything

Event.java:
- Add ONMOUSEWHEEL constant and append it to the MOUSEEVENTS mask
- The value of MOUSEEVENTS will change, but none of the
previously-set bits will be changed. Existing logic should be fine.

MouseListener.java:
- Add public void onMouseWheel(Widget sender, int x, int y, int velocity);
- Update MouseListenerAdapter, Label, Image, Dialog boxes with no-op
functions.
- Update MouseListenerCollection
- Allows for code like:
"""
Label l = new Label("Widget");
l.addMouseListener(new MouseListenerAdapter() {
public void onMouseWheel(Widget w, int x, int y, int velocity) {
((Label)w).setText("Widget: " + velocity);
}
});
"""
- Will break all existing implementations of MouseListener that
don't inherit from MouseListenerAdapter. It's trivial to update code
with the new interface.

Discussion points:
- The signs of the velocity value are different between browsers.
Some have negative values for up, some use positive values. The
ranges are vastly different; safari has about [-1000, 1000], while FF
is [-5, 5].
- Should the velocity be presented raw, normalized (based on
arbitrary divisors), or just reduced to up/down?
- Why don't various of the DOM classes reference the fields from
Event instead of duplicating the numeric values? It's not as
succinct, but it guarantees that things will stay in sync.
- The attached patch is the current state of the work, it's
incomplete and is only verified to work on IE, FF, and Safari.

--
Bob Vawter
Google Web Toolkit Team

[John Tamplin]

On 4/11/07, BobV <bo...@google.com> wrote:

I've taken a first stab at implementing real support for mouse wheel events.

Discussion points:
  - The signs of the velocity value are different between browsers.
Some have negative values for up, some use positive values.  The
ranges are vastly different; safari has about [-1000, 1000], while FF
is [-5, 5].
  - Should the velocity be presented raw, normalized (based on
arbitrary divisors), or just reduced to up/down?

Assuming we can get the full valid range for a given browser, then I think normalizing both the sign and range is a good idea.  It seems to me apps would potentially want more than just the direction, and if that is all they want just looking at the sign should be easy enough.   Perhaps we can document that you should only use the sign if all you care about is the direction of travel, to help insulate apps from browser changes.

--
John A. Tamplin
Software Engineer, Google

[BobV]

On 4/11/07, John Tamplin <j...@google.com> wrote:
> Assuming we can get the full valid range for a given browser, then I think
> normalizing both the sign and range is a good idea. It seems to me apps
> would potentially want more than just the direction, and if that is all they
> want just looking at the sign should be easy enough. Perhaps we can
> document that you should only use the sign if all you care about is the
> direction of travel, to help insulate apps from browser changes.

Attached is an updated version of the patch that adds a new
interface: MouseWheelListener instead of extending MouseListener.
Additional support interfaces and classes were added that parallel the
existing mouse event classes.

There is also a sample app to demonstrate support. There are three
labels, one showing velocity for wheel events intercepted with
EventPreview, a count of all wheel events received, and a Label that
has a MouseWheelListener attached to it. Please verify that positive
velocities are associated with moving the mouse wheel up (i.e. away
from your wrist).

[Sandy McArthur]

I haven't looked at the patch but I have two initial observations.

On 4/12/07, BobV <bo...@google.com> wrote:
> Please verify that positive
> velocities are associated with moving the mouse wheel up (i.e. away
> from your wrist).

First, I really think positive velocities should be moving the mouse
wheel down. Two reasons:

1. In JavaScript window.scrollTo(int,int) parameters are the number of
pixels from the top left corner. Developers will expect code like
Window.scrollTo(Window.getXScroll(), Window.getYScroll() + velocity)
to work instead of having to use the inverse of the velocity.
http://developer.mozilla.org/en/docs/window.scrollTo

2. This fits more the expected output of
java.lang.Comparable.compareTo(Object) (and java.util.Comparator) and
natural ordering of Java objects. If you imagine a natural sequence
("a","b","c",...) then "a".compareTo("b") will return a negative
value. Most people would vertically layout that sequence with "a" at
the top and "z" at the bottom so a negative value would be up to
indicate before which fits with the way pixels are numbered on the
screen.

http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Comparable.html#compareTo(T)

Second, my Apple MightyMouse has a "scroll wheel" that can scroll left
and right too. I don't know if browsers yet send events for horizontal
scrolls but it's be a shame to have to introduce a third mouse event
interface to support that later. I think it's worth planning for that

--
Sandy McArthur

"He who dares not offend cannot be honest."
- Thomas Paine

[Fred Sauer]

Sandy,

Any chance horizontal scrolling gives you even values and vertical scrolling odd values in Bob's test application? (I tried digging up my old IBM ScrollPoint mice, with the familiar "eraser head" instead of a wheel or miniature track ball, but can't find drivers for my current O/S.)

I also found a reference to khtmlHorizontalWheel on Safari:
   http://www.w3.org/2006/webapi/track/issues/56

HTH
Fred

On 4/12/07, Sandy McArthur <sand...@gmail.com> wrote:

I haven't looked at the patch but I have two initial observations.

On 4/12/07, BobV <bo...@google.com> wrote:
> Please verify that positive

> velocities are associated with moving the mouse wheel up ( i.e. away

--
Fred Sauer
fr...@allen-sauer.com

[Miroslav Pokorny]

Wouldnt it be better to change the new mouse listener method

from

void onMouseWheel(Widget sender, int x, int y, int velocity);

to
void onMouseWheel( MouseWheelEvent );

and introduce a new class MouseWheelEvent with
int getX()
int getY()
int getVerticalVelocity()
Widget getSender() etc

This problem has been encountered before in GWT, using a class leaves room for expansion (eg horizontalVelocity) without breaking existing code.

With this in mind there should be no reason why anyone should need to use eventGetMouseWheelVelocity(Event evt);

--
mP

[BobV]

On 4/13/07, Miroslav Pokorny <miroslav...@gmail.com> wrote:
> Wouldnt it be better to change the new mouse listener method
>
> from
> void onMouseWheel(Widget sender, int x, int y, int velocity);
>
> to
> void onMouseWheel( MouseWheelEvent );

This isn't the pattern currently used by the DOM event handling code.
Perhaps Joel or Kelly could weigh in on this.

> With this in mind there should be no reason why anyone should need to use
> eventGetMouseWheelVelocity(Event evt);

The implementation is already browser-specific, moreso if velocity
normalization is implemented. The listeners are registered via
DOM.sinkEvents and Events are generally opaque outside of the DOM
classes, so it makes sense to do the value extraction in DOM.

Responding to Sandy's and Fred's points:
- Making velocity agree with the coordinate system for the axis makes sense.
- For multi-axis support:
- Introde MouseWheelVelocity as a container class.
- It would provide access to the un-normalized velocity data (int
getVelocityXYZ())
- Also, it would have a simplified int getDirection() that would
return constants like UP or LEFT.
- It could support even fancier devices with the additon of
constants and accessors
- The event callbacks will be changed to (Widget sender, int x, int
y, MouseWheelVelocity v)

[Kelly Norton]

This isn't the pattern currently used by the DOM event handling code.
Perhaps Joel or Kelly could weigh in on this.

We're trying to figure out the best way to get the Handler pattern implemented throughout the library. It will probably happen in the next release. At that time, we hope to have mouse handlers that receive EventObjects for every type of event. For now, though, I would rather all the listeners implement the current pattern for the sake of consistency. At least then if we end up with both listeners and handlers, they will have consistent interfaces.

/kel

[Sandy McArthur]

On 4/13/07, BobV <bo...@google.com> wrote:
> - Also, it would have a simplified int getDirection() that would
> return constants like UP or LEFT.

The MightyMouse can handle diagonal scrolling so it's probably best
not to assume a scroll event is limited to one axis.

[Miroslav Pokorny]

Of course consistency is important, if not one of the most important things in a library. But to me it sounds a little silly, to start something new with a mistake like following the *old* pattern with its issues.

So when will the event thing be addressed ?

--
mP

[BobV]

Support for horizontal scrolling isn't there in the current generation
of browsers to be able to include it in GWT 1.4. That said, the work
to provide Y-axis scrolling should provide a pattern that is trivial
to extend when X-axis support is widely available.

This version of the patch:
- Has a MouseWheelVelocity object that provides a normalized
velocity value, as well as isNorth/isSouth convenience methods.
- The velocity values agree with the screen coordinate system.

[BobV]

Same patch, but merges against r931 and has style cleanups.

[Joel Webber]

First, I have to say that this is one of the first times I've ever seen such a simple property *require four different implementations*. Clearly you should have just used capability detection. Just kidding.

DOMImpl & friends:
- Is velocity * 4 correct on Opera? I can't remember what units it had, but I seem to recall multiples of 3 and 120. Just wanted to make sure.
- I think it would be good to see some kind of explanation of the units in DOM.eventGetMouseWheelVelocityY(). I realize that it's not clearly defined by the browsers, but something general like "velocity units should be in terms of the standard scrolling distance on the platform" should make it a little bit more clear (and clear that the kind of crap that IE gives, such as *120 is Right Out). Or maybe it just belongs in MouseWheelVelocity, and can be referenced from here.

Otherwise, LGTM. Good, thorough patch!

joel.

[BobV]

On 4/23/07, Joel Webber <j...@google.com> wrote:
> Clearly you should have just used capability detection.

That's a lot like sticking the fork into the potato and microwaving them both.

> DOMImpl & friends:
> - Is velocity * 4 correct on Opera? I can't remember what units it had, but
> I seem to recall multiples of 3 and 120. Just wanted to make sure.

I was aiming to have the normal scrolling velocity be about 10. Opera
sends both .detail (about 3-4) and .wheelDelta (about 120-200).

> - I think it would be good to see some kind of explanation of the units in
> DOM.eventGetMouseWheelVelocityY(). I realize that it's not clearly defined
> by the browsers, but something general like "velocity units should be in
> terms of the standard scrolling distance on the platform" should make it a
> little bit more clear (and clear that the kind of crap that IE gives, such
> as *120 is Right Out). Or maybe it just belongs in MouseWheelVelocity, and
> can be referenced from here.

The explanation of the units of mouse wheel velocity has been moved to
DOM and an @see tag added from MouseWheelVelocity's class doc back to
DOM.

[Kelly Norton]

Committed as r958.

thanks,
/kel