0
# Window Management
1

2
Browser window and frame management providing multiple window handling, window navigation, frame interactions, and popup control for comprehensive browser simulation.
3

4
## Capabilities
5

6
### WebWindow Interface
7

8
Base interface for all window types providing common window functionality.
9

10
```java { .api }
11
public interface WebWindow {
12
    /**
13
     * Get the page currently displayed in this window
14
     * @return the Page object, or null if no page is loaded
15
     */
16
    public Page getEnclosedPage();
17
    
18
    /**
19
     * Set the page to display in this window
20
     * @param page the Page to display
21
     */
22
    public void setEnclosedPage(Page page);
23
    
24
    /**
25
     * Get the window name (target name for links and forms)
26
     * @return the window name, or empty string if unnamed
27
     */
28
    public String getName();
29
    
30
    /**
31
     * Set the window name
32
     * @param name the new window name
33
     */
34
    public void setName(String name);
35
    
36
    /**
37
     * Get the parent window (null for top-level windows)
38
     * @return parent WebWindow, or null if this is a top-level window
39
     */
40
    public WebWindow getParentWindow();
41
    
42
    /**
43
     * Get the top-level window in the window hierarchy
44
     * @return the root WebWindow in the hierarchy
45
     */
46
    public WebWindow getTopWindow();
47
    
48
    /**
49
     * Get the WebClient that owns this window
50
     * @return the WebClient instance
51
     */
52
    public WebClient getWebClient();
53
    
54
    /**
55
     * Get the browser history for this window
56
     * @return History object for navigation
57
     */
58
    public History getHistory();
59
    
60
    /**
61
     * Get the current window dimensions
62
     * @return Dimension object with width and height
63
     */
64
    public Dimension getInnerSize();
65
    
66
    /**
67
     * Set the window dimensions
68
     * @param dimension new window size
69
     */
70
    public void setInnerSize(Dimension dimension);
71
    
72
    /**
73
     * Check if this window is closed
74
     * @return true if the window has been closed
75
     */
76
    public boolean isClosed();
77
}
78
```
79

80
**Usage Examples:**
81

82
```java
83
WebClient webClient = new WebClient();
84
HtmlPage page = webClient.getPage("https://example.com");
85

86
// Get current window
87
WebWindow currentWindow = webClient.getCurrentWindow();
88

89
// Window properties
90
String windowName = currentWindow.getName();
91
WebWindow parentWindow = currentWindow.getParentWindow();
92
WebWindow topWindow = currentWindow.getTopWindow();
93
Page enclosedPage = currentWindow.getEnclosedPage();
94

95
// Window dimensions
96
Dimension size = currentWindow.getInnerSize();
97
System.out.println("Window size: " + size.width + "x" + size.height);
98
```
99

100
### TopLevelWindow
101

102
Main browser window implementation for primary browser windows.
103

104
```java { .api }
105
public class TopLevelWindow implements WebWindow {
106
    /**
107
     * Create a new top-level window
108
     * @param name the window name
109
     * @param webClient the WebClient that owns this window
110
     */
111
    public TopLevelWindow(String name, WebClient webClient);
112
    
113
    /**
114
     * Open a new window with the specified URL
115
     * @param url the URL to load in the new window
116
     * @param windowName the name for the new window
117
     * @return the newly created WebWindow
118
     * @throws IOException if window creation fails
119
     */
120
    public WebWindow openWindow(URL url, String windowName) throws IOException;
121
    
122
    /**
123
     * Close this window
124
     */
125
    public void close();
126
    
127
    /**
128
     * Get all child windows (frames) of this window
129
     * @return List of child WebWindow objects
130
     */
131
    public List<WebWindow> getChildWindows();
132
    
133
    /**
134
     * Set the window position on screen
135
     * @param x horizontal position
136
     * @param y vertical position
137
     */
138
    public void setOuterPosition(int x, int y);
139
    
140
    /**
141
     * Get the window position
142
     * @return Point object with x,y coordinates
143
     */
144
    public Point getOuterPosition();
145
}
146
```
147

148
**Usage Examples:**
149

150
```java
151
WebClient webClient = new WebClient();
152

153
// Create named window
154
TopLevelWindow mainWindow = new TopLevelWindow("main", webClient);
155
webClient.setCurrentWindow(mainWindow);
156

157
// Load page in window
158
mainWindow.setEnclosedPage(webClient.getPage("https://example.com"));
159

160
// Window positioning
161
mainWindow.setOuterPosition(100, 50);
162
Point position = mainWindow.getOuterPosition();
163

164
// Open popup window
165
WebWindow popupWindow = mainWindow.openWindow(
166
    new URL("https://example.com/popup"), 
167
    "popup"
168
);
169
```
170

171
### FrameWindow
172

173
Frame and iframe window implementation for handling embedded content.
174

175
```java { .api }
176
public class FrameWindow implements WebWindow {
177
    /**
178
     * Get the frame element that contains this window
179
     * @return the BaseFrameElement (HtmlFrame or HtmlInlineFrame)
180
     */
181
    public BaseFrameElement getFrameElement();
182
    
183
    /**
184
     * Get the source URL of this frame
185
     * @return the URL loaded in this frame
186
     */
187
    public URL getSrcAttribute();
188
    
189
    /**
190
     * Reload the frame content
191
     * @throws IOException if reload fails
192
     */
193
    public void reload() throws IOException;
194
    
195
    /**
196
     * Check if this frame allows navigation by parent
197
     * @return true if parent can navigate this frame
198
     */
199
    public boolean isAccessAllowed();
200
}
201
```
202

203
**Usage Examples:**
204

205
```java
206
HtmlPage page = webClient.getPage("https://example.com/frames");
207

208
// Find frame by name
209
WebWindow frameWindow = null;
210
for (WebWindow window : webClient.getWebWindows()) {
211
    if ("contentFrame".equals(window.getName())) {
212
        frameWindow = window;
213
        break;
214
    }
215
}
216

217
if (frameWindow instanceof FrameWindow) {
218
    FrameWindow frame = (FrameWindow) frameWindow;
219
    
220
    // Get frame information
221
    BaseFrameElement frameElement = frame.getFrameElement();
222
    URL frameSrc = frame.getSrcAttribute();
223
    
224
    // Access frame content
225
    Page frameContent = frame.getEnclosedPage();
226
    if (frameContent instanceof HtmlPage) {
227
        HtmlPage framePage = (HtmlPage) frameContent;
228
        String frameTitle = framePage.getTitleText();
229
    }
230
    
231
    // Reload frame
232
    frame.reload();
233
}
234
```
235

236
### Window Collection Management
237

238
Access and manage multiple windows and frames.
239

240
```java { .api }
241
/**
242
 * Get all open windows
243
 * @return List of all WebWindow objects
244
 */
245
public List<WebWindow> getWebWindows();
246

247
/**
248
 * Get all top-level windows
249
 * @return List of TopLevelWindow objects
250
 */
251
public List<TopLevelWindow> getTopLevelWindows();
252

253
/**
254
 * Get the currently active window
255
 * @return the current WebWindow
256
 */
257
public WebWindow getCurrentWindow();
258

259
/**
260
 * Set the active window
261
 * @param window the WebWindow to make current
262
 */
263
public void setCurrentWindow(WebWindow window);
264

265
/**
266
 * Open a target window (handles _blank, _self, named windows)
267
 * @param opener the window that initiated the open
268
 * @param windowName the target window name
269
 * @param defaultName default name if windowName is generic
270
 * @return the target WebWindow
271
 */
272
public WebWindow openTargetWindow(WebWindow opener, String windowName, String defaultName);
273

274
/**
275
 * Close all windows
276
 */
277
public void closeAllWindows();
278
```
279

280
**Usage Examples:**
281

282
```java
283
WebClient webClient = new WebClient();
284

285
// Load page with multiple frames
286
HtmlPage mainPage = webClient.getPage("https://example.com/frameset");
287

288
// Get all windows (main + frames)
289
List<WebWindow> allWindows = webClient.getWebWindows();
290
System.out.println("Total windows: " + allWindows.size());
291

292
// Process each window
293
for (WebWindow window : allWindows) {
294
    String name = window.getName();
295
    Page page = window.getEnclosedPage();
296
    
297
    if (page instanceof HtmlPage) {
298
        HtmlPage htmlPage = (HtmlPage) page;
299
        System.out.println("Window '" + name + "': " + htmlPage.getTitleText());
300
    }
301
}
302

303
// Get only top-level windows
304
List<TopLevelWindow> topWindows = webClient.getTopLevelWindows();
305

306
// Switch between windows
307
WebWindow originalWindow = webClient.getCurrentWindow();
308
for (WebWindow window : allWindows) {
309
    if ("targetFrame".equals(window.getName())) {
310
        webClient.setCurrentWindow(window);
311
        // Perform operations in this window context
312
        break;
313
    }
314
}
315

316
// Restore original window
317
webClient.setCurrentWindow(originalWindow);
318
```
319

320
### Window Event Handling
321

322
Handle window lifecycle events.
323

324
```java { .api }
325
public interface WebWindowListener {
326
    /**
327
     * Called when a new window is opened
328
     * @param event the WebWindowEvent with details
329
     */
330
    void webWindowOpened(WebWindowEvent event);
331
    
332
    /**
333
     * Called when a window is closed
334
     * @param event the WebWindowEvent with details
335
     */
336
    void webWindowClosed(WebWindowEvent event);
337
    
338
    /**
339
     * Called when window content changes
340
     * @param event the WebWindowEvent with details
341
     */
342
    void webWindowContentChanged(WebWindowEvent event);
343
}
344

345
public class WebWindowEvent {
346
    /**
347
     * Get the window that generated this event
348
     * @return the WebWindow source
349
     */
350
    public WebWindow getWebWindow();
351
    
352
    /**
353
     * Get the old page (for content change events)
354
     * @return the previous Page, or null
355
     */
356
    public Page getOldPage();
357
    
358
    /**
359
     * Get the new page (for content change events)
360
     * @return the new Page, or null
361
     */
362
    public Page getNewPage();
363
}
364

365
/**
366
 * Add a window event listener
367
 * @param listener the WebWindowListener to add
368
 */
369
public void addWebWindowListener(WebWindowListener listener);
370

371
/**
372
 * Remove a window event listener
373
 * @param listener the WebWindowListener to remove
374
 */
375
public void removeWebWindowListener(WebWindowListener listener);
376
```
377

378
**Usage Examples:**
379

380
```java
381
WebClient webClient = new WebClient();
382

383
// Add window event listener
384
webClient.addWebWindowListener(new WebWindowListener() {
385
    @Override
386
    public void webWindowOpened(WebWindowEvent event) {
387
        WebWindow window = event.getWebWindow();
388
        System.out.println("Window opened: " + window.getName());
389
    }
390
    
391
    @Override
392
    public void webWindowClosed(WebWindowEvent event) {
393
        WebWindow window = event.getWebWindow();
394
        System.out.println("Window closed: " + window.getName());
395
    }
396
    
397
    @Override
398
    public void webWindowContentChanged(WebWindowEvent event) {
399
        WebWindow window = event.getWebWindow();
400
        Page newPage = event.getNewPage();
401
        System.out.println("Content changed in window: " + window.getName());
402
        
403
        if (newPage instanceof HtmlPage) {
404
            HtmlPage htmlPage = (HtmlPage) newPage;
405
            System.out.println("New page title: " + htmlPage.getTitleText());
406
        }
407
    }
408
});
409

410
// Navigation will trigger content change events
411
HtmlPage page = webClient.getPage("https://example.com");
412
```
413

414
### Popup and Dialog Windows
415

416
Handle popup windows and JavaScript dialogs.
417

418
```java { .api }
419
/**
420
 * Enable or disable popup blocking
421
 * @param enabled true to block popups
422
 */
423
public void setPopupBlockerEnabled(boolean enabled);
424

425
/**
426
 * Check if popup blocking is enabled
427
 * @return true if popups are blocked
428
 */
429
public boolean isPopupBlockerEnabled();
430
```
431

432
**Usage Examples:**
433

434
```java
435
WebClient webClient = new WebClient();
436

437
// Control popup behavior
438
webClient.getOptions().setPopupBlockerEnabled(false); // Allow popups
439

440
// Page with popup links
441
HtmlPage page = webClient.getPage("https://example.com/popups");
442
HtmlAnchor popupLink = page.getAnchorByName("openPopup");
443

444
// Click link that opens popup
445
Page result = popupLink.click();
446

447
// Check if new window was created
448
List<WebWindow> windows = webClient.getWebWindows();
449
if (windows.size() > 1) {
450
    WebWindow popupWindow = windows.get(windows.size() - 1);
451
    System.out.println("Popup opened: " + popupWindow.getName());
452
    
453
    // Access popup content
454
    Page popupContent = popupWindow.getEnclosedPage();
455
}
456

457
// Close popup windows
458
for (WebWindow window : webClient.getWebWindows()) {
459
    if (window instanceof TopLevelWindow && !"main".equals(window.getName())) {
460
        ((TopLevelWindow) window).close();
461
    }
462
}
463
```