com.teamdev.jxbrowser.browser

Interface Browser

All Superinterfaces:

Advisable<BrowserCallback>, java.lang.AutoCloseable, Closeable, Observable<BrowserEvent>

public interface Browser
extends Closeable, Advisable<BrowserCallback>, Observable<BrowserEvent>

A web browser control that allows loading a web page or a local HTML file, accessing DOM and executing JavaScript on the loaded web page, getting notifications about loading progress, dispatching keyboard and mouse events, etc.

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

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

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

The Browser instance is closed automatically when its Engine is closed or unexpectedly crashed. If the instance represents a popup window created by JavaScript via the window.open() function, then JavaScript can close the instance using the window.close() function.

To get notifications that the Browser instance has been closed please subscribe to the following event:

 browser.on(BrowserClosed.class, event -> {
     // The Browser instance has been closed.
 });
 

Method Summary

Modifier and Type	Method and Description
Audio	audio() Returns Audio that allows controlling audio on a web page loaded in the current browser instance.
Bitmap	bitmap() Returns a Bitmap that contains the image of the currently loaded web page.
void	close() Closes the current browser instance and releases all allocated resources.
void	close(CloseOptions options) Closes the current browser instance according to the given options.
DevTools	devTools() Returns DevTools that allows working with Chromium Developer Tools.
void	dispatch(KeyPressed event) Dispatches the key pressed event to the currently focused element on the loaded web page.
void	dispatch(KeyReleased event) Dispatches the key released event to the currently focused element on the loaded web page.
void	dispatch(KeyTyped event) Dispatches the key typed event to the currently focused element on the loaded web page.
void	dispatch(MouseDragged event) Dispatches the mouse dragged event to the currently loaded web page.
void	dispatch(MouseEntered event) Dispatches the mouse entered event to the currently loaded web page.
void	dispatch(MouseExited event) Dispatches the mouse exited event to the currently loaded web page.
void	dispatch(MouseMoved event) Dispatches the mouse moved event to the currently loaded web page.
void	dispatch(MousePressed event) Dispatches the mouse pressed event to the currently loaded web page.
void	dispatch(MouseReleased event) Dispatches the mouse released event to the currently loaded web page.
void	dispatch(MouseWheel event) Dispatches the mouse wheel event to the currently loaded web page.
Display	display() Returns the display where the current browser instance is located.
Engine	engine() Returns the engine instance of the current browser.
Bitmap	favicon() Returns a Bitmap that contains the favicon of the currently loaded web page or a Bitmap that contains default Chromium favicon if the browser did not load any web pages or loaded web page URL is invalid.
void	focus() Tells the current browser instance that it has focus and must be activated.
java.util.Optional<Frame>	focusedFrame() Returns an Optional that contains the focused Frame on the currently loaded web page, otherwise an empty Optional.
java.util.List<Frame>	frames() Returns all the frames on the currently loaded web page or an empty collection if the current browser did not load any web pages.
java.util.Optional<Frame>	mainFrame() Returns an Optional that contains the main Frame of the currently loaded web page if it exists, otherwise an empty Optional.
Navigation	navigation() Returns Navigation that allows controlling navigation in the current browser instance.
Profile	profile() Returns the profile that the browser belongs to.
void	replaceMisspelledWord(java.lang.String word) Replaces misspelled word under cursor on the currently loaded web page with the given word.
void	resize(int width, int height) Updates size of this Browser instance with the given width and height.
void	resize(Size size) Updates size of the current browser instance with the given one.
boolean	saveWebPage(java.nio.file.Path htmlFilePath, java.nio.file.Path resourcesDir, SavePageType saveType) Initiates the saving process of the currently loaded web page.
BrowserSettings	settings() Returns BrowserSettings that allows configuring the current browser instance.
Size	size() Returns the size of the current browser instance in the logical pixels.
TextFinder	textFinder() Returns TextFinder that allows finding text on a web page loaded in the current browser instance.
java.lang.String	title() Returns a string that represents the title of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
void	unfocus() Tells the current browser instance that it does not have focus and must be deactivated.
java.lang.String	url() Returns a string that represents URL of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.
java.lang.String	userAgent() Returns a string that represents the user-agent of the current browser instance.
void	userAgent(java.lang.String userAgent) Updates the user-agent string of the current browser instance and reloads the currently loaded web page.
Zoom	zoom() Returns Zoom that allows zooming content of a web page loaded in the current browser instance.

Methods inherited from interface com.teamdev.jxbrowser.Closeable

isClosed

Methods inherited from interface com.teamdev.jxbrowser.callback.Advisable

get, remove, set

Methods inherited from interface com.teamdev.jxbrowser.event.Observable

on

Method Detail

engine

Engine engine()

Returns the engine instance of the current browser.

profile

Profile profile()

Returns the profile that the browser belongs to.

mainFrame

java.util.Optional<Frame> mainFrame()

Returns an Optional that contains the main Frame of the currently loaded web page if it exists, otherwise an empty Optional.

Make sure that the web page is loaded completely before accessing its main frame.

Throws:

java.lang.IllegalStateException - when the browser is already closed

focusedFrame

java.util.Optional<Frame> focusedFrame()

Returns an Optional that contains the focused Frame on the currently loaded web page, otherwise an empty Optional.

Make sure that the web page is loaded completely before accessing its focused frame.

Throws:

java.lang.IllegalStateException - when the browser is already closed

frames

java.util.List<Frame> frames()

Returns all the frames on the currently loaded web page or an empty collection if the current browser did not load any web pages.

Throws:

java.lang.IllegalStateException - when the browser is already closed

bitmap

Bitmap bitmap()

Returns a Bitmap that contains the image of the currently loaded web page.

The bitmap size depends on the size of the current browser instance and the device scale factor of the display where it is located at the moment. If the current browser size is empty, then the bitmap will be empty as well.

For example, if the device scale factor of the display where the browser instance is located at the moment is 2.0 and the browser size is 100x100, then the size of the bitmap is expected to be 200x200.

Throws:

java.lang.IllegalStateException - when the browser is already closed

Since:

7.1

See Also:

size(), display()

favicon

Bitmap favicon()

Returns a Bitmap that contains the favicon of the currently loaded web page or a Bitmap that contains default Chromium favicon if the browser did not load any web pages or loaded web page URL is invalid.

Maximum bitmap size is 16x16. If actual favicon size is bigger it will be resized to fit this constant.

Throws:

java.lang.IllegalStateException - when the browser is already closed

Since:

7.2

textFinder

TextFinder textFinder()

Returns TextFinder that allows finding text on a web page loaded in the current browser instance.

zoom

Zoom zoom()

Returns Zoom that allows zooming content of a web page loaded in the current browser instance.

audio

Audio audio()

Returns Audio that allows controlling audio on a web page loaded in the current browser instance.

navigation

Navigation navigation()

Returns Navigation that allows controlling navigation in the current browser instance.

settings

BrowserSettings settings()

Returns BrowserSettings that allows configuring the current browser instance.

devTools

DevTools devTools()

Returns DevTools that allows working with Chromium Developer Tools.

Since:

7.1

replaceMisspelledWord

void replaceMisspelledWord(java.lang.String word)

Replaces misspelled word under cursor on the currently loaded web page with the given word. If there is no misspelled word under cursor, this method does nothing.

Parameters:

word - a string that represents the word for replacement

Throws:

java.lang.IllegalArgumentException - when word is an empty or blank string

saveWebPage

boolean saveWebPage(java.nio.file.Path htmlFilePath,
                    java.nio.file.Path resourcesDir,
                    SavePageType saveType)

Initiates the saving process of the currently loaded web page. The web page can be saved as a single HTML file or the file with resources. Before saving a web page make sure that it is not being loaded. It is recommended to completely loaded the web page and only then save it.

Parameters:

htmlFilePath - an absolute path to a file in which the web page will be saved

resourcesDir - an absolute path to a directory in which the resources (e.g. images, css) of the web page will be saved. If the directory does not exist, it will be created

saveType - determines how the web page will be saved: as an HTML file with all the required resources (e.g. images, css etc.), a single HTML or MHTML file

Returns:

true if the saving process has been initialized successfully

Throws:

java.lang.IllegalStateException - when the browser is already closed

url

java.lang.String url()

Returns a string that represents URL of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.

Throws:

java.lang.IllegalStateException - when the browser is already closed

title

java.lang.String title()

Returns a string that represents the title of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.

Throws:

java.lang.IllegalStateException - when the browser is already closed

userAgent

java.lang.String userAgent()

Returns a string that represents the user-agent of the current browser instance.

The user-agent string can be overridden for each browser instance via userAgent(String). If the string has not been overridden, then this method returns the default user-agent string obtained through Network.userAgent().

Throws:

java.lang.IllegalStateException - when the browser is already closed

See Also:

Network.userAgent()

userAgent

void userAgent(java.lang.String userAgent)

Updates the user-agent string of the current browser instance and reloads the currently loaded web page.

Parameters:

userAgent - a new user-agent string

Throws:

java.lang.IllegalStateException - when the browser is already closed

java.lang.IllegalArgumentException - when userAgent is empty or blank

focus

void focus()

Tells the current browser instance that it has focus and must be activated.

Throws:

java.lang.IllegalStateException - when the browser is already closed

unfocus

void unfocus()

Tells the current browser instance that it does not have focus and must be deactivated.

Throws:

java.lang.IllegalStateException - when the browser is already closed

resize

void resize(Size size)

Updates size of the current browser instance with the given one. By default, the size of the browser is empty. Many web pages rely on the browser size and require that it is not empty. The DOM document of a web page might not be loaded and displayed at all, because there is no sense in loading and rendering DOM document when it is empty.

Use this method when you do not need to display content of the loaded web page, but the web page must "think" it has been loaded in a browser instance with a non-empty size.

Parameters:

size - a new size in the logical pixels

Throws:

java.lang.IllegalArgumentException - when size is empty

java.lang.IllegalStateException - when the browser is already closed

resize

void resize(int width,
            int height)

Updates size of this Browser instance with the given width and height. By default, Browser's size is empty. Many web pages rely on the Browser's size and require that it is not empty. DOM document of a web page might not be loaded and displayed at all, because there is no sense in loading and rendering DOM document when it is empty.

Use this method when you do not need to display content of the loaded web page, but the web page must "think" it has been loaded in a Browser instance with non-empty size.

Parameters:

width - the specified width in the logical pixels

height - the specified height in the logical pixels

Throws:

java.lang.IllegalArgumentException - when width or height is not positive

java.lang.IllegalStateException - when this Browser is already closed

size

Size size()

Returns the size of the current browser instance in the logical pixels. By default, the size of the browser is empty.

Throws:

java.lang.IllegalStateException - when the browser is already closed

Since:

7.1

display

Display display()

Returns the display where the current browser instance is located. By default, it is a primary display.

Throws:

java.lang.IllegalStateException - when the browser is already closed

Since:

7.1

dispatch

void dispatch(KeyPressed event)

Dispatches the key pressed event to the currently focused element on the loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the key pressed event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(KeyReleased event)

Dispatches the key released event to the currently focused element on the loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the key released event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(KeyTyped event)

Dispatches the key typed event to the currently focused element on the loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the key typed event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MousePressed event)

Dispatches the mouse pressed event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse pressed event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseReleased event)

Dispatches the mouse released event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse released event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseEntered event)

Dispatches the mouse entered event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse entered event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseExited event)

Dispatches the mouse exited event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse exited event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseDragged event)

Dispatches the mouse dragged event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse dragged event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseMoved event)

Dispatches the mouse moved event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse moved event

Throws:

java.lang.IllegalStateException - when the browser is already closed

dispatch

void dispatch(MouseWheel event)

Dispatches the mouse wheel event to the currently loaded web page. It does nothing if the browser instance hasn't loaded any web page.

Parameters:

event - the mouse wheel event

Throws:

java.lang.IllegalStateException - when the browser is already closed

close

void close()

Closes the current browser instance and releases all allocated resources.

The unload and beforeunload JavaScript events will not be fired in this case. This method is equivalent of close(CloseOptions.newBuilder().build()).

If the browser is already closed, then this method does nothing.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface Closeable

See Also:

close(CloseOptions)

close

void close(CloseOptions options)

Closes the current browser instance according to the given options.

If the currently loaded web page registers the onbeforeunload JavaScript event and the given options tell the browser to fire the beforeunload event, then this method will not close the browser right away.

The BeforeUnloadCallback will be invoked in this case and if the callback tells the browser to stay on the web page, then the browser will not be closed.

The following example demonstrates how to close the browser instance as if a user manually clicking the close button of the tab/window.

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

If the browser is already closed, then this method does nothing.

Since:

7.6