ModulesAPI

Modules / API

The noVNC client is a composed of several modular components that handle rendering, input, networking, etc. Each of the modules is designed to be cross-browser and be useful as a standalone library in other projects (see LICENSE.txt).

Module List

Mouse (include/input.js): Mouse input event handler with mouse wheel support.
Keyboard (include/input.js): Keyboard input event handler with non-US keyboard support. Translates keyDown and keyUp events to X11 keysym values.
Display (include/display.js): Efficient 2D rendering abstraction layered on the HTML5 canvas element.
Websock (include/network.js): Websock client from websockify with transparent binary data support. Automatic fallback to the web-socket-js Flash Websocket shim/polyfill. Websock API wiki page.
RFB (include/rfb.js): Main class that implements the RFB protocol and stitches the other classes together.

Configuration Attributes

The Mouse, Keyboard, Display and RFB classes have a similar API for configuration options. Each configuration option has a default value, which can be overridden by a a configuration object passed to the constructor. Configuration options can then be read and modified after initialization with "get_" and "set_" methods respectively. For example, the following initializes an RFB object with the 'encrypt' configuration option enabled, then confirms it was set, then disables it.

var rfb = new RFB({'encrypt': true});
if (rfb.get_encrypt()) {
    alert("Encryption is set");
}
rfb.set_encrypt(false);

Some attributes are read-only and cannot be changed. For example, the Display 'render_mode' option will throw an exception if an attempt is made to set it. The attribute mode is one of the following:

RO - read only
RW - read write
WO - write once

Methods

In addition to the getter and setter methods to modify configuration attributes, each of the modules has other methods that are available in the object instance. For example, the Display module has method named 'blitImage' which takes an array of pixel data and draws it to the 2D canvas.

Callbacks

Each of the modules has certain events that can be hooked with callback functions. For the Mouse, Keyboard and RFB classes the callback functions are assigned to configuration attributes. The WebSock module has a method named 'on' that takes two parameters: the callback event name, and the callback function. The Display module is a synchronous rendering library and has no callback events.

Mouse Module

<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Methods</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>grab</td> <td colspan=3>()</td>
    <td>Begin capturing mouse events</td>
</tr>
<tr>
    <td>ungrab</td> <td colspan=3>()</td>
    <td>Stop capturing mouse events</td>
</tr>


<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Callbacks</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>onMouseButton</td> <td colspan=3>(x, y, down, bmask)</td>
    <td>Handler for mouse button click/release</td>
</tr>
<tr>
    <td>onMouseMove</td> <td colspan=3>(x, y)</td>
    <td>Handler for mouse movement</td>
</tr>

name	type	mode	default	description
Configuration Attributes
target	DOM	WO	document	DOM element that captures mouse input
focused	bool	RW	true	Capture and send mouse clicks/movement
scale	float	RW	1.0	Viewport scale factor 0.0 - 1.0

Keyboard Module

<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Methods</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>grab</td> <td colspan=3>()</td>
    <td>Begin capturing keyboard events</td>
</tr>
<tr>
    <td>ungrab</td> <td colspan=3>()</td>
    <td>Stop capturing keyboard events</td>
</tr>


<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Callbacks</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>onKeyPress</td> <td colspan=3>(keysym, down, event)</td>
    <td>Handler for key press/release</td>
</tr>

name	type	mode	default	description
Configuration Attributes
target	DOM	WO	document	DOM element that captures keyboard input
focused	bool	RW	document	Capture and send mouse key events

Display Module

<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Methods</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>resize</td> <td colspan=3>(width, height)</td>
    <td>Set width and height</td>
</tr>
<tr>
    <td>clear</td> <td colspan=3>()</td>
    <td>Clear the display (show logo if set)</td>
</tr>
<tr>
    <td>fillRect</td> <td colspan=3>(x, y, width, height, color)</td>
    <td>Draw a filled in rectangle</td>
</tr>
<tr>
    <td>copyImage</td> <td colspan=3>(x1, y1, x2, y2, width, height)</td>
    <td>Copy a rectangular area</td>
</tr>
<tr>
    <td>getTile</td> <td colspan=3>(x, y, width, height, color)</td>
    <td>Get tile from display and prefill it with the color</td>
</tr>
<tr>
    <td>setSubTile</td> <td colspan=3>(tile, x, y, w, h, color)</td>
    <td>Fill a rectangle within the given tile</td>
</tr>
<tr>
    <td>putTile</td> <td colspan=3>(tile)</td>
    <td>Draw the tile back to the display</td>
</tr>
<tr>
    <td>blitImage</td> <td colspan=3>(x, y, width, height, pixels, offset)</td>
    <td>Blit pixels (of R,G,B,A or colourMap indexes) to the display</td>
</tr>
<tr>
    <td>blitStringImage</td> <td colspan=3>(str, x, y)</td>
    <td>Blit URL encoded image in str to display</td>
</tr>
<tr>
    <td>changeCursor</td> <td colspan=3>(pixels, mask, hotx, hoty, w, h)</td>
    <td>Change cursor appearance</td>
</tr>
<tr>
    <td>defaultCursor</td> <td colspan=3>()</td>
    <td>Restore default cursor appearance</td>
</tr>

name	type	mode	default	description
Configuration Attributes
target	DOM	WO		Canvas element for rendering
context	raw	RO		Canvas 2D context for rendering
logo	raw	RW		Logo to display when cleared: {"width": width, "height": height, "data": data}
true_color	bool	RW	true	Use true-color pixel data
colourMap	array	RW	[]	Colour map array (when not true color)
scale	float	RW	1.0	Display area scale factor 0.0 - 1.0
width	int	RO		Display area width
height	int	RO		Display area height
render_mode	str	RO		Canvas rendering mode

RFB Module

<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Methods</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>connect</td> <td colspan=3>(host, port, password)</td>
    <td>Connect to the given host:port. Optional password.</td>
</tr>
<tr>
    <td>disconnect</td> <td colspan=3>()</td>
    <td>Disconnect</td>
</tr>
<tr>
    <td>sendPassword</td> <td colspan=3>(passwd)</td>
    <td>Send password after onPasswordRequired event</td>
</tr>
<tr>
    <td>sendCtrlAltDel</td> <td colspan=3>(passwd)</td>
    <td>Send Ctrl-Alt-Del key sequence</td>
</tr>
<tr>
    <td>sendKey</td> <td colspan=3>(code, down)</td>
    <td>Send a key code event. If down not specified, send a down and up event.</td>
</tr>
<tr>
    <td>clipboardPasteFrom</td> <td colspan=3>(text)</td>
    <td>Send a clipboard paste event</td>
</tr>


<tr><td colspan=5>&nbsp;</td></tr>
<tr>
    <td colspan=5><em>Callbacks</em></td>
</tr>
<tr>
    <th>name</th><th colspan=3>parameters</th><th>description</th>
</tr>
<tr>
    <td>onUpdateState</td> <td colspan=3>(rfb, state, oldstate, statusMsg)</td>
    <td>RFB state update/change (see details below)</td>
</tr>
<tr>
    <td>onPasswordRequired</td> <td colspan=3>(rfb)</td>
    <td>VNC password is required (use sendPassword)</td>
</tr>
<tr>
    <td>onClipboard</td> <td colspan=3>(rfb, text)</td>
    <td>RFB clipboard contents received</td>
</tr>
<tr>
    <td>onBell</td> <td colspan=3>(rfb)</td>
    <td>RFB Bell message received</td>
</tr>
<tr>
    <td>onFBUReceive</td> <td colspan=3>(rfb, fbu)</td>
    <td>RFB FBU received but not yet processed (see details below)</td>
</tr>
<tr>
    <td>onFBUComplete</td> <td colspan=3>(rfb, fbu)</td>
    <td>RFB FBU received and processed (see details below)</td>
</tr>

name	type	mode	default	description
Configuration Attributes
target	DOM	WO	null	Canvas element for rendering (passed to Display and Mouse)
focusContainer	DOM	WO	true	DOM element that captures keyboard input (passed to Keyboard)
encrypt	bool	RW	false	Use TLS/SSL encryption
true_color	bool	RW	true	Request true-color pixel data from server
local_cursor	bool	RW	false	Request locally rendered cursor
shared	bool	RW	true	Request shared VNC mode
connectTimeout	int	RW	2/5	Time (in seconds) to wait for connection (longer default for Flash Websock)
disconnectTimeout	int	RW	3	Time (in seconds) to wait for disconnection

RFB onUpdateState callback details

The RFB module has an 'onUpdateState' callback that is invoked after the noVNC page and/or protocol state changes. Here is a list of the states that are reported.

<tr><td colspan=2>&nbsp;</td></tr>
<tr>
    <td colspan=2><em>RFB Protocol Initialization States</em></td>
</tr>
<tr>
    <th>state</th> <th>description</th>
</tr>
<tr>
    <td>ProtocolVersion</td> <td>first server response</td>
</tr>
<tr>
    <td>Security</td> <td></td>
</tr>
<tr>
    <td>Authentication</td> <td></td>
</tr>
<tr>
    <td>password</td> <td>same as onPasswordRequired (not part of RFB)</td>
</tr>
<tr>
    <td>SecurityResult</td> <td></td>
</tr>
<tr>
    <td>ServerInitialization</td> <td>accepted by server (to normal)</td>
</tr>

state	description
Running States
loaded	page load, similar to disconnected
disconnected	idle unconnected state
connect	starting to connect (to ProtocolVersion)
normal	connected
disconnect	starting to disconnect
failed	abnormal disconnect
fatal	failed to load page, or fatal error

RFB onFBUReceive and on FBUComplete callback details

The onFBUReceive callback is invoked when a frame buffer update message has been received from the server but before the RFB class has done any additional handling. The onFBUComplete callback is invoked with the same information but after the RFB class has handled the message.

The 'fbu' parameter is an object with the following structure:

{
    x:            FBU_x_position,
    y:            FBU_y_position, 
    width:        FBU_width,
    height:       FBU_height,
    encoding:     FBU_encoding_number,
    encodingName: FBU_encoding_string
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ModulesAPI

Modules / API

Module List

Configuration Attributes

Methods

Callbacks

Mouse Module

Keyboard Module

Display Module

RFB Module

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally