public interface Browser extends Closeable, Advisable<BrowserCallback>, Observable<BrowserEvent>
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. });
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. |
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. |
on
Engine engine()
java.util.Optional<Frame> mainFrame()
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.
java.lang.IllegalStateException
- when the current browser is already closedjava.util.Optional<Frame> focusedFrame()
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.
java.lang.IllegalStateException
- when the current browser is already closedjava.util.List<Frame> frames()
java.lang.IllegalStateException
- when the current browser is already closedBitmap bitmap()
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.
Bitmap favicon()
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.
TextFinder textFinder()
TextFinder
that allows finding text on a web page loaded in the current
browser instance.Zoom zoom()
Zoom
that allows zooming content of a web page loaded in the current browser
instance.Audio audio()
Audio
that allows controlling audio on a web page loaded in the current
browser instance.Navigation navigation()
Navigation
that allows controlling navigation in the current browser
instance.BrowserSettings settings()
BrowserSettings
that allows configuring the current browser instance.DevTools devTools()
DevTools
that allows working with Chromium Developer Tools.void replaceMisspelledWord(java.lang.String word)
word
. If there is no misspelled word under cursor, this method does nothing.word
- a string that represents the word for replacementjava.lang.IllegalArgumentException
- when word
is an empty or blank stringboolean saveWebPage(java.nio.file.Path htmlFilePath, java.nio.file.Path resourcesDir, SavePageType saveType)
htmlFilePath
- an absolute path to a file in which the web page will be savedresourcesDir
- 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 createdsaveType
- 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 filetrue
if the saving process has been initialized successfullyjava.lang.IllegalStateException
- when the current browser is already closedjava.lang.String url()
java.lang.IllegalStateException
- when the current browser is already closedjava.lang.String title()
java.lang.IllegalStateException
- when the current browser is already closedjava.lang.String userAgent()
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()
.
java.lang.IllegalStateException
- when the current browser is already closedNetwork.userAgent()
void userAgent(java.lang.String userAgent)
userAgent
- a new user-agent stringjava.lang.IllegalStateException
- when the current browser is already closedjava.lang.IllegalArgumentException
- when userAgent
is empty or blankvoid focus()
java.lang.IllegalStateException
- when the current browser is already closedvoid unfocus()
java.lang.IllegalStateException
- when the current browser is already closedvoid resize(Size size)
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.
size
- a new size in the logical pixelsjava.lang.IllegalArgumentException
- when size
is emptyjava.lang.IllegalStateException
- when the current browser is already closedvoid resize(int width, int height)
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.
width
- the specified width in the logical pixelsheight
- the specified height in the logical pixelsjava.lang.IllegalArgumentException
- when width
is negativejava.lang.IllegalArgumentException
- when height
is negativejava.lang.IllegalStateException
- when this Browser is already closedSize size()
Display display()
void dispatch(KeyPressed event)
event
- the key pressed eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(KeyReleased event)
event
- the key released eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(KeyTyped event)
event
- the key typed eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MousePressed event)
event
- the mouse pressed eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseReleased event)
event
- the mouse released eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseEntered event)
event
- the mouse entered eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseExited event)
event
- the mouse exited eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseDragged event)
event
- the mouse dragged eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseMoved event)
event
- the mouse moved eventjava.lang.IllegalStateException
- when the current browser is already closedvoid dispatch(MouseWheel event)
event
- the mouse wheel eventjava.lang.IllegalStateException
- when the current browser is already closedvoid close()
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.
close
in interface java.lang.AutoCloseable
close
in interface Closeable
close(CloseOptions)
void close(CloseOptions options)
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.