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]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

Adds a clicks attribute to MOUSEBUTTONDOWN and MOUSEBUTTONUP events; event dictionaries now include "clicks" populated from SDL, and documentation updated with a 2.5.7 note describing clicks semantics.

Changes

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

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Add "clicks" to mouse event #3706: Same functional change — exposes SDL mouse clicks in Python event dicts.

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Merge Conflict Detection	⚠️ Warning	❌ Merge conflicts detected (4 files): ⚔️ README.rst (content) ⚔️ docs/reST/ref/event.rst (content) ⚔️ docs/readmes/README.it.rst (content) ⚔️ src_c/event.c (content) These conflicts must be resolved before merging into main.	Resolve conflicts locally and push changes to this branch.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: exposing the mouse button event 'clicks' property to the public API.
Description check	✅ Passed	The description provides clear context about why the change is needed, how it works, includes a test program, and explains the testing and documentation approach.
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 docstrings

🧪 Generate unit tests (beta)

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

⚔️ Resolve merge conflicts (beta)

• Auto-commit resolved conflicts to branch expose_clicks
• Post resolved changes as copyable diffs in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

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!

[Starbuck5]

Looks good to me. Thanks!

[Starbuck5]

@JReesW you can squash the commits yourself if you'd like or we can do a squash and merge. Up to you. (We want to avoid having commits like ~format the code~ in main).

[JReesW]

@Starbuck5 hiya, I've squashed the commits together. Could you check whether it's up to standard now? I rarely do such git manoeuvres, so I want to make sure it all went well

[damusss]

@JReesW GitHub only reports one commit associated with the pull request so I assume it went fine