]> git.proxmox.com Git - mirror_novnc.git/blob - docs/API.md
Remove 'focusContainer' attribute from API documentation
[mirror_novnc.git] / docs / API.md
1 # 1. Modules / API
2
3 The noVNC client is a composed of several modular components that handle
4 rendering, input, networking, etc. Each of the modules is designed to
5 be cross-browser and be useful as a standalone library in other
6 projects (see LICENSE.txt).
7
8
9 ## 1.1 Module List
10
11 * __Mouse__ (core/input/mouse.js): Mouse input event handler with
12 limited touch support.
13
14 * __Keyboard__ (core/input/keyboard.js): Keyboard input event handler with
15 non-US keyboard support. Translates keyDown and keyUp events to X11
16 keysym values.
17
18 * __Display__ (core/display.js): Efficient 2D rendering abstraction
19 layered on the HTML5 canvas element.
20
21 * __Websock__ (core/websock.js): Websock client from websockify
22 with transparent binary data support.
23 [Websock API](https://github.com/novnc/websockify/wiki/websock.js) wiki page.
24
25 * __RFB__ (core/rfb.js): Main class that implements the RFB
26 protocol and stitches the other classes together.
27
28
29 ## 1.2 Configuration Attributes
30
31 The Mouse, Keyboard, Display and RFB classes have a similar API for
32 configuration options. Each configuration option has a default value,
33 which can be overridden by a a configuration object passed to the
34 constructor. Configuration options can then be read and modified after
35 initialization with "get_*" and "set_*" methods respectively. For
36 example, the following initializes an RFB object with the 'encrypt'
37 configuration option enabled, then confirms it was set, then disables
38 it.
39
40 var rfb = new RFB({'encrypt': true});
41 if (rfb.get_encrypt()) {
42 alert("Encryption is set");
43 }
44 rfb.set_encrypt(false);
45
46 Some attributes are read-only and cannot be changed. For example, the
47 Display 'render_mode' option will throw an exception if an attempt is
48 made to set it. The attribute mode is one of the following:
49
50 RO - read only
51 RW - read write
52 WO - write once
53
54
55 ## 1.3 Methods
56
57 In addition to the getter and setter methods to modify configuration
58 attributes, each of the modules has other methods that are available
59 in the object instance. For example, the Display module has method
60 named 'blitImage' which takes an array of pixel data and draws it to
61 the 2D canvas.
62
63 ## 1.4 Callbacks
64
65 Each of the modules has certain events that can be hooked with
66 callback functions. For the Mouse, Keyboard, Display and RFB classes
67 the callback functions are assigned to configuration attributes. The
68 WebSock module has a method named 'on' that takes two parameters: the
69 callback event name, and the callback function.
70
71 ## 2. Modules
72
73 ## 2.1 Mouse Module
74
75 ### 2.1.1 Configuration Attributes
76
77 | name | type | mode | default | description
78 | ----------- | ---- | ---- | -------- | ------------
79 | target | DOM | WO | document | DOM element that captures mouse input
80 | touchButton | int | RW | 1 | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
81
82 ### 2.1.2 Methods
83
84 | name | parameters | description
85 | ------ | ---------- | ------------
86 | grab | () | Begin capturing mouse events
87 | ungrab | () | Stop capturing mouse events
88
89 ### 2.1.2 Callbacks
90
91 | name | parameters | description
92 | ------------- | ------------------- | ------------
93 | onMouseButton | (x, y, down, bmask) | Handler for mouse button click/release
94 | onMouseMove | (x, y) | Handler for mouse movement
95
96
97 ## 2.2 Keyboard Module
98
99 ### 2.2.1 Configuration Attributes
100
101 | name | type | mode | default | description
102 | ------- | ---- | ---- | -------- | ------------
103 | target | DOM | WO | document | DOM element that captures keyboard input
104
105 ### 2.2.2 Methods
106
107 | name | parameters | description
108 | ------ | ---------- | ------------
109 | grab | () | Begin capturing keyboard events
110 | ungrab | () | Stop capturing keyboard events
111
112 ### 2.2.3 Callbacks
113
114 | name | parameters | description
115 | ---------- | -------------------- | ------------
116 | onKeyPress | (keysym, code, down) | Handler for key press/release
117
118
119 ## 2.3 Display Module
120
121 ### 2.3.1 Configuration Attributes
122
123 | name | type | mode | default | description
124 | ----------- | ----- | ---- | ------- | ------------
125 | target | DOM | WO | | Canvas element for rendering
126 | context | raw | RO | | Canvas 2D context for rendering
127 | logo | raw | RW | | Logo to display when cleared: {"width": width, "height": height, "type": mime-type, "data": data}
128 | scale | float | RW | 1.0 | Display area scale factor 0.0 - 1.0
129 | viewport | bool | RW | false | Use viewport clipping
130 | width | int | RO | | Display area width
131 | height | int | RO | | Display area height
132 | render_mode | str | RO | '' | Canvas rendering mode
133 | prefer_js | str | RW | | Prefer JavaScript over canvas methods
134 | cursor_uri | raw | RW | | Can we render cursor using data URI
135
136 ### 2.3.2 Methods
137
138 | name | parameters | description
139 | ------------------ | ------------------------------------------------------- | ------------
140 | viewportChangePos | (deltaX, deltaY) | Move the viewport relative to the current location
141 | viewportChangeSize | (width, height) | Change size of the viewport
142 | absX | (x) | Return X relative to the remote display
143 | absY | (y) | Return Y relative to the remote display
144 | resize | (width, height) | Set width and height
145 | flip | (from_queue) | Update the visible canvas with the contents of the rendering canvas
146 | clear | () | Clear the display (show logo if set)
147 | pending | () | Check if there are waiting items in the render queue
148 | flush | () | Resume processing the render queue unless it's empty
149 | fillRect | (x, y, width, height, color, from_queue) | Draw a filled in rectangle
150 | copyImage | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
151 | imageRect | (x, y, mime, arr) | Draw a rectangle with an image
152 | startTile | (x, y, width, height, color) | Begin updating a tile
153 | subTile | (tile, x, y, w, h, color) | Update a sub-rectangle within the given tile
154 | finishTile | () | Draw the current tile to the display
155 | blitImage | (x, y, width, height, arr, offset, from_queue) | Blit pixels (of R,G,B,A) to the display
156 | blitRgbImage | (x, y, width, height, arr, offset, from_queue) | Blit RGB encoded image to display
157 | blitRgbxImage | (x, y, width, height, arr, offset, from_queue) | Blit RGBX encoded image to display
158 | drawImage | (img, x, y) | Draw image and track damage
159 | changeCursor | (pixels, mask, hotx, hoty, w, h) | Change cursor appearance
160 | defaultCursor | () | Restore default cursor appearance
161 | disableLocalCursor | () | Disable local (client-side) cursor
162 | clippingDisplay | () | Check if the remote display is larger than the client display
163 | autoscale | (containerWidth, containerHeight, downscaleOnly) | Scale the display
164
165 ### 2.3.3 Callbacks
166
167 | name | parameters | description
168 | ------- | ---------- | ------------
169 | onFlush | () | A display flush has been requested and we are now ready to resume FBU processing
170
171
172 ## 2.4 RFB Module
173
174 ### 2.4.1 Configuration Attributes
175
176 | name | type | mode | default | description
177 | ----------------- | ---- | ---- | ---------- | ------------
178 | target | DOM | WO | null | Canvas element for rendering (passed to Display, Mouse and Keyboard)
179 | encrypt | bool | RW | false | Use TLS/SSL encryption
180 | local_cursor | bool | RW | false | Request locally rendered cursor
181 | shared | bool | RW | true | Request shared VNC mode
182 | view_only | bool | RW | false | Disable client mouse/keyboard
183 | xvp_password_sep | str | RW | '@' | Separator for XVP password fields
184 | disconnectTimeout | int | RW | 3 | Time (in seconds) to wait for disconnection
185 | wsProtocols | arr | RW | ['binary'] | Protocols to use in the WebSocket connection
186 | repeaterID | str | RW | '' | UltraVNC RepeaterID to connect to
187 | viewportDrag | bool | RW | false | Move the viewport on mouse drags
188
189 ### 2.4.2 Methods
190
191 | name | parameters | description
192 | ------------------ | ---------------------------- | ------------
193 | connect | (host, port, password, path) | Connect to the given host:port/path. Optional password and path.
194 | disconnect | () | Disconnect
195 | sendPassword | (passwd) | Send password after onPasswordRequired callback
196 | sendCtrlAltDel | () | Send Ctrl-Alt-Del key sequence
197 | xvpOp | (ver, op) | Send a XVP operation (2=shutdown, 3=reboot, 4=reset)
198 | xvpShutdown | () | Send XVP shutdown.
199 | xvpReboot | () | Send XVP reboot.
200 | xvpReset | () | Send XVP reset.
201 | sendKey | (keysym, code, down) | Send a key press event. If down not specified, send a down and up event.
202 | clipboardPasteFrom | (text) | Send a clipboard paste event
203 | requestDesktopSize | (width, height) | Send a request to change the remote desktop size.
204
205 ### 2.4.3 Callbacks
206
207 | name | parameters | description
208 | ------------------ | -------------------------- | ------------
209 | onUpdateState | (rfb, state, oldstate) | Connection state change (see details below)
210 | onNotification | (rfb, msg, level, options) | Notification for the UI (optional options)
211 | onDisconnected | (rfb, reason) | Disconnection finished with an optional reason. No reason specified means normal disconnect.
212 | onPasswordRequired | (rfb, msg) | VNC password is required (use sendPassword), optionally comes with a message.
213 | onClipboard | (rfb, text) | RFB clipboard contents received
214 | onBell | (rfb) | RFB Bell message received
215 | onFBUReceive | (rfb, fbu) | RFB FBU received but not yet processed (see details below)
216 | onFBUComplete | (rfb, fbu) | RFB FBU received and processed (see details below)
217 | onFBResize | (rfb, width, height) | Frame buffer (remote desktop) size changed
218 | onDesktopName | (rfb, name) | VNC desktop name recieved
219 | onXvpInit | (version) | XVP extensions active for this connection.
220
221
222 __RFB onUpdateState callback details__
223
224 The RFB module has an 'onUpdateState' callback that is invoked after
225 the noVNC connection state changes. Here is a list of the states that
226 are reported. Note that the RFB module can not transition from the
227 disconnected state in any way, a new instance of the object has to be
228 created for new connections.
229
230 | connection state | description
231 | ---------------- | ------------
232 | connecting | starting to connect
233 | connected | connected normally
234 | disconnecting | starting to disconnect
235 | disconnected | disconnected - permanent end-state for this RFB object
236
237 __RFB onFBUReceive and on FBUComplete callback details__
238
239 The onFBUReceive callback is invoked when a frame buffer update
240 message has been received from the server but before the RFB class has
241 done any additional handling. The onFBUComplete callback is invoked
242 with the same information but after the RFB class has handled the
243 message.
244
245 The 'fbu' parameter is an object with the following structure:
246
247 {
248 x: FBU_x_position,
249 y: FBU_y_position,
250 width: FBU_width,
251 height: FBU_height,
252 encoding: FBU_encoding_number,
253 encodingName: FBU_encoding_string
254 }