Window¶
from nativehtmlkit import Window # type only; windows come from Application
A Window is a handle to one native top-level window. Create it with
Application.create_window, open_html or open_file. Each window
holds at most one Document at a time.
Attributes¶
| Attribute | Type | Meaning |
|---|---|---|
app |
Application |
The owning application. |
id |
str |
Opaque host ID such as "w1". Never reused within a session. |
document |
Document \| None |
The current document, None before the first load or after unload(). |
closed |
bool |
True once the host reported the window closed or the application shut down. |
Stale-handle semantics¶
When the window closes (its closed window event, or app.shutdown for the last window) the SDK
sets closed = True and retires its document. Every later call on the window, its document or
its nodes raises StaleDocumentError locally, without contacting
the host. Check window.closed or catch the error in code that may outlive a window (threads,
timers, futures).
Loading documents¶
load_html¶
window.load_html(html: str, *, asset_root: str | Path | None = None) -> Document
Replace the window's document with html (at most 1 MiB, else RpcError -32005). asset_root
is the directory for relative URLs; it is resolved to an absolute path. The previous document is
retired only after the new one loaded successfully: a failed load leaves the old document live.
Returns the new Document, also available as window.document.
load_file¶
window.load_file(path: str | Path, *, asset_root: str | Path | None = None) -> Document
Load a UTF-8 HTML file of at most 1 MiB. The path is resolved to an absolute path; asset_root
defaults to the file's directory, so <link href="style.css"> and <img src="logo.png"> next to
the file work. A missing file fails with RpcError -32002.
Both raise StaleDocumentError if the window is closed and ApplicationShutdownError once the
application is shutting down. The host admits at most 16 live documents.
document = window.load_file(Path(__file__).with_name("index.html"))
document.set_text("status", "Loaded")
Window state¶
state¶
window.state() -> dict returns the window description (window.get):
| Member | Meaning |
|---|---|
window_id, title, width, height, visible |
As requested, logical pixels |
native |
False in headless mode |
scale_factor |
Display scale |
physical_size |
Actual size in physical pixels, or None |
requested |
{"visible", "resizable", "decorations", "size_constraints": {"min_width", "min_height", "max_width", "max_height"}} |
observed |
{"focused", "minimized", "maximized", "fullscreen", "resizable", "decorations", "visible", "theme", "position"}; each None when the platform cannot report it (always in headless mode) |
closing |
True while a close is in progress |
app.rpc.call("window.list") returns the same description for every open window.
set¶
window.set(**properties) -> dict
Change window properties and return the updated description. Accepted keywords (all optional):
| Keyword | Type |
|---|---|
title |
str |
width, height |
int, logical pixels |
visible, resizable, decorations |
bool |
minimized, maximized, fullscreen |
bool |
focus |
bool (True asks for focus) |
x, y |
int, together; screen position |
min_width + min_height, max_width + max_height |
int pairs; None removes the constraint |
Unknown keywords, and x without y, fail with RpcError -32602. Platform limits are reported as
RpcError -32001. On Linux the Wayland compositor owns placement and focus: x/y and
minimized=False are always refused there, and focus=True and visible are refused for an
existing native window. On Windows all members are applied. The observed members of the returned
description show what the platform actually did.
window.set(title="Report — saved", width=1024, height=720)
window.set(min_width=480, min_height=320)
window.set(maximized=True)
request_attention¶
window.request_attention(kind: str | None = "informational") -> dict
Ask the desktop to draw attention to the window: "informational", "critical", or None to
clear the request. Returns {"requested": True, "kind", "presented": None, "policy"}. Raises
RpcError -32001 in headless mode and where the window manager does not support it (Wayland cannot
clear a request).
Closing¶
request_close¶
window.request_close() -> None. Ask to close the window as if the user had. The host sends
close_requested (reason backend_request), asks the window's on_before_close
policy, then closes the window (closed event). Closing the last window quits the application
(after on_before_quit). Before app.ready, closing the last
usable window cancels start-up.
on_before_close¶
window.on_before_close(callback: Callable[[], bool]) -> None
Install a close policy for this window: callback() returns True to allow closing and False
to keep the window open (for example to show an "unsaved changes" banner). One policy per window;
a new call replaces it. Windows without a policy always close. The callback runs on an SDK worker
thread and must answer promptly (the host waits indefinitely); it may call the SDK. An exception
counts as deny.
def allow_close() -> bool:
if editor.dirty:
window.document.add_class("unsaved-banner", "shown")
return False
return True
window.on_before_close(allow_close)
Native file dialogs¶
window.open_files(*, multiple=False, title=None, directory=None, filters=(), wait=True)
window.save_file(*, file_name=None, title=None, directory=None, filters=(), wait=True)
window.choose_folder(*, title=None, directory=None, wait=True)
Show a native dialog parented to this window. filters is a list of
{"name": "Images", "extensions": ["png", "jpg"]} (extensions without the dot). directory is
the start folder.
The result is a dict: {"cancelled": bool, "paths": [str, ...]}. paths has one entry for
save_file and choose_folder, and one or more for open_files(multiple=True); it is empty when
the user cancelled.
wait=True(default) blocks until the user answers. There is no timeout.wait=Falsereturns aconcurrent.futures.Futureat once; read it in a done-callback.future.cancel()asks the host to close the native dialog.
Errors: RpcError -32001 in headless mode and without a desktop dialog service (on Linux the
desktop portal), -32005 if this window already shows a native dialog or the host's service limit is
reached, StaleDocumentError for a closed window. With wait=False the error is set on the future.
def done(future):
try:
result = future.result()
except RpcError as error:
print("no dialog:", error.code)
return
if not result["cancelled"]:
window.document.set_text("chosen", result["paths"][0])
window.open_files(title="Choose an image", filters=[{"name": "Images", "extensions": ["png", "jpg"]}],
wait=False).add_done_callback(done)
A blocking (wait=True) dialog inside an event callback holds up later document and window events
until it closes. Prefer wait=False there. See the file dialogs guide.
Source: nativehtmlkit-python/docs/reference/window.md · edit the page there.