Skip to content

Async counter

A counter whose callback is an async function (asyncio basics).

Python only

This example has no counterpart in the other language.

Async counter

Real capture on KDE Plasma 6.6 Wayland with the released packages.

What it teaches: async_adapter; awaitable document.command.

Run it

uv init --app myapp && cd myapp    # once: a uv project for your app
uv add nativehtmlkit
# save the example file(s) in the project folder, then:
uv run async_counter.py

Related guide: asyncio

Source: async_counter.py

View on GitHub

"""Async counter: async callbacks on the owning event loop, awaitable RPC, clean shutdown.

What it teaches (Python-specific: asyncio basics)
  * ``app.async_adapter()``: the same host connection, with callbacks that run on YOUR loop
  * ``async def`` event handlers registered with ``adapter.on_document_event``
  * awaitable RPC (``await adapter.rpc.call(...)``) that keeps the loop responsive
  * ``await adapter.run()``, which returns when the window is closed or the app quits

Run:  uv run async_counter.py   (or: uv run -m nativehtmlkit run async_counter:amain)
"""
from __future__ import annotations

import asyncio

from nativehtmlkit import Application, Window

HTML = """<main style="padding:20px;font-family:sans-serif">
<h1>Async counter</h1>
<button id="inc">Add one</button> <span id="count">0</span>
<p id="status">Ready</p></main>"""


class AsyncCounter:
    def __init__(self, app: Application, window: Window):
        self.window, self.document = window, window.document
        self.adapter = app.async_adapter()   # callbacks registered here run on the current loop
        self.count = 0
        self.adapter.on_document_event(self.document, "click", self.increment, element="inc")

    async def increment(self, _event: dict) -> None:
        self.count += 1
        # Awaitable RPC: the loop keeps running while the host answers.
        await self.adapter.rpc.call("document.command", {
            "window_id": self.window.id, "document_id": self.document.id,
            "command": {"op": "set_text", "element": "count", "text": str(self.count)}})


async def amain(app: Application) -> None:
    # Blocking SDK calls go through a thread so they never stall the loop.
    window = await asyncio.to_thread(app.open_html, HTML, title="NativeHTMLKit async counter", width=420, height=260)
    counter = AsyncCounter(app, window)
    await counter.adapter.run()   # returns after the window is closed / the app quits


def main() -> None:
    with Application.start(name="Async counter") as app:
        asyncio.run(amain(app))


if __name__ == "__main__":
    main()