Back to Qt.io
Contact Us Blog Download Qt
En esta página

QClipboard Class

La clase QClipboard proporciona acceso al portapapeles del sistema de ventanas. Más...

Cabecera: #include <QClipboard>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Hereda: 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 simple para copiar y pegar datos entre aplicaciones.

QClipboard soporta los mismos tipos de datos que QDrag, y utiliza mecanismos similares. Para un uso avanzado del portapapeles lea Arrastrar y Soltar.

Hay un único objeto QClipboard en una aplicación, accesible como QGuiApplication::clipboard().

Ejemplo:

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

QClipboard presenta algunas funciones de conveniencia para acceder a tipos de datos comunes: setText() permite el intercambio de texto Unicode y 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. Para cada una de ellas existen los correspondientes getters, por ejemplo text(), image() y pixmap(). Puede borrar 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 tiene el concepto de selección y portapapeles separados. Cuando se selecciona un texto, éste queda inmediatamente disponible como selección global del ratón. La selección global del ratón puede copiarse posteriormente en el 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 tiene el concepto de propiedad; si cambias la selección dentro de una ventana, X11 sólo 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 está controlado por eventos, es decir, el portapapeles no funcionará correctamente si no se está ejecutando el bucle de eventos. Del mismo modo, se recomienda que el contenido del portapapeles se almacene o recupere en respuesta directa a eventos de entrada del usuario, por ejemplo, pulsaciones y liberaciones de botones o teclas del ratón. No se debe almacenar o recuperar el contenido del portapapeles en respuesta a eventos de temporizador o eventos 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 varios tipos y convenciones MIME. Por ejemplo, Nautilus espera que los archivos se suministren con un tipo MIME x-special/gnome-copied-files con datos que comiencen con 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 contiene 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

  • Windows y macOS no admiten la selección global del ratón; sólo admiten el portapapeles global, es decir, sólo añaden texto al portapapeles cuando se realiza una copia o un corte explícitos.
  • Windows y macOS no tienen el concepto de propiedad; el portapapeles es un recurso totalmente global por lo que todas las aplicaciones son notificadas de los cambios.

Notas para usuarios de Android

En Android sólo se admiten estos tipos mime: text/plain, text/html y text/uri-list.

Véase también QGuiApplication.

Documentación de tipos de miembros

enum QClipboard::Mode

Este tipo enum se utiliza para controlar qué parte del portapapeles del sistema es utilizada por QClipboard::mimeData(), QClipboard::setMimeData() y funciones relacionadas.

ConstanteValorDescripción
QClipboard::Clipboard0indica que los datos deben ser almacenados y recuperados del portapapeles global.
QClipboard::Selection1indica que los datos deben almacenarse y recuperarse de la selección global del ratón. El soporte para Selection sólo se proporciona en sistemas con una selección de ratón global (por ejemplo, X11).
QClipboard::FindBuffer2indica que los datos deben almacenarse y recuperarse del búfer de búsqueda. Este modo se utiliza para mantener cadenas de búsqueda en macOS.

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

Documentación de las funciones miembro

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

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

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

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

Borra 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 global del portapapeles. Si mode es QClipboard::Selection, esta función borra el contenido global de la selección 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 Qt versión 4.3 o superior, los cambios en el portapapeles realizados por otras aplicaciones sólo se detectarán cuando la aplicación esté activada.

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

[signal] void QClipboard::findBufferChanged()

Esta señal se emite cuando se cambia el búfer de búsqueda. Esto sólo se aplica a macOS.

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

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

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

Devuelve la imagen del portapapeles, o devuelve una imagen nula si el portapapeles no contiene ninguna imagen o si contiene una imagen en un formato de imagen no admitido.

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 obtiene 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 QMimeData de los datos actuales del portapapeles (puede ser nullptr si la plataforma no admite mode ).

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 obtienen de la selección global del ratón. Si mode es QClipboard::FindBuffer, los datos se obtienen del búfer de cadenas de búsqueda.

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

Nota: El puntero devuelto puede invalidarse cuando cambia el contenido del portapapeles; ya sea llamando a una de las funciones setter o externamente por el cambio del portapapeles del sistema.

Véase también setMimeData().

bool QClipboard::ownsClipboard() const

Devuelve true si este objeto portapapeles posee los datos del portapapeles; en caso contrario devuelve false.

bool QClipboard::ownsFindBuffer() const

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

bool QClipboard::ownsSelection() const

Devuelve true si este objeto portapapeles posee los datos de 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 un mapa de píxeles. Tenga en cuenta que se puede perder 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 sólo tiene 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 obtiene de la selección global del ratón.

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

[signal] void QClipboard::selectionChanged()

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

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

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

Copia la dirección 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.

Esta es la abreviatura 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 desea eliminar los datos, llame a clear() o vuelva 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 cadenas de búsqueda.

Las funciones setText(), setImage() y setPixmap() son envoltorios más simples para establecer datos de texto, imagen y pixmap respectivamente.

Véase también mimeData().

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

Copia pixmap en el portapapeles. Tenga en cuenta que esto es más lento que setImage() porque necesita convertir primero el QPixmap en un 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 cadenas 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 obtiene del portapapeles global. Si mode es QClipboard::Selection, el texto se obtiene de la selección global del ratón. Si mode es QClipboard::FindBuffer, el texto se obtiene del búfer de cadenas de búsqueda.

Véase 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 obtiene de la selección global del ratón.

Los valores más comunes para subtype son "plain" y "html".

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

Se trata de una función sobrecargada.

Véase 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.