En esta página

QClipboard Class

La clase QClipboard permite acceder al portapapeles del sistema de ventanas. Más información...

Encabezado: #include <QClipboard>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredan: QObject

Tipos públicos

enum Mode { Clipboard, Selection, FindBuffer }

Funciones públicas

void clear(QClipboard::Mode mode = Clipboard)
QImage image(QClipboard::Mode mode = Clipboard) const
const QMimeData *mimeData(QClipboard::Mode mode = Clipboard) const
bool ownsClipboard() const
bool ownsFindBuffer() const
bool ownsSelection() const
QPixmap pixmap(QClipboard::Mode mode = Clipboard) const
void setImage(const QImage &image, QClipboard::Mode mode = Clipboard)
void setMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)
void setPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)
void setText(const QString &text, QClipboard::Mode mode = Clipboard)
bool supportsFindBuffer() const
bool supportsSelection() const
QString text(QClipboard::Mode mode = Clipboard) const
QString text(QString &subtype, QClipboard::Mode mode = Clipboard) const

Señales

void changed(QClipboard::Mode mode)
void dataChanged()
void findBufferChanged()
void selectionChanged()

Descripción detallada

El portapapeles ofrece un mecanismo sencillo para copiar y pegar datos entre aplicaciones.

QClipboard admite los mismos tipos de datos que QDrag y utiliza mecanismos similares. Para un uso avanzado del portapapeles, consulta «Arrastrar y soltar».

En una aplicación hay un único objeto QClipboard, al que se puede acceder mediante QGuiApplication::clipboard().

Ejemplo:

QClipboard *clipboard = QGuiApplication::clipboard();
QString originalText = clipboard->text();
// etc.
clipboard->setText(newText);

QClipboard cuenta con algunas funciones prácticas para acceder a tipos de datos comunes: ` setText()` permite el intercambio de texto Unicode, mientras que ` setPixmap()` y ` setImage()` permiten el intercambio de QPixmaps y QImages entre aplicaciones. La función ` setMimeData()` es lo último en flexibilidad: permite añadir cualquier ` QMimeData ` al portapapeles. Existen funciones de lectura correspondientes para cada una de ellas, por ejemplo: text(), image() y pixmap(). Se puede vaciar el portapapeles llamando a clear().

A continuación se muestra un ejemplo típico del uso de estas funciones:

void DropArea::paste()
{
    const QClipboard *clipboard = QGuiApplication::clipboard();
    const QMimeData *mimeData = clipboard->mimeData();

    if (mimeData->hasImage()) {
        setPixmap(qvariant_cast<QPixmap>(mimeData->imageData()));
    } else if (mimeData->hasHtml()) {
        setText(mimeData->html());
        setTextFormat(Qt::RichText);
    } else if (mimeData->hasText()) {
        setText(mimeData->text());
        setTextFormat(Qt::PlainText);
    } else {
        setText(tr("Cannot display data"));
    }
}

Notas para usuarios de X11

  • El sistema de ventanas X11 cuenta con los conceptos de «selección» y «portapapeles» independientes. Cuando se selecciona texto, este queda inmediatamente disponible como selección global del ratón. La selección global del ratón puede copiarse posteriormente al portapapeles. Por convención, el botón central del ratón se utiliza para pegar la selección global del ratón.
  • X11 también cuenta con el concepto de «propiedad»; si se modifica la selección dentro de una ventana, X11 solo notificará el cambio al propietario y al propietario anterior, es decir, no notificará a todas las aplicaciones que la selección o los datos del portapapeles han cambiado.
  • Por último, el portapapeles de X11 funciona por eventos, es decir, no funcionará correctamente si el bucle de eventos no está en ejecución. Del mismo modo, se recomienda que el contenido del portapapeles se almacene o recupere en respuesta directa a eventos de entrada del usuario, como pulsaciones y sueltas de botones del ratón o teclas. No se debe almacenar ni recuperar el contenido del portapapeles en respuesta a eventos de temporizador o que no sean de entrada del usuario.
  • Dado que no existe una forma estándar de copiar y pegar archivos entre aplicaciones en X11, actualmente se utilizan diversos tipos MIME y convenciones. Por ejemplo, Nautilus espera que los archivos se proporcionen con un tipo MIME x-special/gnome-copied-files, con datos que comiencen por la acción de cortar/copiar, un carácter de nueva línea y la URL del archivo.

Notas para usuarios de macOS

macOS admite un búfer de búsqueda independiente que almacena la cadena de búsqueda actual en las operaciones de búsqueda. Se puede acceder a este portapapeles de búsqueda especificando el modo FindBuffer.

Notas para usuarios de Windows y macOS

  • Ni Windows ni macOS admiten la selección global con el ratón; solo admiten el portapapeles global, es decir, solo añaden texto al portapapeles cuando se realiza una acción explícita de copiar o cortar.
  • Ni Windows ni macOS cuentan con el concepto de propiedad; el portapapeles es un recurso totalmente global, por lo que todas las aplicaciones reciben notificación de los cambios.

Notas para usuarios de Android

En Android solo se admiten estos tipos MIME: text/plain, text/html y text/uri-list.

Véase también QGuiApplication.

Documentación sobre los tipos de miembro

enum QClipboard::Mode

Este tipo de enumeración se utiliza para controlar qué parte del portapapeles del sistema utilizan las funciones ` QClipboard::mimeData()`, ` QClipboard::setMimeData()` y otras relacionadas.

ConstanteValorDescripción
QClipboard::Clipboard0indica que los datos deben almacenarse y recuperarse del portapapeles global.
QClipboard::Selection1indica que los datos deben almacenarse y recuperarse de la selección global del ratón. La compatibilidad con Selection solo está disponible en sistemas con selección global del ratón (por ejemplo, X11).
QClipboard::FindBuffer2indica que los datos deben almacenarse y recuperarse del búfer de búsqueda. Este modo se utiliza para guardar cadenas de búsqueda en macOS.

Véase también QClipboard::supportsSelection().

Documentación de funciones miembro

[signal] void QClipboard::changed(QClipboard::Mode mode)

Esta señal se emite cuando se modifican los datos del portapapeles especificado mode.

Véanse también dataChanged(), selectionChanged() y findBufferChanged().

void QClipboard::clear(QClipboard::Mode mode = Clipboard)

Borrar el contenido del portapapeles.

El argumento « mode » se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si « mode » es « QClipboard::Clipboard », esta función borra el contenido del portapapeles global. Si « mode » es « QClipboard::Selection », esta función borra el contenido de la selección global del ratón. Si « mode » es « QClipboard::FindBuffer », esta función borra el búfer de la cadena de búsqueda.

Véase también QClipboard::Mode y supportsSelection().

[signal] void QClipboard::dataChanged()

Esta señal se emite cuando se modifican los datos del portapapeles.

En macOS y con la versión 4.3 o superior de Qt, los cambios en el portapapeles realizados por otras aplicaciones solo se detectarán cuando la aplicación esté activa.

Véase también findBufferChanged(), selectionChanged() y changed().

[signal] void QClipboard::findBufferChanged()

Esta señal se emite cuando se modifica el búfer de búsqueda. Esto solo se aplica a macOS.

Con la versión 4.3 o superior de Qt, los cambios en el portapapeles realizados por otras aplicaciones solo se detectarán cuando la aplicación esté activa.

Véase también dataChanged(), selectionChanged() y changed().

QImage QClipboard::image(QClipboard::Mode mode = Clipboard) const

Devuelve la imagen del portapapeles o, si este no contiene ninguna imagen o contiene una imagen en un formato no compatible, devuelve una imagen nula.

El argumento ` mode ` se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si ` mode ` es ` QClipboard::Clipboard`, la imagen se recupera del portapapeles global. Si ` mode ` es ` QClipboard::Selection`, la imagen se recupera de la selección global del ratón.

Véase también setImage(), pixmap(), mimeData() y QImage::isNull().

const QMimeData *QClipboard::mimeData(QClipboard::Mode mode = Clipboard) const

Devuelve un puntero a una representación de tipo « QMimeData » de los datos actuales del portapapeles (puede ser de tipo « nullptr » si la plataforma no admite el tipo « mode » especificado).

El argumento mode se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si mode es QClipboard::Clipboard, los datos se recuperan del portapapeles global. Si mode es QClipboard::Selection, los datos se recuperan de la selección global del ratón. Si mode es QClipboard::FindBuffer, los datos se recuperan del búfer de la cadena de búsqueda.

Las funciones text(), image() y pixmap() son envoltorios más sencillos para recuperar datos de texto, imagen y mapa de píxeles.

Nota: El puntero devuelto puede quedar invalidado cuando cambia el contenido del portapapeles; ya sea al llamar a una de las funciones de configuración o de forma externa, al cambiar el portapapeles del sistema.

Véase también setMimeData().

bool QClipboard::ownsClipboard() const

Devuelve ` true ` si este objeto de portapapeles es el propietario de los datos del portapapeles; en caso contrario, devuelve ` false`.

bool QClipboard::ownsFindBuffer() const

Devuelve ` true ` si este objeto del portapapeles es el propietario de los datos del búfer de búsqueda; en caso contrario, devuelve ` false`.

bool QClipboard::ownsSelection() const

Devuelve ` true ` si este objeto del portapapeles contiene los datos de la selección del ratón; en caso contrario, devuelve ` false`.

QPixmap QClipboard::pixmap(QClipboard::Mode mode = Clipboard) const

Devuelve el mapa de píxeles del portapapeles, o «null» si el portapapeles no contiene ningún mapa de píxeles. Ten en cuenta que esto puede provocar la pérdida de información. Por ejemplo, si la imagen es de 24 bits y la pantalla es de 8 bits, el resultado se convierte a 8 bits, y si la imagen tiene un canal alfa, el resultado solo tendrá una máscara.

El argumento ` mode ` se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si ` mode ` es ` QClipboard::Clipboard`, el mapa de píxeles se recupera del portapapeles global. Si ` mode ` es ` QClipboard::Selection`, el mapa de píxeles se recupera de la selección global del ratón.

Véanse también setPixmap(), image(), mimeData() y QPixmap::convertFromImage().

[signal] void QClipboard::selectionChanged()

Esta señal se emite cuando se modifica la selección. Esto solo se aplica a los sistemas de ventanas que admiten selecciones, por ejemplo, X11. Windows y macOS no admiten selecciones.

Véase también dataChanged(), findBufferChanged() y changed().

void QClipboard::setImage(const QImage &image, QClipboard::Mode mode = Clipboard)

Copia el texto « image » en el portapapeles.

El argumento « mode » se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si « mode » es « QClipboard::Clipboard », la imagen se almacena en el portapapeles global. Si « mode » es « QClipboard::Selection », los datos se almacenan en la selección global del ratón.

Esto es una forma abreviada de:

QMimeData *data = new QMimeData;
data->setImageData(image);
clipboard->setMimeData(data, mode);

Véase también image(), setPixmap() y setMimeData().

void QClipboard::setMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)

Establece los datos del portapapeles en ` src`. La propiedad de los datos se transfiere al portapapeles. Si deseas eliminar los datos, llama a ` clear()` o vuelve a llamar a `setMimeData()` con nuevos datos.

El argumento ` mode ` se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si ` mode ` es ` QClipboard::Clipboard`, los datos se almacenan en el portapapeles global. Si ` mode ` es ` QClipboard::Selection`, los datos se almacenan en la selección global del ratón. Si ` mode ` es ` QClipboard::FindBuffer`, los datos se almacenan en el búfer de cadena de búsqueda.

Las funciones setText(), setImage() y setPixmap() son envoltorios más sencillos para establecer datos de texto, imagen y mapa de píxeles, respectivamente.

Véase también mimeData().

void QClipboard::setPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)

Copia pixmap en el portapapeles. Ten en cuenta que esto es más lento que setImage() porque primero tiene que convertir QPixmap a QImage.

El argumento mode se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si mode es QClipboard::Clipboard, el mapa de píxeles se almacena en el portapapeles global. Si mode es QClipboard::Selection, el mapa de píxeles se almacena en la selección global del ratón.

Véase también pixmap(), setImage() y setMimeData().

void QClipboard::setText(const QString &text, QClipboard::Mode mode = Clipboard)

Copia text en el portapapeles como texto sin formato.

El argumento mode se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si mode es QClipboard::Clipboard, el texto se almacena en el portapapeles global. Si mode es QClipboard::Selection, el texto se almacena en la selección global del ratón. Si mode es QClipboard::FindBuffer, el texto se almacena en el búfer de la cadena de búsqueda.

Véase también text() y setMimeData().

bool QClipboard::supportsFindBuffer() const

Devuelve ` true ` si el portapapeles admite un búfer de búsqueda independiente; en caso contrario, devuelve ` false`.

bool QClipboard::supportsSelection() const

Devuelve ` true ` si el portapapeles admite la selección con el ratón; en caso contrario, devuelve ` false`.

QString QClipboard::text(QClipboard::Mode mode = Clipboard) const

Devuelve el texto del portapapeles como texto sin formato, o una cadena vacía si el portapapeles no contiene ningún texto.

El argumento ` mode ` se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si ` mode ` es ` QClipboard::Clipboard`, el texto se recupera del portapapeles global. Si ` mode ` es ` QClipboard::Selection`, el texto se recupera de la selección global del ratón. Si ` mode ` es ` QClipboard::FindBuffer`, el texto se recupera del búfer de la cadena de búsqueda.

Véanse también setText() y mimeData().

QString QClipboard::text(QString &subtype, QClipboard::Mode mode = Clipboard) const

Devuelve el texto del portapapeles en el subtipo « subtype », o una cadena vacía si el portapapeles no contiene ningún texto. Si « subtype » es nulo, se acepta cualquier subtipo, y « subtype » se establece en el subtipo elegido.

El argumento mode se utiliza para controlar qué parte del portapapeles del sistema se utiliza. Si mode es QClipboard::Clipboard, el texto se recupera del portapapeles global. Si mode es QClipboard::Selection, el texto se recupera de la selección global del ratón.

Los valores habituales para subtype son «plain» y «html».

Ten en cuenta que llamar a esta función repetidamente, por ejemplo desde un controlador de eventos de teclas, puede resultar lento. En tales casos, deberías utilizar la señal dataChanged() en su lugar.

Esta es una función sobrecargada.

Véanse también setText() y mimeData().

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