Mouse scrolling stuff

[binary1248]

Implemented support for horizontal mouse wheel scrolling as well as high-precision scrolling on Windows and OS X. Should fix (#95).

If you're wondering why there isn't support for high-precision scrolling on Unix, it's because I spent half a day fighting with the non-existant XCB Xinput documentation only to realize that most X servers probably might not even provide high-precision values yet.

As usual, OS X stuff hasn't been tested.

[LaurentGomila]

Isn't it confusing to have delta, deltaX and deltaY within the same structure? (don't reply "documentation", you know that people never read it...)

What do you think of

int delta;
Vector2f highPrecisionDelta;

Or we could even think of more modifications. For example, we could create two new events HorizontalWheelMoved and VerticalWheelMoved with float delta, and mark MouseWheelMoved as deprecated.

[binary1248]

I think splitting the event might make the most sense. On Windows and Unix they are generated separately anyway, I don't know if OS X actually generates events with deltas along multiple axes simultaneously but I don't think it will be that big of a drawback anyway. On the plus side, if we split the events, the size of the structs/union will be reduced which is always a good thing 😛.

[MarioLiebisch]

What's the reason for introducing a second member rather than just changing the data type? Considering the integer variable is unreliable, I'd just accept potentially breaking existing code, since it would be broken anyway. Also leave the name untouched - classic scrolling is vertical only. Add a second event for horizontal instead.

[LaurentGomila]

What's the reason for introducing a second member rather than just changing the data type? Considering the integer variable is unreliable, I'd just accept potentially breaking existing code

It was discussed in #95 (comment).

I think splitting the event might make the most sense.

Yes, it definitely looks cleaner, and code using the new events won't break in SFML 3 when the old event is removed.

[binary1248]

Updated.

Still needs testing on OS X.

[mantognini]

Deprecated could be mentioned with \deprecated.

[binary1248]

But... there is no paragraph to mark with it? There is only the \brief description line.

[mantognini]

I guess the typical usage would be (on a new line): \deprecated this struct is deprecated. (See bottom of this page.)

[MarioLiebisch]

How about \deprecated This event is deprecated and potentially inaccurate. Use ... instead.? Just saying it is deprecated is kinda pointless as a description.

[mantognini]

Yes, of course. My comment was more about the syntax.

[mantognini]

At first sight the changes look good but I'll test it later (probably next week, though).

[LaurentGomila]

MouseHorizontalWheel or HorizontalMouseWheel? 😛

[binary1248]

I prefer having "Mouse" at the start 😛.

[LaurentGomila]

Ok, I was just wondering if it didn't sound too weird.

[MarioLiebisch]

MouseWheelVertical+ MouseWheelHorizontal IMO - since both are MouseWheel so I wouldn't split that.

[binary1248]

Updated.

[mantognini]

Seems to work relatively well on OS X too. Just one thing: on Unix/Windows, do you get "null" events (where the delta is 0)? On OS X that's the case so you get spammed with those negligible events. I'm wondering if SFML should filter them or not... What do you think?

[binary1248]

You will probably get them with the other OSs as well. If you have a high precision mouse in Linux, you will still get either 0.0 or 1.0 ticks. Don't know how it is on Windows exactly, but I can imagine values of 0 as well if the integer value can't represent the tiny movement you made on your wheel.

This way, we leave it up to the user to interpret what these values could mean. We can't know if it they might be meaningful to them or not, so better just give them everything and let them decide.

[mantognini]

Good point.

[MarioLiebisch]

From a quick test I can't get a delta smaller than -1 or 1 with my Logitech mouse's wheel and the wheel steps disabled (Windows 8.1 x64). I only end up with -1 or 1 no matter how fast I roll the wheel or whatever driver setting I use (125 Hz polling vs. 1 kHz polling). Not sure whether that's normalized in the drivers or so though.

[binary1248]

It's completely up to the operating system what values it returns. MSDN documentation simply states that the OS can return values that are smaller than 120, and the developer should handle this properly. If the driver/OS doesn't want to provide smaller values through the message API, then there is nothing we can really do.

[mantognini]

@binary1248 Is there anything else to do here? Since it's only +134/−44 changes, I feel we could include it in 2.3. What do you think?

[binary1248]

I have nothing more to add to this. If everyone else agrees this can be included in 2.3, then be my guest 😉.

[eXpl0it3r]

This PR has been added to my merge list, meaning it will be merged soon, unless someone raises any concerns.

[eXpl0it3r]

The values seem indeed a bit odd. I'm getting either 1, 2, 3 or 4 for scrolling up and 545.113, 544.113, 543.113 or 542.113 for scrolling down.
For horizontal scrolling I get -545.113 for scrolling left and -1 for scrolling right.

So it doesn't do what the documentation comments say.

[binary1248]

Turns out a cast was missing. 😁

Should work as expected now...

[eXpl0it3r]

Seems to be working now. 👍

[Bromeon]

Why not one event type for both vertical and horizontal scrolling and an additional enum member denoting which one it was?

class Mouse
{
public:
   enum Wheel // <- new
   {
      HorizontalWheel,
      VerticalWheel,
   };
};

struct Event
{
   struct PreciseMouseWheelEvent // <- new
   { 
      float delta;
      int x;
      int y;
      Mouse::Wheel wheel;
   };

   struct MouseWheelEvent // <- deprecated
   {
      int delta;
      int x;
      int y;
   };
};

Having two identical structs is code duplication which eventually leads to combinatorial explosion. If you ever encounter a strange mouse model with a third wheel, you have to create yet another struct (and even with only two, it feels wrong to me).

Even more important, this approach is consistent to existing event APIs like MouseButtonEvent and JoystickButtonEvent which have members for the current mouse/joystick state, and one to know which button was pressed. Scrolling different mouse wheels are not different event types, the same way that pressing different buttons are not.

[TankOs]

I like @Bromeon's suggestion. :)

[zsbzsb]

I know this was merged already, but I have to say @Bromeon made a very good suggestion. I wouldn't be against changing it even though it was already merged into master. Yes - we would be breaking the API, but I think it would be fine as this API is hardly even established yet (I doubt anyone is using it yet).

[mantognini]

I guess it makes sense, indeed. And since the API was not yet written in stone (only official release matter I'd say), we can change that easily.

[Bromeon]

I could write a corresponding pull request. What do you think about the identifiers, are they okay? I extended the above snipped accordingly.

• enum sf::Mouse::Wheel -- consistent to existing sf::Mouse::Button
• struct sf::Event::PreciseMouseWheelEvent -- in addition to deprecated sf::Event::MouseWheelEvent

[zsbzsb]

Those identifiers are fine in my book.

[mantognini]

👌

[Bromeon]

I started a new branch feature/combined_mousewheel.

[Edit] See #837 for further discussion.

[mantognini]

I think for now the MouseWheelPreciseMoved event is ok but you have a good point: with v3 we should have

   struct MouseWheelEvent
   { 
      float delta;
      int x;
      int y;
      Mouse::Wheel wheel;
   };

(Devs would have in any case to adapt their code when migrating to v3 so something that small should not be an issue.)

[eXpl0it3r]

Might want to create your own PR and discuss further things there. 😉

[Bromeon]

You're right. I didn't want to create a PR as long as nobody supported the idea, but it seems like people so far agree with it :)

Please continue the discussion in #837.