# desktop-alarm-clock

**Repository Path**: twsa/desktop-alarm-clock

## Basic Information

- **Project Name**: desktop-alarm-clock
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-03
- **Last Updated**: 2025-12-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 桌面下班提醒闹钟 🕐

一个简单易用的 Ubuntu 桌面闹钟应用，专门用于提醒下班时间。

## ✨ 功能特性

- ⏰ **固定时间提醒** - 设置每天的下班时间，准时提醒
- 📢 **多重提醒方式** - 弹窗通知 + 系统通知 + 声音提醒
- 🖥️ **图形界面** - 简洁直观的 GTK3 界面
- 🔊 **音量控制** - 可调节的提醒音量
- 🔄 **延迟提醒** - 支持 5 分钟延迟提醒
- 📍 **系统托盘** - 后台运行，最小化到托盘
- 🚀 **开机自启** - 支持开机自动启动
- 💾 **设置保存** - 自动保存用户偏好设置

## 📸 界面预览

应用主界面包含：
- 🕐 实时时钟显示
- ⚙️ 闹钟时间设置（小时/分钟选择器）
- 🎚️ 音量控制滑块
- 🔘 启用/禁用开关
- 💾 保存设置按钮
- 🧪 测试提醒按钮

## 🚀 快速开始

### 系统要求

- **操作系统**: Ubuntu 18.04+ (推荐 20.04/22.04/24.04)
- **桌面环境**: GNOME, XFCE, KDE (支持 libnotify 的桌面)
- **Python**: Python 3.8+
- **依赖包**: python3-gi, python3-gi-cairo, libnotify-bin, pulseaudio-utils

### 安装依赖

```bash
sudo apt update
sudo apt install python3-gi python3-gi-cairo libnotify-bin pulseaudio-utils
```

### 安装应用

1. 克隆或下载项目：
```bash
cd ~/Downloads
git clone <repository-url> desktop-alarm-clock
cd desktop-alarm-clock
```

2. 运行安装脚本：
```bash
./install.sh
```

3. 安装完成后，你可以在应用程序菜单中找到"下班提醒闹钟"

### 快速启动

- 从应用程序菜单搜索"下班提醒闹钟"
- 或在终端中运行：`desktop-alarm-clock`

## 🎛️ 使用说明

### 基本设置

1. **启动应用** - 运行应用后主窗口会显示当前时间
2. **设置闹钟时间** - 使用小时和分钟选择器设置你的下班时间
3. **调节音量** - 拖动音量滑块到合适的大小
4. **启用闹钟** - 确保启用开关处于打开状态
5. **保存设置** - 点击"保存设置"按钮

### 测试功能

- 点击"测试提醒"按钮可以立即测试提醒功能
- 测试将显示通知并播放声音

### 系统托盘

- 关闭主窗口后，应用会在系统托盘中继续运行
- 右键托盘图标可以重新显示主窗口或退出应用

### 延迟提醒

- 当闹钟触发时，对话框会提供"延迟5分钟"选项
- 点击后会在 5 分钟后再次提醒

## 🛠️ 高级配置

### 配置文件位置

用户配置存储在：`~/.config/desktop-alarm-clock/alarm_config.json`

配置文件内容示例：
```json
{
  "alarm_time": "18:00",
  "enabled": true,
  "volume": 50,
  "auto_start": false,
  "show_notifications": true,
  "sound_enabled": true,
  "theme": "system"
}
```

### 开机自启动

安装时可以选择是否设置开机自启动，也可以手动设置：

```bash
mkdir -p ~/.config/autostart
cp ~/.local/share/applications/desktop-alarm-clock.desktop ~/.config/autostart/
```

## 🧪 测试应用

项目包含完整的测试脚本：

```bash
python3 test_app.py
```

测试内容包括：
- 模块导入测试
- 配置管理器测试
- 通知系统测试
- 音效播放测试
- 完整应用启动测试

## 🗑️ 卸载应用

### 使用卸载脚本

```bash
~/.local/share/desktop-alarm-clock/uninstall.sh
```

### 手动卸载

如果卸载脚本丢失，可以手动删除以下文件：

```bash
# 应用文件
rm -rf ~/.local/share/desktop-alarm-clock

# 启动脚本
rm -f ~/.local/bin/desktop-alarm-clock

# 桌面文件
rm -f ~/.local/share/applications/desktop-alarm-clock.desktop

# 自启动文件
rm -f ~/.config/autostart/desktop-alarm-clock.desktop

# 配置文件
rm -rf ~/.config/desktop-alarm-clock

# 图标文件
rm -f ~/.local/share/icons/hicolor/256x256/apps/desktop-alarm-clock.png
```

## 🐛 故障排除

### 常见问题

1. **通知不显示**
   - 检查是否安装了 `libnotify-bin`
   - 确保桌面环境支持系统通知
   - 检查系统设置是否允许应用发送通知

2. **声音不播放**
   - 检查是否安装了 `pulseaudio-utils`
   - 确保系统音频正常工作
   - 检查音量设置是否静音

3. **应用无法启动**
   - 检查 Python GTK 绑定是否安装
   - 运行测试脚本检查依赖
   - 查看终端错误信息

4. **托盘图标不显示**
   - 某些桌面环境可能不支持应用指示器
   - 应用仍会正常工作，只是没有托盘图标

### 调试模式

设置调试环境变量：
```bash
export DESKTOP_ALARM_CLOCK_DEBUG=1
desktop-alarm-clock
```

### 日志查看

应用日志会输出到终端，包含：
- 启动信息
- 闹钟触发记录
- 错误信息

## 🔄 开发说明

### 项目结构

```
desktop-alarm-clock/
├── main.py              # 主应用入口
├── alarm_app.py         # 主应用类
├── alarm_manager.py     # 闹钟管理逻辑
├── notification_manager.py  # 通知管理
├── preferences_manager.py   # 配置管理
├── sounds/
│   └── alarm_sound.wav      # 提醒音效
├── resources/
│   └── desktop-alarm-clock.desktop  # 桌面入口
├── install.sh           # 安装脚本
├── uninstall.sh         # 卸载脚本
├── test_app.py          # 测试脚本
├── create_sound.py      # 音效生成
└── README.md           # 说明文档
```

### 依赖技术

- **Python 3** - 主要编程语言
- **GTK3** - 图形界面框架
- **libnotify** - 系统通知
- **PulseAudio** - 音频播放
- **systemd** - 用户服务管理

### 自定义音效

将自定义音效文件放在 `sounds/alarm_sound.wav`，支持：
- WAV 格式
- 立体声
- 44.1kHz 采样率

## 📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 发起 Pull Request

## 📞 支持

如果你遇到问题或有建议：

1. 查看故障排除部分
2. 运行测试脚本检查系统
3. 提交 GitHub Issue
4. 检查是否为已知问题

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者和用户！

---

**享受准时的下班提醒！** 🎉