Add pygame.mouse.get_just_pressed/released()

[damusss]

trafficstars

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.

[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