Add pygame.mouse.get_just_pressed/released()

[damusss]

I added the functions in the title + stubs, tests and docs.
I also added 2 function to the C API and I documented them.
I looked at the same functions in key.c to work myself into implementing them for the mouse.
The suggestions comes from clear code on #contributing

If those functions exist for the keys, I think it makes perfect sense to implement them for the mouse as well.
Tell me what you think and if I messed up something on the C side.

[MyreMylar]

IIRC the only reason get_pressed() has the awkward num_buttons parameter is for backwards compatibility as originally there was only support for three buttons in pygame 1 so when five button support came along with SDL2 I added this parameter.

I would be tempted to make a new function just always return a 5-tuple of all the potential buttons. If a mouse doesn't have x1 or x2 then they would just always be false in the 5-tuple. Simpler API and maybe with the pygame 3/SDL 3 API break we could align .get_pressed() in the same way.

I also think, now I'm looking over it, the docs could be rejigged to list what the buttons are with terminology that matches the SDL & pygame constants (and common usage) e.g.:

get_pressed() -> (left_button, middle_button, right_button, x1_button, x2_button)

...

get_just_pressed() -> (left_button, middle_button, right_button, x1_button, x2_button)

because I know I'm constantly forgetting the order of the buttons.

[damusss]

@MyreMylar thanks for the review, and I agree on all. I used num_buttons when looking at the old function, but I can see that they aren't really necessary as this is a new one. I also almost always forget if the right button is the second or third entry in the tuple, so an update of the docs feels necessary. I'll take the freedom to change the docs of the normal get_pressed as well as it would make it clearer. On my way to update the pr :)

[damusss]

That change is not only better on a python level but reduced massively the test/stub sizes and the API sizes completely removing the logic for parsing arguments and returning different sized tuples.

[MyreMylar]

OK, this works as I would expect in my testing. I just stuck this in a standard pygame-ce game loop:

    if any(pygame.mouse.get_just_pressed()):
        print("pressed: ", pygame.mouse.get_just_pressed())

    if any(pygame.mouse.get_just_released()):
        print("released: ", pygame.mouse.get_just_released())

I expect some users will find it useful, I think we added the keyboard version because it was a similar interface as offered in some other popular game development libraries. I think that still stands as a reason to add this here, along with it being more consistent with the keyboard.

[itzpr3d4t0r]

missing newline here

[itzpr3d4t0r]

as well as here

[itzpr3d4t0r]

and here

[itzpr3d4t0r]

What if the mouse doesn't support 5 buttons here? Just being curious here. And also what if we made these function configurable concerning the number of buttons we want to return? like by passing in an optional int like num_buttons.
Would require METH_FASTCALL tho.

[damusss]

What if the mouse doesn't support 5 buttons here? Just being curious here. And also what if we made these function configurable concerning the number of buttons we want to return? like by passing in an optional int like num_buttons. Would require METH_FASTCALL tho.

Hi,
That's what MyreMylar talked about in the first comment. If the mouse doesn't support the buttons, the entries will always be False, and I personally don't see an issue with that. The tuple values come from a function that I created (edit: don't want to remove credits to who made it for the key module as I used it as a base) which memsets to 0, and if no events with those buttons are passed, it will never be set to 1.
The num_buttons added to get_pressed was for compatibility between pygame 1 and pygame 2 (added by MyreMylar) and MyreMylar even suggested that it could be removed with pygame 3. This is new API, so it doesn't need it. Removing that argument also cleaned up the code a lot.

[damusss]

@itzpr3d4t0r about the newlines, in my defense, it was clang-format as I didn't edit the end of the files. I also wonder why setup.py format is not an option anymore

[ankith26]

It was removed in favour of pre-commit. You can achieve the same affect as python setup.py format by running pre-commit run -a now

[itzpr3d4t0r]

Minor stuff aside this LGTM thanks!

I tested the functionality with this code btw:

import pygame
from random import random
pygame.init()

screen_size = 1000

screen = pygame.display.set_mode((screen_size, screen_size))

clock = pygame.time.Clock()
keep_going = True

particles = []

class Particle:
    def __init__(self, x, y, vx, vy):
        self.x = x
        self.y = y
        self.vx = vx
        self.vy = vy

    def update(self, dt):
        self.x += self.vx * dt
        self.y += self.vy * dt

        if self.x < 0:
            self.x = 0
            self.vx *= -1
        elif self.x > screen_size:
            self.x = screen_size
            self.vx *= -1

        if self.y < 0:
            self.y = 0
            self.vy *= -1
        elif self.y > screen_size:
            self.y = screen_size
            self.vy *= -1

        return self.x, self.y

while keep_going:
    dt = clock.tick_busy_loop(60) * 60 / 1000
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            keep_going = False

    screen.fill((0, 0, 0))

    for p in particles:
        x, y = p.update(dt)
        pygame.draw.circle(screen, (255, 255, 255), (int(x), int(y)), 5)

    if any(pygame.mouse.get_just_released()):
        particles.append(Particle(*pygame.mouse.get_pos(), random() * 2 - 1, random() * 2 - 1))

    pygame.display.flip()