Repository navigation
[ENH]: Distinguish between built-in and user-provided images for toolbar icons #22164
Description
Problem
Currently, the backends treat icon images for the toolbar the same whether they're built-in, or provided by a user. This extends to replacing image.png image_large.png if it exists (#22135), and changing the black pixels in the icon on a dark theme (#22150). Both of these could be unwanted - in the first case, mpl can load a different file from the one requested, and in the second case, it modifies the image.
Proposed solution
Should we consider treating built-in and user-provided image files differently? Maybe by adding function arguments that control these two behaviours, having separate public and private functions for adding tools, or checking in the code whether the icon is being loaded from inside /mpl-data or a different location?
Activity
timhoffm commented on Jan 9, 2022
I agree that our internal processing can conflict with user icons. This should be avoided and we have two ways to do this
I'd prefer to have a closer look at 2 first. Users might want to opt into our features like choosing high-res images and adapting color according to the theme. In general, it would be a good idea to explicitly document what users should provide as icon. I suppose we don't have more than saying you can add an icon file. https://matplotlib.org/devdocs/api/backend_bases_api.html#matplotlib.backend_bases.ToolContainerBase.add_toolitem
We should specify
Only if we then think that we still need an explicit flag for user icons, we should follow up on that.
QuLogic commented on Jan 11, 2022
I need to experiment a bit more, but I believe GTK4 doesn't correctly theme icons because we are not following the icon theme spec directory layout. If that is the case and I can't figure out a way around that, then I think we should a) move icons to corresponding directories, and b) say that is how we expect user-provided icons to work.
github-actions commented on Nov 19, 2025
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!