thechart/API_REFERENCE.md

TheChart API Reference

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

Table of Contents

• Overview

Overview

Technical API documentation and system details

Overview

The TheChart application now includes a comprehensive data export system that allows users to export their medication tracking data and visualizations to multiple formats:

• JSON - Structured data format with metadata
• XML - Hierarchical data format
• PDF - Formatted report with optional graph visualization

Features

Export Formats

JSON Export

• Exports all CSV data to structured JSON format
• Includes metadata about the export (date, total entries, date range)
• Lists all pathologies and medicines being tracked
• Data is exported as an array of entry objects

XML Export

• Exports data to hierarchical XML format
• Includes comprehensive metadata section
• All entries are properly structured with XML tags
• Column names are sanitized for valid XML element names

PDF Export

• Creates a formatted report document
• Includes export metadata and summary information
• Optional graph visualization inclusion
• Data table with all entries
• Proper pagination and styling
• Notes are truncated for better table formatting

User Interface

The export functionality is accessible through:

1. File Menu - "Export Data..." option in the main menu bar
2. Export Window - Modal dialog with export options
3. Format Selection - Radio buttons for JSON, XML, or PDF
4. Graph Option - Checkbox to include graph in PDF exports
5. File Dialog - Standard save dialog for choosing export location

Export Manager Architecture

The export system consists of three main components:

ExportManager Class (src/export_manager.py)

• Core export functionality
• Handles data transformation and file generation
• Integrates with existing data and graph managers
• Supports all three export formats

ExportWindow Class (src/export_window.py)

• GUI interface for export operations
• Modal dialog with export options
• File save dialog integration
• Progress feedback and error handling

Integration in MedTrackerApp (src/main.py)

• Export manager initialization
• Menu integration
• Seamless integration with existing managers

Technical Implementation

Dependencies Added

• reportlab - PDF generation library
• lxml - XML processing (added for future enhancements)
• charset-normalizer - Character encoding support

Data Flow

1. User selects export format and options
2. ExportManager loads data from DataManager
3. Data is transformed according to selected format
4. Graph image is optionally generated for PDF
5. Output file is created and saved
6. User receives success/failure feedback

Error Handling

• Graceful handling of missing data
• File system error management
• User-friendly error messages
• Logging of export operations

Usage Examples

Basic Export Process

1. Open TheChart application
2. Go to File → Export Data...
3. Select desired format (JSON/XML/PDF)
4. For PDF: choose whether to include graph
5. Click "Export..." button
6. Choose save location and filename
7. Confirm successful export

Export File Examples

JSON Structure

{
  "metadata": {
    "export_date": "2025-08-02T09:03:22.580489",
    "total_entries": 32,
    "date_range": {
      "start": "07/02/2025",
      "end": "08/02/2025"
    },
    "pathologies": ["depression", "anxiety", "sleep", "appetite"],
    "medicines": ["bupropion", "hydroxyzine", "gabapentin", "propranolol", "quetiapine"]
  },
  "entries": [
    {
      "date": "07/02/2025",
      "depression": 8,
      "anxiety": 5,
      "sleep": 3,
      "appetite": 1,
      "bupropion": 0,
      "bupropion_doses": "",
      "note": "Starting medication tracking"
    }
  ]
}

XML Structure

<?xml version="1.0" encoding="UTF-8"?>
<thechart_data>
  <metadata>
    <export_date>2025-08-02T09:03:22.613013</export_date>
    <total_entries>32</total_entries>
    <date_range>
      <start>07/02/2025</start>
      <end>08/02/2025</end>
    </date_range>
  </metadata>
  <entries>
    <entry>
      <date>07/02/2025</date>
      <depression>8</depression>
      <anxiety>5</anxiety>
      <note>Starting medication tracking</note>
    </entry>
  </entries>
</thechart_data>

Testing

Automated Tests

• Export functionality is tested through simple_export_test.py
• Creates sample exports in all three formats
• Validates file creation and basic content structure

Manual Testing

• GUI testing available through test_export_gui.py
• Opens export window for interactive testing
• Allows testing of all user interface components

Test Files Location

Exported test files are created in the test_exports/ directory:

• export.json - JSON format export
• export.xml - XML format export
• export.csv - CSV format copy
• test_export.pdf - PDF format with graph

File Locations

Source Files

• src/export_manager.py - Core export functionality
• src/export_window.py - GUI export interface

Test Files

• simple_export_test.py - Basic export functionality test
• test_export_gui.py - GUI testing interface
• scripts/test_export_functionality.py - Comprehensive export tests

Dependencies

• Added to requirements.txt and managed by uv
• PDF generation requires reportlab
• XML processing enhanced with lxml

Future Enhancements

Potential improvements for the export system:

1. Additional Formats - Excel, CSV with formatting
2. Export Filtering - Date range selection, specific pathologies/medicines
3. Batch Exports - Multiple formats at once
4. Email Integration - Direct email export
5. Cloud Storage - Export to cloud services
6. Export Scheduling - Automated periodic exports
7. Advanced PDF Styling - Charts, graphs, custom layouts

Troubleshooting

Common Issues

1. No Data to Export - Ensure CSV file has entries before exporting
2. PDF Generation Fails - Check ReportLab installation and permissions
3. File Save Errors - Verify write permissions to selected directory
4. Large File Exports - PDF exports may take longer for large datasets

Debugging

• Check application logs for detailed error messages
• Export operations are logged with DEBUG level information
• File system errors are captured and reported to user

Integration Notes

The export system integrates seamlessly with existing TheChart functionality:

• Uses same data validation and loading mechanisms
• Respects existing pathology and medicine configurations
• Maintains data integrity and formatting consistency
• Follows existing logging and error handling patterns

---

Originally from: EXPORT_SYSTEM.md

Overview

TheChart application now supports full menu theming that integrates seamlessly with the application's theme system. All menus (File, Tools, Theme, Help) will automatically adopt colors that match the selected application theme.

Features

Automatic Theme Integration

• Menus automatically inherit colors from the current application theme
• Background colors are slightly adjusted to provide subtle visual distinction
• Hover effects use the theme's accent colors for consistency

Supported Menu Elements

• Main menu bar
• All dropdown menus (File, Tools, Theme, Help)
• Menu items and separators
• Hover/active states
• Disabled menu items

Theme Colors Applied

For each theme, the following color properties are applied to menus:

• Background: Slightly darker/lighter than the main theme background
• Foreground: Uses the theme's text color
• Active Background: Uses the theme's selection/accent color
• Active Foreground: Uses the theme's selection text color
• Disabled Foreground: Grayed out color for disabled items

Technical Implementation

ThemeManager Methods

get_menu_colors() -> dict[str, str]

Returns a dictionary of colors specifically optimized for menu theming:

{
    "bg": "#edeeef",           # Menu background
    "fg": "#5c616c",           # Menu text
    "active_bg": "#0078d4",    # Hover background
    "active_fg": "#ffffff",    # Hover text
    "disabled_fg": "#888888"   # Disabled text
}

configure_menu(menu: tk.Menu) -> None

Applies theme colors to a specific menu widget:

theme_manager.configure_menu(menubar)
theme_manager.configure_menu(file_menu)

Automatic Updates

When themes are changed using the Theme menu:

1. The new theme is applied to all UI components
2. The menu setup is refreshed (_setup_menu() is called)
3. All menus are automatically re-themed with the new colors

Usage Example

## Create menu
menubar = tk.Menu(root)
file_menu = tk.Menu(menubar, tearoff=0)

## Apply theming
theme_manager.configure_menu(menubar)
theme_manager.configure_menu(file_menu)

## Menus will now match the current theme

Color Calculation

The menu background color is automatically calculated based on the main theme:

• Light themes: Menu background is made slightly darker than the main background
• Dark themes: Menu background is made slightly lighter than the main background

This provides subtle visual distinction while maintaining theme consistency.

Supported Themes

Menu theming works with all available themes:

• arc
• equilux
• adapta
• yaru
• ubuntu
• plastik
• breeze
• elegance

Testing

A test script is available to verify menu theming functionality:

cd /home/will/Code/thechart
.venv/bin/python scripts/test_menu_theming.py

This script creates a test window with menus that can be used to verify theming across different themes.

---

Originally from: MENU_THEMING.md

---

📖 Documentation Navigation

• 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