Класс QClipboard

Класс QClipboard предоставляет доступ к буферу обмена операционной системы. Подробнее...

• Список всех членов, включая унаследованные

Типы публичного доступа

Функции публичного доступа

Сигналы

Подробное описание

Буфер обмена предоставляет простой механизм копирования и вставки данных между приложениями.

QClipboard поддерживает те же типы данных, что и QDrag, и использует аналогичные механизмы. Для расширенной работы с буфером обмена см. Перетаскивание и сброс.

В приложении существует единственный объект QClipboard, доступный как QGuiApplication::clipboard().

Пример:

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

QClipboard имеет несколько удобных функций для доступа к распространённым типам данных: setText() позволяет обмениваться текстом Юникод, а 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 ожидает, что файлы будут предоставляться с типом MIME x-special/gnome-copied-files с данными, начинающимися с действия вырезания/копирования, символом новой строки и URL файла.

Примечания для пользователей macOS

macOS поддерживает отдельный буфер поиска, который содержит текущую строку поиска в операциях поиска. К этому буферу поиска можно получить доступ, указав режим FindBuffer.

Примечания для пользователей Windows и macOS

• Windows и macOS не поддерживают глобальное выделение мыши; они поддерживают только глобальный буфер обмена, т.е. они добавляют текст в буфер обмена только при явном копировании или вырезании.
• Windows и macOS не имеют понятия владения; буфер обмена является полностью глобальным ресурсом, поэтому все приложения уведомляются об изменениях.

Примечания для пользователей Universal Windows Platform

• Universal Windows Platform позволяет запросить буфер обмена только в том случае, если приложение активно и окно приложения имеет фокус. Доступ к данным буфера обмена в фоновом режиме завершится отказом из-за запрета доступа.

См. также QGuiApplication.

Документация по типам членов

Перечисление QClipboard::Mode

Этот тип перечисления используется для управления той частью буфера обмена системы, которая используется функциями QClipboard::mimeData(), QClipboard::setMimeData() и другими связанными функциями.

См. также QClipboard::supportsSelection().

Документация по функциям-членам

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

Этот сигнал излучается при изменении данных для данного режима буфера обмена mode.

Функция была добавлена в Qt 4.2.

См. также dataChanged(), selectionChanged() и findBufferChanged().

[signal] void QClipboard::dataChanged()

Этот сигнал излучается при изменении данных буфера обмена.

В macOS и с Qt версии 4.3 или выше изменения буфера обмена, сделанные другими приложениями, будут обнаружены только при активации приложения.

См. также findBufferChanged(), selectionChanged() и changed().

[signal] void QClipboard::findBufferChanged()

Этот сигнал излучается при изменении буфера поиска. Это относится только к macOS.

С Qt версии 4.3 или выше изменения буфера обмена, сделанные другими приложениями, будут обнаружены только при активации приложения.

Функция была добавлена в Qt 4.2.

См. также dataChanged(), selectionChanged() и changed().

[signal] void QClipboard::selectionChanged()

Этот сигнал испускается, когда изменяется выделение. Это относится только к системам окон, которые поддерживают выделение, например, X11. Windows и macOS не поддерживают выделение.

См. также dataChanged(), findBufferChanged() и changed().

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

Очищает содержимое буфера обмена.

Аргумент mode используется для управления тем, какая часть системного буфера обмена используется. Если mode равен QClipboard::Clipboard, эта функция очищает содержимое глобального буфера обмена. Если mode равен QClipboard::Selection, эта функция очищает содержимое глобального выделения мышью. Если mode равен QClipboard::FindBuffer, эта функция очищает буфер строки поиска.

См. также QClipboard::Mode и supportsSelection().

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 текущих данных буфера обмена (может быть nullptr , если заданный mode не поддерживается платформой).

Аргумент 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.

Эта функция была добавлена в Qt 4.2.

bool QClipboard::ownsSelection() const

Возвращает true , если этот объект буфера обмена владеет данными выделения мышью; в противном случае возвращает false.

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

Возвращает растровое изображение из буфера обмена или null, если буфер обмена не содержит растрового изображения. Обратите внимание, что это может привести к потере информации. Например, если изображение 24-битовое, а дисплей 8-битовый, результат преобразуется в 8 бит, и если изображение имеет альфа-канал, результат имеет только маску.

Аргумент mode используется для управления тем, какая часть системного буфера обмена используется. Если mode равен QClipboard::Clipboard, растровое изображение извлекается из глобального буфера обмена. Если mode равен QClipboard::Selection, растровое изображение извлекается из глобального выделения мышью.

См. также setPixmap(), image(), mimeData() и QPixmap::convertFromImage().

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);

См. также image(), 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, растровое изображение сохраняется в глобальном буфере обмена. Если mode равен QClipboard::Selection, растровое изображение сохраняется в глобальном выделении мышью.

См. также 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

Возвращает текст из буфера обмена как обычный текст или пустую строку, если в буфере обмена нет текста.

Аргумент mode используется для управления тем, какая часть системного буфера обмена используется. Если mode равен QClipboard::Clipboard, текст извлекается из глобального буфера обмена. Если mode равен QClipboard::Selection, текст извлекается из глобального выделения мышью. Если mode равен QClipboard::FindBuffer, текст извлекается из буфера строки поиска.

См. также setText() и mimeData().

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

Это перегруженная функция.

Возвращает текст буфера обмена в типе subtype, или пустую строку, если буфер обмена не содержит текста. Если subtype равно null, любой тип допустим, и subtype устанавливается на выбранный тип.

Аргумент mode используется для управления частью системного буфера обмена, используемой. Если mode равен QClipboard::Clipboard, текст извлекается из глобального буфера обмена. Если mode равен QClipboard::Selection, текст извлекается из глобального выделения мышью.

Общие значения для subtype — "plain" и "html".

Обратите внимание, что многократный вызов этой функции, например, из обработчика событий нажатия клавиши, может быть медленным. В таких случаях вы должны использовать сигнал dataChanged() вместо этого.

См. также setText() и mimeData().