Add pygame.mouse.get_desktop_pressed

[damusss]

This PR follows the steps of #3070 .

That function gets the global position, this one gets the global press state.
The other function is more "urgent" in my opinion, but I'd love to see them both, at the end of the day it's just a wrapper around SDL_GetGlobalMouseState.

Why/Usecase

• It exists in SDL2, it's an information that is accessible, why keep it a secret
• It's such a simple wrapper that this PR only adds 53 lines, meaning it's not a big change
• Practical usecase: let's say you have an application with some UI inside an always on top window, using get_pressed, the first time the user clicks on the window when it was unfocused the return is going to be False because the window has no focus. it will only be True when the window has focus, meaning the user will have to double click the UI to register a click. Using get_desktop_pressed, the click will be registered immediately without the need of a secondary click. On an always-on-top window one can only use get_desktop_pressed and check for the window hover accordigly.

Sample code

import pygame

win = pygame.Window("desktop pressed test", (200, 200))
win.always_on_top = True

# if a member of the SC is reading this, Window.surface >>>> Window.get_surface!
screen = win.get_surface()

clock = pygame.Clock()

while True:
    for event in pygame.event.get():
        if event.type == pygame.WINDOWCLOSE and event.window == win:
            pygame.quit()
            raise SystemExit

    screen.fill(0)

    dmouse = pygame.mouse.get_desktop_pressed()[0]
    mouse = pygame.mouse.get_pressed()[0]
    if mouse and dmouse:
        print("Pressing LEFT with focus")
    elif dmouse:
        print("Pressing LEFT without focus")

    # click other windows, click the taskbar, you'll always get the left button pressed

    # also test this: after clicking on another window,
    # hold the mouse on the window. You'll see it says "pressing without focus" until you click again

    win.flip()
    clock.tick(60)

[ankith26]

This PR has gotten me thinking about the API design for this PR and the other one. Why are we adding two functions when this could be a keyword argument of the existing functions very easily? The semantics and signatures of the "desktop" variants are very similar or same as the "non desktop" variants

[damusss]

This PR has gotten me thinking about the API design for this PR and the other one. Why are we adding two functions when this could be a keyword argument of the existing functions very easily? The semantics and signatures of the "desktop" variants are very similar or same as the "non desktop" variants

how exactly do you think api-wise a keyword argument could "switch" from a 5tuple to a 2tuple or both? because I thought of combining it aswell but i had the plain mouse state return in mind which wouldn't be consistent

[damusss]

Hold on I might have understood what you mean, you intend on adding a desktop keyword argument to get_pos() and get_pressed(), I feel so dumb. It's lowkey a 🔥 idea, so I'll implement it so you can see what you prefer.