kotonebot 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

kotonebot/interop/win/task_dialog.py

@@ -1,513 +1,513 @@
-"""
-Windows Task Dialog interop module.
-
-This module provides Windows TaskDialog functionality and is only available on Windows systems.
-"""
-
-import platform
-import warnings
-
-from kotonebot.util import is_windows
-
-# 检查是否在 Windows 平台上
-if not is_windows():
-    _WINDOWS_ONLY_MSG = (
-        f"TaskDialog is only available on Windows systems. "
-        f"Current system: non-Windows\n"
-        "To use Windows TaskDialog features, please run this code on a Windows system."
-    )
-
-    
-    # 提供虚拟类以避免导入错误
-    class TaskDialog:
-        def __init__(self, *args, **kwargs):
-            raise ImportError(_WINDOWS_ONLY_MSG)
-    
-    # 导出所有常量作为 None
-    __all__ = [
-        "TaskDialog",
-        "TDCBF_OK_BUTTON", "TDCBF_YES_BUTTON", "TDCBF_NO_BUTTON", "TDCBF_CANCEL_BUTTON",
-        "TDCBF_RETRY_BUTTON", "TDCBF_CLOSE_BUTTON",
-        "IDOK", "IDCANCEL", "IDABORT", "IDRETRY", "IDIGNORE", "IDYES", "IDNO", "IDCLOSE",
-        "TD_WARNING_ICON", "TD_ERROR_ICON", "TD_INFORMATION_ICON", "TD_SHIELD_ICON"
-    ]
-    
-    # 设置所有常量为 None 或保留为模块级变量
-    TDCBF_OK_BUTTON = TDCBF_YES_BUTTON = TDCBF_NO_BUTTON = TDCBF_CANCEL_BUTTON = None
-    TDCBF_RETRY_BUTTON = TDCBF_CLOSE_BUTTON = None
-    IDOK = IDCANCEL = IDABORT = IDRETRY = IDIGNORE = IDYES = IDNO = IDCLOSE = None
-    TD_WARNING_ICON = TD_ERROR_ICON = TD_INFORMATION_ICON = TD_SHIELD_ICON = None
-    
-    # 阻止模块加载
-    raise ImportError(_WINDOWS_ONLY_MSG)
-
-# 如果是 Windows，继续正常加载
-import ctypes
-from ctypes import wintypes
-import time
-from typing import List, Tuple, Optional
-from typing import Literal
-
-__all__ = [
-    "TaskDialog",
-    "TDCBF_OK_BUTTON", "TDCBF_YES_BUTTON", "TDCBF_NO_BUTTON", "TDCBF_CANCEL_BUTTON",
-    "TDCBF_RETRY_BUTTON", "TDCBF_CLOSE_BUTTON",
-    "IDOK", "IDCANCEL", "IDABORT", "IDRETRY", "IDIGNORE", "IDYES", "IDNO", "IDCLOSE",
-    "TD_WARNING_ICON", "TD_ERROR_ICON", "TD_INFORMATION_ICON", "TD_SHIELD_ICON"
-]
-
-# --- Windows API 常量定义 ---
-
-# 常用按钮
-TDCBF_OK_BUTTON = 0x0001
-TDCBF_YES_BUTTON = 0x0002
-TDCBF_NO_BUTTON = 0x0004
-TDCBF_CANCEL_BUTTON = 0x0008
-TDCBF_RETRY_BUTTON = 0x0010
-TDCBF_CLOSE_BUTTON = 0x0020
-
-# 对话框返回值
-IDOK = 1
-IDCANCEL = 2
-IDABORT = 3
-IDRETRY = 4
-IDIGNORE = 5
-IDYES = 6
-IDNO = 7
-IDCLOSE = 8
-
-
-# 标准图标 (使用 MAKEINTRESOURCE 宏)
-def MAKEINTRESOURCE(i: int) -> wintypes.LPWSTR:
-    return wintypes.LPWSTR(i)
-
-
-TD_WARNING_ICON = MAKEINTRESOURCE(65535)
-TD_ERROR_ICON = MAKEINTRESOURCE(65534)
-TD_INFORMATION_ICON = MAKEINTRESOURCE(65533)
-TD_SHIELD_ICON = MAKEINTRESOURCE(65532)
-
-# Task Dialog 标志
-TDF_ENABLE_HYPERLINKS = 0x0001
-TDF_USE_HICON_MAIN = 0x0002
-TDF_USE_HICON_FOOTER = 0x0004
-TDF_ALLOW_DIALOG_CANCELLATION = 0x0008
-TDF_USE_COMMAND_LINKS = 0x0010
-TDF_USE_COMMAND_LINKS_NO_ICON = 0x0020
-TDF_EXPAND_FOOTER_AREA = 0x0040
-TDF_EXPANDED_BY_DEFAULT = 0x0080
-TDF_VERIFICATION_FLAG_CHECKED = 0x0100
-TDF_SHOW_PROGRESS_BAR = 0x0200
-TDF_SHOW_MARQUEE_PROGRESS_BAR = 0x0400
-TDF_CALLBACK_TIMER = 0x0800
-TDF_POSITION_RELATIVE_TO_WINDOW = 0x1000
-TDF_RTL_LAYOUT = 0x2000
-TDF_NO_DEFAULT_RADIO_BUTTON = 0x4000
-TDF_CAN_BE_MINIMIZED = 0x8000
-
-# Task Dialog 通知
-TDN_CREATED = 0
-TDN_NAVIGATED = 1
-TDN_BUTTON_CLICKED = 2
-TDN_HYPERLINK_CLICKED = 3
-TDN_TIMER = 4
-TDN_DESTROYED = 5
-TDN_RADIO_BUTTON_CLICKED = 6
-TDN_DIALOG_CONSTRUCTED = 7
-TDN_VERIFICATION_CLICKED = 8
-TDN_HELP = 9
-TDN_EXPANDO_BUTTON_CLICKED = 10
-
-# Windows 消息
-WM_USER = 0x0400
-TDM_SET_PROGRESS_BAR_POS = WM_USER + 114
-
-CommonButtonLiteral = Literal["ok", "yes", "no", "cancel", "retry", "close"]
-IconLiteral = Literal["warning", "error", "information", "shield"]
-
-
-# --- C 结构体定义 (使用 ctypes) ---
-
-class TASKDIALOG_BUTTON(ctypes.Structure):
-    _pack_ = 1
-    _fields_ = [("nButtonID", ctypes.c_int),
-                ("pszButtonText", wintypes.LPCWSTR)]
-
-
-# 定义回调函数指针原型
-PFTASKDIALOGCALLBACK = ctypes.WINFUNCTYPE(
-    ctypes.HRESULT,  # 返回值
-    wintypes.HWND,  # hwnd
-    ctypes.c_uint,  # msg
-    ctypes.c_size_t,  # wParam
-    ctypes.c_size_t,  # lParam
-    ctypes.c_ssize_t  # lpRefData
-)
-
-
-class TASKDIALOGCONFIG(ctypes.Structure):
-    _pack_ = 1
-    _fields_ = [
-        ("cbSize", ctypes.c_uint),
-        ("hwndParent", wintypes.HWND),
-        ("hInstance", wintypes.HINSTANCE),
-        ("dwFlags", ctypes.c_uint),
-        ("dwCommonButtons", ctypes.c_uint),
-        ("pszWindowTitle", wintypes.LPCWSTR),
-        ("pszMainIcon", wintypes.LPCWSTR),
-        ("pszMainInstruction", wintypes.LPCWSTR),
-        ("pszContent", wintypes.LPCWSTR),
-        ("cButtons", ctypes.c_uint),
-        ("pButtons", ctypes.POINTER(TASKDIALOG_BUTTON)),
-        ("nDefaultButton", ctypes.c_int),
-        ("cRadioButtons", ctypes.c_uint),
-        ("pRadioButtons", ctypes.POINTER(TASKDIALOG_BUTTON)),
-        ("nDefaultRadioButton", ctypes.c_int),
-        ("pszVerificationText", wintypes.LPCWSTR),
-        ("pszExpandedInformation", wintypes.LPCWSTR),
-        ("pszExpandedControlText", wintypes.LPCWSTR),
-        ("pszCollapsedControlText", wintypes.LPCWSTR),
-        ("pszFooterIcon", wintypes.LPCWSTR),
-        ("pszFooter", wintypes.LPCWSTR),
-        ("pfCallback", PFTASKDIALOGCALLBACK),  # 使用定义好的原型
-        ("lpCallbackData", ctypes.c_ssize_t),
-        ("cxWidth", ctypes.c_uint)
-    ]
-
-
-# --- 加载 comctl32.dll 并定义函数原型 ---
-
-comctl32 = ctypes.WinDLL('comctl32')
-user32 = ctypes.WinDLL('user32')
-
-TaskDialogIndirect = comctl32.TaskDialogIndirect
-TaskDialogIndirect.restype = ctypes.HRESULT
-TaskDialogIndirect.argtypes = [
-    ctypes.POINTER(TASKDIALOGCONFIG),
-    ctypes.POINTER(ctypes.c_int),
-    ctypes.POINTER(ctypes.c_int),
-    ctypes.POINTER(wintypes.BOOL)
-]
-
-
-# --- Python 封装类 ---
-
-class TaskDialog:
-    """
-    一个用于显示 Windows TaskDialog 的 Python 封装类。
-    支持自定义按钮、单选按钮、进度条、验证框等。
-    """
-
-    def __init__(self,
-        parent_hwnd: Optional[int] = None,
-        title: str = "Task Dialog",
-        main_instruction: str = "",
-        content: str = "",
-        common_buttons: int | List[CommonButtonLiteral] = TDCBF_OK_BUTTON,
-        main_icon: Optional[wintypes.LPWSTR | int | IconLiteral] = None,
-        footer: str = "",
-        custom_buttons: Optional[List[Tuple[int, str]]] = None,
-        default_button: int = 0,
-        radio_buttons: Optional[List[Tuple[int, str]]] = None,
-        default_radio_button: int = 0,
-        verification_text: Optional[str] = None,
-        verification_checked_by_default: bool = False,
-        show_progress_bar: bool = False,
-        show_marquee_progress_bar: bool = False
-    ):
-        """初始化 TaskDialog 实例。
-
-        :param parent_hwnd: 父窗口的句柄。
-        :param title: 对话框窗口的标题。
-        :param main_instruction: 对话框的主要指令文本。
-        :param content: 对话框的详细内容文本。
-        :param common_buttons: 要显示的通用按钮。可以是以下两种形式之一：
-                               1. TDCBF_* 常量的按位或组合 (例如 TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON)
-                               2. 字符串列表，支持 "ok", "yes", "no", "cancel", "retry", "close"
-        :param main_icon: 主图标。可以是以下几种形式之一：
-                          1. TD_*_ICON 常量之一
-                          2. HICON 句柄
-                          3. 字符串："warning", "error", "information", "shield"
-        :param footer: 页脚区域显示的文本。
-        :param custom_buttons: 自定义按钮列表。每个元组包含 (按钮ID, 按钮文本)。
-        :param default_button: 默认按钮的ID。可以是通用按钮ID (例如 IDOK) 或自定义按钮ID。
-        :param radio_buttons: 单选按钮列表。每个元组包含 (按钮ID, 按钮文本)。
-        :param default_radio_button: 默认选中的单选按钮的ID。
-        :param verification_text: 验证复选框的文本。如果为 None，则不显示复选框。
-        :param verification_checked_by_default: 验证复选框是否默认勾选。
-        :param show_progress_bar: 是否显示标准进度条。
-        :param show_marquee_progress_bar: 是否显示跑马灯式进度条。
-        """
-        self.config = TASKDIALOGCONFIG()
-        self.config.cbSize = ctypes.sizeof(TASKDIALOGCONFIG)
-        self.config.hwndParent = parent_hwnd
-        self.config.dwFlags = TDF_ALLOW_DIALOG_CANCELLATION | TDF_POSITION_RELATIVE_TO_WINDOW
-        self.config.dwCommonButtons = self._process_common_buttons(common_buttons)
-        self.config.pszWindowTitle = title
-        self.config.pszMainInstruction = main_instruction
-        self.config.pszContent = content
-        self.config.pszFooter = footer
-
-        self.progress: int = 0
-        if show_progress_bar or show_marquee_progress_bar:
-            # 进度条暂时还没实现
-            raise NotImplementedError("Progress bar is not implemented yet.")
-            self.config.dwFlags |= TDF_CALLBACK_TIMER
-            if show_progress_bar:
-                self.config.dwFlags |= TDF_SHOW_PROGRESS_BAR
-            else:
-                self.config.dwFlags |= TDF_SHOW_MARQUEE_PROGRESS_BAR
-
-        # 将实例方法转为 C 回调函数指针。
-        # 必须将其保存为实例成员，否则会被垃圾回收！
-        self._callback_func_ptr = PFTASKDIALOGCALLBACK(self._callback)
-        self.config.pfCallback = self._callback_func_ptr
-        # 将本实例的id作为lpCallbackData传递，以便在回调中识别
-        self.config.lpCallbackData = id(self)
-
-        # --- 图标设置 ---
-        processed_icon = self._process_main_icon(main_icon)
-        if processed_icon is not None:
-            if isinstance(processed_icon, wintypes.LPWSTR):
-                self.config.pszMainIcon = processed_icon
-            else:
-                self.config.dwFlags |= TDF_USE_HICON_MAIN
-                self.config.hMainIcon = processed_icon
-
-        # --- 自定义按钮设置 ---
-        self.custom_buttons_list = []
-        if custom_buttons:
-            self.config.cButtons = len(custom_buttons)
-            button_array_type = TASKDIALOG_BUTTON * len(custom_buttons)
-            self.custom_buttons_list = button_array_type()
-            for i, (btn_id, btn_text) in enumerate(custom_buttons):
-                self.custom_buttons_list[i].nButtonID = btn_id
-                self.custom_buttons_list[i].pszButtonText = btn_text
-            self.config.pButtons = self.custom_buttons_list
-
-        if default_button:
-            self.config.nDefaultButton = default_button
-
-        # --- 单选按钮设置 ---
-        self.radio_buttons_list = []
-        if radio_buttons:
-            self.config.cRadioButtons = len(radio_buttons)
-            radio_array_type = TASKDIALOG_BUTTON * len(radio_buttons)
-            self.radio_buttons_list = radio_array_type()
-            for i, (btn_id, btn_text) in enumerate(radio_buttons):
-                self.radio_buttons_list[i].nButtonID = btn_id
-                self.radio_buttons_list[i].pszButtonText = btn_text
-            self.config.pRadioButtons = self.radio_buttons_list
-
-        if default_radio_button:
-            self.config.nDefaultRadioButton = default_radio_button
-
-        # --- 验证复选框设置 ---
-        if verification_text:
-            self.config.pszVerificationText = verification_text
-            if verification_checked_by_default:
-                self.config.dwFlags |= TDF_VERIFICATION_FLAG_CHECKED
-
-    def _process_common_buttons(self, common_buttons: int | List[CommonButtonLiteral]) -> int:
-        """处理 common_buttons 参数，支持常量和字符串列表两种形式"""
-        if isinstance(common_buttons, int):
-            # 直接使用 Win32 常量
-            return common_buttons
-        elif isinstance(common_buttons, list):
-            # 处理字符串列表
-            result = 0
-            for button in common_buttons:
-                # 使用 match 和 assert_never 进行类型检查
-                match button:
-                    case "ok":
-                        result |= TDCBF_OK_BUTTON
-                    case "yes":
-                        result |= TDCBF_YES_BUTTON
-                    case "no":
-                        result |= TDCBF_NO_BUTTON
-                    case "cancel":
-                        result |= TDCBF_CANCEL_BUTTON
-                    case "retry":
-                        result |= TDCBF_RETRY_BUTTON
-                    case "close":
-                        result |= TDCBF_CLOSE_BUTTON
-                    case _:
-                        # 这在实际中不会发生，因为类型检查会阻止它
-                        from typing import assert_never
-                        assert_never(button)
-            return result
-        else:
-            raise TypeError("common_buttons must be either an int or a list of strings")
-
-    def _process_main_icon(self, main_icon: Optional[wintypes.LPWSTR | int | IconLiteral]) -> Optional[wintypes.LPWSTR | int]:
-        """处理 main_icon 参数，支持常量和字符串两种形式"""
-        if main_icon is None:
-            return None
-        elif isinstance(main_icon, (wintypes.LPWSTR, int)):
-            # 直接使用 Win32 常量或 HICON 句柄
-            return main_icon
-        elif isinstance(main_icon, str):
-            # 处理字符串
-            match main_icon:
-                case "warning":
-                    return TD_WARNING_ICON
-                case "error":
-                    return TD_ERROR_ICON
-                case "information":
-                    return TD_INFORMATION_ICON
-                case "shield":
-                    return TD_SHIELD_ICON
-                case _:
-                    # 这在实际中不会发生，因为类型检查会阻止它
-                    from typing import assert_never
-                    assert_never(main_icon)
-        else:
-            raise TypeError("main_icon must be None, a Windows constant, or a string")
-
-    def _callback(self, hwnd: wintypes.HWND, msg: int, wParam: int, lParam: int, lpRefData: int) -> int:
-        # 仅当 lpRefData 指向的是当前这个对象实例时才处理
-        if lpRefData != id(self):
-            return 0  # S_OK
-
-        if msg == TDN_TIMER:
-            # 更新进度条
-            if self.progress < 100:
-                self.progress += 5
-                # 发送消息给对话框来更新进度条位置
-                user32.SendMessageW(hwnd, TDM_SET_PROGRESS_BAR_POS, self.progress, 0)
-            else:
-                # 示例：进度达到100%后，可以模拟点击OK按钮关闭对话框
-                # from ctypes import wintypes
-                # user32.PostMessageW(hwnd, wintypes.UINT(1125), IDOK, 0) # TDM_CLICK_BUTTON
-                pass
-
-        elif msg == TDN_DESTROYED:
-            # 对话框已销毁
-            pass
-
-        return 0  # S_OK
-
-    def show(self) -> Tuple[int, int, bool]:
-        """
-        显示对话框并返回用户交互的结果。
-
-        :return: 一个元组 (button_id, radio_button_id, verification_checked)
-                 - button_id: 用户点击的按钮ID (例如 IDOK, IDCANCEL)。
-                 - radio_button_id: 用户选择的单选按钮的ID。
-                 - verification_checked: 验证复选框是否被勾选 (True/False)。
-        """
-        pnButton = ctypes.c_int(0)
-        pnRadioButton = ctypes.c_int(0)
-        pfVerificationFlagChecked = wintypes.BOOL(False)
-
-        hr = TaskDialogIndirect(
-            ctypes.byref(self.config),
-            ctypes.byref(pnButton),
-            ctypes.byref(pnRadioButton),
-            ctypes.byref(pfVerificationFlagChecked)
-        )
-
-        if hr == 0:  # S_OK
-            return pnButton.value, pnRadioButton.value, bool(pfVerificationFlagChecked.value)
-        else:
-            raise ctypes.WinError(hr)
-
-
-# --- 示例用法 ---
-if __name__ == '__main__':
-
-    print("--- 示例 1: 简单信息框 ---")
-    dlg_simple = TaskDialog(
-        title="操作成功",
-        main_instruction="您的操作已成功完成。",
-        content="文件已保存到您的文档目录。",
-        common_buttons=["ok"],
-        main_icon="information"
-    )
-    result_simple, _, _ = dlg_simple.show()
-    print(f"用户点击了按钮: {result_simple} (1=OK)\n")
-
-    print("--- 示例 2: 确认框 ---")
-    dlg_confirm = TaskDialog(
-        title="确认删除",
-        main_instruction="您确定要永久删除这个文件吗?",
-        content="这个操作无法撤销。文件将被立即删除。",
-        common_buttons=["yes", "no", "cancel"],
-        main_icon="warning",
-        default_button=IDNO
-    )
-    result_confirm, _, _ = dlg_confirm.show()
-    if result_confirm == IDYES:
-        print("用户选择了“是”。")
-    elif result_confirm == IDNO:
-        print("用户选择了“否”。")
-    elif result_confirm == IDCANCEL:
-        print("用户选择了“取消”。")
-    print(f"返回的按钮ID: {result_confirm}\n")
-
-    # 示例 3
-    print("--- 示例 3: 自定义按钮 ---")
-    CUSTOM_BUTTON_SAVE_ID = 101
-    CUSTOM_BUTTON_DONT_SAVE_ID = 102
-    my_buttons = [
-        (CUSTOM_BUTTON_SAVE_ID, "保存并退出"),
-        (CUSTOM_BUTTON_DONT_SAVE_ID, "不保存直接退出")
-    ]
-    dlg_custom = TaskDialog(
-        title="未保存的更改",
-        main_instruction="文档中有未保存的更改，您想如何处理？",
-        custom_buttons=my_buttons,
-        common_buttons=["cancel"],
-        main_icon="warning",
-        footer="这是一个重要的提醒！"
-    )
-    result_custom, _, _ = dlg_custom.show()
-    if result_custom == CUSTOM_BUTTON_SAVE_ID:
-        print("用户选择了“保存并退出”。")
-    elif result_custom == CUSTOM_BUTTON_DONT_SAVE_ID:
-        print("用户选择了“不保存直接退出”。")
-    elif result_custom == IDCANCEL:
-        print("用户选择了“取消”。")
-    print(f"返回的按钮ID: {result_custom}\n")
-
-    # 示例 4: 带单选按钮和验证框的对话框
-    print("--- 示例 4: 单选按钮和验证框 ---")
-    RADIO_BTN_WORD_ID = 201
-    RADIO_BTN_EXCEL_ID = 202
-    RADIO_BTN_PDF_ID = 203
-
-    radio_buttons = [
-        (RADIO_BTN_WORD_ID, "保存为 Word 文档 (.docx)"),
-        (RADIO_BTN_EXCEL_ID, "保存为 Excel 表格 (.xlsx)"),
-        (RADIO_BTN_PDF_ID, "导出为 PDF 文档 (.pdf)")
-    ]
-
-    dlg_radio = TaskDialog(
-        title="选择导出格式",
-        main_instruction="请选择您想要导出的文件格式。",
-        content="选择一个格式后，点击“确定”继续。",
-        common_buttons=["ok", "cancel"],
-        main_icon="information",
-        radio_buttons=radio_buttons,
-        default_radio_button=RADIO_BTN_PDF_ID,  # 默认选中PDF
-        verification_text="设为我的默认导出选项",
-        verification_checked_by_default=True
-    )
-    btn_id, radio_id, checked = dlg_radio.show()
-
-    if btn_id == IDOK:
-        print(f"用户点击了“确定”。")
-        if radio_id == RADIO_BTN_WORD_ID:
-            print("选择了导出为 Word。")
-        elif radio_id == RADIO_BTN_EXCEL_ID:
-            print("选择了导出为 Excel。")
-        elif radio_id == RADIO_BTN_PDF_ID:
-            print("选择了导出为 PDF。")
-
-        if checked:
-            print("用户勾选了“设为我的默认导出选项”。")
-        else:
-            print("用户未勾选“设为我的默认导出选项”。")
-    else:
-        print("用户点击了“取消”。")
-    print(f"返回的按钮ID: {btn_id}, 单选按钮ID: {radio_id}, 验证框状态: {checked}\n")
+"""
+Windows Task Dialog interop module.
+
+This module provides Windows TaskDialog functionality and is only available on Windows systems.
+"""
+
+import platform
+import warnings
+
+from kotonebot.util import is_windows
+
+# 检查是否在 Windows 平台上
+if not is_windows():
+    _WINDOWS_ONLY_MSG = (
+        f"TaskDialog is only available on Windows systems. "
+        f"Current system: non-Windows\n"
+        "To use Windows TaskDialog features, please run this code on a Windows system."
+    )
+
+    
+    # 提供虚拟类以避免导入错误
+    class TaskDialog:
+        def __init__(self, *args, **kwargs):
+            raise ImportError(_WINDOWS_ONLY_MSG)
+    
+    # 导出所有常量作为 None
+    __all__ = [
+        "TaskDialog",
+        "TDCBF_OK_BUTTON", "TDCBF_YES_BUTTON", "TDCBF_NO_BUTTON", "TDCBF_CANCEL_BUTTON",
+        "TDCBF_RETRY_BUTTON", "TDCBF_CLOSE_BUTTON",
+        "IDOK", "IDCANCEL", "IDABORT", "IDRETRY", "IDIGNORE", "IDYES", "IDNO", "IDCLOSE",
+        "TD_WARNING_ICON", "TD_ERROR_ICON", "TD_INFORMATION_ICON", "TD_SHIELD_ICON"
+    ]
+    
+    # 设置所有常量为 None 或保留为模块级变量
+    TDCBF_OK_BUTTON = TDCBF_YES_BUTTON = TDCBF_NO_BUTTON = TDCBF_CANCEL_BUTTON = None
+    TDCBF_RETRY_BUTTON = TDCBF_CLOSE_BUTTON = None
+    IDOK = IDCANCEL = IDABORT = IDRETRY = IDIGNORE = IDYES = IDNO = IDCLOSE = None
+    TD_WARNING_ICON = TD_ERROR_ICON = TD_INFORMATION_ICON = TD_SHIELD_ICON = None
+    
+    # 阻止模块加载
+    raise ImportError(_WINDOWS_ONLY_MSG)
+
+# 如果是 Windows，继续正常加载
+import ctypes
+from ctypes import wintypes
+import time
+from typing import List, Tuple, Optional
+from typing import Literal
+
+__all__ = [
+    "TaskDialog",
+    "TDCBF_OK_BUTTON", "TDCBF_YES_BUTTON", "TDCBF_NO_BUTTON", "TDCBF_CANCEL_BUTTON",
+    "TDCBF_RETRY_BUTTON", "TDCBF_CLOSE_BUTTON",
+    "IDOK", "IDCANCEL", "IDABORT", "IDRETRY", "IDIGNORE", "IDYES", "IDNO", "IDCLOSE",
+    "TD_WARNING_ICON", "TD_ERROR_ICON", "TD_INFORMATION_ICON", "TD_SHIELD_ICON"
+]
+
+# --- Windows API 常量定义 ---
+
+# 常用按钮
+TDCBF_OK_BUTTON = 0x0001
+TDCBF_YES_BUTTON = 0x0002
+TDCBF_NO_BUTTON = 0x0004
+TDCBF_CANCEL_BUTTON = 0x0008
+TDCBF_RETRY_BUTTON = 0x0010
+TDCBF_CLOSE_BUTTON = 0x0020
+
+# 对话框返回值
+IDOK = 1
+IDCANCEL = 2
+IDABORT = 3
+IDRETRY = 4
+IDIGNORE = 5
+IDYES = 6
+IDNO = 7
+IDCLOSE = 8
+
+
+# 标准图标 (使用 MAKEINTRESOURCE 宏)
+def MAKEINTRESOURCE(i: int) -> wintypes.LPWSTR:
+    return wintypes.LPWSTR(i)
+
+
+TD_WARNING_ICON = MAKEINTRESOURCE(65535)
+TD_ERROR_ICON = MAKEINTRESOURCE(65534)
+TD_INFORMATION_ICON = MAKEINTRESOURCE(65533)
+TD_SHIELD_ICON = MAKEINTRESOURCE(65532)
+
+# Task Dialog 标志
+TDF_ENABLE_HYPERLINKS = 0x0001
+TDF_USE_HICON_MAIN = 0x0002
+TDF_USE_HICON_FOOTER = 0x0004
+TDF_ALLOW_DIALOG_CANCELLATION = 0x0008
+TDF_USE_COMMAND_LINKS = 0x0010
+TDF_USE_COMMAND_LINKS_NO_ICON = 0x0020
+TDF_EXPAND_FOOTER_AREA = 0x0040
+TDF_EXPANDED_BY_DEFAULT = 0x0080
+TDF_VERIFICATION_FLAG_CHECKED = 0x0100
+TDF_SHOW_PROGRESS_BAR = 0x0200
+TDF_SHOW_MARQUEE_PROGRESS_BAR = 0x0400
+TDF_CALLBACK_TIMER = 0x0800
+TDF_POSITION_RELATIVE_TO_WINDOW = 0x1000
+TDF_RTL_LAYOUT = 0x2000
+TDF_NO_DEFAULT_RADIO_BUTTON = 0x4000
+TDF_CAN_BE_MINIMIZED = 0x8000
+
+# Task Dialog 通知
+TDN_CREATED = 0
+TDN_NAVIGATED = 1
+TDN_BUTTON_CLICKED = 2
+TDN_HYPERLINK_CLICKED = 3
+TDN_TIMER = 4
+TDN_DESTROYED = 5
+TDN_RADIO_BUTTON_CLICKED = 6
+TDN_DIALOG_CONSTRUCTED = 7
+TDN_VERIFICATION_CLICKED = 8
+TDN_HELP = 9
+TDN_EXPANDO_BUTTON_CLICKED = 10
+
+# Windows 消息
+WM_USER = 0x0400
+TDM_SET_PROGRESS_BAR_POS = WM_USER + 114
+
+CommonButtonLiteral = Literal["ok", "yes", "no", "cancel", "retry", "close"]
+IconLiteral = Literal["warning", "error", "information", "shield"]
+
+
+# --- C 结构体定义 (使用 ctypes) ---
+
+class TASKDIALOG_BUTTON(ctypes.Structure):
+    _pack_ = 1
+    _fields_ = [("nButtonID", ctypes.c_int),
+                ("pszButtonText", wintypes.LPCWSTR)]
+
+
+# 定义回调函数指针原型
+PFTASKDIALOGCALLBACK = ctypes.WINFUNCTYPE(
+    ctypes.HRESULT,  # 返回值
+    wintypes.HWND,  # hwnd
+    ctypes.c_uint,  # msg
+    ctypes.c_size_t,  # wParam
+    ctypes.c_size_t,  # lParam
+    ctypes.c_ssize_t  # lpRefData
+)
+
+
+class TASKDIALOGCONFIG(ctypes.Structure):
+    _pack_ = 1
+    _fields_ = [
+        ("cbSize", ctypes.c_uint),
+        ("hwndParent", wintypes.HWND),
+        ("hInstance", wintypes.HINSTANCE),
+        ("dwFlags", ctypes.c_uint),
+        ("dwCommonButtons", ctypes.c_uint),
+        ("pszWindowTitle", wintypes.LPCWSTR),
+        ("pszMainIcon", wintypes.LPCWSTR),
+        ("pszMainInstruction", wintypes.LPCWSTR),
+        ("pszContent", wintypes.LPCWSTR),
+        ("cButtons", ctypes.c_uint),
+        ("pButtons", ctypes.POINTER(TASKDIALOG_BUTTON)),
+        ("nDefaultButton", ctypes.c_int),
+        ("cRadioButtons", ctypes.c_uint),
+        ("pRadioButtons", ctypes.POINTER(TASKDIALOG_BUTTON)),
+        ("nDefaultRadioButton", ctypes.c_int),
+        ("pszVerificationText", wintypes.LPCWSTR),
+        ("pszExpandedInformation", wintypes.LPCWSTR),
+        ("pszExpandedControlText", wintypes.LPCWSTR),
+        ("pszCollapsedControlText", wintypes.LPCWSTR),
+        ("pszFooterIcon", wintypes.LPCWSTR),
+        ("pszFooter", wintypes.LPCWSTR),
+        ("pfCallback", PFTASKDIALOGCALLBACK),  # 使用定义好的原型
+        ("lpCallbackData", ctypes.c_ssize_t),
+        ("cxWidth", ctypes.c_uint)
+    ]
+
+
+# --- 加载 comctl32.dll 并定义函数原型 ---
+
+comctl32 = ctypes.WinDLL('comctl32')
+user32 = ctypes.WinDLL('user32')
+
+TaskDialogIndirect = comctl32.TaskDialogIndirect
+TaskDialogIndirect.restype = ctypes.HRESULT
+TaskDialogIndirect.argtypes = [
+    ctypes.POINTER(TASKDIALOGCONFIG),
+    ctypes.POINTER(ctypes.c_int),
+    ctypes.POINTER(ctypes.c_int),
+    ctypes.POINTER(wintypes.BOOL)
+]
+
+
+# --- Python 封装类 ---
+
+class TaskDialog:
+    """
+    一个用于显示 Windows TaskDialog 的 Python 封装类。
+    支持自定义按钮、单选按钮、进度条、验证框等。
+    """
+
+    def __init__(self,
+        parent_hwnd: Optional[int] = None,
+        title: str = "Task Dialog",
+        main_instruction: str = "",
+        content: str = "",
+        common_buttons: int | List[CommonButtonLiteral] = TDCBF_OK_BUTTON,
+        main_icon: Optional[wintypes.LPWSTR | int | IconLiteral] = None,
+        footer: str = "",
+        custom_buttons: Optional[List[Tuple[int, str]]] = None,
+        default_button: int = 0,
+        radio_buttons: Optional[List[Tuple[int, str]]] = None,
+        default_radio_button: int = 0,
+        verification_text: Optional[str] = None,
+        verification_checked_by_default: bool = False,
+        show_progress_bar: bool = False,
+        show_marquee_progress_bar: bool = False
+    ):
+        """初始化 TaskDialog 实例。
+
+        :param parent_hwnd: 父窗口的句柄。
+        :param title: 对话框窗口的标题。
+        :param main_instruction: 对话框的主要指令文本。
+        :param content: 对话框的详细内容文本。
+        :param common_buttons: 要显示的通用按钮。可以是以下两种形式之一：
+                               1. TDCBF_* 常量的按位或组合 (例如 TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON)
+                               2. 字符串列表，支持 "ok", "yes", "no", "cancel", "retry", "close"
+        :param main_icon: 主图标。可以是以下几种形式之一：
+                          1. TD_*_ICON 常量之一
+                          2. HICON 句柄
+                          3. 字符串："warning", "error", "information", "shield"
+        :param footer: 页脚区域显示的文本。
+        :param custom_buttons: 自定义按钮列表。每个元组包含 (按钮ID, 按钮文本)。
+        :param default_button: 默认按钮的ID。可以是通用按钮ID (例如 IDOK) 或自定义按钮ID。
+        :param radio_buttons: 单选按钮列表。每个元组包含 (按钮ID, 按钮文本)。
+        :param default_radio_button: 默认选中的单选按钮的ID。
+        :param verification_text: 验证复选框的文本。如果为 None，则不显示复选框。
+        :param verification_checked_by_default: 验证复选框是否默认勾选。
+        :param show_progress_bar: 是否显示标准进度条。
+        :param show_marquee_progress_bar: 是否显示跑马灯式进度条。
+        """
+        self.config = TASKDIALOGCONFIG()
+        self.config.cbSize = ctypes.sizeof(TASKDIALOGCONFIG)
+        self.config.hwndParent = parent_hwnd
+        self.config.dwFlags = TDF_ALLOW_DIALOG_CANCELLATION | TDF_POSITION_RELATIVE_TO_WINDOW
+        self.config.dwCommonButtons = self._process_common_buttons(common_buttons)
+        self.config.pszWindowTitle = title
+        self.config.pszMainInstruction = main_instruction
+        self.config.pszContent = content
+        self.config.pszFooter = footer
+
+        self.progress: int = 0
+        if show_progress_bar or show_marquee_progress_bar:
+            # 进度条暂时还没实现
+            raise NotImplementedError("Progress bar is not implemented yet.")
+            self.config.dwFlags |= TDF_CALLBACK_TIMER
+            if show_progress_bar:
+                self.config.dwFlags |= TDF_SHOW_PROGRESS_BAR
+            else:
+                self.config.dwFlags |= TDF_SHOW_MARQUEE_PROGRESS_BAR
+
+        # 将实例方法转为 C 回调函数指针。
+        # 必须将其保存为实例成员，否则会被垃圾回收！
+        self._callback_func_ptr = PFTASKDIALOGCALLBACK(self._callback)
+        self.config.pfCallback = self._callback_func_ptr
+        # 将本实例的id作为lpCallbackData传递，以便在回调中识别
+        self.config.lpCallbackData = id(self)
+
+        # --- 图标设置 ---
+        processed_icon = self._process_main_icon(main_icon)
+        if processed_icon is not None:
+            if isinstance(processed_icon, wintypes.LPWSTR):
+                self.config.pszMainIcon = processed_icon
+            else:
+                self.config.dwFlags |= TDF_USE_HICON_MAIN
+                self.config.hMainIcon = processed_icon
+
+        # --- 自定义按钮设置 ---
+        self.custom_buttons_list = []
+        if custom_buttons:
+            self.config.cButtons = len(custom_buttons)
+            button_array_type = TASKDIALOG_BUTTON * len(custom_buttons)
+            self.custom_buttons_list = button_array_type()
+            for i, (btn_id, btn_text) in enumerate(custom_buttons):
+                self.custom_buttons_list[i].nButtonID = btn_id
+                self.custom_buttons_list[i].pszButtonText = btn_text
+            self.config.pButtons = self.custom_buttons_list
+
+        if default_button:
+            self.config.nDefaultButton = default_button
+
+        # --- 单选按钮设置 ---
+        self.radio_buttons_list = []
+        if radio_buttons:
+            self.config.cRadioButtons = len(radio_buttons)
+            radio_array_type = TASKDIALOG_BUTTON * len(radio_buttons)
+            self.radio_buttons_list = radio_array_type()
+            for i, (btn_id, btn_text) in enumerate(radio_buttons):
+                self.radio_buttons_list[i].nButtonID = btn_id
+                self.radio_buttons_list[i].pszButtonText = btn_text
+            self.config.pRadioButtons = self.radio_buttons_list
+
+        if default_radio_button:
+            self.config.nDefaultRadioButton = default_radio_button
+
+        # --- 验证复选框设置 ---
+        if verification_text:
+            self.config.pszVerificationText = verification_text
+            if verification_checked_by_default:
+                self.config.dwFlags |= TDF_VERIFICATION_FLAG_CHECKED
+
+    def _process_common_buttons(self, common_buttons: int | List[CommonButtonLiteral]) -> int:
+        """处理 common_buttons 参数，支持常量和字符串列表两种形式"""
+        if isinstance(common_buttons, int):
+            # 直接使用 Win32 常量
+            return common_buttons
+        elif isinstance(common_buttons, list):
+            # 处理字符串列表
+            result = 0
+            for button in common_buttons:
+                # 使用 match 和 assert_never 进行类型检查
+                match button:
+                    case "ok":
+                        result |= TDCBF_OK_BUTTON
+                    case "yes":
+                        result |= TDCBF_YES_BUTTON
+                    case "no":
+                        result |= TDCBF_NO_BUTTON
+                    case "cancel":
+                        result |= TDCBF_CANCEL_BUTTON
+                    case "retry":
+                        result |= TDCBF_RETRY_BUTTON
+                    case "close":
+                        result |= TDCBF_CLOSE_BUTTON
+                    case _:
+                        # 这在实际中不会发生，因为类型检查会阻止它
+                        from typing import assert_never
+                        assert_never(button)
+            return result
+        else:
+            raise TypeError("common_buttons must be either an int or a list of strings")
+
+    def _process_main_icon(self, main_icon: Optional[wintypes.LPWSTR | int | IconLiteral]) -> Optional[wintypes.LPWSTR | int]:
+        """处理 main_icon 参数，支持常量和字符串两种形式"""
+        if main_icon is None:
+            return None
+        elif isinstance(main_icon, (wintypes.LPWSTR, int)):
+            # 直接使用 Win32 常量或 HICON 句柄
+            return main_icon
+        elif isinstance(main_icon, str):
+            # 处理字符串
+            match main_icon:
+                case "warning":
+                    return TD_WARNING_ICON
+                case "error":
+                    return TD_ERROR_ICON
+                case "information":
+                    return TD_INFORMATION_ICON
+                case "shield":
+                    return TD_SHIELD_ICON
+                case _:
+                    # 这在实际中不会发生，因为类型检查会阻止它
+                    from typing import assert_never
+                    assert_never(main_icon)
+        else:
+            raise TypeError("main_icon must be None, a Windows constant, or a string")
+
+    def _callback(self, hwnd: wintypes.HWND, msg: int, wParam: int, lParam: int, lpRefData: int) -> int:
+        # 仅当 lpRefData 指向的是当前这个对象实例时才处理
+        if lpRefData != id(self):
+            return 0  # S_OK
+
+        if msg == TDN_TIMER:
+            # 更新进度条
+            if self.progress < 100:
+                self.progress += 5
+                # 发送消息给对话框来更新进度条位置
+                user32.SendMessageW(hwnd, TDM_SET_PROGRESS_BAR_POS, self.progress, 0)
+            else:
+                # 示例：进度达到100%后，可以模拟点击OK按钮关闭对话框
+                # from ctypes import wintypes
+                # user32.PostMessageW(hwnd, wintypes.UINT(1125), IDOK, 0) # TDM_CLICK_BUTTON
+                pass
+
+        elif msg == TDN_DESTROYED:
+            # 对话框已销毁
+            pass
+
+        return 0  # S_OK
+
+    def show(self) -> Tuple[int, int, bool]:
+        """
+        显示对话框并返回用户交互的结果。
+
+        :return: 一个元组 (button_id, radio_button_id, verification_checked)
+                 - button_id: 用户点击的按钮ID (例如 IDOK, IDCANCEL)。
+                 - radio_button_id: 用户选择的单选按钮的ID。
+                 - verification_checked: 验证复选框是否被勾选 (True/False)。
+        """
+        pnButton = ctypes.c_int(0)
+        pnRadioButton = ctypes.c_int(0)
+        pfVerificationFlagChecked = wintypes.BOOL(False)
+
+        hr = TaskDialogIndirect(
+            ctypes.byref(self.config),
+            ctypes.byref(pnButton),
+            ctypes.byref(pnRadioButton),
+            ctypes.byref(pfVerificationFlagChecked)
+        )
+
+        if hr == 0:  # S_OK
+            return pnButton.value, pnRadioButton.value, bool(pfVerificationFlagChecked.value)
+        else:
+            raise ctypes.WinError(hr)
+
+
+# --- 示例用法 ---
+if __name__ == '__main__':
+
+    print("--- 示例 1: 简单信息框 ---")
+    dlg_simple = TaskDialog(
+        title="操作成功",
+        main_instruction="您的操作已成功完成。",
+        content="文件已保存到您的文档目录。",
+        common_buttons=["ok"],
+        main_icon="information"
+    )
+    result_simple, _, _ = dlg_simple.show()
+    print(f"用户点击了按钮: {result_simple} (1=OK)\n")
+
+    print("--- 示例 2: 确认框 ---")
+    dlg_confirm = TaskDialog(
+        title="确认删除",
+        main_instruction="您确定要永久删除这个文件吗?",
+        content="这个操作无法撤销。文件将被立即删除。",
+        common_buttons=["yes", "no", "cancel"],
+        main_icon="warning",
+        default_button=IDNO
+    )
+    result_confirm, _, _ = dlg_confirm.show()
+    if result_confirm == IDYES:
+        print("用户选择了“是”。")
+    elif result_confirm == IDNO:
+        print("用户选择了“否”。")
+    elif result_confirm == IDCANCEL:
+        print("用户选择了“取消”。")
+    print(f"返回的按钮ID: {result_confirm}\n")
+
+    # 示例 3
+    print("--- 示例 3: 自定义按钮 ---")
+    CUSTOM_BUTTON_SAVE_ID = 101
+    CUSTOM_BUTTON_DONT_SAVE_ID = 102
+    my_buttons = [
+        (CUSTOM_BUTTON_SAVE_ID, "保存并退出"),
+        (CUSTOM_BUTTON_DONT_SAVE_ID, "不保存直接退出")
+    ]
+    dlg_custom = TaskDialog(
+        title="未保存的更改",
+        main_instruction="文档中有未保存的更改，您想如何处理？",
+        custom_buttons=my_buttons,
+        common_buttons=["cancel"],
+        main_icon="warning",
+        footer="这是一个重要的提醒！"
+    )
+    result_custom, _, _ = dlg_custom.show()
+    if result_custom == CUSTOM_BUTTON_SAVE_ID:
+        print("用户选择了“保存并退出”。")
+    elif result_custom == CUSTOM_BUTTON_DONT_SAVE_ID:
+        print("用户选择了“不保存直接退出”。")
+    elif result_custom == IDCANCEL:
+        print("用户选择了“取消”。")
+    print(f"返回的按钮ID: {result_custom}\n")
+
+    # 示例 4: 带单选按钮和验证框的对话框
+    print("--- 示例 4: 单选按钮和验证框 ---")
+    RADIO_BTN_WORD_ID = 201
+    RADIO_BTN_EXCEL_ID = 202
+    RADIO_BTN_PDF_ID = 203
+
+    radio_buttons = [
+        (RADIO_BTN_WORD_ID, "保存为 Word 文档 (.docx)"),
+        (RADIO_BTN_EXCEL_ID, "保存为 Excel 表格 (.xlsx)"),
+        (RADIO_BTN_PDF_ID, "导出为 PDF 文档 (.pdf)")
+    ]
+
+    dlg_radio = TaskDialog(
+        title="选择导出格式",
+        main_instruction="请选择您想要导出的文件格式。",
+        content="选择一个格式后，点击“确定”继续。",
+        common_buttons=["ok", "cancel"],
+        main_icon="information",
+        radio_buttons=radio_buttons,
+        default_radio_button=RADIO_BTN_PDF_ID,  # 默认选中PDF
+        verification_text="设为我的默认导出选项",
+        verification_checked_by_default=True
+    )
+    btn_id, radio_id, checked = dlg_radio.show()
+
+    if btn_id == IDOK:
+        print(f"用户点击了“确定”。")
+        if radio_id == RADIO_BTN_WORD_ID:
+            print("选择了导出为 Word。")
+        elif radio_id == RADIO_BTN_EXCEL_ID:
+            print("选择了导出为 Excel。")
+        elif radio_id == RADIO_BTN_PDF_ID:
+            print("选择了导出为 PDF。")
+
+        if checked:
+            print("用户勾选了“设为我的默认导出选项”。")
+        else:
+            print("用户未勾选“设为我的默认导出选项”。")
+    else:
+        print("用户点击了“取消”。")
+    print(f"返回的按钮ID: {btn_id}, 单选按钮ID: {radio_id}, 验证框状态: {checked}\n")