# VGI - Professional Modern GUI Library for Python
VGI (Visual GUI Interface) is a comprehensive, modern GUI framework for Python designed to create stunning, professional desktop applications with ease. Built on top of Tkinter but providing a much more powerful and intuitive API, VGI offers advanced styling, theming, animations, and a rich set of components that rival the best GUI frameworks available.
## Key Features
### Modern Design Philosophy
- **Clean, Modern Interface**: Professional-grade UI components with contemporary design patterns
- **Responsive Layouts**: Flexible layout system that adapts to different screen sizes and resolutions
- **Professional Themes**: Built-in themes including light, dark, and professional styles
- **Customizable Styling**: Comprehensive styling system with CSS-like properties
### Advanced Component Library
- **Rich Widget Set**: Over 30 professionally designed components
- **Input Validation**: Built-in validation system with real-time feedback
- **Data Visualization**: Integrated charting and graphing capabilities
- **Advanced Layouts**: Sophisticated layout managers (VBox, HBox, Grid, Stack)
### Developer Experience
- **Intuitive API**: Simple, consistent interface that's easy to learn and use
- **Event-Driven Architecture**: Robust event handling system
- **Type Safety**: Full type hints for excellent IDE support
- **Comprehensive Documentation**: Extensive examples and tutorials
### Performance & Reliability
- **High Performance**: Optimized rendering and efficient memory usage
- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux
- **Stable Foundation**: Built on proven Tkinter technology with modern enhancements
- **Production Ready**: Suitable for commercial applications
## Installation
### From PyPI (Recommended)
```bash
pip install vgi
```
### From Source
```bash
git clone https://github.com/vgi-team/vgi.git
cd vgi
pip install -e .
```
### Requirements
- Python 3.8 or higher
- Tkinter (usually included with Python)
- Pillow (automatically installed)
- NumPy (automatically installed)
## Quick Start
### Basic Application
```python
import vgi
# Create application
app = vgi.Application(theme="modern_light")
# Create main window
window = app.create_window(title="My VGI App", size=(800, 600))
# Create layout container
container = vgi.VBox(padding=20, spacing=15)
# Add components
title = vgi.Heading1("Welcome to VGI!")
container.add(title)
button = vgi.PrimaryButton(
text="Click Me!",
on_click=lambda: print("Button clicked!")
)
container.add(button)
# Add container to window
window.add_widget(container, fill="both", expand=True)
# Run application
app.run()
```
### Form Example with Validation
```python
import vgi
app = vgi.Application()
window = app.create_window(title="Contact Form", size=(500, 400))
# Create form layout
form = vgi.Grid(columns=2, spacing=10, padding=20)
# Name field
form.add(vgi.Label("Name:"), row=0, column=0, sticky="e")
name_input = vgi.Input(
placeholder="Enter your name",
validator=vgi.Validator().required().min_length(2)
)
form.add(name_input, row=0, column=1, sticky="ew")
# Email field
form.add(vgi.Label("Email:"), row=1, column=0, sticky="e")
email_input = vgi.EmailInput(placeholder="Enter your email")
form.add(email_input, row=1, column=1, sticky="ew")
# Message field
form.add(vgi.Label("Message:"), row=2, column=0, sticky="ne")
message_input = vgi.TextArea(
placeholder="Enter your message...",
validator=vgi.Validator().required().min_length(10)
)
form.add(message_input, row=2, column=1, sticky="ew")
# Buttons
button_container = vgi.HBox(spacing=10)
button_container.add(vgi.SecondaryButton("Cancel"))
button_container.add(vgi.PrimaryButton("Submit"))
form.add(button_container, row=3, column=0, columnspan=2, sticky="e")
# Configure grid
form.set_column_weight(1, 1)
window.add_widget(form, fill="both", expand=True)
app.run()
```
## Core Components
### Layout Containers
#### VBox - Vertical Layout
```python
vbox = vgi.VBox(spacing=10, align="stretch")
vbox.add(vgi.Label("First item"))
vbox.add(vgi.Label("Second item"))
vbox.add(vgi.Button("Third item"), expand=True)
```
#### HBox - Horizontal Layout
```python
hbox = vgi.HBox(spacing=10, align="center")
hbox.add(vgi.Button("Left"))
hbox.add(vgi.Button("Center"), expand=True)
hbox.add(vgi.Button("Right"))
```
#### Grid - Flexible Grid Layout
```python
grid = vgi.Grid(rows=3, columns=3, spacing=5)
grid.add(vgi.Button("1,1"), row=0, column=0)
grid.add(vgi.Button("Span"), row=0, column=1, columnspan=2)
grid.add(vgi.Button("2,1"), row=1, column=0, rowspan=2)
```
#### Stack - Layered Layout
```python
stack = vgi.Stack()
stack.add(vgi.Label("Page 1"), name="page1")
stack.add(vgi.Label("Page 2"), name="page2")
stack.show("page1") # Show specific page
```
### Input Components
#### Basic Input Fields
```python
# Text input with placeholder
text_input = vgi.Input(placeholder="Enter text...")
# Email input with validation
email_input = vgi.EmailInput(placeholder="your@email.com")
# Password input
password_input = vgi.PasswordInput(placeholder="Password")
# Number input with range
number_input = vgi.NumberInput(min_value=0, max_value=100)
# Multi-line text area
text_area = vgi.TextArea(placeholder="Enter message...")
```
#### Input Validation
```python
# Create validator
validator = (vgi.Validator()
.required()
.min_length(8)
.regex(r'.*[A-Z].*', "Must contain uppercase")
.regex(r'.*\d.*', "Must contain number"))
# Apply to input
password_input = vgi.PasswordInput(
placeholder="Secure password",
validator=validator,
on_change=lambda text: print(f"Valid: {password_input.is_valid}")
)
```
### Button Components
#### Button Styles
```python
# Primary button (main action)
primary_btn = vgi.PrimaryButton("Save", on_click=save_data)
# Secondary button (secondary action)
secondary_btn = vgi.SecondaryButton("Cancel", on_click=cancel)
# Outline button (tertiary action)
outline_btn = vgi.OutlineButton("Options", on_click=show_options)
# Danger button (destructive action)
danger_btn = vgi.DangerButton("Delete", on_click=delete_item)
```
#### Button Sizes
```python
small_btn = vgi.Button("Small", size="small")
medium_btn = vgi.Button("Medium", size="medium")
large_btn = vgi.Button("Large", size="large")
```
#### Button States
```python
# Loading state
loading_btn = vgi.Button("Processing...", loading=True)
# Disabled state
disabled_btn = vgi.Button("Disabled", disabled=True)
# With icon (requires icon implementation)
icon_btn = vgi.Button("Save", icon="save", icon_position="left")
```
### Display Components
#### Labels and Text
```python
# Heading levels
h1 = vgi.Heading1("Main Title")
h2 = vgi.Heading2("Section Title")
h3 = vgi.Heading3("Subsection")
# Regular label
label = vgi.Label("Regular text", text_color="#333333")
# Caption text
caption = vgi.Caption("Small descriptive text")
# Clickable link
link = vgi.Link("Click here", on_click=handle_click)
# Wrapped text
wrapped = vgi.Label(
"This is a long text that will wrap automatically",
wrap=True
)
```
#### Containers and Panels
```python
# Basic container
container = vgi.Container(padding=16)
# Styled panel with border
panel = vgi.Panel(title="Settings", border=True, padding=20)
# Simple frame (no styling)
frame = vgi.Frame()
# Scrollable container
scrollable = vgi.Container(scrollable=True, padding=10)
```
## Theming and Styling
### Built-in Themes
```python
# Available themes
app = vgi.Application(theme="modern_light") # Default light theme
app = vgi.Application(theme="modern_dark") # Dark theme
app = vgi.Application(theme="professional") # Professional/corporate theme
# Switch themes at runtime
app.set_theme("modern_dark")
```
### Custom Styling
```python
# Style individual components
button = vgi.Button("Styled Button")
button.set_style(
background_color="#FF6B6B",
text_color="#FFFFFF",
border_radius=8,
padding=(12, 24),
font_weight="bold"
)
# Create custom theme
custom_theme = app.theme_manager.create_custom_theme(
"my_theme",
base_theme="modern_light"
)
custom_theme.set_widget_style("button", "background_color", "#4ECDC4")
app.set_theme("my_theme")
```
### Color System
```python
# Using Color class
primary_color = vgi.Color.from_hex("#007ACC")
darker_primary = primary_color.darken(0.2)
lighter_primary = primary_color.lighten(0.2)
# Color palettes
palette = vgi.ColorPalette.create_material_palette()
dark_palette = vgi.ColorPalette.create_dark_palette()
# Apply palette to theme
theme = vgi.Theme("Custom Theme")
theme.set_palette(palette)
```
## Advanced Features
### Event Handling
```python
class MyHandler:
def __init__(self):
self.button = vgi.Button("Click me")
# Multiple event handlers
self.button.on("clicked", self.on_click)
self.button.on("mouse_enter", self.on_hover)
self.button.on("mouse_leave", self.on_leave)
def on_click(self, event):
print(f"Button {event.source.id} was clicked!")
def on_hover(self, event):
event.source.set_style(background_color="#E3F2FD")
def on_leave(self, event):
event.source.set_style(background_color="#2196F3")
```
### Animation System
```python
# Simple fade in animation
button = vgi.Button("Animated")
fade_in = vgi.Transition.fade_in(button, duration=0.5)
fade_in.start()
# Custom animation
animation = vgi.Animation(
button,
duration=1.0,
x=100,
y=50,
scale_x=1.2,
scale_y=1.2,
easing="ease_out_bounce"
)
animation.start()
# Animation with callbacks
def on_complete(anim):
print("Animation finished!")
pulse = vgi.Transition.pulse(button, duration=0.3)
pulse.on_complete = on_complete
pulse.start()
```
### Data Binding and Validation
```python
# Form with comprehensive validation
class RegistrationForm:
def __init__(self):
self.form = vgi.Grid(columns=2, spacing=10)
# Username with custom validation
self.username = vgi.Input(
placeholder="Username",
validator=vgi.Validator()
.required()
.min_length(3)
.max_length(20)
.regex(r'^[a-zA-Z0-9_]+$', "Only letters, numbers, underscore")
)
# Email validation
self.email = vgi.EmailInput(placeholder="Email address")
# Password with strength requirements
self.password = vgi.PasswordInput(
placeholder="Password",
validator=vgi.Validator.create_password_validator(min_length=8)
)
# Confirm password
self.confirm_password = vgi.PasswordInput(
placeholder="Confirm password",
validator=vgi.Validator().custom(
lambda x: x == self.password.value,
"Passwords must match"
)
)
self.build_form()
def build_form(self):
fields = [
("Username:", self.username),
("Email:", self.email),
("Password:", self.password),
("Confirm:", self.confirm_password)
]
for i, (label, field) in enumerate(fields):
self.form.add(vgi.Label(label), row=i, column=0, sticky="e")
self.form.add(field, row=i, column=1, sticky="ew")
# Submit button - only enabled when all fields valid
submit_btn = vgi.PrimaryButton("Register", on_click=self.submit)
self.form.add(submit_btn, row=len(fields), column=1, sticky="e")
def submit(self):
if all(field.is_valid for field in [self.username, self.email,
self.password, self.confirm_password]):
print("Registration successful!")
else:
print("Please fix validation errors")
```
## Advanced Components
### Data Display Components
```python
# Table with data
table = vgi.Table(
columns=["Name", "Age", "Email"],
data=[
["John Doe", 30, "john@example.com"],
["Jane Smith", 25, "jane@example.com"]
]
)
# Data grid with sorting/filtering
grid = vgi.DataGrid()
grid.set_columns([
{"key": "name", "title": "Name", "sortable": True},
{"key": "age", "title": "Age", "sortable": True, "type": "number"},
{"key": "email", "title": "Email", "sortable": True}
])
grid.set_data(data_list)
# Tree view
tree = vgi.TreeView()
root_node = tree.add_node("Root")
child_node = root_node.add_child("Child 1")
child_node.add_child("Grandchild")
```
### Charts and Visualization
```python
# Line chart
line_chart = vgi.LineChart(
data={
"x": [1, 2, 3, 4, 5],
"y": [10, 25, 30, 45, 60]
},
title="Sales Over Time"
)
# Bar chart
bar_chart = vgi.BarChart(
data={
"categories": ["Q1", "Q2", "Q3", "Q4"],
"values": [100, 150, 200, 175]
},
title="Quarterly Results"
)
# Pie chart
pie_chart = vgi.PieChart(
data={
"Desktop": 45,
"Mobile": 35,
"Tablet": 20
},
title="Platform Usage"
)
```
### Dialog and Modal Components
```python
# Message boxes
vgi.MessageBox.show("Operation completed successfully!", "Success", "info")
vgi.MessageBox.show("Are you sure?", "Confirmation", "warning")
vgi.MessageBox.show("Error occurred!", "Error", "error")
# File dialogs
filename = vgi.FileDialog.open_file(
title="Open Document",
filetypes=[("Text files", "*.txt"), ("All files", "*.*")]
)
save_path = vgi.FileDialog.save_file(
title="Save Document",
defaultextension=".txt"
)
# Custom dialog
class SettingsDialog(vgi.Dialog):
def __init__(self, parent):
super().__init__(parent, title="Settings", size=(400, 300))
self.build_ui()
def build_ui(self):
content = vgi.VBox(padding=20, spacing=15)
# Settings options
content.add(vgi.Label("Application Settings"))
content.add(vgi.Checkbox("Enable notifications"))
content.add(vgi.Checkbox("Auto-save documents"))
# Buttons
buttons = vgi.HBox(spacing=10)
buttons.add(vgi.SecondaryButton("Cancel", on_click=self.close))
buttons.add(vgi.PrimaryButton("OK", on_click=self.apply))
content.add(buttons)
self.add_widget(content)
```
## Application Architecture
### Model-View-Controller Pattern
```python
class Model:
def __init__(self):
self.data = []
self.observers = []
def add_observer(self, observer):
self.observers.append(observer)
def notify_observers(self):
for observer in self.observers:
observer.update()
def add_item(self, item):
self.data.append(item)
self.notify_observers()
class View:
def __init__(self, model, controller):
self.model = model
self.controller = controller
self.model.add_observer(self)
self.build_ui()
def build_ui(self):
self.window = vgi.Window(title="MVC Example")
self.container = vgi.VBox(padding=20)
# Input area
self.input = vgi.Input(placeholder="Enter item")
self.add_btn = vgi.PrimaryButton(
"Add",
on_click=lambda: self.controller.add_item(self.input.value)
)
# List display
self.list_container = vgi.VBox(spacing=5)
# Layout
input_row = vgi.HBox(spacing=10)
input_row.add(self.input, expand=True)
input_row.add(self.add_btn)
self.container.add(input_row)
self.container.add(self.list_container)
self.window.add_widget(self.container, fill="both", expand=True)
def update(self):
# Refresh list display
self.list_container.clear()
for item in self.model.data:
self.list_container.add(vgi.Label(item))
class Controller:
def __init__(self, model):
self.model = model
def add_item(self, item):
if item.strip():
self.model.add_item(item)
# Usage
model = Model()
controller = Controller(model)
view = View(model, controller)
```
### Plugin Architecture
```python
class PluginManager:
def __init__(self, app):
self.app = app
self.plugins = {}
def register_plugin(self, name, plugin_class):
plugin = plugin_class(self.app)
self.plugins[name] = plugin
plugin.initialize()
def get_plugin(self, name):
return self.plugins.get(name)
class BasePlugin:
def __init__(self, app):
self.app = app
def initialize(self):
pass
def create_menu_items(self):
return []
class ThemePlugin(BasePlugin):
def initialize(self):
# Add theme menu items
pass
def create_menu_items(self):
return [
vgi.MenuItem("Light Theme", on_click=self.set_light_theme),
vgi.MenuItem("Dark Theme", on_click=self.set_dark_theme)
]
# Usage
app = vgi.Application()
plugin_manager = PluginManager(app)
plugin_manager.register_plugin("themes", ThemePlugin)
```
## Performance Optimization
### Efficient Rendering
```python
# Use containers efficiently
container = vgi.VBox()
# Batch updates
container.begin_update() # Suspend layout updates
for i in range(100):
container.add(vgi.Label(f"Item {i}"))
container.end_update() # Resume and apply all updates
# Virtual scrolling for large lists
large_list = vgi.VirtualListView(
item_count=10000,
item_height=30,
render_item=lambda index: vgi.Label(f"Item {index}")
)
# Lazy loading
def load_data_chunk(start, end):
# Load data only when needed
return data[start:end]
lazy_container = vgi.LazyContainer(
total_items=1000,
chunk_size=50,
load_chunk=load_data_chunk
)
```
### Memory Management
```python
# Clean up resources
class DataView:
def __init__(self):
self.observers = []
self.timers = []
def cleanup(self):
# Remove event handlers
for observer in self.observers:
observer.disconnect()
# Stop timers
for timer in self.timers:
timer.stop()
# Clear references
self.observers.clear()
self.timers.clear()
# Use weak references for callbacks
import weakref
class WeakCallback:
def __init__(self, obj, method_name):
self.obj_ref = weakref.ref(obj)
self.method_name = method_name
def __call__(self, *args, **kwargs):
obj = self.obj_ref()
if obj is not None:
method = getattr(obj, self.method_name)
return method(*args, **kwargs)
```
## Testing
### Unit Testing Components
```python
import unittest
import vgi
class TestButton(unittest.TestCase):
def setUp(self):
self.app = vgi.Application()
self.button = vgi.Button("Test Button")
def test_button_text(self):
self.assertEqual(self.button.text, "Test Button")
def test_button_click(self):
clicked = False
def on_click():
nonlocal clicked
clicked = True
self.button.on_click(on_click)
self.button.click()
self.assertTrue(clicked)
def test_button_styling(self):
self.button.set_style(background_color="#FF0000")
self.assertEqual(self.button.get_style("background_color"), "#FF0000")
def tearDown(self):
self.app.quit()
class TestLayout(unittest.TestCase):
def setUp(self):
self.app = vgi.Application()
self.container = vgi.VBox(spacing=10)
def test_add_widgets(self):
widget1 = vgi.Label("Widget 1")
widget2 = vgi.Label("Widget 2")
self.container.add(widget1)
self.container.add(widget2)
self.assertEqual(len(self.container.children), 2)
self.assertIn(widget1, self.container.children)
self.assertIn(widget2, self.container.children)
def test_remove_widget(self):
widget = vgi.Label("Test Widget")
self.container.add(widget)
self.container.remove(widget)
self.assertEqual(len(self.container.children), 0)
self.assertNotIn(widget, self.container.children)
if __name__ == '__main__':
unittest.main()
```
### Integration Testing
```python
import vgi
def test_full_application():
"""Test complete application workflow."""
app = vgi.Application()
window = app.create_window(title="Test App")
# Create form
form = vgi.VBox(spacing=10)
name_input = vgi.Input(placeholder="Name")
email_input = vgi.EmailInput(placeholder="Email")
submit_btn = vgi.PrimaryButton("Submit")
form.add(name_input)
form.add(email_input)
form.add(submit_btn)
window.add_widget(form)
# Simulate user input
name_input.value = "John Doe"
email_input.value = "john@example.com"
# Verify values
assert name_input.value == "John Doe"
assert email_input.value == "john@example.com"
assert email_input.is_valid
# Simulate button click
submitted = False
def on_submit():
global submitted
submitted = True
submit_btn.on_click(on_submit)
submit_btn.click()
assert submitted
print("Integration test passed!")
app.quit()
if __name__ == '__main__':
test_full_application()
```
## Deployment
### Creating Executable Applications
```python
# setup.py for PyInstaller
from setuptools import setup
setup(
name="MyVGIApp",
version="1.0.0",
py_modules=["main"],
install_requires=["vgi>=1.0.0"],
entry_points={
"console_scripts": [
"myapp=main:main",
],
},
)
```
```bash
# Using PyInstaller
pip install pyinstaller
pyinstaller --onefile --windowed main.py
# Using cx_Freeze
pip install cx_freeze
python setup.py build
# Using auto-py-to-exe (GUI for PyInstaller)
pip install auto-py-to-exe
auto-py-to-exe
```
### Distribution
```python
# setup.py for distribution
from setuptools import setup, find_packages
setup(
name="my-vgi-application",
version="1.0.0",
packages=find_packages(),
install_requires=[
"vgi>=1.0.0",
],
entry_points={
"gui_scripts": [
"myapp=myapp.main:main",
],
},
classifiers=[
"Development Status :: 5 - Production/Stable",
"Intended Audience :: End Users/Desktop",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Topic :: Desktop Environment",
],
)
```
## Examples and Tutorials
### Complete Application Examples
The VGI repository includes comprehensive examples:
- **Basic Example**: Simple application demonstrating core features
- **Layout Showcase**: All layout types with interactive examples
- **Theme Demo**: Theme switching and customization
- **Component Gallery**: All components with live examples
- **Professional App**: Full-featured business application
- **Animation Demo**: Showcase of animation capabilities
- **Form Builder**: Dynamic form creation tool
- **Data Visualization**: Charts and graphs examples
- **Plugin System**: Extensible application architecture
### Running Examples
```bash
# Install VGI with examples
pip install vgi[examples]
# Run the main demo launcher
python -m vgi.examples.demo
# Run specific examples
python -m vgi.examples.basic_example
python -m vgi.examples.layout_showcase
python -m vgi.examples.theme_demo
```
## API Reference
### Core Classes
#### Application
Main application class managing windows, themes, and global resources.
**Methods:**
- `create_window(title, size, **kwargs)`: Create new window
- `set_theme(theme_name)`: Change application theme
- `run()`: Start application main loop
- `quit()`: Close application
#### Window
Top-level window container.
**Methods:**
- `add_widget(widget, **layout_options)`: Add widget to window
- `show()`: Show window
- `hide()`: Hide window
- `center()`: Center window on screen
- `set_icon(icon_path)`: Set window icon
#### Widget
Base class for all UI components.
**Properties:**
- `visible`: Widget visibility
- `enabled`: Widget enabled state
- `position`: Widget position
- `size`: Widget size
- `style`: Widget style dictionary
**Methods:**
- `set_style(**kwargs)`: Set style properties
- `on(event_name, handler)`: Add event handler
- `emit(event_name, **kwargs)`: Emit event
- `focus()`: Set focus to widget
### Component Classes
#### Button
Interactive button component.
**Properties:**
- `text`: Button text
- `style`: Button style ("primary", "secondary", etc.)
- `size`: Button size ("small", "medium", "large")
- `loading`: Loading state
- `disabled`: Disabled state
**Methods:**
- `click()`: Programmatically trigger click
- `on_click(handler)`: Set click handler
#### Input
Text input component with validation.
**Properties:**
- `value`: Input value
- `placeholder`: Placeholder text
- `validator`: Validation rules
- `is_valid`: Validation state
- `readonly`: Read-only state
**Methods:**
- `clear()`: Clear input value
- `select_all()`: Select all text
- `focus()`: Set focus to input
#### Layout Containers
**VBox**: Vertical layout
**HBox**: Horizontal layout
**Grid**: Grid layout
**Stack**: Layered layout
Common properties:
- `spacing`: Space between children
- `padding`: Internal padding
- `align`: Child alignment
### Styling Classes
#### Theme
Complete application theme.
**Methods:**
- `set_widget_style(widget_type, property, value)`
- `get_widget_styles(widget_type)`
- `set_global_style(property, value)`
#### Color
Color representation and manipulation.
**Methods:**
- `from_hex(hex_string)`: Create from hex
- `from_name(color_name)`: Create from name
- `lighten(amount)`: Lighten color
- `darken(amount)`: Darken color
- `mix(other_color, ratio)`: Mix colors
### Animation Classes
#### Animation
Property animation over time.
**Parameters:**
- `target`: Widget to animate
- `duration`: Animation duration
- `easing`: Easing function
- `**properties`: Properties to animate
**Methods:**
- `start()`: Start animation
- `pause()`: Pause animation
- `stop()`: Stop animation
#### Transition
Pre-built transition effects.
**Static Methods:**
- `fade_in(widget, duration)`
- `slide_in_left(widget, duration)`
- `scale_in(widget, duration)`
- `pulse(widget, duration)`
## Best Practices
### Application Structure
```python
# Recommended project structure
myapp/
├── __init__.py
├── main.py # Application entry point
├── models/ # Data models
│ ├── __init__.py
│ └── user.py
├── views/ # UI components
│ ├── __init__.py
│ ├── main_window.py
│ └── dialogs/
├── controllers/ # Business logic
│ ├── __init__.py
│ └── user_controller.py
├── resources/ # Assets
│ ├── images/
│ ├── icons/
│ └── themes/
└── tests/ # Test files
├── __init__.py
└── test_views.py
```
### Code Organization
```python
# main.py - Clean application entry point
import vgi
from views.main_window import MainWindow
from controllers.app_controller import AppController
def main():
app = vgi.Application(theme="modern_light")
controller = AppController(app)
main_window = MainWindow(controller)
app.add_window(main_window)
app.run()
if __name__ == "__main__":
main()
# views/main_window.py - Separate UI definition
import vgi
class MainWindow(vgi.Window):
def __init__(self, controller):
super().__init__(title="My Application", size=(800, 600))
self.controller = controller
self.build_ui()
def build_ui(self):
# UI construction logic
pass
```
### Performance Guidelines
1. **Use appropriate containers**: Choose the right layout for your needs
2. **Batch updates**: Group multiple changes together
3. **Lazy loading**: Load data only when needed
4. **Efficient event handling**: Avoid excessive event handlers
5. **Resource cleanup**: Properly dispose of resources
### Accessibility
```python
# Keyboard navigation
button.set_style(focusable=True)
button.on("key_press", handle_key_press)
# Screen reader support
label.set_style(
accessible_name="User Name Input",
accessible_description="Enter your full name"
)
# High contrast support
if app.is_high_contrast_mode():
app.set_theme("high_contrast")
```
## Contributing
We welcome contributions to VGI! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone repository
git clone https://github.com/vgi-team/vgi.git
cd vgi
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e .[dev]
# Run tests
python -m pytest
# Run examples
python -m vgi.examples.demo
```
### Code Style
We use Black for code formatting and follow PEP 8 guidelines.
```bash
# Format code
black .
# Check style
flake8 .
# Type checking
mypy vgi/
```
## License
VGI is released under the MIT License. See [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [https://vgi.readthedocs.io/](https://vgi.readthedocs.io/)
- **GitHub Issues**: [https://github.com/vgi-team/vgi/issues](https://github.com/vgi-team/vgi/issues)
- **Discussions**: [https://github.com/vgi-team/vgi/discussions](https://github.com/vgi-team/vgi/discussions)
- **Email**: support@vgi.dev
## Changelog
### Version 1.0.0 (Initial Release)
- Complete widget library with 30+ components
- Advanced layout system (VBox, HBox, Grid, Stack)
- Professional theming system with built-in themes
- Comprehensive styling with CSS-like properties
- Animation and transition system
- Form validation framework
- Event-driven architecture
- Type safety with full type hints
- Comprehensive documentation and examples
- Cross-platform compatibility
- Performance optimizations
## Acknowledgments
VGI builds upon the solid foundation of Tkinter while providing a modern, professional interface. We thank the Python community and all contributors who have made this project possible.
---
**VGI - Elevating Python GUI Development to Professional Standards**
Raw data
{
"_id": null,
"home_page": "https://github.com/vgi-team/vgi",
"name": "vgi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gui, ui, interface, modern, professional, desktop, application, framework",
"author": "VGI Team",
"author_email": "contact@vgi.dev",
"download_url": "https://files.pythonhosted.org/packages/bb/fa/852be4783f39f2af5e6cdd238b33c5e07361d61c1ac290774d895a3624b2/vgi-1.0.0.tar.gz",
"platform": null,
"description": "# VGI - Professional Modern GUI Library for Python\r\n\r\nVGI (Visual GUI Interface) is a comprehensive, modern GUI framework for Python designed to create stunning, professional desktop applications with ease. Built on top of Tkinter but providing a much more powerful and intuitive API, VGI offers advanced styling, theming, animations, and a rich set of components that rival the best GUI frameworks available.\r\n\r\n## Key Features\r\n\r\n### Modern Design Philosophy\r\n- **Clean, Modern Interface**: Professional-grade UI components with contemporary design patterns\r\n- **Responsive Layouts**: Flexible layout system that adapts to different screen sizes and resolutions\r\n- **Professional Themes**: Built-in themes including light, dark, and professional styles\r\n- **Customizable Styling**: Comprehensive styling system with CSS-like properties\r\n\r\n### Advanced Component Library\r\n- **Rich Widget Set**: Over 30 professionally designed components\r\n- **Input Validation**: Built-in validation system with real-time feedback\r\n- **Data Visualization**: Integrated charting and graphing capabilities\r\n- **Advanced Layouts**: Sophisticated layout managers (VBox, HBox, Grid, Stack)\r\n\r\n### Developer Experience\r\n- **Intuitive API**: Simple, consistent interface that's easy to learn and use\r\n- **Event-Driven Architecture**: Robust event handling system\r\n- **Type Safety**: Full type hints for excellent IDE support\r\n- **Comprehensive Documentation**: Extensive examples and tutorials\r\n\r\n### Performance & Reliability\r\n- **High Performance**: Optimized rendering and efficient memory usage\r\n- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux\r\n- **Stable Foundation**: Built on proven Tkinter technology with modern enhancements\r\n- **Production Ready**: Suitable for commercial applications\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install vgi\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/vgi-team/vgi.git\r\ncd vgi\r\npip install -e .\r\n```\r\n\r\n### Requirements\r\n\r\n- Python 3.8 or higher\r\n- Tkinter (usually included with Python)\r\n- Pillow (automatically installed)\r\n- NumPy (automatically installed)\r\n\r\n## Quick Start\r\n\r\n### Basic Application\r\n\r\n```python\r\nimport vgi\r\n\r\n# Create application\r\napp = vgi.Application(theme=\"modern_light\")\r\n\r\n# Create main window\r\nwindow = app.create_window(title=\"My VGI App\", size=(800, 600))\r\n\r\n# Create layout container\r\ncontainer = vgi.VBox(padding=20, spacing=15)\r\n\r\n# Add components\r\ntitle = vgi.Heading1(\"Welcome to VGI!\")\r\ncontainer.add(title)\r\n\r\nbutton = vgi.PrimaryButton(\r\n text=\"Click Me!\",\r\n on_click=lambda: print(\"Button clicked!\")\r\n)\r\ncontainer.add(button)\r\n\r\n# Add container to window\r\nwindow.add_widget(container, fill=\"both\", expand=True)\r\n\r\n# Run application\r\napp.run()\r\n```\r\n\r\n### Form Example with Validation\r\n\r\n```python\r\nimport vgi\r\n\r\napp = vgi.Application()\r\nwindow = app.create_window(title=\"Contact Form\", size=(500, 400))\r\n\r\n# Create form layout\r\nform = vgi.Grid(columns=2, spacing=10, padding=20)\r\n\r\n# Name field\r\nform.add(vgi.Label(\"Name:\"), row=0, column=0, sticky=\"e\")\r\nname_input = vgi.Input(\r\n placeholder=\"Enter your name\",\r\n validator=vgi.Validator().required().min_length(2)\r\n)\r\nform.add(name_input, row=0, column=1, sticky=\"ew\")\r\n\r\n# Email field\r\nform.add(vgi.Label(\"Email:\"), row=1, column=0, sticky=\"e\")\r\nemail_input = vgi.EmailInput(placeholder=\"Enter your email\")\r\nform.add(email_input, row=1, column=1, sticky=\"ew\")\r\n\r\n# Message field\r\nform.add(vgi.Label(\"Message:\"), row=2, column=0, sticky=\"ne\")\r\nmessage_input = vgi.TextArea(\r\n placeholder=\"Enter your message...\",\r\n validator=vgi.Validator().required().min_length(10)\r\n)\r\nform.add(message_input, row=2, column=1, sticky=\"ew\")\r\n\r\n# Buttons\r\nbutton_container = vgi.HBox(spacing=10)\r\nbutton_container.add(vgi.SecondaryButton(\"Cancel\"))\r\nbutton_container.add(vgi.PrimaryButton(\"Submit\"))\r\n\r\nform.add(button_container, row=3, column=0, columnspan=2, sticky=\"e\")\r\n\r\n# Configure grid\r\nform.set_column_weight(1, 1)\r\n\r\nwindow.add_widget(form, fill=\"both\", expand=True)\r\napp.run()\r\n```\r\n\r\n## Core Components\r\n\r\n### Layout Containers\r\n\r\n#### VBox - Vertical Layout\r\n```python\r\nvbox = vgi.VBox(spacing=10, align=\"stretch\")\r\nvbox.add(vgi.Label(\"First item\"))\r\nvbox.add(vgi.Label(\"Second item\"))\r\nvbox.add(vgi.Button(\"Third item\"), expand=True)\r\n```\r\n\r\n#### HBox - Horizontal Layout\r\n```python\r\nhbox = vgi.HBox(spacing=10, align=\"center\")\r\nhbox.add(vgi.Button(\"Left\"))\r\nhbox.add(vgi.Button(\"Center\"), expand=True)\r\nhbox.add(vgi.Button(\"Right\"))\r\n```\r\n\r\n#### Grid - Flexible Grid Layout\r\n```python\r\ngrid = vgi.Grid(rows=3, columns=3, spacing=5)\r\ngrid.add(vgi.Button(\"1,1\"), row=0, column=0)\r\ngrid.add(vgi.Button(\"Span\"), row=0, column=1, columnspan=2)\r\ngrid.add(vgi.Button(\"2,1\"), row=1, column=0, rowspan=2)\r\n```\r\n\r\n#### Stack - Layered Layout\r\n```python\r\nstack = vgi.Stack()\r\nstack.add(vgi.Label(\"Page 1\"), name=\"page1\")\r\nstack.add(vgi.Label(\"Page 2\"), name=\"page2\")\r\nstack.show(\"page1\") # Show specific page\r\n```\r\n\r\n### Input Components\r\n\r\n#### Basic Input Fields\r\n```python\r\n# Text input with placeholder\r\ntext_input = vgi.Input(placeholder=\"Enter text...\")\r\n\r\n# Email input with validation\r\nemail_input = vgi.EmailInput(placeholder=\"your@email.com\")\r\n\r\n# Password input\r\npassword_input = vgi.PasswordInput(placeholder=\"Password\")\r\n\r\n# Number input with range\r\nnumber_input = vgi.NumberInput(min_value=0, max_value=100)\r\n\r\n# Multi-line text area\r\ntext_area = vgi.TextArea(placeholder=\"Enter message...\")\r\n```\r\n\r\n#### Input Validation\r\n```python\r\n# Create validator\r\nvalidator = (vgi.Validator()\r\n .required()\r\n .min_length(8)\r\n .regex(r'.*[A-Z].*', \"Must contain uppercase\")\r\n .regex(r'.*\\d.*', \"Must contain number\"))\r\n\r\n# Apply to input\r\npassword_input = vgi.PasswordInput(\r\n placeholder=\"Secure password\",\r\n validator=validator,\r\n on_change=lambda text: print(f\"Valid: {password_input.is_valid}\")\r\n)\r\n```\r\n\r\n### Button Components\r\n\r\n#### Button Styles\r\n```python\r\n# Primary button (main action)\r\nprimary_btn = vgi.PrimaryButton(\"Save\", on_click=save_data)\r\n\r\n# Secondary button (secondary action)\r\nsecondary_btn = vgi.SecondaryButton(\"Cancel\", on_click=cancel)\r\n\r\n# Outline button (tertiary action)\r\noutline_btn = vgi.OutlineButton(\"Options\", on_click=show_options)\r\n\r\n# Danger button (destructive action)\r\ndanger_btn = vgi.DangerButton(\"Delete\", on_click=delete_item)\r\n```\r\n\r\n#### Button Sizes\r\n```python\r\nsmall_btn = vgi.Button(\"Small\", size=\"small\")\r\nmedium_btn = vgi.Button(\"Medium\", size=\"medium\")\r\nlarge_btn = vgi.Button(\"Large\", size=\"large\")\r\n```\r\n\r\n#### Button States\r\n```python\r\n# Loading state\r\nloading_btn = vgi.Button(\"Processing...\", loading=True)\r\n\r\n# Disabled state\r\ndisabled_btn = vgi.Button(\"Disabled\", disabled=True)\r\n\r\n# With icon (requires icon implementation)\r\nicon_btn = vgi.Button(\"Save\", icon=\"save\", icon_position=\"left\")\r\n```\r\n\r\n### Display Components\r\n\r\n#### Labels and Text\r\n```python\r\n# Heading levels\r\nh1 = vgi.Heading1(\"Main Title\")\r\nh2 = vgi.Heading2(\"Section Title\")\r\nh3 = vgi.Heading3(\"Subsection\")\r\n\r\n# Regular label\r\nlabel = vgi.Label(\"Regular text\", text_color=\"#333333\")\r\n\r\n# Caption text\r\ncaption = vgi.Caption(\"Small descriptive text\")\r\n\r\n# Clickable link\r\nlink = vgi.Link(\"Click here\", on_click=handle_click)\r\n\r\n# Wrapped text\r\nwrapped = vgi.Label(\r\n \"This is a long text that will wrap automatically\",\r\n wrap=True\r\n)\r\n```\r\n\r\n#### Containers and Panels\r\n```python\r\n# Basic container\r\ncontainer = vgi.Container(padding=16)\r\n\r\n# Styled panel with border\r\npanel = vgi.Panel(title=\"Settings\", border=True, padding=20)\r\n\r\n# Simple frame (no styling)\r\nframe = vgi.Frame()\r\n\r\n# Scrollable container\r\nscrollable = vgi.Container(scrollable=True, padding=10)\r\n```\r\n\r\n## Theming and Styling\r\n\r\n### Built-in Themes\r\n\r\n```python\r\n# Available themes\r\napp = vgi.Application(theme=\"modern_light\") # Default light theme\r\napp = vgi.Application(theme=\"modern_dark\") # Dark theme\r\napp = vgi.Application(theme=\"professional\") # Professional/corporate theme\r\n\r\n# Switch themes at runtime\r\napp.set_theme(\"modern_dark\")\r\n```\r\n\r\n### Custom Styling\r\n\r\n```python\r\n# Style individual components\r\nbutton = vgi.Button(\"Styled Button\")\r\nbutton.set_style(\r\n background_color=\"#FF6B6B\",\r\n text_color=\"#FFFFFF\",\r\n border_radius=8,\r\n padding=(12, 24),\r\n font_weight=\"bold\"\r\n)\r\n\r\n# Create custom theme\r\ncustom_theme = app.theme_manager.create_custom_theme(\r\n \"my_theme\", \r\n base_theme=\"modern_light\"\r\n)\r\ncustom_theme.set_widget_style(\"button\", \"background_color\", \"#4ECDC4\")\r\napp.set_theme(\"my_theme\")\r\n```\r\n\r\n### Color System\r\n\r\n```python\r\n# Using Color class\r\nprimary_color = vgi.Color.from_hex(\"#007ACC\")\r\ndarker_primary = primary_color.darken(0.2)\r\nlighter_primary = primary_color.lighten(0.2)\r\n\r\n# Color palettes\r\npalette = vgi.ColorPalette.create_material_palette()\r\ndark_palette = vgi.ColorPalette.create_dark_palette()\r\n\r\n# Apply palette to theme\r\ntheme = vgi.Theme(\"Custom Theme\")\r\ntheme.set_palette(palette)\r\n```\r\n\r\n## Advanced Features\r\n\r\n### Event Handling\r\n\r\n```python\r\nclass MyHandler:\r\n def __init__(self):\r\n self.button = vgi.Button(\"Click me\")\r\n \r\n # Multiple event handlers\r\n self.button.on(\"clicked\", self.on_click)\r\n self.button.on(\"mouse_enter\", self.on_hover)\r\n self.button.on(\"mouse_leave\", self.on_leave)\r\n \r\n def on_click(self, event):\r\n print(f\"Button {event.source.id} was clicked!\")\r\n \r\n def on_hover(self, event):\r\n event.source.set_style(background_color=\"#E3F2FD\")\r\n \r\n def on_leave(self, event):\r\n event.source.set_style(background_color=\"#2196F3\")\r\n```\r\n\r\n### Animation System\r\n\r\n```python\r\n# Simple fade in animation\r\nbutton = vgi.Button(\"Animated\")\r\nfade_in = vgi.Transition.fade_in(button, duration=0.5)\r\nfade_in.start()\r\n\r\n# Custom animation\r\nanimation = vgi.Animation(\r\n button,\r\n duration=1.0,\r\n x=100,\r\n y=50,\r\n scale_x=1.2,\r\n scale_y=1.2,\r\n easing=\"ease_out_bounce\"\r\n)\r\nanimation.start()\r\n\r\n# Animation with callbacks\r\ndef on_complete(anim):\r\n print(\"Animation finished!\")\r\n\r\npulse = vgi.Transition.pulse(button, duration=0.3)\r\npulse.on_complete = on_complete\r\npulse.start()\r\n```\r\n\r\n### Data Binding and Validation\r\n\r\n```python\r\n# Form with comprehensive validation\r\nclass RegistrationForm:\r\n def __init__(self):\r\n self.form = vgi.Grid(columns=2, spacing=10)\r\n \r\n # Username with custom validation\r\n self.username = vgi.Input(\r\n placeholder=\"Username\",\r\n validator=vgi.Validator()\r\n .required()\r\n .min_length(3)\r\n .max_length(20)\r\n .regex(r'^[a-zA-Z0-9_]+$', \"Only letters, numbers, underscore\")\r\n )\r\n \r\n # Email validation\r\n self.email = vgi.EmailInput(placeholder=\"Email address\")\r\n \r\n # Password with strength requirements\r\n self.password = vgi.PasswordInput(\r\n placeholder=\"Password\",\r\n validator=vgi.Validator.create_password_validator(min_length=8)\r\n )\r\n \r\n # Confirm password\r\n self.confirm_password = vgi.PasswordInput(\r\n placeholder=\"Confirm password\",\r\n validator=vgi.Validator().custom(\r\n lambda x: x == self.password.value,\r\n \"Passwords must match\"\r\n )\r\n )\r\n \r\n self.build_form()\r\n \r\n def build_form(self):\r\n fields = [\r\n (\"Username:\", self.username),\r\n (\"Email:\", self.email),\r\n (\"Password:\", self.password),\r\n (\"Confirm:\", self.confirm_password)\r\n ]\r\n \r\n for i, (label, field) in enumerate(fields):\r\n self.form.add(vgi.Label(label), row=i, column=0, sticky=\"e\")\r\n self.form.add(field, row=i, column=1, sticky=\"ew\")\r\n \r\n # Submit button - only enabled when all fields valid\r\n submit_btn = vgi.PrimaryButton(\"Register\", on_click=self.submit)\r\n self.form.add(submit_btn, row=len(fields), column=1, sticky=\"e\")\r\n \r\n def submit(self):\r\n if all(field.is_valid for field in [self.username, self.email, \r\n self.password, self.confirm_password]):\r\n print(\"Registration successful!\")\r\n else:\r\n print(\"Please fix validation errors\")\r\n```\r\n\r\n## Advanced Components\r\n\r\n### Data Display Components\r\n\r\n```python\r\n# Table with data\r\ntable = vgi.Table(\r\n columns=[\"Name\", \"Age\", \"Email\"],\r\n data=[\r\n [\"John Doe\", 30, \"john@example.com\"],\r\n [\"Jane Smith\", 25, \"jane@example.com\"]\r\n ]\r\n)\r\n\r\n# Data grid with sorting/filtering\r\ngrid = vgi.DataGrid()\r\ngrid.set_columns([\r\n {\"key\": \"name\", \"title\": \"Name\", \"sortable\": True},\r\n {\"key\": \"age\", \"title\": \"Age\", \"sortable\": True, \"type\": \"number\"},\r\n {\"key\": \"email\", \"title\": \"Email\", \"sortable\": True}\r\n])\r\ngrid.set_data(data_list)\r\n\r\n# Tree view\r\ntree = vgi.TreeView()\r\nroot_node = tree.add_node(\"Root\")\r\nchild_node = root_node.add_child(\"Child 1\")\r\nchild_node.add_child(\"Grandchild\")\r\n```\r\n\r\n### Charts and Visualization\r\n\r\n```python\r\n# Line chart\r\nline_chart = vgi.LineChart(\r\n data={\r\n \"x\": [1, 2, 3, 4, 5],\r\n \"y\": [10, 25, 30, 45, 60]\r\n },\r\n title=\"Sales Over Time\"\r\n)\r\n\r\n# Bar chart\r\nbar_chart = vgi.BarChart(\r\n data={\r\n \"categories\": [\"Q1\", \"Q2\", \"Q3\", \"Q4\"],\r\n \"values\": [100, 150, 200, 175]\r\n },\r\n title=\"Quarterly Results\"\r\n)\r\n\r\n# Pie chart\r\npie_chart = vgi.PieChart(\r\n data={\r\n \"Desktop\": 45,\r\n \"Mobile\": 35,\r\n \"Tablet\": 20\r\n },\r\n title=\"Platform Usage\"\r\n)\r\n```\r\n\r\n### Dialog and Modal Components\r\n\r\n```python\r\n# Message boxes\r\nvgi.MessageBox.show(\"Operation completed successfully!\", \"Success\", \"info\")\r\nvgi.MessageBox.show(\"Are you sure?\", \"Confirmation\", \"warning\")\r\nvgi.MessageBox.show(\"Error occurred!\", \"Error\", \"error\")\r\n\r\n# File dialogs\r\nfilename = vgi.FileDialog.open_file(\r\n title=\"Open Document\",\r\n filetypes=[(\"Text files\", \"*.txt\"), (\"All files\", \"*.*\")]\r\n)\r\n\r\nsave_path = vgi.FileDialog.save_file(\r\n title=\"Save Document\",\r\n defaultextension=\".txt\"\r\n)\r\n\r\n# Custom dialog\r\nclass SettingsDialog(vgi.Dialog):\r\n def __init__(self, parent):\r\n super().__init__(parent, title=\"Settings\", size=(400, 300))\r\n self.build_ui()\r\n \r\n def build_ui(self):\r\n content = vgi.VBox(padding=20, spacing=15)\r\n \r\n # Settings options\r\n content.add(vgi.Label(\"Application Settings\"))\r\n content.add(vgi.Checkbox(\"Enable notifications\"))\r\n content.add(vgi.Checkbox(\"Auto-save documents\"))\r\n \r\n # Buttons\r\n buttons = vgi.HBox(spacing=10)\r\n buttons.add(vgi.SecondaryButton(\"Cancel\", on_click=self.close))\r\n buttons.add(vgi.PrimaryButton(\"OK\", on_click=self.apply))\r\n \r\n content.add(buttons)\r\n self.add_widget(content)\r\n```\r\n\r\n## Application Architecture\r\n\r\n### Model-View-Controller Pattern\r\n\r\n```python\r\nclass Model:\r\n def __init__(self):\r\n self.data = []\r\n self.observers = []\r\n \r\n def add_observer(self, observer):\r\n self.observers.append(observer)\r\n \r\n def notify_observers(self):\r\n for observer in self.observers:\r\n observer.update()\r\n \r\n def add_item(self, item):\r\n self.data.append(item)\r\n self.notify_observers()\r\n\r\nclass View:\r\n def __init__(self, model, controller):\r\n self.model = model\r\n self.controller = controller\r\n self.model.add_observer(self)\r\n self.build_ui()\r\n \r\n def build_ui(self):\r\n self.window = vgi.Window(title=\"MVC Example\")\r\n self.container = vgi.VBox(padding=20)\r\n \r\n # Input area\r\n self.input = vgi.Input(placeholder=\"Enter item\")\r\n self.add_btn = vgi.PrimaryButton(\r\n \"Add\", \r\n on_click=lambda: self.controller.add_item(self.input.value)\r\n )\r\n \r\n # List display\r\n self.list_container = vgi.VBox(spacing=5)\r\n \r\n # Layout\r\n input_row = vgi.HBox(spacing=10)\r\n input_row.add(self.input, expand=True)\r\n input_row.add(self.add_btn)\r\n \r\n self.container.add(input_row)\r\n self.container.add(self.list_container)\r\n \r\n self.window.add_widget(self.container, fill=\"both\", expand=True)\r\n \r\n def update(self):\r\n # Refresh list display\r\n self.list_container.clear()\r\n for item in self.model.data:\r\n self.list_container.add(vgi.Label(item))\r\n\r\nclass Controller:\r\n def __init__(self, model):\r\n self.model = model\r\n \r\n def add_item(self, item):\r\n if item.strip():\r\n self.model.add_item(item)\r\n\r\n# Usage\r\nmodel = Model()\r\ncontroller = Controller(model)\r\nview = View(model, controller)\r\n```\r\n\r\n### Plugin Architecture\r\n\r\n```python\r\nclass PluginManager:\r\n def __init__(self, app):\r\n self.app = app\r\n self.plugins = {}\r\n \r\n def register_plugin(self, name, plugin_class):\r\n plugin = plugin_class(self.app)\r\n self.plugins[name] = plugin\r\n plugin.initialize()\r\n \r\n def get_plugin(self, name):\r\n return self.plugins.get(name)\r\n\r\nclass BasePlugin:\r\n def __init__(self, app):\r\n self.app = app\r\n \r\n def initialize(self):\r\n pass\r\n \r\n def create_menu_items(self):\r\n return []\r\n\r\nclass ThemePlugin(BasePlugin):\r\n def initialize(self):\r\n # Add theme menu items\r\n pass\r\n \r\n def create_menu_items(self):\r\n return [\r\n vgi.MenuItem(\"Light Theme\", on_click=self.set_light_theme),\r\n vgi.MenuItem(\"Dark Theme\", on_click=self.set_dark_theme)\r\n ]\r\n\r\n# Usage\r\napp = vgi.Application()\r\nplugin_manager = PluginManager(app)\r\nplugin_manager.register_plugin(\"themes\", ThemePlugin)\r\n```\r\n\r\n## Performance Optimization\r\n\r\n### Efficient Rendering\r\n\r\n```python\r\n# Use containers efficiently\r\ncontainer = vgi.VBox()\r\n\r\n# Batch updates\r\ncontainer.begin_update() # Suspend layout updates\r\nfor i in range(100):\r\n container.add(vgi.Label(f\"Item {i}\"))\r\ncontainer.end_update() # Resume and apply all updates\r\n\r\n# Virtual scrolling for large lists\r\nlarge_list = vgi.VirtualListView(\r\n item_count=10000,\r\n item_height=30,\r\n render_item=lambda index: vgi.Label(f\"Item {index}\")\r\n)\r\n\r\n# Lazy loading\r\ndef load_data_chunk(start, end):\r\n # Load data only when needed\r\n return data[start:end]\r\n\r\nlazy_container = vgi.LazyContainer(\r\n total_items=1000,\r\n chunk_size=50,\r\n load_chunk=load_data_chunk\r\n)\r\n```\r\n\r\n### Memory Management\r\n\r\n```python\r\n# Clean up resources\r\nclass DataView:\r\n def __init__(self):\r\n self.observers = []\r\n self.timers = []\r\n \r\n def cleanup(self):\r\n # Remove event handlers\r\n for observer in self.observers:\r\n observer.disconnect()\r\n \r\n # Stop timers\r\n for timer in self.timers:\r\n timer.stop()\r\n \r\n # Clear references\r\n self.observers.clear()\r\n self.timers.clear()\r\n\r\n# Use weak references for callbacks\r\nimport weakref\r\n\r\nclass WeakCallback:\r\n def __init__(self, obj, method_name):\r\n self.obj_ref = weakref.ref(obj)\r\n self.method_name = method_name\r\n \r\n def __call__(self, *args, **kwargs):\r\n obj = self.obj_ref()\r\n if obj is not None:\r\n method = getattr(obj, self.method_name)\r\n return method(*args, **kwargs)\r\n```\r\n\r\n## Testing\r\n\r\n### Unit Testing Components\r\n\r\n```python\r\nimport unittest\r\nimport vgi\r\n\r\nclass TestButton(unittest.TestCase):\r\n def setUp(self):\r\n self.app = vgi.Application()\r\n self.button = vgi.Button(\"Test Button\")\r\n \r\n def test_button_text(self):\r\n self.assertEqual(self.button.text, \"Test Button\")\r\n \r\n def test_button_click(self):\r\n clicked = False\r\n \r\n def on_click():\r\n nonlocal clicked\r\n clicked = True\r\n \r\n self.button.on_click(on_click)\r\n self.button.click()\r\n self.assertTrue(clicked)\r\n \r\n def test_button_styling(self):\r\n self.button.set_style(background_color=\"#FF0000\")\r\n self.assertEqual(self.button.get_style(\"background_color\"), \"#FF0000\")\r\n \r\n def tearDown(self):\r\n self.app.quit()\r\n\r\nclass TestLayout(unittest.TestCase):\r\n def setUp(self):\r\n self.app = vgi.Application()\r\n self.container = vgi.VBox(spacing=10)\r\n \r\n def test_add_widgets(self):\r\n widget1 = vgi.Label(\"Widget 1\")\r\n widget2 = vgi.Label(\"Widget 2\")\r\n \r\n self.container.add(widget1)\r\n self.container.add(widget2)\r\n \r\n self.assertEqual(len(self.container.children), 2)\r\n self.assertIn(widget1, self.container.children)\r\n self.assertIn(widget2, self.container.children)\r\n \r\n def test_remove_widget(self):\r\n widget = vgi.Label(\"Test Widget\")\r\n self.container.add(widget)\r\n self.container.remove(widget)\r\n \r\n self.assertEqual(len(self.container.children), 0)\r\n self.assertNotIn(widget, self.container.children)\r\n\r\nif __name__ == '__main__':\r\n unittest.main()\r\n```\r\n\r\n### Integration Testing\r\n\r\n```python\r\nimport vgi\r\n\r\ndef test_full_application():\r\n \"\"\"Test complete application workflow.\"\"\"\r\n app = vgi.Application()\r\n window = app.create_window(title=\"Test App\")\r\n \r\n # Create form\r\n form = vgi.VBox(spacing=10)\r\n name_input = vgi.Input(placeholder=\"Name\")\r\n email_input = vgi.EmailInput(placeholder=\"Email\")\r\n submit_btn = vgi.PrimaryButton(\"Submit\")\r\n \r\n form.add(name_input)\r\n form.add(email_input)\r\n form.add(submit_btn)\r\n \r\n window.add_widget(form)\r\n \r\n # Simulate user input\r\n name_input.value = \"John Doe\"\r\n email_input.value = \"john@example.com\"\r\n \r\n # Verify values\r\n assert name_input.value == \"John Doe\"\r\n assert email_input.value == \"john@example.com\"\r\n assert email_input.is_valid\r\n \r\n # Simulate button click\r\n submitted = False\r\n def on_submit():\r\n global submitted\r\n submitted = True\r\n \r\n submit_btn.on_click(on_submit)\r\n submit_btn.click()\r\n \r\n assert submitted\r\n print(\"Integration test passed!\")\r\n \r\n app.quit()\r\n\r\nif __name__ == '__main__':\r\n test_full_application()\r\n```\r\n\r\n## Deployment\r\n\r\n### Creating Executable Applications\r\n\r\n```python\r\n# setup.py for PyInstaller\r\nfrom setuptools import setup\r\n\r\nsetup(\r\n name=\"MyVGIApp\",\r\n version=\"1.0.0\",\r\n py_modules=[\"main\"],\r\n install_requires=[\"vgi>=1.0.0\"],\r\n entry_points={\r\n \"console_scripts\": [\r\n \"myapp=main:main\",\r\n ],\r\n },\r\n)\r\n```\r\n\r\n```bash\r\n# Using PyInstaller\r\npip install pyinstaller\r\npyinstaller --onefile --windowed main.py\r\n\r\n# Using cx_Freeze\r\npip install cx_freeze\r\npython setup.py build\r\n\r\n# Using auto-py-to-exe (GUI for PyInstaller)\r\npip install auto-py-to-exe\r\nauto-py-to-exe\r\n```\r\n\r\n### Distribution\r\n\r\n```python\r\n# setup.py for distribution\r\nfrom setuptools import setup, find_packages\r\n\r\nsetup(\r\n name=\"my-vgi-application\",\r\n version=\"1.0.0\",\r\n packages=find_packages(),\r\n install_requires=[\r\n \"vgi>=1.0.0\",\r\n ],\r\n entry_points={\r\n \"gui_scripts\": [\r\n \"myapp=myapp.main:main\",\r\n ],\r\n },\r\n classifiers=[\r\n \"Development Status :: 5 - Production/Stable\",\r\n \"Intended Audience :: End Users/Desktop\",\r\n \"License :: OSI Approved :: MIT License\",\r\n \"Operating System :: OS Independent\",\r\n \"Programming Language :: Python :: 3\",\r\n \"Programming Language :: Python :: 3.8\",\r\n \"Programming Language :: Python :: 3.9\",\r\n \"Programming Language :: Python :: 3.10\",\r\n \"Programming Language :: Python :: 3.11\",\r\n \"Topic :: Desktop Environment\",\r\n ],\r\n)\r\n```\r\n\r\n## Examples and Tutorials\r\n\r\n### Complete Application Examples\r\n\r\nThe VGI repository includes comprehensive examples:\r\n\r\n- **Basic Example**: Simple application demonstrating core features\r\n- **Layout Showcase**: All layout types with interactive examples\r\n- **Theme Demo**: Theme switching and customization\r\n- **Component Gallery**: All components with live examples\r\n- **Professional App**: Full-featured business application\r\n- **Animation Demo**: Showcase of animation capabilities\r\n- **Form Builder**: Dynamic form creation tool\r\n- **Data Visualization**: Charts and graphs examples\r\n- **Plugin System**: Extensible application architecture\r\n\r\n### Running Examples\r\n\r\n```bash\r\n# Install VGI with examples\r\npip install vgi[examples]\r\n\r\n# Run the main demo launcher\r\npython -m vgi.examples.demo\r\n\r\n# Run specific examples\r\npython -m vgi.examples.basic_example\r\npython -m vgi.examples.layout_showcase\r\npython -m vgi.examples.theme_demo\r\n```\r\n\r\n## API Reference\r\n\r\n### Core Classes\r\n\r\n#### Application\r\nMain application class managing windows, themes, and global resources.\r\n\r\n**Methods:**\r\n- `create_window(title, size, **kwargs)`: Create new window\r\n- `set_theme(theme_name)`: Change application theme\r\n- `run()`: Start application main loop\r\n- `quit()`: Close application\r\n\r\n#### Window\r\nTop-level window container.\r\n\r\n**Methods:**\r\n- `add_widget(widget, **layout_options)`: Add widget to window\r\n- `show()`: Show window\r\n- `hide()`: Hide window\r\n- `center()`: Center window on screen\r\n- `set_icon(icon_path)`: Set window icon\r\n\r\n#### Widget\r\nBase class for all UI components.\r\n\r\n**Properties:**\r\n- `visible`: Widget visibility\r\n- `enabled`: Widget enabled state\r\n- `position`: Widget position\r\n- `size`: Widget size\r\n- `style`: Widget style dictionary\r\n\r\n**Methods:**\r\n- `set_style(**kwargs)`: Set style properties\r\n- `on(event_name, handler)`: Add event handler\r\n- `emit(event_name, **kwargs)`: Emit event\r\n- `focus()`: Set focus to widget\r\n\r\n### Component Classes\r\n\r\n#### Button\r\nInteractive button component.\r\n\r\n**Properties:**\r\n- `text`: Button text\r\n- `style`: Button style (\"primary\", \"secondary\", etc.)\r\n- `size`: Button size (\"small\", \"medium\", \"large\")\r\n- `loading`: Loading state\r\n- `disabled`: Disabled state\r\n\r\n**Methods:**\r\n- `click()`: Programmatically trigger click\r\n- `on_click(handler)`: Set click handler\r\n\r\n#### Input\r\nText input component with validation.\r\n\r\n**Properties:**\r\n- `value`: Input value\r\n- `placeholder`: Placeholder text\r\n- `validator`: Validation rules\r\n- `is_valid`: Validation state\r\n- `readonly`: Read-only state\r\n\r\n**Methods:**\r\n- `clear()`: Clear input value\r\n- `select_all()`: Select all text\r\n- `focus()`: Set focus to input\r\n\r\n#### Layout Containers\r\n\r\n**VBox**: Vertical layout\r\n**HBox**: Horizontal layout\r\n**Grid**: Grid layout\r\n**Stack**: Layered layout\r\n\r\nCommon properties:\r\n- `spacing`: Space between children\r\n- `padding`: Internal padding\r\n- `align`: Child alignment\r\n\r\n### Styling Classes\r\n\r\n#### Theme\r\nComplete application theme.\r\n\r\n**Methods:**\r\n- `set_widget_style(widget_type, property, value)`\r\n- `get_widget_styles(widget_type)`\r\n- `set_global_style(property, value)`\r\n\r\n#### Color\r\nColor representation and manipulation.\r\n\r\n**Methods:**\r\n- `from_hex(hex_string)`: Create from hex\r\n- `from_name(color_name)`: Create from name\r\n- `lighten(amount)`: Lighten color\r\n- `darken(amount)`: Darken color\r\n- `mix(other_color, ratio)`: Mix colors\r\n\r\n### Animation Classes\r\n\r\n#### Animation\r\nProperty animation over time.\r\n\r\n**Parameters:**\r\n- `target`: Widget to animate\r\n- `duration`: Animation duration\r\n- `easing`: Easing function\r\n- `**properties`: Properties to animate\r\n\r\n**Methods:**\r\n- `start()`: Start animation\r\n- `pause()`: Pause animation\r\n- `stop()`: Stop animation\r\n\r\n#### Transition\r\nPre-built transition effects.\r\n\r\n**Static Methods:**\r\n- `fade_in(widget, duration)`\r\n- `slide_in_left(widget, duration)`\r\n- `scale_in(widget, duration)`\r\n- `pulse(widget, duration)`\r\n\r\n## Best Practices\r\n\r\n### Application Structure\r\n\r\n```python\r\n# Recommended project structure\r\nmyapp/\r\n\u251c\u2500\u2500 __init__.py\r\n\u251c\u2500\u2500 main.py # Application entry point\r\n\u251c\u2500\u2500 models/ # Data models\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 user.py\r\n\u251c\u2500\u2500 views/ # UI components\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u251c\u2500\u2500 main_window.py\r\n\u2502 \u2514\u2500\u2500 dialogs/\r\n\u251c\u2500\u2500 controllers/ # Business logic\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 user_controller.py\r\n\u251c\u2500\u2500 resources/ # Assets\r\n\u2502 \u251c\u2500\u2500 images/\r\n\u2502 \u251c\u2500\u2500 icons/\r\n\u2502 \u2514\u2500\u2500 themes/\r\n\u2514\u2500\u2500 tests/ # Test files\r\n \u251c\u2500\u2500 __init__.py\r\n \u2514\u2500\u2500 test_views.py\r\n```\r\n\r\n### Code Organization\r\n\r\n```python\r\n# main.py - Clean application entry point\r\nimport vgi\r\nfrom views.main_window import MainWindow\r\nfrom controllers.app_controller import AppController\r\n\r\ndef main():\r\n app = vgi.Application(theme=\"modern_light\")\r\n controller = AppController(app)\r\n main_window = MainWindow(controller)\r\n \r\n app.add_window(main_window)\r\n app.run()\r\n\r\nif __name__ == \"__main__\":\r\n main()\r\n\r\n# views/main_window.py - Separate UI definition\r\nimport vgi\r\n\r\nclass MainWindow(vgi.Window):\r\n def __init__(self, controller):\r\n super().__init__(title=\"My Application\", size=(800, 600))\r\n self.controller = controller\r\n self.build_ui()\r\n \r\n def build_ui(self):\r\n # UI construction logic\r\n pass\r\n```\r\n\r\n### Performance Guidelines\r\n\r\n1. **Use appropriate containers**: Choose the right layout for your needs\r\n2. **Batch updates**: Group multiple changes together\r\n3. **Lazy loading**: Load data only when needed\r\n4. **Efficient event handling**: Avoid excessive event handlers\r\n5. **Resource cleanup**: Properly dispose of resources\r\n\r\n### Accessibility\r\n\r\n```python\r\n# Keyboard navigation\r\nbutton.set_style(focusable=True)\r\nbutton.on(\"key_press\", handle_key_press)\r\n\r\n# Screen reader support\r\nlabel.set_style(\r\n accessible_name=\"User Name Input\",\r\n accessible_description=\"Enter your full name\"\r\n)\r\n\r\n# High contrast support\r\nif app.is_high_contrast_mode():\r\n app.set_theme(\"high_contrast\")\r\n```\r\n\r\n## Contributing\r\n\r\nWe welcome contributions to VGI! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone repository\r\ngit clone https://github.com/vgi-team/vgi.git\r\ncd vgi\r\n\r\n# Create virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\r\n\r\n# Install development dependencies\r\npip install -e .[dev]\r\n\r\n# Run tests\r\npython -m pytest\r\n\r\n# Run examples\r\npython -m vgi.examples.demo\r\n```\r\n\r\n### Code Style\r\n\r\nWe use Black for code formatting and follow PEP 8 guidelines.\r\n\r\n```bash\r\n# Format code\r\nblack .\r\n\r\n# Check style\r\nflake8 .\r\n\r\n# Type checking\r\nmypy vgi/\r\n```\r\n\r\n## License\r\n\r\nVGI is released under the MIT License. See [LICENSE](LICENSE) file for details.\r\n\r\n## Support\r\n\r\n- **Documentation**: [https://vgi.readthedocs.io/](https://vgi.readthedocs.io/)\r\n- **GitHub Issues**: [https://github.com/vgi-team/vgi/issues](https://github.com/vgi-team/vgi/issues)\r\n- **Discussions**: [https://github.com/vgi-team/vgi/discussions](https://github.com/vgi-team/vgi/discussions)\r\n- **Email**: support@vgi.dev\r\n\r\n## Changelog\r\n\r\n### Version 1.0.0 (Initial Release)\r\n\r\n- Complete widget library with 30+ components\r\n- Advanced layout system (VBox, HBox, Grid, Stack)\r\n- Professional theming system with built-in themes\r\n- Comprehensive styling with CSS-like properties\r\n- Animation and transition system\r\n- Form validation framework\r\n- Event-driven architecture\r\n- Type safety with full type hints\r\n- Comprehensive documentation and examples\r\n- Cross-platform compatibility\r\n- Performance optimizations\r\n\r\n## Acknowledgments\r\n\r\nVGI builds upon the solid foundation of Tkinter while providing a modern, professional interface. We thank the Python community and all contributors who have made this project possible.\r\n\r\n---\r\n\r\n**VGI - Elevating Python GUI Development to Professional Standards**\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Professional Modern GUI Library for Python - Create stunning applications with ease",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/vgi-team/vgi/issues",
"Documentation": "https://vgi.readthedocs.io/",
"Homepage": "https://github.com/vgi-team/vgi",
"Source": "https://github.com/vgi-team/vgi"
},
"split_keywords": [
"gui",
" ui",
" interface",
" modern",
" professional",
" desktop",
" application",
" framework"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf6b00d2024ffc4973aa12298eae85d465ab9bccfe8b1497ddb941dbcebc6097",
"md5": "73e446c932261f2b6f6100a372f5ded2",
"sha256": "d3fc8770e0779d395775f1c073f704c12c5415e3c87cdcdab255560d5b555474"
},
"downloads": -1,
"filename": "vgi-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73e446c932261f2b6f6100a372f5ded2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 73116,
"upload_time": "2025-08-08T22:44:21",
"upload_time_iso_8601": "2025-08-08T22:44:21.428889Z",
"url": "https://files.pythonhosted.org/packages/cf/6b/00d2024ffc4973aa12298eae85d465ab9bccfe8b1497ddb941dbcebc6097/vgi-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bbfa852be4783f39f2af5e6cdd238b33c5e07361d61c1ac290774d895a3624b2",
"md5": "db2dd3874333efb58c3a3d448f48a94b",
"sha256": "e4b37a72fdab557f0fded762fc3067e173ca12074b63a528e97ce8d56b64c23f"
},
"downloads": -1,
"filename": "vgi-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "db2dd3874333efb58c3a3d448f48a94b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 81885,
"upload_time": "2025-08-08T22:44:23",
"upload_time_iso_8601": "2025-08-08T22:44:23.615331Z",
"url": "https://files.pythonhosted.org/packages/bb/fa/852be4783f39f2af5e6cdd238b33c5e07361d61c1ac290774d895a3624b2/vgi-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 22:44:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vgi-team",
"github_project": "vgi",
"github_not_found": true,
"lcname": "vgi"
}
JSON
