Add `desktop` argument to `mouse.get_pos` and `mouse.get_pressed`

[damusss]

This pull request combines the following PRs adopting a "better" API (suggested by @ankith26 ) while retaining the functionality. To know about usecases or why please check them both:

• desktop pos: https://github.com/pygame-community/pygame-ce/pull/3070
• desktop pressed: https://github.com/pygame-community/pygame-ce/pull/3101

Closes #3070 Closes #3101

Combined 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)

    # DESKTOP PRESSED
    dmouse = pygame.mouse.get_pressed(desktop=True)[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

    # DESKTOP POS
    if not mouse and not dmouse:
        dpos = pygame.mouse.get_pos(desktop=True)
        win_rect = pygame.Rect(win.position, win.size)
        if win_rect.collidepoint(dpos):
            print(f"MOUSE HOVERING! desktop pos: {dpos}")
        else:
            print(f"NO HOVER. desktop pos: {dpos}")

        # you will get the hover status regardless of focus

    win.flip()
    clock.tick(60)

[damusss]

I found the position of get_pos(desktop=True) is not scaled in SCALED mode. Will this cause a problem (?

Hi :) as far as I know SCALED is related to a window setting, but the desktop position is relative to the monitor, so by my understanding the monitor position should not be affected by the window size or fullscreen status, so I believe it's not a problem. The only thing that comes to mind is Wayland, but I'm not sure it's possible to check for it or if it's worth it.

[ankith26]

We could also make a note about the SCALED thing in the docs

[damusss]

One thing that could be potentially discussed further is the keyword argument naming. Is desktop good enough or is there something better? I am fine with desktop, but I'm open to other suggestions.

I used Andrew's suggestion. SDL calls it global but I don't think it conveys enough information. absolute was an option but it can be confused with clamped or abs()

[damusss]

We could also make a note about the SCALED thing in the docs

Is it necessary to specify that it's not effected by the SCALED flag?