thechart/USER_GUIDE.md

# 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
### Backup and Restore

#### Creating Backups
- Automatic backups are created on startup and shutdown
- Manual backups: Tools → Create Backup Now (Ctrl+Shift+B)
- Backups are stored in your backups folder (Tools → Open Backups Folder)

#### Restoring from Backup
You can restore the main CSV from a previous backup file.

Steps:
1. Open Tools → Restore from Backup… (or press Ctrl+Shift+R)
2. Select a backup CSV file from the backups folder
3. Review the confirmation dialog (file name, size, last modified)
4. Confirm to proceed

Notes:
- A safety backup of the current data is created automatically before restore
- After restore, the table and graph refresh automatically
- The status bar shows the result and a brief toast confirms success
- Use Tools → Open Backups Folder to locate backup files quickly

- **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*

## New in v1.14.9: Filters, columns, and exports

### Filter presets (Save/Load/Delete)
- Open the Search/Filter panel (Ctrl+F), set filters, then click Save to store a named preset.
- A themed modal dialog asks for a name and shows if you’ll overwrite an existing preset.
- Load via the presets dropdown → Load. Delete via Delete.
- Presets persist across restarts.

### Persistent column widths and sort
- Resize columns; widths are saved automatically and restored next run.
- Click a header to sort; the last sorted column and direction are remembered and re-applied on refresh/startup.

### Export current (filtered) data
- In Export (Ctrl+E), choose scope: All data or Current filtered view.
- Works with CSV, JSON, XML, and PDF exporters.