movement) should be prevented from being sent to the server.
Disabled by default.
+`focusOnClick`
+ - Is a `boolean` indicating if keyboard focus should automatically be
+ moved to the remote session when a `mousedown` or `touchstart`
+ event is received. Enabled by default.
+
`touchButton`
- Is a `long` controlling the button mask that should be simulated
when a touch event is recieved. Uses the same values as
[`MouseEvent.button`](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button).
Is set to `1` by default.
-`viewportScale`
- - Is a `double` indicating how the framebuffer contents should be
- scaled before being rendered on to the canvas. See also
- [`RFB.autoscale()`](#rfbautoscale). Is set to `1.0` by default.
-
`clipViewport`
- - Is a `boolean` indicating if the canvas should be clipped to its
- container. When disabled the container must be able to handle the
- resulting overflow. Disabled by default.
+ - Is a `boolean` indicating if the remote session should be clipped
+ to its container. When disabled scrollbars will be shown to handle
+ the resulting overflow. Disabled by default.
`dragViewport`
- Is a `boolean` indicating if mouse events should control the
- relative position of a clipped canvas. Only relevant if
+ relative position of a clipped remote session. Only relevant if
`clipViewport` is enabled. Disabled by default.
-`isClipped` *Read only*
- - Is a `boolean` indicating if the framebuffer is larger than the
- current canvas, i.e. it is being clipped.
-
-`disconnectTimeout`
- - Is a `long` indicating how many seconds to wait for a disconnect
- request to complete. Is set to `3` by default.
+`scaleViewport`
+ - Is a `boolean` indicating if the remote session should be scaled
+ locally so it fits its container. When disabled it will be centered
+ if the remote session is smaller than its container, or handled
+ according to `clipViewport` if it is larger. Disabled by default.
+
+`resizeSession`
+ - Is a `boolean` indicating if a request to resize the remote session
+ should be sent whenever the container changes dimensions. Disabled
+ by default.
+
+`showDotCursor`
+ - Is a `boolean` indicating whether a dot cursor should be shown
+ instead of a zero-sized or fully-transparent cursor if the server
+ sets such invisible cursor. Disabled by default.
+
+`background`
+ - Is a valid CSS [background](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
+ style value indicating which background style should be applied
+ to the element containing the remote session screen. The default value is `rgb(40, 40, 40)`
+ (solid gray color).
+
+`qualityLevel`
+ - Is an `int` in range `[0-9]` controlling the desired JPEG quality.
+ Value `0` implies low quality and `9` implies high quality.
+ Default value is `6`.
+
+`compressionLevel`
+ - Is an `int` in range `[0-9]` controlling the desired compression
+ level. Value `0` means no compression. Level 1 uses a minimum of CPU
+ resources and achieves weak compression ratios, while level 9 offers
+ best compression but is slow in terms of CPU consumption on the server
+ side. Use high levels with very slow network connections.
+ Default value is `2`.
`capabilities` *Read only*
- Is an `Object` indicating which optional extensions are available
| name | type | description
| -------- | --------- | -----------
| `power` | `boolean` | Machine power control is available
- | `resize` | `boolean` | The framebuffer can be resized
-### Event handlers
+### Events
-[`RFB.onupdatestate()`](#rfbonupdatestate)
- - An event handler called when the connection state of the `RFB`
- object changes.
+[`connect`](#connect)
+ - The `connect` event is fired when the `RFB` object has completed
+ the connection and handshaking with the server.
-[`RFB.onnotification()`](#rfbonnotification)
- - An event handler called when the `RFB` usage has a message to
- display to the user.
+[`disconnect`](#disconnected)
+ - The `disconnect` event is fired when the `RFB` object disconnects.
-[`RFB.ondisconnected()`](#rfbondisconnected)
- - An event handler called when the `RFB` object disconnects.
+[`credentialsrequired`](#credentialsrequired)
+ - The `credentialsrequired` event is fired when more credentials must
+ be given to continue.
-[`RFB.oncredentialsrequired()`](#rfboncredentialsrequired)
- - An event hander called when more credentials must be given to
- continue.
+[`securityfailure`](#securityfailure)
+ - The `securityfailure` event is fired when the security negotiation
+ with the server fails.
-[`RFB.onclipboard()`](#rfbonclipboard)
- - An event handler called when clipboard data is received from the
- server.
+[`clipboard`](#clipboard)
+ - The `clipboard` event is fired when clipboard data is received from
+ the server.
-[`RFB.onbell()`](#rfbonbell)
- - An event handler called when a audible bell request is received
+[`bell`](#bell)
+ - The `bell` event is fired when a audible bell request is received
from the server.
-[`RFB.onfbresize()`](#rfbonfbresize)
- - An event handler called when the framebuffer size is changed.
-
-[`RFB.ondesktopname()`](#rfbondesktopname)
- - An event handler called when the remote desktop name changes.
+[`desktopname`](#desktopname)
+ - The `desktopname` event is fired when the remote desktop name
+ changes.
-[`RFB.oncapabilities()`](#rfboncapabilities)
- - An event handler called when `RFB.capabilities` is updated.
+[`capabilities`](#capabilities)
+ - The `capabilities` event is fired when `RFB.capabilities` is
+ updated.
### Methods
-[`RFB.connect()`](#rfbconnect)
- - Connect to a server.
-
[`RFB.disconnect()`](#rfbdisconnect)
- Disconnect from the server.
[`RFB.sendCredentials()`](#rfbsendcredentials)
- - Send credentials to server. Should be called after
- [`oncredentialsrequired`](#rfboncredentialsrequired) has been
- called.
+ - Send credentials to server. Should be called after the
+ [`credentialsrequired`](#credentialsrequired) event has fired.
[`RFB.sendKey()`](#rfbsendKey)
- Send a key event.
[`RFB.sendCtrlAltDel()`](#rfbsendctrlaltdel)
- Send Ctrl-Alt-Del key sequence.
+[`RFB.focus()`](#rfbfocus)
+ - Move keyboard focus to the remote session.
+
+[`RFB.blur()`](#rfbblur)
+ - Remove keyboard focus from the remote session.
+
[`RFB.machineShutdown()`](#rfbmachineshutdown)
- Request a shutdown of the remote machine.
[`RFB.clipboardPasteFrom()`](#rfbclipboardPasteFrom)
- Send clipboard contents to server.
-[`RFB.autoscale()`](#rfbautoscale)
- - Set `RFB.viewportScale` so that the framebuffer fits a specified
- container.
-
-[`RFB.requestDesktopSize()`](#rfbrequestDesktopSize)
- - Send a request to change the remote desktop size.
-
-[`RFB.viewportChangeSize()`](#rfbviewportChangeSize)
- - Change size of the viewport.
-
### Details
#### RFB()
-The `RFB()` constructor returns a new `RFB` object. The object will
-initially be disconnected and [`RFB.connect()`](#rfbconnect) must be
-called before the object will be useful.
+The `RFB()` constructor returns a new `RFB` object and initiates a new
+connection to a specified VNC server.
##### Syntax
- var rfb = new RFB( target );
+ let rfb = new RFB( target, url [, options] );
###### Parameters
**`target`**
- - A [`HTMLCanvasElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement)
- that specifies where graphics should be rendered and input events
- should be monitored.
-
-#### RFB.onupdatestate
-
-The `onupdatestate` event handler is fired after the noVNC connection
-state changes. Here is a list of the states that are reported:
-
-| connection state | description
-| ----------------- | ------------
-| `"connecting"` | starting to connect
-| `"connected"` | connected normally
-| `"disconnecting"` | starting to disconnect
-| `"disconnected"` | disconnected
-
-Note that a `RFB` objects can not transition from the disconnected
-state in any way, a new instance of the object has to be created for
-new connections.
-
-##### Syntax
-
- RFB.onupdatestate = function(rfb, state) { ... }
-
-#### RFB.onnotification
-
-The `onnotification` event handler is fired when the `RFB` object wants
-a message displayed to the user. **`msg`** is a `DOMString` specifying
-the actual message, and **`level`** is a `DOMString` indicating the
-severity of the message. The following levels are currently defined:
-
- - `"normal"`
- - `"warn"`
- - `"error"`
-
-**`options`** is currently unused.
-
-##### Syntax
-
- RFB.onnotification = function(rfb, msg, level, options) { ... }
-
-#### RFB.ondisconnected
-
-The `ondisconnected` event handler is fired when the connection has
-been terminated. **`reason`** is `undefined` for a clean termination
-and a `DOMString` specifying the reason in the event of an unexpected
-termination.
-
-##### Syntax
-
- RFB.ondisconnected = function(rfb, reason) { ... }
-
-#### RFB.oncredentialsrequired
-
-The `oncredentialsrequired` event handler is fired when the server
-requests more credentials than were specified to
-[`RFB.connect()`](#rfbconnect). The **`types`** argument is a list of
-all the credentials that are required.
-
-##### Syntax
-
- RFB.oncredentialsrequired = function(rfb, types) { ... }
-
-#### RFB.onclipboard
-
-The `onclipboard` event handler is fired when the server has sent
-clipboard data.
-
-##### Syntax
-
- RFB.onclipboard = function(rfb, text) { ... }
-
-#### RFB.onbell
-
-The `onbell` event handler is fired when the server has requested an
-audible bell.
-
-##### Syntax
-
- RFB.onbell = function(rfb) { ... }
-
-#### RFB.onfbresize
-
-The `onfbresize` event handler is fired when the framebuffer has
-changed dimensions.
-
-##### Syntax
-
- RFB.onfbresize = function(rfb, width, height) { ... }
-
-#### RFB.ondesktopname
-
-The `ondesktopname` event handler is fired when the name of the remote
-desktop changes.
-
-##### Syntax
-
- RFB.ondesktopname = function(rfb, name) { ... }
-
-#### RFB.oncapabilities
-
-The `oncapabilities` event handler is fired whenever an entry is added
-or removed from `RFB.capabilities`.
-
-##### Syntax
-
- RFB.oncapabilities = function(rfb, capabilites) { ... }
-
-#### RFB.connect()
-
-The `RFB.connect()` method is used to initiate a new connection to a
-specified VNC server.
-
-##### Syntax
-
- RFB.connect( url [, options] );
-
-###### Parameters
+ - A block [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
+ that specifies where the `RFB` object should attach itself. The
+ existing contents of the `HTMLElement` will be untouched, but new
+ elements will be added during the lifetime of the `RFB` object.
**`url`**
- A `DOMString` specifying the VNC server to connect to. This must be
- A `DOMString` specifying the ID to provide to any VNC repeater
encountered.
+ `wsProtocols`
+ - An `Array` of `DOMString`s specifying the sub-protocols to use
+ in the WebSocket connection. Empty by default.
+
+#### connect
+
+The `connect` event is fired after all the handshaking with the server
+is completed and the connection is fully established. After this event
+the `RFB` object is ready to recieve graphics updates and to send input.
+
+#### disconnect
+
+The `disconnect` event is fired when the connection has been
+terminated. The `detail` property is an `Object` that contains the
+property `clean`. `clean` is a `boolean` indicating if the termination
+was clean or not. In the event of an unexpected termination or an error
+`clean` will be set to false.
+
+#### credentialsrequired
+
+The `credentialsrequired` event is fired when the server requests more
+credentials than were specified to [`RFB()`](#rfb-1). The `detail`
+property is an `Object` containing the property `types` which is an
+`Array` of `DOMString` listing the credentials that are required.
+
+#### securityfailure
+
+The `securityfailure` event is fired when the handshaking process with
+the server fails during the security negotiation step. The `detail`
+property is an `Object` containing the following properties:
+
+| Property | Type | Description
+| -------- | ----------- | -----------
+| `status` | `long` | The failure status code
+| `reason` | `DOMString` | The **optional** reason for the failure
+
+The property `status` corresponds to the
+[SecurityResult](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#securityresult)
+status code in cases of failure. A status of zero will not be sent in
+this event since that indicates a successful security handshaking
+process. The optional property `reason` is provided by the server and
+thus the language of the string is not known. However most servers will
+probably send English strings. The server can choose to not send a
+reason and in these cases the `reason` property will be omitted.
+
+#### clipboard
+
+The `clipboard` event is fired when the server has sent clipboard data.
+The `detail` property is an `Object` containing the property `text`
+which is a `DOMString` with the clipboard data.
+
+#### bell
+
+The `bell` event is fired when the server has requested an audible
+bell.
+
+#### desktopname
+
+The `desktopname` event is fired when the name of the remote desktop
+changes. The `detail` property is an `Object` with the property `name`
+which is a `DOMString` specifying the new name.
+
+#### capabilities
+
+The `capabilities` event is fired whenever an entry is added or removed
+from `RFB.capabilities`. The `detail` property is an `Object` with the
+property `capabilities` containing the new value of `RFB.capabilities`.
+
#### RFB.disconnect()
The `RFB.disconnect()` method is used to disconnect from the currently
#### RFB.sendCredentials()
The `RFB.sendCredentials()` method is used to provide the missing
-credentials after `RFB.oncredentialsrequired` has been fired.
+credentials after a `credentialsrequired` event has been fired.
##### Syntax
**`credentials`**
- An `Object` specifying the credentials to provide to the server
- when authenticating. See [`RFB.connect()`](#rfbconnect) for
- details.
+ when authenticating. See [`RFB()`](#rfb-1) for details.
#### RFB.sendKey()
RFB.sendCtrlAltDel( );
+#### RFB.focus()
+
+The `RFB.focus()` method sets the keyboard focus on the remote session.
+Keyboard events will be sent to the remote server after this point.
+
+##### Syntax
+
+ RFB.focus( );
+
+#### RFB.blur()
+
+The `RFB.blur()` method remove keyboard focus on the remote session.
+Keyboard events will no longer be sent to the remote server after this
+point.
+
+##### Syntax
+
+ RFB.blur( );
+
#### RFB.machineShutdown()
The `RFB.machineShutdown()` method is used to request to shut down the
**`text`**
- A `DOMString` specifying the clipboard data to send. Currently only
characters from ISO 8859-1 are supported.
-
-#### RFB.autoscale()
-
-The `RFB.autoscale()` method is used to automatically adjust
-`RFB.viewportScale` to fit given dimensions.
-
-##### Syntax
-
- RFB.autoscale( width, height );
-
-###### Parameters
-
-**`width`**
- - A `long` specifying the maximum width of the canvas in CSS pixels.
-
-**`height`**
- - A `long` specifying the maximum height of the canvas in CSS pixels.
-
-#### RFB.requestDesktopSize()
-
-The `RFB.requestDesktopSize()` method is used to request a change of
-the framebuffer. The capability `resize` must be set for this method to
-have any effect.
-
-Note that this is merely a request and the server may deny it.
-[`RFB.onfbresize`](#rfbonfbresize) will be called when the framebuffer
-actually changes dimensions.
-
-##### Syntax
-
- RFB.requestDesktopSize( width, height );
-
-###### Parameters
-
-**`width`**
- - A `long` specifying the new requested width in CSS pixels.
-
-**`height`**
- - A `long` specifying the new requested height in CSS pixels.
-
-#### RFB.viewportChangeSize()
-
-The `RFB.viewportChangeSize()` method is used to change the size of the
-canvas rather than the underlying framebuffer.
-
-This method has no effect if `RFB.clipViewport` is set to `false`.
-
-##### Syntax
-
- RFB.viewportChangeSize( width, height );
-
-###### Parameters
-
-**`width`**
- - A `long` specifying the new width in CSS pixels.
-
-**`height`**
- - A `long` specifying the new height in CSS pixels.
projects / mirror_novnc.git / blobdiff