CanvasRenderingContext2D.drawWindow()

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

The non-standard and internal only CanvasRenderingContext2D.drawWindow() method of the Canvas 2D API renders a region of a window into the canvas. The contents of the window's viewport are rendered, ignoring viewport clipping and scrolling.

This API cannot be used by Web content. It is chrome only.

Syntax

void ctx.drawWindow(window, x, y, w, h, bgColor, flags = 0);

Parameters

window
The Window to render.
x
The X coordinate of the window.
y
The Y coordnate of the window.
w
The width of the window.
h
The height of the window.
bgColor
A DOMString that specifies the color the canvas is filled with before the window is rendered into it. This color may be transparent/translucent. It is given as a CSS color string (for example, rgb() or rgba()).
Notes:
  • If "rgba(0,0,0,0)" is used for the background color, the drawing will be transparent wherever the window is transparent.
  • Top-level browsed documents are usually not transparent because the user's background-color preference is applied, but iframes are transparent if the page doesn't set a background.
  • If an opaque color is used for the background color, rendering will be faster because we won't have to compute the window's transparency.
flags Optional
Used to better control the drawWindow call. Flags can be ORed together.
Constant Value Description
DRAWWINDOW_DRAW_CARET 0x01 Show the caret if appropriate when drawing.
DRAWWINDOW_DO_NOT_FLUSH 0x02 Do not flush pending layout notifications that could otherwise be batched up.
DRAWWINDOW_DRAW_VIEW 0x04 Draw scrollbars and scroll the viewport if they are present.
DRAWWINDOW_USE_WIDGET_LAYERS 0x08 Use the widget layer manager if available. This means hardware acceleration may be used, but it might actually be slower or lower quality than normal. It will, however, more accurately reflect the pixels rendered to the screen.
DRAWWINDOW_ASYNC_DECODE_IMAGES 0x10 Do not synchronously decode images - draw what we have.

Example

This method draws a snapshot of the contents of a DOM window into the canvas. For example,

ctx.drawWindow(window, 0, 0, 100, 200, "rgb(255,255,255)");

would draw the contents of the current window, in the rectangle (0,0,100,200) in pixels relative to the top-left of the viewport, on a white background, into the canvas. By specifying "rgba(255,255,255,0)" as the color, the contents would be drawn with a transparent background (which would be slower).

It is usually a bad idea to use any background other than pure white "rgb(255,255,255)" or transparent, as this is what all browsers do, and many websites expect that transparent parts of their interface will be drawn on white background.

With this method, it is possible to fill a hidden IFRAME with arbitrary content (e.g., CSS-styled HTML text, or SVG) and draw it into a canvas. It will be scaled, rotated and so on according to the current transformation.

Ted Mielczarek's tab preview extension uses this technique in chrome to provide thumbnails of web pages, and the source is available for reference.

Specifications

Not part of any current specification or draft. This is a non-standard and internal only API.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support Not supported (Yes) Not supported Not supported Not supported
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support Not supported Not supported (Yes) Not supported Not supported Not supported

See also

Document Tags and Contributors

 Contributors to this page: fscholz
 Last updated by: fscholz,