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. |
java.util.List<CaptureSession> |
captureSessions()
Returns an immutable list of all active capture sessions initiated by the browser.
|
java.util.concurrent.CompletableFuture<CastSession> |
cast(MediaReceiver receiver)
Starts casting the browser content to the media
receiver . |
java.util.concurrent.CompletableFuture<CastSession> |
castScreen(MediaReceiver receiver)
Starts casting screen's content by selecting the screen in the picker dialog.
|
java.util.concurrent.CompletableFuture<CastSession> |
castScreen(MediaReceiver receiver,
ScreenCastOptions options)
Starts casting the screen's content to the media
receiver . |
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.
|
FullScreen |
fullScreen()
Returns the service that controls the fullscreen mode.
|
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. |
on
Engine engine()
Profile profile()
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.
ObjectClosedException
- when the 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.
ObjectClosedException
- when the browser is already closedjava.util.List<Frame> frames()
ObjectClosedException
- when the 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.
ObjectClosedException
- when the browser is already closedBitmapTimeoutException
- when the bitmap can not be retrieved within 10
secondssize()
,
display()
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.
ObjectClosedException
- when the browser is already closedTextFinder 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.java.util.List<CaptureSession> captureSessions()
ObjectClosedException
- if the browser is closedAudio 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.FullScreen fullScreen()
java.util.concurrent.CompletableFuture<CastSession> cast(MediaReceiver receiver)
receiver
.
In case when the web page has the default PresentationRequest
:
const presentationRequest = new PresentationRequest(['receiver/index.html']); navigator.presentation.defaultRequest = presentationRequest;
the presentation of the media content specified in this request is started instead of
casting the browser content. This implies that receiver
should support the
CastMode.PRESENTATION
cast mode. Otherwise, if there is no default
PresentationRequest
, receiver
should support the CastMode.BROWSER
cast mode.
Returns a new CompletableFuture
that is completed when the cast session has been
started. If the cast session has not been started, the future is completed with
CastSessionStartFailedException
. If the browser is closed during the casting start,
the future will be canceled.
java.lang.IllegalStateException
- if media routing is disabledjava.util.concurrent.CompletableFuture<CastSession> castScreen(MediaReceiver receiver)
Returns a new CompletableFuture
that is completed when the cast session has been
started. If the cast session has not been started, the future is completed with
CastSessionStartFailedException
. If the browser is closed during the casting start,
the future will be canceled.
The receiver
should support the CastMode.SCREEN
cast mode.
java.lang.IllegalStateException
- if media routing is disabledjava.util.concurrent.CompletableFuture<CastSession> castScreen(MediaReceiver receiver, ScreenCastOptions options)
receiver
.
Returns a new CompletableFuture
that is completed when the cast session has been
started. If the cast session has not been started, the future is completed with
CastSessionStartFailedException
. If the browser is closed during the casting start,
the future will be canceled.
The receiver
should support the CastMode.SCREEN
cast mode.
java.lang.IllegalStateException
- if media routing is disabledvoid 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 successfullyObjectClosedException
- when the browser is already closedjava.lang.String url()
ObjectClosedException
- when the browser is already closedjava.lang.String title()
ObjectClosedException
- when the 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()
.
ObjectClosedException
- when the browser is already closedNetwork.userAgent()
void userAgent(java.lang.String userAgent)
userAgent
- a new user-agent stringObjectClosedException
- when the browser is already closedjava.lang.IllegalArgumentException
- when userAgent
is empty or blankvoid focus()
ObjectClosedException
- when the browser is already closedvoid unfocus()
ObjectClosedException
- when the 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 emptyObjectClosedException
- when the 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
or height
is not positiveObjectClosedException
- when this Browser is already closedSize size()
ObjectClosedException
- when the browser is already closedDisplay display()
ObjectClosedException
- when the browser is already closedvoid dispatch(KeyPressed event)
event
- the key pressed eventObjectClosedException
- when the browser is already closedvoid dispatch(KeyReleased event)
event
- the key released eventObjectClosedException
- when the browser is already closedvoid dispatch(KeyTyped event)
event
- the key typed eventObjectClosedException
- when the browser is already closedvoid dispatch(MousePressed event)
event
- the mouse pressed eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseReleased event)
event
- the mouse released eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseEntered event)
event
- the mouse entered eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseExited event)
event
- the mouse exited eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseDragged event)
event
- the mouse dragged eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseMoved event)
event
- the mouse moved eventObjectClosedException
- when the browser is already closedvoid dispatch(MouseWheel event)
event
- the mouse wheel eventObjectClosedException
- when the 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.