Introduction
Guides
- Engine
- Browser
- BrowserView
- Navigation
- Content
- DOM
- JavaScript
- Pop-ups
- Dialogs
- Downloads
- Network
- Cache
- Cookies
- Proxy
- Authentication
- Plugins
- Printing
- Media
- Zoom
- Spell Checker
- Deployment
- Chromium
- Troubleshooting
Migration
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 Engine.newBrowser()
method. For example:
Browser browser = engine.newBrowser();
This method performs the following actions:
- Creates a new
Browser
instance. - 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:
- When its
Engine
is closed or unexpectedly crashed. - When
Browser
is a pop-up that is closed from JavaScript usingwindow.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 com.google.common.collect.ImmutableMap;
import com.teamdev.jxbrowser.browser.Browser;
import com.teamdev.jxbrowser.engine.Engine;
import com.teamdev.jxbrowser.engine.EngineOptions;
import com.teamdev.jxbrowser.navigation.event.FrameLoadFinished;
import com.teamdev.jxbrowser.ui.KeyCode;
import com.teamdev.jxbrowser.ui.event.KeyPressed;
import com.teamdev.jxbrowser.ui.event.KeyReleased;
import com.teamdev.jxbrowser.ui.event.KeyTyped;
import com.teamdev.jxbrowser.view.swing.BrowserView;
import javax.swing.*;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;
import java.util.Map;
import java.util.concurrent.CountDownLatch;
import static com.google.common.util.concurrent.Uninterruptibles.awaitUninterruptibly;
import static com.teamdev.jxbrowser.engine.RenderingMode.HARDWARE_ACCELERATED;
/**
* This example demonstrates how to dispatch the {@code KeyEvent} to
* the currently focused element on the loaded web page.
*/
public final class DispatchKeyEventExample {
private static final String HTML = "<input id=\"input\" autofocus>";
private static final Map<Character, KeyCode> charToKeyCode;
static {
charToKeyCode = ImmutableMap.<Character, KeyCode>builder()
.put('h', KeyCode.KEY_CODE_H)
.put('i', KeyCode.KEY_CODE_I)
.build();
}
public static void main(String[] args) {
Engine engine = Engine.newInstance(EngineOptions.newBuilder(HARDWARE_ACCELERATED).build());
Browser browser = engine.newBrowser();
SwingUtilities.invokeLater(() -> {
BrowserView view = BrowserView.newInstance(browser);
JFrame frame = new JFrame("Dispatch key event");
frame.addWindowListener(new WindowAdapter() {
@Override
public void windowClosing(WindowEvent e) {
engine.close();
}
});
frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE);
frame.add(view);
frame.setSize(800, 500);
frame.setLocationRelativeTo(null);
frame.setVisible(true);
});
loadHtmlAndWait(browser, HTML);
dispatchKey(browser, 'h');
dispatchKey(browser, 'i');
}
private static void loadHtmlAndWait(Browser browser, String html) {
CountDownLatch latch = new CountDownLatch(1);
browser.navigation().on(FrameLoadFinished.class, event -> latch.countDown());
browser.mainFrame().ifPresent(frame -> frame.loadHtml(html));
awaitUninterruptibly(latch);
}
private static void dispatchKey(Browser browser, char character) {
dispatchKeyEvent(browser, character, charToKeyCode.get(character));
}
private static void dispatchKeyEvent(Browser browser, char character, KeyCode keyCode) {
KeyPressed keyPressed = KeyPressed.newBuilder(keyCode)
.keyChar(character)
.build();
KeyTyped keyTyped = KeyTyped.newBuilder(keyCode)
.keyChar(character)
.build();
KeyReleased keyReleased = KeyReleased.newBuilder(keyCode)
.build();
browser.dispatch(keyPressed);
browser.dispatch(keyTyped);
browser.dispatch(keyReleased);
}
}