Класс QClipboard

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

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

Типы

Общедоступные функции

• 32 общедоступные функции, унаследованные от QObject

Сигналы

• 2 сигнала, унаследованные от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 общедоступный слот, унаследованный от QObject
• 11 статических общедоступных членов, унаследованных от QObject
• 9 защищённых функций, унаследованных от QObject

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

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

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

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

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

Пример:

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

Класс QClipboard содержит некоторые удобные функции для доступа к общим типам данных: setText() позволяет обмениваться текстом Unicode, а setPixmap() и setImage() позволяют обмениваться объектами QPixmap и QImage между приложениями. Функция 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().

void QClipboard::clear(Mode mode = Clipboard)

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

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

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

[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().

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

Возвращает изображение из буфера обмена или возвращает пустое изображение, если буфер обмена не содержит изображение или содержит изображение в неподдерживаемом формате.

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

См. также setImage(), pixmap(), mimeData() и QImage::isNull().

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

Возвращает указатель на объект QMimeData, представляющий текущие данные буфера обмена (может быть NULL, если данное 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(Mode mode = Clipboard) const

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

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

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

[signal] void QClipboard::selectionChanged()

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

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

void QClipboard::setImage(const QImage &image, 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, 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, Mode mode = Clipboard)

Копирует pixmap в буфер обмена. Обратите внимание, что это медленнее, чем setImage(), потому что ему необходимо сначала преобразовать QPixmap в QImage.

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

См. также pixmap(), setImage() и setMimeData().

void QClipboard::setText(const QString &text, 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(Mode mode = Clipboard) const

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

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

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

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

Это перегруженный метод.

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

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

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

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

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