Canvas QML Type

Proporciona un elemento de lienzo 2D que permite dibujar a través de JavaScript. Más...

• Lista de todos los miembros, incluidos los heredados
• Miembros obsoletos

Propiedades

• available : bool
• canvasSize : size
• context : object
• contextType : string
• renderStrategy : enumeration
• renderTarget : enumeration

Señales

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

Métodos

• 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(rect area)
• int requestAnimationFrame(callback)
• void requestPaint()
• bool save(string filename, size imageSize)
• string toDataURL(string mimeType)
• void unloadImage(url image)

Descripción detallada

El elemento Lienzo permite dibujar líneas rectas y curvas, formas simples y complejas, gráficos e imágenes gráficas referenciadas. También puede añadir texto, colores, sombras, degradados y patrones, y realizar operaciones de píxeles de bajo nivel. La salida del lienzo puede guardarse como un archivo de imagen o serializarse en una URL.

El renderizado en el Lienzo se realiza utilizando un objeto Context2D, normalmente como resultado de la señal paint.

Para definir un área de dibujo en el elemento Lienzo establezca las propiedades width y height. Por ejemplo, el siguiente código crea un elemento Lienzo que tiene un área de dibujo con una altura de 100 píxeles y una anchura de 200 píxeles:

import QtQuick 2.0
Canvas {
    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);
    }
}

Actualmente el elemento Lienzo sólo soporta el contexto de renderizado bidimensional.

Renderizado por hilos y objetivo de renderizado

En Qt 6.0 el elemento Canvas soporta un objetivo de renderizado: Canvas.Image.

El objetivo de renderizado Canvas.Image es un objeto QImage. Este objetivo de renderizado soporta renderizado por hilos en segundo plano, lo que permite ejecutar pinturas complejas o de larga duración sin bloquear la interfaz de usuario. Este es el único objetivo de renderizado soportado por todos los backends de Qt Quick.

El objetivo de renderizado por defecto es Canvas.Image y el renderStrategy por defecto es Canvas.Immediate.

Operaciones con píxeles

Se admiten todas las operaciones de píxeles de contexto 2D de HTML5. Para garantizar un mejor rendimiento en la lectura/escritura de píxeles, debe elegirse el destino de renderizado Canvas.Image.

Consejos para portar aplicaciones Canvas HTML5 existentes

Aunque el elemento Canvas proporciona una API similar a HTML5, las aplicaciones canvas HTML5 deben modificarse para ejecutarse en el elemento Canvas:

• Sustituya todas las llamadas a la API DOM por enlaces a propiedades QML o métodos del elemento Canvas.
• Sustituya todos los controladores de eventos HTML por el elemento MouseArea.
• Cambiar las llamadas a las funciones setInterval/setTimeout por el elemento Timer o el uso de requestAnimationFrame().
• Coloque el código de pintura en el manejador onPaint y dispare la pintura llamando a los métodos markDirty() o requestPaint().
• Para dibujar imágenes, cárguelas llamando al método loadImage() del Canvas y luego solicite pintarlas en el manejador onImageLoaded.

A partir de Qt 5.4, el Canvas es un texture provider y puede ser utilizado directamente en ShaderEffects y otras clases que consumen proveedores de texturas.

Ver también Context2D, QQuickPaintedItem, y Qt Quick Ejemplos - Manejadores de Punteros.

Documentación de propiedades

available : bool [read-only]

Indica cuando Canvas es capaz de proporcionar un contexto de dibujo sobre el que operar.

canvasSize : size

Indica el tamaño lógico del lienzo sobre el que pinta el contexto.

Por defecto, el tamaño del lienzo es el mismo que el del elemento canvas actual.

Estableciendo canvasSize, tileSize y canvasWindow, el elemento Canvas puede actuar como un gran lienzo virtual con muchos rectángulos de mosaico renderizados por separado. Sólo los azulejos dentro de la ventana del lienzo actual son pintados por el motor de renderizado del lienzo.

Véase también tileSize y canvasWindow.

context : object [read-only]

Contiene el contexto de dibujo activo.

Si el lienzo está listo y ha habido una llamada exitosa a getContext() o la propiedad contextType ha sido establecida con un tipo de contexto soportado, esta propiedad contendrá el contexto de dibujo actual, de lo contrario será null.

contextType : string

El tipo de contexto de dibujo a utilizar.

Esta propiedad se establece con el nombre del tipo de contexto activo.

Si se establece explícitamente el lienzo intentará crear un contexto del tipo nombrado después de estar disponible.

El nombre del tipo es el mismo que se utiliza en la llamada a getContext(), para el lienzo 2d el valor será "2d".

Véase también getContext() y available.

renderStrategy : enumeration

Mantiene la estrategia actual de renderizado del lienzo.

Esta sugerencia se proporciona junto con renderTarget al contexto gráfico para determinar el método de renderizado. Una renderStrategy, renderTarget o una combinación puede no ser soportada por un contexto gráfico, en cuyo caso el contexto elegirá las opciones apropiadas y Canvas señalará el cambio a las propiedades.

Las pruebas de configuración o de tiempo de ejecución pueden hacer que el gráfico de escena QML se renderice en el subproceso GUI. La selección de Canvas.Cooperative no garantiza que la renderización se produzca en un subproceso distinto del subproceso de la interfaz gráfica de usuario.

El valor predeterminado es Canvas.Immediate.

Véase también renderTarget.

renderTarget : enumeration

Mantiene el objetivo de renderizado del lienzo actual.

Esta pista se proporciona junto con renderStrategy al contexto gráfico para determinar el método de renderizado. Un renderStrategy, renderTarget o una combinación pueden no ser soportados por un contexto gráfico, en cuyo caso el contexto elegirá las opciones apropiadas y Canvas señalará el cambio a las propiedades.

El objetivo de renderizado por defecto es Canvas.Image.

Documentación de Señales

imageLoaded()

Esta señal se emite cuando se ha cargado una imagen.

Véase también loadImage().

paint(rect region)

Esta señal se emite cuando es necesario renderizar region. Si un contexto está activo puede ser referenciado desde la propiedad context.

Esta señal puede ser activada por markDirty(), requestPaint() o por el cambio de la ventana actual del lienzo.

painted()

Esta señal se emite después de que se hayan ejecutado todos los comandos de pintado contextual y se haya renderizado el lienzo.

Documentación del método

void cancelRequestAnimationFrame(int handle)

Esta función cancelará la llamada de retorno de la animación referenciada por handle.

object getContext(string contextId, ... args)

Devuelve un contexto de dibujo, o null si no hay ningún contexto disponible.

El parámetro contextId nombra el contexto requerido. El elemento Canvas devolverá un contexto que implemente el modo de dibujo requerido. Después de la primera llamada a getContext, cualquier llamada posterior a getContext con el mismo contextId devolverá el mismo objeto de contexto. Cualquier argumento adicional (args) se ignora actualmente.

Si el tipo de contexto no está soportado o el lienzo ha sido previamente solicitado para proporcionar un tipo de contexto diferente e incompatible, se devolverá null.

Canvas sólo soporta un contexto 2d.

bool isImageError(url image)

Devuelve true si image no se ha cargado, false en caso contrario.

Véase también loadImage().

bool isImageLoaded(url image)

Devuelve true si image se ha cargado correctamente y está listo para su uso.

Véase también loadImage().

bool isImageLoading(url image)

Devuelve true si image se está cargando actualmente.

Véase también loadImage().

void loadImage(url image, size sourceSize = undefined)

Carga la imagen image de forma asíncrona.

Una vez que la imagen esté lista, se emitirá la señal imageLoaded(). La imagen cargada puede ser descargada con el método unloadImage().

Si se especifica sourceSize, la imagen se escalará a ese tamaño durante la carga. Esto es útil para cargar imágenes escalables (vectoriales) (por ejemplo, SVG) en su tamaño de visualización previsto. Este parámetro se introdujo en Qt 6.7.

Véase también unloadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), y Context2D::drawImage().

void markDirty(rect area)

Marca el area dado como sucio, de modo que cuando esta área sea visible el renderizador del lienzo la redibujará. Esto activará la señal paint.

Véase también paint y requestPaint().

int requestAnimationFrame(callback)

Esta función programa callback para ser invocada antes de componer la escena Qt Quick.

void requestPaint()

Solicita que se redibuje toda la región visible.

Véase también markDirty().

bool save(string filename, size imageSize = undefined)

Guarda el contenido del lienzo actual en un archivo de imagen filename. El formato de la imagen guardada se decide automáticamente por el sufijo de filename. Devuelve true en caso de éxito. Si se especifica imageSize, la imagen resultante tendrá este tamaño, y tendrá un devicePixelRatio de 1.0. En caso contrario, se aplicará a la imagen guardada el devicePixelRatio() de la ventana en la que se muestra el lienzo.

Véase también canvasWindow, canvasSize, y toDataURL().

string toDataURL(string mimeType)

Devuelve una URL de datos para la imagen en el lienzo.

El valor predeterminado de mimeType es "image/png".

Véase también save().

void unloadImage(url image)

Descarga image.

Una vez que una imagen es descargada, no puede ser pintada por el contexto del lienzo a menos que sea cargada de nuevo.

Véase también loadImage(), imageLoaded(), isImageLoaded(), Context2D::createImageData(), y Context2D::drawImage.