Great point, and worth discussing before we go further.

Our primary motivation for raise_window() is programmatic workflows — e.g. from an IPython session, bringing a figure window into view to inspect a plot, without leaving the terminal (IPython session). In that context, stealing keyboard focus is probably not what the user wants: there isn't much to do with keyboard focus in a matplotlib window anyway, and the user likely wants to stay in their REPL.

That said, you are right that the current rcParams["figure.raise_window"] path has always included focus transfer (at least on Qt and GTK), so changing that silently would be a behaviour regression.

Our proposal would be:

raise_window(*, with_focus=True)

With with_focus=True as the default, the behaviour matches the current rcParams["figure.raise_window"] path, so there is no surprise for existing users. Users who want to bring the window to the front without leaving their REPL can opt out with raise_window(with_focus=False). Internally, show() would simply call raise_window(with_focus=True) to preserve the existing rcParams semantics.

macOS investigation

I ran a first investigation on the macOS backend using the following script:

BACKEND="macosx"
BLOCK=False
FIGURE_RAISE_WINDOW=True

import subprocess
import matplotlib as mpl
mpl.rcParams["figure.raise_window"]=FIGURE_RAISE_WINDOW
mpl.use(BACKEND)
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3])

manager = fig.canvas.manager

# Register focus callbacks so we can observe focus changes
manager.mpl_connect('focus_in_event',  lambda: print(">>> matplotlib window got focus"))
manager.mpl_connect('focus_out_event', lambda: print(">>> matplotlib window lost focus"))

def frontmost_app():
    result = subprocess.run(
        ['osascript', '-e',
         'tell application "System Events" to get name of first application process whose frontmost is true'],
        capture_output=True, text=True
    )
    return result.stdout.strip()

plt.show(block=BLOCK)

# --- After clicking back into the terminal ---

print("Frontmost before:", frontmost_app())
manager.raise_window()
print("Frontmost after: ", frontmost_app())

The four combinations of BLOCK and FIGURE_RAISE_WINDOW were tested:

Conclusions

On macOS:

• [orderFrontRegardless] (the native call behind both show() and raise_window()) brings the window visually to the front without stealing keyboard focus from the calling process. The frontmost app never changes from the terminal (wezterm-gui).
• Focus events only fire when block=True, because blocking the event loop hands control to the macOS run loop, which naturally activates the window. This is a side-effect of blocking, not of raise_window.
• rcParams["figure.raise_window"] has no effect on focus on macOS — focus behaviour is entirely determined by whether show() is blocking or not.

This means the macOS backend's raise_window() already implements "raise without stealing focus" — which is the behaviour I would prefer for the standalone raise_window() call. However, this is likely inconsistent with what Qt and GTK currently do via activateWindow() and present(), which do transfer focus. So macOS is already effectively doing with_focus=False, but it diverges from the other backends — which is exactly the cross-platform inconsistency that needs to be resolved.

Our proposal would be:

raise_window(*, with_focus=True)

An optional parameter is likely reasonable. Alternative would be a separate focus() method. Viability depends on whether all backends support the opertions separately (or we accept cross-talk on some backends).

With with_focus=True as the default, the behaviour matches the current rcParams["figure.raise_window"] path, so there is no surprise for existing users.

The default value of with_focus=True can be chosen freely. If with_focus=False was better, we would simply call raise_window(with_focus=True) in the existing mpl.rcParams["figure.raise_window"] context and document that in the parameter.

Note: This is a good example why we are reseved on extending the backend. It's a lot of effort to make this right and consistent across all backends.

Hi Tim!

An optional parameter is likely reasonable. Alternative would be a separate focus() method. Viability depends on whether all backends support the opertions separately (or we accept cross-talk on some backends).

Cool. Probably we do not have to decide it now; we can defer the decision of whether to use a parameter with_focus or a new function focus() to later. My preference as of today is to use a parameter: focus() has a clear meaning (make it visible and steal focus), but raise_window is not 100% clear what it is supposed to do. So, if we go for raise_window(*, with_focus=True), it provides the user with a simpler mental picture; much less to process in the head.

Viability depends on whether all backends support the opertions separately (or we accept cross-talk on some backends).

I cross my fingers that it is possible to implement it cleanly on all backends, but I never worked with Tk/Gtk3. Do you have a list of preferences in which order I should investigate the other backends: Qt5, Qt4, Gtk3, Tk? Anything else? macosx is already covered. This could take me a while. Is there a minimum subset that is considered a must-have while the rest can be implemented at a later time?

Note: This is a good example why we are reseved on extending the backend. It's a lot of effort to make this right and consistent across all backends.

Yes, I totally see it, and I want to help you.

For a PoC I'd typically use Qt as it a very capable framework (but maybe I'm biased, because that's the one I'm most familiar with). Tk and Gtk3 and on the lower end of features and good to look at when needing to identify the minimal common feature set.

Note that we do not support Qt4 anymore it's Qt5/6 now.

Not all backends have to be implemented at once. The important point is that we have to make sure there are no surpises from the other backend that would conflict with our design.

For a release, I'd say Qt, Tk and Mac should be covered as these are the morst common ones. But you can make separate PRs if that makes it easier.