Article-22742-EquiVolume-Indicator-In-MQL5/README.md

# Article-22742-EquiVolume-Indicator-In-MQL5

This repository is an article-derived reference project based on the original MQL5 article. It does not claim to reproduce the full original source code unless files are explicitly attached.

## Overview

This project is a reference reconstruction of an MQL5 custom indicator that implements an EquiVolume-style visualization. Instead of fixed-width candles, it draws volume-weighted rectangles in a separate indicator window, where candle height represents price range and candle width represents relative trading activity over a configurable lookback period.

The article describes the implementation incrementally and provides code fragments for key parts of the indicator logic.

## Original Article

- **Article ID:** 22742
- **Author:** Abioye Israel Pelumi
- **Publication date:** 2026.05.31 
- **Category:** MQL5 / Indicators
- **URL:** https://www.mql5.com/en/articles/22742

## Repository Purpose

The purpose of this repository is to preserve and document the article’s EquiVolume indicator design as a technical reference project.

Based on the processed material, the indicator aims to:

- choose between real volume and tick volume automatically;
- find the maximum volume in a lookback range;
- normalize candle volumes against that maximum;
- convert normalized volume into horizontal box width;
- draw candle range and candle body as rectangle objects;
- render the result in a separate indicator subwindow;
- remove outdated objects to keep the display limited to the active range.

## Key Concepts

- **EquiVolume visualization:** candle width reflects volume rather than being fixed.
- **Volume source fallback:** use real volume when available, otherwise tick volume.
- **Lookback-based scaling:** maximum volume is determined only within the selected historical window.
- **Dynamic vertical scaling:** indicator window min/max are set from the highest high and lowest low in the range.
- **Object-based rendering:** rectangles are used instead of standard indicator buffers.
- **Incremental redraw control:** calculations are run once per new candle using a stored bar timestamp.
- **Bullish/bearish body coloring:** candle body fill depends on close vs. open.

## Algorithm / Architecture Summary

The article describes the following architecture:

1. **Indicator setup**
- Declare a separate-window indicator with no standard plots.
- Define inputs such as lookback, bull/bear colors, outline color, and maximum width scaling.
- Store the indicator subwindow index with `ChartWindowFind()`.

2. **Execution timing**
- In `OnCalculate()`, limit processing to the configured lookback.
- Run the main logic only once per new candle using a `lastTradeBarTime` check.

3. **Volume source selection**
- Detect whether broker-provided real volume is available.
- Fall back to tick volume if real volume is unavailable.

4. **Reference range scan**
- Scan the lookback range to determine:
- maximum volume;
- highest high;
- lowest low.

5. **Indicator scale update**
- Set `INDICATOR_MAXIMUM` and `INDICATOR_MINIMUM` from the observed price extremes.

6. **Volume normalization**
- For each closed candle in the range, compute a width factor:
- `width = volume / maxVolume * InpMaxWidthPct`
- Skip zero-volume candles.

7. **Rectangle drawing**
- Draw one rectangle for the candle’s full high-low range.
- Draw a second filled rectangle for the open-close body.
- Reuse existing objects when possible rather than recreating them.

8. **Horizontal chaining**
- Use time coordinates to place each rectangle.
- Move the next candle’s starting point to the previous candle’s endpoint so boxes connect sequentially.

9. **Cleanup**
- Delete old rectangle objects outside the active display range.
- Clear box objects during initialization and deinitialization.

## Mentioned or Attached Files

### Explicitly attached files

No attached source files were available in the processed input.

### Files mentioned in the article text

The article provides inline MQL5 code fragments for an indicator implementation, including:

- an indicator source containing:
- `OnInit()`
- `OnCalculate()`
- `OnDeinit()`
- `DrawBox(...)`
- `BoxEmptyName(...)`
- `BoxFillName(...)`

No concrete filename was provided in the processed input.

## Statistics

- **Code availability:** Partial, from article excerpts only
- **Implementation type:** Custom indicator
- **Rendering method:** Chart rectangle objects in a separate indicator window
- **Primary data inputs:** Open, high, low, close, tick volume, real volume
- **Configurable inputs mentioned:** 5
- `InpLookback`
- `InpBullColor`
- `InpBearColor`
- `InpOutlineColor`
- `InpMaxWidthPct`

## Tags

`MQL5` `Indicator` `EquiVolume` `Volume-Analysis` `Custom-Charting` `MetaTrader-5` `Object-Drawing` `Technical-Analysis`

## Difficulty

**Intermediate**

The article assumes familiarity with:

- MQL5 indicator lifecycle functions;
- timeseries arrays in `OnCalculate()`;
- chart object APIs such as `ObjectCreate`, `ObjectMove`, and `ObjectsDeleteAll`;
- subwindow rendering and indicator scaling.

## Limitations

- The full original source code is **not available** in the processed input.
- The article content includes **incremental code excerpts**, not a clearly attached complete project file.
- Because no explicit repository file list was attached, this README presents the project as a **reference/reconstruction** rather than a verified full reproduction.
- Some implementation details may require validation in a real `.mq5` file, especially object cleanup behavior and subwindow object management.

## Reference

This README is based solely on the processed article text describing an MQL5 EquiVolume indicator implemented with rectangle objects, dynamic price scaling, and volume-normalized candle widths.