FIX: macOS backend reports wrong button for button_release_event by mishanilkazreen · Pull Request #31937 · matplotlib/matplotlib

mishanilkazreen · 2026-06-22T13:56:34Z

PR summary

The issue reports on macOS that Option+click and Ctrl+click were not correctly mapped to middle and right button clicks, respectively.

In qtagg, Option+click was hardcoded to button = 1 as backend_qt.py did not contain a button modifier mapping. So event.button() returned the physical button, which resulted in Option+click incorrectly emulating button 1 instead of button 2.

In macosx, the mouseDown: method was correctly mapped, however, mouseUp: hardcoded button = 1, which resulted in press and release being inconsistent.

Fixes

For qtagg, I added a _remap_darwin_button(...) static method in backend_qt.py that maps Alt/Option+left-click to the middle button on macOS.

For macosx, I added a static variable effectiveLeftButton to store the resolved button at press time, allowing mouseUp: to read it back instead of hardcoding 1.

Minimum self-contained example

Instructions:

Left Click
Left Click + Option
Left Click + Control

import matplotlib
matplotlib.use('macosx') # macosx/qtagg
import matplotlib.pyplot as plt

def on_press(event):
    print(f'button press:   {event.button}')

def on_release(event):
    print(f'button release: {event.button}')
    print()

fig = plt.figure()
fig.canvas.mpl_connect('button_press_event', on_press)
fig.canvas.mpl_connect('button_release_event', on_release)
plt.show()

Outputs

Current

macosx

button press:   1
button release: 1

button press:   2
button release: 1

button press:   3
button release: 1

qtagg (PyQt6)

button press:   1
button release: 1

button press:   1
button release: 1

button press:   3
button release: 3

With Fixes

macosx & qtagg

button press:   1
button release: 1

button press:   2
button release: 2

button press:   3
button release: 3

Question

As raised in the initial issue, should the intended behaviour for the action Alt + left-click result in the middle mouse? This implements it, but can be dropped by removing _remap_darwin_button(...) helper function.

AI Disclosure

Claude Opus 4.8 was utilised to proofread my changes.

PR checklist

closes [Bug]: macOS backend reports wrong button for button_release_event #31899
new and changed code is tested
[N/A] Plotting related features are demonstrated in an example
[N/A] New Features and API Changes are noted with a directive and release note
[N/A] Documentation complies with general and docstring guidelines

Fixes matplotlib#31899

github-actions · 2026-06-22T13:56:46Z

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. We also ask that you please finish addressing any review comments on this PR and wait for it to be merged (or closed) before opening a new one, as it can be a valuable learning experience to go through the review process.

You can also join us on discourse chat for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

We strive to be a welcoming and open project. Please follow our Code of Conduct.

iccir · 2026-06-23T02:15:09Z

Thanks for this! Your solution for the macOS backend made me realize a potential issue that I forgot to check in the original bug.

Consider the following:

Hold down Alt/Option
Press the mouse button, but don't release
Release Alt/Option
Release mouse button

qtagg with your PR prints:

button press: 2
button release: 1

If you do the same with Control instead of Alt/Option, qtagg instead prints:

button press: 3
button release: 3

I suspect that we want Alt/Option to show 2 for both press and release to match what QT already does for the right mouse button, but I'm new here so I'm not sure!

…mouse button Fixes matplotlib#31899

mishanilkazreen · 2026-06-28T12:58:37Z

Hi @iccir,

Thanks for commenting on another case where it reports the wrong button release. I repeated your experiment and confirmed that it did affect qtagg. The cause is that the methods mousePressEvent, mouseDoubleClickEvent and mouseReleaseEvent were querying the modifier keys live at the time of each event, so if we were to release Option/Alt before the mouse button, the release event would see no Alt and report the button release as 1 instead of 2.

My solution was that I added a _pressed_buttons dict on the canvas that stores the remapped buttons at press time. So on release, it pops the stored value instead of requerying the modifiers.

mishanilkazreen · 2026-07-04T11:51:40Z

Just bumping this up for visibility, as I haven't heard back for more than one week.

iccir · 2026-08-01T19:54:14Z

Hi @mishanilkazreen!

Sorry for the delay in responding. A few weeks ago, I researched the history of "alt+click" emulating a middle click. As far as I can tell, this originates with the original implementation of Apple's XQuartz X11 server. It's not a widespread macOS convention like Control+Click.

While I'm new to the project myself and not yet a maintainer, I don't think that this behavior should go into the other backends. I'm more inclined to remove it entirely from the macOS backend.

That said, your implementation in the macosx backend is superior to my original one. Right now, we are in the process of adopting a reworked "macos" backend. As a result, I think your _macosx.m change in this PR is going to get lost in the chaos.

I want you to get credit, however! I added you as a co-contributor to c7faa7f. I think that this will properly attribute you when I eventually merge. If this isn't the case, please let me know and I'll try to fix it! I'll also try to tag you on the eventual PR that will include this commit.

mishanilkazreen · 2026-08-02T06:05:52Z

Hi @iccir

Thank you for your response and I appreciate you including my contribution to your rework. Much appreciated :)

[Bug]: macOS backend reports wrong button for button_release_event

a47ac21

Fixes matplotlib#31899

github-actions Bot added first-contribution GUI: Qt GUI: MacOSX and removed first-contribution labels Jun 22, 2026

[Bug]: qtagg reports wrong button when Option is released before the …

92c4212

…mouse button Fixes matplotlib#31899

mishanilkazreen changed the title ~~[Bug]: macOS backend reports wrong button for button_release_event~~ FIX: macOS backend reports wrong button for button_release_event Jul 4, 2026

Navigation Menu

Uh oh!

Uh oh!

FIX: macOS backend reports wrong button for button_release_event - #31937

FIX: macOS backend reports wrong button for button_release_event#31937
mishanilkazreen wants to merge 2 commits into
matplotlib:mainfrom
mishanilkazreen:mishanilkazreen/issue31899

mishanilkazreen commented Jun 22, 2026

Uh oh!

github-actions Bot commented Jun 22, 2026

Uh oh!

iccir commented Jun 23, 2026

Uh oh!

mishanilkazreen commented Jun 28, 2026

Uh oh!

mishanilkazreen commented Jul 4, 2026

Uh oh!

iccir commented Aug 1, 2026

Uh oh!

mishanilkazreen commented Aug 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

mishanilkazreen commented Jun 22, 2026

PR summary

Fixes

Minimum self-contained example

Outputs

Current

With Fixes

Question

AI Disclosure

PR checklist

Uh oh!

github-actions Bot commented Jun 22, 2026

Uh oh!

iccir commented Jun 23, 2026

Uh oh!

mishanilkazreen commented Jun 28, 2026

Uh oh!

mishanilkazreen commented Jul 4, 2026

Uh oh!

iccir commented Aug 1, 2026

Uh oh!

mishanilkazreen commented Aug 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants