| Table des matières du kit d'application | Index du kit d'application |
Hérité de : aucun
Déclaré dans : be/app/Clipboard.h
Bibliothèque : libbe.so
Allocation: Constructeur
Un objet BClipboard est une interface pour le presse-papier (clipboard), la ressource qui fournit un stockage de données temporaire, pour tout le système. Les presse-papiers sont identifiés par un nom ; si deux applications souhaitent faire référence au même presse-papier, elles créent simplement leurs objets BClipboard respectifs avec le même nom :
/* Application A: crée un presse-papier nommé "MonClipboard". */
BClipboard *appAclipboard = new BClipboard("MonClipboard");
/* Application B:
cet objet fait référence au presse-papier MonClipboard déjà crée par l'application A. */
BClipboard *appBclipboard = new BClipboard("MonClipboard");
En pratique, vous avez rarement besoin de construire votre propre objet BClipboard ; à la place, vous utilisez le BClipboard crée pour vous par votre objet BApplication. Cet objet, référencé via la variable globale be_clipboard, accède au presse-papier système par défaut. Les données écrites par votre objet be_clipboard peuvent être lues par n'importe quel be_clipboard des autres applications. Par exemple, les opérations couper/copier/coller définies par BTextView échangent des données au travers du presse-papier système.
|
Pour accéder aux données d'un presse-papier, vous appelez des fonctions manipulant le BMessage que l'objet BClipboard vous communique (via sa fonction Data()). Le BMessage respecte les conventions suivantes :
L'exemple annoté suivant montre comment écrire dans le presse-papier.
BMessage *clip = (BMessage *)NULL;
if (be_clipboard->Lock()1) {
be_clipboard->Clear()2;
if ((clip = be_clipboard->Data()3) {
clip->AddData("text/MyFormat", B_MIME_TYPE, myText, myLength)4;
clip->AddData("text/plain", B_MIME_TYPE, asciiText, asciiLength)4;
be_clipboard->Commit()5;
}
be_clipboard->Unlock()6;
}
1 Lock() verrouille votre objet BClipboard. Ce qui charge les données du presse-papier dans l'objet local BMessage de votre BClipboard, et empêche les autres threads de votre application d'accéder aux données du BClipboard. Notez que le verrouillage ne verrouille pas les données sous-jacentes du presse-papier — d'autres applications peuvent modifier le presse-papier pendant que votre objet est verrouillé.
2 Prépare BClipboard à l'écriture en appelant Clear(). Ce qui détruit les données récupérées du presse-papier.
3 Appelle Data() pour obtenir un pointeur sur l'objet BMessage du BClipboard.
4 Ecrit les données en invoquant AddData() directement sur le BMessage. Dans cet exemple, on écrit les données suivant deux formats différents.
5 Appelle Commit() pour copier votre BMessage dans le presse-papier. Dès que vous appelez Commit(), les données ajoutées sont visibles aux autres clients du presse-papier.
6 Unlock() est symétrique à Lock(). L'objet BClipboard est maintenant accessible aux autres threads de votre application.
Si vous décidez de ne pas valider vos modifications, vous devez appeler Revert() avant de déverrouiller.
On montre ici comment lire une simple chaîne à partir du presse-papier.
const char *text;
int32 textLen;
BMessage *clip = (BMessage *)NULL;
if (be_clipboard->Lock()1) {
if ((clip = be_clipboard->Data();
clip->FindData("text/plain", B_MIME_TYPE,
(const void **)&text, &textlen)2;
be_clipboard->Unlock()3;
}
1 Comme pour l'écriture, on encadre l'opération par Lock() et Unlock(). Gardez à l'esprit que Lock() charge les données du presse-papier dans votre objet. Toute modification du presse-papier (par une autre application) après que Lock() ait été appelée ne sera pas visible.
2 Dans cet exemple, on s'intéresse uniquement à un format. Dans une application réelle, il est probable d'avoir à rechercher une liste de formats.
3 Il n'est pas obligatoire d'examiner les données du presse-papier avant de le déverouiller. L'appel à FindData() aurait aussi bien pu être effectué après l'appel à Unlock().
Persistance inter-boot : Les données du presse-papier ne persistent pas entre les démarrages — le constructeur fournit un indicateur de persistance (flag), mais il est inutilisé à ce jour.
Persistance intra-boot : Une fois créé, le presse-papier existera jusqu'au redémarrage de l'ordinateur. Par exemple, vous concevez une application qui crée un presse-papier appelé "MonPressePapier" : vous lancez l'application, écrivez quelque chose dans "MonPressePapier", et quittez ensuite l'application. Le presse-papier — et les données écrites par vous — existent encore : si vous relancez votre application (ou n'importe quelle application qui connait "MonPressePapier"), vous pourrez retrouver les données en lisant le presse-papier "MonPressePapier".
|
|
Crée un nouvel objet BClipboard qui fait référence au presse-papier name. Le presse-papier est lui-même créé si un presse-papier de ce nom n'existe pas déjà.
L'indicateur discard est inutilisé à ce jour.
|
|
Détruit l'objet BClipboard. Le presse-papier lui-même et les données qu'il contient ne sont pas affectés par la destruction de l'objet.
|
|
Ces fonctions sont utilisées lors de l'écriture des données dans le presse-papier. Clear() prépare votre BClipboard à l'écriture. Vous appellez Clear() juste avant d'ajouter de nouvelles données à votre message presse-papier. Commit() copie vos données BClipboard dans le presse-papier. voir "Ecrire dans le Presse-papier" pour un exemple de ces fonctions.
Revert() rafraîchit les données du message BClipboard en les rechargeant du presse-papier. La fonction est fournie pour les (rares) cas où vous modifiez les données du message BClipboard, et ensuite décidez de revenir à l'état antérieur. Dans ce cas, vous devriez appeller Revert() (plutôt que Commit()). Si vous ne revenez pas en arrière, votre message BClipboard contiendra toujours les modifications non voulues, même si vous déverrouillez, puis re-verrouillez l'objet.
Ces trois fonctions retournent B_ERROR si BClipboard n'est pas verrouillé, et B_OK dans le cas contraire.
|
|
Retourne l'objet BMessage qui contient les données de BClipboard, ou NULL si le BClipboard n'est pas verrouillé. On attend de vous que vous lisiez ou écriviez directement le BMessage ; Toutefois, vous n'êtes pas autorisés à le libérer ou le distribuer comme un BMessage normal. Si vous modifiez le BMessage et voulez l'écrire dans le presse-papier, vous devez appeller Commit() après avoir procédé à la modification.
voir "Le message Presse-papier" pour plus de détails.
|
|
Retourne un BMessenger qui cible l'objet BApplication de la dernière application ayant mis à jour les données du presse-papier. Le BClipboard n'a pas besoin d'être verrouillé.
|
|
Ces fonctions retournent le compteur du presse-papier. LocalCount() utilise un compteur en cache, tandis que SystemCount() interroge le Serveur d'application pour un compteur système, plus précis.
|
|
Lock() charge les données du presse-papier dans votre objet BClipboard, et le verrouille pour qu'aucun autre thread de votre application ne puisse l'utiliser. Vous devez appeller Lock() avant de lire ou d'écrire le BClipboard. Lock() bloque si l'objet est déjà verrouillé. Elle retourne true quand le verrou a été placé, et false si l'objet BClipboard a été détruit pendant que Lock() était bloquée.
|
Unlock() déverrouille l'objet pour que les autres threads de votre application puissent l'utiliser.
IsLocked() se comprend d'elle-même.
|
|
Retourne le nom du presse-papier. L'objet n'a pas besoin d'être verrouillé.
|
|
Si vous voulez être alertés quand le presse-papier est modifié, appelez StartWatching(), en passant un BMessenger qui sera la cible de la notification. Quand le presse-papier est modifié, un message B_CLIPBOARD_CHANGED est envoyé à la cible.
StopWatching() interrompt la surveillance des modifications du presse-papier.
CODES RETOUR
B_OK. Aucune erreur.
| Table des matières du kit d'application | Index du kit d'application |
Copyright © 2000 Be, Inc. All rights reserved..
