The document describes how to embed a visual component that displays content of web pages in Swing and JavaFX applications.

Embedding

JxBrowser can be used in Java applications built with the following Java GUI frameworks:

  • Swing
  • JavaFX

The Browser component itself is not a visual component that allows displaying web page. To display the content of a web page loaded in Browser please use one of the following controls, depending on the GUI framework used:

  • com.teamdev.jxbrowser.view.swing.BrowserView
  • com.teamdev.jxbrowser.view.javafx.BrowserView

Swing

To display the content of a web page in a Java Swing application create an instance of the com.teamdev.jxbrowser.view.swing.BrowserView:

import com.teamdev.jxbrowser.view.swing.BrowserView;
...
BrowserView view = BrowserView.newInstance(browser.getId());

And embed it into a JFrame:

frame.add(view, BorderLayout.CENTER);

Here is the complete example:

import com.teamdev.jxbrowser.Browser;
import com.teamdev.jxbrowser.Engine;
import com.teamdev.jxbrowser.EngineOptions;
import com.teamdev.jxbrowser.RenderingMode;
import com.teamdev.jxbrowser.view.swing.BrowserView;
import java.awt.BorderLayout;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;
import javax.swing.JFrame;
import javax.swing.SwingUtilities;
import javax.swing.WindowConstants;

public class HelloWorld {

    public static void main(String[] args) {
        // Create and run Chromium engine.
        Engine engine = Engine.newInstance(EngineOptions.newBuilder()
                // Tell the engine to render content using GPU.
                .setRenderingMode(RenderingMode.HARDWARE_ACCELERATED)
                .build());

        Browser browser = Browser.newInstance(engine.getId());
        // Load the required web page.
        browser.getNavigation().loadUrl("https://html5test.com");

        SwingUtilities.invokeLater(() -> {
            // Create Swing component for rendering web content
            // loaded in the given Browser instance.
            BrowserView view = BrowserView.newInstance(browser.getId());

            // Create and display Swing app frame.
            JFrame frame = new JFrame("JxBrowser AWT/Swing");
            // Close Engine and closing app frame.
            frame.addWindowListener(new WindowAdapter() {
                @Override
                public void windowClosing(WindowEvent e) {
                    engine.close();
                }
            });
            frame.setDefaultCloseOperation(WindowConstants.DISPOSE_ON_CLOSE);
            frame.add(view, BorderLayout.CENTER);
            frame.setSize(800, 600);
            frame.setVisible(true);
        });
    }
}

The output of this example looks as follows: HTML5 Video

JavaFX

To display the content of a web page in a JavaFX application create an instance of the com.teamdev.jxbrowser.view.javafx.BrowserView:

import com.teamdev.jxbrowser.view.javafx.BrowserView;
...
BrowserView view = BrowserView.newInstance(browser.getId());

And embed it into a Scene:

Scene scene = new Scene(new BorderPane(view), 800, 600);

Here is the complete example:

import com.teamdev.jxbrowser.Browser;
import com.teamdev.jxbrowser.Engine;
import com.teamdev.jxbrowser.EngineOptions;
import com.teamdev.jxbrowser.RenderingMode;
import com.teamdev.jxbrowser.view.javafx.BrowserView;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;
import javafx.stage.Stage;

public class HelloWorld extends Application {

    @Override
    public void start(Stage primaryStage) {
        // Create and run Chromium engine.
        Engine engine = Engine.newInstance(EngineOptions.newBuilder()
                // Tell the engine to render content using GPU.
                .setRenderingMode(RenderingMode.HARDWARE_ACCELERATED)
                .build());
        Browser browser = Browser.newInstance(engine.getId());
        // Load the https://html5test.com web page.
        browser.getNavigation().loadUrl("https://html5test.com");

        // Create UI component for rendering web content
        // loaded in the given Browser instance.
        BrowserView view = BrowserView.newInstance(browser.getId());

        Scene scene = new Scene(new BorderPane(view), 800, 600);
        primaryStage.setTitle("JxBrowser JavaFX");
        primaryStage.setScene(scene);
        primaryStage.show();

        // Close the engine when stage is about to close.
        primaryStage.setOnCloseRequest(event -> engine.close());
    }
}

The output of this example looks as follows: HTML5 Video

Rendering

JxBrowser supports several rendering modes. In this section we will describe each of the modes with their performance and limitations, and provide you with recommendations on choosing the right mode depending on the type of the Java application.

Hardware Accelerated

In this rendering mode the library renders the content of a web page using the GPU in Chromium GPU process and displays it directly on a surface. In this mode the BrowserView creates and embeds a native heavyweight window (surface) on which the library renders the produced pixels.

Off-Screen

In this rendering mode the library renders the content of a web page using the GPU in Chromium GPU process and copies the pixels to an off-screen buffer allocated in the Java process memory. In this mode the BrowserView creates and embeds a lightweight component that reads the pixels from the off-screen buffer and displays them using the standard Java Graphics API.

Performance

The rendering modes have different performance. For example, if we play an HTML5 video full screen (2880x1800) on MacBook Pro (15-inch, 2017) with the following hardware:

  • CPU: 2.9 GHz Intel Core i7
  • RAM: 16 GB 2133 MHz LPDDR3
  • GPU: Radeon Pro 560 4096 MB
  • Built-in Display: 15.4-inch (2880 x 1800)

the rendering performance in Frame Per Second (FPS) would be: Rendering Performance

Limitations

Mixing Heavyweight and Lightweight

Please do not embed the BrowserView into a JInternalFrame or JLayeredPane, or display other Swing components over the BrowserView when the HARDWARE_ACCELERATED rendering mode is enabled. In this mode BrowserView displays a native heavyweight window. Displaying a heavyweight window inside a lightweight component leads to a well-known issue with mixing heavyweight and lightweight components.

According to the article the issue with mixing the heavyweight and lightweight components has been fixed in JDK 6 Update 12 and JDK 7 build 19. It is true only for the Java Swing heavyweight components such as java.awt.Canvas. JxBrowser embeds its own heavyweight native widget. So, the fix will not be applied in this case.

JavaFX Layered Windows

Configuring a JavaFX Stage with the StageStyle.TRANSPARENT style adds the WS_EX_LAYERED window style flag to JavaFX window on Windows. This flag is used to create a layered window. The layered window is a window that draws its content off-screen. If we embed a native window into a layered window when the HARDWARE_ACCELERATED rendering mode is enabled, its content will not be painted because of the window types conflict.

Mouse, Keyboard, Touch, Drag and Drop

In the OFF_SCREEN rendering mode on Windows and Linux, and both HARDWARE_ACCELERATED and OFF_SCREEN modes on macOS, the mouse, keyboard, and touch events are processed on the Java side and forwarded to the Chromium engine. Right now Java does not provide a fully functional touch events support, so JxBrowser does not support some touch gestures in these rendering modes. The same limitation applies to the Drag and Drop (DnD) functionality. In these rendering modes DnD is processed using the Java API, so it does not work exactly like in Google Chrome. DnD supports only the predefined set of flavours.

Go Top