En esta página

QImageIOHandler Class

La clase QImageIOHandler define la interfaz común de entrada/salida de imágenes para todos los formatos de imagen en Qt. Más información...

Cabecera: #include <QImageIOHandler>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum ImageOption { Size, ClipRect, ScaledSize, ScaledClipRect, Description, …, ImageTransformation }
enum Transformation { TransformationNone, TransformationMirror, TransformationFlip, TransformationRotate180, TransformationRotate90, …, TransformationRotate270 }
flags Transformations

Funciones públicas

QImageIOHandler()
virtual ~QImageIOHandler()
virtual bool canRead() const = 0
virtual int currentImageNumber() const
virtual QRect currentImageRect() const
QIODevice *device() const
QByteArray format() const
virtual int imageCount() const
virtual bool jumpToImage(int imageNumber)
virtual bool jumpToNextImage()
virtual int loopCount() const
virtual int nextImageDelay() const
virtual QVariant option(QImageIOHandler::ImageOption option) const
virtual bool read(QImage *image) = 0
void setDevice(QIODevice *device)
void setFormat(const QByteArray &format)
void setFormat(const QByteArray &format) const
virtual void setOption(QImageIOHandler::ImageOption option, const QVariant &value)
virtual bool supportsOption(QImageIOHandler::ImageOption option) const
virtual bool write(const QImage &image)

Miembros públicos estáticos

(since 6.0) bool allocateImage(QSize size, QImage::Format format, QImage *image)

Descripción detallada

Qt utiliza QImageIOHandler para leer y escribir imágenes a través de QImageReader y QImageWriter. También puedes derivar de esta clase para crear tu propio controlador de formato de imagen utilizando el mecanismo de complementos de Qt.

Llama a ` setDevice()` para asignar un dispositivo al controlador, y a ` setFormat()` para asignarle un formato. Un `QImageIOHandler` puede admitir más de un formato de imagen. ` canRead()` devuelve ` true ` si se puede leer una imagen desde el dispositivo, y ` read()` y ` write()` devuelven `true` si la lectura o la escritura de una imagen se ha completado con éxito.

QImageIOHandler también admite formatos de animación a través de las funciones loopCount(), imageCount(), nextImageDelay() y currentImageNumber().

Para determinar qué opciones admite un gestor de imágenes, Qt llamará a supportsOption() y setOption(). Asegúrate de reimplementar estas funciones si puedes ofrecer compatibilidad con alguna de las opciones de la enumeración ImageOption.

Para escribir tu propio gestor de imágenes, debes, como mínimo, reimplementar canRead() y read(). A continuación, crea un QImageIOPlugin que pueda crear el gestor. Por último, instala tu complemento; QImageReader y QImageWriter cargarán automáticamente el complemento y comenzarán a utilizarlo.

Véase también QImageIOPlugin, QImageReader y QImageWriter.

Documentación sobre los tipos de miembros

enum QImageIOHandler::ImageOption

Esta enumeración describe las diferentes opciones que admite QImageIOHandler. Algunas opciones se utilizan para consultar las propiedades de una imagen, mientras que otras sirven para configurar la forma en que debe escribirse una imagen.

ConstanteValorDescripción
QImageIOHandler::Size0El tamaño original de una imagen. Se espera que un controlador que admita esta opción lea el tamaño de la imagen a partir de los metadatos de la misma y devuelva este tamaño desde ` option()` como un objeto ` QSize`.
QImageIOHandler::ClipRect1El rectángulo de recorte, o ROI (región de interés). Se espera que un controlador que admita esta opción lea únicamente el área QRect proporcionada de la imagen original en read(), antes de que se aplique cualquier otra transformación.
QImageIOHandler::ScaledSize4El tamaño escalado de la imagen. Se espera que un controlador que admita esta opción escale la imagen al tamaño proporcionado (un QSize), tras aplicar cualquier transformación del rectángulo de recorte (ClipRect). Si el controlador no admite esta opción, QImageReader realizará el escalado una vez leída la imagen.
QImageIOHandler::ScaledClipRect3El rectángulo de recorte escalado (o ROI, región de interés) de la imagen. Se espera que un controlador que admita esta opción aplique la rectángulo de recorte proporcionado (un ` QRect`), tras aplicar cualquier escalado (`ScaleSize`) o recorte normal (`ClipRect`). Si el controlador no admite esta opción, ` QImageReader ` aplicará el rectángulo de recorte escalado una vez leída la imagen.
QImageIOHandler::Description2La descripción de la imagen. Algunos formatos de imagen, como GIF y PNG, permiten incrustar texto o comentarios en los datos de la imagen (por ejemplo, para almacenar información de derechos de autor). Es habitual que el texto se almacene en pares clave-valor, pero algunos formatos almacenan todo el texto en un bloque continuo. QImageIOHandler devuelve el texto como un único QString, donde las claves y los valores están separados por un «:», y los pares clave-valor están separados por dos saltos de línea (\n\n ). Por ejemplo: «Título: Puesta de sol\n\nAuthor : Jim Smith\nSarah Jones\n\n ». Los formatos que almacenan el texto en un único bloque pueden utilizar «Descripción» como clave.
QImageIOHandler::CompressionRatio5La relación de compresión de los datos de la imagen. Se espera que un controlador que admita esta opción establezca su tasa de compresión en función del valor de esta opción (un entero) al escribir.
QImageIOHandler::Gamma6El nivel de gamma de la imagen. Se espera que un controlador que admita esta opción establezca el nivel de gamma de la imagen en función del valor de esta opción (un número flotante) al escribir.
QImageIOHandler::Quality7El nivel de calidad de la imagen. Se espera que un controlador que admita esta opción establezca el nivel de calidad de la imagen en función del valor de esta opción (un entero) al escribir.
QImageIOHandler::Name8El nombre de la imagen. Se espera que un controlador que admita esta opción lea el nombre a partir de los metadatos de la imagen y lo devuelva como un ` QString`, o que, al escribir una imagen, almacene el nombre en los metadatos de la imagen.
QImageIOHandler::SubType9El subtipo de la imagen. Un controlador que admita esta opción puede utilizar el valor del subtipo como ayuda al leer y escribir imágenes. Por ejemplo, un controlador PPM puede tener un valor de subtipo «ppm» o «ppmraw».
QImageIOHandler::IncrementalReading10Se espera que un controlador que admita esta opción lea la imagen en varias pasadas, como si se tratara de una animación. QImageReader tratará la imagen como una animación.
QImageIOHandler::Endianness11El orden de bytes (endianidad) de la imagen. Ciertos formatos de imagen pueden almacenarse como BigEndian o LittleEndian. Un controlador que admita la endianidad utiliza el valor de esta opción para determinar cómo debe almacenarse la imagen.
QImageIOHandler::Animation12Los formatos de imagen que admiten animación devuelven «true» para este valor en supportsOption(); en caso contrario, se devuelve «false».
QImageIOHandler::BackgroundColor13Ciertos formatos de imagen permiten especificar el color de fondo. Un controlador que admita «BackgroundColor» inicializa el color de fondo con el valor de esta opción (un ` QColor`) al leer una imagen.
QImageIOHandler::ImageFormat14El formato de datos de la imagen devuelto por el controlador. Puede ser cualquiera de los formatos enumerados en QImage::Format.
QImageIOHandler::SupportedSubTypes15Los formatos de imagen que admiten diferentes variantes de guardado deben devolver una lista de los nombres de las variantes admitidas (QList<QByteArray>) en esta opción.
QImageIOHandler::OptimizedWrite16Se espera que un controlador que admita esta opción active los indicadores de optimización al escribir.
QImageIOHandler::ProgressiveScanWrite17Se espera que un controlador que admita esta opción escriba la imagen como una imagen de exploración progresiva.
QImageIOHandler::ImageTransformation18Un controlador que admita esta opción puede leer los metadatos de transformación de una imagen. Un controlador que admita esta opción no debe aplicar la transformación por sí mismo.

enum QImageIOHandler::Transformation
flags QImageIOHandler::Transformations

Esta enumeración describe las diferentes transformaciones u orientaciones que admiten algunos formatos de imagen, normalmente a través de EXIF.

ConstanteValorDescripción
QImageIOHandler::TransformationNone0No se debe aplicar ninguna transformación.
QImageIOHandler::TransformationMirror1Invertir la imagen horizontalmente.
QImageIOHandler::TransformationFlip2Reflejar la imagen verticalmente.
QImageIOHandler::TransformationRotate180TransformationMirror | TransformationFlipGira la imagen 180 grados. Esto equivale a reflejarla tanto horizontal como verticalmente.
QImageIOHandler::TransformationRotate904Gira la imagen 90 grados.
QImageIOHandler::TransformationMirrorAndRotate90TransformationMirror | TransformationRotate90Invertir la imagen horizontalmente y, a continuación, girarla 90 grados.
QImageIOHandler::TransformationFlipAndRotate90TransformationFlip | TransformationRotate90Invertir la imagen verticalmente y, a continuación, girarla 90 grados.
QImageIOHandler::TransformationRotate270TransformationRotate180 | TransformationRotate90Gira la imagen 270 grados. Esto equivale a reflejarla tanto horizontal como verticalmente y, a continuación, girarla 90 grados.

El tipo «Transformations» es un typedef para QFlags<Transformation>. Almacena una combinación OR de valores de «Transformation».

Véase también QImageReader::transformation(), QImageReader::setAutoTransform() y QImageWriter::setTransformation().

Documentación de las funciones miembro

QImageIOHandler::QImageIOHandler()

Crea un objeto QImageIOHandler.

[virtual noexcept] QImageIOHandler::~QImageIOHandler()

Destruye el objeto ` QImageIOHandler `.

[static, since 6.0] bool QImageIOHandler::allocateImage(QSize size, QImage::Format format, QImage *image)

Se trata de un método de conveniencia para la función de lectura en las subclases. Los gestores de formatos de imagen deben rechazar la carga de una imagen si la asignación necesaria superara el límite de asignación actual. Esta función comprueba los parámetros y el límite, y realiza la asignación si es válida y necesaria. Si la función devuelve un valor de éxito, ` image ` será un objeto ` QImage ` válido y independiente de los valores ` size ` y ` format` proporcionados.

Esta función se introdujo en Qt 6.0.

Véase también QImageReader::allocationLimit().

[pure virtual] bool QImageIOHandler::canRead() const

Devuelve ` true ` si se puede leer una imagen del dispositivo (es decir, si se admite el formato de la imagen, se puede leer desde el dispositivo y la información inicial de la cabecera indica que la imagen se puede leer); en caso contrario, devuelve ` false`.

Al reimplementar canRead(), asegúrate de que el dispositivo de E/S (device()) se mantenga en su estado original (por ejemplo, utilizando peek() en lugar de read()).

Véanse también read() y QIODevice::peek().

[virtual] int QImageIOHandler::currentImageNumber() const

En el caso de los formatos de imagen que admiten animación, esta función devuelve el número de secuencia de la imagen actual dentro de la animación. Si se invoca esta función antes de que se haya llamado a ` read()`, se devuelve -1. El número de la primera imagen de la secuencia es 0.

Si el formato de imagen no admite animación, se devuelve 0.

Véase también read().

[virtual] QRect QImageIOHandler::currentImageRect() const

Devuelve el rectángulo de la imagen actual. Si no se ha definido ningún rectángulo para la imagen, se devuelve un QRect() vacío.

Esta función resulta útil para animaciones, en las que es posible que solo se actualicen partes del fotograma cada vez.

QIODevice *QImageIOHandler::device() const

Devuelve el dispositivo asignado actualmente a QImageIOHandler. Si no se ha asignado ningún dispositivo, se devuelve nullptr.

Véase también setDevice().

QByteArray QImageIOHandler::format() const

Devuelve el formato asignado actualmente a QImageIOHandler. Si no se ha asignado ningún formato, se devuelve una cadena vacía.

Véase también setFormat().

[virtual] int QImageIOHandler::imageCount() const

Para los formatos de imagen que admiten animación, esta función devuelve el número de imágenes que componen la animación. Si el formato de imagen no admite animación, o si no es posible determinar el número de imágenes, se devuelve 0.

La implementación por defecto devuelve 1 si canRead() devuelve true; en caso contrario, se devuelve 0.

[virtual] bool QImageIOHandler::jumpToImage(int imageNumber)

En el caso de los formatos de imagen que admiten animación, esta función salta a la imagen cuyo número de secuencia es imageNumber. La siguiente llamada a ` read()` intentará leer esta imagen.

La implementación por defecto no realiza ninguna acción y devuelve false.

[virtual] bool QImageIOHandler::jumpToNextImage()

En el caso de los formatos de imagen que admiten animación, esta función pasa a la siguiente imagen.

La implementación por defecto no realiza ninguna acción y devuelve ` false`.

[virtual] int QImageIOHandler::loopCount() const

En el caso de los formatos de imagen que admiten animación, esta función devuelve el número de veces que debe repetirse la animación. Si el formato de imagen no admite animación, se devuelve 0.

[virtual] int QImageIOHandler::nextImageDelay() const

En el caso de los formatos de imagen que admiten animación, esta función devuelve el número de milisegundos que hay que esperar antes de leer la siguiente imagen. Si el formato de imagen no admite animación, se devuelve 0.

[virtual] QVariant QImageIOHandler::option(QImageIOHandler::ImageOption option) const

Devuelve el valor asignado a ` option ` como un ` QVariant`. El tipo del valor depende de la opción. Por ejemplo, la opción `(Size)` devuelve una variante ` QSize `.

Véase también setOption() y supportsOption().

[pure virtual] bool QImageIOHandler::read(QImage *image)

Lee una imagen del dispositivo y la almacena en ` image`. Devuelve ` true ` si la imagen se lee correctamente; en caso contrario, devuelve `false`.

En el caso de los formatos de imagen que admiten la carga incremental, así como en los formatos de animación, el gestor de imágenes puede dar por hecho que ` image ` apunta al fotograma anterior.

Véase también canRead().

void QImageIOHandler::setDevice(QIODevice *device)

Establece el dispositivo de la función « QImageIOHandler » en « device ». El gestor de imágenes utilizará este dispositivo al leer y escribir imágenes.

El dispositivo solo se puede configurar una vez y debe hacerse antes de llamar a canRead(), read(), write(), etc. Si necesitas leer varios archivos, crea varias instancias de la subclase adecuada de QImageIOHandler.

Véase también device().

void QImageIOHandler::setFormat(const QByteArray &format)

Establece el formato de la propiedad « QImageIOHandler » en « format ». Este formato resulta especialmente útil para los controladores que admiten varios formatos de imagen.

Véase también format().

void QImageIOHandler::setFormat(const QByteArray &format) const

Establece el formato de ` QImageIOHandler ` en ` format`. Este formato resulta especialmente útil para los controladores que admiten varios formatos de imagen.

Esta función se declara como `const` para que pueda llamarse desde ` canRead()` ().

Véase también format().

[virtual] void QImageIOHandler::setOption(QImageIOHandler::ImageOption option, const QVariant &value)

Establece la opción « option » con el valor « value ».

Véase también « option()» y « ImageOption ».

[virtual] bool QImageIOHandler::supportsOption(QImageIOHandler::ImageOption option) const

Devuelve ` true ` si ` QImageIOHandler ` admite la opción ` option`; en caso contrario, devuelve ` false`. Por ejemplo, si ` QImageIOHandler ` admite la opción ` Size `, `supportsOption(Size)` debe devolver `true`.

Véase también setOption() y option().

[virtual] bool QImageIOHandler::write(const QImage &image)

Escribe la imagen image en el dispositivo asignado. Devuelve true si la operación se realiza correctamente; en caso contrario, devuelve false.

La implementación por defecto no realiza ninguna acción y simplemente devuelve false.

© 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.