API Reference

The JadeUI Python SDK provides a complete set of APIs for building desktop applications. This document describes each class and method in detail.

JadeUIApp

The main application class, which manages the application lifecycle. It uses the singleton pattern.

Constructor

Python

app = JadeUIApp()

Methods

initialize()

Initializes the application.

Python

app.initialize(
    enable_dev_tools=False,  # Whether to enable developer tools (F12)
    log_file=None,           # Log file path
    data_directory=None,     # WebView data directory
    app_name=None,           # Application name (JadeView 2.x)
    app_signature=None,      # App signature; placeholder must be at least 6 chars (JadeView 2.x)
    single_instance=False,   # Single-instance mode (JadeView 2.x)
)

Parameter	Type	Description
enable_dev_tools	bool	Enable developer tools
log_file	str \| None	Log file path
data_directory	str \| None	WebView data storage directory
app_name	str \| None	Application name; generated by the SDK when omitted
app_signature	str \| None	Application signature; JadeView 2.x requires a non-empty value with at least 6 trimmed characters, and the SDK fills a safe fallback
single_instance	bool	Whether to enable single-instance mode

Return value: JadeUIApp (supports method chaining)

run()

Starts the application message loop. This method blocks until all windows are closed.

Python

app.run()

quit()

Quits the application.

Python

app.quit()

is_ready()

Checks whether the application has been initialized.

Python

if app.is_ready():
    print("Application is ready")

Return value: bool

get_webview_version()

Gets the WebView engine version.

Python

version = app.get_webview_version()
print(f"WebView version: {version}")  # e.g.: "120.0.2210.144"

Return value: str | None - The WebView version string, or None if unavailable

Decorators

@on_ready

Registers an application-ready event handler.

Python

@app.on_ready
def setup():
    window = Window("My App")
    window.show()

@on_window_all_closed

Registers an all-windows-closed event handler.

Python

@app.on_window_all_closed
def cleanup():
    print("All windows have been closed")

Events

Event name	Description
ready	Application initialization complete
error	An error occurred
window-all-closed	All windows closed
before-quit	Application is about to quit

Window

The WebView window class, used to create and manage windows.

Constructor

Python

window = Window(
    title="Window",          # Window title
    width=800,               # Width
    height=600,              # Height
    url=None,                # Initial URL
    **options                # Other options
)

Window Options

Option	Type	Default	Description
resizable	bool	True	Allow resizing
remove_titlebar	bool	False	Remove the native titlebar
transparent	bool	False	Enable window transparency
background_color	RGBA	(255,255,255,255)	Background color
always_on_top	bool	False	Keep window on top
theme	str	"System"	Theme (Light/Dark/System)
maximized	bool	False	Maximized initially
maximizable	bool	True	Allow maximizing
minimizable	bool	True	Allow minimizing
x	int	-1	X coordinate (-1 centers)
y	int	-1	Y coordinate (-1 centers)
min_width	int	0	Minimum width
min_height	int	0	Minimum height
max_width	int	0	Maximum width (0 means no limit)
max_height	int	0	Maximum height (0 means no limit)
fullscreen	bool	False	Fullscreen mode
focus	bool	True	Acquire focus on creation
hide_window	bool	False	Hide on creation
use_page_icon	bool	True	Use the page icon
frame_style	str \| None	None	JadeView 2.x frame style: `normal` / `no-titlebar` / `borderless` / `title-overlay`
auto_save_state	bool	False	Save and restore window state automatically
skip_taskbar	bool	False	v2.3: keep the window out of the taskbar / Alt-Tab
no_activate	bool	False	v2.3: do not steal focus when shown or clicked
autoplay	bool	False	Allow media autoplay
disable_right_click	bool	False	Disable the right-click menu
user_agent	str \| None	None	Custom User-Agent
preload_js	str \| None	None	Preloaded JavaScript
allow_fullscreen	bool	True	Allow the page's JS to call the fullscreen API (requires Jadeui 0.2.1)
borderless	bool	False	Borderless mode, removes the border and system shadow (requires 0.2.1+)
content_protection	bool	False	Content protection, prevents screenshots/screen recording (requires 1.1+)
postmessage_whitelist	str \| None	None	PostMessage whitelist, comma-separated origins (requires 1.0.2+)

Parameter Conflict Notes

borderless: borderless=True cannot be used together with remove_titlebar or transparent, otherwise a ValueError is raised. This is because borderless removes the border and system shadow, which conflicts with the functionality of the latter two.
content_protection: content_protection=True cannot be used together with minimizable or maximizable. When content protection is enabled, the window cannot be minimized or maximized.

Lifecycle Methods

show()

Shows the window.

Python

window.show(url=None)  # Optionally pass a URL

Return value: Window (method chaining)

hide()

Hides the window.

Python

window.hide()

Return value: Window

close()

Closes the window.

Python

window.close()

focus()

Gives the window focus.

Python

window.focus()

Return value: Window

State Control Methods

minimize()

Minimizes the window.

Python

window.minimize()

Return value: Window

maximize()

Toggles between the maximized and restored states.

Python

window.maximize()

Return value: Window

restore()

Restores the window from the minimized/maximized state.

Python

window.restore()

Return value: Window

set_fullscreen()

Sets fullscreen mode.

Version Requirement

This feature requires Jadeui 0.2.1 or later.

Python

window.set_fullscreen(True)   # Enter fullscreen
window.set_fullscreen(False)  # Exit fullscreen

Parameter	Type	Description
fullscreen	bool	Whether to go fullscreen

Return value: Window

toggle_fullscreen()

Toggles fullscreen mode. If currently fullscreen, exits; otherwise enters fullscreen.

Version Requirement

This feature requires Jadeui 0.2.1 or later.

Python

window.toggle_fullscreen()

Return value: Window

Property Methods

set_title()

Sets the window title.

Python

window.set_title("New Title")
# Or use the property
window.title = "New Title"

Return value: Window

set_size()

Sets the window size.

Python

window.set_size(1280, 720)

Parameter	Type	Description
width	int	Width (pixels)
height	int	Height (pixels)

Return value: Window

set_min_size()

Sets the minimum window size.

Python

window.set_min_size(400, 300)

Return value: Window

set_max_size()

Sets the maximum window size.

Python

window.set_max_size(1920, 1080)  # 0 means no limit

Return value: Window

set_position()

Sets the window position.

Python

window.set_position(100, 100)

Parameter	Type	Description
x	int	X coordinate
y	int	Y coordinate

Return value: Window

center()

Centers the window.

Python

window.center()

Return value: Window

set_visible()

Sets the window visibility.

Python

window.set_visible(True)
window.set_visible(False)

Return value: Window

set_always_on_top()

Sets whether the window stays on top.

Python

window.set_always_on_top(True)

Return value: Window

set_resizable()

Sets whether the window is resizable.

Python

window.set_resizable(False)

Return value: Window

set_skip_taskbar()

Sets whether the window is hidden from the taskbar / Alt-Tab. Requires JadeView 2.3+.

Python

window.set_skip_taskbar(True)
window.set_skip_taskbar(False)

Return value: Window

set_no_activate()

Sets whether the window avoids stealing focus when shown or clicked. Requires JadeView 2.3+.

Python

window.set_no_activate(True)
window.set_no_activate(False)

Return value: Window

set_level()

Sets the window level. Requires JadeView 2.3+.

Python

window.set_level("topmost")  # topmost / normal / bottom / desktop

Parameter	Type	Description
level	str	`topmost`, `normal`, `bottom`, or `desktop`

Return value: Window

Theme Methods

set_theme()

Sets the window theme.

Python

from jadeui import Theme

window.set_theme(Theme.LIGHT)  # Light
window.set_theme(Theme.DARK)   # Dark
window.set_theme(Theme.SYSTEM) # Follow the system

Return value: Window

get_theme()

Gets the current theme.

Python

theme = window.get_theme()

Return value: str

set_backdrop()

Sets the window backdrop material (Windows 11).

Python

from jadeui import Backdrop

window.set_backdrop(Backdrop.MICA)     # Mica effect
window.set_backdrop(Backdrop.MICA_ALT) # Mica Alt effect
window.set_backdrop(Backdrop.ACRYLIC)  # Acrylic effect

INFO

The window must have transparent=True set in order to use backdrop effects.

Return value: Window

WebView Methods

load_url() / navigate()

Navigates to a URL.

Python

window.load_url("https://example.com")
# Or
window.navigate("https://example.com")

Return value: Window

execute_js() / eval()

Executes JavaScript code.

Python

window.execute_js("console.log('Hello!')")
# Or
window.eval("document.title = 'New Title'")

Return value: Window

reload()

Reloads the current page.

Python

window.reload()

Return value: Window

State Properties

Property	Type	Description
id	int \| None	Window ID
title	str	Window title
size	tuple[int, int]	Window size (width, height)
position	tuple[int, int]	Window position (x, y)
is_visible	bool	Whether visible
is_maximized	bool	Whether maximized (requires Jadeui 0.2.1)
is_minimized	bool	Whether minimized
is_focused	bool	Whether focused
is_fullscreen	bool	Whether fullscreen (requires Jadeui 0.2.1)

Native Handle

get_hwnd()

Gets the native HWND. Starting with JadeView 2.3, regular windows created via create_webview_window can also return a valid handle.

Python

hwnd = window.get_hwnd()

Return value: int

Static Methods

get_window_count()

Gets the number of active windows.

Python

count = Window.get_window_count()

get_window_by_id()

Gets a window by its ID.

Python

window = Window.get_window_by_id(1)

get_id_from_hwnd()

Gets the JadeView window id from a native HWND. Requires JadeView 2.3+.

Python

window_id = Window.get_id_from_hwnd(hwnd)

get_all_windows()

Gets all active windows.

Python

windows = Window.get_all_windows()

Events

The Window class provides two ways to listen for events: typed decorators (recommended) and Events constants.

Event arguments are parsed automatically; there is no need to call json.loads manually.

Typed Event Decorators (Recommended)

These provide IDE type hints, and the arguments are parsed automatically:

Decorator	Callback signature	Description
`@window.on_resized`	`(width: int, height: int)`	Window size changed
`@window.on_moved`	`(x: int, y: int)`	Window position changed
`@window.on_focused`	`()`	Window gained focus
`@window.on_blurred`	`()`	Window lost focus
`@window.on_closing`	`() -> bool`	Window is about to close; return True to prevent it
`@window.on_state_changed`	`(is_maximized: bool)`	Window state changed
`@window.on_fullscreen_changed`	`(is_fullscreen: bool)`	Fullscreen state changed (requires 1.2+)
`@window.on_file_dropped`	`(files: List[str], x: int, y: int)`	File drop
`@window.on("drag-drop")`	`(data: dict)`	v2.x drag/drop lifecycle event
`@window.on_navigate`	`(url: str) -> bool`	About to navigate; return True to prevent it
`@window.on_page_loaded`	`(url: str)`	Page finished loading
`@window.on_title_updated`	`(title: str)`	Page title updated
`@window.on_new_window`	`(url: str, frame_name: str) -> bool`	New window requested; return True to prevent it
`@window.on_download_started`	`(url: str, filename: str) -> bool`	Download started; return True to prevent it (requires 0.3.1+)

Example:

Python

from jadeui import Window

window = Window(title="Event Example")

@window.on_resized
def handle_resize(width: int, height: int):
    print(f"Window size: {width} x {height}")

@window.on_moved
def handle_move(x: int, y: int):
    print(f"Window position: ({x}, {y})")

@window.on_focused
def handle_focus():
    print("Window gained focus")

@window.on_closing
def handle_closing():
    if has_unsaved_changes:
        return True  # Prevent closing
    return False

@window.on_page_loaded
def handle_loaded(url: str):
    print(f"Page finished loading: {url}")

window.show()

Events Constants Approach

You can also use the Events constants; the arguments are likewise parsed automatically:

Event constant	Event name	Callback arguments	Description
`Events.WINDOW_RESIZED`	window-resized	`(width, height)`	Size changed
`Events.WINDOW_MOVED`	window-moved	`(x, y)`	Position changed
`Events.WINDOW_FOCUSED`	window-focused	`()`	Gained focus
`Events.WINDOW_BLURRED`	window-blurred	`()`	Lost focus
`Events.WINDOW_CLOSING`	window-closing	`()`	About to close (return 1 to prevent it)
`Events.WINDOW_STATE_CHANGED`	window-state-changed	`(is_maximized,)`	State changed
`Events.WINDOW_FULLSCREEN`	window-fullscreen	`(is_fullscreen,)`	Fullscreen state changed (requires 1.2+)
`Events.FILE_DROP`	file-drop	`(files, x, y)`	File drop
`Events.WEBVIEW_WILL_NAVIGATE`	webview-will-navigate	`(url,)`	About to navigate
`Events.WEBVIEW_DID_FINISH_LOAD`	webview-did-finish-load	`(url,)`	Loading finished
`Events.WEBVIEW_NEW_WINDOW`	webview-new-window	`(url, frame_name)`	New window requested
`Events.WEBVIEW_PAGE_TITLE_UPDATED`	webview-page-title-updated	`(title,)`	Title updated
`Events.FAVICON_UPDATED`	favicon-updated	`(favicon,)`	Icon updated
`Events.WEBVIEW_DOWNLOAD_STARTED`	webview-download-started	`(url, filename)`	Download started (requires 0.3.1+)

Example:

Python

from jadeui import Window, Events

window = Window(title="Event Example")

# Arguments are parsed automatically; no json.loads needed
@window.on(Events.WINDOW_RESIZED)
def on_resize(width: int, height: int):
    print(f"Window size: {width} x {height}")

@window.on(Events.WEBVIEW_DID_FINISH_LOAD)
def on_page_load(url: str):
    print(f"Page finished loading: {url}")

window.show()

Internal Events

Event name	Callback arguments	Description
created	Window	Window creation complete
closed	-	Window has closed
page-loaded	url, status	Page finished loading

drag-drop / file-drop Event Details

The low-level JadeView 2.x event is drag-drop, fired for the enter, over, drop, and leave phases. The SDK keeps file-drop / on_file_dropped as a compatibility wrapper that fires only for the final drop.

Callback arguments:

Parameter	Type	Description
files	List[str]	List of dropped file paths
x	int	X coordinate of the drop location
y	int	Y coordinate of the drop location

Example:

Python

from jadeui import Window

window = Window(title="File Drop Example")

@window.on_file_dropped
def on_file_drop(files: list, x: int, y: int):
    print(f"Dropped {len(files)} files at position ({x}, {y})")
    for file_path in files:
        print(f"  - {file_path}")

window.show()

Python

@window.on("drag-drop")
def on_drag_drop(data):
    print(data["type"], data.get("paths", []))
    # Starting with JadeView 2.3, returning True or a non-empty string in
    # enter/drop can synchronously intercept or consume the operation.
    return False

Note

Using the file-drop event takes over the WebView's drag-and-drop event handling, which means the frontend will not receive native drag-and-drop events. If you need to handle drag-and-drop events in the frontend, do not register this event.

download-started Event Details

The webview-download-started event is triggered when a file download begins in the WebView.

Version Requirement

This event requires JadeView DLL 0.3.1 or later.

Callback arguments:

Parameter	Type	Description
url	str	URL of the file being downloaded
filename	str	Suggested file name

Return value:

Return True or 1: prevent the download
Return False, 0, or None: allow the download (default behavior)

Example:

Python

from jadeui import Window

window = Window(title="Download Event Example")

@window.on_download_started
def on_download(url: str, filename: str):
    print(f"Download request: {filename}")
    print(f"Source: {url}")
    
    # Prevent executable file downloads
    if filename.endswith((".exe", ".msi", ".bat")):
        print("Blocked an executable file download")
        return True
    
    # Prevent downloads from untrusted domains
    if "untrusted-site.com" in url:
        return True
    
    return False  # Allow the download

window.show()

IPCManager

The IPC communication manager, which handles communication between the Python backend and the web frontend.

Constructor

Python

ipc = IPCManager()

Methods

register_handler()

Registers a message handler.

Python

def handler(window_id: int, message: str) -> int:
    print(f"Received: {message}")
    return 1

ipc.register_handler("channel-name", handler)

Parameter	Type	Description
channel	str	Channel name
handler	Callable	Handler function

send()

Sends a message to a window.

Python

ipc.send(window_id, "channel-name", "message content")

Parameter	Type	Description
window_id	int	Target window ID
channel	str	Channel name
message	str	Message content

remove_handler()

Removes a message handler.

Python

ipc.remove_handler("channel-name")

list_handlers()

Lists all registered channels.

Python

channels = ipc.list_handlers()

Return value: list[str]

Decorators

@on()

Registers a handler using a decorator.

Python

@ipc.on("greet")
def handle_greet(window_id, message):
    print(f"Received: {message}")
    ipc.send(window_id, "response", "Hello!")
    return 1

LocalServer

A local HTTP server used to host web content.

Constructor

Python

server = LocalServer()

Methods

start()

Starts the server.

Python

url = server.start(
    app_name="myapp",    # Kept for compatibility; not used by JadeView 2.x
    root_path="./web",   # Static root
    hot_reload=False,    # Hot reload (forced off for .japk files)
    japk=None,           # Optional .japk path (overrides root_path)
    from_memory=False,   # True when a JAPK is already loaded in memory
)
print(f"Server running at: {url}")

Parameter	Type	Description
root_path	str	Static file root directory
app_name	str	Application identifier
hot_reload	bool	Whether to enable hot reload
japk	str \| None	Path to a `.japk` file; overrides `root_path` when set
from_memory	bool	Set `True` when a JAPK is already loaded in memory

Return value: str - The server URL

stop()

Stops the server.

Python

server.stop()

get_url()

Gets the full URL of a file.

Python

url = server.get_url("index.html")

Return value: str

Properties

Property	Type	Description
is_running	bool	Whether the server is running
url	str \| None	The server URL

Router

A backend-driven routing system that supports built-in templates and custom templates.

Constructor

Python

router = Router(ipc=None)  # An IPCManager instance can be passed in

Methods

page()

Registers a page route.

Python

router.page(
    path="/",                    # Route path
    template="pages/home.html",  # Template file
    title="Home",                # Page title
    icon="🏠",                   # Icon (shown in the sidebar)
    show_in_nav=True,            # Whether to show in the navigation bar
)

Parameter	Type	Default	Description
path	str	-	Route path, supports parameters (e.g. `/user/:id`)
template	str	-	Template file path
title	str	"Page"	Page title
icon	str	""	Page icon
show_in_nav	bool	True	Whether to show in the navigation

Return value: Router (method chaining)

mount()

Mounts the router and creates a window.

Python

window = router.mount(
    title="My App",          # Window title
    web_dir="web",           # Web file directory
    width=1024,              # Window width
    height=768,              # Window height
    sidebar_width=220,       # Sidebar width
    theme="system",          # Theme
    initial_path="/",        # Initial route
    template=None,           # Custom template (None uses the built-in one)
    head_links=[],           # Additional CSS links
    scripts=[],              # Additional JS scripts
    **window_options         # Other window options
)

Return value: Window

go()

Navigates to a specified route.

Python

router.go("/settings")
router.go("/user/123")  # With a parameter

Return value: bool - Whether it succeeded

set_theme()

Sets the application theme.

Python

router.set_theme("light")  # light, dark, system

set_backdrop()

Sets the window backdrop material.

Python

router.set_backdrop("mica")  # mica, micaAlt, acrylic

Properties

Property	Type	Description
current_route	str	Current route path
window	Window \| None	The associated window instance

Dialog

The dialog API, which provides file open, file save, and message box functionality.

Version Requirement

The Dialog API requires JadeView DLL 1.3.0 or later.

Methods

show_open_dialog()

Shows an open-file dialog.

Python

from jadeui import Dialog

# Blocking mode (default)
Dialog.show_open_dialog(
    window_id=1,
    title="Select an image",
    default_path="C:/",
    filters=[
        {"name": "Images", "extensions": ["png", "jpg", "gif"]},
        {"name": "All files", "extensions": ["*"]}
    ],
    properties=["openFile", "multiSelections"]
)

# Non-blocking mode + callback
def on_result(result):
    print(f"Selected: {result}")

Dialog.show_open_dialog(
    window_id=1,
    title="Select a file",
    properties=["openFile"],
    blocking=False,
    callback=on_result
)

Parameter	Type	Description
window_id	int	Parent window ID
title	str \| None	Dialog title
default_path	str \| None	Default path to open
button_label	str \| None	Custom label for the confirm button
filters	list \| None	File filters, e.g. `[{"name": "图片", "extensions": ["png", "jpg"]}]`
properties	list \| None	Dialog properties: `openFile`, `openDirectory`, `multiSelections`, `showHiddenFiles`
blocking	bool	Whether to block (default True)
callback	Callable	Callback function (used in non-blocking mode)

Return value: int - 1 for success, 0 for failure

show_save_dialog()

Shows a save-file dialog.

Python

Dialog.show_save_dialog(
    window_id=1,
    title="Save document",
    default_path="document.txt",
    filters=[{"name": "Text files", "extensions": ["txt"]}]
)

Parameter	Type	Description
window_id	int	Parent window ID
title	str \| None	Dialog title
default_path	str \| None	Default save path/file name
button_label	str \| None	Custom label for the confirm button
filters	list \| None	File filters
blocking	bool	Whether to block (default True)
callback	Callable	Callback function (used in non-blocking mode)

Return value: int - 1 for success, 0 for failure

show_message_box()

Shows a message box.

Python

Dialog.show_message_box(
    window_id=1,
    title="Confirm deletion",
    message="Are you sure you want to delete this file?",
    detail="This operation cannot be undone",
    type_="warning",
    buttons=["Delete", "Cancel"],
    default_id=1,
    cancel_id=1
)

Parameter	Type	Description
window_id	int	Parent window ID
title	str \| None	Message box title
message	str \| None	Message content
detail	str \| None	Detailed information
buttons	list \| None	List of button labels, e.g. `["确定", "取消"]`
default_id	int	Index of the button selected by default
cancel_id	int	Index of the cancel button (triggered when ESC is pressed)
type_	str	Message type: `none`, `info`, `error`, `warning`, `question`
blocking	bool	Whether to block (default True)
callback	Callable	Callback function (used in non-blocking mode)

Return value: int - 1 for success, 0 for failure

show_error_box()

Shows an error box (simplified version).

Python

Dialog.show_error_box(1, "Error", "Failed to read the file!")

Convenience Methods

confirm()

Shows a confirmation dialog.

Python

Dialog.confirm("Are you sure you want to quit?")
Dialog.confirm("Delete file?", title="Confirm", ok_label="Delete", cancel_label="Cancel")

alert()

Shows an alert dialog.

Python

Dialog.alert("Operation succeeded!")
Dialog.alert("Please note!", type_="warning")

error()

Shows an error dialog.

Python

Dialog.error("Failed to save the file!")

Constants

MessageBoxType

Message box type constants.

Python

from jadeui import MessageBoxType

MessageBoxType.NONE      # "none"
MessageBoxType.INFO      # "info"
MessageBoxType.WARNING   # "warning"
MessageBoxType.ERROR     # "error"
MessageBoxType.QUESTION  # "question"

OpenDialogProperties

Open-dialog property constants.

Python

from jadeui import OpenDialogProperties

OpenDialogProperties.OPEN_FILE         # "openFile"
OpenDialogProperties.OPEN_DIRECTORY    # "openDirectory"
OpenDialogProperties.MULTI_SELECTIONS  # "multiSelections"
OpenDialogProperties.SHOW_HIDDEN_FILES # "showHiddenFiles"

Notification

The desktop notification API, with support for Windows system notifications.

Version Requirement

The Notification API requires JadeView DLL 1.3.0 or later. Windows 10+ only.

Methods

config()

Configures the notification application information (optional, has default values).

Python

from jadeui import Notification

Notification.config(
    app_name="My App",
    icon="C:/path/to/icon.ico"  # Absolute path
)

Parameter	Type	Description
app_name	str \| None	Application display name (default "JadeUI App")
icon	str \| None	Application icon path (absolute path)

show()

Shows a simple notification (no buttons).

Python

Notification.show("Notice", "Operation complete")
Notification.show("Downloading", "Downloading file...", timeout=5000)

Parameter	Type	Description
title	str	Notification title (required)
body	str \| None	Notification content
icon	str \| None	Icon path (overrides the config setting)
timeout	int	Timeout (milliseconds; ≤ 0 uses the default)

Return value: bool - Returns True if shown successfully

with_buttons()

Shows a notification with buttons (up to two buttons).

Python

Notification.with_buttons(
    "Download complete",
    "video.mp4 has been downloaded",
    "Open",       # First button
    "Dismiss",    # Second button (optional)
    action="download_123"  # Action identifier
)

Parameter	Type	Description
title	str	Notification title
body	str	Notification content
button1	str	First button text
button2	str \| None	Second button text (optional)
icon	str \| None	Icon path
timeout	int	Timeout
action	str \| None	Action identifier, used to identify the notification in the callback

Return value: bool - Returns True if shown successfully

on()

Registers a notification event listener.

Python

from jadeui import Notification, Events

@Notification.on(Events.NOTIFICATION_ACTION)
def on_action(data):
    # data = {
    #     "action": "action_0",      # Button index
    #     "title": "打开",           # Button text
    #     "arguments": "download_123" # The action argument you passed in
    # }
    print(f"Button clicked: {data}")

@Notification.on(Events.NOTIFICATION_DISMISSED)
def on_dismissed(data):
    print("Notification was dismissed")

Supported events:

Event	Description
`Events.NOTIFICATION_ACTION`	The user clicked a notification button
`Events.NOTIFICATION_SHOWN`	The notification was shown successfully
`Events.NOTIFICATION_DISMISSED`	The notification was dismissed
`Events.NOTIFICATION_FAILED`	The notification failed to show

Convenience Methods

Python

Notification.info("Title", "Content")
Notification.success("Title", "Content")
Notification.warning("Title", "Content")
Notification.error("Title", "Content")

Complete Example

Python

from jadeui import Notification, Events

# 1. Configure the application information
Notification.config(app_name="My App", icon="C:/app/icon.ico")

# 2. Listen for button click events
@Notification.on(Events.NOTIFICATION_ACTION)
def on_action(data):
    action_id = data.get("arguments")  # Get the action argument
    button = data.get("action")        # Button index

    if action_id == "download_123":
        if button == "action_0":
            print("The user clicked \"Open\"")
        elif button == "action_1":
            print("The user clicked \"Dismiss\"")

# 3. Send the notification
Notification.with_buttons(
    "Download complete",
    "video.mp4 has been downloaded",
    "Open",
    "Dismiss",
    action="download_123"
)

Clipboard

System clipboard text API. Requires JadeView 2.x.

Python

from jadeui import Clipboard

Clipboard.write_text("Hello JadeUI")
text = Clipboard.read_text()

Method	Description
`Clipboard.write_text(text)`	Writes text; returns `True` on success
`Clipboard.read_text(buffer_size=65536)`	Reads text; returns `None` when empty or failed

System

System information and v2.3 system integration APIs.

Python

from jadeui import System

print(System.is_windows_11())
print(System.locale())
print(System.displays())
print(System.get_path("desktop"))
print(System.jadeview_version())
print(System.webview_version())

Method	Description
`System.is_windows_11()`	Whether the current system is Windows 11
`System.locale()`	System locale, such as `en-US`
`System.displays()`	Display information list
`System.cursor_position()`	Current cursor position
`System.get_path(name)`	Gets a system path such as `desktop`, `documents`, `appdata`, or `temp`
`System.webview_version()`	WebView2 Runtime version
`System.jadeview_version()`	JadeView DLL version
`System.set_login_autostart(enable=True, args=None)`	v2.3: set login autostart
`System.get_login_autostart()`	v2.3: query login autostart status
`System.register_url_scheme(scheme, ...)` / `unregister_url_scheme`	v2.3: register / unregister a custom URL scheme
`System.register_file_association(...)`	v2.3: register a file association
`System.register_resource` / `unregister_resource` / `clear_window_resources`	v2.3: per-window resources (`None/0` default TTL, `-1` never expire)
`System.printer_list()` / `System.print_file(...)`	v2.3: list printers / print a file
`System.clear_data_directory(confirm=True)`	v2.3: clear data directory (requires `CLEAR_DATA_CONFIRM_TOKEN`)
`System.convert_encoding` / `gbk_to_utf8` / `utf8_to_gbk`	v2.3: encoding helpers
`System.get_file_icon(path, size=48, window_id=0, ttl_seconds=0)`	v2.3: extract a file/folder icon and return a `jade://` URL
`System.ntp_now(server=None)`	v2.3: get an NTP UTC millisecond timestamp; returns `None` on network failure

Native context menus. Prefer Menu.attach_context_menu: items are created inside the context-menu callback (official flow).

Python

from jadeui import Menu, Window

window = Window(title="Menu Demo", disable_right_click=False)

Menu.attach_context_menu(window, [
    {"label": "Reload", "on_click": lambda: window.reload()},
    {"type": "separator"},
    {"label": "copy", "type": "native"},  # WebView2 native menu Name
    {
        "label": "More",
        "type": "submenu",
        "children": [
            {"label": "About", "on_click": lambda: print("about")},
        ],
    },
])

When type="native", label must be a WebView2 native menu Name such as "copy" or "paste".

Storage

YAML persistence API. Requires JadeView 2.3+; use it after app.on_ready.

Python

from jadeui import Storage

Storage.set("settings", "window.width", 1024)
Storage.set_str("settings", "literal", "true")

print(Storage.get("settings", "window.width"))
print(Storage.get_all("settings", {}))
print(Storage.keys("settings", "window"))
print(Storage.length("settings", "window"))

Method	Description
`Storage.set(file_name, key_path, value)`	Writes a value; non-string values are serialized as JSON
`Storage.set_str(file_name, key_path, value)`	Writes a literal string
`Storage.get(file_name, key_path, default=None)`	Reads a path value
`Storage.get_str(file_name, key_path, default=None)`	Reads a value as a literal string (pairs with `set_str`; keeps `"123"` a string)
`Storage.get_all(file_name, default=None)`	Reads the whole YAML file
`Storage.has(file_name, key_path)`	Checks whether a path exists
`Storage.delete(file_name, key_path)`	Deletes a path
`Storage.clear(file_name)`	Clears the file to `{}`
`Storage.delete_file(file_name)`	Deletes the YAML file
`Storage.keys(file_name, key_path="")`	Lists keys under a path
`Storage.length(file_name, key_path="")`	Returns object key count or array length

Tray

System tray API. Requires JadeView 2.x and is usually created after app.on_ready.

Python

from jadeui import Tray

tray = Tray()
tray.set_tooltip("JadeUI App")
tray.set_icon("C:/app/icon.ico")
tray.set_menu([
    {"key": "show", "label": "Show window", "on_click": lambda: window.show()},
    {"type": "separator", "key": "sep"},
    {"key": "quit", "label": "Quit", "dangerous": True, "on_click": app.quit},
])
tray.show()

Method	Description
`set_tooltip(text)`	Sets the tooltip
`set_icon(icon_path)`	Sets the tray icon from a file
`set_icon_from_bytes(data)`	Sets the tray icon from bytes
`set_menu(items)`	Sets the context menu
`on_click(callback)`	Listens for tray click events
`show()` / `hide()`	Shows or hides the tray icon
`destroy()`	Destroys the tray icon

HotKey

Global hotkey API. Requires JadeView 2.x.

Python

from jadeui import HotKey

@HotKey.register("Ctrl+Alt+J")
def on_hotkey():
    window.flash(3)

hotkey_id = HotKey.register("Alt+F1", lambda: print("F1"))
HotKey.unregister(hotkey_id)

Method	Description
`HotKey.register(combo, callback=None)`	Registers a global hotkey; can be used as a decorator
`HotKey.unregister(hotkey_id)`	Unregisters a hotkey
`HotKey.unregister_all()`	Unregisters all hotkeys

EventEmitter

The event emitter base class, which provides event subscription and publishing functionality.

Methods

on()

Registers an event listener.

Python

# Method form
emitter.on("event", callback)

# Decorator form
@emitter.on("event")
def callback(data):
    pass

off()

Removes an event listener.

Python

emitter.off("event", callback)  # Remove a specific listener
emitter.off("event")            # Remove all listeners for the event

emit()

Triggers an event.

Python

emitter.emit("event", arg1, arg2, key=value)

Return value: bool - Whether any listener was called

once()

Registers a one-time listener.

Python

@emitter.once("event")
def callback():
    pass  # Will only be called once

remove_all_listeners()

Removes all listeners.

Python

emitter.remove_all_listeners("event")  # A specific event
emitter.remove_all_listeners()         # All events

listener_count()

Gets the number of listeners.

Python

count = emitter.listener_count("event")

event_names()

Gets the names of all events that have listeners.

Python

names = emitter.event_names()

Constants

Theme

Window theme constants.

Python

from jadeui import Theme

Theme.LIGHT   # "Light"
Theme.DARK    # "Dark"
Theme.SYSTEM  # "System"

Backdrop

Windows 11 backdrop material constants.

Python

from jadeui import Backdrop

Backdrop.MICA      # "mica"
Backdrop.MICA_ALT  # "micaAlt"
Backdrop.ACRYLIC   # "acrylic"

Events

Standard event name constants. Using these constants instead of hand-written strings is recommended, as it is more type-safe.

Python

from jadeui import Events

# Application lifecycle events
Events.APP_READY          # "app-ready"
Events.WINDOW_ALL_CLOSED  # "window-all-closed"
Events.BEFORE_QUIT        # "before-quit"

# Window events
Events.WINDOW_CREATED         # "window-created"
Events.APP_WINDOW_CREATED     # "app-window-created"
Events.WINDOW_CLOSED          # "window-closed"
Events.WINDOW_CLOSING         # "window-closing"
Events.WINDOW_RESIZED         # "window-resized"
Events.WINDOW_STATE_CHANGED   # "window-state-changed"
Events.WINDOW_FULLSCREEN      # "window-fullscreen" (requires 1.2+)
Events.WINDOW_MOVED           # "window-moved"
Events.WINDOW_FOCUSED         # "window-focused"
Events.WINDOW_BLURRED         # "window-blurred"
Events.WINDOW_DESTROYED       # "window-destroyed"
Events.RESIZED                # "resized" (legacy compatibility format)

# WebView events
Events.WEBVIEW_WILL_NAVIGATE      # "webview-will-navigate"
Events.WEBVIEW_DID_START_LOADING  # "webview-did-start-loading"
Events.WEBVIEW_DID_FINISH_LOAD    # "webview-did-finish-load"
Events.WEBVIEW_NEW_WINDOW         # "webview-new-window"
Events.WEBVIEW_PAGE_TITLE_UPDATED # "webview-page-title-updated"
Events.WEBVIEW_PAGE_ICON_UPDATED  # "webview-page-icon-updated"
Events.FAVICON_UPDATED            # "favicon-updated"
Events.JAVASCRIPT_RESULT          # "javascript-result"
Events.WEBVIEW_DOWNLOAD_STARTED   # "webview-download-started" (requires 0.3.1+)
Events.POSTMESSAGE_RECEIVED       # "postmessage-received" (requires 1.0.2+)

# File events
Events.FILE_DROP          # "file-drop"

# Theme events
Events.THEME_CHANGED      # "theme-changed"

# Notification events (requires 1.3.0+)
Events.NOTIFICATION_ACTION    # "notification-action" (user clicked a button)
Events.NOTIFICATION_SHOWN     # "notification-shown" (notification shown successfully)
Events.NOTIFICATION_DISMISSED # "notification-dismissed" (notification was dismissed)
Events.NOTIFICATION_FAILED    # "notification-failed" (notification failed to show)

# Other events
Events.UPDATE_WINDOW_ICON # "update-window-icon"
Events.IPC_MESSAGE        # "ipc-message"

Listening for Events with Typed Decorators

Python

from jadeui import Window

window = Window(title="Event Example")

# Arguments are parsed automatically, and IDE type hints are provided
@window.on_resized
def on_resize(width: int, height: int):
    print(f"Window size changed: {width} x {height}")

@window.on_moved
def on_move(x: int, y: int):
    print(f"Window position: ({x}, {y})")

@window.on_focused
def on_focus():
    print("Window gained focus")

@window.on_blurred
def on_blur():
    print("Window lost focus")

@window.on_page_loaded
def on_page_load(url: str):
    print(f"Page finished loading: {url}")

# Prevent the window from closing
@window.on_closing
def on_closing():
    return True  # Return True to prevent closing

# Intercept new window requests
@window.on_new_window
def on_new_window(url: str, frame_name: str):
    print(f"Intercepted new window: {url}")
    window.navigate(url)  # Open in the current window
    return True  # Prevent a new window from opening

# Listen for file download events (requires 0.3.1+)
@window.on_download_started
def on_download(url: str, filename: str):
    print(f"Download request: {filename} from {url}")
    if filename.endswith(".exe"):
        return True  # Prevent .exe file downloads
    return False

# Listen for fullscreen state changes (requires 1.2+)
@window.on_fullscreen_changed
def on_fullscreen(is_fullscreen: bool):
    print(f"Fullscreen state: {is_fullscreen}")

window.show()

Type Definitions

RGBA

A color struct.

Python

from jadeui import RGBA

color = RGBA(r=255, g=128, b=64, a=255)

WebViewWindowOptions

The window configuration options struct.

WebViewSettings

The WebView behavior settings struct.

Exceptions

JadeUIError

The base class for all JadeUI exceptions.

DLLLoadError

DLL failed to load.

WindowCreationError

Window creation failed.

IPCError

IPC communication error.

ServerError

Local server error.

InitializationError

SDK initialization error.

Python

from jadeui import JadeUIError, WindowCreationError

try:
    window = Window(title="Test")
    window.show()
except WindowCreationError as e:
    print(f"Window creation failed: {e}")
except JadeUIError as e:
    print(f"JadeUI error: {e}")

Utility Functions

create_app()

Quickly creates an application instance.

Python

from jadeui import create_app, Window

app = create_app(
    enable_dev_tools=True,
    log_file="app.log"
)

@app.on_ready
def setup():
    Window(title="My App").show()

app.run()

utils.get_resource_path()

Gets the absolute path of a resource file, compatible with packaged environments.

Python

from jadeui import utils

path = utils.get_resource_path("assets/icon.png")

utils.show_error()

Shows an error message.

Python

from jadeui import utils

utils.show_error("Error", "An error occurred")

utils.ensure_directory()

Ensures a directory exists.

Python

from jadeui import utils

utils.ensure_directory("./data/cache")

DLL Download Tools

Prefer the CLI: jadeui download (see CLI). The following are Python APIs.

download_dll()

Downloads the JadeView DLL.

Python

from jadeui import download_dll

download_dll(force=False)  # force=True forces a re-download

ensure_dll()

Ensures the DLL exists, downloading it if it does not.

Python

from jadeui import ensure_dll

ensure_dll()

find_dll()

Finds the DLL file path.

Python

from jadeui import find_dll

path = find_dll()

get_architecture()

Gets the current system architecture.

Python

from jadeui import get_architecture

arch = get_architecture()  # "x64" or "x86"

v2.3 DLL Rule

get_architecture() returns x86, x64, or arm64 based on the current Python interpreter architecture. The downloader only selects the latest build inside the SDK-adapted release tag and never automatically crosses compatibility boundaries such as 2.2 -> 2.3.