Gui Development

GUI 開發 Skill

何時使用此 Skill

當需要：

1. 新增 GUI 元件（按鈕、對話框、進度條）
2. 處理背景執行緒（避免 UI 凍結）
3. 更新進度顯示（執行緒安全）
4. 修復 GUI 問題（響應速度、錯誤處理）

核心原則

⚠️ 執行緒安全規則

1. 長時間操作必須在背景執行緒
2. GUI 更新必須回主執行緒 (root.after())
3. 共用資料使用 threading.Lock

GUI 元件範例

新增按鈕

def create_my_button(self):
    """建立新按鈕"""
    btn = ttk.Button(
        self.button_frame,
        text="🚀 執行操作",
        command=self.on_button_click,
        style='primary.TButton'
    )
    btn.pack(side='left', padx=5)

def on_button_click(self):
    """按鈕點擊處理"""
    # 啟動背景執行緒
    thread = threading.Thread(
        target=self._worker_function,
        daemon=True
    )
    thread.start()

背景執行緒模式

def _worker_function(self):
    """背景執行緒（長時間操作）"""
    try:
        # 執行耗時操作
        result = do_long_task()
        
        # 回到主執行緒更新 UI
        self.root.after(0, lambda: self.show_result(result))
        
    except Exception as e:
        # 錯誤處理（也要回主執行緒）
        self.root.after(0, lambda: self.show_error(str(e)))

進度更新

def update_progress(self, message: str):
    """更新進度（執行緒安全）"""
    # 確保在主執行緒執行
    self.root.after(0, lambda: self._update_progress_ui(message))

def _update_progress_ui(self, message: str):
    """實際更新 UI（主執行緒）"""
    self.progress_label.config(text=message)
    self.progress_bar.step()

常見錯誤與解決

錯誤 1: UI 凍結

# ❌ 錯誤：在主執行緒執行耗時操作
def on_click(self):
    result = long_task()  # UI 凍結！
    self.show_result(result)

# ✅ 正確：使用背景執行緒
def on_click(self):
    threading.Thread(target=self._worker, daemon=True).start()

def _worker(self):
    result = long_task()
    self.root.after(0, lambda: self.show_result(result))

錯誤 2: 跨執行緒 UI 更新

# ❌ 錯誤：直接在背景執行緒更新 UI
def _worker(self):
    self.label.config(text="完成")  # 可能崩潰！

# ✅ 正確：使用 root.after()
def _worker(self):
    self.root.after(0, lambda: self.label.config(text="完成"))

相關檔案

• src/ui/main_gui.py - 主介面
• src/ui/preferences_dialog.py - 偏好設定對話框
• src/ui/search_result_dialog.py - 搜尋結果對話框

Converted and distributed by TomeVault — claim your Tome and manage your conversions.