Clipboard

Since: BlackBerry 10.0.0

#include <bb/system/Clipboard>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

Copy and paste data within an application or between applications.

The Clipboard class lets you add or remove data from the clipboard that is shared between applications on the device. This clipboard allows for copying and pasting data in different locations within the same application, or between different applications on the device.

Data in the clipboard is referenced by type. Multiple types of data can exist in the clipboard at the same time. Each type typically refers to a different encoding of the same data. For example, an application copying data from an HTML source might insert both HTML markup and plain text into the clipboard. This increases the likelihood that an application performing a paste operation will find data in the clipboard with a suitable encoding. For example, a rich document editor performing a paste operation might first look for HTML markup in the clipboard and fall back to plain text if no HTML markup is found, whereas a simple document editor might look for plain text data only.

A type can be any non-empty string. For compatibility with other applications, using Internet media types (i.e., MIME types) is recommended. For example, "text/plain", "text/html", and "text/rtf" are three commonly-used encodings for textual data.

The following example shows how to "paste" plain text data from the clipboard:

bb::system::Clipboard clipboard;
QByteArray data = clipboard.value("text/plain");
if (!data.isEmpty()) {
    // process data from clipboard
}

The following example shows how to "copy" html and plain text data to the clipboard:

bb::system::Clipboard clipboard;
clipboard.clear();
clipboard.insert("text/html", "<b>Hello world</b>");
clipboard.insert("text/plain", "Hello world");


Overview

Public Functions Index

Clipboard (QObject *parent=0)
Clipboard (const QString &path, QObject *parent=0)
virtual ~Clipboard ()
boolclear ()
boolcontains (const QString &type, bool *restricted=0) const
boolinsert (const QString &type, const QByteArray &data)
boolremove (const QString &type)
QByteArrayvalue (const QString &type, bool *restricted=0) const

Public Functions

Clipboard (

Creates a new Clipboard object that manages data stored in the default, system-wide clipboard.

All applications run within a particular security perimeter and the data they copy to the system clipboard is associated with that perimeter. Applications in the same perimeter can share data via the clipboard but may be blocked (due to a security policy) from accessing data in a different perimeter.

Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

Clipboard (

Creates a new Clipboard object that manages data stored in the specified directory.

You can use a custom path to create a clipboard local to this application or a subset of applications. All users of the custom clipboard must have appropriate filesystem permissions to access the directory.

Note:

All files in the specified directory are assumed to be owned by the clipboard. Calling clear() will delete every file in the directory.

Parameters
path

A directory that stores data for a custom clipboard, or an empty path to indicate the default, system-wide clipboard - see Clipboard(QObject*) for more details.

parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~Clipboard ()

Destructor.

Since:

BlackBerry 10.0.0

bool clear ()

Deletes all data from the clipboard.

Return:

true if all data was deleted from the clipboard successfully, false otherwise.

Since:

BlackBerry 10.0.0

bool contains (
  • const QString &type,
  • bool *restricted )

Indicates whether the clipboard contains data for the specified type.

Data may exist for the specified type in a different security perimeter. Furthermore, a security policy may block the caller from accessing this perimeter. If this occurs, false will be returned and restricted will be set to true.

Parameters
type

The type of data requested from the clipboard.

restricted

If not 0, restricted is an out parameter that is set to true if data exists but is not accessible to the caller, false otherwise.

Return:

true if the data exists in the clipboard for the specified type and is accessible to the caller, false otherwise.

Since:

BlackBerry 10.0.0

bool insert (

Adds new data to the clipboard for the specified type.

If data already exists for the type, the data is replaced. Data for other types is unaffected by this operation.

Parameters
type

The type of data being added the clipboard.

data

The raw data to put in the clipboard.

Return:

true if the data was added to the clipboard successfully, false otherwise.

Since:

BlackBerry 10.0.0

bool remove (

Deletes data from the clipboard for the specified type.

Parameters
type

The type of data to remove from the clipboard.

Return:

true if the data was deleted from the clipboard successfully, false otherwise.

Since:

BlackBerry 10.0.0

QByteArray value (
  • const QString &type,
  • bool *restricted )

Retrieves data from the clipboard for the specified type.

Data may exist for the specified type in a different security perimeter. Furthermore, a security policy may block the caller from accessing this perimeter. If this occurs, an empty byte array will be returned and restricted will be set to true.

Parameters
type

The type of data requested from the clipboard.

restricted

If not 0, restricted is an out parameter that is set to true if data exists but is not accessible to the caller, false otherwise.

Return:

The raw clipboard data or an empty byte array if the type could not be found, if the data is not accessible to the caller, or if an error occurred.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus