Add mouse.(get|set)_relative_mode() (replaces _sdl2.Window.relative_mouse)

[yunline]

Issue: #2073

[zoldalma999]

Looks good to me!

[MyreMylar]

I know this PR is just moving the functions to a more proper place, however my main questions are about how this interacts with the existing functions that cover this functionality, namely:

• mouse.get_rel()
• mouse.set_visble()
• mouse.get_visible()
• event.set_grab()
• event.get_grab()

Mostly so we can document them if it is odd, or maybe correct functionality if it does something you would not expect.

I'd guess users would likely expect all except the event.set_/get_grab() pair to maybe work OK with relative mode enabled. Then probably we could document whatever happens when you try to set/unset grab with relative mode enabled as a reminder not do it as the functionality, while distinct, overlaps somewhat. Whether those mouse function do work however is something we'll need to test...

[MyreMylar]

OK, so there are a couple of things that come up because SDL_SetRelativeMouseMode() also hides the cursor and locks the mouse to the window.

As the event grab also locks the key events to the window I think it is fine that pygame.event.get_grab() doesn't return true while the mouse is in relative mode.

However - mouse.get_visible() really should be false while we are in relative mode as the mouse cursor is not visible and this function does nothing else.

Anyway, it would be an easy fix, except these functions just got updated in the main branch for SDL3 so:

1. Please merge main into this PR.
2. If still needed (as the functions might have changed) please change line 218 of mouse.get_visible() to something like:

result = (PG_CursorVisible() || SDL_GetRelativeMouseMode());

so that pygame.mouse.get_visible() returns False while in relative mode.

Test program:

import pygame


display_surf = pygame.display.set_mode((1280, 800))
display_surf.fill((255, 255, 255))


pygame.init()

clock = pygame.time.Clock()

running = True

mouse_state_changed = False

while running:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

        if event.type == pygame.KEYDOWN and event.key == pygame.K_r:
            if pygame.mouse.get_relative_mode():
                pygame.mouse.set_relative_mode(False)
            else:
                pygame.mouse.set_relative_mode(True)
            mouse_state_changed = True

        if event.type == pygame.KEYDOWN and event.key == pygame.K_v:
            if pygame.mouse.get_visible():
                pygame.mouse.set_visible(False)
            else:
                pygame.mouse.set_visible(True)
            mouse_state_changed = True

        if event.type == pygame.KEYDOWN and event.key == pygame.K_g:
            if pygame.event.get_grab():
                pygame.event.set_grab(False)
            else:
                pygame.event.set_grab(True)
            mouse_state_changed = True

    if mouse_state_changed:
        print("mouse relative mode:", pygame.mouse.get_relative_mode())
        print("mouse visible:", pygame.mouse.get_visible())
        print("events grabbed:", pygame.event.get_grab(), "\n")
        mouse_state_changed = False

    pygame.display.flip()

    clock.tick(60)

[ankith26]

I know I'm late and the PR has been merged already, but this is missing version added tags. Can open a new PR to fix this

[MyreMylar]

#2573