exposed the mouse button event "clicks" property

[JReesW]

Why?
I am adding this because I wanted a simple mechanism to detect double-clicks inside my game. I found that the SDL_MouseButtonEvent actually has a property called clicks that counts the amount of rapid clicks in a row based on the system-defined double click timing. Pygame-CE just didn't expose this functionality. This PR amends this by simply exposing the clicks property of the SDL_MouseButtonEvent to the Pygame mouse button events. It is my belief that Pygame should expose this as it is an existing functionality of SDL that Pygame seems to have forgotten to implement, and it offers an easy solution to a commonly tackled problem of how to add double-click detection to Pygame (or any n-clicks detection for that matter).

Test program
Below is a simple test program that opens a window that can detect mouse clicks. It prints the button ID and the clicks property whenever a mouse button is clicked. Additionally pressing q exits the program.

import pygame
pygame.init()

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

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

while running:
    clock.tick(60)

    for event in pygame.event.get():
        if event.type == pygame.MOUSEBUTTONDOWN:
            print(event.button, event.clicks)
        if event.type == pygame.KEYDOWN and event.key == pygame.K_q:
            running = False

As can be seen when running the program, if you rapidly click on the window then the clicks value (the second number) increases, showing the number of rapid, consecutive clicks. Pausing for a short second and then clicking shows that the clicks value has gone back to 1, meaning the pause was enough for the clicks to no longer be considered rapid and consecutive.

Tests
No test has been added, as Pygame-CE's tests don't seem to cover testing the individual properties of events. If it should be put in a test, let me know and I'll get on it.

Documentation
The clicks property has been added to the list of properties for both the MOUSEBUTTONUP and MOUSEBUTTONDOWN events. No additional documentation has been added as no individual properties are discussed in depth elsewhere either.

[coderabbitai]

📝 Walkthrough

Walkthrough

Add a clicks member to SDL mouse button events: MOUSEBUTTONDOWN and MOUSEBUTTONUP event dictionaries now include a clicks attribute; documentation updated with the attribute and a 2.5.7 change note.

Changes

Cohort / File(s)	Summary
Docs: event attribute surface docs/reST/ref/event.rst	Add clicks to MOUSEBUTTONDOWN and MOUSEBUTTONUP attribute lists and a 2.5.7 note describing clicks semantics.
C event handling src_c/event.c	In dict_from_event, populate the "clicks" key from event->button.clicks for SDL_MOUSEBUTTONDOWN and SDL_MOUSEBUTTONUP so Python event dicts include the number of clicks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Add "clicks" to mouse event #3706: Adds exposure of SDL mouse clicks to Python event dicts, matching this change.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: exposing the mouse button event 'clicks' property, which directly matches the primary focus of this changeset.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the motivation for exposing the clicks property, providing a test program, and discussing documentation updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/reST/ref/event.rst`:
- Around line 75-76: Add a short description for the new clicks attribute in the
MOUSEBUTTONDOWN and MOUSEBUTTONUP attribute list explaining it reports the
number of rapid consecutive clicks (as provided by the system/SDL double-click
detection) and add a version directive (e.g., .. versionadded:: 2.5.x) after the
existing .. versionchangedold:: 2.0.1 note stating that the clicks attribute was
added to MOUSEBUTTONDOWN and MOUSEBUTTONUP; reference the attribute name
"clicks" and the event names "MOUSEBUTTONDOWN"/"MOUSEBUTTONUP" so the change is
discoverable.

[damusss]

Hello, first of all, thank you for contributing!

I agree that event attributes are generally undocumented, but after the list of event types there are a few paragraphs clarifying some event attributes, for example, if you scroll down you can read:

The touch attribute of MOUSE events indicates whether or not the events were generated by a touch input device, and not a real mouse. You might want to ignore such events, if your application already handles FINGERMOTION, FINGERDOWN and FINGERUP events.

I think this page of the docs is extremely messy, there's version added/version changed tags in random places (they should probably be at the end) and the paragraphs aren't perfectly placed. I think this section should be improved, and I might even try to do that myself.

That aside, the same way the touch attribute is "documented", I think a small paragraph near it should be added clarifying the attribute. For example, I can see someone wondering whether a double click will fire a single event with clicks=2 or two events, the first having clicks=1 and the second clicks=2, therefore I think it should be explained.
Also, as the AI pointed out, the versionadded tag should be added. Where? I'm not sure... they're all scattered around, if I had to suggest anything probably close to the paragraph explaining the attribute.

[JReesW]

Thank you! I will take these points into consideration and work on them tomorrow. With that I have a question.

What version should I write down? Should it be the version 2.5.7 found in the pyproject.toml (minus the .dev1)?

It's nice to give contributing a try, even if it's what I already do at my job haha

[damusss]

@JReesW :)

You could put 2.5.7 for now but it would probably need to be updated as I think 2.5.7 won't take long to drop and likely won't receive any new API, tho it's not guaranteed (also we still need the opinion of senior reviewers, but I don't have anything against the addition myself)

[JReesW]

@damusss I have added some more clarity to the documentation regarding the clicks attribute, let me know if it's acceptable and in the right place!

[damusss]

@JReesW thank you, it's looking good! If I could propose a final improvement to the explanation, as mentioned in my original message, I'd add a sentence along the lines of Note that double, triple or more clicks will still fire the corresponding amount of mouse events with progressively increasing ``clicks`` attribute. after the period.

[JReesW]

@damusss done!

[damusss]

Looking good to me, it's useful information that SDL easily gives us. Thank you :)

[JReesW]

Awesome, glad I could be of service, and thanks for looking it over for me! :)
Does this mean I get a contributor role now haha 👀 ?

[damusss]

@JReesW No problem! I'm pretty sure the contributor role is given after the pull request is merged, for a pull request to be merged it requires at least two approvals, one of which has to come from a senior reviewer or an admin, which I am not, so we'll have to wait and see what their opinions are :)

[JReesW]

haha fair enough, we will see!

[damusss]

(if you want the failing check to pass you have to run py dev.py format and let it fix the formatting)

[JReesW]

done!