# برنامه «قیمت دلار» با Basic4Android (B4A)

برنامه‌ای که **قیمت دلار بازار آزاد** را از tgju.org می‌گیرد، **به تومان** با ارقام فارسی نشان می‌دهد و یک **ویجت صفحه اصلی** هم دارد.

---

## امکانات

- نمایش قیمت دلار بازار آزاد به **تومان** با جداکننده هزارگان و ارقام فارسی (مثلاً `۲۳۶,۵۶۵`)

- نمایش **مقدار و درصد تغییر** روز (▲ سبز / ▼ قرمز)

- **بروزرسانی خودکار هر ۳۰ ثانیه** تا وقتی برنامه باز است + دکمه «بروزرسانی»

- **ویجت صفحه اصلی**: نرخ را روی هوم‌اسکرین نشان می‌دهد؛ خودکار هر ۳۰ دقیقه و با **لمس، فوری** بروزرسانی می‌شود

- آخرین نرخ در حافظه داخلی ذخیره می‌شود، پس برنامه و ویجت حتی بدون اینترنت هم آخرین قیمت را نشان می‌دهند

- ظاهر تیره و راست‌به‌چپ‌پسند، همه متن‌ها فارسی

---

## پیش‌نیازها

| مورد | توضیح |

|---|---|

| B4A | نسخه **۱۲.۸ یا بالاتر** (ویجت با Receiver ساخته شده) |

| کتابخانه‌ها | `Core` و `OkHttpUtils2` — هر دو همراه خود B4A نصب می‌شوند |

| اندروید | گوشی یا شبیه‌ساز با اندروید ۵ و بالاتر |

---

## فایل‌های پروژه

```

DollarPrice/

├── DollarPrice.b4a ← فایل پروژه: کد صفحه اصلی + تنظیمات manifest (منابع ویجت)

├── Starter.bas ← سرویس استاندارد B4A

├── Widget_dollar.bas ← ماژول ویجت (از نوع Receiver)

└── Files/

├── main.bal ← چیدمان صفحه اصلی

└── dollar.bal ← چیدمان ویجت (مبنای شناسه‌ها؛ ظاهر نهایی از XML دست‌نویس داخل manifest می‌آید)

```

---

## اجرا (گام‌به‌گام)

1. کل پوشه `DollarPrice` را روی کامپیوتری که B4A دارد کپی کنید.

2. در B4A: **File ▸ Open** و فایل `DollarPrice.b4a` را باز کنید.

3. (اختیاری) **Project ▸ Build Configurations**: یک `Package name` دلخواه مثل `com.name.dollarprice` بگذارید.

4. برای تست خودِ برنامه، دکمه **Run (F5)** را بزنید. (اجرا با حالت پیش‌فرض Debug هم اوکی است.)

5. ⚠️ **برای تست ویجت حتماً Release بسازید:** از **Project ▸ Build Configurations** حالت **Release** را انتخاب کنید و پروژه را اجرا/کامپایل کنید. طبق مستندات B4A، ویجت در حالت Debug وقتی سیستم خودش پروسه را اجرا می‌کند کار نمی‌کند.

6. اپ را روی گوشی نصب کنید.

---

## افزودن ویجت به صفحه اصلی

1. یک جای خالی از صفحه اصلی را چند ثانیه نگه دارید.

2. **Widgets** را انتخاب کنید و «**قیمت دلار**» را روی صفحه بکشید.

3. هر وقت خواستید نرخ تازه شود، **روی ویجت بزنید**.

---

## نکته‌های مهم

- **تومان یا ریال؟** tgju نرخ «دلار» را **ریال** می‌دهد؛ برنامه آن را تقسیم بر ۱۰ می‌کند و **تومان** نشان می‌دهد.

اگر ریال می‌خواهید: در `DollarPrice.b4a` و `Widget_dollar.bas` عبارت `FormatToman(rial / 10)` را به `FormatToman(rial)` تغییر دهید.

- **بازه بروزرسانی برنامه:** ثابت `REFRESH_MS` در ابتدای ماژول اصلی (پیش‌فرض `30000` میلی‌ثانیه = ۳۰ ثانیه).

- **بازه بروزرسانی ویجت:** اندروید برای بروزرسانی خودکار ویجت‌ها **حداقل ۳۰ دقیقه** را اجازه می‌دهد (عدد `30` در خط `ConfigureHomeWidget`). با لمس ویجت این محدودیت وجود ندارد و نرخ همان لحظه گرفته می‌شود.

- **هماهنگی ویجت با برنامه:** هر بار برنامه نرخ تازه بگیرد، ویجت هم فوراً (اگر برنامه در حال اجرا باشد) با همان نرخ بروزرسانی می‌شود.

- **منبع داده:** `api.tgju.org` (آدرس سبک) و در صورت خطا `call1.tgju.org` به‌عنوان جایگزین.

- **اگر نرخ نیامد:** اتصال اینترنت را بررسی کنید؛ بعضی VPNها/اپراتورها ممکن است به tgju دسترسی ندهند (برنامه پیام خطا نشان می‌دهد و آخرین نرخ ذخیره‌شده را نگه می‌دارد).

---

## توضیح فنی (برای علاقه‌مندان)

- **دریافت نرخ:** درخواست به `https://api.tgju.org/v1/widget/tmp?keys=price_dollar_rl` و خواندن فیلدهای `p` (قیمت ریالی)، `d` (تغییر)، `dp` (درصد) و `t` (ساعت نرخ). چون tgju متن فارسی را به شکل `\uXXXX` می‌فرستد، تابع `DecodeUnicodeEscapes` آن را به فارسی برمی‌گرداند.

- **ویجت:** با یک ماژول از نوع **Receiver** ساخته شده:

```b4x

rv = ConfigureHomeWidget("dollar", "rv", 30, "قیمت دلار", True)

```

و ظاهر آن با **XML دست‌نویس** داخل manifest بازنویسی شده است:

```b4x

CreateResource(xml, widget_dollar_info.xml, ...)

CreateResource(layout, widget_dollar_layout.xml, ...)

CreateResource(drawable, widget_dollar_bg.xml, ...)

```

این تکنیک رسمی انجمن B4X برای ساختن ویجت‌های **واکنش‌گرا (Resizable/Adaptive)** است؛ چون طراحی layout ویجت با Designer محدودیت دارد. با این کار ویجت با هر اندازه‌ای که کاربر تغییر دهد، هماهنگ می‌ماند.

- **قواعد نام‌گذاری B4A:** ماژول `Widget_dollar` ⟶ receiver با نام `.widget_dollar`، منابع `@xml/widget_dollar_info` و `@layout/widget_dollar_layout` و شناسه‌ها `widget_dollar_label1` تا `widget_dollar_label3`. XML دست‌نویس با همین شناسه‌ها نوشته شده تا `rv.SetText("Label2", ...)` درست کار کند.

---

## آیکون برنامه (اختیاری)

B4A آیکون را از `Objects\res\drawable\icon.png` برمی‌دارد، پس:

1. در B4A: **Project ▸ Choose Icon**

2. فایل `site/images/icon-512.png` را انتخاب کنید (B4A اندازه ۵۱۲×۵۱۲ را قبول می‌کند)

3. **Project ▸ Clean** و بعد دوباره کامپایل کنید

> گذاشتن فایل در پوشه `Files` آیکون برنامه را عوض نمی‌کند (فقط یک فایل Asset می‌شود)؛ به همین دلیل آن فایل را از پروژه برداشتم.

> تصویر آیکون در `site/images/icon-512.png` هست (همراه `icon-192`، `icon-64` و `favicon.ico`).

## پوشه `tools` (اختیاری – برای ویرایش چیدمان‌ها)

چون فایل‌های `.bal` فرمت **باینری** دارند، برای تولید/ویرایش برنامه‌نویسی‌شده‌ی آن‌ها این ابزارها را گذاشتم:

| فایل | کار |

|---|---|

| `tools/balcon.py` | پورت پایتونیِ **BalConverter** رسمی B4X؛ تبدیل `.bal` ↔ JSON (خواندن و نوشتن layout باینری B4A) |

| `tools/make_layouts.py` | ساخت دوباره‌ی `main.bal` و `dollar.bal` از روی JSON |

| `tools/layouts/main.json` | نسخه قابل‌ویرایش چیدمان صفحه اصلی |

| `tools/layouts/dollar.json` | نسخه قابل‌ویرایش چیدمان ویجت |

مثال:

```bash

python3 tools/make_layouts.py DollarPrice/Files

python3 tools/balcon.py tojson DollarPrice/Files/main.bal main.json

```

> خروجی نوشتار این ابزار با فایل‌های واقعیِ ساخته‌شده توسط Designer بایت‌به‌بایت یکسان شد (آزمون رفت‌وبرگشت روی چند پروژه نمونه رسمی B4X)، پس فایل‌های `.bal` تولیدشده در B4A باز می‌شوند.