QClipboard 类

QClipboard 类提供了对窗口系统剪贴板的访问。 更多...

头文件 #include <QClipboard>
CMakefind_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmakeQT += gui
继承自 QObject

公共类型

枚举Mode { Clipboard, Selection, FindBuffer }

公共函数

voidclear(QClipboard::Mode mode = Clipboard)
QImageimage(QClipboard::Mode mode = Clipboard) const
const QMimeData *mimeData(QClipboard::Mode mode = Clipboard) const
boolownsClipboard() const
boolownsFindBuffer() const
boolownsSelection() const
QPixmappixmap(QClipboard::Mode mode = Clipboard) const
voidsetImage(const QImage &image, QClipboard::Mode mode = Clipboard)
voidsetMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)
voidsetPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)
voidsetText(const QString &text, QClipboard::Mode mode = Clipboard)
boolsupportsFindBuffer() const
boolsupportsSelection() const
QStringtext(QClipboard::Mode mode = Clipboard) const
QStringtext(QString &subtype, QClipboard::Mode mode = Clipboard) const

信号

voidchanged(QClipboard::Mode mode)
void数据改变()
void查找缓冲区改变()
void选择改变()

详细描述

剪贴板提供了在应用程序之间复制和粘贴数据的简单机制。

QClipboard 支持与 QDrag 相同的数据类型，并使用类似的机制。对于高级剪贴板使用，请参阅 拖放。

应用中有一个单一的 QClipboard 对象，可以通过 QGuiApplication::clipboard 访问。

示例

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

QClipboard 包含一些方便的函数来访问常见的数据类型：setText() 允许交换 Unicode 文本和 setPixmap() 以及 setImage() 允许应用程序之间交换 QPixmaps 和 QImages。函数 setMimeData() 是最灵活的：允许您将任何 QMimeData 添加到剪贴板中。对应这些的获取器有，例如 text()、image() 以及 pixmap()。您可以通过调用 clear() 清除剪贴板。

以下是一个使用这些函数的典型示例

void DropArea::paste()
{
    const QClipboard *clipboard = QApplication::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"));
    }
}

针对 X11 用户注意事项

  • 在 X11 窗口系统中，存在独立的选定内容和剪贴板的概念。当文本被选中时，它立即作为全局鼠标选定内容可用。全局鼠标选定内容随后可以被复制到剪贴板。根据惯例，中键鼠标按钮用于粘贴全局鼠标选定内容。
  • X11 还有一个所有权的概念；如果您在窗口中更改选定内容，X11 将仅通知所有者以及先前的所有者更改，即不会通知所有应用程序选定内容或剪贴板数据已更改。
  • 最后，X11 剪贴板是事件驱动的，即如果事件循环没有运行，剪贴板无法正常工作。同样，建议在直接对用户输入事件（如鼠标按钮或按键的按下和释放）做出响应的情况下存储或检索剪贴板的内容。您不应在定时器或非用户输入事件的情况下存储或检索剪贴板的内容。
  • 由于 X11 软件没有标准方法在不同应用程序之间复制和粘贴文件，因此目前正在使用各种 MIME 类型和方法。例如，Nautilus 预期文件应以 x-special/gnome-copied-files MIME 类型提供，数据以剪切/复制操作开始，一个换行符，以及文件的 URL。

针对 macOS 用户注意事项

macOS 支持一个单独的查找缓冲区，用于在查找操作中存储当前搜索字符串。可以通过指定 FindBuffer 模式来访问此查找剪贴板。

针对 Windows 和 macOS 用户注意事项

  • Windows 和 macOS 不支持全局鼠标选定内容；它们仅支持全局剪贴板，即仅在执行显式复制或剪切时向剪贴板添加文本。
  • Windows 和 macOS 没有所有权的概念；剪贴板是一个完全全球的资源，因此所有应用程序都会收到更改的通知。

针对 Android 用户注意事项

在 Android 上，仅支持以下这些 MIME 类型：text/plain、text/html 和 text/uri-list。

另请参阅 QGuiApplication。

成员类型文档

枚举 QClipboard::Mode

此枚举类型用于控制 QClipboard::mimeData()、QClipboard::setMimeData() 和相关函数使用的系统剪贴板的哪一部分。

常量值描述
QClipboard::Clipboard0表示数据应从全局剪贴板存储和检索。
QClipboard::Selection1表示数据应从全局鼠标选定内容存储和检索。仅在具有全局鼠标选定内容的系统（例如 X11）上提供 Selection 支持。
QClipboard::FindBuffer2表示数据应从查找缓冲区存储和检索。此模式用于在 macOS 上存储搜索字符串。

另请参阅 QClipboard::supportsSelection。

成员函数文档

[信号] void QClipboard::changed(QClipboard::Mode mode)

当指定剪贴板 mode 的数据发生变化时，会发出此信号。

另请参阅dataChanged()，selectionChanged()和findBufferChanged()。

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

清除剪贴板内容。

mode 参数用于控制使用系统剪贴版的哪个部分。如果 mode 是 QClipboard::Clipboard，此函数清除全局剪贴板内容。如果 mode 是 QClipboard::Selection，此函数清除全局鼠标选择内容。如果 mode 是 QClipboard::FindBuffer，此函数清除搜索字符串缓冲区。

另请参阅QClipboard::Mode 和 supportsSelection。

[信号] void QClipboard::dataChanged()

当剪贴板数据发生变化时，会发出此信号。

在 macOS 上以及使用 4.3 或更高版本的 Qt 时，只有当应用程序被激活时，其他应用程序更改剪贴板才会被检测到。

另请参阅findBufferChanged()，selectionChanged() 和 changed()。

[信号] void QClipboard::findBufferChanged()

当查找缓冲区发生变化时，会发出此信号。此功能仅适用于 macOS。

使用 4.3 或更高版本的 Qt 时，只有当应用程序被激活时，其他应用程序更改剪贴板才会被检测到。

另请参阅dataChanged()，selectionChanged() 和 changed()。

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

返回剪贴板图像，或者如果剪贴板不包含图像或包含不支持的图像格式，则返回空图像。

mode 参数用于控制使用系统剪贴版的哪个部分。如果 mode 是 QClipboard::Clipboard，则从全局剪贴板检索图像。如果 mode 是 QClipboard::Selection，则从全局鼠标选择中检索图像。

另请参阅setImage()，pixmap()，mimeData() 和 QImage::isNull()。

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

返回指向当前剪贴板数据 QMimeData 表示的指针（如果给定的 mode 不受平台支持，则可以是 nullptr）。

模式（mode）参数用于控制使用系统剪贴板的哪个部分。如果模式（mode）是QClipboard::Clipboard，则从全局剪贴板检索数据。如果模式（mode）是QClipboard::Selection，则从全局鼠标选择中检索数据。如果模式（mode）是QClipboard::FindBuffer，则从搜索字符串缓冲区中检索数据。

text()、image()和pixmap()函数是用来获取文本、图像和像素数据的简单包装器。

注意：当剪贴板的内容改变时，返回的指针可能会失效；无论是通过调用设置函数，还是通过系统剪贴板的更改。

另请参阅：setMimeData。

bool QClipboard::ownsClipboard() const

如果此剪贴板对象拥有剪贴板数据，则返回true；否则返回false。

bool QClipboard::ownsFindBuffer() const

如果此剪贴板对象拥有查找缓冲区数据，则返回true；否则返回false。

bool QClipboard::ownsSelection() const

如果此剪贴板对象拥有鼠标选择数据，则返回true；否则返回false。

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

返回剪贴板像素图，如果没有像素图，则返回null。请注意，这可能会丢失信息。例如，如果图像是24位，而显示是8位，结果将转换为8位，如果图像有alpha通道，则结果仅有遮罩。

模式（mode）参数用于控制使用系统剪贴板的哪个部分。如果模式（mode）是QClipboard::Clipboard，则从全局剪贴板检索像素图。如果模式（mode）是QClipboard::Selection，则从全局鼠标选择中检索像素图。

另请参阅：setPixmap、image、mimeData和QPixmap::convertFromImage。

[信号] void QClipboard::selectionChanged()

当选择发生改变时发出此信号。这仅适用于支持选择的窗口系统，例如X11。Windows和macOS不支持选择。

另请参阅：dataChanged、findBufferChanged和changed。

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

将图像image复制到剪贴板。

模式（mode）参数用于控制使用系统剪贴板的哪个部分。如果模式（mode）是QClipboard::Clipboard，则将图像存储在全局剪贴板中。如果模式（mode）是QClipboard::Selection，则数据存储在全局鼠标选择中。

这是简写形式

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

另见图像()，setPixmap()，以及setMimeData()。

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

将剪贴板数据设置为src。数据的所有权将转移到剪贴板。如果您想删除数据，可以调用clear()或再次使用新数据调用setMimeData()。

mode参数用于控制使用系统剪贴板的哪一部分。如果mode为QClipboard::Clipboard，则数据存储在全局剪贴板中。如果mode为QClipboard::Selection，则数据存储在全局鼠标选择中。如果mode为QClipboard::FindBuffer，则数据存储在搜索字符串缓冲区中。

setText()，setImage()和setPixmap()函数是分别用于设置文本、图像和位图数据的简单封装。

另见mimeData()。

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

将pixmap复制到剪贴板。请注意，这比setImage()慢，因为它需要首先将QPixmap转换为QImage。

mode参数用于控制使用系统剪贴板的哪一部分。如果mode为QClipboard::Clipboard，则 pixmap 存储在全局剪贴板中。如果mode为QClipboard::Selection，则 pixmap 存储在全局鼠标选择中。

另见pixmap()，setImage()和setMimeData()。

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

将text作为纯文本复制到剪贴板。

mode参数用于控制使用系统剪贴板的哪一部分。如果mode为QClipboard::Clipboard，则文本存储在全局剪贴板中。如果mode为QClipboard::Selection，则文本存储在全局鼠标选择中。如果mode为QClipboard::FindBuffer，则文本存储在搜索字符串缓冲区中。

另见text()和setMimeData()。

bool QClipboard::supportsFindBuffer() const

如果剪贴板支持单独的搜索缓冲区，则返回true；否则返回false。

bool QClipboard::supportsSelection() const

如果剪贴板支持鼠标选择，则返回true；否则返回false。

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

以纯文本形式返回剪贴板文本，如果剪贴板不包含任何文本，则返回空字符串。

模式 参数用于控制使用系统剪贴板的哪一部分。如果 模式 是 QClipboard::Clipboard，则从全局剪贴板中检索文本。如果 模式 是 QClipboard::Selection，则从全局鼠标选择中检索文本。如果 模式 是 QClipboard::FindBuffer，则从搜索字符串缓冲区中检索文本。

另请参阅 setText() 和 mimeData。

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

这是重载函数。

以子类型 subtype 返回剪贴板文本，如果剪贴板不包含任何文本，则返回空字符串。如果 subtype 为空，则接受任何子类型，并将 subtype 设置为所选子类型。

模式 参数用于控制使用系统剪贴板的哪一部分。如果 模式 是 QClipboard::Clipboard，则从全局剪贴板中检索文本。如果 模式 是 QClipboard::Selection，则从全局鼠标选择中检索文本。

subtype 的常见值有 "plain" 和 "html"。

请注意，频繁调用此函数，例如从键事件处理器中调用，可能较慢。在这种情况下，您应使用 dataChanged() 信号。

另请参阅 setText() 和 mimeData。

© 2024 The Qt Company Ltd. 本文档中的内容贡献版权属于其各自的所有者。本提供的文档根据由自由软件基金会发布的 GNU自由文档许可证版本1.3 的条款进行许可。Qt及其相应的标志是芬兰的 The Qt Company Ltd. 以及全球其他国家和地区的 商标。所有其他商标均为其各自所有者的财产。