Documentation

Introduction
Guides

Browser

This guide describes how to create, use, and close Browser.

Please consider reading the Architecture guide to better understand how the JxBrowser architecture is designed, what main components it provides, and how it works.

Creating Browser

To create a new Browser instance please use the Profile.newBrowser() method. For example:

Browser browser = profile.newBrowser();

If you use Engine.newBrowser() then the browser is created under the default profile.

Browser browser = engine.newBrowser();

This method performs the following actions:

  1. Creates a new Browser instance.
  2. Loads the about:blank web page in it and waits until the web page is loaded completely.

Closing Browser

The Browser instance is running in a separate native process that allocates memory and system resources to be released. So, when a Browser instance is no longer needed, it should be closed through the Browser.close() method to release all the allocated memory and system resources. For example:

Browser browser = engine.newBrowser();
...
browser.close();

An attempt to use an already closed Browser instance will lead to the IllegalStateException.

The Browser instance is closed automatically in the following cases:

  1. When its Engine is closed or unexpectedly crashed.
  2. When Browser is a pop-up that is closed from JavaScript using window.close().

To get notifications when the Browser instance is closed, please use the BrowserClosed event. For example:

browser.on(BrowserClosed.class, event -> {});

To check whether Browser is closed please use the isClosed() method:

boolean closed = browser.isClosed();

Browser Size

By default Browser size is empty. If you want to work with DOM or Find Text on a web page please configure the size.

To update the size of the Browser please use resize(int width, int height). For example:

browser.resize(800, 600);

This method notifies Chromium that the size of the Browser has been changed. Chromium will update the DOM layout of the loaded web page and repaint its content asynchronously. So, it might take some time for the web page to be repainted after the method returns.

User Agent

You can override the default User Agent string and configure Browser to use a custom string. For example:

browser.userAgent("<user-agent>");

To get the current user agent string please use:

String userAgent = browser.userAgent();

Remote Debugging URL

To get the remote debugging URL for a web page loaded in a particular Browser instance, use the following approach:

browser.devTools().remoteDebuggingUrl().ifPresent(url -> {});

This approach returns a valid URL only if the Engine was configured with the Remote Debugging Port.

Mouse and Keyboard Events

JxBrowser provides functionality that allows you to intercept the mouse and keyboard events before they will be sent to the web page using the following callbacks:

  • EnterMouseCallback
  • ExitMouseCallback
  • MoveMouseCallback
  • MoveMouseWheelCallback
  • PressKeyCallback
  • PressMouseCallback
  • ReleaseKeyCallback
  • ReleaseMouseCallback
  • TypeKeyCallback

The following example demonstrates how to suppress mouse wheel:

browser.set(MoveMouseWheelCallback.class, params -> Response.suppress());

You can use these callbacks to get notifications about the mouse and keyboard events in order to implement hotkeys in your application. Or you can suppress the default shortcuts such as Ctrl+C on Windows and Linux. For example:

browser.set(PressKeyCallback.class, params -> {
    KeyPressed event = params.event();
    boolean keyCodeC = event.keyCode() == KeyCode.KEY_CODE_C;
    boolean controlDown = event.keyModifiers().isControlDown();
    if (controlDown && keyCodeC) {
        return PressKeyCallback.Response.suppress();
    }
    return PressKeyCallback.Response.proceed();
});

Dispatch Keyboard Events

You can simulate typing into the focused DOM element of Browser.

import static com.google.common.util.concurrent.Uninterruptibles.awaitUninterruptibly;
import static com.teamdev.jxbrowser.dom.event.EventType.KEY_DOWN;
import static com.teamdev.jxbrowser.dom.event.EventType.KEY_PRESS;
import static com.teamdev.jxbrowser.dom.event.EventType.KEY_UP;
import static com.teamdev.jxbrowser.engine.RenderingMode.HARDWARE_ACCELERATED;
import static java.lang.String.format;

import com.teamdev.jxbrowser.browser.Browser;
import com.teamdev.jxbrowser.dom.Element;
import com.teamdev.jxbrowser.dom.event.Event;
import com.teamdev.jxbrowser.dom.event.KeyEvent;
import com.teamdev.jxbrowser.engine.Engine;
import com.teamdev.jxbrowser.engine.EngineOptions;
import com.teamdev.jxbrowser.frame.Frame;
import com.teamdev.jxbrowser.navigation.event.FrameLoadFinished;
import com.teamdev.jxbrowser.view.swing.BrowserView;
import java.awt.BorderLayout;
import java.util.Optional;
import java.util.concurrent.CountDownLatch;
import javax.swing.JFrame;
import javax.swing.SwingUtilities;
import javax.swing.WindowConstants;

/**
 * This examples demonstrates how to capture keyboard events from the DOM nodes.
 */
public class DomKeyEvents {

    private static final String INPUT_FIELD_ID = "input-field";
    private static final String HTML = "<input type='text' id='" + INPUT_FIELD_ID + "' />";

    public static void main(String[] args) {
        EngineOptions options = EngineOptions.newBuilder(HARDWARE_ACCELERATED).build();
        Engine engine = Engine.newInstance(options);
        Browser browser = engine.newBrowser();

        SwingUtilities.invokeLater(() -> {
            BrowserView view = BrowserView.newInstance(browser);

            JFrame frame = new JFrame("DOM Keyboard Event Listener ");
            frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE);
            frame.add(view, BorderLayout.CENTER);
            frame.setSize(800, 600);
            frame.setLocationRelativeTo(null);
            frame.setVisible(true);
        });
        loadHtmlAndWait(browser);

        findInputField(browser).ifPresent(element -> {
            element.addEventListener(KEY_DOWN, DomKeyEvents::printEventDetails, false);
            element.addEventListener(KEY_PRESS, DomKeyEvents::printEventDetails, false);
            element.addEventListener(KEY_UP, DomKeyEvents::printEventDetails, false);
        });
    }

    private static void printEventDetails(Event event) {
        KeyEvent keyEvent = (KeyEvent) event;
        String message = format("Event type: %s. Typed character (if applicable): %s. Key: %s",
                keyEvent.type().value(), keyEvent.character(), keyEvent.domKeyCode());
        System.out.println(message);
    }

    private static void loadHtmlAndWait(Browser browser) {
        CountDownLatch latch = new CountDownLatch(1);
        browser.navigation().on(FrameLoadFinished.class, event -> latch.countDown());
        LoadHtml.loadHtmlAndWait(browser, HTML);
        awaitUninterruptibly(latch);
    }

    private static Optional<Element> findInputField(Browser browser) {
        return browser.mainFrame()
                .flatMap(Frame::document)
                .flatMap(document -> document.findElementById(INPUT_FIELD_ID));
    }
}
Go Top