cheerpjInit must be called once in the page to setup and initialise the CheerpJ runtime environment.
cheerpjInit accepts an optional object argument which can be used to set options.
This method is to be invoked as follows:
All the supported options are described below.
By default CheerpJ supports an internal clipboard which is local to the Java application and is not integrated with the system clipboard. To change this behaviour you can initialize CheerpJ in the following way:
system mode CheerpJ will share the clipboard with the system. Browsers enforce serious limitations on how the system clipboard can be accessed. In practice it is generally accessible when the
Ctrl+V shortcuts are used (
Cmd+V on MacOSX). Due to these limitations the UX when using
Cmd+C: the user has to press the shortcut twice to give CheerpJ access to the system clipboard. CheerpJ will block the execution while waiting for the second
Cmd+V: this shortcut behaves normally, there is no difference with native execution.
- Menu based Copy/Paste:
Ctrl+Vare needed to access the clipboard. CheerpJ will block the execution while waiting the appropriate shortcut.
Commercial users adopting this integration have so far reported that this change in UX is not a significant burden for users. Moreover, in the future we plan to add an additional clipboard mode to take advantage of a new permission-based browser API which is currently being standardized. This future mode will provide native like user experience in all cases.
CheerpJ automatically reports errors at runtime. Setting this option to
true disables this system.
CheerpJ automatically get data about loading time. Setting this option to
true disables this system.
When this option is set to
true CheerpJ will be able to receive text input from the input method framework of the platform. This is useful to support text input for languages such as Chinese, Japanese and Korean.
When this option is set to
true CheerpJ will automatically keep track of the classes actually used at runtime. Moreover, it will also keep track of classes which are accessed by reflection. After the application has been fully tested you can use the
cjGetProguardConfiguration() function from the browser console to download a ProGuard configuration file (
cheerpj.pro) that you can directly use with ProGuard to remove unneeded classes, methods and fields from the application, greatly reducing the download size and startup time.
An array of Java properties in the form
"key=value". They will be defined on the System object (System properties). This option should be used if command line arguments in the form
-Dkey=value are required when using native Java.
An object containing callbacks that CheerpJ will use to report various information to the user. Currently only the
preloadProgress callbacks are supported.
Warning: enabling this listener may have significant performance impact and should not be used in production.
For each new .jar.js to be loaded, CheerpJ will call this function. This can be useful to debug the reason why some parts of the runtime are loaded, if unexpected.
scriptName: The name of the JS file being loaded
directReason: A CheerpJ uncompressed and mangled symbol. The method that most directly caused the load. This might not be very useful since it will most often be a
java.lang.ClassLoadermethod. Can be
(Internal)if it could not be detected.
userReason: A CheerpJ uncompressed and mangled symbol. The last non-runtime method in the stack before the loading. This should be more useful in understanding the user code that introduces the dependency. Can be
(Internal)if it could not be detected.
This listener may be used in combination with
preloadResources to monitor the loading of an application. The information provided is useful, for example, to display a loading/progress bar.
loadedFiles: How many files have been preloaded so far
totalFiles: How many files needs to be preloaded in total. This number may increment during the loading phase. CheerpJ has a prediction mechanism and may preload additional resources depending on application behaviour
When set to
true, it enables logs on the console about the display areas which are being updated. Useful to debug overdrawing.
Some applications needs to internally handle keyboard shortcuts which are also used by the browser, for example Ctrl+F. Most users expect the standard browser behavior for these shortcuts and CheerpJ does not, by default, override them in any way.
A CheerpJ-converted application can take control of additional shortcuts by providing a callback function as the
overrideShortcuts options of
cheerpjInit. This callback receives the
KeyboardEvent coming from the browser and should return
true if the default browser behaviour should be prevented.
Whenever possible we recommend not to use browser reserved shortcuts, to maintain a consistent user experience. In any case, the following limitations apply:
- Some shortcuts (Ctrl+T, Ctrl+N, Ctrl+W) are reserved by the browser and never received by the page itself. These cannot be overridden
- Overriding (Ctrl+C/Ctrl+V) will prevent
clipboardMode:"system"from working correctly.
See also cjGetRuntimeResources.
This option determines the level of verbosity of CheerpJ in reporting status updates.
"default": Enables status reporting during initialization and short-lived “Loading…” messages every time new runtime code is being downloaded.
"splash": Enabled status reporting only during initialization. There will be no feedback after the first window is shown on screen.
"none": Disable all status reporting.
Some applications may need to have some parameter modified before getting those inside the applet.
Boolean option which makes the classloader behavior similar to the native Java plugin. For better performance it is recommended to upgrade to CheerpJ 3.
cheerpjCreateDisplay(w, h, oldElem, useLoadingAnimation)
This method will create the HTML element that will contain all Java windows. It is only required to run graphical applications.
height parameter represent the display area size in CSS pixels. It is also possible to specify a parent element if required, if a parent element is not specified the display area will be appended to the page
body element. If a parent is specified it is also possible to pass
-1 to both
height, in that case the size will correspond to the parent size and it will also change dynamically if the parent is modified by either CSS changes or browser window resize.
Running applications and
Warning: CheerpJ does not support opening the HTML pages directly from disk. If the URL in your browser starts with
file://, CheerpJ will not run. You must use a local Web server.
cheerpjRunMain(className, classPath, ...)
The most common way of starting an application is to use the
cheerpjRunMain API, which lets you execute the static main method of a Java class in the classpath.
Alternatively, if your JAR is designed to be executed with
java -jar my_application_archive.jar, you can use this simpler API.
cheerpjRunJarWithClasspath(jarName, classPath, ...)
Deprecation warningThis API is deprecated and was removed in CheerpJ 3.0.
Optionally, if your JAR also need additional dependencies, you can use.
Calling Java from JS
These functions make it possible to conveniently call Java code from JS. Java code is always run asynchronously, so the returned values are
Promises. See below for details.
Promises. They can be transparently used in other calls to
cjNew/cjCall or you can use
.catch(...) to access the resulting value and handle errors. It is also possible to use
async/await (either natively or through a JS transpiler) to write sync-like code using
cjNew/cjCall as async primitives.
cjCall(objOrClassNameOrInvoker, methodName, ...)
cjResolveCall / cjResolveNew
cjResolveCall(className, methodName, types)
cjCall/cjNew is convenient, but under the hood Java reflection APIs are used, which may have a significant performance impact if used heavily. If you plan to use
cjCall/cjNew many times it is convenient to go through reflection APIs only once by using the
cjResolveCall supports both instance and static methods of classes. The third parameter (for both APIs) is an array of Java types and it is only required if the methodName is not unique in the class (i.e. it is overloaded). The third parameter can be omitted (be null) if the method name (or constructor) is unique. For example:
cjResolveCall/cjResolveNew are async, like most of CheerpJ’s APIs. To get the actual result you can either use .then() or the async/await functionality of JS. For example:
The returned value is an opaque handle to the desired method (or constructor), which can now be called an arbitrary number of times without going through Java reflection.
Alternatively resolvedMethod can also be used directly as a function, for example:
Please note that this convenient form can unfortunately only be used on the main thread, not on Workers. For more information see WebWorker API
cjNew are automatically converted so it is not necessary to use this methods in that case.
Converts a TypedArray to a Java compatible primitive array. This operation implies a copy. Data is converted as follows:
|Typed Array||Java array|
Used to download files from the CheerpJ filesystem. It returns a promise that eventually resolve to a Blob object, which can be downloaded with standard HTML5 techniques.
Used to add files into the
/str/ mount point filesystem.
To be used on the browser console to download a ProGuard configuration file (
cheerpj.pro). See enableProguardTrace.