docs/user/app/Clipboard.dox

   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
  64 const char *string;
  65 int32 stringLen;
  66 if (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
  81 const char* string = "Some clipboard data";
  82
  83 if (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 //! @}