Metadata-Version: 2.4
Name: qjalalicalendarwidget
Version: 0.2.3
Summary: A modern Jalali (Persian) calendar widget for PySide6
Author: Reza
License: MIT License
        
        Copyright (c) 2026 Reza
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.9
Requires-Dist: jdatetime>=4.0
Dynamic: license-file

# 📅 QJalaliCalendarWidget

> A modern, fully RTL-ready Jalali (Persian) calendar widget for PySide6\
> <span dir="rtl">ویجت تقویم جلالی حرفه‌ای و قابل شخصی‌سازی برای PySide6</span>

![PyPI](https://img.shields.io/pypi/v/qjalalicalendarwidget) ![Python Version](https://img.shields.io/pypi/pyversions/qjalalicalendarwidget) ![License](https://img.shields.io/pypi/l/qjalalicalendarwidget) ![Downloads](https://img.shields.io/pypi/dm/qjalalicalendarwidget) ![GitHub stars](https://img.shields.io/github/stars/reza-rezvani2052/QJalaliCalendarWidget) ![GitHub issues](https://img.shields.io/github/issues/reza-rezvani2052/QJalaliCalendarWidget)

## ✨ Quick Preview

![QJalaliCalendarWidget Screenshot](https://raw.githubusercontent.com/reza-rezvani2052/QJalaliCalendarWidget/master/docs/screenshot.png)

------------------------------------------------------------------------

## ❓ Why QJalaliCalendarWidget? | چرا این پروژه؟

### 🇬🇧 English

Qt does not provide a built-in Jalali (Persian) calendar widget.  
Developers often need to implement custom solutions from scratch.

**QJalaliCalendarWidget** fills this gap by providing a modern, customizable, and production-ready Jalali calendar component for PySide6 applications.

### 🇮🇷 فارسی

<div dir="rtl">
Qt به‌صورت پیش‌فرض ویجتی برای تقویم جلالی (شمسی) ارائه نمی‌دهد و توسعه‌دهندگان معمولاً مجبورند این قابلیت را از ابتدا پیاده‌سازی کنند.

پروژه **QJalaliCalendarWidget** این خلأ را با ارائه یک ویجت تقویم جلالی مدرن، قابل شخصی‌سازی و آماده استفاده در محیط‌های
واقعی (Production) برای PySide6 برطرف می‌کند.
</div>

------------------------------------------------------------------------

## 🔄 Compared to QCalendarWidget | مقایسه با QCalendarWidget

### 🇬🇧 English

While Qt provides `QCalendarWidget`, it is primarily designed for the Gregorian calendar and lacks native Jalali (Persian) support.

**QJalaliCalendarWidget** is not just a visual modification — it is built with a fully Jalali-based internal logic and
tailored specifically for Persian applications.

Key differences:

- ✅ Fully Jalali-based date system (not a conversion layer)
- ✅ Native RTL layout design
- ✅ Persian digit rendering support
- ✅ Integrated with `jdatetime`
- ✅ Customizable month & weekday names
- ✅ Designed specifically for Persian user experience

---

### 🇮🇷 فارسی

<div dir="rtl">

اگرچه Qt ویجتی به نام `QCalendarWidget` ارائه می‌دهد، اما این ویجت بر پایه تقویم میلادی طراحی شده و پشتیبانی بومی از
تقویم جلالی (شمسی) ندارد.

ویجت QJalaliCalendarWidget صرفاً یک تغییر ظاهری نیست؛ بلکه بر پایه منطق داخلی کاملاً جلالی توسعه داده شده و به‌طور ویژه
برای اپلیکیشن‌های فارسی طراحی شده است.

تفاوت‌های کلیدی:

- ✅ سیستم تاریخ کاملاً جلالی (نه صرفاً تبدیل از میلادی)
- ✅ طراحی بومی راست‌به‌چپ (RTL)
- ✅ پشتیبانی از نمایش اعداد فارسی
- ✅ یکپارچه با `jdatetime`
- ✅ امکان شخصی‌سازی نام ماه‌ها و روزهای هفته
- ✅ طراحی شده با تمرکز بر تجربه کاربری فارسی

</div>

------------------------------------------------------------------------

## 🌟 Features \| ویژگی‌ها

### 🇬🇧 English

- ✅ Jalali (Persian) calendar support\
- ✅ Built with **PySide6**
- ✅ Right-to-left (RTL) layout support
- ✅ Customizable theme colors
- ✅ Persian / English digit modes
- ✅ Keyboard navigation
- ✅ Date range restriction (min/max)
- ✅ Custom month & weekday names
- ✅ Qt-style signals compatible with QCalendarWidget
- ✅ Modern UI design

------------------------------------------------------------------------

### 🇮🇷 فارسی

<div dir="rtl">

- ✅ پشتیبانی کامل از تقویم جلالی (شمسی)
- ✅ توسعه داده شده با PySide6
- ✅ پشتیبانی کامل از راست‌به‌چپ (RTL)
- ✅ قابلیت شخصی‌سازی رنگ‌ها (تم)
- ✅ نمایش اعداد فارسی یا انگلیسی
- ✅ ناوبری با کیبورد
- ✅ محدودسازی بازه تاریخ (حداقل/حداکثر)
- ✅ امکان تغییر نام ماه‌ها و روزهای هفته
- ✅ سیگنال‌های مشابه QCalendarWidget
- ✅ طراحی مدرن و تمیز

</div>

------------------------------------------------------------------------

## 📦 Installation \| نصب

``` bash
pip install qjalalicalendarwidget
```

------------------------------------------------------------------------

## 🚀 Basic Usage \| مثال استفاده

``` python
import sys
from PySide6.QtWidgets import QApplication

from qjalalicalendarwidget import QJalaliCalendarWidget

app = QApplication(sys.argv)


def on_date_confirmed(selected_date):
    print(selected_date.strftime("%Y/%m/%d"))
    app.quit()


def move_to_center(calendar):
    from PySide6.QtGui import QGuiApplication

    calendar.adjustSize()

    # --- Center of Screen ---
    screen = QGuiApplication.primaryScreen()
    screen_geometry = screen.availableGeometry()

    calendar.resize(calendar.sizeHint())
    x = (screen_geometry.width() - calendar.width()) // 2
    y = (screen_geometry.height() - calendar.height()) // 2

    calendar.move(x, y)


calendar = QJalaliCalendarWidget()
calendar.confirmed.connect(on_date_confirmed)

move_to_center(calendar)
calendar.show()

sys.exit(app.exec())
```

------------------------------------------------------------------------

## 🎨 Customization \| شخصی‌سازی

### Change Digit Mode \| تغییر حالت اعداد

``` python
calendar.setDigitMode("fa")  # Persian digits
calendar.setDigitMode("en")  # English digits
```

------------------------------------------------------------------------

### Set Date Range \| تعیین بازه تاریخ

``` python
import jdatetime

calendar.setMinimumDate(jdatetime.date(1403, 1, 1))
calendar.setMaximumDate(jdatetime.date(1404, 12, 29))
```

------------------------------------------------------------------------

### Customize Theme Colors \| تغییر رنگ‌ها

``` python
calendar.setThemeColors(
    selected_bg="#2e7d32",
    selected_fg="#ffffff",
    today_bg="#e8f5e9",
    friday_fg="#d32f2f"
)
```

------------------------------------------------------------------------

## ⌨ Keyboard Navigation \| ناوبری با کیبورد

| Key                     | Action                    |
|-------------------------|---------------------------|
| ← →                     | Previous / Next day       |
| ↑ ↓                     | Previous / Next week      |
| PageUp / PageDown       | Previous / Next month     |
| Shift + PageUp/PageDown | Previous / Next year      |
| Home / End              | First / Last day of month |
| Enter                   | Confirm selection         |

------------------------------------------------------------------------

## 🔔 Signals \| سیگنال‌ها

``` python
calendar.selectionChanged.connect(...)
calendar.activated.connect(...)
calendar.currentPageChanged.connect(...)
calendar.confirmed.connect(...)
calendar.dateSelected.connect(...)
```

------------------------------------------------------------------------

## 📋 Requirements \| پیش‌نیازها

- Python >= 3.11
- PySide6 >= 6.6
- jdatetime >= 4.1

------------------------------------------------------------------------

## 📄 License \| مجوز

MIT License

------------------------------------------------------------------------

## 🤝 Contributing \| مشارکت

Pull requests are welcome.\
For major changes, please open an issue first.

از پیشنهادها و مشارکت شما استقبال می‌شود.

------------------------------------------------------------------------

## 🔗 Links

- GitHub: https://github.com/reza-rezvani2052/QJalaliCalendarWidget
- PyPI: https://pypi.org/project/qjalalicalendarwidget/

------------------------------------------------------------------------

## ⭐ Support

If you find this project useful, consider giving it a ⭐ on GitHub.
