Browser (JxBrowser 7.41.2 API)

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

All Methods Instance Methods Abstract Methods
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`.
`java.util.Optional<PresentationRequest>`	`defaultPresentationRequest()` Returns the default JavaScript `PresentationRequest` specified on the page.
`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.

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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - when the browser is already closed
    
    BitmapTimeoutException - when the bitmap can not be retrieved within 10 seconds
    
    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:
    
    ObjectClosedException - 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.
  - captureSessions
```
java.util.List<CaptureSession> captureSessions()
```
    Returns an immutable list of all active capture sessions initiated by the browser.
    
    Throws:
    
    ObjectClosedException - if the browser is closed
    
    Since:
    
    7.20
  - 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
  - fullScreen
```
FullScreen fullScreen()
```
    Returns the service that controls the fullscreen mode.
    
    Since:
    
    7.28
  - cast
```
java.util.concurrent.CompletableFuture<CastSession> cast(MediaReceiver receiver)
```
    Starts casting the browser content to the media 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 the receiver should support the presentation as a media source. Otherwise, if there is no default PresentationRequest, the receiver should support any browser's content as a media source.
    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.
    Throws:
    
    java.lang.IllegalStateException - if media routing is disabled
    
    ObjectClosedException - if the browser is closed
    
    Since:
    
    7.29
    
    See Also:
    
    MediaSource.browser(), PresentationRequest
  - castScreen
```
java.util.concurrent.CompletableFuture<CastSession> castScreen(MediaReceiver receiver)
```
    Starts casting screen's content by selecting the screen in the picker dialog.
    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.
    
    Throws:
    
    java.lang.IllegalStateException - if media routing is disabled
    
    ObjectClosedException - if the browser is closed
    
    Since:
    
    7.29
    
    See Also:
    
    MediaSource.screen()
  - castScreen
```
java.util.concurrent.CompletableFuture<CastSession> castScreen(MediaReceiver receiver,
                                                               ScreenCastOptions options)
```
    Starts casting the screen's content to the media 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.
    
    Throws:
    
    java.lang.IllegalStateException - if media routing is disabled
    
    ObjectClosedException - if the browser is closed
    
    Since:
    
    7.29
    
    See Also:
    
    MediaSource.screen()
  - defaultPresentationRequest
```
java.util.Optional<PresentationRequest> defaultPresentationRequest()
```
    Returns the default JavaScript PresentationRequest specified on the page.
    Usually, the default PresentationRequest is specified on resources like YouTube. The developer can specify it this way:
```
 const presentationRequest = new PresentationRequest(['receiver/index.html']);
 navigator.presentation.defaultRequest = presentationRequest;
 
```
    Throws:
    
    ObjectClosedException - if the browser is closed
    
    Since:
    
    7.34
  - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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
    
    ObjectClosedException - 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
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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:
    
    ObjectClosedException - 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

Interface Browser

Method Summary

Methods inherited from interface com.teamdev.jxbrowser.Closeable

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

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

Method Detail

engine

profile

mainFrame

focusedFrame

frames

bitmap

favicon

textFinder

zoom

captureSessions

audio

navigation

settings

devTools

fullScreen

cast

castScreen

castScreen

defaultPresentationRequest

replaceMisspelledWord

saveWebPage

url

title

userAgent

userAgent

focus

unfocus

resize

resize

size

display

dispatch

dispatch

dispatch

dispatch

dispatch

dispatch

dispatch

dispatch

dispatch

dispatch

close

close