refactor: add Holt_Engine architecture

Indicators/MyIndicators/Holt.md

@@ -1,12 +1,17 @@
-# Holt Double Exponential Smoothing (MA, Oscillator & Channel)
+# Holt Double Exponential Smoothing Professional
 
 ## 1. Summary (Introduction)
 
-The Holt Double Exponential Smoothing (DES), also known as Holt's Linear Trend Method, is a powerful statistical technique for smoothing and forecasting time series data. Unlike traditional moving averages that only calculate the average price level, Holt's method explicitly models and smooths two distinct components of price movement: the **Level** (the average value) and the **Trend** (the rate of change).
+The Holt Double Exponential Smoothing (DES), or Holt's Linear Trend Method, is a powerful statistical technique for smoothing and forecasting time series data. Unlike traditional moving averages, Holt's method explicitly models and smooths two distinct components: the **Level** (average value) and the **Trend** (rate of change).
 
-By separating these components, the Holt method produces an exceptionally smooth moving average that is less prone to whipsaws in choppy markets. Its most significant feature is its predictive nature: the final plotted line is a **one-bar-ahead forecast** of where the price level is expected to be if the current smoothed trend continues.
+By separating these components, the Holt method produces an exceptionally smooth moving average that is also a **one-bar-ahead forecast** of the price level.
 
-Our MQL5 suite provides a complete family of indicators based on this model: the main **Holt MA** line, a **Holt Trend Oscillator** for measuring trend velocity, and a **Holt Forecast Channel** for visualizing the projected price path. All indicators are available in both standard and Heikin Ashi variants.
+Our professional MQL5 suite provides a complete, unified family of indicators based on this model:
+
+* **`Holt_Pro.mq5`**: A versatile chart indicator that can display either the main **Holt MA** line or a full **Holt Forecast Channel**.
+* **`Holt_Oscillator_Pro.mq5`**: A separate-window indicator that plots the **Trend** component as a histogram, visualizing the trend's velocity.
+
+Both indicators can be calculated using either **standard** or **Heikin Ashi** price data, selectable from a single input parameter.
 
 ## 2. Mathematical Foundations and Calculation Logic
 
@@ -14,67 +19,59 @@ The Holt method is a recursive system defined by two interconnected smoothing eq
 
 ### Required Components
 
-- **Alpha ($\alpha$):** The smoothing factor for the **Level** component (0 < $\alpha$ < 1). A higher alpha gives more weight to recent prices.
-- **Beta ($\beta$):** The smoothing factor for the **Trend** component (0 < $\beta$ < 1). A higher beta makes the trend component react more quickly to changes in the direction of the price.
-- **Price Data:** The source price series (e.g., `PRICE_CLOSE`).
+* **Alpha ($\alpha$):** The smoothing factor for the **Level** component (0 < $\alpha$ < 1).
+* **Beta ($\beta$):** The smoothing factor for the **Trend** component (0 < $\beta$ < 1).
+* **Price Data:** The source price series (e.g., `PRICE_CLOSE`).
 
 ### Calculation Steps (Algorithm)
 
-1. **Initialization:** The model requires initial values for the first Level ($L_0$) and Trend ($T_0$). A robust statistical approach is used:
-    - $L_0 = \text{Price}_0$
-    - $T_0 = \text{Price}_1 - \text{Price}_0$
+1. **Initialization:** The model requires initial values for the first Level ($L_0$) and Trend ($T_0$).
+    * $L_0 = \text{Price}_0$
+    * $T_0 = \text{Price}_1 - \text{Price}_0$
 
-2. **Recursive Calculation:** For each subsequent bar `t`, the Level and Trend are calculated as follows:
+2. **Recursive Calculation:** For each subsequent bar `t`:
+    * **Level Equation:** $L_t = \alpha \cdot \text{Price}_t + (1 - \alpha) \cdot (L_{t-1} + T_{t-1})$
+    * **Trend Equation:** $T_t = \beta \cdot (L_t - L_{t-1}) + (1 - \beta) \cdot T_{t-1}$
 
-    - **Level Equation:** The current Level ($L_t$) is a weighted average of the current price and the previous period's forecasted level (which is the sum of the previous level and previous trend).
-        $L_t = \alpha \cdot \text{Price}_t + (1 - \alpha) \cdot (L_{t-1} + T_{t-1})$
-
-    - **Trend Equation:** The current Trend ($T_t$) is a weighted average of the change in the Level between the current and previous bar, and the previous Trend value.
-        $T_t = \beta \cdot (L_t - L_{t-1}) + (1 - \beta) \cdot T_{t-1}$
-
-3. **Forecasting:** The model's predictive power comes from its ability to project into the future. The forecast for `m` periods ahead is:
-    - $\text{Forecast}_{t+m} = L_t + m \cdot T_t$
-    - The main **Holt MA** line is the one-bar-ahead forecast ($m=1$).
-    - The **Holt Channel** uses this formula with a user-defined `m` to plot the upper and lower bands.
-    - The **Holt Oscillator** directly plots the value of the `Trend` component ($T_t$).
+3. **Forecasting:** The forecast for `m` periods ahead is:
+    * $\text{Forecast}_{t+m} = L_t + m \cdot T_t$
+    * The main **Holt MA** line is the one-bar-ahead forecast ($m=1$).
+    * The **Holt Channel** uses this formula with a user-defined `m`.
+    * The **Holt Oscillator** directly plots the `Trend` component ($T_t$).
 
 ## 3. MQL5 Implementation Details
 
-Our MQL5 implementation is designed as a cohesive and reusable indicator family, built upon a single, robust calculation engine.
+Our MQL5 implementation is a cohesive and reusable indicator family, built upon a single, robust calculation engine.
 
-- **Modular, Reusable Calculation Engine (`Holt_Calculator.mqh`):** The entire Holt DES algorithm is encapsulated within a powerful `CHoltMACalculator` class, located in `MyIncludes\Holt_Calculator.mqh`.
-  - This engine performs the full calculation of all three components (Level, Trend, and Forecast) in a single pass.
-  - It uses an elegant, object-oriented inheritance model to provide a Heikin Ashi variant. The `CHoltMACalculator_HA` child class inherits all the complex logic from the base class and only overrides the initial data preparation step to use smoothed Heikin Ashi prices as its input. This eliminates code duplication and ensures both versions are always in sync.
+* **Centralized Calculation Engine (`Holt_Engine.mqh`):**
+    The core of our implementation is a single, powerful calculation engine. This include file contains the complete logic for calculating all Holt components (Level, Trend, Forecast, and Channel bands). It supports both standard and Heikin Ashi data sources through class inheritance (`CHoltEngine` and `CHoltEngine_HA`), eliminating code duplication.
 
-- **Stability via Full Recalculation:** The Holt method is highly recursive. To ensure perfect accuracy and prevent any risk of calculation errors, all our Holt indicators employ a "brute-force" **full recalculation** on every tick. This is our core principle of prioritizing stability.
+* **Specialized Wrappers (`Holt_Calculator.mqh`, `Holt_Oscillator_Calculator.mqh`):**
+    The final indicators use thin "wrapper" classes that utilize the central engine.
+  * `Holt_Calculator` calls the engine and provides the outputs needed for the `Holt_Pro` indicator (MA and Channel bands).
+  * `Holt_Oscillator_Calculator` calls the same engine but only extracts the `Trend` component for the `Holt_Oscillator_Pro` indicator.
 
-- **Robust Initialization:** The calculator uses a statistically sound method to initialize the first Level and Trend values, ensuring the indicator behaves correctly from the very first bars of the chart history.
-
-- **The Holt Indicator Family:**
-  - **`Holt_MA.mq5`**: The main indicator, displaying the one-bar-ahead forecast line on the main chart.
-  - **`Holt_Oscillator.mq5`**: A separate-window indicator that plots the `Trend` component as a histogram around a zero line, visualizing the trend's velocity and acceleration.
-  - **`Holt_Channel.mq5`**: A chart-window indicator that plots the `Holt MA` as a centerline and adds upper/lower bands based on a multi-period forecast, creating a predictive price channel.
-  - Each indicator is also available in a `_HeikinAshi` variant.
+* **Stability via Full Recalculation:** The Holt method is highly recursive. To ensure perfect accuracy and prevent calculation errors, all our Holt indicators employ a "brute-force" **full recalculation** on every tick.
 
 ## 4. Parameters
 
-- **Period (`InpPeriod`):** Used for the robust initialization of the model. It has a minor effect on the ongoing calculation. Default is `20`.
-- **Alpha (`InpAlpha`):** The smoothing factor for the Level. Lower values create a smoother, slower-reacting level component. Higher values make it more sensitive to recent prices. Default is `0.1`.
-- **Beta (`InpBeta`):** The smoothing factor for the Trend. Lower values create a very smooth, stable trend component that is slow to change direction. Higher values make the trend component react very quickly to changes in price direction. Default is `0.05`.
-- **Forecast Period (`InpForecastPeriod`):** (Only for `Holt_Channel`) The number of bars (`m`) to project into the future for the channel bands. Default is `5`.
-- **Source Price (`InpSourcePrice`):** The price data used for the calculation. Default is `PRICE_CLOSE`.
+* **Period (`InpPeriod`):** Used for the robust initialization of the model. Default is `20`.
+* **Alpha (`InpAlpha`):** The smoothing factor for the Level. Lower values create a smoother level. Default is `0.1`.
+* **Beta (`InpBeta`):** The smoothing factor for the Trend. Lower values create a more stable trend component. Default is `0.05`.
+* **Source Price (`InpSourcePrice`):** The price data used for the calculation. This unified dropdown menu allows you to select from all standard and Heikin Ashi price types.
+* **Display Mode (`InpDisplayMode`):** (Only for `Holt_Pro`) Toggles between displaying only the MA line or the full MA + Channel.
+* **Forecast Period (`InpForecastPeriod`):** (Only for `Holt_Pro` in Channel mode) The number of bars (`m`) to project into the future for the channel bands. Default is `5`.
 
 ## 5. Usage and Interpretation
 
-- **`Holt_MA` (The Main Line):**
-  - **Trend Filter:** The slope of the Holt MA line indicates the smoothed, forecasted trend direction. A flattening line is an early warning that the trend is losing momentum.
-  - **Dynamic Support/Resistance:** The line acts as an intelligent S/R level that projects where the "fair value" should be in the next bar. Pullbacks to the line in a strong trend can be entry opportunities.
+### `Holt_Pro` (The Main Line and Channel)
 
-- **`Holt_Oscillator` (The Trend Engine):**
-  - **Trend Direction:** Values above the zero line indicate a bullish trend; values below indicate a bearish trend. A crossover of the zero line is a strong trend-change signal.
-  - **Trend Velocity:** The magnitude of the oscillator's bars indicates the speed of the trend. Rising bars show acceleration; falling bars (while still positive) show deceleration.
-  - **Divergence:** Divergence between the oscillator and price can signal trend exhaustion and an impending reversal.
+* **Trend Filter:** The slope of the Holt MA line indicates the smoothed, forecasted trend direction. A flattening line is an early warning that the trend is losing momentum.
+* **Dynamic Support/Resistance:** The line acts as an intelligent S/R level that projects where the "fair value" should be in the next bar.
+* **Channel as Forecast Path:** The channel visualizes the path the price is expected to follow if the current trend persists. When price touches or exceeds the outer channel bands, it signals that the move is potentially over-extended.
 
-- **`Holt_Channel` (The Forecast Path):**
-  - **Projected Path:** The channel visualizes the path the price is expected to follow if the current trend persists.
-  - **Over-extension Signal:** When price touches or exceeds the outer channel bands, it signals that the move has been exceptionally strong and is potentially over-extended, increasing the probability of a pullback toward the centerline.
+### `Holt_Oscillator_Pro` (The Trend Engine)
+
+* **Trend Direction:** Values above the zero line indicate a bullish trend; values below indicate a bearish trend. A crossover of the zero line is a strong trend-change signal.
+* **Trend Velocity:** The magnitude of the oscillator's bars indicates the speed of the trend. Rising bars show acceleration; falling bars (while still on the same side of zero) show deceleration.
+* **Divergence:** Divergence between the oscillator and price can signal trend exhaustion and an impending reversal.