Dialogs

This guide shows how to handle the requests to display various dialogs.

By default JxBrowser does not display dialogs and is set to the silent mode where all the dialogs are automatically closed as if the user clicked the Cancel button in the dialog.

To change the default behavior you will need to register your own implementation of the appropriate callback for a particular dialog. In your implementation you decide how to display the dialog and provide the results to the engine. You can also create and display every dialog with given parameters.

JavaScript Dialogs

Alert

When a JavaScript alert dialog should be displayed the AlertCallback callback is invoked. It happens when the window.alert() JavaScript function is invoked.

In this callback you can obtain the dialog parameters such as title, message, and localized text of the “OK” action. When the dialog is closed tell.ok() must be called. For example:

browser.set(AlertCallback.class, (params, tell) -> {
    // Dialog title.
    String title = params.title();
    // Dialog message.
    String message = params.message();
    // The localized text of the "OK" callback action.
    String okActionText = params.okActionText();
    // Create and display the dialog if necessary.
    ...
    // The dialog has been closed.
    tell.ok();
});

JavaScript execution will be blocked until the Alert dialog is closed.

Confirm

When a JavaScript confirm dialog should be displayed the ConfirmCallback callback is invoked. It happens when the window.confirm() JavaScript function is invoked.

In this callback you can obtain the dialog parameters such as title, message, localized text of the “Yes” and “No” actions. When the dialog is closed tell.ok() or tell.cancel() must be called. For example:

browser.set(ConfirmCallback.class, (params, tell) -> {
    // Dialog title.
    String title = params.title();
    // Dialog message.
    String message = params.message();
    // The localized text of the "OK" action.
    String okActionText = params.okActionText();
    // The localized text of the "Cancel" action.
    String cancelActionText = params.cancelActionText();
    ...
    // The "OK" action has been selected.
    tell.ok();
});

JavaScript execution will be blocked until the Confirm dialog is closed.

Prompt

When a JavaScript prompt dialog should be displayed the PromptCallback callback is invoked. It happens when the window.prompt() JavaScript function is invoked.

In this callback you can obtain the dialog parameters such as title, message, text, localized text of the “OK” and “Cancel” actions. When the dialog is closed tell.ok(String) or tell.cancel() must be called. For example:

browser.set(PromptCallback.class, (params, tell) -> {
    // Dialog title.
    String title = params.title();
    // Dialog message.
    String message = params.message();
    // The localized text of the "OK" action.
    String okActionText = params.okActionText();
    // The localized text of the "Cancel" action.
    String cancelActionText = params.cancelActionText();
    ...
    // A text has been entered and the "OK" action has been selected.
    tell.ok("Entered text");
});

JavaScript execution will be blocked until the Prompt dialog is closed.

BeforeUnload

The onbeforeunload event is fired when the web page is about to be unloaded. This event allows you to display a message in a confirmation dialog to inform the user whether they want to stay or leave the current page.

The BeforeUnloadCallback callback is invoked, when the confirmation dialog should be displayed. In this callback you can obtain the dialog parameters such as title, message, localized text of the “Stay” and “Leave” actions. When the dialog is closed, tell.stay() or tell.leave() must be called. For example:

browser.set(BeforeUnloadCallback.class, (params, tell) -> {
    // Dialog title.
    String title = params.title();
    // Dialog message.
    String message = params.message();
    // The localized text of the "Stay" action.
    String stayActionText = params.stayActionText();
    // The localized text of the "Leave" action.
    String leaveActionText = params.leaveActionText();
    ...
    // The "Stay" action has been selected.
    tell.stay();
});

This callback will not be invoked when closing Browser instance via Browser.close().

If you would like to display the dialog when closing Browser, then please close the Browser using the following approach:

browser.close(CloseOptions.newBuilder().fireBeforeUnload().build());

Select Color

When a color should be selected a SelectColorCallback callback is invoked. It happens when a user clicks the input element with the color type:

<input type="color" value="#ff0000">

In this callback you can obtain the dialog parameters such as default color. When the dialog is closed tell.select(Color) or tell.cancel() must be called. For example:

browser.set(SelectColorCallback.class, (params, tell) -> {
    // The default color.
    Color defaultColor = params.defaultColor();
    // The selected color.
    Color selectedColor = Color.newBuilder()
            .red(1.0f)
            .green(1.0f)
            .blue(1.0f)
            .build();
    ...
    // The given color has been selected.
    tell.select(selectedColor);
});

Open File

When a web page wants the user to choose a file from their device storage the OpenFileCallback callback is invoked. It happens when the user clicks the input element with the file type:

<input type="file" accept="image/png, image/jpeg">

In this callback you can obtain the dialog parameters such as default file name, acceptable file extensions, and description of the acceptable file extensions. When the dialog is closed tell.open(Path) or tell.cancel()must be called. For example:

browser.set(OpenFileCallback.class, (params, tell) -> {
    // The default file name.
    String defaultFileName = params.defaultFileName();
    // Acceptable extensions.
    List<String> acceptableExtensions = params.acceptableExtensions();
    ...
    // The given file should be opened.
    tell.open(Paths.get("<path-to-selected-file>"));
});

Open Files

When a web page wants the user choose multiple files from their device storage the OpenFilesCallback callback is invoked. It happens when the user clicks the input element with the file type and the multiple attribute:

<input type="file" accept="image/png, image/jpeg" multiple>

In this callback you can obtain the dialog parameters such as default file name, acceptable file extensions, and description of the acceptable file extensions. When the dialog is closed tell.open(Path...) or tell.cancel() must be called. For example:

browser.set(OpenFilesCallback.class, (params, tell) -> {
    // Acceptable extensions.
    List<String> acceptableExtensions = params.acceptableExtensions();
    ...
    Path file1 = Paths.get("<path-to-selected-file1>");
    Path file2 = Paths.get("<path-to-selected-file1>");
    // The given files should be opened.
    tell.open(file1, file2);
});

Open Folder

When Chromium wants the user to choose a folder from their device storage the OpenFolderCallback callback is invoked.

If necessary, you can create and display a dialog where the user can choose the folder. When the dialog is closed tell.open(Path) or tell.cancel() must be called. For example:

browser.set(OpenFolderCallback.class, (params, tell) -> {
    ...
    // The given folder should be opened.
    tell.open(Paths.get("<path-to-folder>"));
});

Save As PDF

When saving a web page as PDF document through the Print Preview dialog the SaveAsPdfCallback callback is invoked.

In this callback you can obtain the dialog parameters such as default file name. When the dialog is closed tell.save(Path) or tell.cancel() must be called. For example:

browser.set(SaveAsPdfCallback.class, (params, tell) -> {
    // The suggested file name.
    String suggestedFileName = params.suggestedFileName();
    ...
    // The given file should be saved.
    tell.save(Paths.get("<path-to-file>"));
});

Select Client Certificate

When Chromium wants the user to select a client SSL certificate from the list of available certificates the SelectClientCertificateCallback callback is invoked.

In this callback you can obtain the dialog parameters such as dialog title, message, localized text of the “Select” and “Cancel” actions, the list of available certificates.

When the dialog is closed tell.select(int) or tell.cancel() must be called. For example:

browser.set(SelectClientCertificateCallback.class, (params, tell) -> {
    // The dialog title.
    String title = params.getTitle();
    // The dialog message.
    String message = params.getMessage();
    // The localized text of the "Select" action.
    String selectActionText = params.getSelectActionText();
    // The localized text of the "Cancel" action.
    String cancelActionText = params.getCancelActionText();
    // Available SSL certificates.
    List<Certificate> certificates = params.getCertificatesList();
    // The index of the last certificate in the list.
    int certificateIndex = certificates.size() - 1;
    ...
    // The last certificate in the list has been selected.
    tell.select(certificateIndex);
});

Open External App

When a web page wants to open a link in the associated external application the OpenExternalAppCallback callback is invoked.

In this callback you can get the localized dialog title, message, text of the “Open” and “Cancel” actions. You can display a dialog to the end users to decide whether the link can be opened or open the external application programmatically as shown in the example below:

browser.set(OpenExternalAppCallback.class, (params, tell) -> tell.open());

By default, the requests to open an external application will be canceled.

If you create a BrowserView control and embed it into your JavaFX, Swing, SWT app, the default UI-toolkit specific implementation of the callback will be registered. The end users will see the following dialog: