ClipboardManager Class Reference

Programmatic clipboard access. More...

Inherits GDClipboardManagerInterface.

Description

This class provides programmatic access to clipboard data, which may have been protected by BlackBerry Dynamics if required by enterprise policy. Clipboard data is used in cut-copy-paste operations, and in drag and drop interactions.

There are BlackBerry Dynamics replacements for a number of methods in the native android.content.ClipboardManager programming interface. There are also methods that can be used to implement drag and drop operations in a custom View class.

Replacement Clipboard Manager Interface

The BlackBerry Dynamics runtime may secure or block text in transit to or from the clipboard, depending on the policies for data leakage prevention (DLP) at the enterprise that the end user represents. The runtime secures text by encrypting it when it is cut or copied to the device clipboard, and then decrypting it when it is pasted from the clipboard.

Use methods in this class for programmatic access to the clipboard, instead of methods in the native ClipboardManager class. The methods in this class will encrypt, decrypt, or block data as necessary, which the native methods do not.

The following limitations apply to this class.

• Only text is supported, not other types of data. Only pass in ClipData objects with textual Item contents, for example created with the ClipData.Item(CharSequence) constructor.
• Methods that are deprecated in the native android.content.ClipboardManager programming interface aren't implemented:
  • getText()
  • hasText()
  • setText()

Otherwise, the replacement methods have the same names and semantics as the native. For example, getPrimaryClip() in this class reads data from the clipboard.

Drag and Drop Implementation

An end user can transfer data within a mobile application, and between mobile applications, by using drag and drop operations. The transfer of data by drag and drop may be secured or blocked by the BlackBerry Dynamics runtime. The runtime secures the payload data in a drag and drop interaction in the same way as clipboard data, see above.

A custom View in an application that supports drag and drop operations can use the methods in this class in its implementation.

The methods for drag and drop implementation in this class have the same names as similar native methods, or the same names as the interfaces from which they would be called. For example, startDragAndDrop() would be called from the custom startDragAndDrop implementation.

See also

GDAndroid.getApplicationConfig for background on DLP policies.

The source code of the SecureCopyPaste sample application that comes with the BlackBerry Dynamics Software Development Kit for Android. The code illustrates usage of this class.

ClipboardManager on the android.com developer website.

View on the android.com developer website for background on supporting drag and drop operations. Look for the startDragAndDrop method documentation.

com.good.gd.widget package reference for details of replacement classes for user interface elements.

Public Member Functions
void	addPrimaryClipChangedListener (android.content.ClipboardManager.OnPrimaryClipChangedListener what)
	Replacement. More...
void	removePrimaryClipChangedListener (android.content.ClipboardManager.OnPrimaryClipChangedListener what)
	Replacement. More...
ClipData	getPrimaryClip ()
	Replacement for reading from the clipboard. More...
ClipDescription	getPrimaryClipDescription ()
	Replacement for getting a description of what is on the clipboard. More...
boolean	hasPrimaryClip ()
	Replacement for checking whether the clipboard has data. More...
void	setPrimaryClip (ClipData clipData)
	Replacement for writing to the clipboard. More...
void	clearPrimaryClip ()
	Clears primary clip in clipboard. More...
void	startDragAndDrop (ClipData clipData, View view)
	Initialise drag and drop interaction with defaults. More...
void	startDragAndDrop (ClipData clipData, View view, View.DragShadowBuilder shadowBuilder, Object myLocalState)
	Initialise drag and drop interaction with state. More...
void	startDragAndDrop (ClipData clipData, View view, View.DragShadowBuilder shadowBuilder, Object myLocalState, int flags)
	Initialise drag and drop interaction with all parameters. More...
ClipData	getClipData (DragEvent event)
	Retrieve payload from a drag and drop interaction. More...

Static Public Member Functions
static ClipboardManager	getInstance (Context context)
	Get a reference to the Clipboard Manager object. More...

Static Public Attributes
static final int	CLIPDATA_TEXT_SIZE_LIMIT = 1024 * 100
	Maximum supported clip size in bytes. More...

Member Function Documentation

getInstance()

static ClipboardManager getInstance ( Context  context )

static

This method returns a reference to the BlackBerry Dynamics Clipboard Manager object. The Clipboard Manager is a "singleton class".

Returns

Reference that can be used to call, for example, getPrimaryClip().

addPrimaryClipChangedListener()

void addPrimaryClipChangedListener

(

android.content.ClipboardManager.OnPrimaryClipChangedListener

what

)

This method has the same semantics as the native method of the same name. See the ClipboardManager on the android.com developer website.

removePrimaryClipChangedListener()

void removePrimaryClipChangedListener

(

android.content.ClipboardManager.OnPrimaryClipChangedListener

what

)

This method has the same semantics as the native method of the same name. See the ClipboardManager on the android.com developer website.

getPrimaryClip()

ClipData getPrimaryClip

(

)

This method returns data from the clipboard and has the same semantics as the native method of the same name, with the following exceptions.

• If the data on the clipboard was encrypted by BlackBerry Dynamics, then it is decrypted before being returned.
• If pasting the data would be blocked by the current enterprise DLP policy settings, then null is returned.

See also

ClipboardManager on the android.com developer website.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

getPrimaryClipDescription()

ClipDescription getPrimaryClipDescription

(

)

This method returns a description of the data on the clipboard and has the same semantics as the native method of the same name, with the following exceptions.

• If pasting the data would be blocked by the current enterprise DLP policy settings, then null is returned.

See also

ClipboardManager on the android.com developer website.

hasPrimaryClip()

boolean hasPrimaryClip

(

)

This method checks whether there is data on the clipboard and has the same semantics as the native method of the same name, with the following exceptions.

• If there is data on the clipboard but pasting it would be blocked by the current enterprise DLP policy settings, then this method returns false.

See also

ClipboardManager on the android.com developer website.

setPrimaryClip()

void setPrimaryClip

(

ClipData

clipData

)

This method writes data to the clipboard and has the same semantics as the native method of the same name, with the following exceptions.

• The data will be encrypted by the BlackBerry Dynamics runtime before being sent to the system clipboard, if required by the current enterprise DLP policy settings.

See also

ClipboardManager on the android.com developer website.

Exceptions

com.good.gd.error.GDNotAuthorizedError	if BlackBerry Dynamics authorization processing has not yet completed.
IllegalArgumentException	if the amount of data to be written exceeds CLIPDATA_TEXT_SIZE_LIMIT.

clearPrimaryClip()

void clearPrimaryClip

(

)

This method clears system clipboard and has the same semantics as the native method of the same name, with the following exceptions.

• Primary clip will be cleared only if clipboard has primary clip set previously

See also

ClipboardManager on the android.com developer website.

startDragAndDrop() [1/3]

void startDragAndDrop	(	ClipData	clipData,
		View	view
	)

Call this method as part of a custom drag and drop implementation.

Calling this method is equivalent to calling startDragAndDrop(ClipData, View, View.DragShadowBuilder, Object, int), below, and passing:

• null for the View.DragShadowBuilder.
• null for the Object.
• View.DRAG_FLAG_GLOBAL for the int, if the target Android API level is 24 or higher.
• Zero for the int, if the target Android API level is lower than 24.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

startDragAndDrop() [2/3]

void startDragAndDrop	(	ClipData	clipData,
		View	view,
		View.DragShadowBuilder	shadowBuilder,
		Object	myLocalState
	)

Call this method as part of a custom drag and drop implementation.

Calling this method is equivalent to calling startDragAndDrop(ClipData, View, View.DragShadowBuilder, Object, int), below, and passing:

• View.DRAG_FLAG_GLOBAL for the int, if the target Android API level is 24 or higher.
• Zero for the int, if the target Android API level is lower than 24.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

startDragAndDrop() [3/3]

void startDragAndDrop	(	ClipData	clipData,
		View	view,
		View.DragShadowBuilder	shadowBuilder,
		Object	myLocalState,
		int	flags
	)

This method initialises a BlackBerry Dynamics drag and drop operation, in which the payload is protected in the same way as data on the clipboard is protected. Call this method as part of a custom drag and drop interaction, for example, from within the startDragAndDrop method of a custom View.

The parameters have the same semantics as the parameters of the same names in the native View.startDragAndDrop interface, except as noted in the following.

Parameters

clipData	ClipData object containing the payload of the drag and drop operation, as in the native interface. The payload will be encrypted by the BlackBerry Dynamics runtime, if the enterprise DLP settings require.
view	View instance for the start of the drag and drop interaction.
shadowBuilder	View.ShadowBuilder object used to build a shadow, as in the native interface. This parameter is ignored if the enterprise DLP settings require that the payload is encrypted. In that case, a BlackBerry Dynamics View.ShadowBuilder object is substituted. If null is passed, and there is no substitution, a default shadow is built, based on the view parameter.
myLocalState	Same as native interface.
flags	int value representating a number of flags, as in the native interface. Any flags that contravene enterprise DLP settings are ignored.

The variants of this method, above, omit some parameters. Omitted parameter will take default values as follows.

• shadowBuilder will be null.
• myLocalState will be null.
• flags will be View.DRAG_FLAG_GLOBAL if the target Android API level is 24 or higher, or zero if the API level is lower than 24.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

See also

View on the android.com developer website for documentation of the startDragAndDrop interface.

getClipData()

ClipData getClipData

(

DragEvent

event

)

Call this method to retrieve the payload of a BlackBerry Dynamics drag and drop operation, which may have been protected in the same way as data on the clipboard. Pass as a parameter the drag event from the system.

This method has the same semantics as the native android.view.DragEvent.getClipData method, with the following exceptions:

• If the event represents a drop action, and the payload was encrypted by BlackBerry Dynamics, then it is decrypted before being returned.
• If the payload would be blocked by the current enterprise DLP policy settings, then null is returned.
• It isn't a method of the DragEvent class. It takes a DragEvent instance as a parameter.

Returns

ClipData object containing the payload of the drag and drop operation, or null.

Exceptions

com.good.gd.error.GDNotAuthorizedError

if BlackBerry Dynamics authorization processing has not yet completed.

See also

DragEvent on the android.com developer website.

Member Data Documentation

CLIPDATA_TEXT_SIZE_LIMIT

final int CLIPDATA_TEXT_SIZE_LIMIT = 1024 * 100

static

This constant represents the maximum clip size, in bytes, that is supported by the methods in this class.