Adding Custom Icons and Tooltips to QGIS Toolbar Buttons

"""
toolbar_button_manager.py — production-ready toolbar button registration for QGIS plugins.
Register in initGui(), clean up in unload().
"""

import functools
from pathlib import Path
from typing import Callable, List, Optional

from qgis.PyQt.QtWidgets import QAction
from qgis.PyQt.QtGui import QIcon
from qgis.core import QgsApplication, QgsMessageLog, Qgis
from qgis.utils import iface


class ToolbarButtonManager:
    """
    Manages custom toolbar button registration and teardown for a QGIS plugin.

    Always store one instance on the main plugin class so Python's reference
    count never drops to zero while the plugin is loaded.
    """

    TAG = "MyPlugin"

    def __init__(self) -> None:
        # Strong references prevent Qt from garbage-collecting QAction objects
        # after the enclosing function scope exits.
        self.actions: List[QAction] = []

    def add_button(
        self,
        icon_path: str,
        tooltip: str,
        callback: Callable,
        *,
        object_name: str = "custom_action",
        callback_args: Optional[tuple] = None,
    ) -> QAction:
        """
        Register a toolbar button with a custom icon, tooltip, and callback.

        Args:
            icon_path:    Absolute or plugin-relative path to an SVG/PNG icon.
            tooltip:      Hover text shown above the button (also set as status tip).
            callback:     Python callable triggered on button click.
            object_name:  Qt object name — used for automated testing lookups.
            callback_args: Optional tuple of extra arguments forwarded to callback
                           via functools.partial.

        Returns:
            The registered QAction (caller may store it for later shortcut binding).
        """
        resolved = Path(icon_path).resolve()

        if resolved.exists():
            icon = QIcon(str(resolved))
        else:
            QgsMessageLog.logMessage(
                f"Icon not found at {resolved}; using theme fallback.",
                self.TAG,
                level=Qgis.Warning,
            )
            icon = QgsApplication.getThemeIcon("/mActionZoomFullExtent.svg")

        # iface.mainWindow() as parent: ensures the action joins the correct
        # Qt object tree and is destroyed with the main window on shutdown.
        action = QAction(icon, tooltip, iface.mainWindow())
        action.setObjectName(object_name)
        action.setToolTip(tooltip)
        action.setStatusTip(tooltip)  # written to the QGIS status bar on hover

        handler = (
            functools.partial(callback, *callback_args)
            if callback_args
            else callback
        )
        action.triggered.connect(handler)

        iface.addToolBarIcon(action)
        self.actions.append(action)
        return action

    def remove_all(self) -> None:
        """
        Deregister every managed action from the toolbar.
        Call this from the plugin's unload() method.
        """
        for action in self.actions:
            iface.removeToolBarIcon(action)
        self.actions.clear()

"""
my_plugin.py — minimal plugin skeleton demonstrating ToolbarButtonManager usage.
"""

import os
from qgis.utils import iface
from .toolbar_button_manager import ToolbarButtonManager


class MyPlugin:
    def __init__(self, iface_ref) -> None:
        self._iface = iface_ref
        self._toolbar = ToolbarButtonManager()

    def initGui(self) -> None:
        icon = os.path.join(os.path.dirname(__file__), "icons", "my_tool.svg")
        self._toolbar.add_button(
            icon_path=icon,
            tooltip=self.tr("Run spatial analysis workflow"),
            callback=self._run_analysis,
            object_name="my_plugin_analysis_action",
        )

    def unload(self) -> None:
        # Removes all buttons and releases Qt references cleanly
        self._toolbar.remove_all()

    def _run_analysis(self) -> None:
        iface.messageBar().pushSuccess("MyPlugin", "Analysis complete.")

from qgis.PyQt.QtGui import QIcon
icon = QIcon("/abs/path/my_tool.svg")
print(icon.availableSizes())  # [] means Qt could not parse the file

"""
plugin_main.py — minimal single-action plugin skeleton.
Handles i18n via self.tr(), safe path resolution, and deterministic teardown.
"""

import os
from qgis.gui import QgisInterface
from .toolbar_button_manager import ToolbarButtonManager


class SingleActionPlugin:
    """Minimal plugin demonstrating correct icon + tooltip registration."""

    def __init__(self, iface: QgisInterface) -> None:
        self.iface = iface
        self._toolbar = ToolbarButtonManager()

    def initGui(self) -> None:
        """Called by the plugin manager after the plugin module is imported."""
        icon_path = os.path.join(os.path.dirname(__file__), "icons", "tool.svg")
        self._toolbar.add_button(
            icon_path=icon_path,
            tooltip=self.tr("Export selected features to GeoPackage"),
            callback=self._on_export,
            object_name="single_action_export",
        )

    def unload(self) -> None:
        """Called when the user disables or uninstalls the plugin."""
        self._toolbar.remove_all()

    def _on_export(self) -> None:
        from qgis.utils import iface
        iface.messageBar().pushInfo("Export", "Starting GeoPackage export…")

    def tr(self, message: str) -> str:  # noqa: D401
        """Wrap user-facing strings for Qt Linguist translation pipelines."""
        from qgis.PyQt.QtCore import QCoreApplication
        return QCoreApplication.translate("SingleActionPlugin", message)