1/* 2 * Copyright 2011-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Gabe Yoder, gyoder@stny.rr.com 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/app/Clipboard.h hrev47355 11 * src/kits/app/Clipboard.cpp hrev47355 12 */ 13 14 15/*! 16 \file Clipboard.h 17 \ingroup app 18 \ingroup libbe 19 \brief Provides the BClipboard class. 20*/ 21 22 23/*! 24 \var be_clipboard 25 \brief Global system clipboard object. 26 27 \since BeOS R3 28*/ 29 30 31/*! 32 \class BClipboard 33 \ingroup app 34 \ingroup libbe 35 \brief Used for short-term data storage between documents and 36 applications via copy and paste operations. 37 38 Clipboards are differentiated by their name. In order for two 39 applications to share a clipboard they simply have to create a 40 BClipboard object with the same name. However, it is rarely necessary 41 to create your own clipboard, instead you can use the \c be_clipboard 42 system clipboard object. 43 44 \remark To access the system clipboard without a BApplication object, 45 create a BClipboard object with the name "system". You should avoid 46 creating a custom clipboard with the name "system" for your own use. 47 48 To access the clipboard data call the Data() method. The BMessage object 49 returned by the Data() method has the following properties: 50 - The \c what value is unused. 51 - The clipboard data is stored in a message field typed as 52 \c B_MIME_TYPE. 53 - The MIME type of the data is used as the name of the field that 54 holds the data. 55 - Each field in the data message contains the same data with a 56 different format. 57 58 To read and write to the clipboard you must first lock the BClipboard 59 object. If you fail to lock the BClipboard object then the Data() method 60 will return \c NULL instead of a pointer to a BMessage object. 61 62 Below is an example of reading a string from the system clipboard. 63\code 64const char *string; 65int32 stringLen; 66if (be_clipboard->Lock()) { 67 // Get the clipboard BMessage 68 BMessage *clip = be_clipboard->Data(); 69 70 // Read the string from the clipboard data message 71 clip->FindData("text/plain", B_MIME_TYPE, (const void **)&string, 72 &stringLen); 73 74 be_clipboard->Unlock(); 75} else 76 fprintf(stderr, "could not lock clipboard.\n"); 77\endcode 78 79 Below is an example of writing a string to the system clipboard. 80\code 81const char* string = "Some clipboard data"; 82 83if (be_clipboard->Lock()) { 84 // Clear the clipboard data 85 be_clipboard->Clear(); 86 87 // Get the clipboard data message 88 BMessage *clip = be_clipboard->Data(); 89 90 // Write string data to the clipboard data message 91 clip->AddData("text/plain", B_MIME_TYPE, string, strlen(string)); 92 93 // Commit the data to the clipboard 94 status = be_clipboard->Commit(); 95 if (status != B_OK) 96 fprintf(stderr, "could not commit data to clipboard.\n"); 97 98 be_clipboard->Unlock(); 99} else 100 fprintf(stderr, "could not lock clipboard.\n"); 101\endcode 102 103 \since BeOS R3 104*/ 105 106 107/*! 108 \fn BClipboard::BClipboard(const char* name, bool transient = false) 109 \brief Create a BClipboard object with the given \a name. 110 111 If the \a name parameter is \c NULL then the "system" BClipboard object 112 is constructed instead. 113 114 \param name The \a name of the clipboard. 115 \param transient If \c true, lose data after a reboot (currently unused). 116 117 \since BeOS R3 118*/ 119 120 121/*! 122 \fn BClipboard::~BClipboard() 123 \brief Destroys the BClipboard object. The clipboard data is not destroyed. 124 125 \since BeOS R3 126*/ 127 128 129/*! 130 \fn const char* BClipboard::Name() const 131 \brief Returns the name of the BClipboard object. 132 133 \returns The name of the clipboard. 134 135 \since BeOS R3 136*/ 137 138 139/*! 140 \name Commit Count 141*/ 142 143 144//! @{ 145 146 147/*! 148 \fn uint32 BClipboard::LocalCount() const 149 \brief Returns the (locally cached) number of commits to the clipboard. 150 151 The returned value is the number of successful Commit() invocations for 152 the clipboard represented by this object, either invoked on this object 153 or another (even from another application). This method returns a locally 154 cached value, which might already be obsolete. For an up-to-date value 155 use SystemCount(). 156 157 \return The number of commits to the clipboard. 158 159 \sa SystemCount() 160 161 \since BeOS R5 162*/ 163 164 165/*! 166 \fn uint32 BClipboard::SystemCount() const 167 \brief Returns the number of commits to the clipboard. 168 169 The returned value is the number of successful Commit() invocations for 170 the clipboard represented by this object, either invoked on this object 171 or another (even from another application). This method retrieves the 172 value directly from the system service managing the clipboards, so it is 173 more expensive, but more up-to-date than LocalCount(), which returns a 174 locally cached value. 175 176 \return The number of commits to the clipboard. 177 178 \sa LocalCount() 179 180 \since BeOS R5 181*/ 182 183 184//! @} 185 186 187/*! 188 \name Monitoring 189*/ 190 191 192//! @{ 193 194 195/*! 196 \fn status_t BClipboard::StartWatching(BMessenger target) 197 \brief Start watching the BClipboard object for changes. 198 199 When a change in the clipboard occurs, most like as the result of a cut 200 or copy action, a \a B_CLIPBOARD_CHANGED message is sent to \a target. 201 202 \retval B_OK Everything went fine. 203 \retval B_BAD_VALUE \a target is invalid. 204 \retval B_ERROR An error occured. 205 206 \sa StopWatching() 207 208 \since BeOS R5 209*/ 210 211 212/*! 213 \fn status_t BClipboard::StopWatching(BMessenger target) 214 \brief Stop watching the BClipboard object for changes. 215 216 \retval B_OK Everything went fine. 217 \retval B_BAD_VALUE \a target is invalid. 218 \retval B_ERROR An error occurred. 219 220 \sa StartWatching() 221 222 \since BeOS R5 223*/ 224 225 226//! @} 227 228 229/*! 230 \name Locking 231*/ 232 233 234//! @{ 235 236 237/*! 238 \fn bool BClipboard::Lock() 239 \brief Locks the clipboard so that no other tread can read from it or 240 write to it. 241 242 You should call Lock() before reading or writing to the clipboard. 243 244 \returns \c true if the clipboard was locked, \c false otherwise. 245 246 \sa Unlock() 247 248 \since BeOS R3 249*/ 250 251 252/*! 253 \fn void BClipboard::Unlock() 254 \brief Unlocks the clipboard. 255 256 \sa Lock() 257 258 \since BeOS R3 259*/ 260 261 262/*! 263 \fn bool BClipboard::IsLocked() const 264 \brief Returns whether or not the clipboard is locked. 265 266 \returns \c true if the clipboard is locked, \c false if it is unlocked. 267 268 \since BeOS R5 269*/ 270 271 272//! @} 273 274 275/*! 276 \name Clipboard Data Transaction 277*/ 278 279 280//! @{ 281 282 283/*! 284 \fn status_t BClipboard::Clear() 285 \brief Clears out all data from the clipboard. 286 287 You should call Clear() before adding new data to the BClipboard object. 288 289 \return A status code. 290 \retval B_OK Everything went find. 291 \retval B_NOT_ALLOWED The clipboard is not locked. 292 \retval B_NO_MEMORY Ran out of memory initializing the data message. 293 \retval B_ERROR Another error occurred. 294 295 \since BeOS R3 296*/ 297 298 299/*! 300 \fn status_t BClipboard::Commit() 301 \brief Commits the clipboard data to the BClipboard object. 302 303 \return A status code. 304 \retval B_OK Everything went find. 305 \retval B_NOT_ALLOWED The clipboard is not locked. 306 \retval B_ERROR Another error occurred. 307 308 \since BeOS R3 309*/ 310 311 312/*! 313 \fn status_t BClipboard::Commit(bool failIfChanged) 314 \brief Commits the clipboard data to the BClipboard object with the 315 option to fail if there is a change to the clipboard data. 316 317 \param failIfChanged Whether or not to fail to commit the changes 318 if there is a change in the clipboard data. 319 320 \return A status code. 321 \retval B_OK Everything went find. 322 \retval B_NOT_ALLOWED The clipboard is not locked. 323 \retval B_ERROR Another error occurred. 324 325 \since BeOS R5 326*/ 327 328 329/*! 330 \fn status_t BClipboard::Revert() 331 \brief Reverts the clipboard data. 332 333 The method should be used in the case that you have made a change to the 334 clipboard data message and then decide to revert the change instead of 335 committing it. 336 337 \return A status code. 338 \retval B_OK Everything went find. 339 \retval B_NOT_ALLOWED The clipboard is not locked. 340 \retval B_NO_MEMORY Ran out of memory initializing the data message. 341 \retval B_ERROR Another error occurred. 342 343 \since BeOS R5 344*/ 345 346 347//! @} 348 349 350/*! 351 \name Clipboard Data Message 352*/ 353 354 355//! @{ 356 357 358/*! 359 \fn BMessenger BClipboard::DataSource() const 360 \brief Gets a BMessenger object targeting the application that last 361 modified the clipboard. 362 363 The clipboard object does not need to be locked to call this method. 364 365 \returns A BMessenger object that targets the application that last 366 modified the clipboard. 367 368 \since BeOS R3 369*/ 370 371 372/*! 373 \fn BMessage* BClipboard::Data() const 374 \brief Gets a pointer to the BMessage object that holds the clipboard 375 data. 376 377 If the BClipboard object is not locked this method returns \c NULL. 378 379 \returns A pointer to the BMessage object that holds the clipboard 380 data or \c NULL if the clipboard is not locked. 381 382 \since BeOS R3 383*/ 384 385 386//! @} 387