Derived from: none
Declared in: be/app/Clipboard.h
Library: libbe.so
A BClipboard is an interface to system-wide, temporary data storage. The storage that a clipboard represents is identified by name; if two apps want to refer to the same (underlying) storage, they simply create BClipboard objects with the same name. By sharing clipboard names, apps can easily transfer data. Currently, clipboard storage does not persist between boots.
Your BApplication object creates a default BClipboard (named "system") and assigns it to the global be_clipboard variable. The storage behind be_clipboard is the same for all apps. For most apps, be_clipboard is sufficient--but you can create other clipboards (with their own storage) if you want. Simply create a new BClipboard object and assign it a name other than "system".
If you want to access the system clipboard without creating a BApplication object, construct a BClipboard object with the name "system".
A clipboard uses a BMessage to hold its data. To inspect, add to, or replace the data in the clipboard, call BClipboard's Data() function (to retrieve the BMessage), and then call normal BMessage functions.
There are few established conventions for arranging data in the clipboard, other than those that the BMessage class imposes. The BeOS follows this rule: If the what data member of the container BMessage is B_SIMPLE_DATA, the clipboard is understood to hold just one item of data, though it may hold it in more than one data format. For example, a B_SIMPLE_DATA clipboard might contain some copied text in three formats--in a format native to the application that put the text in the clipboard, in a rich but possibly less informative standard format such as HTML or RTF, and as a simple ASCII string. Each format is a separately-named data field in the BMessage.
The retrieving application can choose the format that's most appropriate for the impending paste operation, generally the richest format that it can deal with. It might care what the names of the data fields are, or it might look only at the data types. If the type is B_MIME_TYPE, the name is a MIME string that encodes the true data type. The BTextView object accepts B_MIME_TYPE data with the name "text/plain".
You must bracket all interactions with a BClipboard object with calls to Lock() and Unlock(). This prevents other applications (or other threads of the same application) from accessing the clipboard while you're using it. Conversely, if some other application (or another thread in your application) holds the lock to the clipboard when you call Lock(), your thread will block until the current lock holder calls Unlock()--in other words, Lock() will always succeed, even if it has to wait forever to do so. Currently, there's no way to tell if the clipboard is already locked, nor can you specify a time limit beyond which you won't wait for the lock.
When putting data in the clipboard, interactions should also be bracketed by calls to Clear() and Commit(). Clearing the clipboard removes all data that it currently holds. The Commit() function tells the clipboard that you're serious about the additions you've made. If you don't commit your additions, they'll be lost.
The following code fragment demonstrates the expected sequence of function calls:
if ( be_clipboard->Lock() ) {
be_clipboard->Clear();
BMessage *clipper = be_clipboard->Data();
. . .
clipper->AddString("text", theData);
. . .
be_clipboard->Commit();
be_clipboard->Unlock();
}
When retrieving data from the clipboard, it's necessary to lock and unlock the BClipboard object, but not to clear it (which would remove the data before you could look at it) or commit changes. For example:
if ( be_clipboard->Lock() ) {
BMessage *clipper = be_clipboard->Data();
. . .
if ( clipper->FindString("text", &theText) == B_OK ) {
. . .
}
. . .
be_clipboard->Unlock();
}
Once the BClipboard is locked, it's possible to both retrieve and add data during the same session, but such a pursuit doesn't correspond to traditional manipulations.
BClipboard(const char *name, bool transient = false)
Creates a new BClipboard object for the name clipboard. If there's no clipboard with that name or name is NULL, one is created. Otherwise, the new object is an interface to the clipboard previously created, by any application, with name.
The transient flag tells the clipboard service whether to save the clipboard when the system shuts down. If saved, the data in the clipboard will be available again when the user next turns the computer on. If not, the data is lost.
See also: Name()
virtual ~BClipboard()
Deletes all memory allocated by the BClipboard, including the container BMessage and the data it holds.
status_t Clear(void)
Erases all items that are currently on the clipboard. Normally, you call Clear() just after locking the clipboard and just before getting the data container with the intention of adding new data to it. This function returns B_ERROR if the BClipboard isn't locked, and B_OK otherwise.
See also: Commit()
status_t Commit(void)
Forces the clipboard to notice the items you added. Additions to the clipboard are lost unless followed by a call to Commit(). The call to Commit() must precede the call to Unlock(). If the BClipboard isn't locked, this function fails and returns B_ERROR. If successful, it returns B_OK.
See also: Clear()
BMessage *Data(void) const
Returns the BMessage object that holds clipboard data, or NULL if the BClipboard isn't locked. The returned object belongs to the system; you should not free it, assign it to another object, or arrange for it to be delivered as an ordinary message.
See also: the BMessage class
BMessenger DataSource(void) const
Returns a BMessenger object for the application that last committed data to the clipboard. The BMessenger targets that application's BApplication object.
See also: the BMessenger class
bool Lock(void)
void Unlock(void)
These functions lock and unlock the clipboard. Locking the clipboard gives a thread exclusive permission to invoke the other BClipboard functions. If some other thread already has the clipboard locked when your thread calls Lock(), your thread will wait until the lock-holding thread calls Unlock(). Your thread should also invoke Unlock() when it's done manipulating the clipboard.
Lock() should invariably be successful and return true.
See also: BLooper::Lock()
const char *Name(void) const
Returns the name of the clipboard. The returned string belongs to the BClipboard object.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 23, 1998.