Класс QClipboard

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

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

Открытые типы

Открытые функции

Сигналы

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

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

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 ожидает, что файлы будут предоставлены с типом MIME x-special/gnome-copied-files, данные которого начинаются с действия вырезания/копирования, символа новой строки и URL файла.

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

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

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

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

См. также QGuiApplication.

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

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

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

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

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

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

Этот сигнал генерируется, когда данные для заданного режима буфера обмена mode изменяются.

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

[signal] void QClipboard::dataChanged()

Этот сигнал генерируется, когда данные буфера обмена изменяются.

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

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

[signal] void QClipboard::findBufferChanged()

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

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

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

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