Metadata-Version: 2.4
Name: vibeUI
Version: 3.0.0
Summary: A beginner-friendly Python framework for building desktop applications, on top of Tkinter
Author-email: Samarth Chugh <iforgot3360@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Sam3360/VibeUI
Project-URL: Documentation, https://github.com/Sam3360/VibeUI#readme
Project-URL: Repository, https://github.com/Sam3360/VibeUI
Project-URL: Bug Tracker, https://github.com/Sam3360/VibeUI/issues
Project-URL: Changelog, https://github.com/Sam3360/VibeUI/blob/main/CHANGELOG.md
Keywords: gui,tkinter,beginner,education,ui,widgets,desktop,framework,reactive
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Education
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: images
Requires-Dist: pillow>=9.0; extra == "images"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# vibeUI

**vibeUI** is a beginner-friendly Python framework for building desktop applications, on top of Tkinter.

- **v1**: Make Tkinter easier.
- **v2**: Make Tkinter modern.
- **v3**: Make building desktop applications *pleasant*.

No pixel math, no `StringVar` juggling, no theming headaches — just describe what you want.

```python
import vibe as vi

win = vi.Window("My App", theme="dark", accent="#7c6cf5")

name = vi.State("world")
win.add_label(text=lambda: f"Hello, {name.value}!", size="xl", bold=True)
win.add_input(value=name)

with win.row():
    win.add_button("Say hi", on_click=lambda: vi.alert(f"Hi {name.value}!"))
    win.add_button("Reset", variant="secondary", on_click=lambda: name.set("world"))

win.run()
```

---

## Why vibeUI over raw Tkinter?

Raw Tkinter makes you: place widgets with manual `x, y` coordinates or juggle
`pack`/`grid`/`place` yourself; manage `StringVar`/`BooleanVar`/`DoubleVar`
plumbing for every input; hand-roll hover states and theming; and write your
own validation, notifications, and dialogs from scratch. vibeUI does all of
that for you, while still being *Tkinter* underneath — no new runtime, no
heavy dependencies, and an escape hatch (`.widget`) to raw Tkinter whenever
you need it.

## Installation

```bash
pip install vibeUI
```

Optional, for resizable/JPEG images (`add_image(..., width=..., height=...)`):

```bash
pip install "vibeUI[images]"
```

Tkinter ships with most Python installs. On some Linux distros you may need
`sudo apt install python3-tk` first.

## Quick Start

```python
import vibe as vi

win = vi.Window("Vibe Demo", size=(500, 400), theme="dark", accent="#7c6cf5")

win.add_label("Hello, Vibe!", size="xl", bold=True)
name = win.add_input("Enter your name")

def greet():
    vi.alert(f"Hello {name.get() or 'friend'}!", title="Greeting")

win.add_button("Greet Me", on_click=greet)
win.run()
```

Run any of the bundled examples:

```bash
python examples/hello_world.py
python examples/dashboard.py
python examples/state_demo.py
```

See `examples/` for: `hello_world`, `calculator`, `login`, `settings`, `todo`,
`dashboard`, `form`, `file_manager`, `chat`, `theme_demo`, `responsive_demo`,
`state_demo`.

---

## Layout

Widgets stack automatically. Group them with `row()`, `column()`, `grid()`,
`card()`, `sidebar()`, `navbar()`, `modal()`, or `accordion()`:

```python
with win.row(gap=12, align="center"):
    win.add_button("Save")
    win.add_button("Cancel")

with win.grid(columns=3, gap=12):
    for i in range(6):
        with win.card(title=f"Item {i}"):
            win.add_label("...")
```

Full reference: [`docs/layout.md`](docs/layout.md).

## Reactive state

```python
count = vi.State(0)
win.add_label(text=lambda: f"Clicked {count.value} times")
win.add_button("+1", on_click=lambda: count.set(count.value + 1))
```

Labels re-render automatically when a `State` they read changes; inputs,
checkboxes, sliders, and dropdowns support two-way `value=state` binding.
Full reference: [`docs/state.md`](docs/state.md).

## Theming

```python
vi.create_theme(name="cyber", background="#0b0b0f", surface="#15151c",
                 text="#ffffff", accent="#00ffcc")
win.set_theme("cyber")   # every widget re-colors instantly, no restart
```

Built-in: `light`, `dark`, `ocean`. Full reference: [`docs/themes.md`](docs/themes.md).

## Forms & validation

```python
form = vi.Form()
email = win.add_input("Email")
form.add_field("email", email, required=True, pattern=r".+@.+\..+")

if form.is_valid():
    ...
else:
    print(form.errors)
```

## Widgets

Labels, headings, buttons (4 variants + icons), text inputs & search inputs
(with real placeholders and password masking), text areas, checkboxes,
switches, radio groups, sliders, spinboxes, dropdowns/comboboxes, listboxes,
a simple data table, progress bars, images, links, badges, tooltips, tabs, a
menu bar, and a status bar. Every interactive widget returns a consistent
wrapper with `.get()`/`.set()`/`.on_change(...)`. Full reference:
[`docs/widgets.md`](docs/widgets.md).

## Dialogs & notifications

`vi.alert()`, `vi.confirm()`, `vi.prompt()`, `vi.choose_file()`,
`vi.choose_folder()`, `vi.save_file()`, `vi.pick_color()`, and a non-blocking,
stacking `vi.toast(message, type="success")` (`info`/`success`/`warning`/`error`).

## Keyboard shortcuts

```python
win.bind_shortcut("Ctrl+S", save)
win.bind_shortcut("Escape", win.close)
```

## Window management

```python
win.center(); win.maximize(); win.minimize(); win.fullscreen()
win.set_min_size(400, 300); win.on_close(confirm_before_closing)
```

## Custom widgets

```python
class RatingStars(vi.Widget):
    def build(self, container, theme):
        ...  # build your Tkinter widget tree, return the outer widget

win.add_widget(RatingStars())
```

Full guide: [`docs/custom_widgets.md`](docs/custom_widgets.md).

## Debugging layouts

```python
win.debug_layout()   # outlines every container so you can see how things nest
```

Off by default; never affects a shipped app unless you call it yourself.

---

## Cross-platform support

vibeUI targets Windows, macOS, and Linux — anywhere Tkinter runs. Window
management methods (`maximize`, `fullscreen`, etc.) use platform-appropriate
Tk calls with graceful fallbacks where window managers differ (notably
`maximize()` on some Linux window managers). If you hit a platform-specific
issue, please open an issue with your OS and Python version.

## Optional dependencies

vibeUI's only hard requirement is Python's standard library (Tkinter). The
`images` extra (`pip install vibeUI[images]`) adds [Pillow](https://python-pillow.org/)
for image resizing and broader format support — without it, `add_image()`
still works for PNG/GIF via Tkinter's built-in `PhotoImage`.

## Migrating from v2

See [`docs/migration_v2.md`](docs/migration_v2.md) — almost everything is
backward compatible; the few breaking changes are documented there.

## Testing

```bash
pip install pytest
pytest                    # Windows/macOS with a desktop session
xvfb-run -a pytest         # Linux without a display
```

## License

vibeUI is released under the MIT License.

## Author

Created and maintained by **Samarth Chugh** ([@Sam3360](https://github.com/Sam3360)).
