Test cases for consistent mouse behavior

Hey all, after having fixed various bugs in mouse handling on Mac and Win32, Sam and I agreed that we needed some form of documentation for what “expected” behavior was so we can make all implementations consistent.

As a step towards that, I’ve created the following “test cases” for verifying it (filed as http://bugzilla.libsdl.org/show_bug.cgi?id=1894). I’d love to hear what you all think and what could be added / clarified / removed. In addition, I need help in speccing out the “grabbed” behavior as I don’t actually know how that is supposed to work.

Non-relative, non-grabbed:

  • Move cursor moved outside of window:
    • Ensure focus lost event
    • Ensure clamped values
    • Ensure no more mouse motion events
  • Move cursor moved into window
    • Ensure focus gained event before mouse motion event
  • Click inside window, drag outside of window, release outside of window
    • Ensure mouse motion events with values outside of the window bounds
    • Ensure no focus lost event until you release button
    • Ensure mouse up event when released
  • Click inside window, drag outside of window and back in again, release inside of window
    • Same as release outside of window, except no focus lost event
  • Hide cursor, move cursor out of window
    • Cursor should be displayed once it has left window
  • Hide cursor, command/alt+tab to change focus
    • Cursor should be displayed once you change focus
    • Once you change focus back (command/alt+tab), cursor should be hidden once inside window

Relative:

  • Cursor should not be moveable outside of window
  • Cursor should be hidden
    • Cmd/alt-tab should reshow the cursor
    • Cmd/alt-tab back should hide the cursor again
    • SDL_ShowCursor(1) should not show the cursor
  • Enable relative mode while cursor is outside of window
    • Window with current keyboard focus should get a mouse focus event
    • Clicks should go inside window and not remove focus from application
    • Movement should not “jump” for the first mouse move
    • Cmd/alt-tab should remove focus from application and motion events should not be received
    • Cmd/alt-tab out of app should return cursor to the position it was in before enabling relative mode or the application last gained focus (if relative mode was enabled)
  • Enable relative mode, alt-tab back, move cursor away from application bounds
    • Cmd/alt-tab back should return to relative mode
    • Clicks after cmd/alt-tabbing back should not remove focus from the application
    • Movement should not “jump” for the first mouse move
  • Switching keyboard focus inside the application (if it has multiple windows) should update SDL_GetMouse()->focus if relative mode is enabled
  • Disable relative mode
    • Mouse cursor should return to the position it was in before enabling relative mode or the application last gained focus (if relative mode was enabled)
    • Focus lost events should be sent if cursor was previously outside of window
    • Cursor should be shown unless the user called SDL_ShowCursor(0)

Grabbed:

  • ??? (Please help me fill this out.)

  • J?rgen

Message-ID:

Content-Type: text/plain; charset=“iso-8859-1”

Hey all, after having fixed various bugs in mouse handling on Mac and Win32,
Sam and I agreed that we needed some form of documentation for what
"expected" behavior was so we can make all implementations consistent.

As a step towards that, I’ve created the following “test cases” for
verifying it (filed as http://bugzilla.libsdl.org/show_bug.cgi?id=1894). I’d
love to hear what you all think and what could be added / clarified /
removed. In addition, I need help in speccing out the “grabbed” behavior as
I don’t actually know how that is supposed to work.

Non-relative, non-grabbed:

  • Move cursor moved outside of window:
    • Ensure focus lost event
    • Ensure clamped values
    • Ensure no more mouse motion events
  • Move cursor moved into window
    • Ensure focus gained event before mouse motion event
  • Click inside window, drag outside of window, release outside of window
    • Ensure mouse motion events with values outside of the window bounds
    • Ensure no focus lost event until you release button
    • Ensure mouse up event when released
  • Click inside window, drag outside of window and back in again, release
    inside of window
    • Same as release outside of window, except no focus lost event
  • Hide cursor, move cursor out of window
    • Cursor should be displayed once it has left window
  • Hide cursor, command/alt+tab to change focus
    • Cursor should be displayed once you change focus
    • Once you change focus back (command/alt+tab), cursor should be hidden
      once inside window

Relative:

  • Cursor should not be moveable outside of window
  • Cursor should be hidden
    • Cmd/alt-tab should reshow the cursor
    • Cmd/alt-tab back should hide the cursor again
    • SDL_ShowCursor(1) should not show the cursor
  • Enable relative mode while cursor is outside of window
    • Window with current keyboard focus should get a mouse focus event
    • Clicks should go inside window and not remove focus from application
    • Movement should not “jump” for the first mouse move
    • Cmd/alt-tab should remove focus from application and motion events
      should not be received
    • Cmd/alt-tab out of app should return cursor to the position it was in
      before enabling relative mode or the application last gained focus (if
      relative mode was enabled)
  • Enable relative mode, alt-tab back, move cursor away from application
    bounds
    • Cmd/alt-tab back should return to relative mode
    • Clicks after cmd/alt-tabbing back should not remove focus from the
      application
    • Movement should not “jump” for the first mouse move
  • Switching keyboard focus inside the application (if it has multiple
    windows) should update SDL_GetMouse()->focus if relative mode is enabled
  • Disable relative mode
    • Mouse cursor should return to the position it was in before enabling
      relative mode or the application last gained focus (if relative mode was
      enabled)
    • Focus lost events should be sent if cursor was previously outside of
      window
    • Cursor should be shown unless the user called SDL_ShowCursor(0)

Grabbed:

  • ??? (Please help me fill this out.)

  • J?rgen

Grabbed:

  • Cursor should default to shown
  • Cursor should be movable outside of window
    • Continue mouse motion events
    • Do NOT clamp values
  • Mouse clicked outside of window
    • Same as cmd/alt-tab out of app
    • Ensure mouse down, & matching mouse up (for “bookkeeping” purposes)
  • Cmd/alt-tab out of app
    • One final event for the current mouse location?
    • Ensure focus lost event

I’m certain there are more, but those come to the top of my mind.> Date: Wed, 5 Jun 2013 19:37:04 +0000

From: Jorgen Tjerno
To: “sdl at lists.libsdl.org
Subject: [SDL] Test cases for consistent mouse behavior

Note that in SDL 1.2 in grab mode alt-tab doesn’t work (is there a
distinction between grab keyboard/mouse vs grab input now?).

Also for the other modes, there are some other things to consider:

In KDE alt+LMB grabs the window and allows you to move it around (you click
anywhere on the window). Cursor’s position in the window doesn’t change,
but position on the screen does. I think that in the app no motion events
should appear (in particular in relative mode). There is no focus change
with this action. You can move around windows that are behind other windows.

alt+RMB allows to resize the window (again you click inside the window).
This time position of the cursor changes (because window size changes) so
it makes sense to report the motion (that’s how it works in SDL1.2 now).

And while we are at that, there is one more thing - when you resize the
window in the traditional way, that is grab the edge and move, if you move
towards the window (shrinking movement), the cursors enters the window just
for a moment generating events, then resize kicks in, the window shrinks
and the cursor ends up being outside again. If you resize in the "outside"
direction it does not happen.
I can’t conceive of a situation where it would be important in any way,
maybe except when focus lost/gain events do something non trivial, so
spamming them while resizing may throttle the app.

Is “grabbed” the same as normal, except it reports movement outside of the window?

Kind regards,
J?rgen P. Tjern?.
(Sent using a touchscreen keyboard)On Jun 6, 2013, at 19:14, “Jared Maddox” wrote:

Date: Wed, 5 Jun 2013 19:37:04 +0000
From: Jorgen Tjerno <@Jorgen_Tjerno>
To: “sdl at lists.libsdl.org
Subject: [SDL] Test cases for consistent mouse behavior
Message-ID:

Content-Type: text/plain; charset=“iso-8859-1”

Hey all, after having fixed various bugs in mouse handling on Mac and Win32,
Sam and I agreed that we needed some form of documentation for what
"expected" behavior was so we can make all implementations consistent.

As a step towards that, I’ve created the following “test cases” for
verifying it (filed as http://bugzilla.libsdl.org/show_bug.cgi?id=1894). I’d
love to hear what you all think and what could be added / clarified /
removed. In addition, I need help in speccing out the “grabbed” behavior as
I don’t actually know how that is supposed to work.

Non-relative, non-grabbed:

  • Move cursor moved outside of window:
    • Ensure focus lost event
    • Ensure clamped values
    • Ensure no more mouse motion events
  • Move cursor moved into window
    • Ensure focus gained event before mouse motion event
  • Click inside window, drag outside of window, release outside of window
    • Ensure mouse motion events with values outside of the window bounds
    • Ensure no focus lost event until you release button
    • Ensure mouse up event when released
  • Click inside window, drag outside of window and back in again, release
    inside of window
    • Same as release outside of window, except no focus lost event
  • Hide cursor, move cursor out of window
    • Cursor should be displayed once it has left window
  • Hide cursor, command/alt+tab to change focus
    • Cursor should be displayed once you change focus
    • Once you change focus back (command/alt+tab), cursor should be hidden
      once inside window

Relative:

  • Cursor should not be moveable outside of window
  • Cursor should be hidden
    • Cmd/alt-tab should reshow the cursor
    • Cmd/alt-tab back should hide the cursor again
    • SDL_ShowCursor(1) should not show the cursor
  • Enable relative mode while cursor is outside of window
    • Window with current keyboard focus should get a mouse focus event
    • Clicks should go inside window and not remove focus from application
    • Movement should not “jump” for the first mouse move
    • Cmd/alt-tab should remove focus from application and motion events
      should not be received
    • Cmd/alt-tab out of app should return cursor to the position it was in
      before enabling relative mode or the application last gained focus (if
      relative mode was enabled)
  • Enable relative mode, alt-tab back, move cursor away from application
    bounds
    • Cmd/alt-tab back should return to relative mode
    • Clicks after cmd/alt-tabbing back should not remove focus from the
      application
    • Movement should not “jump” for the first mouse move
  • Switching keyboard focus inside the application (if it has multiple
    windows) should update SDL_GetMouse()->focus if relative mode is enabled
  • Disable relative mode
    • Mouse cursor should return to the position it was in before enabling
      relative mode or the application last gained focus (if relative mode was
      enabled)
    • Focus lost events should be sent if cursor was previously outside of
      window
    • Cursor should be shown unless the user called SDL_ShowCursor(0)

Grabbed:

  • ??? (Please help me fill this out.)

  • J?rgen

Grabbed:

  • Cursor should default to shown
  • Cursor should be movable outside of window
    • Continue mouse motion events
    • Do NOT clamp values
  • Mouse clicked outside of window
    • Same as cmd/alt-tab out of app
    • Ensure mouse down, & matching mouse up (for “bookkeeping” purposes)
  • Cmd/alt-tab out of app
    • One final event for the current mouse location?
    • Ensure focus lost event

I’m certain there are more, but those come to the top of my mind.


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

In SDL 1.2, grabbed mode for the cursor prevents it from leaving the window bounds when the program has input focus. I don’t see why it should be different in SDL 2.0.

When clicking inside the window and dragging outside without releasing the mouse button, is the plan to clamp the mouse motion event coordinates to the window dimensions, or leave them unbounded? Personally I’d expect the former.
It should also account for users click-and-dragging out of the window, and then alt-tabbing to a different program without releasing the mouse button first.On 2013-06-07, at 4:48 PM, Jorgen Tjerno wrote:

Is “grabbed” the same as normal, except it reports movement outside of the window?

Kind regards,
J?rgen P. Tjern?.
(Sent using a touchscreen keyboard)

On Jun 6, 2013, at 19:14, “Jared Maddox” wrote:

Date: Wed, 5 Jun 2013 19:37:04 +0000
From: Jorgen Tjerno
To: “sdl at lists.libsdl.org
Subject: [SDL] Test cases for consistent mouse behavior
Message-ID:

Content-Type: text/plain; charset=“iso-8859-1”

Hey all, after having fixed various bugs in mouse handling on Mac and Win32,
Sam and I agreed that we needed some form of documentation for what
"expected" behavior was so we can make all implementations consistent.

As a step towards that, I’ve created the following “test cases” for
verifying it (filed as http://bugzilla.libsdl.org/show_bug.cgi?id=1894). I’d
love to hear what you all think and what could be added / clarified /
removed. In addition, I need help in speccing out the “grabbed” behavior as
I don’t actually know how that is supposed to work.

Non-relative, non-grabbed:

  • Move cursor moved outside of window:
    • Ensure focus lost event
    • Ensure clamped values
    • Ensure no more mouse motion events
  • Move cursor moved into window
    • Ensure focus gained event before mouse motion event
  • Click inside window, drag outside of window, release outside of window
    • Ensure mouse motion events with values outside of the window bounds
    • Ensure no focus lost event until you release button
    • Ensure mouse up event when released
  • Click inside window, drag outside of window and back in again, release
    inside of window
    • Same as release outside of window, except no focus lost event
  • Hide cursor, move cursor out of window
    • Cursor should be displayed once it has left window
  • Hide cursor, command/alt+tab to change focus
    • Cursor should be displayed once you change focus
    • Once you change focus back (command/alt+tab), cursor should be hidden
      once inside window

Relative:

  • Cursor should not be moveable outside of window
  • Cursor should be hidden
    • Cmd/alt-tab should reshow the cursor
    • Cmd/alt-tab back should hide the cursor again
    • SDL_ShowCursor(1) should not show the cursor
  • Enable relative mode while cursor is outside of window
    • Window with current keyboard focus should get a mouse focus event
    • Clicks should go inside window and not remove focus from application
    • Movement should not “jump” for the first mouse move
    • Cmd/alt-tab should remove focus from application and motion events
      should not be received
    • Cmd/alt-tab out of app should return cursor to the position it was in
      before enabling relative mode or the application last gained focus (if
      relative mode was enabled)
  • Enable relative mode, alt-tab back, move cursor away from application
    bounds
    • Cmd/alt-tab back should return to relative mode
    • Clicks after cmd/alt-tabbing back should not remove focus from the
      application
    • Movement should not “jump” for the first mouse move
  • Switching keyboard focus inside the application (if it has multiple
    windows) should update SDL_GetMouse()->focus if relative mode is enabled
  • Disable relative mode
    • Mouse cursor should return to the position it was in before enabling
      relative mode or the application last gained focus (if relative mode was
      enabled)
    • Focus lost events should be sent if cursor was previously outside of
      window
    • Cursor should be shown unless the user called SDL_ShowCursor(0)

Grabbed:

  • ??? (Please help me fill this out.)

  • J?rgen

Grabbed:

  • Cursor should default to shown
  • Cursor should be movable outside of window
    • Continue mouse motion events
    • Do NOT clamp values
  • Mouse clicked outside of window
    • Same as cmd/alt-tab out of app
    • Ensure mouse down, & matching mouse up (for “bookkeeping” purposes)
  • Cmd/alt-tab out of app
    • One final event for the current mouse location?
    • Ensure focus lost event

I’m certain there are more, but those come to the top of my mind.


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

I assume you also will test hardware colored cursors that SDL 2 supports, and it will change back to the system pointer once it has left focus of the SDL window/screen ?

Message-ID: <567E03C2-8016-4521-9706-2EA9D87A4522 at valvesoftware.com>
Content-Type: text/plain; charset=“iso-8859-1”

Is “grabbed” the same as normal, except it reports movement outside of the
window?

That’s what I was thinking, but admittedly I’m not certain how it
would be useful.> Date: Fri, 7 Jun 2013 19:48:40 +0000

From: Jorgen Tjerno
To: SDL Development List
Subject: Re: [SDL] Test cases for consistent mouse behavior

Date: Fri, 7 Jun 2013 16:57:26 -0300
From: Alexander Szpakowski
To: SDL Development List
Subject: Re: [SDL] Test cases for consistent mouse behavior
Message-ID: <02E1082F-E361-45F9-B5EE-BBB7BCDF037D at gmail.com>
Content-Type: text/plain; charset=iso-8859-1

In SDL 1.2, grabbed mode for the cursor prevents it from leaving the window
bounds when the program has input focus. I don’t see why it should be
different in SDL 2.0.

If you look at the description for relative mode below, you’ll see
that the first thing listed is exactly that. Why would we want two
names for the same thing?

When clicking inside the window and dragging outside without releasing the
mouse button, is the plan to clamp the mouse motion event coordinates to the
window dimensions, or leave them unbounded? Personally I’d expect the
former.

I’d expect the later. If I’m receiving mouse coordinates, and the
cursor is outside the window, I expect some way to take a guess at
where the cursor actually is. Clamping to the window should be done by
keeping the cursor inside the window, not by pretending that the
cursor never left it. Clamping coordinates is easy enough to do in
your app, anyways.

On 2013-06-07, at 4:48 PM, Jorgen Tjerno wrote:

Is “grabbed” the same as normal, except it reports movement outside of the
window?

Kind regards,
J?rgen P. Tjern?.
(Sent using a touchscreen keyboard)

On Jun 6, 2013, at 19:14, “Jared Maddox” <@Jared_Maddox> wrote:

Date: Wed, 5 Jun 2013 19:37:04 +0000
From: Jorgen Tjerno
To: “sdl at lists.libsdl.org
Subject: [SDL] Test cases for consistent mouse behavior
Message-ID:

Content-Type: text/plain; charset=“iso-8859-1”

Hey all, after having fixed various bugs in mouse handling on Mac and
Win32,
Sam and I agreed that we needed some form of documentation for what
"expected" behavior was so we can make all implementations consistent.

As a step towards that, I’ve created the following “test cases” for
verifying it (filed as http://bugzilla.libsdl.org/show_bug.cgi?id=1894).
I’d
love to hear what you all think and what could be added / clarified /
removed. In addition, I need help in speccing out the “grabbed” behavior
as
I don’t actually know how that is supposed to work.

Non-relative, non-grabbed:

  • Move cursor moved outside of window:
    • Ensure focus lost event
    • Ensure clamped values
    • Ensure no more mouse motion events
  • Move cursor moved into window
    • Ensure focus gained event before mouse motion event
  • Click inside window, drag outside of window, release outside of
    window
    • Ensure mouse motion events with values outside of the window
      bounds
    • Ensure no focus lost event until you release button
    • Ensure mouse up event when released
  • Click inside window, drag outside of window and back in again,
    release
    inside of window
    • Same as release outside of window, except no focus lost event
  • Hide cursor, move cursor out of window
    • Cursor should be displayed once it has left window
  • Hide cursor, command/alt+tab to change focus
    • Cursor should be displayed once you change focus
    • Once you change focus back (command/alt+tab), cursor should be
      hidden
      once inside window

Relative:

  • Cursor should not be moveable outside of window
  • Cursor should be hidden
    • Cmd/alt-tab should reshow the cursor
    • Cmd/alt-tab back should hide the cursor again
    • SDL_ShowCursor(1) should not show the cursor
  • Enable relative mode while cursor is outside of window
    • Window with current keyboard focus should get a mouse focus event
    • Clicks should go inside window and not remove focus from
      application
    • Movement should not “jump” for the first mouse move
    • Cmd/alt-tab should remove focus from application and motion events
      should not be received
    • Cmd/alt-tab out of app should return cursor to the position it was
      in
      before enabling relative mode or the application last gained focus (if
      relative mode was enabled)
  • Enable relative mode, alt-tab back, move cursor away from
    application
    bounds
    • Cmd/alt-tab back should return to relative mode
    • Clicks after cmd/alt-tabbing back should not remove focus from the
      application
    • Movement should not “jump” for the first mouse move
  • Switching keyboard focus inside the application (if it has multiple
    windows) should update SDL_GetMouse()->focus if relative mode is
    enabled
  • Disable relative mode
    • Mouse cursor should return to the position it was in before
      enabling
      relative mode or the application last gained focus (if relative mode
      was
      enabled)
    • Focus lost events should be sent if cursor was previously outside
      of
      window
    • Cursor should be shown unless the user called SDL_ShowCursor(0)

Grabbed:

  • ??? (Please help me fill this out.)

  • J?rgen

Grabbed:

  • Cursor should default to shown
  • Cursor should be movable outside of window
    • Continue mouse motion events
    • Do NOT clamp values
  • Mouse clicked outside of window
    • Same as cmd/alt-tab out of app
    • Ensure mouse down, & matching mouse up (for “bookkeeping” purposes)
  • Cmd/alt-tab out of app
    • One final event for the current mouse location?
    • Ensure focus lost event

I’m certain there are more, but those come to the top of my mind.


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

Mouse grabbing simply prevents the mouse from leaving the window when you
move it, whereas relative mode hides the cursor and prevents the mouse from
moving at all.

One example of mouse grabbing in its current form being useful is if you have
an RTS game where the user expects to be able to move the viewport in the
world by moving the mouse to the edge of the window.
It would be sucky to accidentally move the mouse outside the window bounds
(and then click on another program by accident, bringing something else into
focus), so the developer would enable mouse grabbing when the game is in
windowed mode and not in the menus, to prevent that.On 2013-06-08, at 3:49 PM, Jared Maddox wrote:

Date: Fri, 7 Jun 2013 16:57:26 -0300
From: Alexander Szpakowski <@Alex_Szpakowski>
To: SDL Development List
Subject: Re: [SDL] Test cases for consistent mouse behavior
Message-ID: <02E1082F-E361-45F9-B5EE-BBB7BCDF037D at gmail.com>
Content-Type: text/plain; charset=iso-8859-1

In SDL 1.2, grabbed mode for the cursor prevents it from leaving the window
bounds when the program has input focus. I don’t see why it should be
different in SDL 2.0.

If you look at the description for relative mode below, you’ll see
that the first thing listed is exactly that. Why would we want two
names for the same thing?


SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org