Canvas2D QML Type

Provides a 2D canvas item enabling drawing via JavaScript. More...

This type is in technology preview and is subject to change.

• List of all members, including inherited members

Properties

• available : bool
• context : object
• contextType : string

Signals

• imageLoaded()
• paint(rect region)
• painted()

Methods

• void cancelRequestAnimationFrame(int handle)
• object getContext(string contextId, ... args)
• bool isImageError(url image)
• bool isImageLoaded(url image)
• bool isImageLoading(url image)
• void loadImage(url image, size sourceSize)
• void markDirty()
• int requestAnimationFrame(callback)
• void requestPaint()
• void unloadImage(url image)

Detailed Description

The Canvas2D item allows drawing of straight and curved lines, simple and complex shapes, graphs, and referenced graphic images. It can also add text, colors, gradients, and patterns, and do low level pixel operations.

Rendering to the Canvas is done using a Canvas2DContext object, usually as a result of the paint signal.

To define a drawing area in the Canvas2D item set the width and height properties. For example, the following code creates a Canvas2D item which has a drawing area with a height of 100 pixels and width of 200 pixels:

import QtCanvas2D

Canvas2D {
    id: mycanvas
    width: 100
    height: 200
    onPaint: {
        var ctx = getContext("2d");
        ctx.fillStyle = Qt.rgba(1, 0, 0, 1);
        ctx.fillRect(0, 0, width, height);
    }
}

Tips for Porting Existing HTML5 Canvas Applications

Although the Canvas item provides an HTML5-like API, HTML5 canvas applications need to be modified to run in the Canvas item:

• Replace all DOM API calls with QML property bindings or Canvas item methods.
• Replace all HTML event handlers with the MouseArea item.
• Change setInterval/setTimeout function calls with the FrameAnimation item or the use of requestAnimationFrame().
• Place painting code into the onPaint handler and trigger painting by calling the markDirty() or requestPaint() methods.
• To draw images, load them by calling the Canvas's loadImage() method and then request to paint them in the onImageLoaded handler.

See also Canvas2DContext, QCanvasPainterItem, and QCanvasPainter.

Property Documentation

available : bool [read-only]

Indicates when Canvas is able to provide a drawing context to operate on.

context : object [read-only]

Holds the active drawing context.

If the canvas is ready and there has been a successful call to getContext() or the contextType property has been set with a supported context type, this property will contain the current drawing context, otherwise null.

contextType : string

The type of drawing context to use.

This property is set to the name of the active context type.

If set explicitly the canvas will attempt to create a context of the named type after becoming available.

The type name is the same as used in the getContext() call, for the 2d canvas the value will be "2d".

See also getContext() and available.

Signal Documentation

imageLoaded()

This signal is emitted when an image has been loaded.

See also loadImage().

paint(rect region)

This signal is emitted when the region needs to be rendered. If a context is active it can be referenced from the context property.

This signal can be triggered by markDirty(), requestPaint() or by changing the current canvas window.

painted()

This signal is emitted after all context painting commands are executed and the Canvas has been rendered.

Method Documentation

void cancelRequestAnimationFrame(int handle)

This function will cancel the animation callback referenced by handle.

object getContext(string contextId, ... args)

Returns a drawing context, or null if no context is available.

The contextId parameter names the required context. The Canvas2D item will return a context that implements the required drawing mode. After the first call to getContext, any subsequent call to getContext with the same contextId will return the same context object. Any additional arguments (args) are currently ignored.

If the context type is not supported or the canvas has previously been requested to provide a different and incompatible context type, null will be returned.

Canvas2D only supports a 2d context.

bool isImageError(url image)

Returns true if the image failed to load, false otherwise.

See also loadImage().

bool isImageLoaded(url image)

Returns true if the image is successfully loaded and ready to use.

See also loadImage().

bool isImageLoading(url image)

Returns true if the image is currently loading.

See also loadImage().

void loadImage(url image, size sourceSize = undefined)

Loads the given image asynchronously.

Once the image is ready, imageLoaded() signal will be emitted. The loaded image can be unloaded with the unloadImage() method.

If sourceSize is specified, the image will be scaled to that size during loading. This is useful for loading scalable (vector) images (eg. SVGs) at their intended display size.

See also unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), and Context2D::drawImage().

void markDirty()

Marks the canvas as dirty. This will trigger the paint signal.

See also paint and requestPaint().

int requestAnimationFrame(callback)

This function schedules callback to be invoked before composing the Qt Quick scene.

void requestPaint()

Request the entire visible region be re-drawn.

See also markDirty().

void unloadImage(url image)

Unloads the image.

Once an image is unloaded, it cannot be painted by the canvas context unless it is loaded again.

See also loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), and Context2D::drawImage.