QClipboard Class
La classe QClipboard permet d'accéder au presse-papiers du système de fenêtrage. En savoir plus...
| En-tête : | #include <QClipboard> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
| Hérite de : | QObject |
Types publics
| enum | Mode { Clipboard, Selection, FindBuffer } |
Fonctions publiques
| 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 |
Signaux
| void | changed(QClipboard::Mode mode) |
| void | dataChanged() |
| void | findBufferChanged() |
| void | selectionChanged() |
Description détaillée
Le presse-papiers offre un mécanisme simple pour copier et coller des données entre les applications.
QClipboard prend en charge les mêmes types de données que QDrag et utilise des mécanismes similaires. Pour une utilisation avancée du presse-papiers, consultez la section Glisser-déposer.
Il n’y a qu’un seul objet QClipboard dans une application, accessible via la fonction ` QGuiApplication::clipboard()`.
Exemple :
QClipboard *clipboard = QGuiApplication::clipboard();
QString originalText = clipboard->text();
// etc.
clipboard->setText(newText);QClipboard propose des fonctions pratiques pour accéder aux types de données courants : ` setText()` permet l’échange de texte Unicode, tandis que ` setPixmap()` et ` setImage()` permettent l’échange de QPixmaps et de QImages entre applications. La fonction ` setMimeData()` offre une flexibilité optimale : elle vous permet d’ajouter n’importe quel objet ` QMimeData ` dans le presse-papiers. Il existe des fonctions de récupération correspondantes pour chacune d’entre elles, par exemple text(), image() et pixmap(). Vous pouvez vider le presse-papiers en appelant clear().
Voici un exemple typique d’utilisation de ces fonctions :
void DropArea::paste()
{
const QClipboard *clipboard = QGuiApplication::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"));
}
}Remarques à l’attention des utilisateurs de X11
- Le système de fenêtrage X11 distingue la sélection et le presse-papiers. Lorsqu’un texte est sélectionné, il est immédiatement disponible en tant que sélection globale de la souris. La sélection globale de la souris peut ensuite être copiée dans le presse-papiers. Par convention, le bouton central de la souris sert à coller la sélection globale de la souris.
- X11 repose également sur le concept de « propriété » ; si vous modifiez la sélection au sein d’une fenêtre, X11 n’informera de ce changement que le propriétaire et l’ancien propriétaire, c’est-à-dire qu’il ne signalera pas à toutes les applications que la sélection ou les données du presse-papiers ont changé.
- Enfin, le presse-papiers X11 est piloté par les événements, c'est-à-dire qu'il ne fonctionnera pas correctement si la boucle d'événements n'est pas active. De même, il est recommandé de stocker ou de récupérer le contenu du presse-papiers en réponse directe à des événements liés aux entrées de l'utilisateur, par exemple les pressions et relâchements de boutons de souris ou de touches. Vous ne devez pas enregistrer ni récupérer le contenu du presse-papiers en réponse à des événements de type « timer » ou à des événements non liés à une entrée de l’utilisateur.
- Comme il n’existe pas de méthode standard pour copier et coller des fichiers entre applications sous X11, divers types MIME et conventions sont actuellement utilisés. Par exemple, Nautilus s’attend à ce que les fichiers soient fournis avec un type MIME «
x-special/gnome-copied-files», dont les données commencent par l’action de coupure/copie, un caractère de nouvelle ligne, puis l’URL du fichier.
Remarques à l’attention des utilisateurs de macOS
macOS prend en charge un presse-papiers de recherche distinct qui contient la chaîne de recherche actuelle lors des opérations de recherche. Ce presse-papiers de recherche est accessible en spécifiant le mode FindBuffer.
Remarques à l'attention des utilisateurs de Windows et de macOS
- Windows et macOS ne prennent pas en charge la sélection globale par la souris ; ils ne prennent en charge que le presse-papiers global, c'est-à-dire qu'ils n'ajoutent du texte au presse-papiers que lorsqu'une opération explicite de copie ou de coupure est effectuée.
- Windows et macOS ne connaissent pas le concept de propriété ; le presse-papiers est une ressource entièrement globale, de sorte que toutes les applications sont informées des modifications.
Remarques à l'attention des utilisateurs d'Android
Sur Android, seuls les types MIME suivants sont pris en charge : text/plain, text/html et text/uri-list.
Voir également QGuiApplication.
Documentation sur les types de membres
enum QClipboard::Mode
Ce type d'énumération sert à déterminer quelle partie du presse-papiers système est utilisée par les fonctions ` QClipboard::mimeData()` et ` QClipboard::setMimeData()`, ainsi que par les fonctions associées.
| Constante | Valeur | Description |
|---|---|---|
QClipboard::Clipboard | 0 | indique que les données doivent être stockées et récupérées à partir du presse-papiers global. |
QClipboard::Selection | 1 | indique que les données doivent être enregistrées et récupérées à partir de la sélection globale de la souris. La prise en charge de la fonction ` Selection ` n’est disponible que sur les systèmes disposant d’une sélection globale de la souris (par exemple, X11). |
QClipboard::FindBuffer | 2 | indique que les données doivent être stockées et récupérées à partir du tampon de recherche. Ce mode est utilisé pour conserver les chaînes de recherche sous macOS. |
Voir aussi ` QClipboard::supportsSelection()` ().
Documentation sur les fonctions membres
[signal] void QClipboard::changed(QClipboard::Mode mode)
Ce signal est émis lorsque les données associées à l'mode du presse-papiers indiquée sont modifiées.
Voir également dataChanged(), selectionChanged() et findBufferChanged().
void QClipboard::clear(QClipboard::Mode mode = Clipboard)
Effacer le contenu du presse-papiers.
L'argument ` mode ` permet de contrôler quelle partie du presse-papiers système est utilisée. Si ` mode ` est défini sur ` QClipboard::Clipboard`, cette fonction efface le contenu du presse-papiers global. Si ` mode ` est défini sur ` QClipboard::Selection`, cette fonction efface le contenu de la sélection globale de la souris. Si ` mode ` est défini sur ` QClipboard::FindBuffer`, cette fonction efface le tampon de chaîne de recherche.
Voir également QClipboard::Mode et supportsSelection().
[signal] void QClipboard::dataChanged()
Ce signal est émis lorsque les données du presse-papiers sont modifiées.
Sous macOS et avec la version 4.3 ou supérieure de Qt, les modifications apportées au presse-papiers par d'autres applications ne seront détectées que lorsque l'application est activée.
Voir également findBufferChanged(), selectionChanged() et changed().
[signal] void QClipboard::findBufferChanged()
Ce signal est émis lorsque le tampon de recherche est modifié. Cela ne s'applique qu'à macOS.
À partir de la version 4.3 de Qt, les modifications apportées au presse-papiers par d'autres applications ne seront détectées que lorsque l'application est active.
Voir également dataChanged(), selectionChanged() et changed().
QImage QClipboard::image(QClipboard::Mode mode = Clipboard) const
Renvoie l'image du presse-papiers ou une image nulle si le presse-papiers ne contient pas d'image ou si celle-ci est dans un format non pris en charge.
L'argument ` mode ` permet de contrôler quelle partie du presse-papiers système est utilisée. Si ` mode ` vaut ` QClipboard::Clipboard`, l'image est récupérée à partir du presse-papiers global. Si ` mode ` vaut ` QClipboard::Selection`, l'image est récupérée à partir de la sélection globale de la souris.
Voir également setImage(), pixmap(), mimeData() et QImage::isNull().
const QMimeData *QClipboard::mimeData(QClipboard::Mode mode = Clipboard) const
Renvoie un pointeur vers une représentation de type « QMimeData » des données actuelles du presse-papiers (peut être de type « nullptr » si le format « mode » spécifié n'est pas pris en charge par la plateforme).
L’argument mode permet de contrôler quelle partie du presse-papiers système est utilisée. Si mode est QClipboard::Clipboard, les données sont extraites du presse-papiers global. Si mode est QClipboard::Selection, les données sont extraites de la sélection globale de la souris. Si mode est QClipboard::FindBuffer, les données sont extraites du tampon de chaîne de recherche.
Les fonctions ` text()`, ` image()` et ` pixmap()` sont des wrappers plus simples permettant de récupérer des données de type texte, image et pixmap.
Remarque : le pointeur renvoyé peut devenir invalide lorsque le contenu du presse-papiers change, soit à la suite de l’appel d’une des fonctions de définition, soit de manière externe en raison d’une modification du presse-papiers système.
Voir également setMimeData().
bool QClipboard::ownsClipboard() const
Renvoie ` true ` si cet objet « presse-papiers » contient les données du presse-papiers ; sinon, renvoie ` false`.
bool QClipboard::ownsFindBuffer() const
Renvoie ` true ` si cet objet « presse-papiers » détient les données du tampon de recherche ; sinon, renvoie ` false`.
bool QClipboard::ownsSelection() const
Renvoie « true » si cet objet presse-papiers contient les données de sélection de la souris ; sinon, renvoie « false ».
QPixmap QClipboard::pixmap(QClipboard::Mode mode = Clipboard) const
Renvoie le pixmap du presse-papiers, ou null si celui-ci ne contient pas de pixmap. Notez que cette opération peut entraîner une perte d'informations. Par exemple, si l'image est en 24 bits et que l'affichage est en 8 bits, le résultat est converti en 8 bits ; de même, si l'image comporte un canal alpha, le résultat ne comporte qu'un masque.
L’argument ` mode ` sert à contrôler quelle partie du presse-papiers système est utilisée. Si ` mode ` est défini sur ` QClipboard::Clipboard`, l’image est récupérée à partir du presse-papiers global. Si ` mode ` est défini sur ` QClipboard::Selection`, l’image est récupérée à partir de la sélection globale de la souris.
Voir également setPixmap(), image(), mimeData() et QPixmap::convertFromImage().
[signal] void QClipboard::selectionChanged()
Ce signal est émis lorsque la sélection est modifiée. Cela ne s'applique qu'aux systèmes de fenêtrage prenant en charge les sélections, par exemple X11. Windows et macOS ne prennent pas en charge les sélections.
Voir également dataChanged(), findBufferChanged() et changed().
void QClipboard::setImage(const QImage &image, QClipboard::Mode mode = Clipboard)
Copie l'image dans le presse-papiers.
L'argument « mode » permet de contrôler quelle partie du presse-papiers système est utilisée. Si « mode » est défini sur « QClipboard::Clipboard », l'image est stockée dans le presse-papiers global. Si « mode » est défini sur « QClipboard::Selection », les données sont stockées dans la sélection globale de la souris.
Il s'agit d'une forme abrégée de :
Voir également image(), setPixmap() et setMimeData().
void QClipboard::setMimeData(QMimeData *src, QClipboard::Mode mode = Clipboard)
Définit les données du presse-papiers sur src. La propriété des données est transférée au presse-papiers. Si vous souhaitez supprimer ces données, appelez soit la fonction clear(), soit la fonction setMimeData() à nouveau avec de nouvelles données.
L’argument ` mode ` permet de contrôler quelle partie du presse-papiers système est utilisée. Si ` mode ` vaut ` QClipboard::Clipboard`, les données sont stockées dans le presse-papiers global. Si ` mode ` vaut ` QClipboard::Selection`, les données sont stockées dans la sélection globale de la souris. Si ` mode ` vaut ` QClipboard::FindBuffer`, les données sont stockées dans le tampon de chaîne de recherche.
Les fonctions setText(), setImage() et setPixmap() sont des wrappers plus simples permettant respectivement de définir des données de texte, d’image et de pixmap.
Voir également mimeData().
void QClipboard::setPixmap(const QPixmap &pixmap, QClipboard::Mode mode = Clipboard)
Copie pixmap dans le presse-papiers. Notez que cette opération est plus lente que setImage() car elle nécessite de convertir au préalable QPixmap en QImage.
L’argument mode permet de contrôler quelle partie du presse-papiers système est utilisée. Si mode est QClipboard::Clipboard, le pixmap est stocké dans le presse-papiers global. Si mode est QClipboard::Selection, le pixmap est stocké dans la sélection globale de la souris.
Voir également pixmap(), setImage() et setMimeData().
void QClipboard::setText(const QString &text, QClipboard::Mode mode = Clipboard)
Copie text dans le presse-papiers sous forme de texte brut.
L'argument mode permet de contrôler quelle partie du presse-papiers système est utilisée. Si mode vaut QClipboard::Clipboard, le texte est stocké dans le presse-papiers global. Si mode vaut QClipboard::Selection, le texte est stocké dans la sélection globale de la souris. Si mode vaut QClipboard::FindBuffer, le texte est stocké dans le tampon de chaîne de recherche.
Voir également text() et setMimeData().
bool QClipboard::supportsFindBuffer() const
Renvoie « true » si le presse-papiers prend en charge un tampon de recherche distinct ; sinon, renvoie « false ».
bool QClipboard::supportsSelection() const
Renvoie « true » si le presse-papiers prend en charge la sélection à la souris ; sinon, renvoie « false ».
QString QClipboard::text(QClipboard::Mode mode = Clipboard) const
Renvoie le contenu du presse-papiers sous forme de texte brut, ou une chaîne vide si le presse-papiers ne contient aucun texte.
L'argument mode permet de contrôler quelle partie du presse-papiers système est utilisée. Si mode vaut QClipboard::Clipboard, le texte est récupéré depuis le presse-papiers global. Si mode vaut QClipboard::Selection, le texte est récupéré depuis la sélection globale de la souris. Si mode vaut QClipboard::FindBuffer, le texte est récupéré depuis le tampon de chaîne de recherche.
Voir également setText() et mimeData().
QString QClipboard::text(QString &subtype, QClipboard::Mode mode = Clipboard) const
Renvoie le texte du presse-papiers au format « subtype », ou une chaîne vide si le presse-papiers ne contient aucun texte. Si « subtype » est nul, n’importe quel sous-type est accepté, et « subtype » est défini sur le sous-type choisi.
L'argument ` mode ` permet de contrôler quelle partie du presse-papiers système est utilisée. Si ` mode ` vaut ` QClipboard::Clipboard`, le texte est récupéré depuis le presse-papiers global. Si ` mode ` vaut ` QClipboard::Selection`, le texte est récupéré depuis la sélection globale de la souris.
Les valeurs courantes de subtype sont « plain » et « html ».
Notez que l’appel répété de cette fonction, par exemple depuis un gestionnaire d’événements de touche, peut s’avérer lent. Dans ce cas, il est préférable d’utiliser le signal dataChanged() à la place.
Il s’agit d’une fonction surchargée.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
