Skip to content

User Guides

In-depth guides and tutorials for EzQt Widgets library.

Overview

This section provides comprehensive guides for mastering EzQt Widgets features and best practices. Whether you're just getting started or looking to contribute to the project, you'll find detailed documentation here.

Available Guides

Guide Description Level
QSS Style Guide Visual customization with Qt stylesheets Beginner
Development Guide Development workflow and contribution guide Intermediate
Testing Guide Test suite documentation and testing practices Advanced

For Beginners

For Developers

For Advanced Users

Topics

Core Concepts

  • Qt Signals & Slots - Understanding widget communication through Qt's signal/slot mechanism
  • QPropertyAnimation - Smooth animations with configurable easing curves
  • QSS Styling - Customizing widget appearance with Qt stylesheets
  • Type Hints - Using Python type annotations for better IDE support

Widget Features

  • Button Widgets - Date pickers, icon buttons, and loading buttons
  • Input Widgets - Auto-complete, search, and password inputs
  • Label Widgets - Clickable tags, hover labels, and status indicators
  • Misc Widgets - Timers, drag-and-drop lists, toggles, and selectors

Integration

  • Application Integration - Integrating EzQt Widgets into your PySide6 applications
  • Custom Styling - Creating custom themes and visual styles
  • Signal Management - Connecting widgets with signals and slots
  • Layout Management - Organizing widgets in layouts

Best Practices

  • Performance - Optimizing widget performance in large applications
  • Error Handling - Robust error handling with Qt widgets
  • Testing - Testing applications that use EzQt Widgets
  • Code Organization - Structuring your Qt application code

Development Workflow

Setting Up

  1. Clone the repository
git clone https://github.com/neuraaak/ezqt-widgets.git
cd ezqt_widgets
  1. Install in development mode
pip install -e ".[dev]"
  1. Install pre-commit hooks
pre-commit install

See the Development Guide for detailed setup instructions.

Testing

Run the test suite to ensure everything works:

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=ezqt_widgets

# Run specific test types
pytest tests/unit/
pytest tests/integration/

# Using the CLI
ezqt test --unit
ezqt test --coverage

See the Testing Guide for more information.

Contributing

We welcome contributions! Here's how to get started:

  1. Fork the repository on GitHub
  2. Create a feature branch (git checkout -b feature/amazing-widget)
  3. Make your changes with tests
  4. Run tests and linting (pytest, ruff check)
  5. Commit your changes with conventional commits
  6. Push to your fork (git push origin feature/amazing-widget)
  7. Open a Pull Request on GitHub

See the Development Guide for contribution guidelines.

Code Style

EzQt Widgets follows these coding standards:

  • PEP 8 - Python style guide
  • Type Hints - Full type annotations for Python 3.10+
  • Docstrings - Google-style docstrings for all public APIs
  • Testing - Comprehensive test coverage (~75%)
  • Black - Code formatting (88 character line length)
  • Ruff - Linting and code quality

Documentation

Building Docs

Build the documentation locally:

# Install docs dependencies
pip install -e ".[docs]"

# Build documentation
mkdocs build

# Serve locally
mkdocs serve

Then open http://127.0.0.1:8000 in your browser.

Writing Docs

Documentation is written in Markdown and built with MkDocs Material:

  • Guides - Located in docs/guides/
  • API Reference - Auto-generated from docstrings with mkdocstrings
  • Examples - Code examples in docs/examples/
  • CLI - Command-line interface docs in docs/cli/

See Also

Need Help?

Happy coding with EzQt Widgets! 🚀