[Windows] TRootBrowser cannot display non-ASCII filenames (GDK encoding + font fallback)

[wacfrr]

Check duplicate issues.

• Checked for duplicates

Description

[Windows] TRootBrowser cannot display non-ASCII filenames (GDK encoding + font fallback)

1. The Problem

On Windows platforms, TRootBrowser cannot correctly display filenames or directory paths containing characters outside the standard ASCII/Latin-1 range, including but not limited to Chinese, Japanese, and Korean (CJK) characters.

Instead of rendering properly, these filenames appear as garbled text (Mojibake). This is a long-standing limitation that affects both custom source builds and the official pre-built MSVC binaries on Windows.

I am aware that ROOT already features a new web-based GUI based on OpenUI5, but this encoding issue has existed for many years and continues to affect users who rely on the TRootBrowser on Windows.

2. Potential Root Cause Analysis

My local investigation suggests that this rendering failure stems from two interconnected issues within the legacy GDK graphics backend located under graf2d/win32gdk/gdk/src/gdk/win32/:

• Windows Encoding Context Mismatch (gdkim-win32.c):
  Inside gdk_nmbstowchar_ts, the implementation relies on the standard C runtime function mbstowcs to convert multi-byte sequences into wide characters. On Windows, the behavior of mbstowcs is strictly tied to the system's active legacy ANSI code page (e.g., CP936/GBK on Chinese Windows, CP932/Shift-JIS on Japanese Windows).
  This introduces an encoding management conflict: the backend attempts to decode the incoming string using the OS legacy code page, whereas the upper layers of ROOT pass down strings uniformly encoded in UTF-8. This mismatch causes mbstowcs to misinterpret the UTF-8 byte streams, resulting in corrupted wide-character output.

• Missing Font Fallback Mechanism (gdkfont-win32.c):
  When rendering these characters, gdk_wchar_text_handle attempts to map the character to an appropriate font block. If an exact glyph match for the specific Unicode block is missing in the primary font, the font pointer is silently fallback-assigned to NULL. Consequently, any non-ASCII characters outside the primary font's immediate coverage are dropped entirely during the drawing cycle rather than substituted.

Additional context on encoding: I noticed that ROOT's build system already includes config/root-manifest.xml.in, which explicitly declares <activeCodePage>UTF-8</activeCodePage>. This means ROOT officially expects the process to operate under a UTF-8 code page on Windows. Since the manifest guarantees that strings entering the GDK backend are already valid UTF-8, a fix based on UTF-8 decoding (rather than relying on the system ANSI code page) is not only safe but consistent with ROOT's own configuration intent.

3. Proposed Fix

To resolve this without introducing massive architectural changes to the native graphics engine, I have tested two minimal patches within graf2d/win32gdk/gdk/src/gdk/win32/:

• In gdkim-win32.c: Replace the system-dependent mbstowcs call with an explicit, manual UTF-8 decoding loop. Since ROOT's manifest already sets the active code page to UTF-8, this ensures that incoming multi-byte filenames are always consistently decoded as UTF-8 into proper wide characters, bypassing the interference of the local Windows ANSI code page.

• In gdkfont-win32.c: Modify the fallback logic so that when an exact Unicode block match is not found, the system defaults to the first available font in the active font set instead of returning NULL. This guarantees that characters are at least rendered via a fallback font rather than being silently discarded.

Expected Behavior After Fix

After applying the proposed fixes, CJK filenames are correctly displayed in TRootBrowser and no longer appear as garbled text or missing characters.

4. Notes

• This proposed fix does not aim to implement a perfect, comprehensive "best match font fallback" system; it is a minimal, defensive patch designed to ensure text visibility and prevent silent glyph dropping on Windows.
• These underlying GDK routines seem to have remained unchanged in the upstream Windows port for a long time, leading to consistent reproduction across multiple ROOT versions.
• I am more than happy to submit a Pull Request (PR) with these minimal changes if the maintainers agree that this is an acceptable approach for stabilizing the native Windows GUI experience.

Reproducer

Steps to Reproduce

1. On a Windows machine, create a dummy file with non-ASCII characters in its name (e.g., 你好.txt) in any directory.
2. Open Windows Terminal / Command Prompt, and launch ROOT with the web GUI explicitly disabled to force the legacy native interface:

   root --web=off

3. Open the traditional TBrowser from the ROOT prompt:

   root [0] new TBrowser

4. Navigate to the directory where 你好.txt was created.
5. Observed Behavior: The filename 你好.txt is not displayed correctly. It either appears as garbled text (Mojibake) or the non-ASCII characters are silently dropped/skipped entirely in the tree and icon views.

ROOT version

This issue has been observed across multiple versions of ROOT (including v6.38.04 and v6.39.99) on Windows platforms."

Installation method

pre-built binary

Operating system

Windows 10 / 11 (Simplified Chinese Edition, System ANSI Code Page: CP936 / GBK)

Additional context

No response

[linev]

Does web-based TBrowser works for you?

[wacfrr]

Does web-based TBrowser works for you?

Yes, the web-based TBrowser works perfectly for me and renders non-ASCII filenames correctly, precisely because it operates entirely on UTF-8 encoding end-to-end.

However, the reason I am raising this issue for the native GDK-based TRootBrowser is that many users still explicitly rely on --web=off or the legacy GUI due to specific environment constraints (such as restricted port/firewall policies in certain institutional networks, remote graphics forwarding, or general preference for native window performance).

Given that the proposed fix for the legacy GDK backend is extremely minimal and achieves the exact same UTF-8 consistency that the project intends, I believe patching this would be highly beneficial for ensuring a seamless experience across both GUI modes on Windows.

[linev]

Yes, the web-based TBrowser works perfectly

Grate!

Given that the proposed fix for the legacy GDK backend is extremely minimal and achieves the exact same UTF-8 consistency that the project intends, I believe patching this would be highly beneficial for ensuring a seamless experience across both GUI modes on Windows.

Can you provide PR with proposed changes?

[wacfrr]

Can you provide PR with proposed changes?

Sure, I would be happy to provide a PR with the proposed changes!

I will prepare and submit the patch as soon as possible, making sure to strictly follow the official "How to Contribute Code to ROOT" guidelines. Thanks.