Window grab API rework

[yunline]

• grab -> grab_mouse
• Add grab_keyboard
• Add mouse_grabbed
• Add keyboard_grabbed

We already have grab_mouse/keyboard, why add mouse/keyboard_grabbed?

These attribute are for different uses.
grab_mouse means whether the window will try to grab the mouse.
mouse_grabbed means whether the mouse is grabbed by this window.
See docs for details.

TestCode

import sys

import pygame
from pygame._sdl2 import video

w1 = video.Window("w1", position=(200, 200))
w2 = video.Window("w2", position=(600, 300))
w1.grab_keyboard = True
w2.grab_keyboard = True

pygame.key.stop_text_input()

print(
    "This is a test script for 'grab_keyboard' and 'keyboard_grabbed'.s\n"
    "Try press 's' or change the focus of the two windows."
)

while 1:
    for event in pygame.event.get():
        if event.type == pygame.WINDOWFOCUSGAINED:
            print(
                f"w1 grabbed:{w1.keyboard_grabbed}, "
                f"w2 grabbed:{w2.keyboard_grabbed}"
            )
        if event.type == pygame.KEYDOWN and event.unicode == "s":
            if (win := event.window) is not None:
                win.grab_keyboard = not win.grab_keyboard
                print(
                    f"[{win.title}] grab mode {'on' if win.grab_keyboard else 'off'}. "
                    f"`Win + D` should {'not ' if win.grab_keyboard else ''}work.\n"
                    f"w1 grabbed:{w1.keyboard_grabbed}, "
                    f"w2 grabbed:{w2.keyboard_grabbed}"
                )
        if event.type == pygame.WINDOWCLOSE:
            sys.exit()

[MyreMylar]

All works on my machine, I can grab the mouse and the keyboard shortcuts with the Window class all day long 👍 🎉

I added a couple of small documentation suggestion fixes along with this review. Feel free to fix them yourself or whoever ends up 2nd review and merging this can do so.

[zoldalma999]

Looks good to me! Used your test app (and modified it to make sure mouse grabbing works), and it did what it should. I also tested passing in grab_keyboard as an argument, that works too.