public final class WebEngine extends Object
WebEngine
is a non-visual object capable of managing one Web page
at a time. It loads Web pages, creates their document models, applies
styles as necessary, and runs JavaScript on pages. It provides access
to the document model of the current page, and enables two-way
communication between a Java application and JavaScript code of the page.
The WebEngine
class provides two ways to load content into a
WebEngine
object:
load(java.lang.String)
method. This method uses
the java.net
package for network access and protocol handling.
loadContent(java.lang.String, java.lang.String)
and
loadContent(java.lang.String)
methods.
Loading always happens on a background thread. Methods that initiate
loading return immediately after scheduling a background job. To track
progress and/or cancel a job, use the Worker
instance available from the getLoadWorker()
method.
The following example changes the stage title when loading completes successfully:
import javafx.concurrent.Worker.State;
final Stage stage;
webEngine.getLoadWorker().stateProperty().addListener(
new ChangeListener<State>() {
public void changed(ObservableValue ov, State oldState, State newState) {
if (newState == State.SUCCEEDED) {
stage.setTitle(webEngine.getLocation());
}
}
});
webEngine.load("http://javafx.com");
A number of user interface callbacks may be registered with a
WebEngine
object. These callbacks are invoked when a script running
on the page requests a user interface operation to be performed, for
example, opens a popup window or changes status text. A WebEngine
object cannot handle such requests internally, so it passes the request to
the corresponding callbacks. If no callback is defined for a specific
operation, the request is silently ignored.
The table below shows JavaScript user interface methods and properties
with their corresponding WebEngine
callbacks:
JavaScript method/property | WebEngine callback |
---|---|
window.alert() | onAlert
|
window.confirm() | confirmHandler
|
window.open() | createPopupHandler
|
window.open() andwindow.close() | onVisibilityChanged
|
window.prompt() | promptHandler
|
Setting window.status | onStatusChanged
|
Setting any of the following:window.innerWidth , window.innerHeight ,window.outerWidth , window.outerHeight ,window.screenX , window.screenY ,window.screenLeft , window.screenTop
| onResized
|
The following example shows a callback that resizes a browser window:
Stage stage;
webEngine.setOnResized(
new EventHandler<WebEvent<Rectangle2D>>() {
public void handle(WebEvent<Rectangle2D> ev) {
Rectangle2D r = ev.getData();
stage.setWidth(r.getWidth());
stage.setHeight(r.getHeight());
}
});
The WebEngine
objects create and manage a Document Object Model
(DOM) for their Web pages. The model can be accessed and modified using
Java DOM Core classes. The getDocument()
method provides access
to the root of the model. Additionally DOM Event specification is supported
to define event handlers in Java code.
The following example attaches a Java event listener to an element of a Web page. Clicking on the element causes the application to exit:
EventListener listener = new EventListener() {
public void handleEvent(Event ev) {
Platform.exit();
}
};
Document doc = webEngine.getDocument();
Element el = doc.getElementById("exit-app");
((EventTarget) el).addEventListener("click", listener, false);
It is possible to execute arbitrary JavaScript code in the context of
the current page using the executeScript(java.lang.String)
method. For example:
webEngine.executeScript("history.back()");
The execution result is returned to the caller, as described in the next section.
java.lang.Boolean
;
and a string becomes a java.lang.String
.
A number can be java.lang.Double
or a java.lang.Integer
,
depending.
The undefined value maps to a specific unique String
object whose value is "undefined"
.
If the result is a
JavaScript object, it is wrapped as an instance of the
JSObject
class.
(As a special case, if the JavaScript object is
a JavaRuntimeObject
as discussed in the next section,
then the original Java object is extracted instead.)
The JSObject
class is a proxy that provides access to
methods and properties of its underlying JavaScript object.
The most commonly used JSObject
methods are
getMember
(to read a named property),
setMember
(to set or define a property),
and call
(to call a function-valued property).
A DOM Node
is mapped to an object that both extends
JSObject
and implements the appropriate DOM interfaces.
To get a JSObject
object for a Node
just do a cast:
JSObject jdoc = (JSObject) webEngine.getDocument();
In some cases the context provides a specific Java type that guides
the conversion.
For example if setting a Java String
field from a JavaScript
expression, then the JavaScript value is converted to a string.
JSObject
methods setMember
and
call
pass Java objects to the JavaScript environment.
This is roughly the inverse of the JavaScript-to-Java mapping
described above:
Java String
, Number
, or Boolean
objects
are converted to the obvious JavaScript values. A JSObject
object is converted to the original wrapped JavaScript object.
Otherwise a JavaRuntimeObject
is created. This is
a JavaScript object that acts as a proxy for the Java object,
in that accessing properties of the JavaRuntimeObject
causes the Java field or method with the same name to be accessed.
Note that the Java objects bound using
JSObject.setMember
,
JSObject.setSlot
, and
JSObject.call
are implemented using weak references. This means that the Java object
can be garbage collected, causing subsequent accesses to the JavaScript
objects to have no effect.
The JSObject.setMember
method is useful to enable upcalls from JavaScript
into Java code, as illustrated by the following example. The Java code
establishes a new JavaScript object named app
. This object has one
public member, the method exit
.
public class JavaApplication {
public void exit() {
Platform.exit();
}
}
...
JavaApplication javaApp = new JavaApplication();
JSObject window = (JSObject) webEngine.executeScript("window");
window.setMember("app", javaApp);
You can then refer to the object and the method from your HTML page:
<a href="" onclick="app.exit()">Click here to exit application</a>
When a user clicks the link the application is closed.
Note that in the above example, the application holds a reference
to the JavaApplication
instance. This is required for the callback
from JavaScript to execute the desired method.
In the following example, the application does not hold a reference to the Java object:
JSObject window = (JSObject) webEngine.executeScript("window");
window.setMember("app", new JavaApplication());
In this case, since the property value is a local object, "new JavaApplication()"
,
the value may be garbage collected in next GC cycle.
When a user clicks the link, it does not guarantee to execute the callback method exit
.
If there are multiple Java methods with the given name, then the engine selects one matching the number of parameters in the call. (Varargs are not handled.) An unspecified one is chosen if there are multiple ones with the correct number of parameters.
You can pick a specific overloaded method by listing the
parameter types in an extended method name
, which has the
form "method_name(param_type1,...,param_typen)"
. Typically you'd write the JavaScript expression:
receiver["method_name(param_type1,...,param_typeN)"](arg1,...,argN)
WebEngine
objects must be created and accessed solely from the
JavaFX Application thread. This rule also applies to any DOM and JavaScript
objects obtained from the WebEngine
object.
Constructor and Description |
---|
WebEngine()
Creates a new engine.
|
WebEngine(String url)
Creates a new engine and loads a Web page into it.
|
Modifier and Type | Method and Description |
---|---|
ObjectProperty<Callback<String,Boolean>> |
confirmHandlerProperty()
JavaScript
confirm handler property. |
ObjectProperty<Callback<PopupFeatures,WebEngine>> |
createPopupHandlerProperty()
JavaScript popup handler property.
|
ReadOnlyObjectProperty<Document> |
documentProperty()
Document object for the current Web page.
|
Object |
executeScript(String script)
Executes a script in the context of the current page.
|
Callback<String,Boolean> |
getConfirmHandler()
Returns the JavaScript
confirm handler. |
Callback<PopupFeatures,WebEngine> |
getCreatePopupHandler()
Returns the JavaScript popup handler.
|
Document |
getDocument()
Returns the document object for the current Web page.
|
WebHistory |
getHistory()
Returns the session history object.
|
Worker<Void> |
getLoadWorker()
Returns a
Worker object that can be used to
track loading progress. |
String |
getLocation()
Returns URL of the current Web page.
|
EventHandler<WebEvent<String>> |
getOnAlert()
Returns the JavaScript
alert handler. |
EventHandler<WebErrorEvent> |
getOnError() |
EventHandler<WebEvent<Rectangle2D>> |
getOnResized()
Returns the JavaScript window resize handler.
|
EventHandler<WebEvent<String>> |
getOnStatusChanged()
Returns the JavaScript status handler.
|
EventHandler<WebEvent<Boolean>> |
getOnVisibilityChanged()
Returns the JavaScript window visibility handler.
|
Callback<PromptData,String> |
getPromptHandler()
Returns the JavaScript
prompt handler. |
String |
getTitle()
Returns title of the current Web page.
|
String |
getUserAgent() |
File |
getUserDataDirectory() |
String |
getUserStyleSheetLocation() |
Debugger |
impl_getDebugger()
Deprecated.
This is an internal API that can be changed or
removed in the future.
|
boolean |
isJavaScriptEnabled() |
BooleanProperty |
javaScriptEnabledProperty() |
void |
load(String url)
Loads a Web page into this engine.
|
void |
loadContent(String content)
Loads the given HTML content directly.
|
void |
loadContent(String content,
String contentType)
Loads the given content directly.
|
ReadOnlyStringProperty |
locationProperty()
URL of the current Web page.
|
ObjectProperty<EventHandler<WebEvent<String>>> |
onAlertProperty()
JavaScript
alert handler property. |
ObjectProperty<EventHandler<WebErrorEvent>> |
onErrorProperty() |
ObjectProperty<EventHandler<WebEvent<Rectangle2D>>> |
onResizedProperty()
JavaScript window resize handler property.
|
ObjectProperty<EventHandler<WebEvent<String>>> |
onStatusChangedProperty()
JavaScript status handler property.
|
ObjectProperty<EventHandler<WebEvent<Boolean>>> |
onVisibilityChangedProperty()
JavaScript window visibility handler property.
|
void |
print(PrinterJob job)
Prints the current Web page using the given printer job.
|
ObjectProperty<Callback<PromptData,String>> |
promptHandlerProperty()
JavaScript
prompt handler property. |
void |
reload()
Reloads the current page, whether loaded from URL or directly from a String in
one of the
loadContent methods. |
void |
setConfirmHandler(Callback<String,Boolean> handler)
Sets the JavaScript
confirm handler. |
void |
setCreatePopupHandler(Callback<PopupFeatures,WebEngine> handler)
Sets the JavaScript popup handler.
|
void |
setJavaScriptEnabled(boolean value) |
void |
setOnAlert(EventHandler<WebEvent<String>> handler)
Sets the JavaScript
alert handler. |
void |
setOnError(EventHandler<WebErrorEvent> handler) |
void |
setOnResized(EventHandler<WebEvent<Rectangle2D>> handler)
Sets the JavaScript window resize handler.
|
void |
setOnStatusChanged(EventHandler<WebEvent<String>> handler)
Sets the JavaScript status handler.
|
void |
setOnVisibilityChanged(EventHandler<WebEvent<Boolean>> handler)
Sets the JavaScript window visibility handler.
|
void |
setPromptHandler(Callback<PromptData,String> handler)
Sets the JavaScript
prompt handler. |
void |
setUserAgent(String value) |
void |
setUserDataDirectory(File value) |
void |
setUserStyleSheetLocation(String value) |
ReadOnlyStringProperty |
titleProperty()
Title of the current Web page.
|
StringProperty |
userAgentProperty() |
ObjectProperty<File> |
userDataDirectoryProperty() |
StringProperty |
userStyleSheetLocationProperty() |
public WebEngine()
public WebEngine(String url)
public final Worker<Void> getLoadWorker()
Worker
object that can be used to
track loading progress.public final Document getDocument()
null
.public final ReadOnlyObjectProperty<Document> documentProperty()
null
if the Web page failed to load.public final String getLocation()
public final ReadOnlyStringProperty locationProperty()
public final String getTitle()
null
.public final ReadOnlyStringProperty titleProperty()
null
.public final void setJavaScriptEnabled(boolean value)
public final boolean isJavaScriptEnabled()
public final BooleanProperty javaScriptEnabledProperty()
public final void setUserStyleSheetLocation(String value)
public final String getUserStyleSheetLocation()
public final StringProperty userStyleSheetLocationProperty()
public final File getUserDataDirectory()
public final void setUserDataDirectory(File value)
public final ObjectProperty<File> userDataDirectoryProperty()
public final void setUserAgent(String value)
public final String getUserAgent()
public final StringProperty userAgentProperty()
public final EventHandler<WebEvent<String>> getOnAlert()
alert
handler.public final void setOnAlert(EventHandler<WebEvent<String>> handler)
alert
handler.onAlertProperty()
,
getOnAlert()
public final ObjectProperty<EventHandler<WebEvent<String>>> onAlertProperty()
alert
handler property. This handler is invoked
when a script running on the Web page calls the alert
function.public final EventHandler<WebEvent<String>> getOnStatusChanged()
public final void setOnStatusChanged(EventHandler<WebEvent<String>> handler)
onStatusChangedProperty()
,
getOnStatusChanged()
public final ObjectProperty<EventHandler<WebEvent<String>>> onStatusChangedProperty()
window.status
property.public final EventHandler<WebEvent<Rectangle2D>> getOnResized()
public final void setOnResized(EventHandler<WebEvent<Rectangle2D>> handler)
onResizedProperty()
,
getOnResized()
public final ObjectProperty<EventHandler<WebEvent<Rectangle2D>>> onResizedProperty()
window
object.public final EventHandler<WebEvent<Boolean>> getOnVisibilityChanged()
public final void setOnVisibilityChanged(EventHandler<WebEvent<Boolean>> handler)
public final ObjectProperty<EventHandler<WebEvent<Boolean>>> onVisibilityChangedProperty()
window
object.public final Callback<PopupFeatures,WebEngine> getCreatePopupHandler()
public final void setCreatePopupHandler(Callback<PopupFeatures,WebEngine> handler)
public final ObjectProperty<Callback<PopupFeatures,WebEngine>> createPopupHandlerProperty()
To satisfy this request a handler may create a new WebEngine
,
attach a visibility handler and optionally a resize handler, and return
the newly created engine. To block the popup, a handler should return
null
.
By default, a popup handler is installed that opens popups in this
WebEngine
.
PopupFeatures
public final Callback<String,Boolean> getConfirmHandler()
confirm
handler.public final void setConfirmHandler(Callback<String,Boolean> handler)
confirm
handler.confirmHandlerProperty()
,
getConfirmHandler()
public final ObjectProperty<Callback<String,Boolean>> confirmHandlerProperty()
confirm
handler property. This handler is invoked
when a script running on the Web page calls the confirm
function.
An implementation may display a dialog box with Yes and No options, and return the user's choice.
public final Callback<PromptData,String> getPromptHandler()
prompt
handler.public final void setPromptHandler(Callback<PromptData,String> handler)
prompt
handler.promptHandlerProperty()
,
getPromptHandler()
,
PromptData
public final ObjectProperty<Callback<PromptData,String>> promptHandlerProperty()
prompt
handler property. This handler is invoked
when a script running on the Web page calls the prompt
function.
An implementation may display a dialog box with an text field, and return the user's input.
PromptData
public final EventHandler<WebErrorEvent> getOnError()
public final void setOnError(EventHandler<WebErrorEvent> handler)
public final ObjectProperty<EventHandler<WebErrorEvent>> onErrorProperty()
public void load(String url)
url
- URL of the web page to loadpublic void loadContent(String content)
load(String)
, this method is asynchronous.public void loadContent(String content, String contentType)
load(String)
, this method is asynchronous. This method also allows you to
specify the content type of the string being loaded, and so may optionally support
other types besides just HTML.public void reload()
loadContent
methods.public WebHistory getHistory()
public Object executeScript(String script)
java.lang.Integer
java.lang.Double
java.lang.String
java.lang.Boolean
null
to null
netscape.javascript.JSObject
netscape.javascript.JSObject
, that also implement
org.w3c.dom.Node
JavaRuntimeObject
which is used to wrap a Java object as a JavaScript value - in this
case we just extract the original Java value.
@Deprecated public Debugger impl_getDebugger()
All methods of the debugger must be called on the JavaFX Application Thread. The message callback object registered with the debugger is always called on the JavaFX Application Thread.
null
.public void print(PrinterJob job)
This method does not modify the state of the job, nor does it call
PrinterJob.endJob()
, so the job may be safely reused afterwards.
job
- printer job used for printingCopyright © 2020. All rights reserved.