# HrBar

## Overview

The HrBar widget is a custom TouchGFX container designed to visually represent heart rate levels using a series of heart-shaped icons. It provides a simple, intuitive way to display heart rate data in wearable or fitness applications, with five distinct visual states ranging from very low to very high heart rate.

## Purpose

The HrBar widget serves as a graphical indicator for heart rate monitoring. It displays one of five heart icons based on the current heart rate value compared against configurable thresholds. This allows users to quickly assess their heart rate status at a glance, making it ideal for fitness trackers, smartwatches, and health monitoring applications.

## Components

The widget consists of the following visual elements:

- **Background Group**: A static background image (`HR_group.png`) that provides the base visual context
- **Heart Icons**: Five individual heart images representing different heart rate levels:
  - `HR_1.png`: Very low heart rate (default visible state)
  - `HR_2.png`: Low heart rate
  - `HR_3.png`: Medium heart rate (centered position)
  - `HR_4.png`: High heart rate
  - `HR_5.png`: Very high heart rate

The heart icons are positioned asymmetrically to create a balanced visual bar effect, with the medium level icon centered and the extreme levels positioned at the edges.

## Functionality

### Core Features

- **Threshold-Based Display**: Accepts a heart rate value and four threshold values to determine which icon to display
- **Five Visual States**: Supports five distinct heart rate levels for granular feedback
- **Dynamic Visibility**: Only one heart icon is visible at a time, with others hidden
- **Automatic Invalidation**: Refreshes the display after state changes

### Threshold Logic

The widget uses the following logic to select which heart icon to display:

```cpp
if (hr > th[3]) {
    // Show very high heart rate (hr5)
} else if (hr > th[2]) {
    // Show high heart rate (hr4)
} else if (hr > th[1]) {
    // Show medium heart rate (hr3)
} else if (hr > th[0]) {
    // Show low heart rate (hr2)
} else {
    // Show very low heart rate (hr1)
}
```

Where:
- `hr`: Current heart rate value (float)
- `th`: Array of four threshold values (uint8_t[4]), ordered from lowest to highest

## Usage in TouchGFX Designer

1. **Import the Custom Container**:
   - Open your TouchGFX project
   - Go to the Designer view
   - Import the HrBar custom container package

2. **Add to Screen**:
   - Drag the HrBar widget from the custom containers panel onto your screen
   - Position and resize as needed (default size: 210x71 pixels)

3. **Configure Properties**:
   - The widget doesn't have configurable properties in the Designer
   - All configuration is done programmatically

## Usage in C++ Code

### Basic Setup

```cpp
#include <gui/containers/HrBar.hpp>

// In your view or presenter
HrBar hrBar;

// Initialize in setup
hrBar.initialize();
```

### Setting Heart Rate

```cpp
// Define thresholds (example values)
std::array<uint8_t, 4> thresholds = {60, 100, 140, 180}; // BPM thresholds

// Set current heart rate
float currentHR = 120.0f; // BPM
hrBar.setHR(currentHR, thresholds);
```

### Integration Example

```cpp
class MainView : public MainViewBase
{
private:
    HrBar hrBar;

public:
    MainView() : hrBar() {}

    void setupScreen()
    {
        MainViewBase::setupScreen();
        hrBar.initialize();
        add(hrBar); // Add to screen
    }

    void updateHeartRate(float bpm)
    {
        std::array<uint8_t, 4> thresholds = {50, 80, 120, 160};
        hrBar.setHR(bpm, thresholds);
    }
};
```

## Advanced Features

### Customizable Thresholds

The widget's thresholds are fully configurable, allowing adaptation to different user profiles or activity contexts:

- **Resting Heart Rate**: Lower thresholds for sedentary users
- **Athletic Training**: Higher thresholds for athletes
- **Age-Adjusted**: Different ranges for various age groups

### Visual Design Considerations

- **Asymmetric Layout**: The heart icons are positioned to create visual balance and flow
- **Size Variation**: Icons vary in size to emphasize the center position
- **Background Integration**: The group background provides context and framing

### Performance Notes

- Minimal redraw operations (only the active icon is visible)
- Efficient state management with automatic invalidation
- Suitable for real-time heart rate updates

## Technical Details

- **Base Class**: Inherits from `HrBarBase` (generated by TouchGFX Designer)
- **Minimum TouchGFX Version**: 4.26.0
- **File Structure**:
  - `HrBar.hpp`: Class declaration
  - `HrBar.cpp`: Implementation
  - Image assets: 6 PNG files
  - Configuration files: Manifests and export data

## Best Practices

1. **Threshold Calibration**: Set meaningful thresholds based on user health data
2. **Real-time Updates**: Call `setHR()` frequently for live monitoring
3. **User Feedback**: Combine with numerical display for precise values
4. **Accessibility**: Consider color-blind users when designing heart rate zones

## Limitations

- Fixed visual design (5 levels, specific icon positions)
- No animation between states
- Thresholds must be provided programmatically (not configurable in Designer)