This document describes the BClipboard interface and some basics of how it is implemented. The document has the following sections:
The BClipboard class provides an interface to a named, system-wide, temporary storage resource. Access to the system clipboard is provided by the be_clipboard variable provided by a BApplication object (or by constructing a clipboard with the name "system"). The best source of information for the BClipboard interface can be found here in the Be Book.
The following use cases cover the BClipboard functionality:
Construction: A BClipboard will accept one or two arguments to construction. A name is required for identifying the clipboard. The discard argument indicates whether the clipboard data should be discarded between boots. Te discard argument defaults to false, however this is meaningless since functionality has not been implemented to maintain clipboard data between boots. After construction, the queue is empty.
Destruction: The destructor destroys the BClipboard object, however the system-wide clipboard itself is unaffected.
Writing to clipboard 1: The normal procedure for writing data consists of the following: locking the clipboard via Lock(), clearing the data via Clear(), adding data to the clipboard message, committing the data via Commit(), and unlocking the clipboard via Unlock().
Writing to clipboard 2: The data which is to be written is not added directly to the BClipboard object, but is added to the data message for the BClipboard. The message is obtained by calling BClipboard::Data(). Data is added in fields of type B_MIME_TYPE. The name of the field corresponds to the MIME type of the data. If multiple fields are added, they should contain the same data, but formatted for different MIME types.
Writing to clipboard 3: In the event that one wishes to back out of writing process before calling Commit(), Revert() must be called. Otherwise, the changes to the clipboard remain in the BClipboard object.
Reading from clipboard 1: The normal procedure for reading data consists of the following: locking the clipboard via Lock(), obtaining the data from the clipboards data message, and unlocking the clipboard via Unlock().
Reading from clipboard 2: The data message is obtained from a call to BClipboard::Data(). Data is obtained from the message by using BMessage::FindData for a specified MIME type.
Reading from clipboard 3: The data is uploaded from the system when Lock() is called, therefore any data which is written to the clipboard between the calls to Lock() and Data() will not be included in the data message.
Reading from clipboard 4: It is permissible to Unlock() the clipboard before calling FindData on the data message.
Clearing: The Clear() function is used to remove all data from the clipboard and is used before adding new data which is to be written to the clipboard. Clear() returns B_ERROR if the BClipboard is not locked, and returns B_OK if it is locked.
Committing: The Commit() function is used to upload data from the BClipboard to the system. The data is immediately available to other applications once Commit() has been called. Commit() returns B_ERROR if the BClipboard is not locked, and returns B_OK if it is locked.
Revert: The Revert() function is used to synchronize the data in the BClipboard to the system. This is only needed in case one begins to modify the data message and wishes to back out of the changes. Revert() returns B_ERROR if the BClipboard is not locked, and returns B_OK if it is locked.
Accessing data: Data() is used to obtain a pointer to the BClipboard's data message. One is expected to read and write data directly to the message, but the message must not be freed or dispatched. Data() returns NULL if the BClipboard is not locked.
Accessing a data source: DataSource() is used to obtain a BMessenger pointed at the BApplication which last committed data to the clipboard. There is no requirement for the the BClipboard to be locked when calling DataSource().
Obtaining a count: The count refers to the number of times that data has been uploaded to the clipboard. There are two count functions. SystemCount() returns an up to date count which is obtained from the system. Count() returns a cached count. The cached count is set to zero upon creation of the BClipboard, and is updated when Lock() or Commit() is called.
Locking: Lock() is used to upload data from the system into the BClipboard object and prevent other threads in the application from using it. It must be called before reading or writing data to the BClipboard. It blocks if the BClipboard is already locked. The return value is true if the BClipboard is successfully locked, or false if the BClipboard was deleted while Lock() was blocked.
Unlocking: Unlock() is used to unlock the BClipboard and allow other threads in the application to use it.
Checking lock status: IsLocked() returns true if the BClipboard is locked by the current thread, and false if it is not lockedi or is locked by another thread.
Checking clipboard name: Name() returns a string containing the name of the clipboard. It is not necessary for the BClipboard to be locked when calling Name().
Watching a clipboard: StartWatching and StopWatching are used to enable and disable watching of a clipboard. When the clipboard is changed, a B_CLIPBOARD_CHANGED message is sent to the target specified in the call to StartWatching.
The BClipboard class is implemented via a message passing system between the BClipboard, the Registrar, and the Clipboard Handler associated with the Registrar. Details of the message passing protocol are listed in the Registrar documentation.