Tkinter 快顯功能表關閉殘影調查報告

⚠ 本篇報告全文由 Codex 生成

1. 摘要

test_tk_manual.py 在 Windows 上顯示 Tkinter 右鍵快顯功能表後，若使用者選擇 Close 並直接在選單 callback 中執行 root.destroy()，主視窗雖然關閉，畫面上卻可能暫時留下選單殘影。

調查確認，問題核心不是一般 Tk widget 沒有刷新，而是 Windows 上的 Tk 選單使用原生 menu loop。選單 callback 執行時，menu.tk_popup() 可能仍未返回；此時銷毀選單的 owner 視窗，會破壞 Windows 正常結束與重繪選單的時序。

目前的修正策略如下：

1. 選單 callback 不直接銷毀主視窗。
2. callback 設定關閉旗標。
3. 呼叫 Windows EndMenu()，明確結束目前執行緒的原生 menu loop。
4. 等 menu.tk_popup() 返回後，再由外層事件處理函式執行 root.destroy()。

目前版本已通過 Python 語法檢查；最終視覺效果仍需由使用者在實際桌面環境確認。

2. 原始展示範例

以下是會觸發問題的最小範例：

import tkinter as tk

root = tk.Tk()
root.geometry("300x100+100+100")

menu = tk.Menu(root, tearoff=0)
menu.add_command(label="Close", command=root.destroy)

def show_menu(event):
    menu.tk_popup(event.x_root, event.y_root)

root.bind("<Button-3>", show_menu)
root.mainloop()

重現步驟：

1. 執行程式。
2. 在主視窗按滑鼠右鍵。
3. 在快顯功能表選擇 Close。
4. 觀察主視窗消失後，選單區域是否留下殘影。

問題點在這一行：

menu.add_command(label="Close", command=root.destroy)

它會在選單 callback 尚處於原生選單處理流程時，立即銷毀 owner 視窗。

3. 平台行為與根因

Tk 的選單行為會依視窗平台而不同。Tk 開發資料指出，在 Windows 上選單由原生機制處理，而且 menu post 呼叫可能在選單關閉前不返回，但等待期間仍會處理事件。參考資料：

• Tk ticket：Windows 上的 menu post 行為
• Tk menu.tcl 原始碼與 MenuUnpost 流程
• Microsoft EndMenu API

事件順序可概括為：

使用者點選 Close
        |
        v
Tk 執行選單 command callback
        |
        |  此時 Windows menu loop 可能仍在運作
        v
若 callback 直接 root.destroy()
        |
        v
owner 視窗提前消失，選單清除／重繪時序不完整
        |
        v
可能留下快顯功能表殘影

因此，安全的關閉點不是選單 callback 本身，而是原生 menu loop 結束、tk_popup() 返回之後。

4. 修正歷程

4.1 直接銷毀主視窗

初始程式在選單命令中直接呼叫：

menu.add_command(label="Close", command=root.destroy)

結果：主視窗關閉，但 Windows 桌面可能留下快顯功能表殘影。

4.2 unpost()、釋放 grab，再用 after_idle() 關閉

第一次嘗試：

def close_window():
    menu.unpost()
    menu.grab_release()
    root.after_idle(root.destroy)

結果：殘影仍存在。

原因：after_idle() 只保證目前 Tk callback 返回後執行，不保證 Windows 原生 menu loop 已經退出。

4.3 延遲 100 ms 後關閉

第二次嘗試：

root.after(100, root.destroy)

結果：殘影仍存在。

原因：原生選單等待期間仍會處理 Tk 事件，因此計時器可能在 tk_popup() 尚未返回時觸發。增加任意延遲不能建立可靠的事件順序，只會造成時間相依的行為。

4.4 callback 只設定旗標

第三次嘗試讓 callback 只記錄關閉要求：

def close_window():
    global close_requested
    close_requested = True

並在 tk_popup() 返回後關閉：

menu.tk_popup(event.x_root, event.y_root)
if close_requested:
    root.destroy()

結果：選擇 Close 後主視窗沒有立即關閉，必須再按一下滑鼠，選單與主視窗才一起消失。

原因：只設定旗標沒有主動終止目前的原生 menu loop，所以 tk_popup() 仍未返回，外層的 root.destroy() 尚無機會執行。

4.5 使用 menu.unpost() 或 tk::MenuUnpost

後續分別測試 widget 層級的：

menu.unpost()

以及 Tk 內部完整狀態清理：

root.tk.call("tk::MenuUnpost", menu._w)

結果：實際環境仍需額外滑鼠點擊才能讓 tk_popup() 返回。

這表示 Tk 層級的 unpost 清理在此 Windows 原生 menu loop 中不足以立即終止追蹤流程。

4.6 使用 Windows EndMenu()

目前版本改用 Windows API：

ctypes.windll.user32.EndMenu()

EndMenu() 的用途是結束呼叫執行緒目前作用中的選單。callback 僅終止 menu loop，不銷毀 owner；等 tk_popup() 返回後，才關閉主視窗。

5. 目前完整展示範例

import ctypes
import tkinter as tk

root = tk.Tk()
root.geometry("300x100+100+100")

label = tk.Label(root, text="Right-click me")
label.pack(fill="both", expand=True)

menu = tk.Menu(root, tearoff=0)
close_requested = False

def close_window():
    global close_requested
    close_requested = True
    ctypes.windll.user32.EndMenu()

menu.add_command(label="Close", command=close_window)

def show_menu(event):
    try:
        menu.tk_popup(event.x_root, event.y_root)
    finally:
        menu.grab_release()

    if close_requested:
        root.destroy()

root.bind("<Button-3>", show_menu)
label.bind("<Button-3>", show_menu)
root.mainloop()

6. 修正版事件順序

使用者點選 Close
        |
        v
close_window() 設定 close_requested
        |
        v
EndMenu() 結束 Windows 原生 menu loop
        |
        v
menu.tk_popup() 返回
        |
        v
finally 釋放 menu grab
        |
        v
show_menu() 檢查 close_requested
        |
        v
root.destroy() 安全銷毀主視窗

7. 驗證方式

7.1 語法檢查

.\.venv\Scripts\python.exe -m py_compile test_tk_manual.py

預期結果：命令結束碼為 0，沒有輸出語法錯誤。

7.2 手動視覺測試

.\.venv\Scripts\pythonw.exe .\test_tk_manual.py

測試項目：

編號	操作	預期結果
1	在主視窗按右鍵	Close 選單立即出現
2	點選 Close	選單與主視窗立即消失
3	觀察原選單位置	不留下選單內容或陰影殘影
4	再次執行，點選選單外部	選單取消，主視窗保持開啟
5	重複快速開啟與取消選單	不應卡住 grab 或要求額外點擊

7.3 驗收狀態

項目	狀態
Python 語法檢查	已通過
原始問題重現	已確認
after_idle() 修正	失敗
100 ms 延遲修正	失敗
Tk unpost 修正	失敗
Windows EndMenu() 修正	已實作，待使用者確認視覺結果

8. 限制與後續考量

目前修正呼叫 Windows API，因此是 Windows 專用方案。若程式未來需要跨平台，應依 root.tk.call("tk", "windowingsystem") 分流：Windows 使用 EndMenu()；其他平台保留 Tk 原生關閉流程。

若 EndMenu() 在目標機器上仍無法消除殘影，下一步不應再增加延遲時間，而應考慮：

1. 收集 Python、Tcl/Tk 與 Windows 的確切版本。
2. 建立獨立的最小重現程式並記錄螢幕畫面。
3. 改用自訂 Toplevel 實作非原生快顯選單，以完全避開 Windows native menu loop。
4. 比較不同 Tcl/Tk 發行版本，確認是否為特定版本的 Windows 選單缺陷。