Files

William Valentin a521ed6e9a

Build and Push Docker Image / build-and-push (push) Has been cancelled

Details

Add quick test runner and enhance run_tests script

- Introduced `quick_test.py` for running specific test categories (unit, integration, theme, all).
- Updated `run_tests.py` to improve test execution and reporting, including coverage.
- Removed outdated test scripts for keyboard shortcuts, menu theming, note saving, and entry updating.
- Added new test script `test_theme_changing.py` to verify theme changing functionality.
- Consolidated integration tests into `test_integration.py` for comprehensive testing of TheChart application.
- Updated theme manager to ensure color retrieval works correctly.
- Modified test constants to import from the correct module path.

2025-08-05 15:09:13 -07:00

19 KiB

Raw Permalink Blame History

TheChart User Guide

📖 Consolidated Documentation: This document combines multiple documentation files for better organization and easier navigation.

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

Through UI: Go to Tools → Manage Medicines...
Manual Configuration: Edit medicines.json directly
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

Context-sensitive help system providing guidance throughout the application.

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:

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

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

<EFBFBD> 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. For development information, see 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

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

Ctrl+N - Clear fields for new entry
Enter data in the form
Ctrl+S - Save the entry
F5 - Refresh to see updated data

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

User Guide - Features, shortcuts, and usage
Developer Guide - Development and testing
API Reference - Technical documentation
Changelog - Version history
Documentation Index - Complete navigation

This document was generated by the documentation consolidation system. Last updated: 2025-08-05 14:53:36

19 KiB Raw Permalink Blame History Unescape Escape

TheChart User Guide

Table of Contents

Overview

Overview

🎨 Modern UI/UX System (New in v1.9.5)

Professional Theme Engine

Available Themes:

UI Enhancements:

⌨️ Comprehensive Keyboard Shortcuts

File Operations:

Data Management:

Window Management:

Core Features

🏥 Modular Medicine System

Features:

Medicine Configuration:

Default Medicines:

Usage:

⚙️ Settings and Theme Management

Settings Window (F2):

Theme Features:

💡 Smart Tooltip System

Tooltip Types:

Features:

💊 Advanced Dose Tracking

Core Capabilities:

Dose Management Interface:

Data Format:

Example CSV Format:

📊 Enhanced Graph Visualization

Medicine Dose Visualization:

Interactive Controls:

Enhanced Legend:

Dose Calculation Features:

🏥 Pathology Management

Features:

📝 Data Management

Data Features:

Migration Support:

🧪 Comprehensive Testing Framework

Testing Statistics:

Test Coverage by Module:

Testing Tools:

User Interface Features

🖥️ Intuitive Design

🎯 User Experience Improvements

⌨️ Keyboard Shortcuts

File Operations:

Data Management:

Window Management:

Table Operations:

Help System:

Integration Features:

Technical Architecture

<EFBFBD> Modern UI Architecture

🏗️ Core Application Design

🔧 Configuration and Data Management

📈 Advanced Data Processing

UI/UX Technical Implementation

🎭 Theme System Architecture

💡 Enhanced User Experience

⚙️ Settings and Persistence

Deployment and Distribution

📦 Standalone Executable

🐳 Docker Support

🔄 Package Management

Integration Features

🔄 Import/Export

🔌 API Integration

Future Enhancements

🚀 Planned Features

🎯 Development Roadmap

File Operations

Data Management

Window Management

Table Operations

Help

Implementation Details

Menu Integration

19 KiB

Raw Permalink Blame History