QCanvasPainterWidget Class
QCanvasPainterWidget es un widget para la representación gráfica que utiliza QCanvasPainter. Más información...
| Encabezado: | #include <QCanvasPainterWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS CanvasPainter) target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter) |
| Desde: | Qt 6.11 |
| Heredado de: | QRhiWidget |
Funciones públicas
| QCanvasPainterWidget(QWidget *parent = nullptr) | |
| virtual | ~QCanvasPainterWidget() override |
| QColor | fillColor() const |
| void | grabCanvas(const QCanvasOffscreenCanvas &canvas, const QObject *context, Functor &&callback) |
| bool | hasSharedPainter() const |
| void | setFillColor(QColor color) |
| void | setSharedPainter(bool enable) |
Funciones protegidas
| void | beginCanvasPainting(QCanvasOffscreenCanvas &canvas) |
| void | endCanvasPainting() |
| virtual void | graphicsResourcesInvalidated() |
| virtual void | initializeResources(QCanvasPainter *painter) |
| virtual void | paint(QCanvasPainter *painter) |
| virtual void | prePaint(QCanvasPainter *painter) |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *event) override |
| virtual void | initialize(QRhiCommandBuffer *cb) override |
| virtual void | releaseResources() override |
| virtual void | render(QRhiCommandBuffer *cb) override |
Descripción detallada
Implementa la función virtual ` paint ` en una subclase para realizar el renderizado utilizando un ` QCanvasPainter`.
El siguiente fragmento de código muestra la estructura típica de una subclase de `QCanvasPainterWidget`:
class MyWidget : public QCanvasPainterWidget
{
public:
void initializeResources(QCanvasPainter *p) override
{
// load assets
if (m_image.isNull())
m_image = p->addImage(QImage("image.png"), QCanvasPainter::ImageFlag::Repeat);
}
void paint(QCanvasPainter *p) override
{
// ... draw using m_image
}
void graphicsResourcesInvalidated() override
{
// textures are lost, indicate the need for reload
m_image = {};
}
QCanvasImage m_image;
};Documentación de las funciones miembro
[explicit] QCanvasPainterWidget::QCanvasPainterWidget(QWidget *parent = nullptr)
Crea un objeto `QCanvasPainterWidget` con el ` parent` indicado.
[override virtual noexcept] QCanvasPainterWidget::~QCanvasPainterWidget()
Destruye el « QCanvasPainterWidget ».
[protected] void QCanvasPainterWidget::beginCanvasPainting(QCanvasOffscreenCanvas &canvas)
Comienza a grabar los comandos de dibujo de « QCanvasPainter » dirigidos a « canvas ».
Nota: Esta función solo debe llamarse desde ` prePaint()`.
beginCanvasPainting() debe ir siempre seguida de la correspondiente llamada a endCanvasPainting() antes de salir de prePaint().
El siguiente fragmento de código, extraído de una subclase de ` QCanvasPainterWidget `, muestra cómo se puede renderizar un lienzo fuera de pantalla y, a continuación, utilizarlo como imagen o patrón de imagen al dibujar el contenido del widget:
class MyWidget : public QCanvasPainterWidget
{
public:
QCanvasOffscreenCanvas canvas;
QCanvasImage canvasImage;
void graphicsResourcesInvalidated() override
{
canvas = {}; // so that the next prePaint() will recreate and redraw the canvas
}
void prePaint(QCanvasPainter *p) override
{
if (canvas.isNull()) {
canvas = p->createCanvas(QSize(320, 240));
beginCanvasPainting(canvas);
p->beginPath();
p->circle(160, 120, 20);
p->setFillStyle(Qt::red);
p->fill();
endCanvasPainting();
canvasImage = p->addImage(canvas, QCanvasPainter::ImageFlag::Repeat);
}
}
void paint(QCanvasPainter *p) override
{
// use canvasImage as a brush or with drawImage()
}
};[protected] void QCanvasPainterWidget::endCanvasPainting()
Indica el final del dibujo en el lienzo especificado en ` beginCanvasPainting()`.
Nota: Esta función solo debe llamarse desde prePaint().
beginCanvasPainting() debe ir siempre seguida de la función correspondiente endCanvasPainting() antes de salir de prePaint().
[override virtual protected] bool QCanvasPainterWidget::event(QEvent *event)
Reimplementa: QRhiWidget::event(QEvent *e).
QColor QCanvasPainterWidget::fillColor() const
Devuelve el color de relleno actual.
Véase también setFillColor().
template <typename Functor> void QCanvasPainterWidget::grabCanvas(const QCanvasOffscreenCanvas &canvas, const QObject *context, Functor &&callback)
Envía una solicitud de lectura de textura para ` canvas`, asociándola con ` context`.
callback Se invoca en el hilo actual (principal/GUI) antes de que la función devuelva un resultado, o más tarde, dependiendo de la implementación subyacente de ` QRhi ` y de la API 3D. La lectura del contenido de la textura puede implicar una copia de la GPU a la CPU, dependiendo de la arquitectura de la GPU. Toma un único argumento ` const QImage & ` y puede ser cualquier functor, incluidos los de solo movimiento.
Si context se destruye antes de que se complete la lectura, la captura se cancela y no se invoca callback. Esto hace que sea seguro que la llamada de retorno haga referencia a objetos que quizá no sobrevivan a la lectura pendiente.
Por ejemplo, el siguiente código guardaría el contenido de un lienzo fuera de pantalla en un archivo PNG:
grabCanvas(m_offscreenCanvas, this, [](const QImage &image) {
image.save("result.png");
});[virtual protected] void QCanvasPainterWidget::graphicsResourcesInvalidated()
Se invoca cuando se pierden los recursos gráficos subyacentes, como las texturas.
Esto indica que los objetos ` QCanvasImage ` devueltos por `addImage()` ya no son válidos, y es necesario volver a llamar a `addImage()`. Si la implementación de ` paint()` es tal que esto no tiene importancia, por ejemplo, porque no se utilizan imágenes o porque siempre se llama a `addImage()`, entonces no es necesario realizar ninguna acción. De lo contrario, se recomienda activar un indicador, o algo similar, y actuar en consecuencia en la siguiente invocación de ` paint()`.
Lo mismo se aplica a los objetos ` QCanvasOffscreenCanvas ` devueltos por ` QCanvasPainter::createCanvas()`. Cuando se llama a esta función, la siguiente invocación de ` paint()` debería crear nuevos lienzos y volver a dibujar su contenido.
Los recursos gráficos pueden perderse, por ejemplo, cuando el widget se mueve a una nueva ventana de nivel superior, ya que eso implica que se asocie a una nueva instancia de QRhi.
Véase también QRhiWidget::releaseResources().
bool QCanvasPainterWidget::hasSharedPainter() const
Devuelve ` true ` si este widget utiliza un pintor compartido.
Véase también setSharedPainter.
[override virtual protected] void QCanvasPainterWidget::initialize(QRhiCommandBuffer *cb)
Reimplementa: QRhiWidget::initialize(QRhiCommandBuffer *cb).
[virtual protected] void QCanvasPainterWidget::initializeResources(QCanvasPainter *painter)
Reimplementa este método para inicializar los recursos utilizando painter. Por lo general, se llamará una vez antes de la primera llamada a prePaint() y paint(). Una excepción se da cuando se pierden los recursos gráficos; consulta graphicsResourcesInvalidated(). En ese caso, este método se volverá a invocar posteriormente.
La implementación por defecto está vacía.
[virtual protected] void QCanvasPainterWidget::paint(QCanvasPainter *painter)
Reimplementa este método para dibujar utilizando ` painter`.
En primer lugar, el widget se rellena con fillColor().
La implementación por defecto está vacía.
[virtual protected] void QCanvasPainterWidget::prePaint(QCanvasPainter *painter)
Reimplementa esta función para dibujar en uno o varios lienzos fuera de pantalla utilizando painter.
La implementación por defecto está vacía.
Véanse también beginCanvasPainting() y endCanvasPainting().
[override virtual protected] void QCanvasPainterWidget::releaseResources()
Reimplementa: QRhiWidget::releaseResources().
[override virtual protected] void QCanvasPainterWidget::render(QRhiCommandBuffer *cb)
Reimplementa: QRhiWidget::render(QRhiCommandBuffer *cb).
void QCanvasPainterWidget::setFillColor(QColor color)
Establece el color de relleno en color. Este color se utilizará para dibujar el fondo del elemento. El color predeterminado es el negro.
Véase también fillColor().
void QCanvasPainterWidget::setSharedPainter(bool enable)
Desactiva el uso compartido del «painter» si enable es false.
Si el uso compartido del pintor está habilitado, todas las instancias de ` QCanvasPainterWidget ` dentro del mismo ` QWindow ` utilizarán el mismo ` QCanvasPainter`. Esta función debe definirse en una fase temprana, por ejemplo, desde el constructor de la clase derivada, y no debe modificarse posteriormente.
El uso compartido de «painter» está habilitado por defecto.
Si dos widgets utilizan pintores dedicados y no compartidos, los recursos gráficos del otro, como los que respaldan QCanvasImage o QOffscreenCanvas, no serán visibles para ellos. En cambio, si los widgets se encuentran en la misma ventana y el uso compartido está habilitado, pueden utilizar imágenes o lienzos creados por el otro widget, ya que ambos utilizan el mismo ` QCanvasPainter`.
Nota: Incluso cuando enable es verdadero, los «pintores» no se comparten entre widgets que pertenezcan a ventanas diferentes (widgets de nivel superior).
Véase también hasSharedPainter.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.