318 lines
20 KiB
HTML
318 lines
20 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="fa" dir="rtl">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>X121 XReplay - سند پروژه</title>
|
||
<style>
|
||
@page { size: A4; margin: 2cm; }
|
||
@media print {
|
||
.page-break { page-break-before: always; }
|
||
body { font-size: 11px; }
|
||
}
|
||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||
body {
|
||
font-family: 'Segoe UI', Tahoma, Arial, sans-serif;
|
||
line-height: 1.9; color: #1a1a2e; background: #fff;
|
||
padding: 40px; max-width: 850px; margin: 0 auto;
|
||
}
|
||
h1 { font-size: 1.7em; color: #0f3460; border-bottom: 3px solid #e94560; padding-bottom: 12px; margin-bottom: 20px; }
|
||
h2 { font-size: 1.35em; color: #16213e; margin-top: 28px; margin-bottom: 12px; padding-right: 12px; border-right: 4px solid #e94560; }
|
||
h3 { font-size: 1.1em; color: #0f3460; margin-top: 18px; margin-bottom: 8px; }
|
||
p { margin-bottom: 10px; text-align: justify; }
|
||
.cover { text-align: center; padding: 70px 0; }
|
||
.cover h1 { font-size: 2.4em; border: none; color: #e94560; margin-bottom: 10px; }
|
||
.cover .subtitle { font-size: 1.2em; color: #555; margin-top: 12px; }
|
||
.cover .meta { margin-top: 50px; color: #777; line-height: 2.2; }
|
||
table { width: 100%; border-collapse: collapse; margin: 12px 0 20px; font-size: 0.9em; }
|
||
th, td { border: 1px solid #ccc; padding: 9px 11px; text-align: right; }
|
||
th { background: #0f3460; color: #fff; font-weight: 600; }
|
||
tr:nth-child(even) { background: #f4f6f9; }
|
||
code { background: #f0f0f0; padding: 2px 5px; border-radius: 3px; font-family: 'Courier New', monospace; font-size: 0.87em; color: #c7254e; }
|
||
pre {
|
||
background: #1e1e2e; color: #cdd6f4; padding: 16px; border-radius: 6px;
|
||
overflow-x: auto; margin: 12px 0 20px; font-size: 0.82em;
|
||
line-height: 1.6; direction: ltr; text-align: left;
|
||
}
|
||
.note { background: #fff3cd; border-right: 4px solid #ffc107; padding: 12px 16px; margin: 12px 0; border-radius: 0 5px 5px 0; }
|
||
.tip { background: #d1ecf1; border-right: 4px solid #17a2b8; padding: 12px 16px; margin: 12px 0; border-radius: 0 5px 5px 0; }
|
||
.success { background: #d4edda; border-right: 4px solid #28a745; padding: 12px 16px; margin: 12px 0; border-radius: 0 5px 5px 0; }
|
||
.flow-box { background: #e8f4fd; border: 1px solid #b3d9f2; border-radius: 6px; padding: 14px; margin: 10px 0; }
|
||
ul, ol { padding-right: 22px; margin-bottom: 10px; }
|
||
li { margin-bottom: 5px; }
|
||
.footer { margin-top: 50px; padding-top: 15px; border-top: 2px solid #eee; text-align: center; color: #999; font-size: 0.85em; }
|
||
.kbd { background: #eee; border: 1px solid #ccc; border-radius: 3px; padding: 2px 6px; font-family: monospace; }
|
||
.section-num { color: #e94560; font-weight: bold; }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<!-- ===== صفحه عنوان ===== -->
|
||
<div class="cover page-break">
|
||
<h1>X121 XReplay</h1>
|
||
<div class="subtitle">ابزار پخش مجدد کندل‌ها در متاتریدر ۵</div>
|
||
<div class="subtitle" style="color:#e94560;">TradingView-Style Candle Replay Tool for MetaTrader 5</div>
|
||
<div class="meta">
|
||
<p><strong>نسخه:</strong> 1.00</p>
|
||
<p><strong>توسعه‌دهنده:</strong> هادی خزاعی اصل</p>
|
||
<p><strong>شرکت:</strong> فن آوران ساحر علم</p>
|
||
<p><strong>SaherElm IT Center</strong></p>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- ===== بخش ۱: نیازمندی ===== -->
|
||
<div class="page-break">
|
||
<h1><span class="section-num">۱.</span> شرح نیازمندی</h1>
|
||
|
||
<h2>۱.۱ مسئله</h2>
|
||
<p>
|
||
معامله‌گران برای تمرین و بک‌تست دستی استراتژی‌های خود به ابزاری نیاز دارند که بتواند
|
||
کندل‌های بازار را از یک نقطه زمانی مشخص پنهان کند و سپس به‌صورت تدریجی
|
||
(کندل به کندل) آن‌ها را نمایش دهد. این قابلیت در پلتفرم TradingView با نام
|
||
<strong>Bar Replay</strong> وجود دارد، اما در MetaTrader 5 به‌صورت پیش‌فرض
|
||
در دسترس نیست.
|
||
</p>
|
||
|
||
<h2>۱.۲ نیازمندی‌های عملکردی</h2>
|
||
<table>
|
||
<tr><th>#</th><th>نیازمندی</th><th>توضیح</th></tr>
|
||
<tr><td>۱</td><td>پنهان‌سازی کندل‌ها</td><td>کندل‌های بعد از نقطه cutoff باید از دید کاربر پنهان شوند</td></tr>
|
||
<tr><td>۲</td><td>نمایش تدریجی</td><td>امکان نمایش کندل‌ها یکی‌یکی با دکمه یا کیبورد</td></tr>
|
||
<tr><td>۳</td><td>پخش خودکار</td><td>امکان پخش خودکار کندل‌ها با سرعت قابل تنظیم</td></tr>
|
||
<tr><td>۴</td><td>بازنشانی</td><td>امکان بازگشت به نقطه شروع با یک کلیک</td></tr>
|
||
<tr><td>۵</td><td>تغییر تایم‌فریم</td><td>حفظ وضعیت Replay هنگام تغییر تایم‌فریم چارت</td></tr>
|
||
<tr><td>۶</td><td>بازیابی خودکار</td><td>بازیابی خودکار حالت چارت پس از حذف اندیکاتور</td></tr>
|
||
</table>
|
||
|
||
<h2>۱.۳ محدودیت‌های فنی MQL5</h2>
|
||
<ul>
|
||
<li>امکان حذف یا پنهان‌سازی مستقیم کندل‌های واقعی وجود ندارد</li>
|
||
<li>اندیکاتور نمی‌تواند داده‌های تاریخی را تغییر دهد</li>
|
||
<li>مدیریت رویدادهای چارت محدود به <code>OnChartEvent</code> است</li>
|
||
<li>ذخیره‌سازی وضعیت بین جلسات نیازمند Global Variables یا فایل است</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<!-- ===== بخش ۲: معرفی ابزار ===== -->
|
||
<div class="page-break">
|
||
<h1><span class="section-num">۲.</span> معرفی ابزار</h1>
|
||
|
||
<h2>۲.۱ مشخصات کلی</h2>
|
||
<table>
|
||
<tr><th>مشخصه</th><th>مقدار</th></tr>
|
||
<tr><td>نام</td><td><code>X121 XReplay</code></td></tr>
|
||
<tr><td>نوع</td><td>اندیکاتور (Indicator)</td></tr>
|
||
<tr><td>پلتفرم</td><td>MetaTrader 5 (MQL5)</td></tr>
|
||
<tr><td>نسخه</td><td>1.00</td></tr>
|
||
<tr><td>فایل</td><td><code>x-saherelm.x121.x-reply.mq5</code></td></tr>
|
||
<tr><td>مسیر نصب</td><td><code>MQL5/Indicators/</code></td></tr>
|
||
<tr><td>وابستگی</td><td><code>x-saherelm.common.lib.mq5</code></td></tr>
|
||
<tr><td>توسعه‌دهنده</td><td>هادی خزاعی اصل</td></tr>
|
||
<tr><td>شرکت</td><td>فن آوران ساحر علم (SaherElm IT Center)</td></tr>
|
||
</table>
|
||
|
||
<h2>۲.۲ روش کار</h2>
|
||
<p>
|
||
ابزار از روش <strong>DRAW_COLOR_CANDLES</strong> با ۵ بافر برای رسم کندل‌ها استفاده می‌کند.
|
||
کندل‌های واقعی چارت با تغییر استایل چارت (تبدیل رنگ‌ها به <code>CLR_NONE</code>)
|
||
پنهان می‌شوند و کندل‌های Replay توسط بافرهای اندیکاتور رسم می‌شوند.
|
||
</p>
|
||
|
||
<h2>۲.۳ بافرها</h2>
|
||
<table>
|
||
<tr><th>بافر</th><th>نوع</th><th>کاربرد</th></tr>
|
||
<tr><td><code>pBarOpenBuffer</code></td><td>INDICATOR_DATA</td><td>قیمت Open</td></tr>
|
||
<tr><td><code>pBarHighBuffer</code></td><td>INDICATOR_DATA</td><td>قیمت High</td></tr>
|
||
<tr><td><code>pBarLowBuffer</code></td><td>INDICATOR_DATA</td><td>قیمت Low</td></tr>
|
||
<tr><td><code>pBarCloseBuffer</code></td><td>INDICATOR_DATA</td><td>قیمت Close</td></tr>
|
||
<tr><td><code>pBarColorBuffer</code></td><td>INDICATOR_COLOR_INDEX</td><td>ایندکس رنگ کندل</td></tr>
|
||
</table>
|
||
|
||
<h2>۲.۴ ایندکس‌های رنگ</h2>
|
||
<table>
|
||
<tr><th>ایندکس</th><th>نام</th><th>کاربرد</th></tr>
|
||
<tr><td>0</td><td><code>hideColorIDX</code></td><td>کندل پنهان (CLR_NONE)</td></tr>
|
||
<tr><td>1</td><td><code>bullishColorIDX</code></td><td>کندل صعودی (clrDodgerBlue)</td></tr>
|
||
<tr><td>2</td><td><code>bearishColorIDX</code></td><td>کندل نزولی (clrDarkOrange)</td></tr>
|
||
<tr><td>3</td><td><code>neuturalColorIDX</code></td><td>کندل خنثی</td></tr>
|
||
</table>
|
||
|
||
<h2>۲.۵ پارامترهای ورودی</h2>
|
||
<table>
|
||
<tr><th>گروه</th><th>پارامتر</th><th>پیش‌فرض</th><th>توضیح</th></tr>
|
||
<tr><td rowspan="2">Replay Settings</td><td><code>startBar</code></td><td>20</td><td>تعداد کندل‌های cutoff</td></tr>
|
||
<tr><td><code>autoPlaySpeed</code></td><td>1000</td><td>سرعت پخش خودکار (ms)</td></tr>
|
||
<tr><td rowspan="4">Presentation</td><td><code>panelButtonTextColor</code></td><td>clrYellow</td><td>رنگ متن دکمه‌ها</td></tr>
|
||
<tr><td><code>panelBackgroundColor</code></td><td>clrBlack</td><td>رنگ پس‌زمینه پنل</td></tr>
|
||
<tr><td><code>infoColor</code></td><td>clrWhite</td><td>رنگ متن اطلاعات</td></tr>
|
||
<tr><td><code>infoPanelBorderColor</code></td><td>clrBlack</td><td>رنگ حاشیه پنل</td></tr>
|
||
</table>
|
||
|
||
<h2>۲.۶ کنترل‌ها</h2>
|
||
<table>
|
||
<tr><th>دکمه</th><th>متن</th><th>عملکرد</th><th>کیبورد</th></tr>
|
||
<tr><td>Prev</td><td><code>|<</code></td><td>یک کندل به عقب</td><td><span class="kbd">←</span> / <span class="kbd">↓</span></td></tr>
|
||
<tr><td>Play</td><td><code>></code></td><td>شروع پخش خودکار</td><td><span class="kbd">Space</span></td></tr>
|
||
<tr><td>Pause</td><td><code>||</code></td><td>توقف پخش</td><td><span class="kbd">Space</span></td></tr>
|
||
<tr><td>Next</td><td><code>>|</code></td><td>یک کندل به جلو</td><td><span class="kbd">→</span> / <span class="kbd">↑</span></td></tr>
|
||
<tr><td>Reset</td><td><code>R</code></td><td>بازنشانی به نقطه شروع</td><td><span class="kbd">R</span></td></tr>
|
||
</table>
|
||
</div>
|
||
|
||
<!-- ===== بخش ۳: معماری ===== -->
|
||
<div class="page-break">
|
||
<h1><span class="section-num">۳.</span> معماری فنی</h1>
|
||
|
||
<h2>۳.۱ ساختار فایل</h2>
|
||
<table>
|
||
<tr><th>بخش</th><th>محتوا</th></tr>
|
||
<tr><td><code>#region Imports</code></td><td>کتابخانه‌های مورد نیاز</td></tr>
|
||
<tr><td><code>#region Definitions</code></td><td>ثابت‌ها، ساختار XChartStyle، ایندکس‌های رنگ</td></tr>
|
||
<tr><td><code>#region Inputs</code></td><td>پارامترهای ورودی کاربر</td></tr>
|
||
<tr><td><code>#region Buffers</code></td><td>تعریف ۵ بافر و پلات</td></tr>
|
||
<tr><td><code>#region Variables</code></td><td>متغیرهای سراسری</td></tr>
|
||
<tr><td><code>#region Event Handlers</code></td><td>OnInit، OnDeinit، OnCalculate، OnTimer، OnChartEvent</td></tr>
|
||
<tr><td><code>#region Custm Functions</code></td><td>توابع کمکی و اعتبارسنجی</td></tr>
|
||
<tr><td><code>#region Value Calculators</code></td><td>محاسبه مقادیر بافرها</td></tr>
|
||
<tr><td><code>#region Chart Style</code></td><td>مدیریت استایل چارت</td></tr>
|
||
<tr><td><code>#region UI</code></td><td>پنل کنترل و دکمه‌ها</td></tr>
|
||
<tr><td><code>#region Control Actions</code></td><td>اکشن‌های پخش</td></tr>
|
||
<tr><td><code>#region TimeFrame Change</code></td><td>مدیریت تغییر تایم‌فریم</td></tr>
|
||
</table>
|
||
|
||
<h2>۳.۲ ساختار XChartStyle</h2>
|
||
<p>این ساختار ۲۱ فیلد دارد و برای ذخیره و بازیابی کامل حالت چارت استفاده می‌شود:</p>
|
||
<table>
|
||
<tr><th>دسته</th><th>فیلدها</th></tr>
|
||
<tr><td>شناسایی</td><td>chartId, mode</td></tr>
|
||
<tr><td>نمایش</td><td>showBidLine, showAskLine, showGrid, showVolumes, showTradeLevels, autoScroll, quickNavigation</td></tr>
|
||
<tr><td>رنگ‌ها</td><td>foreGroundColor, backGroundColor, upColor, downColor, bullishColor, bearishColor, gridColor, bidLineColor, askLineColor, lineColor, stopColor, volumesColor</td></tr>
|
||
</table>
|
||
|
||
<h2>۳.۳ مکانیزم پنهان‌سازی</h2>
|
||
<div class="flow-box">
|
||
<ol>
|
||
<li><strong>ReadChartStyle:</strong> خواندن حالت فعلی چارت و ذخیره در <code>xReplyChartStyle</code></li>
|
||
<li><strong>SaveChartStyleToFile:</strong> ذخیره در فایل باینری با <code>FileWriteStruct</code></li>
|
||
<li><strong>ساخت clearStyle:</strong> کپی از حالت اصلی با رنگ‌های <code>CLR_NONE</code></li>
|
||
<li><strong>HideBars:</strong> اعمال <code>clearStyle</code> بر چارت → کندل‌های واقعی نامرئی می‌شوند</li>
|
||
</ol>
|
||
</div>
|
||
|
||
<h2>۳.۴ مکانیزم رسم کندل‌های Replay</h2>
|
||
<div class="flow-box">
|
||
<ol>
|
||
<li><strong>OnCalculate:</strong> پر کردن بافرهای OHLC از داده‌های واقعی</li>
|
||
<li><strong>UpdateVisibleColors:</strong> تنظیم رنگ بافر بر اساس وضعیت Replay</li>
|
||
<li>کندل‌های قبل از cutoff → رنگ عادی (صعودی/نزولی)</li>
|
||
<li>کندل‌های بعد از cutoff → <code>hideColorIDX</code> (پنهان)</li>
|
||
<li>کندل‌های قابل نمایش Replay → رنگ عادی (صعودی/نزولی)</li>
|
||
</ol>
|
||
</div>
|
||
|
||
<h2>۳.۵ مدیریت تغییر تایم‌فریم</h2>
|
||
<div class="flow-box">
|
||
<p><strong>هنگام تغییر تایم‌فریم (OnDeinit با REASON_CHARTCHANGE):</strong></p>
|
||
<ol>
|
||
<li>محاسبه ایندکس آخرین کندل نمایش داده شده</li>
|
||
<li>ذخیره زمان آن کندل در Global Variable</li>
|
||
<li>ذخیره وضعیت فعال بودن در Global Variable</li>
|
||
<li>ذخیره تعداد کندل‌های قابل نمایش در Global Variable</li>
|
||
</ol>
|
||
<p><strong>در تایم‌فریم جدید (OnInit):</strong></p>
|
||
<ol>
|
||
<li>بررسی وجود Global Variables</li>
|
||
<li>یافتن اولین کندل در تایم‌فریم جدید که شامل زمان ذخیره‌شده است</li>
|
||
<li>تنظیم <code>xReplyStartBarIndex</code> بر اساس کندل یافت‌شده</li>
|
||
<li>بازیابی تعداد کندل‌های قابل نمایش</li>
|
||
<li>حذف Global Variables</li>
|
||
</ol>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- ===== بخش ۴: فرآیند انجام کار ===== -->
|
||
<div class="page-break">
|
||
<h1><span class="section-num">۴.</span> فرآیند و مراحل انجام کار</h1>
|
||
|
||
<h2>۴.۱ خلاصه مراحل توسعه</h2>
|
||
<table>
|
||
<tr><th>مرحله</th><th>شرح</th><th>نتیجه</th></tr>
|
||
<tr><td>۱</td><td>تحلیل نیازمندی و بررسی محدودیت‌های MQL5</td><td>شناسایی روش پنهان‌سازی</td></tr>
|
||
<tr><td>۲</td><td>طراحی معماری با DRAW_COLOR_CANDLES</td><td>تعریف ۵ بافر و ۴ رنگ</td></tr>
|
||
<tr><td>۳</td><td>پیاده‌سازی مدیریت Chart Style</td><td>ساختار XChartStyle با ۲۱ فیلد</td></tr>
|
||
<tr><td>۴</td><td>پیاده‌سازی ذخیره/بازیابی فایل باینری</td><td>FileWriteStruct / FileReadStruct</td></tr>
|
||
<tr><td>۵</td><td>پیاده‌سازی پنل UI و کنترل‌ها</td><td>۵ دکمه + برچسب اطلاعات</td></tr>
|
||
<tr><td>۶</td><td>پیاده‌سازی میانبرهای کیبورد</td><td>Arrow Keys + Space + R</td></tr>
|
||
<tr><td>۷</td><td>پیاده‌سازی تایمر و پخش خودکار</td><td>StartTimer / StopTimer</td></tr>
|
||
<tr><td>۸</td><td>پیاده‌سازی مدیریت تغییر تایم‌فریم</td><td>Global Variables</td></tr>
|
||
<tr><td>۹</td><td>بهینه‌سازی و تست نهایی</td><td>نسخه 1.00</td></tr>
|
||
</table>
|
||
|
||
<h2>۴.۲ تصمیمات فنی کلیدی</h2>
|
||
<table>
|
||
<tr><th>تصمیم</th><th>دلیل</th></tr>
|
||
<tr><td>استفاده از DRAW_COLOR_CANDLES</td><td>کارآمدترین روش رسم کندل در MQL5 بدون ایجاد اشیاء گرافیکی</td></tr>
|
||
<tr><td>پنهان‌سازی با CLR_NONE</td><td>تنها روش ممکن برای نامرئی کردن کندل‌های واقعی بدون حذف آن‌ها</td></tr>
|
||
<tr><td>ذخیره Chart Style در فایل باینری</td><td>بازیابی خودکار پس از حذف اندیکاتور یا کرش ترمینال</td></tr>
|
||
<tr><td>Global Variables برای تایم‌فریم</td><td>حفظ وضعیت بین OnDeinit و OnInit هنگام تغییر تایم‌فریم</td></tr>
|
||
<tr><td>تایمر فقط در حالت Play</td><td>بهینه‌سازی مصرف CPU در حالت Pause</td></tr>
|
||
</table>
|
||
|
||
<h2>۴.۳ ساختار کدنویسی</h2>
|
||
<p>کد بر اساس دستخط کدنویسی شرکت فن آوران ساحر علم نوشته شده است:</p>
|
||
<ul>
|
||
<li>بلوک‌بندی با <code>#region</code> / <code>#endregion</code></li>
|
||
<li>کامنت‌های ساختاریافته با <code>//</code></li>
|
||
<li>پیشوند <code>xReply</code> برای متغیرهای مربوط به Replay</li>
|
||
<li>توابع استاندارد: <code>ValidateInputs</code>، <code>InitRequirements</code>، <code>DefineBuffers</code>، <code>SetIndicatorName</code></li>
|
||
<li>مدیریت خطا با الگوی <code>has</code> / <code>result</code></li>
|
||
<li>پاکسازی منابع در <code>OnDeinit</code></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<!-- ===== بخش ۵: راهنمای استفاده ===== -->
|
||
<div class="page-break">
|
||
<h1><span class="section-num">۵.</span> راهنمای استفاده</h1>
|
||
|
||
<h2>۵.۱ نصب</h2>
|
||
<ol>
|
||
<li>فایل <code>x-saherelm.x121.x-reply.mq5</code> را در مسیر <code>MQL5/Indicators/</code> قرار دهید</li>
|
||
<li>در MetaEditor با <span class="kbd">F7</span> کامپایل کنید</li>
|
||
<li>اندیکاتور را از Navigator روی چارت بکشید</li>
|
||
<li>پارامتر <code>startBar</code> را تنظیم کنید (تعداد کندل‌های cutoff)</li>
|
||
</ol>
|
||
|
||
<h2>۵.۲ استفاده</h2>
|
||
<ul>
|
||
<li>با <span class="kbd">→</span> یا <span class="kbd">↑</span> یک کندل به جلو بروید</li>
|
||
<li>با <span class="kbd">←</span> یا <span class="kbd">↓</span> یک کندل به عقب برگردید</li>
|
||
<li>با <span class="kbd">Space</span> پخش خودکار را شروع/متوقف کنید</li>
|
||
<li>با <span class="kbd">R</span> به نقطه شروع برگردید</li>
|
||
<li>تایم‌فریم را آزادانه تغییر دهید — وضعیت حفظ می‌شود</li>
|
||
</ul>
|
||
|
||
<h2>۵.۳ حذف</h2>
|
||
<p>
|
||
با حذف اندیکاتور از چارت، حالت چارت به‌طور خودکار بازیابی می‌شود،
|
||
فایل Chart Style حذف می‌شود و اشیاء UI پاک می‌شوند.
|
||
</p>
|
||
|
||
<div class="success">
|
||
<strong>✅ نکته:</strong> در صورت کرش ترمینال، فایل Chart Style باقی می‌ماند و در اجرای بعدی
|
||
به‌جای خواندن از چارت، از فایل خوانده می‌شود. این تضمین می‌کند که حالت چارت همیشه درست بازیابی شود.
|
||
</div>
|
||
</div>
|
||
|
||
<!-- ===== فوتر ===== -->
|
||
<div class="footer page-break">
|
||
<h2 style="border:none; text-align:center; padding:0;">پایان سند</h2>
|
||
<br>
|
||
<p><strong>X121 XReplay</strong> — نسخه 1.00</p>
|
||
<p>توسعه‌دهنده: هادی خزاعی اصل</p>
|
||
<p>فن آوران ساحر علم | SaherElm IT Center</p>
|
||
<br>
|
||
<p style="color:#aaa; font-size:0.9em;">© تمامی حقوق محفوظ است</p>
|
||
</div>
|
||
|
||
</body>
|
||
</html> |