# The Application Kit: BClipboard

Derived from: none

Declared in: be/app/Clipboard.h

Library: libbe.so

## Overview

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".

### The Data Container

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".

### Using the Clipboard

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.

## Constructor and Destructor

### BClipboard()

          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()`

### ~BClipboard()

          virtual ~BClipboard()

Deletes all memory allocated by the BClipboard, including the container BMessage and the data it holds.

## Member Functions

### Clear()

          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()`

### 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()`

### Data()

          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

### DataSource()

          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

### Lock(), Unlock()

          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()`

### Name()

          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 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.