Skip to content

application.md

Latest commit

 

History

History
217 lines (152 loc) · 6.23 KB

application.md

File metadata and controls

217 lines (152 loc) · 6.23 KB
Raw

Application

The root object that owns the event loop and all windows.

import { Application } from '@webviewjs/webview';
const app = new Application();

Constructor

new Application(options?: ApplicationOptions)

ApplicationOptions is accepted but currently unused; pass null or omit it.

Methods

run(options?)

Start the event pump. Calls pumpEvents() on a setInterval and returns immediately.

app.run(options?: { interval?: number; ref?: boolean }): void
Option Default Description
interval 16 Pump interval in ms
ref true If false the timer won't prevent process exit

runSync()

Run Tao's native event loop on the current thread and block JavaScript until the application exits.

app.runSync(): void

Use this only when you want the GUI loop to own the thread. In Node.js apps, run() is usually the safer default because it keeps the JS event loop available.

stop()

Clear the pump interval. The app object and windows remain valid.

app.stop(): void

exit()

Stop the pump, hide all tracked windows, and mark the application as exited. Subsequent pumpEvents() calls return false.

app.exit(): void

pumpEvents()

Process one batch of OS events without blocking. Returns true while alive, false when the app should exit. Normally called automatically by run().

app.pumpEvents(): boolean

whenReady(options?)

Resolve when wry emits its first native resumed() lifecycle callback. whenReady() starts the event pump by default:

app.whenReady().then(() => {
  const window = app.createBrowserWindow();
  window.createWebview({ url: 'https://example.com' });
});
type ApplicationWhenReadyOptions =
  | { autoRun?: true; interval?: number; ref?: boolean }
  | { autoRun: false; interval?: never; ref?: never };

app.whenReady(options?: ApplicationWhenReadyOptions): Promise<void>
app.isReady(): boolean

autoRun defaults to true; interval and ref are forwarded to run(). Use { autoRun: false } when manually calling run() or pumpEvents(). Manual mode rejects interval and ref because no implicit timer is created. Calls made after readiness still resolve asynchronously.

Application events

Application implements the standard Node.js EventEmitter API. Prefer this interface for new Node.js code:

app.on('window-close-requested', (event) => {
  console.log('window close requested', event);
});

app.on('application-close-requested', () => {
  app.exit();
});

app.on('custom-menu-click', ({ customMenuEvent }) => {
  console.log(customMenuEvent.id, customMenuEvent.windowId);
});
Event Fired when
window-close-requested A user requests that a window be closed
application-close-requested The last window has been closed
custom-menu-click A custom menu item is selected
ready The native event loop is ready

The usual on, once, off, addListener, removeListener, removeAllListeners, listenerCount, listeners, rawListeners, emit, and eventNames methods are available. Listener-registration and removal methods are chainable.

See the runnable application events example.

Legacy onEvent(handler) / bind(handler)

Register a callback for application-level events. Both names are equivalent aliases.

app.onEvent(handler: (event: ApplicationEvent) => void): void

ApplicationEvent:

interface ApplicationEvent {
  event: WebviewApplicationEvent; // enum value
  customMenuEvent?: { id: string; windowId: number };
}

WebviewApplicationEvent values:

Value Fired when
WindowCloseRequested User clicks the OS close button on a window
ApplicationCloseRequested The last window was closed
CustomMenuClick A custom menu item was clicked; see customMenuEvent.id
Ready The native event loop emitted its first resume event

createBrowserWindow(options?)

Create and return a new BrowserWindow.

app.createBrowserWindow(options?: BrowserWindowOptions): BrowserWindow

createChildBrowserWindow(options?)

Create a child/popup window. The webview fills a precise region inside the parent rather than the whole window.

app.createChildBrowserWindow(options?: BrowserWindowOptions): BrowserWindow

createWebContext(options?)

Create an isolated browser-data context that can be shared by multiple webviews.

app.createWebContext(options?: WebContextOptions): WebContext

Create contexts through the application rather than with new WebContext(). See the WebContext reference.

setMenu(options?)

Set the global application menu. Pass null to remove it.

app.setMenu(options?: MenuOptions): void

See Menus guide for the full options shape.

This API remains supported. Compare its numeric event value with the exported enum:

app.onEvent((event) => {
  if (event.event === WebviewApplicationEvent.ApplicationCloseRequested) {
    app.exit();
  }
});

Symbol.dispose

Application implements the TC39 Explicit Resource Management protocol. Use using to guarantee cleanup:

{
  using app = new Application();
  // …
} // app.exit() called automatically

Root-owned disposal

Resources created through an application are owned by that application. app.exit(), Symbol.dispose, and application finalization dispose tray icons, webviews, windows, web contexts, menus, and callbacks. Cleanup is idempotent. Retained resource wrappers report isDisposed() === true and reject subsequent method calls. Creating new resources after exit also fails.