cheerpjInit
Set up and initialize the CheerpJ runtime environment
cheerpjInit
must be called once in the page to setup and initialise the CheerpJ runtime environment.
Parameters
- options (
object
, optional) - Used to configure different settings of the CheerpJ runtime environment in the form{ option: "value" }
.
Returns
cheerpjInit
returns a Promise which is resolved when the CheerpJ runtime environment is ready to be used.
Options
A description of each cheerpjInit()
option with brief examples are given below.
version
The Java runtime version to use. 8
is the only supported value at the moment.
status
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.
Example:
logCanvasUpdates
When set to true
, it enables logs on the console about the display areas which are being updated. Useful to debug overdrawing.
Example:
preloadResources
By using preloadResources
, you can provide CheerpJ with a list of runtime files which you know in advance will be required for the specific application. The list should be given as a JavaScript array of strings.
Example:
See also cjGetRuntimeResources.
preloadProgress
This callback 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.
Example:
clipboardMode
This option allows you to configure how the clipboard will behave. Supported clipboard modes are java
, system
and permission
.
Example:
java
mode
This is the default setting. CheerpJ supports an internal clipboard which is local to the Java application and is not integrated with the system clipboard.
system
mode
In 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+C
and Ctrl+V
shortcuts are used (Cmd+C
and Cmd+V
on MacOSX). Due to these limitations the UX when using clipboardMode:"system"
is:
Ctrl+C
/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 secondCtrl+C
.Ctrl+V
/Cmd+V
: this shortcut behaves normally, there is no difference with native execution.- Menu based Copy/Paste:
Ctrl+C
/Ctrl+V
are needed to access the clipboard. CheerpJ will block the execution while waiting the appropriate shortcut.
permission
mode
With permission
mode enabled, CheerpJ offers a more seamless integration than system
mode. This includes support for images and HTML on top of plain text. Another important feature is that pressing extra Ctrl+C
/Ctrl+V
to perform copying and pasting operations is not required.
The first time an operation is requested, the user will be asked for permission to use the clipboard. If this permission is refused, a message will be prompted explaining this permission is necessary to continue.
This mode is experimental and might show a few inconsistencies in some browsers.
See more
.
beepCallback
This callback runs when java.awt.Toolkit.getDefaultToolkit().beep()
is called in Java. It corresponds to the system’s beep sound.
Example of usage:
enableInputMethods
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.
overrideShortcuts
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-compiled 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.
Example:
appletParamFilter
Some applications may need to have some parameter modified before getting those inside the applet.
Example:
natives
This option is used to implement native methods from an AOT-compiled language in JavaScript.
Example usage:
Read more about implementing native methods here.
overrideDocumentBase
Replaces the current <base>
URL of the document with the URL passed as a string
.
Example usage:
javaProperties
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.
Example usage:
tailscaleControlUrl
This option expects a string URL of the Tailscale control plane. The control plane verifies the user’s identity and validates various keys among the connected peers in the network. Only pass this option if you are self-hosting Tailscale, if omitted, it will point to the Tailscale control plane.
Example usage:
tailscaleDnsUrl
Expects a string with the IPv4 or IPv6 address to use for DNS queries. If omitted, the default IP address is “8.8.8.8”.
Example usage:
tailscaleAuthKey
This option expects a string that contains a Tailscale auth key. Using auth keys allows one to register new users/devices that are pre-authenticated. You can create an auth key here. This option is mutually exclusive with tailscaleLoginUrlCb
InfoA combination of a user and a device connected to a Tailscale network is called a “node” in Tailscale terminology.
For more information about auth keys visit the Tailscale auth keys documentation.
Example of usage:
tailscaleLoginUrlCb
This option is used to login into a Tailscale network and it is mutually exclusive with tailscaleAuthKey
. It expects the base URL of a control server that will continue and finish the login process. This callback is executed when it is time to prompt the user to login to Tailscale via the UI.
For more information visit the Tailscale documentation.
tailscaleIpCb
This callback is used to retrieve the IP address of the client once the connection with the Tailscale network is established.
Example of usage:
licenseKey
This option expects a license key. The non-commercial license message will be removed from the CheerpJ display if a valid license key is used. Please visit our licensing guide for more information.
Example of usage: