Window API

The Window API provides everything you need to create and manage windows, including creating windows, resizing, setting themes, and more.

For WebView-related operations such as page navigation, script execution, DevTools, and printing, see WebView API.

For unified interception of web permission requests (camera, microphone, display capture, file access, etc.), see Web Permission API.

All of the following functions target a specific window_id (the integer returned when the window was created). Unless otherwise noted, success is usually 1 and failure is 0.


Configuration starts with struct_size / abi_version. Initialize with window_options_default(out, sizeof(*out)), which returns JADE_OK on success; pass NULL to creation to use defaults. See V3 ABI.

Creating Windows

default uses the system frame and caption; BarOverlay adds a title-bar button overlay that reserves only the button rectangles, not page height — custom headers must leave space. Both styles show left navigation buttons; Back appears only when there is history. Configure button colors and height with set_titlebar_style.

Non-default background_material values require Windows 11: set them before the window is shown and the WebView is created, and use a transparent page background to see the material. Linux and Windows 10 reject them; a failed system setting puts the window into a failed state.

Create a Normal Window

Creates a browser window with a system title bar and border, running a WebView inside it. This is the most common way to create a main window.

C
uint32_t create_webview_window(const char* url, uint32_t parent_window_id, const struct WebViewWindowOptions* options, const struct WebViewSettings* webview_settings);

Parameters:

  • url string - The URL or local protocol address to open first

  • parent_window_id uint32_t - Parent window; 0 means a top-level window

  • options WebViewWindowOptions* (optional) - Window appearance configuration; pass NULL to use defaults

    WebViewWindowOptions options:

    • title string - The text shown in the window's title bar
    • width int32_t - Initial width (pixels)
    • height int32_t - Initial height (pixels)
    • resizable int32_t - Whether the user can resize the window by dragging its edges with the mouse
    • noframe int32_t - Borderless: 1 uses the existing borderless implementation, 0 keeps the system frame; borderless takes precedence over the system title bar
    • transparent int32_t - Whether to use a transparent background (depends on the WebView and system capabilities)
    • background_color string - Window background color string (e.g. hexadecimal with a #)
    • always_on_top int32_t - Whether to keep the window always on top
    • theme string - Light / Dark / follow system (Light, Dark, System)
    • maximized int32_t - Whether to start maximized
    • maximizable int32_t - Whether the maximize button in the title bar is enabled
    • minimizable int32_t - Whether the minimize button in the title bar is enabled
    • x int32_t - X coordinate of the window's top-left corner; setting both to -1 lets the system center it for you
    • y int32_t - Y coordinate of the window's top-left corner; setting both to -1 lets the system center it for you
    • min_width int32_t - Minimum allowed width; 0 usually means no limit
    • min_height int32_t - Minimum allowed height; 0 usually means no limit
    • max_width int32_t - Maximum allowed width; 0 usually means no limit
    • max_height int32_t - Maximum allowed height; 0 usually means no limit
    • fullscreen int32_t - Whether to start in fullscreen
    • focus int32_t - Whether to grab keyboard focus after opening
    • hide_window int32_t - When non-zero, create the window but don't show it (good for loading first, then calling show)
    • use_page_icon int32_t - Whether to use the web page's favicon as the initial window icon (supported on both Windows and Linux; extracting the icon from the exe is Windows only)
    • content_protection int32_t - Whether to enable screen-recording/screenshot protection (Windows only; Linux/X11 has no system-level equivalent — the setting does not error but provides no actual protection)
    • auto_save_state int32_t - Non-0: records the window's last valid physical top-left coordinates by window_id in window_state.yaml under the data directory; the next time a window is created with the same window_id, if that position still falls within the work area of some monitor, the position is restored (width, height, and maximized state still follow the parameters of this creation call). The state is debounced and written to disk roughly 450ms after the window stops moving, and is saved once more on close
    • skip_taskbar int32_t - Whether to keep the window out of the taskbar / Alt-Tab (0 = no, 1 = yes). appended at the end of the struct to keep field order compatible (use set_window_skip_taskbar at runtime, see "Window Flags & Level" below)
    • no_activate int32_t - Whether to avoid stealing focus: neither clicking nor showing the window activates it (0 = no, 1 = yes). appended at the end of the struct to keep field order compatible (use set_window_no_activate at runtime, see "Window Flags & Level" below)
    • titlebar_back int32_t - Windows Back button enabled: 0/1, default 1; shared by default caption and BarOverlay
    • titlebar_refresh int32_t - Windows Refresh button enabled: 0/1, default 1; shared by default caption and BarOverlay
    • titlebar_icon int32_t - Default-caption window icon visible: 0/1, default 1; does not affect the taskbar icon
    • background_material string - Background material at creation: default / mica / micaAlt / acrylic; NULL means default
  • webview_settings WebViewSettings* (optional) - Web page behavior configuration; pass NULL to use defaults

    WebViewSettings options:

    • autoplay int32_t - Whether media is allowed to autoplay
    • background_throttling int32_t - Windows: 0 and 2 use the engine default; 1 disables background timer throttling via a WebView2 browser argument. Linux rejects 1 and 2
    • allow_right_click int32_t - Whether to allow the web page's right-click menu. 0 = disabled, 1 = allowed; unset (or passing NULL for the whole webview_settings) defaults to allowed
    • user_agent string - Custom User-Agent
    • preload_js string - A snippet of JS to inject before the page loads
    • allow_fullscreen int32_t - Whether the fullscreen API is allowed within the web page
    • postmessage_allowed_origins string - A whitelist that determines whether the page's postMessage calls are forwarded to the main process, given as a comma- or semicolon-separated UTF-8 string (usually close to the page's origin, e.g. https://example.com). When matching, the library passes if event.origin equals the string, or if one of the comma- or semicolon-separated allowed origins matches exactly, or an entry is *. If the pointer is NULL/unset: under the current implementation, no origin is allowed through (i.e. you won't receive postmessage-received). Built-in static pages loaded via set_protocol_service_path skip the whitelist in the implementation and are always able to receive
    • cors_allowed_origins string - CORS origin whitelist, a comma- or semicolon-separated list of domains (e.g. "http://198.18.0.1:8001, http://localhost:3000").
      • Exact origin matching is used; * allows all origins. On Windows, when unset (NULL) or empty, the custom-protocol IPC path allows any Origin, including remote pages; set the whitelist explicitly to restrict it. Linux local HTTPS ignores this field and enforces the per-view origin and random credentials instead.
    • password_autofill int32_t - Whether to enable account/password autofill. 0 = disabled, 1 = enabled.
    • form_autofill int32_t - Whether to enable general form autofill (name/address/phone, etc.). 0 = disabled, 1 = enabled.
    • incognito int32_t - Whether to run in incognito/private browsing mode. 0 = normal mode, 1 = incognito mode. Page rendering becomes slower when enabled.
    • disable_clipboard int32_t - Whether to disable clipboard read/write permissions. 0 = allowed, 1 = disabled.
    • proxy_url string - Proxy URL; supports HTTP and SOCKS5 proxies (e.g. "http://127.0.0.1:7890" or "socks5://127.0.0.1:1080"). NULL means no proxy is used.
    • focused int32_t - Whether the WebView automatically gains focus initially. 0 = does not gain focus, 1 = autofocus (default 1).
    • profile_name string - appended at the end of the struct. NULL or an empty string uses the default profile; a non-empty string names an environment that isolates cookies, LocalStorage, IndexedDB, and cache. On Linux a named profile is exclusive per view (including incognito and remote-initial-page views): a second live WebView with the same name fails to create. The name must be at most 64 characters, contain only letters, digits, ., _, -, or spaces, and must not start or end with . or a space; invalid names fall back to the default profile.
    • devtools int32_t - DevTools: 0 follows global devmod, 1 enable for this view, 2 disable for this view

Return value:

  • > 0 - The window id; the window may actually be drawn slightly later, which you can pair with events such as window-created
  • 0 - Failure, for example calling it before app-ready

Create a Frameless Window

Creates a WebView window with no system title bar, suitable for scenarios such as custom-drawn title bars or floating tool windows. The frame style is fixed to frameless.

C
uint32_t create_borderless_webview_window(const char* url, const struct WebViewSettings* webview_settings);

Parameters:

  • url string - The URL or local protocol address to open first
  • webview_settings WebViewSettings* (optional) - Web page behavior configuration; pass NULL to use defaults

Return value:

A non-0 return is the window_id. Use this id for navigation, IPC, and executing JS, just like with a normal window.


Create an Empty Window (create_window)

Creates a native window with no WebView attached. To add page views to it, see WebView API.

C
uint32_t create_window(uint32_t parent_window_id, const struct WebViewWindowOptions* options);
  • parent_window_id uint32_t — parent Window ID; pass 0 when there is no parent
  • options const struct WebViewWindowOptions* — the same config struct the one-step creation entries use
  • Return value: uint32_t; non-zero is the accepted Window ID

Typical call order

C
/* Create a window: returns the Window ID */
uint32_t window_id = create_webview_window(url, 0, NULL, NULL);

/* Get the default view; every later page operation uses the WebView ID */
uint32_t view_id = get_default_webview(window_id);
send_ipc_message(view_id, "message", "hello");

To put several views in one window, attach extra WebViews with add_webview / add_webview_to_window from the WebView API.


Get Window Handle

When working in C/C++, an HWND is required to pass a window to other Win32 APIs (such as SetWindowPos or child control attachment).

Note: Only windows created via create_borderless_webview_window return a valid handle value. Regular windows created with create_webview_window always return 0.

C
size_t get_window_hwnd(uint32_t window_id);

Parameters:

  • window_id uint32_t – Target window ID

Get Window ID

Retrieve the Jadeview window ID from its window handle

C
uint32_t get_window_id(size_t hwnd);

Parameters:

  • hwnd int32_t – Target window handle

Specify the Default WebView (set_default_webview)

C
int32_t set_default_webview(uint32_t window_id, uint32_t webview_id);

Points the window's default association at the given view. window_id is a Window ID and webview_id is a WebView ID. After the association is cleared, check the default_webview_id field of get_window_state.


List All WebViews of a Window (get_window_webviews / free_webview_id_array)

C
int32_t get_window_webviews(uint32_t window_id, struct WebViewIdArray* out_array);
void free_webview_id_array(struct WebViewIdArray* array);

The result comes back in a WebViewIdArray; you must call free_webview_id_array to release the internal array when done.

C
typedef struct WebViewIdArray {
  const uint32_t *ids;
  size_t count;
} WebViewIdArray;

Query the Parent Window (get_webview_parent_window_id)

C
uint32_t get_webview_parent_window_id(uint32_t webview_id);

Takes a WebView ID and returns the Window ID that owns it.


Query Object State (get_window_state / get_webview_state)

C
int32_t get_window_state(uint32_t window_id, struct JadeObjectState* out);
int32_t get_webview_state(uint32_t webview_id, struct JadeObjectState* out);

The two functions take a Window ID and a WebView ID respectively, and write into the same struct:

C
typedef struct JadeObjectState {
  uint32_t kind;
  uint32_t state;
  uint32_t parent_window_id;
  uint32_t default_webview_id;
  int32_t error_code;
} JadeObjectState;
FieldC typeMeaning
kinduint32_tObject kind (Window / WebView)
stateuint32_tLifecycle state, see the table below
parent_window_iduint32_tOwning window of a WebView; not applicable to Window objects
default_webview_iduint32_tCurrent default view of the window; 0 when cleared
error_codeint32_tError code when the object entered a failed state

Object lifecycle state constants (include/JadeView.h):

ConstantValueMeaning
JADE_STATE_RESERVED1Slot reserved
JADE_STATE_CONFIGURED2Configured
JADE_STATE_CREATING3Creating
JADE_STATE_READY4Native instance usable
JADE_STATE_CLOSING5Closing
JADE_STATE_DESTROYING6Destroying
JADE_STATE_DESTROYED7Destroyed
JADE_STATE_FAILED8Failed
JADE_STATE_CRASHED9Crashed

Request results use a separate 1 accepted / 2 waiting / 3 succeeded / 4 failed / 5 cancelled numbering — see Core API. Do not mix the two.


Position, Size, and Title

Set the Window Title

Changes the text shown in the window's title bar (which can differ from the <title> in the HTML).

C
int32_t set_window_title(uint32_t window_id, const char* title);

Parameters:

  • window_id uint32_t - Target window id
  • title string - The new window title

Set the Window Size

Changes the window's width and height in pixels.

C
int32_t set_window_size(uint32_t window_id, int32_t width, int32_t height);

Parameters:

  • window_id uint32_t - Target window id
  • width int32_t - The new width (pixels)
  • height int32_t - The new height (pixels)

Set the Window Position

Changes the window's position on the screen in pixels.

C
int32_t set_window_position(uint32_t window_id, int32_t x, int32_t y);

Parameters:

  • window_id uint32_t - Target window id
  • x int32_t - The new X coordinate
  • y int32_t - The new Y coordinate

Get Window Position and Size (get_window_bounds)

C
int32_t get_window_bounds(uint32_t window_id, char* buffer, int32_t buffer_size);

Parameters:

  • window_id uint32_t - Target window id
  • buffer char* - Output buffer
  • buffer_size int - Buffer size

Return value: 1 = success, with the buffer written as JSON {"x":0,"y":0,"width":800,"height":600}; 0 = failure


Visibility and Focus

Show or Hide the Window

Shows or hides the window (visibility changes other than minimizing).

C
int32_t set_window_visible(uint32_t window_id, int32_t visible);

Parameters:

  • window_id uint32_t - Target window id
  • visible int32_t - Non-0 shows, 0 hides

Give the Window Focus

Gives the window keyboard focus.

C
int32_t set_window_focus(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Set the Window Always on Top

Whether to keep the window on top so it isn't covered by other normal windows.

C
int32_t set_window_always_on_top(uint32_t window_id, int32_t always_on_top);

Parameters:

  • window_id uint32_t - Target window id
  • always_on_top int32_t - Non-0 pins it on top, 0 unpins it

Set Ignore Cursor Events (set_window_ignore_cursor_events)

Sets whether the window ignores mouse events (mouse pass-through), suitable for floating window / overlay scenarios.

C
int32_t set_window_ignore_cursor_events(uint32_t window_id, int32_t ignore);
  • Parameters: window_id, ignore (1 = ignore mouse events / pass-through, 0 = normal)
  • Return value: 1 = success, 0 = failure

Titlebar Components (set_titlebar_components)

Windows only. Each call sets all five flags; every flag must be 0 or 1.

C
int32_t set_titlebar_components(uint32_t window_id, int32_t back,
    int32_t refresh, int32_t icon, int32_t minimize, int32_t maximize);

set_titlebar_components(window_id, 1, 1, 1, 1, 1);
  • back=1 shows Back only when the WebView has history; back=0 always hides it.
  • refresh shows Refresh in the default caption and BarOverlay. Refresh reloads the current page and is disabled while loading.
  • icon controls the window icon in the default caption, not the actual window or taskbar icon. BarOverlay does not draw an icon but keeps the flag for switching back.
  • minimize / maximize match the creation options minimizable / maximizable; they do not affect Close.
  • Creation options titlebar_back / titlebar_refresh / titlebar_icon default to 1. Runtime calls update them, and the settings survive title-bar style changes.
  • Left-hand buttons appear in title_bar_style=default and BarOverlay. BarOverlay reserves only the button rectangles, so custom page headers must leave space for them.
  • Title text is unaffected. Button colors are configured with set_titlebar_style.

Call after the window is ready. Returns 1 when queued, 0 on rejection; use jade_last_error_code/message for the cause. Non-Windows platforms and flags outside 0/1 are errors.

Python
window.set_titlebar_components(back=True, refresh=True, icon=True, minimize=True, maximize=True)

Window Flags & Level

For scenarios such as side docks, floating panels, desktop widgets, and launchers: keep the window out of the taskbar / Alt-Tab, avoid stealing focus while it stays resident, or push the window down to the desktop wallpaper layer.

Skip the Taskbar / Alt-Tab (set_window_skip_taskbar)

Hides the window from the taskbar and the Alt-Tab switcher; commonly used for floating tool windows and widgets. You can also set it at creation time via WebViewWindowOptions.skip_taskbar.

C
int32_t set_window_skip_taskbar(uint32_t window_id, int32_t skip);
  • Parameters: window_id; skip (1 = skip the taskbar / Alt-Tab, 0 = restore)
  • Return value: 1 = success, 0 = failure

Do Not Steal Focus (set_window_no_activate)

Keeps the window from gaining activation focus when clicked or shown, suitable for resident floating panels (clicking it won't interrupt your typing elsewhere). You can also set it at creation time via WebViewWindowOptions.no_activate.

C
int32_t set_window_no_activate(uint32_t window_id, int32_t no_activate);
  • Parameters: window_id; no_activate (1 = do not steal focus, 0 = restore)
  • Return value: 1 = success, 0 = failure

Set the Window Level (set_window_level)

Sets which layer the window sits on in one call — more flexible than plain "always on top": you can push the window below all others, or even pin it to the desktop wallpaper layer as a widget.

C
// level: "topmost" | "normal" | "bottom" | "desktop"
int32_t set_window_level(uint32_t window_id, const char* level);
  • Parameters: window_id; level string - the level string; see the table below
  • Return value: 1 = success, 0 = failure
levelBehaviorImplementation
topmostOn top, above normal windowsset_always_on_top(true) (cross-platform)
normalNormal layer; cancels topmost / bottomClears always-on-top / always-on-bottom
bottomBelow other windowsset_always_on_bottom(true) (cross-platform)
desktopPinned to the desktop wallpaper layer (only visible after minimizing all windows; widget-like)First bottom; on Windows parents to Progman / WorkerW, on Linux sets GTK WindowTypeHint::Desktop

Window State

Minimize the Window

Sends the window to the taskbar.

C
int32_t minimize_window(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Toggle the Maximized State

Toggles between maximized and restored.

C
int32_t toggle_maximize_window(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Query Whether Maximized

Queries whether the window is currently maximized.

C
int32_t is_window_maximized(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Return value:

  • 1 - Currently maximized
  • 0 - Currently not maximized

Set Fullscreen

Enters or exits fullscreen (filling the monitor, not just maximizing). The request takes effect asynchronously; you can also listen for the window-fullscreen event.

C
int32_t set_window_fullscreen(uint32_t window_id, int32_t fullscreen);

Parameters:

  • window_id uint32_t - Target window id
  • fullscreen int32_t - Non-0 enters fullscreen, 0 exits fullscreen

Query Whether the Window Is Minimized (is_window_minimized)

C
int32_t is_window_minimized(uint32_t window_id);
  • Parameters: window_id uint32_t
  • Return value: 1 = minimized, 0 = not

Query Whether the Window Is Visible (is_window_visible)

C
int32_t is_window_visible(uint32_t window_id);
  • Parameters: window_id uint32_t
  • Return value: 1 = visible, 0 = not visible

Query Whether the Window Is Focused (is_window_focused)

C
int32_t is_window_focused(uint32_t window_id);
  • Parameters: window_id uint32_t
  • Return value: 1 = focused, 0 = not

Query Whether the Window Is Fullscreen (is_window_fullscreen)

C
int32_t is_window_fullscreen(uint32_t window_id);
  • Parameters: window_id uint32_t
  • Return value: 1 = fullscreen, 0 = not

Window Constraints

Set the Window Minimum Size (set_window_min_size)

C
int32_t set_window_min_size(uint32_t window_id, int32_t width, int32_t height);
  • Parameters: window_id, width (minimum width), height (minimum height)
  • Return value: 1 = success, 0 = failure

Set the Window Maximum Size (set_window_max_size)

C
int32_t set_window_max_size(uint32_t window_id, int32_t width, int32_t height);
  • Parameters: window_id, width (maximum width), height (maximum height)
  • Return value: 1 = success, 0 = failure

Set Whether the Window Is Resizable (set_window_resizable)

C
int32_t set_window_resizable(uint32_t window_id, int32_t resizable);
  • Parameters: window_id, resizable (1 = resizable, 0 = not)
  • Return value: 1 = success, 0 = failure

Enable or Disable the Window

When a window is disabled, the user cannot click the controls on it (like the grayed-out window behind a modal dialog); pass non-0 to restore it.

C
int32_t set_window_enabled(uint32_t window_id, int32_t enabled);

Parameters:

  • window_id uint32_t - Target window id
  • enabled int32_t - Non-0 enables, 0 disables

Appearance and Style

Change the Window Frame at Runtime (set_window_frame)

Dynamically changes the window's frame style without recreating the window.

C
int32_t set_window_frame(uint32_t window_id, int32_t noframe, const char* title_bar_style);

Parameters:

  • window_id uint32_t - Target window id
    • noframe int32_t - Borderless: 1 uses the existing borderless implementation, 0 keeps the system frame; borderless takes precedence over the system title bar

Set the Title Bar Style (set_titlebar_style)

Windows only. Sets the height and button colors for both the default caption and BarOverlay.

C
int32_t set_titlebar_style(uint32_t window_id, int32_t height,
    const char* background_color, const char* foreground_color,
    const char* button_background_color,
    const char* button_hover_background_color, const char* button_hover_foreground_color);
ParameterMeaning
window_idTarget Window ID, not a WebView ID
height-1 keeps the current value; 0 restores the mode default; custom heights are 20–100 DIP; values outside this range are rejected
background_colorCaption background, default caption only
foreground_colorShared color for title text and normal button icons. Follows the theme by default. The title and unhovered buttons are dimmed when the window is inactive
button_background_colorNormal background of all buttons; transparent by default
button_hover_background_colorHover background of buttons other than Close
button_hover_foreground_colorHover icon color of buttons other than Close

Colors accept #RRGGBB, #RRGGBBAA, rgb(r,g,b) and rgba(r,g,b,a) (a in 0–1). Each call updates all colors. Pass NULL or an empty string to restore the window theme default. An invalid color rejects the whole update. Close keeps its red hover background and white glyph.

BarOverlay does not draw the caption background or title, but retains their settings for switching back to the default caption. Styles survive frame changes and are removed when the Window is destroyed.

Overlay controls belong to the Window (even empty ones) and survive navigation, zoom and default WebView destruction. They reserve no page height — keep content clear of both button groups. Controls hide in fullscreen and return on exit. The host EXE must declare Windows 8 or newer in its manifest.

Returns 1 when accepted or 0 when rejected; use jade_last_error_code/message for details. Non-Windows platforms return a platform error.

Python
window.set_titlebar_style(
    height=40,
    background_color="#202124",
    foreground_color="#F5F5F5",
    button_background_color="#00000000",
    button_hover_background_color="#3367D6",
    button_hover_foreground_color="#FFFFFF",
)

In Python, pass None or "", or omit a color argument to restore its default.


Set the Window Light/Dark Theme

Controls whether the window and WebView use the light theme, dark theme, or follow the system theme.

For more detailed information, see Theme Management.

C
int32_t set_window_theme(uint32_t window_id, const char* theme);

Parameters:

  • window_id uint32_t - Target window id
  • theme string - Theme string; available values: Light, Dark, System

Get the Current Window Theme

Queries the theme currently used by the window.

C
int32_t get_window_theme(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Return value:

  • 1 - Dark
  • 0 - Light

The System theme is resolved to 1 / 0 based on the current system light/dark setting; returns 0 if the window does not exist or the theme is unknown.


Set the Window Backdrop Material

Sets system backdrop materials such as Mica and Acrylic on Windows 11.

For available strings, see Theme Management.

C
int32_t set_window_backdrop(uint32_t window_id, const char* backdrop_type);

Parameters:

  • window_id uint32_t - Target window id
  • backdrop_type string - Backdrop material type

Set the Window Background Color

Sets the window's background color (hexadecimal string).

C
int32_t set_window_background_color(uint32_t window_id, const char* background_color_hex);

Parameters:

  • window_id uint32_t - Target window id
  • background_color_hex string - Background color hexadecimal string, e.g. #FF0000

Request a Redraw

Notifies the system to repaint the client area (rarely needs to be called manually).

C
int32_t request_redraw(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Taskbar Effects

Set the Taskbar Progress Bar (set_window_progress)

Displays a progress bar on the taskbar button (e.g. download progress, install progress, etc.).

C
int32_t set_window_progress(uint32_t window_id, int32_t progress, int32_t state);
  • Parameters:
    • window_id uint32_t
    • progress int - Progress value (0–100)
    • state int - State: 0=no progress, 1=normal, 2=paused (yellow), 3=error (red), 4=indeterminate
  • Return value: 1 = success, 0 = failure

Flash the Taskbar Icon (flash_window)

Flashes the taskbar icon to attract the user's attention (e.g. when a message arrives).

C
int32_t flash_window(uint32_t window_id, uint32_t count);
  • Parameters: window_id uint32_t; count uint32_t - Number of flashes, 0 = stop flashing
  • Return value: 1 = success, 0 = failure

Closing and Counting

Close the Window

Initiates closing; if the page registered a beforeunload handler and the user chooses to stay, closing may be deferred or canceled, depending on the WebView and the page script.

C
int32_t close_window(uint32_t window_id);

Parameters:

  • window_id uint32_t - Target window id

Close Flow

All close methods — window.close(), the title-bar close button and Alt+F4 — share one flow:

  1. Dispatch window-closing first (the host can intercept it; return a non-null pointer from the callback to block closing — see Event Types);
  2. Close the window and dispatch window-closed;
  3. When the last window closes, dispatch window-all-closed.

Close source and page URL: the event_data of the window-closing callback now distinguishes the source — {"source":"system"} means user-initiated (Alt+F4, system close button, title-bar close button); {"source":"frontend","url":"<page's current URL>"} means initiated by the frontend window.close(). The page URL is read directly from the WebView's current address by JadeView, not taken from a value the page reports.

Fallback: if a window is destroyed for any reason without going through the normal close flow, window-closed (and window-all-closed when all windows are closed) is still emitted afterward and the window state is cleaned up, so the host will not miss the close notification.


Get the Window Count

Queries how many windows are still open in the current JadeView.

C
uint32_t get_window_count(void);

Maximized or fixed-size windows retain the title-bar buttons.