Enhance windows native icon handling

Updated favicon handling to require local .ico files in Windows native mode.

Added a function to create unique Windows application IDs based on the title.

Improved icon setting logic and added error logging for better stability.

Cleaned up the codebase by removing old window icon tests.

Updated documentation to match the new icon loading requirements.

Author: Ebrahim Nejati

nicegui/native/native_mode.py

@@ -3,6 +3,7 @@
 import _thread
 import multiprocessing as mp
 import queue
+import re
 import socket
 import sys
 import time
@@ -30,6 +31,17 @@
     optional_features.register('webview')
 
 
+WINDOWS_APP_ID_PREFIX = 'nicegui.'
+WINDOWS_APP_ID_MAX_LENGTH = 128
+
+
+def _create_windows_app_id(title: str) -> str:
+    normalized_title = re.sub(r'[^0-9A-Za-z]+', '_', title).strip('_')
+    suffix = normalized_title or 'app'
+    max_suffix_length = WINDOWS_APP_ID_MAX_LENGTH - len(WINDOWS_APP_ID_PREFIX)
+    return f'{WINDOWS_APP_ID_PREFIX}{suffix[:max_suffix_length]}'
+
+
 def _open_window(
     protocol: str, host: str, port: int, title: str, width: int, height: int, fullscreen: bool, frameless: bool,
     method_queue: mp.Queue, response_queue: mp.Queue, event_sender: Connection,
@@ -54,20 +66,18 @@ def _open_window(
     window.events.closed += closed.set
     _bind_pywebview_events(window, event_sender)
 
-    if sys.platform == 'win32' and favicon is not None and helpers.is_file(favicon):
-        favicon_path = Path(favicon)
-
+    if sys.platform == 'win32' and favicon is not None:
         def on_window_shown() -> None:
             hwnd = window_icon.find_window_by_title(title)
             if not hwnd:
                 log.warning('Could not find native window by title to set icon')
                 return
-            icon_path = str(favicon_path.resolve())
+            icon_path = str(favicon)
             # Set window icon for title bar and Alt+Tab
             if not window_icon.set_window_icon_windows(hwnd, icon_path):
                 log.warning('Could not set native window icon (unsupported format?)')
             # Set property store for taskbar icon
-            app_id = f'nicegui.{title.replace(" ", "_")}'
+            app_id = _create_windows_app_id(title)
             window_icon.set_window_property_store(hwnd, app_id, icon_path)
         window.events.shown += on_window_shown
 

nicegui/native/window_icon.py

@@ -3,7 +3,8 @@
 import ctypes
 import sys
 from ctypes import wintypes
-from pathlib import Path
+
+from ..logging import log
 
 user32 = ctypes.windll.user32 if sys.platform == 'win32' else None  # type: ignore[attr-defined]
 shell32 = ctypes.windll.shell32 if sys.platform == 'win32' else None  # type: ignore[attr-defined]
@@ -12,12 +13,12 @@
 
 # COM GUIDs for IPropertyStore (defined unconditionally for mypy on non-Windows)
 class GUID(ctypes.Structure):
-    _fields_ = [('Data1', ctypes.c_ulong), ('Data2', ctypes.c_ushort),  # noqa: RUF012
+    _fields_ = [('Data1', ctypes.c_ulong), ('Data2', ctypes.c_ushort),
                 ('Data3', ctypes.c_ushort), ('Data4', ctypes.c_ubyte * 8)]
 
 
 class PROPERTYKEY(ctypes.Structure):
-    _fields_ = [('fmtid', GUID), ('pid', ctypes.c_ulong)]  # noqa: RUF012
+    _fields_ = [('fmtid', GUID), ('pid', ctypes.c_ulong)]
 
 
 # PKEY_AppUserModel_ID = {9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3}, 5
@@ -31,7 +32,7 @@ class PROPERTYKEY(ctypes.Structure):
 
 def find_window_by_title(title: str) -> int | None:
     """Find HWND by exact title. None on non-Windows or not found."""
-    if sys.platform != 'win32' or user32 is None:
+    if user32 is None:
         return None
     result: list[int] = []
 
@@ -51,79 +52,83 @@ def enum_cb(hwnd: int, _: int) -> bool:
 
 def set_window_icon_windows(hwnd: int, icon_path: str) -> bool:
     """Set window icon via LoadImageW/WM_SETICON for title bar and Alt+Tab."""
-    if sys.platform != 'win32' or user32 is None or not Path(icon_path).is_file():
+    if user32 is None:
         return False
-    path = str(Path(icon_path).resolve())
-    hicon = user32.LoadImageW(None, path, IMAGE_ICON, 0, 0, LR_LOADFROMFILE)
+    hicon = user32.LoadImageW(None, icon_path, IMAGE_ICON, 0, 0, LR_LOADFROMFILE)
     if not hicon:
         return False
-    user32.SendMessageW(hwnd, WM_SETICON, ICON_SMALL, hicon)
-    user32.SendMessageW(hwnd, WM_SETICON, ICON_BIG, hicon)
+    old_small = user32.SendMessageW(hwnd, WM_SETICON, ICON_SMALL, hicon)
+    old_big = user32.SendMessageW(hwnd, WM_SETICON, ICON_BIG, hicon)
+    # Keep the new icon handle alive while the window exists.
+    # Destroying it too early can cause Alt+Tab/taskbar to fall back to defaults.
+    for old_icon in (old_small, old_big):
+        if old_icon and old_icon != hicon:
+            user32.DestroyIcon(old_icon)
     return True
 
 
 def set_window_property_store(hwnd: int, app_id: str, icon_path: str) -> bool:
     """Set window properties via IPropertyStore for proper taskbar icon on Windows 7+."""
-    if sys.platform != 'win32' or shell32 is None:
+    if shell32 is None:
         return False
 
-    try:
-        # Define PROPVARIANT structure
-        class PROPVARIANT(ctypes.Structure):
-            _fields_ = [  # noqa: RUF012
-                ('vt', ctypes.c_ushort),
-                ('wReserved1', ctypes.c_ushort),
-                ('wReserved2', ctypes.c_ushort),
-                ('wReserved3', ctypes.c_ushort),
-                ('pwszVal', ctypes.c_wchar_p),
-                ('padding', ctypes.c_ulonglong),
-            ]
-
-        VT_LPWSTR = 31
+    class PROPVARIANT(ctypes.Structure):
+        _fields_ = [
+            ('vt', ctypes.c_ushort),
+            ('wReserved1', ctypes.c_ushort),
+            ('wReserved2', ctypes.c_ushort),
+            ('wReserved3', ctypes.c_ushort),
+            ('pwszVal', ctypes.c_wchar_p),
+            ('padding', ctypes.c_ulonglong),
+        ]
+
+    VT_LPWSTR = 31
+    pps = ctypes.c_void_p()
+    release_fn = None
 
+    try:
         # Get IPropertyStore interface
         IID_IPropertyStore = GUID(0x886D8EEB, 0x8CF2, 0x4446,
                                   (0x8D, 0x02, 0xCD, 0xBA, 0x1D, 0xBD, 0xCF, 0x99))
 
-        # SHGetPropertyStoreForWindow
         SHGetPropertyStoreForWindow = shell32.SHGetPropertyStoreForWindow
         SHGetPropertyStoreForWindow.argtypes = [wintypes.HWND, ctypes.POINTER(GUID), ctypes.POINTER(ctypes.c_void_p)]
         SHGetPropertyStoreForWindow.restype = ctypes.HRESULT
 
-        pps = ctypes.c_void_p()
         hr = SHGetPropertyStoreForWindow(hwnd, ctypes.byref(IID_IPropertyStore), ctypes.byref(pps))
         if hr != 0 or not pps:
+            log.warning('Could not get IPropertyStore for window (HRESULT=%s)', hr)
             return False
 
-        # Get vtable
         vtable = ctypes.cast(ctypes.cast(pps, ctypes.POINTER(ctypes.c_void_p))[0],
                              ctypes.POINTER(ctypes.c_void_p * 10))[0]
+        set_value = ctypes.WINFUNCTYPE(ctypes.HRESULT, ctypes.c_void_p,
+                                       ctypes.POINTER(PROPERTYKEY), ctypes.POINTER(PROPVARIANT))(vtable[6])
+        commit = ctypes.WINFUNCTYPE(ctypes.HRESULT, ctypes.c_void_p)(vtable[7])
+        release_fn = ctypes.WINFUNCTYPE(ctypes.c_ulong, ctypes.c_void_p)(vtable[2])
 
-        # SetValue is at index 6 in IPropertyStore vtable
-        SetValue = ctypes.WINFUNCTYPE(ctypes.HRESULT, ctypes.c_void_p,
-                                      ctypes.POINTER(PROPERTYKEY), ctypes.POINTER(PROPVARIANT))(vtable[6])
-
-        # Commit is at index 7
-        Commit = ctypes.WINFUNCTYPE(ctypes.HRESULT, ctypes.c_void_p)(vtable[7])
-
-        # Release is at index 2
-        Release = ctypes.WINFUNCTYPE(ctypes.c_ulong, ctypes.c_void_p)(vtable[2])
-
-        # Set AppUserModelID (vt=VT_LPWSTR, reserved=0, pwszVal=app_id)
         pv_id = PROPVARIANT(VT_LPWSTR, 0, 0, 0, app_id, 0)
-        SetValue(pps, ctypes.byref(PKEY_AppUserModel_ID), ctypes.byref(pv_id))
+        hr = set_value(pps, ctypes.byref(PKEY_AppUserModel_ID), ctypes.byref(pv_id))
+        if hr != 0:
+            log.warning('Could not set AppUserModelID property (HRESULT=%s)', hr)
+            return False
 
-        # Set RelaunchIconResource (format: "path,index")
         icon_resource = f'{icon_path},0'
         pv_icon = PROPVARIANT(VT_LPWSTR, 0, 0, 0, icon_resource, 0)
-        SetValue(pps, ctypes.byref(PKEY_AppUserModel_RelaunchIconResource), ctypes.byref(pv_icon))
-
-        # Commit changes
-        Commit(pps)
+        hr = set_value(pps, ctypes.byref(PKEY_AppUserModel_RelaunchIconResource), ctypes.byref(pv_icon))
+        if hr != 0:
+            log.warning('Could not set RelaunchIconResource property (HRESULT=%s)', hr)
+            return False
 
-        # Release
-        Release(pps)
+        hr = commit(pps)
+        if hr != 0:
+            log.warning('Could not commit property store changes (HRESULT=%s)', hr)
+            return False
 
         return True
-    except Exception:
+    except (ctypes.ArgumentError, OSError, TypeError, ValueError):
+        log.exception('Error while setting native window property store values')
         return False
+    finally:
+        if pps and release_fn is not None:
+            release_fn(pps)

nicegui/ui_run.py

@@ -91,7 +91,8 @@ def run(root: Callable | None = None, *,
     :param port: use this port (default: 8080 in normal mode, and an automatically determined open port in native mode)
     :param title: page title (default: `'NiceGUI'`, can be overwritten per page)
     :param viewport: page meta viewport content (default: `'width=device-width, initial-scale=1'`, can be overwritten per page)
-    :param favicon: relative filepath, absolute URL to a favicon (default: `None`, NiceGUI icon will be used) or emoji (e.g. `'🚀'`, works for most browsers)
+    :param favicon: relative filepath, absolute URL to a favicon (default: `None`, NiceGUI icon will be used) or emoji (e.g. `'🚀'`, works for most browsers).
+        On Windows native mode, only local file paths are used for the native window icon, and Win32 icon loading expects `.ico`.
     :param dark: whether to use Quasar's dark mode (default: `False`, use `None` for "auto" mode)
     :param language: language for Quasar elements (default: `'en-US'`)
     :param binding_refresh_interval: interval for updating active links (default: 0.1 seconds, bigger is more CPU friendly, *since version 3.4.0*: can be ``None`` to disable update loop)
@@ -240,7 +241,7 @@ def run_script() -> None:
         native_host = '127.0.0.1' if host == '0.0.0.0' else host
         if reload:
             shutdown_event = multiprocessing.Event()
-        native_favicon = str(Path(favicon).resolve()) if favicon and helpers.is_file(favicon) else favicon
+        native_favicon = str(Path(favicon).resolve()) if favicon and helpers.is_file(favicon) else None
         native_module.activate(protocol, native_host, port, title, width, height, fullscreen, frameless,
                                shutdown_event, native_favicon)
     else:

tests/test_native_window_icon.py

@@ -46,7 +46,8 @@ def urls_demo():
     This is typically pre-installed on standard Windows installations,
     but may be missing on minimal or freshly installed systems.
 
-    On Windows, a file-path `favicon` is also used as the native window icon (taskbar, title bar); `.ico` recommended.
+    On Windows, a file-path `favicon` is also used as the native window icon (taskbar, title bar).
+    Native icon loading uses Win32 `LoadImageW(..., IMAGE_ICON, ...)`, so `.ico` is required (`.cur`/`.ani` are also supported by Win32 icon loading; `.png` is not).
 ''', tab=lambda: ui.label('NiceGUI'))
 def native_mode_demo():
     from nicegui import app