Package com.teamdev.jxbrowser.frame

Interface Frame

public interface Frame
A frame in the browser.

Each web page loaded in the browser has a main (top-level) frame. The frame itself may have child frames. When a web page is unloaded, its frame and all child frames are closed automatically. Any attempt to work with an already closed frame will lead to the IllegalStateException error.

  • Method Summary

    Modifier and Type
    Method
    Description
    Browser
    browser()
    Returns the Browser instance of this frame.
    List<Frame>
    children()
    Returns the list of child frames or an empty list if this frame does not have any children.
    Optional<Document>
    document()
    Returns an Optional that contains the DOM Document instance of the frame or an empty Optional if the frame does not have a document.
    boolean
    execute(EditorCommand command)
    Executes the given command in the frame.
    <T> T
    executeJavaScript(String javaScript)
    Executes the given javaScript code in the frame and returns the result of the execution.
    void
    executeJavaScript(String javaScript, Consumer<?> callback)
    Executes the given javaScript code in the frame and returns the result of the execution through the given callback.
    boolean
    hasSelection()
    Returns true if some content in this frame is selected.
    String
    html()
    Returns a string that represents content of the frame in the HTML format or an empty string if the frame does not have a content or its content is empty.
    PointInspection
    inspect(int x, int y)
    Inspects the given location on the web page containing this frame and returns the result of the inspection.
    PointInspection
    inspect(Point location)
    Inspects the given location on the web page containing this frame and returns the result of the inspection.
    boolean
    isCommandEnabled(EditorCommand.Name commandName)
    Returns true if the command with the given commandName can be executed in the frame.
    boolean
    isMain()
    Returns true if the frame is a main (top-level) frame in the browser.
    Json
    json()
    Returns the Json instance for this frame.
    void
    loadUrl(String url)
    Navigates the frame to a resource identified by the given url.
    WebStorage
    localStorage()
    Returns the localStorage instance of this frame.
    String
    name()
    Returns a string that represent the name of the frame or an empty string if the frame does not have a name.
    Optional<Frame>
    parent()
    Returns an Optional that contains the parent Frame instance or an empty Optional if the current frame is a main (top-level) frame and it does not have a parent.
    void
    print()
    Requests printing of the currently loaded web page in this frame.
    RenderProcess
    renderProcess()
    Returns a RenderProcess associated with the current Frame instance.
    String
    selectionAsHtml()
    Returns a string that contains HTML of the selected content in the frame or an empty string if there is no selection.
    String
    selectionAsText()
    Returns a text representation of the selected content in the frame or an empty string if there is no selection.
    WebStorage
    sessionStorage()
    Returns the sessionStorage instance of this frame.
    String
    text()
    Returns the content of the frame and its sub-frames as plain text or an empty string if the frame does not have content or its content is empty.
    void
    viewSource()
    Creates a new popup where the view-source:<frame-url> URL is loaded to display HTML source of the frame.

  • Method Details

    • browser

      Browser browser()
      Returns the Browser instance of this frame.

    • isMain

      boolean isMain()
      Returns true if the frame is a main (top-level) frame in the browser.

    • parent

      Optional<Frame> parent()
      Returns an Optional that contains the parent Frame instance or an empty Optional if the current frame is a main (top-level) frame and it does not have a parent.
      Throws:
      ObjectClosedException - when the frame is closed

    • children

      List<Frame> children()
      Returns the list of child frames or an empty list if this frame does not have any children.
      Throws:
      ObjectClosedException - when this frame is closed

    • selectionAsText

      String selectionAsText()
      Returns a text representation of the selected content in the frame or an empty string if there is no selection.
      Throws:
      ObjectClosedException - when the frame is closed

    • selectionAsHtml

      String selectionAsHtml()
      Returns a string that contains HTML of the selected content in the frame or an empty string if there is no selection.
      Throws:
      ObjectClosedException - when the frame is closed

    • hasSelection

      boolean hasSelection()
      Returns true if some content in this frame is selected.
      Throws:
      ObjectClosedException - when the frame is closed

    • document

      Optional<Document> document()
      Returns an Optional that contains the DOM Document instance of the frame or an empty Optional if the frame does not have a document.

      Note: Chromium injects a document into the frame asynchronously, so there is a chance that this method might return an empty Optional even if the frame is already available.

      Throws:
      ObjectClosedException - when the frame is closed

    • name

      String name()
      Returns a string that represent the name of the frame or an empty string if the frame does not have a name.
      Throws:
      ObjectClosedException - when the frame is closed

    • html

      String html()
      Returns a string that represents content of the frame in the HTML format or an empty string if the frame does not have a content or its content is empty.
      Throws:
      ObjectClosedException - when the frame is closed

    • text

      String text()
      Returns the content of the frame and its sub-frames as plain text or an empty string if the frame does not have content or its content is empty.

      Limitations:

      • If the frame has sub-frames from another domain, their text will not be included into the return value.
      • No specification is given for how text from one frame will be delimited from the next.
      • The return value may contain text that is not visible to the user, whether due to scrolling, display:none, unexpanded divs, etc.
      • The ordering of the text does not reflect the ordering of the text on the page as seen by the user. Each element's text may appear in a totally different position in the result from its position on the page.

      Please note that this functionality is resource-intensive, consuming significant memory and CPU during a text capture.

      Throws:
      ObjectClosedException - when the frame is closed

    • viewSource

      void viewSource()
      Creates a new popup where the view-source:<frame-url> URL is loaded to display HTML source of the frame.
      Throws:
      ObjectClosedException - when the frame is closed

    • loadUrl

      void loadUrl(String url)
      Navigates the frame to a resource identified by the given url.

      This method tells the frame to start asynchronous loading and returns immediately.

      Parameters:
      url - URL of the resource to load
      Throws:
      IllegalArgumentException - when url is empty or blank
      ObjectClosedException - when the frame is closed

    • executeJavaScript

      @Nullable <T> T executeJavaScript(String javaScript)
      Executes the given javaScript code in the frame and returns the result of the execution.

      The type mapping rules are the following: 

       | JavaScript         | Java           |
 |--------------------|----------------|
 | Number             | Double         |
 | BigInt             | BigInteger     |
 | String             | String         |
 | Boolean            | Boolean        |
 | Symbol             | JsSymbol       |
 | null and undefined | null           |
 | Node               | JsObject, Node |
 | ArrayBuffer        | JsArrayBuffer  |
 | Array              | JsArray        |
 | Set                | JsSet          |
 | Map                | JsMap          |
 | Object             | JsObject       |
 | Proxy Object       | Object         |

      Proxy objects are mapped to the corresponding injected Java object.

      Important: This method blocks the current thread execution and waits until the passed JavaScript code has been executed completely. The time required to complete the execution can be different depending on the passed JavaScript code. So, it is strongly recommended that the method is not invoked in the application UI thread.

      Type Parameters:
      T - the result type according to the type mapping rules
      Parameters:
      javaScript - a string that represents JavaScript code to execute
      Returns:
      the result of the execution. Can be null if the result of the execution on JavaScript is null or undefined
      Throws:
      ObjectClosedException - when the frame is closed
      IllegalArgumentException - when javaScript is empty

    • executeJavaScript

      void executeJavaScript(String javaScript, Consumer<?> callback)
      Executes the given javaScript code in the frame and returns the result of the execution through the given callback.

      The type mapping rules are the following: 

       | JavaScript         | Java           |
 |--------------------|----------------|
 | Number             | Double         |
 | BigInt             | BigInteger     |
 | String             | String         |
 | Boolean            | Boolean        |
 | Symbol             | JsSymbol       |
 | null and undefined | null           |
 | Node               | JsObject, Node |
 | ArrayBuffer        | JsArrayBuffer  |
 | Array              | JsArray        |
 | Set                | JsSet          |
 | Map                | JsMap          |
 | Object             | JsObject       |
 | Proxy Object       | Object         |

      Proxy objects are mapped to the corresponding injected Java object.

      This method does not block the current thread execution and executes the given JavaScript code asynchronously.

      Parameters:
      javaScript - a string that represents JavaScript code to execute
      callback - a callback you can use to get the result of the execution. The result type is determined according to the type mapping rules
      Throws:
      ObjectClosedException - when the frame is closed
      IllegalArgumentException - when javaScript is empty

    • execute

      boolean execute(EditorCommand command)
      Executes the given command in the frame.

      Before executing the command it is recommended to check whether it can be executed or not using the isCommandEnabled(EditorCommand.Name) method.

      Parameters:
      command - the command to execute
      Returns:
      true if the command has been executed successfully
      Throws:
      ObjectClosedException - when the frame is closed
      See Also:

    • isCommandEnabled

      boolean isCommandEnabled(EditorCommand.Name commandName)
      Returns true if the command with the given commandName can be executed in the frame.

      Some commands can be executed only under certain conditions. For example, the EditorCommand.Name.INSERT_TEXT command can be executed only if there is a focused text field in the frame.

      Parameters:
      commandName - the name of the command to check
      Throws:
      ObjectClosedException - when the frame is closed

    • inspect

      PointInspection inspect(Point location)
      Inspects the given location on the web page containing this frame and returns the result of the inspection.
      Parameters:
      location - a point on the web page
      Returns:
      the result of the inspection that contains the details about the DOM node at the given location
      Throws:
      ObjectClosedException - when the frame is closed

    • inspect

      PointInspection inspect(int x, int y)
      Inspects the given location on the web page containing this frame and returns the result of the inspection.
      Parameters:
      x - a horizontal coordinate on the web page
      y - a vertical coordinate on the web page
      Returns:
      the result of the inspection that contains the details about the DOM node at the given location
      Throws:
      ObjectClosedException - when the frame is closed

    • localStorage

      WebStorage localStorage()
      Returns the localStorage instance of this frame.
      Throws:
      ObjectClosedException - when the frame is closed
      Since:
      7.1

    • sessionStorage

      WebStorage sessionStorage()
      Returns the sessionStorage instance of this frame.
      Throws:
      ObjectClosedException - when the frame is closed
      Since:
      7.1

    • print

      void print()
      Requests printing of the currently loaded web page in this frame.
      Throws:
      ObjectClosedException - when the frame is closed

    • json

      Json json()
      Returns the Json instance for this frame.
      Throws:
      ObjectClosedException - when the frame is closed

    • renderProcess

      RenderProcess renderProcess()
      Returns a RenderProcess associated with the current Frame instance. When Chromium loads a new web page, it creates a new render process where DOM and JavaScript are running. This render process can be terminated by Chromium engine when a new web page with different domain is loaded. So, this method can return different render process information.
      Since:
      7.5