WebWindow

All pages are contained within WebWindow objects. This could be a TopLevelWindow representing an actual browser window, an HtmlFrame representing a <frame> element or an HtmlInlineFrame representing an <iframe> element.

When a WebClient is first instantiated, a TopLevelWindow is automatically created. You could think of this as being the first window displayed by a web browser. Calling WebClient.getPage(WebWindow, WebRequest) will load the new page into this window.

The JavaScript open() function can be used to load pages into other windows. New WebWindow objects will be created automatically by this function.

WebWindowEvents

If you wish to be notified when windows are created or pages are loaded, you need to register a WebWindowListener with the WebClient via the method WebClient.addWebWindowListener(WebWindowListener)

When a window is opened either by JavaScript or through the WebClient, a WebWindowEvent will be fired and passed into the WebWindowListener.webWindowOpened(WebWindowEvent) method. Note that both the new and old pages in the event will be null as the window does not have any content loaded at this point. If a URL was specified during creation of the window then the page will be loaded and another event will be fired as described below.

When a new page is loaded into a specific window, a WebWindowEvent will be fired and passed into the WebWindowListener.webWindowContentChanged(WebWindowEvent) method.

Frame Example I

Getting the page inside <frame> element or <iframe> element can be done by using HtmlPage.getFrames().
Suppose you have the following page:

<html>
  <body>
    <iframe src="two.html">
  </body>
</html>

You can use the following code to get the content of two.html:

final List<FrameWindow> window = page.getFrames();
final HtmlPage pageTwo = (HtmlPage) window.get(0).getEnclosedPage();

Frame Example II

Another example that navigates API docs to get a desired page of a class:

final WebClient client = new WebClient();
final HtmlPage mainPage = client.getPage("http://htmlunit.sourceforge.net/apidocs/index.html");

To get the page of the first frame (at upper left) and click the sixth link:

final HtmlPage packageListPage = (HtmlPage) mainPage.getFrames().get(0).getEnclosedPage();
packageListPage.getAnchors().get(5).click();

To get the page of the frame named 'packageFrame' (at lower left) and click the second link:

final HtmlPage pakcagePage = (HtmlPage) mainPage.getFrameByName("packageFrame").getEnclosedPage();
pakcagePage.getAnchors().get(1).click();

To get the page of the frame named 'classFrame' (at right):

final HtmlPage classPage = (HtmlPage) mainPage.getFrameByName("classFrame").getEnclosedPage();