Metadata-Version: 2.5
Name: material-dialogs
Version: 0.1.2
Summary: A Custom Set of Material Dialogs that uses Google's Material Design System
Project-URL: Homepage, https://github.com/AceBurgundy/Python-Material-Dialogs
Project-URL: Repository, https://github.com/AceBurgundy/Python-Material-Dialogs
Author-email: AceBurgundy <Samadriansabalo99@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: pyqt6>=6.11.0
Requires-Dist: requests>=2.32.5
Provides-Extra: all
Requires-Dist: pytest-mock>=3.15.1; extra == 'all'
Requires-Dist: pytest-qt>=4.5.0; extra == 'all'
Requires-Dist: pytest>=7.0.0; extra == 'all'
Description-Content-Type: text/markdown

# 🎨 Python Material Dialogs 🌟

📱 **A Custom Set of Material Dialogs that uses Google's Material Design System.**

Built specifically for PyQt6, this package brings sleek, modern, and highly customizable pop-up modals to your desktop applications! Whether you need simple confirmations, text input prompts, or scrollable selection lists, Material Dialogs provides an edge-to-edge, beautifully animated, and dynamically scalable UI right out of the box. 🚀

## 📑 Table of Contents

* [📦 Requirements & Installation](https://www.google.com/search?q=%23-requirements--installation)

* [🚀 Core Features](https://www.google.com/search?q=%23-core-features)

* [💻 Quick Start & Usage Examples](https://www.google.com/search?q=%23-quick-start--usage-examples)

* [🎨 The Styling System](https://www.google.com/search?q=%23-the-styling-system)

* [🗂️ Project Architecture](https://www.google.com/search?q=%23%EF%B8%8F-project-architecture)

* [🔗 Links & Repository](https://www.google.com/search?q=%23-links--repository)

* [📜 License](https://www.google.com/search?q=%23-license)

* [👤 Author](https://www.google.com/search?q=%23-author)


## 📦 Requirements & Installation

Before installing, ensure your environment meets the minimum version constraints defined in the `pyproject.toml` configuration:

* **Python (`>= 3.11`):** The core programming language requirement.


* **PyQt6 (`>= 6.11.0`):** The underlying GUI framework used to render the windows.


* **requests (`>= 2.32.5`):** Required for internal web/network operations.



You can easily install the package via `pip`:

```bash
pip install material-dialogs

```

## 🚀 Core Features

* ✅ **Confirmation Dialogs:** Present critical yes/no or confirm/cancel decisions with standard or custom button layouts.


* 📝 **Input Prompts:** Capture user text input with a clean, heavily styled `QLineEdit` that features focus borders.


* 🔘 **Selection Dialogs:** Render choices in a beautifully animated `SmoothScrollArea`. Supports both single-choice buttons and multiple-choice checkboxes.


* 🖌️ **Deep Style Customization:** Fully override surface colors, typography, and button states using `DialogRGB` and `DialogRGBA` classes.


* 📏 **Dynamic UI Scaling:** Instantly bump up your UI layout margins using `DialogPadding` and the new `ScaleType` Enum (supports `S`, `M`, `L`, and `XL` sizing).


* 🔤 **Custom Font Support:** Native fallback sequences for Google Sans, with the ability to load local `.ttf` or `.otf` files on initialization. Typography is now centralized utilizing the `DialogFont` class.



## 💻 Quick Start & Usage Examples

Below is a verbose breakdown of how to utilize the core `MaterialDialogs` singleton and trigger each specific dialog type.

### 1️⃣ Initialization & Setup ⚙️

Import the library and instantiate the singleton. You can pass global styles, a custom font path, or a taskbar icon at this stage.

```python
from material_dialogs import MaterialDialogs

# Initialize the core dialogs singleton
dialog = MaterialDialogs()

```

### 2️⃣ The Delete Confirmation Dialog 🗑️

![Delete Confirmation Dialog](images/delete.png)

Create a dark-themed confirmation popup by passing a custom `DialogStyles` object.

```python
from material_dialogs import DialogStyles, MaterialSurface, DialogTitle, DialogBody, DialogButton, DialogRGB, DialogRGBA

confirmed: bool = dialog.confirm(
    message=(
        "This will delete prompts, responses, and feedback from your Gemini Apps "
        "Activity, plus any content you created.\nLearn More"
    ),
    title="Delete Chat?",
    confirm_text="Delete",
    style=DialogStyles(
        surface=MaterialSurface(
            background_color=DialogRGB(31, 31, 31)
        ),
        # Assuming you want to rely on the default DialogFont sizing but change color
        # You would pass a customized DialogFont object here per the new styles.py architecture
    ),
)

```

### 3️⃣ The Text Input Prompt ⌨️

![Text Input Prompt Dialog](images/input.png)

Prompt the user for simple string data. Note that this raises a `ValueError` if the user submits a blank string or cancels the window!

```python
try:
    name: str = dialog.prompt(
        title="Enter your name",
        initial_content="Alice",
    )
    
    print(f"Welcome, {name}!")
except ValueError as error:
    print(f"Prompt canceled: {error}")

```

### 4️⃣ The Selection Dialog (Optional Multiple Choice) ☑️

![Selection Dialog](images/selection.png)

Render a list of choices using native layout dividers and animated scrolling.

```python
options = ["Python", "JavaScript", "C++", "Rust", "Go", "Java"]

selected = dialog.selection(
    message="What is your favorite programming language?",
    selections=options,
    title="Language Selection",
    optional=True, # Allows the user to confirm without making a choice
)

```

### 5️⃣ Dynamic Scaling (Padding & Fonts) 🔎

![Scaled Dialog](images/scale.png)

Use the layout helper dataclasses to scale up a dialog specifically for accessibility or larger displays. This version has been updated to utilize the `ScaleType` enum and `DialogFont` object.

```python
from material_dialogs import DialogStyles, DialogPadding, ScaleType, DialogTitle, DialogBody, DialogButton, DialogFont, DialogRGB

scaling_confirmed: bool = dialog.confirm(
    title="Extra Large Dialog",
    message="This dialog utilizes the DialogPadding class and ScaleType enum to instantly scale up the layout margins.",
    confirm_text="Looks Good",
    style=DialogStyles(
        padding=DialogPadding(scale=ScaleType.XL),
        title=DialogTitle(
            font=DialogFont(
                families=["Roboto"], size=28, color=DialogRGB(28, 27, 31)
            )
        ),
        body=DialogBody(
            font=DialogFont(
                families=["Roboto"], size=18, color=DialogRGB(73, 69, 79)
            )
        ),
        button=DialogButton(
            font=DialogFont(
                families=["Roboto"], size=16, color=DialogRGB(101, 85, 143)
            )
        )
    )
)

```

## 🎨 The Styling System

Material Dialogs leverages robust Python `dataclasses` to enforce strict type-hinting and easy customization!

* **`MaterialSurface`:** Controls the background card. Available properties: `base_width`, `base_height`, `background_color`, `border_radius`.


* **`DialogFont`:** Centralized typography definition. Available properties: `families`, `size`, `color`, `weight`.


* **`DialogTitle`:** Typography for the header. Available properties: `center_align`, `font`.


* **`DialogBody`:** Typography for the message text. Available properties: `center_align`, `line_height`, `margin_right`, `font`.


* **`DialogButton`:** Styling for confirm/cancel actions. Available properties: `background_color`, `hover_background_color`, `pressed_background_color`, `border_radius`, `padding`, `font`.


* **`DialogInputStyle`:** Configuration for input fields. Available properties: `height`, `background_color`, `font`.


* **`DialogSelectionItemStyle`:** Configuration for selectable items. Available properties: `height`, `background_color`, `font`.


* **`DialogRGB`:** Standard solid colors. Available properties: `red`, `green`, `blue`.


* **`DialogRGBA`:** Colors with opacity for states. Available properties: `red`, `green`, `blue`, `alpha`.


* **`ScaleType`:** Enumerator for scale identifiers. Available properties: `S`, `M`, `L`, `XL`.


* **`DialogPadding`:** Pre-calculated dialog margins. Available properties: `scale` (utilizes `ScaleType`).



## 🗂️ Project Architecture

For contributors, the package is deeply modular and easy to navigate:

* **`__init__.py`:** Handles standard top-level exports.


* **`core.py`:** Manages the application singleton state and central `MaterialDialogs` class.


* **`styles.py`:** Contains all the styling dataclasses, centralized `DialogFont` logic, and `ScaleType` enumerations.


* **`fonts.py`:** Manages QFontDatabase injection and system sequence validations.


* **`dialogs/base.py`:** Generates the dynamic QSS (Qt Style Sheet) string based on properties.


* **`dialogs/confirm.py`:** Logic for Boolean questions.


* **`dialogs/prompt.py`:** Logic for text extraction (`QLineEdit`).


* **`dialogs/selection.py`:** Complex logic handling single vs. multiple choices, `QButtonGroup`, and smooth scrolling.


## 🔗 Links & Repository

* **Homepage & Documentation**: [https://github.com/AceBurgundy/Python-Material-Dialogs](https://www.google.com/search?q=https://github.com/AceBurgundy/Python-Material-Dialogs)

* **Repository & Source Code**: [https://github.com/AceBurgundy/Python-Material-Dialogs](https://www.google.com/search?q=https://github.com/AceBurgundy/Python-Material-Dialogs)


## 📜 License

This project is licensed and distributed under the **Mozilla Public License (MPL)**.

## 👤 Author

* **Name:** AceBurgundy
* **Email:** samadriansabalo99@gmail.com
