BClipboard Class Reference

Used for short-term data storage between documents and applications via copy and paste operations. More...

Public Member Functions
	BClipboard (const char *name, bool transient=false)
	Create a BClipboard object with the given name.
virtual	~BClipboard ()
	Destroys the BClipboard object. The clipboard data is not destroyed.
const char *	Name () const
	Returns the name of the BClipboard object.
Commit Count
uint32	LocalCount () const
	Returns the (locally cached) number of commits to the clipboard.
uint32	SystemCount () const
	Returns the number of commits to the clipboard.
Monitoring
status_t	StartWatching (BMessenger target)
	Start watching the BClipboard object for changes.
status_t	StopWatching (BMessenger target)
	Stop watching the BClipboard object for changes.
Locking
bool	Lock ()
	Locks the clipboard so that no other tread can read from it or write to it.
void	Unlock ()
	Unlocks the clipboard.
bool	IsLocked () const
	Returns whether or not the clipboard is locked.
Clipboard Data Transaction
status_t	Clear ()
	Clears out all data from the clipboard.
status_t	Commit ()
	Commits the clipboard data to the BClipboard object.
status_t	Commit (bool failIfChanged)
	Commits the clipboard data to the BClipboard object with the option to fail if there is a change to the clipboard data.
status_t	Revert ()
	Reverts the clipboard data.
Clipboard Data Message
BMessenger	DataSource () const
	Gets a BMessenger object targeting the application that last modified the clipboard.
BMessage *	Data () const
	Gets a pointer to the BMessage object that holds the clipboard data.

Detailed Description

Used for short-term data storage between documents and applications via copy and paste operations.

Clipboards are differentiated by their name. In order for two applications to share a clipboard they simply have to create a BClipboard object with the same name. However, it is rarely necessary to create your own clipboard, instead you can use the be_clipboard system clipboard object.

Remarks

To access the system clipboard without a BApplication object, create a BClipboard object with the name "system". You should avoid creating a custom clipboard with the name "system" for your own use.

To access the clipboard data call the Data() method. The BMessage object returned by the Data() method has the following properties:

• The what value is unused.
• The clipboard data is stored in a message field typed as B_MIME_TYPE.
• The MIME type of the data is used as the name of the field that holds the data.
• Each field in the data message contains the same data with a different format.

To read and write to the clipboard you must first lock the BClipboard object. If you fail to lock the BClipboard object then the Data() method will return NULL instead of a pointer to a BMessage object.

Below is an example of reading a string from the system clipboard.

const char *string;
int32 stringLen;
if (be_clipboard->Lock()) {
    // Get the clipboard BMessage
    BMessage *clip = be_clipboard->Data();
 
    // Read the string from the clipboard data message
    clip->FindData("text/plain", B_MIME_TYPE, (const void **)&string,
        &stringLen);
 
    be_clipboard->Unlock();
} else
    fprintf(stderr, "could not lock clipboard.\n");

Below is an example of writing a string to the system clipboard.

const char* string = "Some clipboard data";
 
if (be_clipboard->Lock()) {
    // Clear the clipboard data
    be_clipboard->Clear();
 
    // Get the clipboard data message
    BMessage *clip = be_clipboard->Data();
 
    // Write string data to the clipboard data message
    clip->AddData("text/plain", B_MIME_TYPE, string, strlen(string));
 
    // Commit the data to the clipboard
    status = be_clipboard->Commit();
    if (status != B_OK)
        fprintf(stderr, "could not commit data to clipboard.\n");
 
    be_clipboard->Unlock();
} else
    fprintf(stderr, "could not lock clipboard.\n");

Since

BeOS R3

Constructor & Destructor Documentation

BClipboard()

BClipboard::BClipboard	(	const char *	name,
		bool	transient = false
	)

Create a BClipboard object with the given name.

If the name parameter is NULL then the "system" BClipboard object is constructed instead.

Parameters

name	The name of the clipboard.
transient	If true, lose data after a reboot (currently unused).

Since

BeOS R3

~BClipboard()

BClipboard::~BClipboard ( )

virtual

Destroys the BClipboard object. The clipboard data is not destroyed.

Since

BeOS R3

Member Function Documentation

Clear()

status_t BClipboard::Clear

(

)

Clears out all data from the clipboard.

You should call Clear() before adding new data to the BClipboard object.

Returns

A status code.

Return values

B_OK	Everything went find.
B_NOT_ALLOWED	The clipboard is not locked.
B_NO_MEMORY	Ran out of memory initializing the data message.
B_ERROR	Another error occurred.

Since

BeOS R3

Commit() [1/2]

status_t BClipboard::Commit

(

)

Commits the clipboard data to the BClipboard object.

Returns

A status code.

Return values

B_OK	Everything went find.
B_NOT_ALLOWED	The clipboard is not locked.
B_ERROR	Another error occurred.

Since

BeOS R3

Commit() [2/2]

status_t BClipboard::Commit

(

bool

failIfChanged

)

Commits the clipboard data to the BClipboard object with the option to fail if there is a change to the clipboard data.

Parameters

failIfChanged

Whether or not to fail to commit the changes if there is a change in the clipboard data.

Returns

A status code.

Return values

B_OK	Everything went find.
B_NOT_ALLOWED	The clipboard is not locked.
B_ERROR	Another error occurred.

Since

BeOS R5

Data()

BMessage * BClipboard::Data

(

)

const

Gets a pointer to the BMessage object that holds the clipboard data.

If the BClipboard object is not locked this method returns NULL.

Returns

A pointer to the BMessage object that holds the clipboard data or NULL if the clipboard is not locked.

Since

BeOS R3

DataSource()

BMessenger BClipboard::DataSource

(

)

const

Gets a BMessenger object targeting the application that last modified the clipboard.

The clipboard object does not need to be locked to call this method.

Returns

A BMessenger object that targets the application that last modified the clipboard.

Since

BeOS R3

IsLocked()

bool BClipboard::IsLocked

(

)

const

Returns whether or not the clipboard is locked.

Returns

true if the clipboard is locked, false if it is unlocked.

Since

BeOS R5

LocalCount()

uint32 BClipboard::LocalCount

(

)

const

Returns the (locally cached) number of commits to the clipboard.

The returned value is the number of successful Commit() invocations for the clipboard represented by this object, either invoked on this object or another (even from another application). This method returns a locally cached value, which might already be obsolete. For an up-to-date value use SystemCount().

Returns

The number of commits to the clipboard.

See also

SystemCount()

Since

BeOS R5

Lock()

bool BClipboard::Lock

(

)

Locks the clipboard so that no other tread can read from it or write to it.

You should call Lock() before reading or writing to the clipboard.

Returns

true if the clipboard was locked, false otherwise.

See also

Unlock()

Since

BeOS R3

Name()

const char * BClipboard::Name

(

)

const

Returns the name of the BClipboard object.

Returns

The name of the clipboard.

Since

BeOS R3

Revert()

status_t BClipboard::Revert

(

)

Reverts the clipboard data.

The method should be used in the case that you have made a change to the clipboard data message and then decide to revert the change instead of committing it.

Returns

A status code.

Return values

B_OK	Everything went find.
B_NOT_ALLOWED	The clipboard is not locked.
B_NO_MEMORY	Ran out of memory initializing the data message.
B_ERROR	Another error occurred.

Since

BeOS R5

StartWatching()

status_t BClipboard::StartWatching

(

BMessenger

target

)

Start watching the BClipboard object for changes.

When a change in the clipboard occurs, most like as the result of a cut or copy action, a B_CLIPBOARD_CHANGED message is sent to target.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	target is invalid.
B_ERROR	An error occured.

See also

StopWatching()

Since

BeOS R5

StopWatching()

status_t BClipboard::StopWatching

(

BMessenger

target

)

Stop watching the BClipboard object for changes.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	target is invalid.
B_ERROR	An error occurred.

See also

StartWatching()

Since

BeOS R5

SystemCount()

uint32 BClipboard::SystemCount

(

)

const

Returns the number of commits to the clipboard.

The returned value is the number of successful Commit() invocations for the clipboard represented by this object, either invoked on this object or another (even from another application). This method retrieves the value directly from the system service managing the clipboards, so it is more expensive, but more up-to-date than LocalCount(), which returns a locally cached value.

Returns

The number of commits to the clipboard.

See also

LocalCount()

Since

BeOS R5

Unlock()

void BClipboard::Unlock

(

)

Unlocks the clipboard.

See also

Lock()

Since

BeOS R3