docs/API-internal.md

   1 # 1. Internal Modules
   2
   3 The noVNC client is composed of several internal modules that handle
   4 rendering, input, networking, etc. Each of the modules is designed to
   5 be cross-browser and independent from each other.
   6
   7 Note however that the API of these modules is not guaranteed to be
   8 stable, and this documentation is not maintained as well as the
   9 official external API.
  10
  11
  12 ## 1.1 Module List
  13
  14 * __Mouse__ (core/input/mouse.js): Mouse input event handler with
  15 limited touch support.
  16
  17 * __Keyboard__ (core/input/keyboard.js): Keyboard input event handler with
  18 non-US keyboard support. Translates keyDown and keyUp events to X11
  19 keysym values.
  20
  21 * __Display__ (core/display.js): Efficient 2D rendering abstraction
  22 layered on the HTML5 canvas element.
  23
  24 * __Websock__ (core/websock.js): Websock client from websockify
  25 with transparent binary data support.
  26 [Websock API](https://github.com/novnc/websockify/wiki/websock.js) wiki page.
  27
  28
  29 ## 1.2 Callbacks
  30
  31 For the Mouse, Keyboard and Display objects the callback functions are
  32 assigned to configuration attributes, just as for the RFB object. The
  33 WebSock module has a method named 'on' that takes two parameters: the
  34 callback event name, and the callback function.
  35
  36 ## 2. Modules
  37
  38 ## 2.1 Mouse Module
  39
  40 ### 2.1.1 Configuration Attributes
  41
  42 | name        | type | mode | default  | description
  43 | ----------- | ---- | ---- | -------- | ------------
  44 | touchButton | int  | RW   | 1        | Button mask (1, 2, 4) for which click to send on touch devices. 0 means ignore clicks.
  45
  46 ### 2.1.2 Methods
  47
  48 | name   | parameters | description
  49 | ------ | ---------- | ------------
  50 | grab   | ()         | Begin capturing mouse events
  51 | ungrab | ()         | Stop capturing mouse events
  52
  53 ### 2.1.2 Callbacks
  54
  55 | name          | parameters          | description
  56 | ------------- | ------------------- | ------------
  57 | onmousebutton | (x, y, down, bmask) | Handler for mouse button click/release
  58 | onmousemove   | (x, y)              | Handler for mouse movement
  59
  60
  61 ## 2.2 Keyboard Module
  62
  63 ### 2.2.1 Configuration Attributes
  64
  65 None
  66
  67 ### 2.2.2 Methods
  68
  69 | name   | parameters | description
  70 | ------ | ---------- | ------------
  71 | grab   | ()         | Begin capturing keyboard events
  72 | ungrab | ()         | Stop capturing keyboard events
  73
  74 ### 2.2.3 Callbacks
  75
  76 | name       | parameters           | description
  77 | ---------- | -------------------- | ------------
  78 | onkeypress | (keysym, code, down) | Handler for key press/release
  79
  80
  81 ## 2.3 Display Module
  82
  83 ### 2.3.1 Configuration Attributes
  84
  85 | name         | type  | mode | default | description
  86 | ------------ | ----- | ---- | ------- | ------------
  87 | logo         | raw   | RW   |         | Logo to display when cleared: {"width": width, "height": height, "type": mime-type, "data": data}
  88 | scale        | float | RW   | 1.0     | Display area scale factor 0.0 - 1.0
  89 | clipViewport | bool  | RW   | false   | Use viewport clipping
  90 | width        | int   | RO   |         | Display area width
  91 | height       | int   | RO   |         | Display area height
  92
  93 ### 2.3.2 Methods
  94
  95 | name               | parameters                                              | description
  96 | ------------------ | ------------------------------------------------------- | ------------
  97 | viewportChangePos  | (deltaX, deltaY)                                        | Move the viewport relative to the current location
  98 | viewportChangeSize | (width, height)                                         | Change size of the viewport
  99 | absX               | (x)                                                     | Return X relative to the remote display
 100 | absY               | (y)                                                     | Return Y relative to the remote display
 101 | resize             | (width, height)                                         | Set width and height
 102 | flip               | (from_queue)                                            | Update the visible canvas with the contents of the rendering canvas
 103 | clear              | ()                                                      | Clear the display (show logo if set)
 104 | pending            | ()                                                      | Check if there are waiting items in the render queue
 105 | flush              | ()                                                      | Resume processing the render queue unless it's empty
 106 | fillRect           | (x, y, width, height, color, from_queue)                | Draw a filled in rectangle
 107 | copyImage          | (old_x, old_y, new_x, new_y, width, height, from_queue) | Copy a rectangular area
 108 | imageRect          | (x, y, mime, arr)                                       | Draw a rectangle with an image
 109 | startTile          | (x, y, width, height, color)                            | Begin updating a tile
 110 | subTile            | (tile, x, y, w, h, color)                               | Update a sub-rectangle within the given tile
 111 | finishTile         | ()                                                      | Draw the current tile to the display
 112 | blitImage          | (x, y, width, height, arr, offset, from_queue)          | Blit pixels (of R,G,B,A) to the display
 113 | blitRgbImage       | (x, y, width, height, arr, offset, from_queue)          | Blit RGB encoded image to display
 114 | blitRgbxImage      | (x, y, width, height, arr, offset, from_queue)          | Blit RGBX encoded image to display
 115 | drawImage          | (img, x, y)                                             | Draw image and track damage
 116 | changeCursor       | (pixels, mask, hotx, hoty, w, h)                        | Change cursor appearance
 117 | defaultCursor      | ()                                                      | Restore default cursor appearance
 118 | disableLocalCursor | ()                                                      | Disable local (client-side) cursor
 119 | autoscale          | (containerWidth, containerHeight)                       | Scale the display
 120
 121 ### 2.3.3 Callbacks
 122
 123 | name    | parameters | description
 124 | ------- | ---------- | ------------
 125 | onflush | ()         | A display flush has been requested and we are now ready to resume FBU processing