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.
| Constante | Valor | Descripción |
|---|---|---|
QImageIOHandler::Size | 0 | El 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::ClipRect | 1 | El 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::ScaledSize | 4 | El 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::ScaledClipRect | 3 | El 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::Description | 2 | La 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::CompressionRatio | 5 | La 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::Gamma | 6 | El 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::Quality | 7 | El 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::Name | 8 | El 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::SubType | 9 | El 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::IncrementalReading | 10 | Se 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::Endianness | 11 | El 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::Animation | 12 | Los formatos de imagen que admiten animación devuelven «true» para este valor en supportsOption(); en caso contrario, se devuelve «false». |
QImageIOHandler::BackgroundColor | 13 | Ciertos 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::ImageFormat | 14 | El formato de datos de la imagen devuelto por el controlador. Puede ser cualquiera de los formatos enumerados en QImage::Format. |
QImageIOHandler::SupportedSubTypes | 15 | Los 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::OptimizedWrite | 16 | Se espera que un controlador que admita esta opción active los indicadores de optimización al escribir. |
QImageIOHandler::ProgressiveScanWrite | 17 | Se espera que un controlador que admita esta opción escriba la imagen como una imagen de exploración progresiva. |
QImageIOHandler::ImageTransformation | 18 | Un 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.
| Constante | Valor | Descripción |
|---|---|---|
QImageIOHandler::TransformationNone | 0 | No se debe aplicar ninguna transformación. |
QImageIOHandler::TransformationMirror | 1 | Invertir la imagen horizontalmente. |
QImageIOHandler::TransformationFlip | 2 | Reflejar la imagen verticalmente. |
QImageIOHandler::TransformationRotate180 | TransformationMirror | TransformationFlip | Gira la imagen 180 grados. Esto equivale a reflejarla tanto horizontal como verticalmente. |
QImageIOHandler::TransformationRotate90 | 4 | Gira la imagen 90 grados. |
QImageIOHandler::TransformationMirrorAndRotate90 | TransformationMirror | TransformationRotate90 | Invertir la imagen horizontalmente y, a continuación, girarla 90 grados. |
QImageIOHandler::TransformationFlipAndRotate90 | TransformationFlip | TransformationRotate90 | Invertir la imagen verticalmente y, a continuación, girarla 90 grados. |
QImageIOHandler::TransformationRotate270 | TransformationRotate180 | TransformationRotate90 | Gira 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.