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)

## 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
```json
{
  "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
<?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:
```python
{
    "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:
```python
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

```python
## 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:

```bash
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](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*