QClipboard 类

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

头：	#include <QClipboard>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui
继承：	QObject

所有成员列表，包括继承成员

公共类型

enum	Mode { Clipboard, Selection, FindBuffer }

公共函数

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

信号

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

详细描述

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

QClipboard 支持相同的数据类型如 QDrag 所做的，且使用类似机制。对于高级剪贴板用法，阅读拖放 .

应用程序中有一个 QClipboard 对象，可访问通过 QGuiApplication::clipboard ().

范例：

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

QClipboard 特征化了一些访问常见数据类型的方便函数： setText () 允许交换 Unicode 文本和 setPixmap () 和 setImage () 允许交换 QPixmap 和 QImage 在应用程序之间。 setMimeData () 函数最具灵活性：它允许添加任何 QMimeData 到剪贴板。这些中的每个都有相应 Getter，如 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 (多用途 Internet 邮件扩展) 类型：text/plain、text/html 及 text/uri-list。

另请参阅 QGuiApplication .

成员类型文档编制

enum QClipboard:: 模式

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

常量	值	描述
`QClipboard::Clipboard`	`0`	指示应该从全局剪贴板，存储和检索数据。
`QClipboard::Selection`	`1`	指示应该从全局鼠标选定，存储和检索数据。支持 `Selection` 仅在具有全局鼠标选定 (如 X11) 的系统中提供。
`QClipboard::FindBuffer`	`2`	指示应该从查找缓冲，存储和检索数据。此模式用于在 macOS 保持搜索字符串。

另请参阅 QClipboard::supportsSelection ().

成员函数文档编制

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

此信号被发射当数据对于给定剪贴板 mode 改变。

另请参阅 dataChanged (), selectionChanged ()，和 findBufferChanged ().

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

清零剪贴板内容。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，此函数清零全局剪贴板内容。若 mode is QClipboard::Selection ，此函数清零全局鼠标选定内容。若 mode is QClipboard::FindBuffer ，此函数清零搜索字符串缓冲。

另请参阅 QClipboard::Mode and supportsSelection ().

`[signal]` void QClipboard:: dataChanged ()

此信号被发射，当剪贴板数据改变时。

在 macOS 和采用 Qt 4.3 或更高版本，由其它应用程序所做的剪贴板改变，仅当应用程序被激活时才检测。

另请参阅 findBufferChanged (), selectionChanged ()，和 changed ().

`[signal]` void QClipboard:: findBufferChanged ()

此信号被发射，当查找缓冲改变时。这仅适用于 macOS。

采用 Qt 4.3 或更高版本，由其它应用程序所做的剪贴板改变，仅当应用程序被激活时才检测。

另请参阅 dataChanged (), selectionChanged ()，和 changed ().

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

返回剪贴板图像，或返回 null 图像若剪贴板不包含图像，或者若它包含不被支持的图像格式的图像。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，图像检索自全局剪贴板。若 mode is QClipboard::Selection ，图像检索自全局鼠标选定。

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

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

返回指针指向 QMimeData 表示为当前剪贴板数据 (可以为 nullptr 若给定 mode 不被平台支持)。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，数据检索自全局剪贴板。若 mode is QClipboard::Selection ，数据检索自全局鼠标选定。若 mode is QClipboard::FindBuffer ，数据检索自搜索字符串缓冲。

The text (), image ()，和 pixmap () 函数是用于检索文本、图像及像素图数据的更简单包装器。

注意： 返回指针可能变为失效，当剪贴板内容改变时；通过调用某一 setter 函数或在外部通过系统剪贴板改变。

另请参阅 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 通道，则结果仅仅拥有遮罩。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，像素图检索自全局剪贴板。若 mode is QClipboard::Selection ，像素图检索自全局鼠标选定。

另请参阅 setPixmap (), image (), mimeData ()，和 QPixmap::convertFromImage ().

`[signal]` void QClipboard:: selectionChanged ()

此信号被发射，当选定改变时。这只适用于支持选定的窗口系统，如 X11。Windows 和 macOS 不支持选定。

另请参阅 dataChanged (), findBufferChanged ()，和 changed ().

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

拷贝 image 到剪贴板。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，图像存储在全局剪贴板中。若 mode is QClipboard::Selection ，数据存储在全局鼠标选定中。

这是简写对于：

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

另请参阅 image (), setPixmap ()，和 setMimeData ().

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

将剪贴板数据设为 src 。将数据的所有权转移给剪贴板。若想要移除数据，调用 clear () 或调用 setMimeData() 再次采用新数据。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，数据存储在全局剪贴板中。若 mode is QClipboard::Selection ，数据存储在全局鼠标选定中。若 mode is QClipboard::FindBuffer ，数据存储在搜索字符串缓冲中。

The setText (), setImage () 和 setPixmap () 函数是分别设置文本、图像及像素图数据的更简单包装器。

另请参阅 mimeData ().

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

拷贝 pixmap 到剪贴板。注意，这更慢相比 setImage () 因为它需要转换 QPixmap 到 QImage 首先。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，像素图存储在全局剪贴板中。若 mode is QClipboard::Selection ，像素图存储在全局鼠标选定中。

另请参阅 pixmap (), setImage ()，和 setMimeData ().

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

拷贝 text 到剪贴板以纯文本形式。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，文本存储在全局剪贴板中。若 mode is QClipboard::Selection ，文本存储在全局鼠标选定中。若 mode is QClipboard::FindBuffer ，文本存储在搜索字符串缓冲中。

另请参阅 text () 和 setMimeData ().

bool QClipboard:: supportsFindBuffer () const

返回 true 若剪贴板支持单独搜索缓冲；否则返回 false .

bool QClipboard:: supportsSelection () const

返回 true 若剪贴板支持鼠标选定；否则返回 false .

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

以纯文本形式返回剪贴板文本，或空字符串若剪贴板未包含任何文本。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，文本检索自全局剪贴板。若 mode is QClipboard::Selection ，文本检索自全局鼠标选定。若 mode is QClipboard::FindBuffer ，文本检索自搜索字符串缓冲。

另请参阅 setText () 和 mimeData ().

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

这是重载函数。

返回剪贴板文本按子类型 subtype ，或空字符串若剪贴板未包含任何文本。若 subtype 为 null，任何子类型都可接受，和 subtype 被设为选取子类型。

The mode 自变量用于控制使用系统剪贴板的哪一部分。若 mode is QClipboard::Clipboard ，文本检索自全局剪贴板。若 mode is QClipboard::Selection ，文本检索自全局鼠标选定。

常见值对于 subtype 为 plain 和 html。

请注意，重复调用此函数 (例如：从键事件处理程序) 可能很慢。在这种情况下，应使用 dataChanged() 信号代替。