QClipboard露
- PyQt5.QtGui.QClipboard
Inherits from QObject.
Description露
The QClipboard class provides access to the window system clipboard.
The clipboard offers a simple mechanism to copy and paste data between applications.
QClipboard supports the same data types that QDrag does, and uses similar mechanisms. For advanced clipboard usage read Drag and Drop.
There is a single QClipboard object in an application, accessible as clipboard().
Example:
# QClipboard *clipboard = QGuiApplication::clipboard();
# QString originalText = clipboard->text();
# ...
# clipboard->setText(newText);
QClipboard features some convenience functions to access common data types: setText() allows the exchange of Unicode text and setPixmap() and setImage() allows the exchange of QPixmaps and QImages between applications. The setMimeData() function is the ultimate in flexibility: it allows you to add any QMimeData into the clipboard. There are corresponding getters for each of these, e.g. text(), image() and pixmap(). You can clear the clipboard by calling clear().
A typical example of the use of these functions follows:
# This code needs porting to Python.
# /****************************************************************************
# **
# ** Copyright (C) 2016 The Qt Company Ltd.
# ** Contact: https://www.qt.io/licensing/
# **
# ** This file is part of the documentation of the Qt Toolkit.
# **
# ** $QT_BEGIN_LICENSE:BSD$
# ** Commercial License Usage
# ** Licensees holding valid commercial Qt licenses may use this file in
# ** accordance with the commercial license agreement provided with the
# ** Software or, alternatively, in accordance with the terms contained in
# ** a written agreement between you and The Qt Company. For licensing terms
# ** and conditions see https://www.qt.io/terms-conditions. For further
# ** information use the contact form at https://www.qt.io/contact-us.
# **
# ** BSD License Usage
# ** Alternatively, you may use this file under the terms of the BSD license
# ** as follows:
# **
# ** "Redistribution and use in source and binary forms, with or without
# ** modification, are permitted provided that the following conditions are
# ** met:
# ** * Redistributions of source code must retain the above copyright
# ** notice, this list of conditions and the following disclaimer.
# ** * Redistributions in binary form must reproduce the above copyright
# ** notice, this list of conditions and the following disclaimer in
# ** the documentation and/or other materials provided with the
# ** distribution.
# ** * Neither the name of The Qt Company Ltd nor the names of its
# ** contributors may be used to endorse or promote products derived
# ** from this software without specific prior written permission.
# **
# **
# ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
# **
# ** $QT_END_LICENSE$
# **
# ****************************************************************************/
# #include <QtGui>
# #include "droparea.h"
# DropArea::DropArea(QWidget *parent)
# : QLabel(parent)
# {
# setMinimumSize(200, 200);
# setFrameStyle(QFrame::Sunken | QFrame::StyledPanel);
# setAlignment(Qt::AlignCenter);
# setAcceptDrops(true);
# setAutoFillBackground(true);
# clear();
# }
# void DropArea::dragEnterEvent(QDragEnterEvent *event)
# {
# setText(tr("<drop content>"));
# setBackgroundRole(QPalette::Highlight);
# event->acceptProposedAction();
# emit changed(event->mimeData());
# }
# void DropArea::dragMoveEvent(QDragMoveEvent *event)
# {
# event->acceptProposedAction();
# }
# void DropArea::dropEvent(QDropEvent *event)
# {
# const QMimeData *mimeData = event->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"));
# }
# setBackgroundRole(QPalette::Dark);
# event->acceptProposedAction();
# }
# //![0]
# 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"));
# }
# //![0]
# emit changed(mimeData);
# setBackgroundRole(QPalette::Dark);
# //event->acceptProposedAction();
# }
# void DropArea::dragLeaveEvent(QDragLeaveEvent *event)
# {
# clear();
# event->accept();
# }
# void DropArea::clear()
# {
# setText(tr("<drop content>"));
# setBackgroundRole(QPalette::Dark);
# emit changed();
# }
# QPixmap DropArea::extractPixmap(const QByteArray &data, const QString &format)
# {
# const QList<QByteArray> imageFormats = QImageReader::supportedImageFormats();
# QPixmap pixmap;
# for (const QByteArray &imageFormat : imageFormats) {
# if (format.mid(6) == QString(imageFormat)) {
# pixmap.loadFromData(data, imageFormat);
# break;
# }
# }
# return pixmap;
# }
Notes for X11 Users露
The X11 Window System has the concept of a separate selection and clipboard. When text is selected, it is immediately available as the global mouse selection. The global mouse selection may later be copied to the clipboard. By convention, the middle mouse button is used to paste the global mouse selection.
X11 also has the concept of ownership; if you change the selection within a window, X11 will only notify the owner and the previous owner of the change, i.e. it will not notify all applications that the selection or clipboard data changed.
Lastly, the X11 clipboard is event driven, i.e. the clipboard will not function properly if the event loop is not running. Similarly, it is recommended that the contents of the clipboard are stored or retrieved in direct response to user-input events, e.g. mouse button or key presses and releases. You should not store or retrieve the clipboard contents in response to timer or non-user-input events.
Since there is no standard way to copy and paste files between applications on X11, various MIME types and conventions are currently in use. For instance, Nautilus expects files to be supplied with a
x-special/gnome-copied-filesMIME type with data beginning with the cut/copy action, a newline character, and the URL of the file.
Notes for macOS Users露
macOS supports a separate find buffer that holds the current search string in Find operations. This find clipboard can be accessed by specifying the FindBuffer mode.
Notes for Windows and macOS Users露
Windows and macOS do not support the global mouse selection; they only supports the global clipboard, i.e. they only add text to the clipboard when an explicit copy or cut is made.
Windows and macOS does not have the concept of ownership; the clipboard is a fully global resource so all applications are notified of changes.
Notes for Universal Windows Platform Users露
The Universal Windows Platform only allows to query the clipboard in case the application is active and an application window has focus. Accessing the clipboard data when in background will fail due to access denial.
See also
Enums露
- Mode
This enum type is used to control which part of the system clipboard is used by mimeData(), setMimeData() and related functions.
See also
Member
Value
Description
Clipboard 0
indicates that data should be stored and retrieved from the global clipboard.
FindBuffer 2
indicates that data should be stored and retrieved from the Find buffer. This mode is used for holding search strings on macOS.
Selection 1
indicates that data should be stored and retrieved from the global mouse selection. Support for
Selectionis provided only on systems with a global mouse selection (e.g. X11).
Methods露
- image(mode: Mode = Clipboard) → QImage
Returns the clipboard image, or returns a null image if the clipboard does not contain an image or if it contains an image in an unsupported image format.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the image is retrieved from the global clipboard. If mode is Selection, the image is retrieved from the global mouse selection.
See also
- ownsClipboard() → bool
Returns
trueif this clipboard object owns the clipboard data; otherwise returnsfalse.
- ownsFindBuffer() → bool
Returns
trueif this clipboard object owns the find buffer data; otherwise returnsfalse.
- ownsSelection() → bool
Returns
trueif this clipboard object owns the mouse selection data; otherwise returnsfalse.
- pixmap(mode: Mode = Clipboard) → QPixmap
Returns the clipboard pixmap, or null if the clipboard does not contain a pixmap. Note that this can lose information. For example, if the image is 24-bit and the display is 8-bit, the result is converted to 8 bits, and if the image has an alpha channel, the result just has a mask.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the pixmap is retrieved from the global clipboard. If mode is Selection, the pixmap is retrieved from the global mouse selection.
See also
- setImage(QImage, mode: Mode = Clipboard)
Copies the image into the clipboard.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the image is stored in the global clipboard. If mode is Selection, the data is stored in the global mouse selection.
This is shorthand for:
# QMimeData *data = new QMimeData; # data->setImageData(image); # clipboard->setMimeData(data, mode);
See also
- setPixmap(QPixmap, mode: Mode = Clipboard)
Copies pixmap into the clipboard. Note that this is slower than setImage() because it needs to convert the QPixmap to a QImage first.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the pixmap is stored in the global clipboard. If mode is Selection, the pixmap is stored in the global mouse selection.
See also
- setText(str, mode: Mode = Clipboard)
Copies text into the clipboard as plain text.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the text is stored in the global clipboard. If mode is Selection, the text is stored in the global mouse selection. If mode is FindBuffer, the text is stored in the search string buffer.
See also
- supportsFindBuffer() → bool
Returns
trueif the clipboard supports a separate search buffer; otherwise returnsfalse.
- supportsSelection() → bool
Returns
trueif the clipboard supports mouse selection; otherwise returnsfalse.
- text(mode: Mode = Clipboard) → str
Returns the clipboard text as plain text, or an empty string if the clipboard does not contain any text.
The mode argument is used to control which part of the system clipboard is used. If mode is Clipboard, the text is retrieved from the global clipboard. If mode is Selection, the text is retrieved from the global mouse selection. If mode is FindBuffer, the text is retrieved from the search string buffer.
See also
