468 lines
19 KiB
Markdown
468 lines
19 KiB
Markdown
# TheChart User Guide
|
||
|
||
> 📖 **Consolidated Documentation**: This document combines multiple documentation files for better organization and easier navigation.
|
||
|
||
## Table of Contents
|
||
- [Overview](#overview)
|
||
|
||
## Overview
|
||
|
||
Complete user manual with features, shortcuts, and usage
|
||
|
||
|
||
### Overview
|
||
TheChart is a comprehensive medication tracking application with a modern, professional UI that allows users to monitor medication intake, track symptoms, and visualize treatment progress over time.
|
||
|
||
### 🎨 Modern UI/UX System (New in v1.9.5)
|
||
|
||
#### Professional Theme Engine
|
||
TheChart features a sophisticated theme system powered by ttkthemes, offering 8 carefully curated professional themes.
|
||
|
||
##### Available Themes:
|
||
- **Arc**: Modern flat design with subtle shadows
|
||
- **Equilux**: Dark theme with excellent contrast
|
||
- **Adapta**: Clean, minimalist design
|
||
- **Yaru**: Ubuntu-inspired modern interface
|
||
- **Ubuntu**: Official Ubuntu styling
|
||
- **Plastik**: Classic professional appearance
|
||
- **Breeze**: KDE-inspired clean design
|
||
- **Elegance**: Sophisticated dark theme
|
||
|
||
##### UI Enhancements:
|
||
- **Modern Styling**: Card-style frames, enhanced buttons, professional form controls
|
||
- **Smart Tooltips**: Context-sensitive help for all interactive elements
|
||
- **Improved Tables**: Better selection highlighting and alternating row colors
|
||
- **Settings System**: Comprehensive preferences with theme persistence
|
||
- **Responsive Design**: Automatic layout adjustments and scaling
|
||
- **Menu Theming**: Complete menu integration with theme colors and hover effects
|
||
|
||
#### ⌨️ Comprehensive Keyboard Shortcuts
|
||
Professional keyboard shortcut system for efficient navigation and operation.
|
||
|
||
##### File Operations:
|
||
- **Ctrl+S**: Save/Add new entry
|
||
- **Ctrl+Q**: Quit application (with confirmation)
|
||
- **Ctrl+E**: Export data
|
||
|
||
##### Data Management:
|
||
- **Ctrl+N**: Clear entries
|
||
- **Ctrl+R / F5**: Refresh data
|
||
- **Ctrl+F**: Toggle search/filter panel
|
||
- **Delete**: Delete selected entry
|
||
- **Escape**: Clear selection
|
||
|
||
##### Window Management:
|
||
- **Ctrl+M**: Manage medicines
|
||
- **Ctrl+P**: Manage pathologies
|
||
- **F1**: Show keyboard shortcuts help
|
||
- **F2**: Open settings window
|
||
|
||
### Core Features
|
||
|
||
#### 🏥 Modular Medicine System
|
||
TheChart features a dynamic medicine management system that allows complete customization without code modifications.
|
||
|
||
##### Features:
|
||
- **Dynamic Medicine Management**: Add, edit, and remove medicines through the UI
|
||
- **Configurable Properties**: Each medicine has customizable display names, dosages, colors, and quick-dose options
|
||
- **Automatic UI Updates**: All interface elements update automatically when medicines change
|
||
- **JSON Configuration**: Human-readable `medicines.json` file for easy management
|
||
|
||
##### Medicine Configuration:
|
||
Each medicine includes:
|
||
- **Key**: Internal identifier (e.g., "bupropion")
|
||
- **Display Name**: User-friendly name (e.g., "Bupropion")
|
||
- **Dosage Info**: Dosage information (e.g., "150/300 mg")
|
||
- **Quick Doses**: Common dose amounts for quick selection
|
||
- **Color**: Hex color for graph display (e.g., "#FF6B6B")
|
||
- **Default Enabled**: Whether to show in graphs by default
|
||
|
||
##### Default Medicines:
|
||
| Medicine | Dosage | Default Graph | Color |
|
||
|----------|--------|---------------|--------|
|
||
| Bupropion | 150/300 mg | ✅ | Red (#FF6B6B) |
|
||
| Hydroxyzine | 25 mg | ❌ | Teal (#4ECDC4) |
|
||
| Gabapentin | 100 mg | ❌ | Blue (#45B7D1) |
|
||
| Propranolol | 10 mg | ✅ | Green (#96CEB4) |
|
||
| Quetiapine | 25 mg | ❌ | Yellow (#FFEAA7) |
|
||
|
||
##### Usage:
|
||
1. **Through UI**: Go to `Tools` → `Manage Medicines...`
|
||
2. **Manual Configuration**: Edit `medicines.json` directly
|
||
3. **Programmatically**: Use the MedicineManager API
|
||
|
||
#### ⚙️ Settings and Theme Management
|
||
Advanced configuration system allowing users to customize their experience.
|
||
|
||
##### Settings Window (F2):
|
||
- **Theme Selection**: Choose from 8 professional themes with live preview
|
||
- **UI Preferences**: Font scaling, window behavior options
|
||
- **About Information**: Detailed application and version information
|
||
- **Tabbed Interface**: Organized settings categories for easy navigation
|
||
|
||
##### Theme Features:
|
||
- **Real-time Switching**: No restart required for theme changes
|
||
- **Persistence**: Selected theme remembered between sessions
|
||
- **Quick Access**: Theme menu for instant switching
|
||
- **Fallback Handling**: Graceful handling if themes fail to load
|
||
|
||
#### 💡 Smart Tooltip System
|
||
Context-sensitive help system providing guidance throughout the application.
|
||
|
||
##### Tooltip Types:
|
||
- **Pathology Scales**: Usage guidance for symptom tracking
|
||
- **Medicine Checkboxes**: Medication information and dosage details
|
||
- **Action Buttons**: Functionality description with keyboard shortcuts
|
||
- **Form Controls**: Input guidance and format requirements
|
||
|
||
##### Features:
|
||
- **Delayed Display**: Non-intrusive timing (500-800ms delay)
|
||
- **Theme-aware Styling**: Tooltips match selected theme
|
||
- **Smart Positioning**: Automatic placement to avoid screen edges
|
||
- **Rich Content**: Multi-line descriptions with formatting
|
||
|
||
#### 💊 Advanced Dose Tracking
|
||
Comprehensive dose tracking system that records exact timestamps and dosages throughout the day.
|
||
|
||
##### Core Capabilities:
|
||
- **Timestamp Recording**: Exact time when medicine is taken
|
||
- **Dose Amount Tracking**: Record specific doses (150mg, 10mg, etc.)
|
||
- **Multiple Doses Per Day**: Take the same medicine multiple times
|
||
- **Real-time Display**: See today's doses immediately
|
||
- **Data Persistence**: All doses saved to CSV with full history
|
||
|
||
##### Dose Management Interface:
|
||
Located in the edit window (double-click any entry):
|
||
- **Individual Dose Entry Fields**: For each medicine
|
||
- **"Take [Medicine]" Buttons**: Immediate dose recording with timestamps
|
||
- **Editable Dose Display Areas**: View and modify existing doses
|
||
- **Quick Dose Buttons**: Pre-configured common dose amounts
|
||
- **Format Consistency**: All doses displayed in HH:MM: dose format
|
||
|
||
##### Data Format:
|
||
- **Timestamp Format**: `YYYY-MM-DD HH:MM:SS`
|
||
- **Dose Separator**: `|` (pipe) for multiple doses
|
||
- **Dose Format**: `timestamp:dose`
|
||
- **CSV Storage**: Additional columns in existing CSV file
|
||
|
||
##### Example CSV Format:
|
||
```csv
|
||
date,depression,anxiety,sleep,appetite,bupropion,bupropion_doses,hydroxyzine,hydroxyzine_doses,propranolol,propranolol_doses,note
|
||
07/28/2025,4,5,3,3,1,"2025-07-28 14:30:00:150mg|2025-07-28 18:30:00:150mg",0,"",1,"2025-07-28 12:30:00:10mg","Multiple doses today"
|
||
```
|
||
|
||
#### 📊 Enhanced Graph Visualization
|
||
Advanced graphing system with comprehensive data visualization and interactive controls.
|
||
|
||
##### Medicine Dose Visualization:
|
||
- **Colored Bar Charts**: Each medicine has distinct colors
|
||
- **Daily Dose Totals**: Automatically calculated from individual doses
|
||
- **Scaled Display**: Doses scaled by 1/10 for better visibility (labeled as "mg/10")
|
||
- **Dynamic Positioning**: Bars positioned below main chart area
|
||
- **Semi-transparent Bars**: Alpha=0.6 to avoid overwhelming symptom data
|
||
|
||
##### Interactive Controls:
|
||
- **Toggle Buttons**: Independent show/hide for each medicine and symptom
|
||
- **Organized Sections**: "Symptoms" and "Medicines" sections
|
||
- **Real-time Updates**: Changes take effect immediately
|
||
|
||
##### Enhanced Legend:
|
||
- **Multi-column Layout**: Efficient use of graph space (2 columns)
|
||
- **Average Dosage Display**: Shows average dose for each medicine
|
||
- **Color Coding**: Consistent color scheme matching graph elements
|
||
- **Professional Styling**: Frame, shadow, and transparency effects
|
||
- **Tracking Status**: Shows medicines being monitored but without current dose data
|
||
|
||
##### Dose Calculation Features:
|
||
- **Multiple Format Support**: Handles various dose string formats
|
||
- **Robust Parsing**: Handles timestamps, symbols (•), and mixed formats
|
||
- **Edge Case Handling**: Manages empty strings, NaN values, malformed data
|
||
- **Daily Totals**: Sums all individual doses for comprehensive daily tracking
|
||
|
||
#### 🏥 Pathology Management
|
||
Comprehensive symptom tracking with configurable pathologies.
|
||
|
||
##### Features:
|
||
- **Dynamic Pathology System**: Similar to medicine management
|
||
- **Configurable Symptoms**: Add, edit, and remove symptom categories
|
||
- **Scale-based Rating**: 0-10 rating system for symptom severity
|
||
- **Historical Tracking**: Full symptom history with trend analysis
|
||
|
||
#### 📝 Data Management
|
||
Robust data handling with comprehensive backup and migration support.
|
||
|
||
##### Data Features:
|
||
- **CSV-based Storage**: Human-readable and portable data format
|
||
- **Automatic Backups**: Created before major migrations
|
||
- **Backward Compatibility**: Existing data continues to work with updates
|
||
- **Dynamic Column Management**: Automatically adapts to new medicines/pathologies
|
||
- **Data Validation**: Ensures data integrity and handles edge cases
|
||
|
||
##### Migration Support:
|
||
- **Automatic Migration**: Data structure updates handled automatically
|
||
- **Backup Creation**: `thechart_data.csv.backup_YYYYMMDD_HHMMSS` format
|
||
- **No Data Loss**: All existing functionality and data preserved
|
||
- **Version Compatibility**: Seamless updates across application versions
|
||
|
||
#### 🧪 Comprehensive Testing Framework
|
||
Professional testing infrastructure with high code coverage.
|
||
|
||
##### Testing Statistics:
|
||
- **93% Overall Code Coverage** (482 total statements, 33 missed)
|
||
- **112 Total Tests** across 6 test modules
|
||
- **80 Tests Passing** (71.4% pass rate)
|
||
- **Pre-commit Testing**: Core functionality tests run before each commit
|
||
|
||
##### Test Coverage by Module:
|
||
- **100% Coverage**: constants.py, logger.py
|
||
- **97% Coverage**: graph_manager.py
|
||
- **95% Coverage**: init.py
|
||
- **93% Coverage**: ui_manager.py
|
||
- **91% Coverage**: main.py
|
||
- **87% Coverage**: data_manager.py
|
||
|
||
##### Testing Tools:
|
||
- **pytest**: Modern Python testing framework
|
||
- **pytest-cov**: Coverage reporting with HTML, XML, and terminal output
|
||
- **pytest-mock**: Mocking support for isolated testing
|
||
- **pre-commit hooks**: Automated testing before commits
|
||
|
||
### User Interface Features
|
||
|
||
#### 🖥️ Intuitive Design
|
||
- **Clean Main Interface**: Simplified new entry form focused on essential inputs
|
||
- **Organized Edit Windows**: Comprehensive dose management in dedicated edit interface
|
||
- **Scrollable Interface**: Vertical scrollbar for expanded UI components
|
||
- **Responsive Design**: Interface adapts to window size and content
|
||
- **Visual Feedback**: Success messages and clear status indicators
|
||
|
||
#### 🎯 User Experience Improvements
|
||
- **Centralized Dose Management**: All dose operations consolidated in edit windows
|
||
- **Quick Entry Options**: Pre-configured dose buttons for common amounts
|
||
- **Format Guidance**: Clear instructions and format examples
|
||
- **Real-time Updates**: Immediate feedback and data updates
|
||
- **Error Handling**: Comprehensive error messages and recovery options
|
||
|
||
#### ⌨️ Keyboard Shortcuts
|
||
Comprehensive keyboard shortcuts for efficient navigation and data entry.
|
||
|
||
##### File Operations:
|
||
- **Ctrl+S**: Save/Add new entry - Quickly save current entry data
|
||
- **Ctrl+Q**: Quit application - Exit with confirmation dialog
|
||
- **Ctrl+E**: Export data - Open export dialog window
|
||
|
||
##### Data Management:
|
||
- **Ctrl+N**: Clear entries - Clear all input fields for new entry
|
||
- **Ctrl+R / F5**: Refresh data - Reload data from CSV and update displays
|
||
- **Ctrl+F**: Toggle search/filter - Show or hide the search and filter panel
|
||
|
||
##### Window Management:
|
||
- **Ctrl+M**: Manage medicines - Open medicine management window
|
||
- **Ctrl+P**: Manage pathologies - Open pathology management window
|
||
|
||
##### Table Operations:
|
||
- **Delete**: Delete selected entry - Remove selected table entry with confirmation
|
||
- **Escape**: Clear selection - Clear current table selection
|
||
- **Double-click**: Edit entry - Open edit dialog for selected entry
|
||
|
||
##### Help System:
|
||
- **F1**: Show keyboard shortcuts - Display help dialog with all shortcuts
|
||
|
||
##### Integration Features:
|
||
- **Menu Display**: All shortcuts shown in menu bar next to items
|
||
- **Button Labels**: Primary buttons show their keyboard shortcuts
|
||
- **Case Insensitive**: Both Ctrl+S and Ctrl+Shift+S work
|
||
- **Focus Management**: Shortcuts work when main window has focus
|
||
- **Status Feedback**: All operations provide status bar feedback
|
||
|
||
### Technical Architecture
|
||
|
||
#### <20> Modern UI Architecture
|
||
- **ThemeManager**: Centralized theme management with dynamic switching
|
||
- **TooltipManager**: Smart tooltip system with context-sensitive help
|
||
- **UIManager**: Enhanced UI component creation with theme integration
|
||
- **SettingsWindow**: Advanced configuration interface with persistence
|
||
|
||
#### 🏗️ Core Application Design
|
||
- **MedicineManager**: Core medicine CRUD operations with JSON persistence
|
||
- **PathologyManager**: Symptom and pathology management system
|
||
- **GraphManager**: Professional graph rendering with matplotlib integration
|
||
- **DataManager**: Robust CSV operations and data persistence with validation
|
||
|
||
#### 🔧 Configuration and Data Management
|
||
- **JSON-based Configuration**: `medicines.json` and `pathologies.json` for easy management
|
||
- **Dynamic Loading**: Runtime configuration updates without restarts
|
||
- **Data Validation**: Comprehensive input validation and error handling
|
||
- **Backward Compatibility**: Seamless updates and migrations across versions
|
||
|
||
#### 📈 Advanced Data Processing
|
||
- **Pandas Integration**: Efficient data manipulation and analysis
|
||
- **Real-time Calculations**: Dynamic dose totals, averages, and statistics
|
||
- **Robust Parsing**: Handles various data formats and edge cases gracefully
|
||
- **Performance Optimization**: Efficient batch operations and caching
|
||
|
||
### UI/UX Technical Implementation
|
||
|
||
#### 🎭 Theme System Architecture
|
||
- **Multiple Theme Support**: 8 curated professional themes
|
||
- **Dynamic Style Application**: Real-time theme switching without restart
|
||
- **Color Extraction**: Automatic color scheme detection and application
|
||
- **Fallback Mechanisms**: Graceful handling when themes fail to load
|
||
|
||
#### 💡 Enhanced User Experience
|
||
- **Smart Tooltips**: Context-sensitive help with delayed, non-intrusive display
|
||
- **Modern Styling**: Card-style frames, enhanced buttons, professional form controls
|
||
- **Improved Tables**: Better selection highlighting and alternating row colors
|
||
- **Responsive Design**: Automatic layout adjustments and proper scaling
|
||
|
||
#### ⚙️ Settings and Persistence
|
||
- **Configuration Management**: Theme and preference persistence across sessions
|
||
- **Tabbed Settings Interface**: Organized categories for easy navigation
|
||
- **Live Preview**: Real-time theme preview in settings
|
||
- **Error Recovery**: Robust handling of corrupted settings with defaults
|
||
|
||
### Deployment and Distribution
|
||
|
||
#### 📦 Standalone Executable
|
||
- **PyInstaller Integration**: Creates self-contained executables
|
||
- **Cross-platform Support**: Linux deployment with desktop integration
|
||
- **Automatic Installation**: Installs to `~/Applications/` with desktop entry
|
||
- **Data Migration**: Copies data files to appropriate user directories
|
||
|
||
#### 🐳 Docker Support
|
||
- **Multi-platform Images**: Docker container support
|
||
- **Docker Compose**: Easy container management
|
||
- **Development Environment**: Consistent development setup across platforms
|
||
|
||
#### 🔄 Package Management
|
||
- **UV Integration**: Fast Python package management with Rust performance
|
||
- **Virtual Environment**: Isolated dependency management
|
||
- **Lock Files**: Reproducible builds with `uv.lock`
|
||
- **Development Dependencies**: Separate dev dependencies for clean production builds
|
||
|
||
### Integration Features
|
||
|
||
#### 🔄 Import/Export
|
||
- **CSV Import**: Import existing medication data
|
||
- **Data Export**: Export data for backup or analysis
|
||
- **Format Compatibility**: Standard CSV format for portability
|
||
|
||
#### 🔌 API Integration
|
||
- **Extensible Architecture**: Plugin system for future enhancements
|
||
- **Medicine API**: Programmatic medicine management
|
||
- **Data API**: Direct data access and manipulation
|
||
|
||
### Future Enhancements
|
||
|
||
#### 🚀 Planned Features
|
||
- **Mobile Companion App**: Mobile dose tracking and reminders
|
||
- **Cloud Synchronization**: Multi-device data synchronization
|
||
- **Advanced Analytics**: Machine learning-based trend analysis
|
||
- **Reminder System**: Intelligent dose reminders and scheduling
|
||
- **Doctor Integration**: Export reports for healthcare providers
|
||
|
||
#### 🎯 Development Roadmap
|
||
- **macOS/Windows Support**: Extended platform support
|
||
- **Plugin Architecture**: Third-party extension support
|
||
- **API Development**: RESTful API for external integrations
|
||
- **Advanced Visualizations**: Additional chart types and analysis tools
|
||
|
||
---
|
||
|
||
For detailed usage instructions, see the main [README.md](../README.md).
|
||
For development information, see [DEVELOPMENT.md](DEVELOPMENT.md).
|
||
|
||
---
|
||
*Originally from: FEATURES.md*
|
||
|
||
|
||
|
||
TheChart application supports comprehensive keyboard shortcuts for improved productivity and efficient navigation.
|
||
|
||
### File Operations
|
||
- **Ctrl+S**: Save/Add new entry - Saves the current entry data to the database
|
||
- **Ctrl+Q**: Quit application - Exits the application (with confirmation dialog)
|
||
- **Ctrl+E**: Export data - Opens the export dialog window
|
||
|
||
### Data Management
|
||
- **Ctrl+N**: Clear entries - Clears all input fields to start a new entry
|
||
- **Ctrl+R** or **F5**: Refresh data - Reloads data from the CSV file and updates the display
|
||
|
||
### Window Management
|
||
- **Ctrl+M**: Manage medicines - Opens the medicine management window
|
||
- **Ctrl+P**: Manage pathologies - Opens the pathology management window
|
||
|
||
### Table Operations
|
||
- **Delete**: Delete selected entry - Deletes the currently selected entry in the table (with confirmation)
|
||
- **Escape**: Clear selection - Clears the current selection in the table
|
||
- **Double-click**: Edit entry - Opens the edit dialog for the selected entry
|
||
|
||
### Help
|
||
- **F1**: Show keyboard shortcuts help - Displays a dialog with all available keyboard shortcuts
|
||
|
||
### Implementation Details
|
||
|
||
#### Menu Integration
|
||
All keyboard shortcuts are displayed in the menu bar next to their corresponding menu items for easy reference.
|
||
|
||
#### Button Labels
|
||
Primary action buttons show their keyboard shortcuts in the button text (e.g., "Add Entry (Ctrl+S)").
|
||
|
||
#### Case Sensitivity
|
||
- Shortcuts are case-insensitive
|
||
- Both `Ctrl+S` and `Ctrl+Shift+S` work
|
||
- Uppercase and lowercase variants are supported
|
||
|
||
#### Focus Requirements
|
||
- Keyboard shortcuts work when the main window has focus
|
||
- Focus is automatically set to the main window on startup
|
||
- Shortcuts work across all tabs and interface elements
|
||
|
||
#### Feedback System
|
||
- All operations provide feedback through the status bar
|
||
- Success and error messages are displayed
|
||
- Confirmation dialogs are shown for destructive operations (quit, delete)
|
||
|
||
### Usage Tips
|
||
|
||
#### Quick Workflow
|
||
1. **Ctrl+N** - Clear fields for new entry
|
||
2. Enter data in the form
|
||
3. **Ctrl+S** - Save the entry
|
||
4. **F5** - Refresh to see updated data
|
||
|
||
#### Navigation
|
||
- Use **Ctrl+M** and **Ctrl+P** to quickly access management windows
|
||
- Use **Delete** to remove unwanted entries from the table
|
||
- Use **Escape** to clear selections when needed
|
||
|
||
#### Getting Help
|
||
- Press **F1** anytime to see the keyboard shortcuts help dialog
|
||
- All shortcuts are also visible in the menu bar
|
||
- Button tooltips show additional keyboard shortcut information
|
||
|
||
### Accessibility
|
||
- Keyboard shortcuts provide full application functionality without mouse use
|
||
- All critical operations have keyboard equivalents
|
||
- Shortcuts follow standard application conventions (Ctrl+S for save, Ctrl+Q for quit)
|
||
- Help system is easily accessible via F1
|
||
|
||
---
|
||
*Originally from: KEYBOARD_SHORTCUTS.md*
|
||
|
||
|
||
---
|
||
|
||
## 📖 Documentation Navigation
|
||
|
||
- [User Guide](USER_GUIDE.md) - Features, shortcuts, and usage
|
||
- [Developer Guide](DEVELOPER_GUIDE.md) - Development and testing
|
||
- [API Reference](API_REFERENCE.md) - Technical documentation
|
||
- [Changelog](CHANGELOG.md) - Version history
|
||
- [Documentation Index](docs/README.md) - Complete navigation
|
||
|
||
---
|
||
|
||
*This document was generated by the documentation consolidation system.*
|
||
*Last updated: 2025-08-05 14:53:36*
|