jcarr
/
noVNC
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Split out internal API 

We only commit to maintaining the API of the RFB object, not the
other modules.
This commit is contained in:
Pierre Ossman 2017-10-13 12:18:45 +02:00
parent 458086177c
commit 6929a0a183
2 changed files with 165 additions and 161 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
docs/API-internal.md Normal file
View File

@ -0,0 +1,141 @@
# 1. Internal Modules
The noVNC client is composed of several internal modules that handle
rendering, input, networking, etc. Each of the modules is designed to
be cross-browser and independent from each other.
Note however that the API of these modules is not guaranteed to be
stable, and this documentation is not maintained as well as the
official external API.
## 1.1 Module List
* __Mouse__ (core/input/mouse.js): Mouse input event handler with
limited touch support.
* __Keyboard__ (core/input/keyboard.js): Keyboard input event handler with
non-US keyboard support. Translates keyDown and keyUp events to X11
keysym values.
* __Display__ (core/display.js): Efficient 2D rendering abstraction
layered on the HTML5 canvas element.
* __Websock__ (core/websock.js): Websock client from websockify
with transparent binary data support.
[Websock API](https://github.com/novnc/websockify/wiki/websock.js) wiki page.
## 1.2 Configuration Attributes
The Mouse, Keyboard and Display objects have a similar API for
configuration options as the RFB object. See the official API
documentation for details.
## 1.3 Callbacks
For the Mouse, Keyboard and Display objects the callback functions are
assigned to configuration attributes, just as for the RFB object. The
WebSock module has a method named 'on' that takes two parameters: the
callback event name, and the callback function.
## 2. Modules
## 2.1 Mouse Module
### 2.1.1 Configuration Attributes
| name | type | mode | default | description
| ----------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures mouse input
| touchButton | int | RW | 1 | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
### 2.1.2 Methods
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing mouse events
| ungrab | () | Stop capturing mouse events
### 2.1.2 Callbacks
| name | parameters | description
| ------------- | ------------------- | ------------
| onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
| onMouseMove | (x, y) | Handler for mouse movement
## 2.2 Keyboard Module
### 2.2.1 Configuration Attributes
| name | type | mode | default | description
| ------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures keyboard input
### 2.2.2 Methods
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing keyboard events
| ungrab | () | Stop capturing keyboard events
### 2.2.3 Callbacks
| name | parameters | description
| ---------- | -------------------- | ------------
| onKeyPress | (keysym, code, down) | Handler for key press/release
## 2.3 Display Module
### 2.3.1 Configuration Attributes
| name | type | mode | default | description
| ----------- | ----- | ---- | ------- | ------------
| 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, "type": mime-type, "data": data}
| scale | float | RW | 1.0 | Display area scale factor 0.0 - 1.0
| viewport | bool | RW | false | Use viewport clipping
| width | int | RO | | Display area width
| height | int | RO | | Display area height
| render_mode | str | RO | '' | Canvas rendering mode
| prefer_js | str | RW | | Prefer JavaScript over canvas methods
| cursor_uri | raw | RW | | Can we render cursor using data URI
### 2.3.2 Methods
| name | parameters | description
| ------------------ | ------------------------------------------------------- | ------------
| viewportChangePos | (deltaX, deltaY) | Move the viewport relative to the current location
| viewportChangeSize | (width, height) | Change size of the viewport
| absX | (x) | Return X relative to the remote display
| absY | (y) | Return Y relative to the remote display
| resize | (width, height) | Set width and height
| flip | (from_queue) | Update the visible canvas with the contents of the rendering canvas
| clear | () | Clear the display (show logo if set)
| pending | () | Check if there are waiting items in the render queue
| flush | () | Resume processing the render queue unless it's empty
| fillRect | (x, y, width, height, color, from_queue) | Draw a filled in rectangle
| copyImage | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
| imageRect | (x, y, mime, arr) | Draw a rectangle with an image
| startTile | (x, y, width, height, color) | Begin updating a tile
| subTile | (tile, x, y, w, h, color) | Update a sub-rectangle within the given tile
| finishTile | () | Draw the current tile to the display
| blitImage | (x, y, width, height, arr, offset, from_queue) | Blit pixels (of R,G,B,A) to the display
| blitRgbImage | (x, y, width, height, arr, offset, from_queue) | Blit RGB encoded image to display
| blitRgbxImage | (x, y, width, height, arr, offset, from_queue) | Blit RGBX encoded image to display
| drawImage | (img, x, y) | Draw image and track damage
| changeCursor | (pixels, mask, hotx, hoty, w, h) | Change cursor appearance
| defaultCursor | () | Restore default cursor appearance
| disableLocalCursor | () | Disable local (client-side) cursor
| clippingDisplay | () | Check if the remote display is larger than the client display
| autoscale | (containerWidth, containerHeight, downscaleOnly) | Scale the display
### 2.3.3 Callbacks
| name | parameters | description
| ------- | ---------- | ------------
| onFlush | () | A display flush has been requested and we are now ready to resume FBU processing

185
docs/API.md
View File

@ -1,41 +1,17 @@
# 1. Modules / API # API
The noVNC client is a composed of several modular components that handle The interface of the noVNC client consists of a single RFB object that
rendering, input, networking, etc. Each of the modules is designed to is instantiated once per connection.
be cross-browser and be useful as a standalone library in other
projects (see LICENSE.txt).
## 1.1 Module List ## 1 Configuration Attributes
* __Mouse__ (core/input/mouse.js): Mouse input event handler with Each configuration option has a default value, which can be overridden
limited touch support. by a a configuration object passed to the constructor. Configuration
options can then be read and modified after initialization with "get_*"
* __Keyboard__ (core/input/keyboard.js): Keyboard input event handler with and "set_*" methods respectively. For example, the following
non-US keyboard support. Translates keyDown and keyUp events to X11 initializes an RFB object with the 'encrypt' configuration option
keysym values. enabled, then confirms it was set, then disables it:
* __Display__ (core/display.js): Efficient 2D rendering abstraction
layered on the HTML5 canvas element.
* __Websock__ (core/websock.js): Websock client from websockify
with transparent binary data support.
[Websock API](https://github.com/novnc/websockify/wiki/websock.js) wiki page.
* __RFB__ (core/rfb.js): Main class that implements the RFB
protocol and stitches the other classes together.
## 1.2 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}); var rfb = new RFB({'encrypt': true});
if (rfb.get_encrypt()) { if (rfb.get_encrypt()) {
@ -43,136 +19,14 @@ it.
} }
rfb.set_encrypt(false); rfb.set_encrypt(false);
Some attributes are read-only and cannot be changed. For example, the Some attributes are read-only and cannot be changed. An exception will
Display 'render_mode' option will throw an exception if an attempt is be thrown if an attempt is made to set one of these attributs. The
made to set it. The attribute mode is one of the following: attribute mode is one of the following:
RO - read only RO - read only
RW - read write RW - read write
WO - write once WO - write once
## 1.3 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.
## 1.4 Callbacks
Each of the modules has certain events that can be hooked with
callback functions. For the Mouse, Keyboard, Display 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.
## 2. Modules
## 2.1 Mouse Module
### 2.1.1 Configuration Attributes
| name | type | mode | default | description
| ----------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures mouse input
| touchButton | int | RW | 1 | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
### 2.1.2 Methods
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing mouse events
| ungrab | () | Stop capturing mouse events
### 2.1.2 Callbacks
| name | parameters | description
| ------------- | ------------------- | ------------
| onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
| onMouseMove | (x, y) | Handler for mouse movement
## 2.2 Keyboard Module
### 2.2.1 Configuration Attributes
| name | type | mode | default | description
| ------- | ---- | ---- | -------- | ------------
| target | DOM | WO | document | DOM element that captures keyboard input
### 2.2.2 Methods
| name | parameters | description
| ------ | ---------- | ------------
| grab | () | Begin capturing keyboard events
| ungrab | () | Stop capturing keyboard events
### 2.2.3 Callbacks
| name | parameters | description
| ---------- | -------------------- | ------------
| onKeyPress | (keysym, code, down) | Handler for key press/release
## 2.3 Display Module
### 2.3.1 Configuration Attributes
| name | type | mode | default | description
| ----------- | ----- | ---- | ------- | ------------
| 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, "type": mime-type, "data": data}
| scale | float | RW | 1.0 | Display area scale factor 0.0 - 1.0
| viewport | bool | RW | false | Use viewport clipping
| width | int | RO | | Display area width
| height | int | RO | | Display area height
| render_mode | str | RO | '' | Canvas rendering mode
| prefer_js | str | RW | | Prefer JavaScript over canvas methods
| cursor_uri | raw | RW | | Can we render cursor using data URI
### 2.3.2 Methods
| name | parameters | description
| ------------------ | ------------------------------------------------------- | ------------
| viewportChangePos | (deltaX, deltaY) | Move the viewport relative to the current location
| viewportChangeSize | (width, height) | Change size of the viewport
| absX | (x) | Return X relative to the remote display
| absY | (y) | Return Y relative to the remote display
| resize | (width, height) | Set width and height
| flip | (from_queue) | Update the visible canvas with the contents of the rendering canvas
| clear | () | Clear the display (show logo if set)
| pending | () | Check if there are waiting items in the render queue
| flush | () | Resume processing the render queue unless it's empty
| fillRect | (x, y, width, height, color, from_queue) | Draw a filled in rectangle
| copyImage | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
| imageRect | (x, y, mime, arr) | Draw a rectangle with an image
| startTile | (x, y, width, height, color) | Begin updating a tile
| subTile | (tile, x, y, w, h, color) | Update a sub-rectangle within the given tile
| finishTile | () | Draw the current tile to the display
| blitImage | (x, y, width, height, arr, offset, from_queue) | Blit pixels (of R,G,B,A) to the display
| blitRgbImage | (x, y, width, height, arr, offset, from_queue) | Blit RGB encoded image to display
| blitRgbxImage | (x, y, width, height, arr, offset, from_queue) | Blit RGBX encoded image to display
| drawImage | (img, x, y) | Draw image and track damage
| changeCursor | (pixels, mask, hotx, hoty, w, h) | Change cursor appearance
| defaultCursor | () | Restore default cursor appearance
| disableLocalCursor | () | Disable local (client-side) cursor
| clippingDisplay | () | Check if the remote display is larger than the client display
| autoscale | (containerWidth, containerHeight, downscaleOnly) | Scale the display
### 2.3.3 Callbacks
| name | parameters | description
| ------- | ---------- | ------------
| onFlush | () | A display flush has been requested and we are now ready to resume FBU processing
## 2.4 RFB Module
### 2.4.1 Configuration Attributes
| name | type | mode | default | description | name | type | mode | default | description
| ----------------- | ---- | ---- | ---------- | ------------ | ----------------- | ---- | ---- | ---------- | ------------
| target | DOM | WO | null | Canvas element for rendering (passed to Display, Mouse and Keyboard) | target | DOM | WO | null | Canvas element for rendering (passed to Display, Mouse and Keyboard)
@ -186,7 +40,12 @@ callback event name, and the callback function.
| repeaterID | str | RW | '' | UltraVNC RepeaterID to connect to | repeaterID | str | RW | '' | UltraVNC RepeaterID to connect to
| viewportDrag | bool | RW | false | Move the viewport on mouse drags | viewportDrag | bool | RW | false | Move the viewport on mouse drags
### 2.4.2 Methods
## 2 Methods
In addition to the getter and setter methods to modify configuration
attributes, the RFB object has other methods that are available in the
object instance.
| name | parameters | description | name | parameters | description
| ------------------ | ---------------------------- | ------------ | ------------------ | ---------------------------- | ------------
@ -202,7 +61,11 @@ callback event name, and the callback function.
| clipboardPasteFrom | (text) | Send a clipboard paste event | clipboardPasteFrom | (text) | Send a clipboard paste event
| requestDesktopSize | (width, height) | Send a request to change the remote desktop size. | requestDesktopSize | (width, height) | Send a request to change the remote desktop size.
### 2.4.3 Callbacks
## 3 Callbacks
The RFB object has certain events that can be hooked with callback
functions.
| name | parameters | description | name | parameters | description
| ------------------ | -------------------------- | ------------ | ------------------ | -------------------------- | ------------