0
# Window & Webview Management
1
2
Comprehensive control over application windows and webviews, including creation, positioning, styling, and advanced features like effects and drag operations.
3
4
## Capabilities
5
6
### Window Control
7
8
Main window management class providing complete control over window properties and behavior.
9
10
```typescript { .api }
11
/**
12
* Main window management class
13
*/
14
class Window {
15
constructor(window: WindowHandle, label: string, listeners: Map<string, EventCallback<any>>);
16
17
/**
18
* Get window by label
19
* @param label - Window identifier
20
* @returns Window instance or null if not found
21
*/
22
static getByLabel(label: string): Promise<Window | null>;
23
24
/**
25
* Get current window instance
26
* @returns Current window
27
*/
28
static getCurrent(): Window;
29
30
/**
31
* Get all window instances
32
* @returns Array of all windows
33
*/
34
static getAll(): Promise<Window[]>;
35
36
// Event handling
37
listen<T>(event: EventName, handler: EventCallback<T>, options?: EventOptions): Promise<UnlistenFn>;
38
once<T>(event: EventName, handler: EventCallback<T>, options?: EventOptions): Promise<UnlistenFn>;
39
emit<T>(event: string, payload?: T): Promise<void>;
40
emitTo<T>(target: EventTarget | string, event: string, payload?: T): Promise<void>;
41
42
// Position and size
43
outerPosition(): Promise<PhysicalPosition>;
44
innerPosition(): Promise<PhysicalPosition>;
45
outerSize(): Promise<PhysicalSize>;
46
innerSize(): Promise<PhysicalSize>;
47
setPosition(position: LogicalPosition | PhysicalPosition): Promise<void>;
48
setSize(size: LogicalSize | PhysicalSize): Promise<void>;
49
50
// Window state
51
isFullscreen(): Promise<boolean>;
52
isMinimized(): Promise<boolean>;
53
isMaximized(): Promise<boolean>;
54
isVisible(): Promise<boolean>;
55
isFocused(): Promise<boolean>;
56
isDecorated(): Promise<boolean>;
57
isResizable(): Promise<boolean>;
58
isMaximizable(): Promise<boolean>;
59
isMinimizable(): Promise<boolean>;
60
isClosable(): Promise<boolean>;
61
62
// Window control
63
show(): Promise<void>;
64
hide(): Promise<void>;
65
close(): Promise<void>;
66
minimize(): Promise<void>;
67
unminimize(): Promise<void>;
68
maximize(): Promise<void>;
69
unmaximize(): Promise<void>;
70
toggleMaximize(): Promise<void>;
71
setFocus(): Promise<void>;
72
73
// Appearance
74
setTitle(title: string): Promise<void>;
75
setIcon(icon: Image | string): Promise<void>;
76
setDecorated(decorated: boolean): Promise<void>;
77
setAlwaysOnTop(alwaysOnTop: boolean): Promise<void>;
78
setResizable(resizable: boolean): Promise<void>;
79
setMaximizable(maximizable: boolean): Promise<void>;
80
setMinimizable(minimizable: boolean): Promise<void>;
81
setClosable(closable: boolean): Promise<void>;
82
83
// Advanced features
84
startDragging(): Promise<void>;
85
requestUserAttention(requestType?: UserAttentionType): Promise<void>;
86
setProgressBar(state: ProgressBarState): Promise<void>;
87
setBadgeLabel(label?: string): Promise<void>;
88
setOverlayIcon(icon: Image | string | null, description?: string): Promise<void>;
89
setCursorIcon(icon: CursorIcon): Promise<void>;
90
setTitleBarStyle(style: TitleBarStyle): Promise<void>;
91
setFullscreen(fullscreen: boolean): Promise<void>;
92
setEffects(effects: Effects): Promise<void>;
93
clearEffects(): Promise<void>;
94
95
// Event listeners
96
onResized(handler: EventCallback<PhysicalSize>): Promise<UnlistenFn>;
97
onMoved(handler: EventCallback<PhysicalPosition>): Promise<UnlistenFn>;
98
onCloseRequested(handler: EventCallback<CloseRequestedEvent>): Promise<UnlistenFn>;
99
onFocusChanged(handler: EventCallback<boolean>): Promise<UnlistenFn>;
100
onScaleChanged(handler: EventCallback<ScaleFactorChanged>): Promise<UnlistenFn>;
101
onThemeChanged(handler: EventCallback<Theme>): Promise<UnlistenFn>;
102
}
103
104
/**
105
* Convenience functions for current window
106
*/
107
function getCurrentWindow(): Window;
108
function getAllWindows(): Promise<Window[]>;
109
```
110
111
### Webview Control
112
113
Webview management for embedding web content with full control over navigation and behavior.
114
115
```typescript { .api }
116
/**
117
* Webview management class
118
*/
119
class Webview {
120
constructor(webview: WebviewHandle, label: string, listeners: Map<string, EventCallback<any>>);
121
122
/**
123
* Get webview by label
124
* @param label - Webview identifier
125
* @returns Webview instance or null if not found
126
*/
127
static getByLabel(label: string): Promise<Webview | null>;
128
129
/**
130
* Get current webview instance
131
* @returns Current webview
132
*/
133
static getCurrent(): Webview;
134
135
/**
136
* Get all webview instances
137
* @returns Array of all webviews
138
*/
139
static getAll(): Promise<Webview[]>;
140
141
// Event handling
142
listen<T>(event: EventName, handler: EventCallback<T>, options?: EventOptions): Promise<UnlistenFn>;
143
once<T>(event: EventName, handler: EventCallback<T>, options?: EventOptions): Promise<UnlistenFn>;
144
emit<T>(event: string, payload?: T): Promise<void>;
145
emitTo<T>(target: EventTarget | string, event: string, payload?: T): Promise<void>;
146
147
// Position and size
148
position(): Promise<PhysicalPosition>;
149
size(): Promise<PhysicalSize>;
150
setPosition(position: LogicalPosition | PhysicalPosition): Promise<void>;
151
setSize(size: LogicalSize | PhysicalSize): Promise<void>;
152
153
// Webview control
154
close(): Promise<void>;
155
setFocus(): Promise<void>;
156
reparent(window: Window): Promise<void>;
157
print(): Promise<void>;
158
159
// Navigation and content
160
setUrl(url: string): Promise<void>;
161
reload(): Promise<void>;
162
goBack(): Promise<void>;
163
goForward(): Promise<void>;
164
canGoBack(): Promise<boolean>;
165
canGoForward(): Promise<boolean>;
166
167
// Zoom and appearance
168
setZoom(factor: number): Promise<void>;
169
getZoom(): Promise<number>;
170
setBackgroundColor(color: Color): Promise<void>;
171
172
// Developer tools
173
openDevTools(): Promise<void>;
174
closeDevTools(): Promise<void>;
175
isDevToolsOpen(): Promise<boolean>;
176
}
177
178
/**
179
* Convenience functions for current webview
180
*/
181
function getCurrentWebview(): Webview;
182
function getAllWebviews(): Promise<Webview[]>;
183
```
184
185
### Combined WebviewWindow
186
187
Unified class combining window and webview functionality for most common use cases.
188
189
```typescript { .api }
190
/**
191
* Combined window and webview functionality
192
*/
193
class WebviewWindow {
194
/**
195
* Create a new webview window
196
* @param label - Unique identifier for the window
197
* @param options - Window and webview configuration
198
*/
199
constructor(label: string, options?: WebviewWindowOptions);
200
201
/**
202
* Set the background color of the webview
203
* @param color - RGBA color specification
204
*/
205
setBackgroundColor(color: Color): Promise<void>;
206
207
// Inherits all methods from both Window and Webview classes
208
}
209
210
/**
211
* Convenience functions for current webview window
212
*/
213
function getCurrentWebviewWindow(): WebviewWindow;
214
function getAllWebviewWindows(): Promise<WebviewWindow[]>;
215
```
216
217
### Position and Size Types
218
219
Device-independent positioning and sizing utilities.
220
221
```typescript { .api }
222
/**
223
* Logical size in device-independent pixels
224
*/
225
class LogicalSize {
226
constructor(width: number, height: number);
227
toPhysical(scaleFactor: number): PhysicalSize;
228
}
229
230
/**
231
* Physical size in actual screen pixels
232
*/
233
class PhysicalSize {
234
constructor(width: number, height: number);
235
toLogical(scaleFactor: number): LogicalSize;
236
}
237
238
/**
239
* Union wrapper for logical or physical size
240
*/
241
class Size {
242
static logical(width: number, height: number): Size;
243
static physical(width: number, height: number): Size;
244
}
245
246
/**
247
* Logical position in device-independent pixels
248
*/
249
class LogicalPosition {
250
constructor(x: number, y: number);
251
toPhysical(scaleFactor: number): PhysicalPosition;
252
}
253
254
/**
255
* Physical position in actual screen pixels
256
*/
257
class PhysicalPosition {
258
constructor(x: number, y: number);
259
toLogical(scaleFactor: number): LogicalPosition;
260
}
261
262
/**
263
* Union wrapper for logical or physical position
264
*/
265
class Position {
266
static logical(x: number, y: number): Position;
267
static physical(x: number, y: number): Position;
268
}
269
```
270
271
### Window Configuration
272
273
Comprehensive configuration options for window creation and management.
274
275
```typescript { .api }
276
interface WebviewWindowOptions {
277
// Window properties
278
width?: number;
279
height?: number;
280
minWidth?: number;
281
minHeight?: number;
282
maxWidth?: number;
283
maxHeight?: number;
284
x?: number;
285
y?: number;
286
center?: boolean;
287
288
// Window behavior
289
resizable?: boolean;
290
maximizable?: boolean;
291
minimizable?: boolean;
292
closable?: boolean;
293
title?: string;
294
titleBarStyle?: TitleBarStyle;
295
fullscreen?: boolean;
296
focus?: boolean;
297
alwaysOnTop?: boolean;
298
alwaysOnBottom?: boolean;
299
visible?: boolean;
300
transparent?: boolean;
301
decorations?: boolean;
302
shadow?: boolean;
303
304
// Webview properties
305
url?: string;
306
html?: string;
307
userAgent?: string;
308
acceptFirstMouse?: boolean;
309
backgroundColor?: Color;
310
311
// Advanced
312
theme?: Theme;
313
windowClassId?: string;
314
incognito?: boolean;
315
proxyUrl?: string;
316
}
317
318
interface WindowOptions {
319
// Similar to WebviewWindowOptions but without webview-specific properties
320
}
321
322
interface WebviewOptions {
323
// Webview-specific configuration
324
x?: number;
325
y?: number;
326
width?: number;
327
height?: number;
328
url?: string;
329
html?: string;
330
initialization?: string;
331
userAgent?: string;
332
acceptFirstMouse?: boolean;
333
autoplay?: boolean;
334
backgroundColor?: Color;
335
transparent?: boolean;
336
zoom?: number;
337
}
338
339
type TitleBarStyle = 'visible' | 'transparent' | 'overlay';
340
type Theme = 'light' | 'dark' | 'auto';
341
type UserAttentionType = 'critical' | 'informational';
342
343
interface Color {
344
r: number;
345
g: number;
346
b: number;
347
a: number;
348
}
349
350
interface ProgressBarState {
351
status?: ProgressBarStatus;
352
progress?: number;
353
}
354
355
enum ProgressBarStatus {
356
None = 'none',
357
Normal = 'normal',
358
Indeterminate = 'indeterminate',
359
Paused = 'paused',
360
Error = 'error'
361
}
362
363
type CursorIcon =
364
| 'default'
365
| 'crosshair'
366
| 'hand'
367
| 'arrow'
368
| 'move'
369
| 'text'
370
| 'wait'
371
| 'help'
372
| 'progress'
373
| 'notAllowed'
374
| 'contextMenu'
375
| 'cell'
376
| 'verticalText'
377
| 'alias'
378
| 'copy'
379
| 'noDrop'
380
| 'grab'
381
| 'grabbing'
382
| 'allScroll'
383
| 'zoomIn'
384
| 'zoomOut'
385
| 'eResize'
386
| 'nResize'
387
| 'neResize'
388
| 'nwResize'
389
| 'sResize'
390
| 'seResize'
391
| 'swResize'
392
| 'wResize'
393
| 'ewResize'
394
| 'nsResize'
395
| 'neswResize'
396
| 'nwseResize'
397
| 'colResize'
398
| 'rowResize';
399
400
interface ScaleFactorChanged {
401
scaleFactor: number;
402
size: PhysicalSize;
403
}
404
405
class CloseRequestedEvent {
406
event: EventName;
407
id: number;
408
preventDefault(): void;
409
isPreventDefault(): boolean;
410
}
411
```
412
413
### Monitor Information
414
415
System monitor detection and information.
416
417
```typescript { .api }
418
/**
419
* Monitor information interface
420
*/
421
interface Monitor {
422
name: string | null;
423
position: PhysicalPosition;
424
size: PhysicalSize;
425
scaleFactor: number;
426
}
427
428
/**
429
* Get the monitor containing the current window
430
* @returns Monitor information or null if not found
431
*/
432
function currentMonitor(): Promise<Monitor | null>;
433
434
/**
435
* Get the primary monitor
436
* @returns Primary monitor information or null if not found
437
*/
438
function primaryMonitor(): Promise<Monitor | null>;
439
440
/**
441
* Get monitor at specific screen coordinates
442
* @param x - Screen X coordinate
443
* @param y - Screen Y coordinate
444
* @returns Monitor at the given point or null if not found
445
*/
446
function monitorFromPoint(x: number, y: number): Promise<Monitor | null>;
447
448
/**
449
* Get all available monitors
450
* @returns Array of all available monitors
451
*/
452
function availableMonitors(): Promise<Monitor[]>;
453
454
/**
455
* Get current cursor position
456
* @returns Cursor position in physical coordinates
457
*/
458
function cursorPosition(): Promise<PhysicalPosition>;
459
```
460
461
### Visual Effects
462
463
Advanced window visual effects and styling (primarily macOS).
464
465
```typescript { .api }
466
/**
467
* Window visual effects configuration
468
*/
469
interface Effects {
470
effect: Effect;
471
state?: EffectState;
472
radius?: number;
473
}
474
475
enum Effect {
476
AppearanceBased = 'appearanceBased',
477
Light = 'light',
478
Dark = 'dark',
479
MediumLight = 'mediumLight',
480
UltraDark = 'ultraDark',
481
Titlebar = 'titlebar',
482
Selection = 'selection',
483
Menu = 'menu',
484
Popover = 'popover',
485
Sidebar = 'sidebar',
486
HeaderView = 'headerView',
487
Sheet = 'sheet',
488
WindowBackground = 'windowBackground',
489
HudWindow = 'hudWindow',
490
FullScreenUI = 'fullScreenUI',
491
Tooltip = 'tooltip',
492
ContentBackground = 'contentBackground',
493
UnderWindowBackground = 'underWindowBackground',
494
UnderPageBackground = 'underPageBackground'
495
}
496
497
enum EffectState {
498
FollowsWindowActiveState = 'followsWindowActiveState',
499
Active = 'active',
500
Inactive = 'inactive'
501
}
502
```
503
504
### Close Event Handling
505
506
Handle window close requests with prevention capability.
507
508
```typescript { .api }
509
/**
510
* Window close request event
511
*/
512
class CloseRequestedEvent {
513
/**
514
* Prevent the window from closing
515
*/
516
preventDefault(): void;
517
518
/**
519
* Check if the default close behavior was prevented
520
* @returns true if preventDefault() was called
521
*/
522
isDefaultPrevented(): boolean;
523
}
524
```
525
526
## Usage Examples
527
528
### Basic Window Management
529
530
```typescript
531
import { getCurrentWindow } from '@tauri-apps/api/window';
532
533
const window = getCurrentWindow();
534
535
// Set window properties
536
await window.setTitle('My Application');
537
await window.setSize({ width: 800, height: 600 });
538
await window.center();
539
540
// Window state management
541
if (await window.isMinimized()) {
542
await window.unminimize();
543
}
544
545
await window.setAlwaysOnTop(true);
546
await window.setResizable(false);
547
```
548
549
### Creating New Windows
550
551
```typescript
552
import { WebviewWindow } from '@tauri-apps/api/webviewWindow';
553
554
const newWindow = new WebviewWindow('settings', {
555
title: 'Settings',
556
width: 600,
557
height: 400,
558
center: true,
559
resizable: false,
560
url: '/settings.html'
561
});
562
563
// Wait for window to be ready
564
newWindow.once('tauri://created', () => {
565
console.log('Settings window created');
566
});
567
568
newWindow.once('tauri://error', (error) => {
569
console.error('Failed to create window:', error);
570
});
571
```
572
573
### Handling Window Events
574
575
```typescript
576
import { getCurrentWindow } from '@tauri-apps/api/window';
577
578
const window = getCurrentWindow();
579
580
// Handle window close request
581
await window.listen('tauri://close-requested', (event) => {
582
// event is CloseRequestedEvent
583
if (hasUnsavedChanges()) {
584
event.preventDefault();
585
showSaveDialog();
586
}
587
});
588
589
// Handle resize events
590
await window.listen('tauri://resize', (event) => {
591
console.log('Window resized:', event.payload);
592
});
593
594
// Handle focus events
595
await window.listen('tauri://focus', () => {
596
console.log('Window focused');
597
});
598
```
599
600
### Multi-Monitor Support
601
602
```typescript
603
import { availableMonitors, currentMonitor } from '@tauri-apps/api/window';
604
605
// Get all monitors
606
const monitors = await availableMonitors();
607
console.log(`Found ${monitors.length} monitors`);
608
609
// Get current monitor
610
const current = await currentMonitor();
611
if (current) {
612
console.log(`Current monitor: ${current.name}, Scale: ${current.scaleFactor}`);
613
}
614
615
// Position window on specific monitor
616
const targetMonitor = monitors[1]; // Second monitor
617
if (targetMonitor) {
618
await window.setPosition({
619
x: targetMonitor.position.x + 100,
620
y: targetMonitor.position.y + 100
621
});
622
}
623
```
624
625
### Progressive Enhancement for Web vs Desktop
626
627
```typescript
628
import { isTauri } from '@tauri-apps/api/core';
629
import { getCurrentWindow } from '@tauri-apps/api/window';
630
631
if (isTauri()) {
632
// Desktop-specific functionality
633
const window = getCurrentWindow();
634
635
// Add desktop window controls
636
document.getElementById('minimize-btn')?.addEventListener('click', () => {
637
window.minimize();
638
});
639
640
document.getElementById('maximize-btn')?.addEventListener('click', () => {
641
window.toggleMaximize();
642
});
643
644
document.getElementById('close-btn')?.addEventListener('click', () => {
645
window.close();
646
});
647
} else {
648
// Web fallback - hide desktop controls
649
document.querySelector('.window-controls')?.remove();
650
}
651
```