AYON UI Qt Addon API Reference

ayon-ui-qt is Qt widget library addon for AYON, designed to override Qt stylesheets of host applications and preserve our UIs appearance.

It provides AYON-styled widgets, data models, and utility components for building consistent desktop tools.

Most widgets use variants that can be defined and tweaked in ayon_style.json.

Overview

ayon-ui-qt packages reusable UI building blocks that mirror AYON's visual language while staying native to Qt. It includes:

• A custom QStyle implementation (AYONStyle) and style helpers
• Component widgets (buttons, form controls, containers, cards, filters)
• Data-driven views and models for paginated tables and lazy trees
• Async task queue utilities for non-blocking model/view updates

Recent Changes

• Added/expanded advanced data components:
• PaginatedTableModel with async fetch, sorting, tree mode, and optional event-loop batch fetching via fetch_page_batch
• AYTableView support for persistent editor widgets through TableColumn.widget_factory
• LazyTreeModel for async on-demand tree loading
• Added richer filtering/tagging and selection components:
• AYFilter, AYFilterByCategory, AYTableFilter, AYTagSelector
• Added more view widgets and helpers:
• AYCardView, AYGalleryDialog, AYFilterableList, AYSlicer
• Async infrastructure and monitoring:
• AsyncTaskQueue and AsyncTaskQueueMonitor

Installation

As an AYON Addon

1. Build the addon package:

   bash python create_package.py

2. Upload the generated zip package from dist/ to your AYON server.

3. Enable the addon in AYON Studio Settings.

For Development

uv sync
uv run pytest

Python requirement: >=3.9.1,<3.10

Quick Start

from qtpy.QtWidgets import QApplication

from ayon_ui_qt.style import get_ayon_style, style_widget_and_siblings
from ayon_ui_qt.components.buttons import AYButton
from ayon_ui_qt.components.container import AYContainer
from ayon_ui_qt.components.label import AYLabel

app = QApplication([])
app.setStyle(get_ayon_style())

container = AYContainer(
      layout=AYContainer.Layout.VBox,
      variant=AYContainer.Variants.Low,
      layout_margin=10,
      layout_spacing=8,
)

container.add_widget(
      AYButton("Run", variant=AYButton.Variants.Filled, icon="play_arrow")
)
container.add_widget(
      AYLabel("Ready", icon="check_circle", icon_color="#60c689")
)

style_widget_and_siblings(container)
container.show()
app.exec()

Paginated Model API

PaginatedTableModel expects a page fetch callback with this signature:

def fetch_page(
      page: int,
      page_size: int,
      sort_key: str | None,
      descending: bool,
      parent_id: str | None,
) -> list[dict]:
      ...

Optional batch callback (tree mode child fetches):

from ayon_ui_qt.components.table_model import BatchFetchRequest


def fetch_page_batch(
      requests: list[BatchFetchRequest],
) -> dict[str | None, list[dict]]:
      ...

Notes:

• Root-level fetch uses fetch_page
• Child-node fetches can be coalesced per event-loop tick using fetch_page_batch
• Use reset_data() when external context changes (project/folder/filter)

Component Catalog

Core Widgets

Data Views and Models

Entity and Content Widgets

Filtering, Tags, and Selection

Layout and Utility Components

Project Structure

ayon-ui-qt/
├── client/
│   └── ayon_ui_qt/
│       ├── __init__.py
│       ├── addon.py
│       ├── style.py
│       ├── variants.py
│       ├── components/
│       ├── resources/
│       └── vendor/
├── server/
│   └── __init__.py
├── package.py
├── create_package.py
├── pyproject.toml
├── TESTING.md
└── README.md

Development

• Install dependencies: uv sync
• Run tests: uv run pytest
• Run a single test: uv run pytest tests/<file>::<test> -v
• Format: uv run ruff format <file>
• Lint: uv run ruff check <file>

Detailed visual testing workflow is documented in TESTING.md.

Variants management

The concept of variants is borrowed from AYON's REACT library. A variant is a version of a component with a different appearance. They act like preset stylesheets.

Variants are defined in 2 files:

• ayon_style.json - defines the styles for each variant
• This file contains:
  • global settings like the base font or the style's palette.
  • Per base class variants to modify the appearance of the component.
• variants.py - defines the variants and their properties
• This file contains enums reflecting all available variants from ayon_style.json.
• The enums can be automatically updated by running variants.py. The code in __main__ will read ayon_style.json and update the enums if need be. It will also print a summary of the changes.

  [!IMPORTANT] Always run variants.py after modifying ayon_style.json to ensure the enums are up to date.

License

Apache-2.0