En esta página

Redimensionamiento de imágenes

Muestra cómo descargar y redimensionar imágenes de forma asíncrona.

Este ejemplo muestra cómo utilizar las clases ` QFuture`, ` QPromise` y ` QFutureWatcher ` para descargar una colección de imágenes de la red y redimensionarlas, sin bloquear la interfaz de usuario.

Imágenes descargadas en una cuadrícula con los botones «Añadir URL», «Cancelar» y el estado «Finalizado»

La aplicación consta de los siguientes pasos:

  1. Descargar imágenes de la lista de URL especificadas por el usuario.
  2. Redimensionar las imágenes.
  3. Mostrar las imágenes redimensionadas en un diseño de cuadrícula.

Empecemos por la descarga:

QFuture<QByteArray> Images::download(const QList<QUrl> &urls)
{

El método ` download() ` toma una lista de URL y devuelve un ` QFuture`. El ` QFuture ` almacena los datos del array de bytes recibidos para cada imagen descargada. Para almacenar los datos dentro del ` QFuture`, creamos un objeto ` QPromise ` e indicamos que ha comenzado para señalar el inicio de la descarga:

    QSharedPointer<QPromise<QByteArray>> promise(new QPromise<QByteArray>());
    promise->start();
    ...
    return promise->future();
}

El «future» asociado a la «promise» se devuelve al llamante.

Sin entrar aún en detalles, cabe señalar que el objeto «promise» está envuelto dentro de un « QSharedPointer ». Esto se explicará más adelante.

Utilizamos QNetworkAccessManager para enviar solicitudes de red y descargar datos para cada URL:

for (const auto &url : urls) {
    QSharedPointer<QNetworkReply> reply(qnam.get(QNetworkRequest(url)));
    replies.push_back(reply);

Y aquí empieza lo interesante:

    QtFuture::connect(reply.get(), &QNetworkReply::finished).then([=] {
        if (promise->isCanceled()) {
            if (!promise->future().isFinished())
                promise->finish();
            return;
        }

        if (reply->error() != QNetworkReply::NoError) {
            if (!promise->future().isFinished())
                throw reply->error();
        }
        promise->addResult(reply->readAll());

        // Report finished on the last download
        if (promise->future().resultCount() == urls.size())
            promise->finish();
    }).onFailed([promise] (QNetworkReply::NetworkError error) {
        promise->setException(std::make_exception_ptr(error));
        promise->finish();
    }).onFailed([promise] {
        const auto ex = std::make_exception_ptr(
                    std::runtime_error("Unknown error occurred while downloading."));
        promise->setException(ex);
        promise->finish();
    });
}
    ...

En lugar de conectarnos a las señales de ` QNetworkReply` mediante el método ` QObject::connect()`, utilizamos ` QtFuture::connect()`. Funciona de forma similar a ` QObject::connect()`, pero devuelve un objeto ` QFuture `, que queda disponible tan pronto como se emite la señal ` QNetworkReply::finished()`. Esto nos permite adjuntar continuaciones y controladores de errores, tal y como se hace en el ejemplo.

En la continuación asociada mediante ` .then()` (), comprobamos si el usuario ha solicitado cancelar la descarga. Si es así, detenemos el procesamiento de la solicitud. Al llamar al método ` QPromise::finish()` (), notificamos al usuario que el procesamiento ha finalizado. En caso de que la solicitud de red haya finalizado con un error, lanzamos una excepción. La excepción se gestionará en el controlador de errores adjunto mediante el método .onFailed(). Ten en cuenta que tenemos dos controladores de errores: el primero captura los errores de red, y el segundo, todas las demás excepciones lanzadas durante la ejecución. Ambos controladores guardan la excepción dentro del objeto «promise» (para que la gestione quien haya llamado al método download() ) e informan de que el cálculo ha finalizado. Ten en cuenta también que, por simplicidad, en caso de error interrumpimos todas las descargas pendientes.

Si la solicitud no se ha cancelado y no se ha producido ningún error, leemos los datos de la respuesta de la red y los añadimos a la lista de resultados del objeto «promise»:

    ...
    promise->addResult(reply->readAll());

    // Report finished on the last download
    if (promise->future().resultCount() == urls.size())
        promise->finish();
    ...

Si el número de resultados almacenados en el objeto «promise» es igual al número de archivos « url» que hay que descargar, no hay más solicitudes que procesar, por lo que también notificamos que la promesa ha finalizado.

Como se ha mencionado anteriormente, hemos envuelto la promesa dentro de un ` QSharedPointer`. Dado que el objeto `promise` se comparte entre los controladores conectados a cada respuesta de red, necesitamos copiar y utilizar el objeto `promise` en varios lugares simultáneamente. Por lo tanto, se utiliza un ` QSharedPointer `.

El método ` download() ` se invoca desde el método ` Images::process `. Se ejecuta cuando el usuario pulsa el botón «Añadir URL »:

    ...
    connect(addUrlsButton, &QPushButton::clicked, this, &Images::process);
    ...

Tras borrar los posibles restos de descargas anteriores, creamos un cuadro de diálogo para que el usuario pueda especificar las URL de las imágenes que desea descargar. En función del número de URL especificadas, inicializamos el diseño en el que se mostrarán las imágenes e iniciamos la descarga. Se guarda el objeto «future» devuelto por el método « download() », de modo que el usuario pueda cancelar la descarga si es necesario:

void Images::process()
{
    // Clean previous state
    replies.clear();
    addUrlsButton->setEnabled(false);

    if (downloadDialog->exec() == QDialog::Accepted) {

        const auto urls = downloadDialog->getUrls();
        if (urls.empty())
            return;

        cancelButton->setEnabled(true);

        initLayout(urls.size());

        downloadFuture = download(urls);
        statusBar->showMessage(tr("Downloading..."));
    ...

A continuación, adjuntamos una continuación para gestionar el paso de redimensionamiento. Más adelante hablaremos de ello:

downloadFuture
        .then([this](auto) {
            cancelButton->setEnabled(false);
            updateStatus(tr("Scaling..."));
            scalingWatcher.setFuture(QtConcurrent::run(Images::scaled,
                                                       downloadFuture.results()));
        })
    ...

Después de eso, adjuntamos los controladores onCanceled() y onFailed():

        .onCanceled([this] {
            updateStatus(tr("Download has been canceled."));
        })
        .onFailed([this](QNetworkReply::NetworkError error) {
            updateStatus(tr("Download finished with error: %1").arg(error));
            // Abort all pending requests
            abortDownload();
        })
        .onFailed([this](const std::exception &ex) {
            updateStatus(tr(ex.what()));
        })
    ...

El controlador asociado mediante el método .onCanceled() se llamará si el usuario ha pulsado el botón «Cancelar »:

    ...
    connect(cancelButton, &QPushButton::clicked, this, &Images::cancel);
    ...

El método cancel() simplemente cancela todas las solicitudes pendientes:

void Images::cancel()
{
    statusBar->showMessage(tr("Canceling..."));

    downloadFuture.cancel();
    abortDownload();
}

Los controladores asociados mediante el método .onFailed() se invocarán en caso de que se haya producido un error durante uno de los pasos anteriores. Por ejemplo, si se ha registrado un error de red en la promesa durante el paso de descarga, este se propagará al controlador que toma QNetworkReply::NetworkError como argumento.

Si el ` downloadFuture ` no se cancela y no ha notificado ningún error, se ejecuta la continuación del escalado.

Dado que el escalado puede suponer una gran carga computacional y no queremos bloquear el hilo principal, utilizamos QtConcurrent::run() para iniciar el paso de escalado en un nuevo hilo.

scalingWatcher.setFuture(QtConcurrent::run(Images::scaled,
                                           downloadFuture.results()));

Dado que el escalado se inicia en un hilo independiente, es posible que el usuario decida cerrar la aplicación mientras la operación de escalado está en curso. Para gestionar estas situaciones de forma adecuada, pasamos el objeto ` QFuture ` devuelto por `QtConcurrent::run()` a la instancia de ` QFutureWatcher `.

La señal « QFutureWatcher::finished » del observador está conectada a la ranura « Images::scaleFinished »:

    connect(&scalingWatcher, &QFutureWatcher<QList<QImage>>::finished,
            this, &Images::scaleFinished);

Esta ranura se encarga de mostrar las imágenes escaladas en la interfaz de usuario, así como de gestionar los errores que pudieran producirse durante el escalado:

void Images::scaleFinished()
{
    const OptionalImages result = scalingWatcher.result();
    if (result.has_value()) {
        const auto scaled = result.value();
        showImages(scaled);
        updateStatus(tr("Finished"));
    } else {
        updateStatus(tr("Failed to extract image data."));
    }
    addUrlsButton->setEnabled(true);
}

La notificación de errores se implementa devolviendo un «optional» desde el método « Images::scaled() »:

Images::OptionalImages Images::scaled(const QList<QByteArray> &data)
{
    QList<QImage> scaled;
    for (const auto &imgData : data) {
        QImage image;
        image.loadFromData(imgData);
        if (image.isNull())
            return std::nullopt;

        scaled.push_back(image.scaled(100, 100, Qt::KeepAspectRatio));
    }

    return scaled;
}

El tipo ` Images::OptionalImages ` aquí es simplemente una definición de tipo (`typedef`) para ` std::optional`:

using OptionalImages = std::optional<QList<QImage>>;

Nota: Nopodemos gestionar los errores de la operación de escalado asíncrono utilizando el controlador ` .onFailed()`, ya que este debe ejecutarse en el contexto del objeto ` Images ` en el hilo de la interfaz de usuario. Si el usuario cierra la aplicación mientras se realiza el cálculo asíncrono, el objeto ` Images ` se destruirá y el acceso a sus miembros desde la continuación provocará un bloqueo. El uso de « QFutureWatcher » y sus señales nos permite evitar el problema, ya que las señales se desconectan cuando se destruye el « QFutureWatcher », por lo que las ranuras relacionadas nunca se ejecutarán en un contexto destruido.

El resto del código es sencillo; puedes consultar el proyecto de ejemplo para obtener más detalles.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Proyecto de ejemplo en code.qt.io

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