中文 | English

tk-倒數計時器

目錄

• 專案概述
• 重點特色
• 使用說明
• 開發須知
• 使用技術
• 專案結構
• 備註

---

專案概述

一款以 CustomTkinter 打造的 Windows 桌面倒數計時器，支援時/分/秒自由設定、暫停續計、時間到時自動播放音效並發送系統通知。

---

重點特色

• 彈性時間輸入：時/分/秒各欄位支援手動輸入與上下鍵調整，輸入超過進位值（如 90 秒）會自動進位
• 即時結束時間預測：倒數期間持續顯示預計結束時刻，暫停後恢復時同步更新
• 暫停 / 繼續：暫停後可選擇繼續計時或返回設定畫面重新設定
• 音效提醒：時間到時循環播放自備音效，直到手動停止
• 系統通知：可選擇是否在時間到時發送 Windows 系統右下角通知

---

使用說明

請至 Release 下載最新版本並解壓縮。

• 啟動：

  • 直接執行執行檔： 執行 .exe 檔案，如 tk-Timer_vX.X.X.exe
  • 由程式碼啟動：

    python main.py
    

• 功能介紹：

1. 設定計時（New Timer）： 調整時、分、秒後按下 Start Timer。各欄位支援直接輸入數字，超過範圍上限會自動進位（例如輸入 90 秒 → 自動轉為 1 分 30 秒）。可勾選 Notify me when the timer ends 以啟用時間到的系統通知。

2. 倒數計時（Time Remaining）： 畫面即時顯示剩餘時間與預計結束時刻。按下 Pause 暫停計時，暫停後會出現 Back 按鈕可返回設定畫面；按下 Resume 繼續倒數，結束時間同步更新。

3. 時間到（Time's Up!）： 自動播放音效並循環直到手動停止。按 New Timer 停止音效並回到設定畫面；按 Stop & Exit 停止音效並關閉程式。

---

開發須知

1. 請先閱讀以下開發須知並遵守所用條款。
2. 請運行以下指令複製此倉庫至您的本地電腦：

   git clone https://github.com/294Ryan/tk-Timer.git
   

3. 使用語言：
   • Python 3.x
4. 安裝必要工具：
   • Python 模組：請運行以下指令

     pip install -r requirements.txt
     

5. 音效檔案：將自備的 alarm.wav 放入專案根目錄下的 alarm/ 資料夾，路徑需為 alarm/alarm.wav
6. 使用技術：請參見 使用技術
7. 專案結構：請參見 專案結構

---

使用技術

• CustomTkinter：現代化 Tkinter GUI 框架，支援 Light / Dark / System 三種主題，可於 main.py 頂部的 set_appearance_mode() 調整
• Frame 堆疊切換：三個 CTkFrame 以 place() 疊放於同一位置，透過 tkraise() 切換畫面，避免重建 UI 的額外開銷
• root.after() 計時迴圈：倒數邏輯以遞迴 after(1000, ...) 實作，不阻塞主執行緒
• pygame.mixer：跨平台音效播放，loops=-1 實現循環播放直到手動停止
• plyer：跨平台系統通知介面，於 Windows 發送右下角 Toast 通知
• 自動進位邏輯：TimeSpinner 元件在輸入確認時以 divmod 計算進位，並透過 carryTo 鏈式傳遞到上層欄位

---

專案結構

tkinter-Timer/
├── alarm/
│   └── alarm.wav          # 時間到時循環播放的音效檔
├── .gitignore
├── icon.ico               # 程式圖示
├── LICENSE
├── main.py                # 主程式
├── main.spec              # PyInstaller 打包設定
├── README.md
└── requirements.txt       # Python 套件依賴清單

---

備註

• 維護者：294Ryan - GitHub
• 使用條款：MIT
• <!> 敬請在本專案所用條款之允許範圍內進行使用。且任何因操作疏失或不當使用造成的後果請自負。

---

tk-Timer

Table of Contents

• Project Overview
• Key Features
• Instructions for Use
• Development Guidelines
• Technologies Used
• Project Structure
• Notes

---

Project Overview

A Windows desktop countdown timer built with CustomTkinter. Supports flexible time input, pause/resume, looping alarm playback, and optional system notifications when the timer ends.

---

Key Features

• Flexible time input: Each field (hours/minutes/seconds) supports both manual input and arrow-key adjustment, with automatic carry-over when values exceed their limit (e.g. entering 90 seconds auto-converts to 1 min 30 sec)
• Live end-time display: The projected end time is shown throughout the countdown and recalculated whenever the timer is resumed after a pause
• Pause / Resume: Pause mid-countdown and choose to resume or go back to the setup screen
• Alarm sound: Loops the alarm audio on completion until manually stopped
• System notification: Optionally sends a Windows toast notification when the timer ends

---

Instructions for Use

Download the latest release from Release and extract the contents.

• Launch:

  • Execute the executable file directly: Run the .exe file, e.g. tk-Timer_vX.X.X.exe
  • Launch from source:

    python main.py
    

• Feature Introduction:

1. Set a Timer (New Timer): Adjust hours, minutes, and seconds, then press Start Timer. Each field accepts direct input — values exceeding the field's limit are automatically carried over (e.g. entering 90 seconds converts to 1 min 30 sec). Check Notify me when the timer ends to enable a system notification on completion.

2. Countdown (Time Remaining): Displays the remaining time and projected end time in real time. Press Pause to pause — a Back button will appear to return to the setup screen. Press Resume to continue; the end time updates accordingly.

3. Timer Complete (Time's Up!): The alarm plays on a loop until stopped manually. Press New Timer to stop the alarm and return to setup; press Stop & Exit to stop the alarm and close the app.

---

Development Guidelines

1. Please read the following guidelines and comply with all applicable terms.
2. Clone this repository to your local machine:

   git clone https://github.com/294Ryan/tk-Timer.git
   

3. Programming Languages:
   • Python 3.x
4. Required Tool Installation:
   • Python Modules:

     pip install -r requirements.txt
     

5. Alarm audio: Place your own alarm.wav inside the alarm/ folder at the project root. The expected path is alarm/alarm.wav.
6. Technologies Used: Please refer to Technologies Used
7. Project Structure: Please refer to Project Structure

---

Technologies Used

• CustomTkinter: Modern Tkinter GUI framework, supports Light / Dark / System themes — configurable via set_appearance_mode() at the top of main.py
• Frame stack switching: Three CTkFrame instances are stacked at the same position via place() and switched using tkraise(), avoiding unnecessary UI rebuilds
• root.after() countdown loop: The countdown logic runs via recursive after(1000, ...) calls, keeping the main thread unblocked
• pygame.mixer: Cross-platform audio playback; loops=-1 enables indefinite looping until manually stopped
• plyer: Cross-platform notification interface; sends a Windows toast notification on timer completion
• Auto carry-over logic: The TimeSpinner widget uses divmod on commit to calculate overflow and propagates carry values up the chain via the carryTo reference

---

Project Structure

tkinter-Timer/
├── alarm/
│   └── alarm.wav          # Alarm audio file played on completion
├── .gitignore
├── icon.ico               # Application icon
├── LICENSE
├── main.py                # Main application entry point
├── main.spec              # PyInstaller packaging configuration
├── README.md
└── requirements.txt       # Python package dependencies

---

Notes

• Maintainer: 294Ryan - GitHub
• Terms of Use: MIT
• <!> Please use this project only within the scope permitted by its license. You are solely responsible for any consequences arising from operational errors or improper use.