The Application Kit: BClipboard

The Application Kit Table of Contents | The Application Kit Index

# BClipboard

Derived from: none

Declared in: be/app/Clipboard.h

Library: libbe.so

Allocation: Constructor, on the stack, or use the

###### Summary

A BClipboard object is an interface to a clipboard, a resource that provides system-wide, temporary data storage. Clipboards are identified by name; if two apps want to refer to the same clipboard, they simply create respective BClipboard objects with the same name:

       /* App A:  This creates a clipboard named "MyClipboard". */
       BClipboard *appAclipboard = new BClipboard("MyClipboard");

       /* App B:  This object refers to the clipboard already created by App A. */
       BClipboard *appBclipboard = new BClipboard("MyClipboard");

### The System Clipboard

In practice, you rarely need to construct your own BClipboard object; instead, you use the BClipboard that's created for you by your BApplication object. This object, which you refer to through the global `be_clipboard` variable, accesses the default system clipboard. Data that you write to your `be_clipboard` object can be read from any other app's `be_clipboard`. For example, the cut/copy/paste operations defined by BTextView transfer data through the system clipboard.

To access the system clipboard without creating a BApplication object, construct a BClipboard object with the name "system". The system clipboard is under the control of the user—you should only read or write the system clipboard as a direct result of the user's actions. If you create your own clipboards don't name them "system".

### The Clipboard Message

To access a clipboard's data, you call functions on a BMessage that the BClipboard object hands you (through its `Data()` function). The BMessage follows these conventions:

- The `what` value is unused.

- The data is stored in a message field. The field should be typed as `B_MIME_TYPE`; the MIME type that describes the data should be used as the name of the field that holds the data (see "Writing to the Clipboard" for an example).

- If the BMessage contains more than one field, each field should present the same data in a different format. For example, the StyledEdit app writes text data in its own format (in order to encode the fonts, colors, etc.) and also writes the data as plain ASCII text (MIME type "text/plain").

### Writing to the Clipboard

The following annotated example shows how to write to the clipboard.

       BMessage *clip = (BMessage *)NULL;

       if (be_clipboard->Lock()1) {
           be_clipboard->Clear()2;
           if ((clip = be_clipboard->Data()3) {
             clip->AddData("text/MyFormat", B_MIME_TYPE, myText, myLength)4;
             clip->AddData("text/plain", B_MIME_TYPE, asciiText, asciiLength)4;
             be_clipboard->Commit()5;
          }
           be_clipboard->Unlock()6;
       }

1 `Lock()` your BClipboard object. This uploads data from the clipboard into your BClipboard's local BMessage object, and prevents other threads in your application from accessing the BClipboard's data. Note that locking does not lock the underlying clipboard data—other applications can change the clipboard while you have your object locked.

2 Prepare the BClipboard for writing by calling `Clear()`. This erases the data that was uploaded from the clipboard.

3 Call `Data()` to get a pointer to the BClipboard's BMessage object.

4 Write the data by invoking `AddData()` directly on the BMessage. In the example, we write the data in two different formats.

5 Call `Commit()` to copy your BMessage back to the clipboard. As soon as you call `Commit()`, the data that you added is visible to other clipboard clients.

6 `Unlock()` balances the `Lock()`. The BClipboard object can now be accessed by other threads in your application.

If you decide that you don't want to commit your changes, you should call `Revert()` before you unlock.

### Reading from the Clipboard

Here we show how to read a simple string from the clipboard.

       const char *text;
       int32 textLen;
       BMessage *clip = (BMessage *)NULL;

       if (be_clipboard->Lock()1) {
          if ((clip = be_clipboard->Data();
             clip->FindData("text/plain", B_MIME_TYPE,
                (const void **)&text, &textlen)2;
          be_clipboard->Unlock()3;
       }

1 As in writing, we bracket the operation with `Lock()` and `Unlock()`. Keep in mind that `Lock()` uploads data from the clipboard into our object. Any changes that are made to the clipboard (by some other application) after `Lock()` is called won't be seen here.

2 In this example, we only look for one hard-coded format. In a real application, you may have a list of formats that you can look for.

3 It isn't necessary to examine the clipboard data before you unlock it. The `FindData()` call could just as well have been performed after the `Unlock()` call.

### Persistence

Inter-boot persistence: Clipboard data does not persist between boots—the constructor provides a persistence flag, but it's currently unused.

Intra-boot persistence: Once you've created a clipboard, that clipboard will exist until you reboot your computer. For example, let's say you design an app that creates a clipboard called "MyClip": You launch the app, write something to "MyClip", and then quit the app. The clipboard—and the data that you wrote to it—will still exist: If you relaunch your app (or any app that knows about "MyClip"), you can pick up the data by reading from the "MyClip" clipboard.

## Constructor and Destructor

### BClipboard()

`BClipboard(`const char *name, bool discard = false`)`

Creates a new BClipboard object that refers to the name clipboard. The clipboard itself is created if a clipboard of that name doesn't already exist.

The discard flag is currently unused.

### ~BClipboard()

virtual `~BClipboard()`

Destroys the BClipboard object. The clipboard itself and the data it contains are not affected by the object's destruction.

## Member Functions

### Clear() , Commit() , Revert()

status_t `Clear(`void`)`
status_t `Commit(`void`)`
status_t `Revert(`void`)`

These functions are used when you're writing data to the clipboard. `Clear()` prepares your BClipboard for writing. You call `Clear()` just before you add new data to your clipboard message. `Commit()` copies your BClipboard data back to the clipboard. See "Writing to the Clipboard" for an example of these functions.

`Revert()` refreshes the BClipboard's data message by uploading it from the clipboard. The function is provided for the (rare) case where you alter your BClipboard's data message, and then decide to back out of the change. In this case, you should call `Revert()` (rather than `Commit()`). If you don't revert, your BClipboard's message will still contain your unwanted change, even if you unlock and then re-lock the object.

All three functions returns `B_ERROR` if the BClipboard isn't locked, and `B_OK` otherwise.

### Commit() see Clear()

### Data()

BMessage *`Data(`void`)` const

Returns the BMessage object that holds the BClipboard's data, or `NULL` if the BClipboard isn't locked. You're expected to read and write the BMessage directly; however, you may not free it or dispatch it like a normal BMessage. If you change the BMessage and want to write it back to the clipboard, you have to call `Commit()` after you make the change.

See "The Clipboard Message" for more information.

### DataSource()

BMessenger `DataSource(`void`)` const

Returns a BMessenger that targets the BApplication object of the application that last committed data to the clipboard. The BClipboard needn't be locked.

### LocalCount() , SystemCount()

uint32 `LocalCount(`void`)` const
uint32 `SystemCount(`void`)` const

These functions return the clipboard count. `LocalCount()` uses a cached count, while `SystemCount()` asks the Application Server for the more accurate system counter.

### Lock() , Unlock() , IsLocked()

bool `Lock(`void`) `
void `Unlock(`void`) `
bool `IsLocked(`void`) `

`Lock()` uploads data from the clipboard into your BClipboard object, and locks the object so no other thread in your application can use it. You must call `Lock()` before reading or writing the BClipboard. `Lock()` blocks if the object is already locked. It returns `true` if the lock was acquired, and `false` if the BClipboard object was deleted while `Lock()` was blocked.

| There's no way to tell `Lock()` to time out.

`Unlock()` unlocks the object so other threads in your application can use it.

`IsLocked()` hardly needs to be documented.

### Name()

const char *`Name(`void`)` const

Returns the name of the clipboard. The object needn't be locked.

### Revert() see Clear()

### StartWatching() , StopWatching()

status_t `StartWatching(` BMessenger target`) `
status_t `StopWatching(` BMessenger target`) `

If you want to be alerted when the clipboard changes, call `StartWatching()`, passing a BMessenger to be the target for the notification. When the clipboard changes, a `B_CLIPBOARD_CHANGED` message will be sent to the target.

`StopWatching()` stops monitoring the clipboard for changes.

RETURN CODES

`B_OK`. No error.

- Other errors. You get the idea.

### StopWatching() see StartWatching()

### SystemCount() see LocalCount()

### Unlock() see Lock()

The Application Kit Table of Contents | The Application Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..