0
# Window Management
1

2
Browser window and frame management for handling pop-ups, iframes, modal dialogs, and multi-window scenarios. Essential for complex web application navigation and testing applications with multiple windows or frames.
3

4
## Capabilities
5

6
### WebWindow Interface
7

8
Base interface for all browser window types including top-level windows, frames, and dialogs.
9

10
```java { .api }
11
/**
12
 * Base interface for browser windows and frames
13
 */
14
public interface WebWindow {
15
    /** Get window name */
16
    public String getName();
17
    
18
    /** Set window name */
19
    public void setName(String name);
20
    
21
    /** Get current page in window */
22
    public Page getEnclosedPage();
23
    
24
    /** Set page in window */
25
    public void setEnclosedPage(Page page);
26
    
27
    /** Get parent WebClient */
28
    public WebClient getWebClient();
29
    
30
    /** Get parent window (null for top-level) */
31
    public WebWindow getParentWindow();
32
    
33
    /** Get top-level window */
34
    public WebWindow getTopWindow();
35
    
36
    /** Get window history */
37
    public History getHistory();
38
    
39
    /** Get inner window width */
40
    public int getInnerWidth();
41
    
42
    /** Set inner window width */
43
    public void setInnerWidth(int innerWidth);
44
    
45
    /** Get inner window height */
46
    public int getInnerHeight();
47
    
48
    /** Set inner window height */
49
    public void setInnerHeight(int innerHeight);
50
    
51
    /** Get outer window width */
52
    public int getOuterWidth();
53
    
54
    /** Set outer window width */
55
    public void setOuterWidth(int outerWidth);
56
    
57
    /** Get outer window height */
58
    public int getOuterHeight();
59
    
60
    /** Set outer window height */
61
    public void setOuterHeight(int outerHeight);
62
    
63
    /** Get window job manager for JavaScript */
64
    public JavaScriptJobManager getJobManager();
65
    
66
    /** Initialize window */
67
    public void initialize();
68
    
69
    /** Check if window is closed */
70
    public boolean isClosed();
71
    
72
    /** Close window */
73
    public void close();
74
}
75
```
76

77
**Usage Examples:**
78

79
```java
80
import com.gargoylesoftware.htmlunit.*;
81

82
try (WebClient webClient = new WebClient()) {
83
    // Get current window
84
    WebWindow currentWindow = webClient.getCurrentWindow();
85
    System.out.println("Current window: " + currentWindow.getName());
86
    
87
    // Load page in current window
88
    HtmlPage page = webClient.getPage("https://example.com");
89
    
90
    // Window properties
91
    currentWindow.setName("mainWindow");
92
    currentWindow.setInnerWidth(1024);
93
    currentWindow.setInnerHeight(768);
94
    
95
    System.out.println("Window size: " + currentWindow.getInnerWidth() + "x" + currentWindow.getInnerHeight());
96
    System.out.println("Page URL: " + currentWindow.getEnclosedPage().getUrl());
97
}
98
```
99

100
### TopLevelWindow Class
101

102
Implementation for top-level browser windows.
103

104
```java { .api }
105
/**
106
 * Top-level browser window implementation
107
 */
108
public class TopLevelWindow extends WebWindowImpl {
109
    /** Create top-level window */
110
    public TopLevelWindow(String name, WebClient webClient);
111
    
112
    /** Get window opener (if opened by another window) */
113
    public WebWindow getOpener();
114
    
115
    /** Set window opener */
116
    public void setOpener(WebWindow opener);
117
    
118
    /** Check if window can be closed */
119
    public boolean isCloseable();
120
    
121
    /** Set window closeable state */
122
    public void setCloseable(boolean closeable);
123
    
124
    /** Get window status text */
125
    public String getStatus();
126
    
127
    /** Set window status text */
128
    public void setStatus(String status);
129
    
130
    /** Check if window is maximized */
131
    public boolean isMaximized();
132
    
133
    /** Maximize window */
134
    public void maximize();
135
    
136
    /** Minimize window */
137
    public void minimize();
138
    
139
    /** Restore window */
140
    public void restore();
141
    
142
    /** Move window to position */
143
    public void moveTo(int x, int y);
144
    
145
    /** Move window by offset */
146
    public void moveBy(int deltaX, int deltaY);
147
    
148
    /** Resize window to size */
149
    public void resizeTo(int width, int height);
150
    
151
    /** Resize window by delta */
152
    public void resizeBy(int deltaWidth, int deltaHeight);
153
    
154
    /** Scroll window to position */
155
    public void scrollTo(int x, int y);
156
    
157
    /** Scroll window by offset */
158
    public void scrollBy(int deltaX, int deltaY);
159
    
160
    /** Get window position X */
161
    public int getLeft();
162
    
163
    /** Set window position X */
164
    public void setLeft(int left);
165
    
166
    /** Get window position Y */
167
    public int getTop();
168
    
169
    /** Set window position Y */
170
    public void setTop(int top);
171
}
172
```
173

174
### DialogWindow Class
175

176
Implementation for modal dialog windows.
177

178
```java { .api }
179
/**
180
 * Modal dialog window implementation
181
 */
182
public class DialogWindow extends WebWindowImpl {
183
    /** Create dialog window */
184
    public DialogWindow(WebClient webClient, WebWindow opener, Object dialogArguments);
185
    
186
    /** Get window that opened this dialog */
187
    public WebWindow getOpener();
188
    
189
    /** Get dialog arguments passed when opened */
190
    public Object getDialogArguments();
191
    
192
    /** Get dialog return value */
193
    public Object getReturnValue();
194
    
195
    /** Set dialog return value */
196
    public void setReturnValue(Object returnValue);
197
    
198
    /** Close dialog with return value */
199
    public void close(Object returnValue);
200
    
201
    /** Check if dialog is modal */
202
    public boolean isModal();
203
    
204
    /** Check if dialog blocks parent window */
205
    public boolean isBlocking();
206
}
207
```
208

209
### FrameWindow Class
210

211
Implementation for frame and iframe windows.
212

213
```java { .api }
214
/**
215
 * Frame window implementation for <frame> and <iframe> elements
216
 */
217
public class FrameWindow extends WebWindowImpl {
218
    /** Create frame window */
219
    public FrameWindow(BaseFrameElement frameElement);
220
    
221
    /** Get frame element that contains this window */
222
    public BaseFrameElement getFrameElement();
223
    
224
    /** Get frame name from element */
225
    public String getFrameName();
226
    
227
    /** Get frame source URL */
228
    public String getFrameSource();
229
    
230
    /** Check if frame content is accessible (same origin) */
231
    public boolean isContentAccessible();
232
    
233
    /** Get frame border width */
234
    public int getFrameBorder();
235
    
236
    /** Get frame margin width */
237
    public int getMarginWidth();
238
    
239
    /** Get frame margin height */
240
    public int getMarginHeight();
241
    
242
    /** Check if frame allows scrolling */
243
    public boolean isScrollingAllowed();
244
    
245
    /** Check if frame is resizable */
246
    public boolean isResizable();
247
}
248
```
249

250
**Usage Examples:**
251

252
```java
253
// Working with frames
254
HtmlPage page = webClient.getPage("https://example.com/frames.html");
255

256
// Find frame by name
257
WebWindow frameWindow = webClient.getWebWindowByName("contentFrame");
258
if (frameWindow instanceof FrameWindow) {
259
    FrameWindow frame = (FrameWindow) frameWindow;
260
    
261
    // Get content from frame
262
    Page framePage = frame.getEnclosedPage();
263
    if (framePage instanceof HtmlPage) {
264
        HtmlPage frameHtmlPage = (HtmlPage) framePage;
265
        String frameContent = frameHtmlPage.asText();
266
        System.out.println("Frame content: " + frameContent);
267
    }
268
    
269
    // Check frame properties
270
    System.out.println("Frame source: " + frame.getFrameSource());
271
    System.out.println("Frame accessible: " + frame.isContentAccessible());
272
}
273

274
// Find iframe element and get its window
275
HtmlInlineFrame iframe = (HtmlInlineFrame) page.getElementById("myIframe");
276
FrameWindow iframeWindow = (FrameWindow) iframe.getContentWindow();
277
Page iframePage = iframeWindow.getEnclosedPage();
278
```
279

280
### History Class
281

282
Browser history management for back/forward navigation.
283

284
```java { .api }
285
/**
286
 * Browser history for window navigation
287
 */
288
public class History {
289
    /** Get history length */
290
    public int getLength();
291
    
292
    /** Navigate back one page */
293
    public void back() throws IOException;
294
    
295
    /** Navigate forward one page */
296
    public void forward() throws IOException;
297
    
298
    /** Navigate by relative index */
299
    public void go(int relativeIndex) throws IOException;
300
    
301
    /** Get current history index */
302
    public int getIndex();
303
    
304
    /** Get history entry at index */
305
    public HistoryEntry getEntry(int index);
306
    
307
    /** Get all history entries */
308
    public List<HistoryEntry> getEntries();
309
    
310
    /** Clear history */
311
    public void clear();
312
    
313
    /** Get URL at history index */
314
    public URL getUrl(int index);
315
    
316
    /** Get current URL */
317
    public URL getCurrentUrl();
318
    
319
    /** Check if can go back */
320
    public boolean canGoBack();
321
    
322
    /** Check if can go forward */
323
    public boolean canGoForward();
324
    
325
    /** Push state to history (HTML5) */
326
    public void pushState(Object data, String title, String url);
327
    
328
    /** Replace current state (HTML5) */
329
    public void replaceState(Object data, String title, String url);
330
    
331
    /** Get current state object */
332
    public Object getCurrentState();
333
}
334

335
/**
336
 * Individual history entry
337
 */
338
public class HistoryEntry {
339
    /** Get entry URL */
340
    public URL getUrl();
341
    
342
    /** Get entry title */
343
    public String getTitle();
344
    
345
    /** Get state object */
346
    public Object getState();
347
    
348
    /** Get timestamp */
349
    public Date getTimestamp();
350
}
351
```
352

353
**Usage Examples:**
354

355
```java
356
// History navigation
357
try (WebClient webClient = new WebClient()) {
358
    WebWindow window = webClient.getCurrentWindow();
359
    History history = window.getHistory();
360
    
361
    // Navigate through pages
362
    webClient.getPage("https://example.com/page1");
363
    webClient.getPage("https://example.com/page2");
364
    webClient.getPage("https://example.com/page3");
365
    
366
    System.out.println("History length: " + history.getLength());
367
    System.out.println("Current URL: " + history.getCurrentUrl());
368
    
369
    // Navigate back
370
    if (history.canGoBack()) {
371
        history.back();
372
        System.out.println("After back: " + history.getCurrentUrl());
373
    }
374
    
375
    // Navigate forward
376
    if (history.canGoForward()) {
377
        history.forward();
378
        System.out.println("After forward: " + history.getCurrentUrl());
379
    }
380
    
381
    // Go to specific history index
382
    history.go(-2); // Go back 2 pages
383
    
384
    // Clear history
385
    history.clear();
386
}
387
```
388

389
### Window Opening and Management
390

391
```java { .api }
392
/**
393
 * WebClient methods for window management
394
 */
395
public class WebClient implements AutoCloseable {
396
    /** Get current active window */
397
    public WebWindow getCurrentWindow();
398
    
399
    /** Set current active window */
400
    public void setCurrentWindow(WebWindow window);
401
    
402
    /** Open new window with URL */
403
    public WebWindow openWindow(URL url, String windowName) throws IOException;
404
    
405
    /** Open new window with target */
406
    public WebWindow openWindow(URL url, String windowName, String windowFeatures) throws IOException;
407
    
408
    /** Open modal dialog window */
409
    public DialogWindow openDialogWindow(URL url, WebWindow opener, Object dialogArguments) throws IOException;
410
    
411
    /** Find window by name */
412
    public WebWindow getWebWindowByName(String name);
413
    
414
    /** Get all open windows */
415
    public List<WebWindow> getWindows();
416
    
417
    /** Close all windows */
418
    public void closeAllWindows();
419
    
420
    /** Get default window for new content */
421
    public WebWindow getDefaultWindow();
422
}
423
```
424

425
**Usage Examples:**
426

427
```java
428
// Open new windows
429
try (WebClient webClient = new WebClient()) {
430
    // Open new window
431
    WebWindow newWindow = webClient.openWindow(new URL("https://example.com/popup"), "popupWindow");
432
    
433
    // Switch to new window
434
    webClient.setCurrentWindow(newWindow);
435
    
436
    // Load page in new window
437
    HtmlPage popupPage = webClient.getPage("https://example.com/popup-content");
438
    
439
    // Open modal dialog
440
    DialogWindow dialog = webClient.openDialogWindow(
441
        new URL("https://example.com/dialog"), 
442
        webClient.getCurrentWindow(), 
443
        "dialog arguments"
444
    );
445
    
446
    // Work with dialog
447
    HtmlPage dialogPage = (HtmlPage) dialog.getEnclosedPage();
448
    
449
    // Close dialog with return value
450
    dialog.close("dialog result");
451
    
452
    // Find window by name
453
    WebWindow foundWindow = webClient.getWebWindowByName("popupWindow");
454
    if (foundWindow != null) {
455
        System.out.println("Found window: " + foundWindow.getName());
456
    }
457
    
458
    // List all windows
459
    List<WebWindow> allWindows = webClient.getWindows();
460
    System.out.println("Total windows: " + allWindows.size());
461
    
462
    for (WebWindow window : allWindows) {
463
        System.out.println("Window: " + window.getName() + " - " + window.getEnclosedPage().getUrl());
464
    }
465
}
466
```
467

468
### Frame Element Classes
469

470
HTML frame elements that create frame windows.
471

472
```java { .api }
473
/**
474
 * Base class for frame elements
475
 */
476
public abstract class BaseFrameElement extends HtmlElement {
477
    /** Get frame content window */
478
    public abstract FrameWindow getContentWindow();
479
    
480
    /** Get frame name */
481
    public String getNameAttribute();
482
    
483
    /** Get frame source URL */
484
    public String getSrcAttribute();
485
    
486
    /** Set frame source URL */
487
    public void setSrcAttribute(String src);
488
    
489
    /** Check if frame is loading */
490
    public boolean isContentLoading();
491
    
492
    /** Wait for frame content to load */
493
    public void waitForContentToLoad(long timeoutMillis) throws InterruptedException;
494
    
495
    /** Get frame border */
496
    public String getFrameBorderAttribute();
497
    
498
    /** Get margin width */
499
    public String getMarginWidthAttribute();
500
    
501
    /** Get margin height */
502
    public String getMarginHeightAttribute();
503
    
504
    /** Get scrolling setting */
505
    public String getScrollingAttribute();
506
}
507

508
/**
509
 * Frame element (<frame>)
510
 */
511
public class HtmlFrame extends BaseFrameElement {
512
    /** Check if frame is resizable */
513
    public boolean isResizable();
514
    
515
    /** Get frame resize setting */
516
    public String getNoResizeAttribute();
517
}
518

519
/**
520
 * Inline frame element (<iframe>)
521
 */
522
public class HtmlInlineFrame extends BaseFrameElement {
523
    /** Get iframe width */
524
    public String getWidthAttribute();
525
    
526
    /** Get iframe height */
527
    public String getHeightAttribute();
528
    
529
    /** Get iframe align */
530
    public String getAlignAttribute();
531
    
532
    /** Get iframe longdesc */
533
    public String getLongDescAttribute();
534
    
535
    /** Check if iframe is seamless */
536
    public boolean isSeamless();
537
    
538
    /** Get iframe sandbox */
539
    public String getSandboxAttribute();
540
    
541
    /** Get iframe srcdoc */
542
    public String getSrcdocAttribute();
543
    
544
    /** Check if frame allows fullscreen */
545
    public boolean isAllowFullscreen();
546
}
547
```
548

549
### Window Events and Handlers
550

551
```java { .api }
552
/**
553
 * Window event handling
554
 */
555
public interface WindowEventHandler {
556
    /** Handle window opened event */
557
    void onWindowOpened(WebWindow window);
558
    
559
    /** Handle window closed event */
560
    void onWindowClosed(WebWindow window);
561
    
562
    /** Handle window focus event */
563
    void onWindowFocused(WebWindow window);
564
    
565
    /** Handle window blur event */
566
    void onWindowBlurred(WebWindow window);
567
}
568

569
/**
570
 * Status handler for window status updates
571
 */
572
public interface StatusHandler {
573
    /** Handle status message update */
574
    void statusMessageChanged(Page page, String message);
575
}
576
```
577

578
### Cross-Frame Communication
579

580
```java { .api }
581
/**
582
 * Methods for cross-frame communication and access
583
 */
584
public class WebWindow {
585
    /** Post message to another window (HTML5) */
586
    public void postMessage(String message, String targetOrigin, WebWindow targetWindow);
587
    
588
    /** Get window by frame reference */
589
    public WebWindow getFrameByName(String frameName);
590
    
591
    /** Get parent frame window */
592
    public WebWindow getParent();
593
    
594
    /** Get top-level window */
595
    public WebWindow getTop();
596
    
597
    /** Check if windows are same origin */
598
    public boolean isSameOrigin(WebWindow otherWindow);
599
    
600
    /** Check if window can access another window */
601
    public boolean canAccessWindow(WebWindow otherWindow);
602
}
603
```
604

605
**Usage Examples:**
606

607
```java
608
// Cross-frame communication
609
HtmlPage mainPage = webClient.getPage("https://example.com/frameset.html");
610

611
// Access frame by name
612
WebWindow frameWindow = webClient.getWebWindowByName("contentFrame");
613
if (frameWindow != null) {
614
    HtmlPage framePage = (HtmlPage) frameWindow.getEnclosedPage();
615
    
616
    // Execute JavaScript in frame
617
    ScriptResult result = framePage.executeJavaScript("document.title");
618
    System.out.println("Frame title: " + result.getJavaScriptResult());
619
    
620
    // Check frame relationships
621
    WebWindow parentWindow = frameWindow.getParentWindow();
622
    WebWindow topWindow = frameWindow.getTopWindow();
623
    
624
    System.out.println("Frame parent: " + parentWindow.getName());
625
    System.out.println("Frame top: " + topWindow.getName());
626
    
627
    // Check same origin
628
    boolean sameOrigin = frameWindow.isSameOrigin(parentWindow);
629
    System.out.println("Same origin: " + sameOrigin);
630
}
631

632
// Handle multiple windows
633
List<WebWindow> windows = webClient.getWindows();
634
for (WebWindow window : windows) {
635
    if (window instanceof TopLevelWindow) {
636
        TopLevelWindow topWindow = (TopLevelWindow) window;
637
        System.out.println("Top-level window: " + topWindow.getName());
638
    } else if (window instanceof DialogWindow) {
639
        DialogWindow dialog = (DialogWindow) window;
640
        System.out.println("Dialog window with args: " + dialog.getDialogArguments());
641
    } else if (window instanceof FrameWindow) {
642
        FrameWindow frame = (FrameWindow) window;
643
        System.out.println("Frame window: " + frame.getFrameName());
644
    }
645
}
646
```