Derived from: none
Declared in: <app/Clipboard.h>
A clipboard is a shared repository for data--a vehicle for transferring data between applications or between different parts of the same application. An application adds some amount of data to the clipboard, then some other application (or the same application) retrieves (or "finds") that data. This mechanism permits, most notably, the ability to cut, copy, and paste data items. For example, the BTextView class, in the Interface Kit, responds to B_CUT, B_COPY, and B_PASTE messages by adding data to and retrieving it from the system clipboard.
A BClipboard object represents a clipboard and is the programming interface to the clipboard service. If you provide a unique name when constructing a BClipboard object, a new clipboard with that name is created for you. If you provide the name of an existing clipboard, the new object will be an additional interface to that clipboard.
However, for most uses, you don't need a clipboard that's your own creation, but rather one that's common to all applications. The BeOS creates just such a clipboard--named "system"--when you boot the machine. Then, when each application starts up, it's automatically given a BClipboard object for the common clipboard. The object is assigned to a global variable, be_clipboard. The be_clipboard variables in all applications refer (ultimately) to the same system clipboard.
The system be_clipboard object is the one that you should use for all normal cut, copy, and paste operations. An application-created clipboard might be used for more limited data sharing. For example, you can construct a BClipboard with a private name, add data to it, and pass the name to another application. That application can use the name to construct its own BClipboard interface to the clipboard you created.
A clipboard uses a BMessage to hold its data. The BClipboard object hands you the BMessage in response to a Data() request. Once you have the BMessage container, you can add data to it or find what's already there by calling standard BMessage functions. You can ignore the what data member of the BMessage, or you can use it to indicate something about what the clipboard contains.
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 separate named entry 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 entries 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(void)
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.
See also: the BClipboard constructor
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 30, 1997.