# Titanium.UI.Clipboard

A module used for accessing clipboard data.

Availability

1.8.0

1.5.0

9.2.0

Extends

Titanium.Module

# Overview

The Clipboard is a temporary data store, used to save a single item of data that may then be accessed by the user using UI copy and paste interactions within an app or between apps.

On iOS, the module's setData() and getData() methods enable multiple representations of the same data item to be stored together with their respective MIME type (opens new window) to describe their format. For example, 'text' and 'text/plain' for text, and 'image/jpg' and 'image/png' for an image. iOS Will report back the type of data representation in getItems() as Universal Type Identifiers (opens new window).

When working with text, either of the getData()/setData() methods may be used with a 'text/plain' type, or the getText()/hasText()/setText() methods without the need to specify the type.

Android currently only supports text data to be stored.

# Clipboard Data Types

The getText()/hasText()/setText() methods are equivalent to calling getData()/setData() with a 'text' or 'text/plain' type. These work with plain Unicode strings.

An image is stored using the 'image' type, or an explicit image MIME type, and is returned as a Titanium.Blob (binary) type.

A URL is stored with the 'url' or 'text/uri-list' type, and is returned as a string.

Any data type that is specified but not correctly mapped to a clipboard type by the system is retrieved as a Titanium.Blob type.

# Examples

# Copy Text to the Clipboard

Clear the clipboard and output the resulting empty clipboard to console.

Then, store the string, "hello", to the clipboard and output it from the clipboard to the console.

Ti.API.info('Deleting all text in Clipboard');
Ti.UI.Clipboard.clearText();
Ti.API.info('Clipboard.getText(): ' + Ti.UI.Clipboard.getText()); // returns empty string on Android and undefined on iOS
Ti.API.info('Set text Clipboard to hello');
Ti.UI.Clipboard.setText('hello');
Ti.API.info('Clipboard.hasText(), should be true: ' + Ti.UI.Clipboard.hasText()); // returns true on Android and 1 on iOS
Ti.API.info('Clipboard.getText(), should be hello: ' + Ti.UI.Clipboard.getText());

# Set multiple items including privacy options (iOS 10 and later)

The items are represented as an array that holds different objects of key-value items. Optionally, you can set privacy options described in Ti.UI.CLIPBOARD_OPTION_*. Note that you can not have the same two keys in one object and the key must match a valid mime-type. If no valid mime-type is specified

var win = Ti.UI.createWindow({
    backgroundColor: "#fff"
});

var btn1 = Ti.UI.createButton({
    title: "Set clipboard items",
    top: 40
});

var btn2 = Ti.UI.createButton({
    title: "Get clipboard items",
    top: 80
});

btn1.addEventListener("click", function () {
  const options = {};
  options[Ti.UI.CLIPBOARD_OPTION_LOCAL_ONLY] = true;
  options[Ti.UI.CLIPBOARD_OPTION_EXPIRATION_DATE] = new Date(2030, 4, 20);

    Ti.UI.Clipboard.setItems({
      items: [{
          "text/plain": "John",
      },{
          "text/plain": "Doe"
      }],
      options
  });
});

btn2.addEventListener("click", function () {
    alert(Ti.UI.Clipboard.getItems());
});

win.add(btn1);
win.add(btn2);
win.open();

# Use of named clipboard in iOS

var clipboard1 = Ti.UI.createClipboard({
    name: 'myClipboard',
    allowCreation: true
});
clipboard1.setText('hello');

var clipboard2 = Ti.UI.createClipboard({
    name: 'myClipboard'
});

Ti.API.info('Clipboard name is: ' + clipboard1.name);
Ti.API.info('Both clipboards should return "hello"');
Ti.API.info('clipboard1.getText() ' + clipboard1.getText());
Ti.API.info('clipboard2.getText() ' + clipboard2.getText());

# Use of unique named clipboard in iOS

var clipboard = Ti.UI.createClipboard({
    unique: true
});
clipboard.setText('hello');

Ti.API.info('clipboard name is: ' + clipboard.name);
Ti.API.info('clipboard.getText() ' + clipboard.getText());

# Properties

# allowCreation CREATION ONLY

Availability

6.1.0

9.2.0

allowCreation :Boolean

Create a clipboard identified by name if it doesn't exist.

If "create" is false, it will return the existing named clipboard but will not create new one. If "create" is true, it will return the existing clipboard (if exists). Otherwise it will create new clipboard with given name.

# apiName READONLY

Availability

3.2.0

9.2.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability

3.0.0

9.2.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# lifecycleContainer

Availability

3.6.0

lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# name CREATION ONLY

Availability

6.1.0

9.2.0

name :String

Create a new named clipboard.

Create a new clipboard with a given name. See the example on how to use this.

# unique CREATION ONLY

Availability

6.1.0

9.2.0

unique :Boolean

Create a new clipboard identified by a unique system-generated name.

Create a new clipboard identified by a unique system-generated name. See the example on how to use this.

# Methods

# addEventListener

Availability

1.8.0

1.5.0

9.2.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type: void

# applyProperties

Availability

3.0.0

9.2.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
`props`	Dictionary	A dictionary of properties to apply.

Returns

Type: void

# clearData

Availability

1.8.0

1.5.0

9.2.0

clearData([type]) → void

Deletes data of the specified MIME type stored in the clipboard. If MIME type omitted, all data is deleted.

On Android, identical to the clearText() method.

Parameters

Name	Type	Description
`type`	String	MIME type. Ignored on Android.

Returns

Type: void

# clearText

Availability

1.8.0

1.5.0

9.2.0

clearText() → void

Deletes all text data stored in the clipboard.

This method deletes any data saved using the setText method, or that has a text or text/plain MIME type.

Returns

Type: void

# fireEvent

Availability

1.8.0

1.5.0

9.2.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
`name`	String	Name of the event.
`event`	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type: void

# getData

Availability

1.8.0

1.5.0

9.2.0

getData(type) → String | Titanium.Blob

Gets data of the specified MIME type stored in the clipboard. Returns null if non-text mimetype on Android.

Parameters

Name	Type	Description
`type`	String	MIME type. Must be 'text' or 'text/plain' on Android, or else null is returned.

Returns

Type: String | Titanium.Blob

# getItems

Availability

5.5.0

9.2.0

getItems() → Array<Dictionary>

Gets the items that have been specified earlier using setItems.

The returned Array contains simple Objects whose keys are the reported Universal Type Identifiers reported by iOS; and values are the underlying object/data.

Returns

Type: Array<Dictionary>

# getText

Availability

1.8.0

1.5.0

9.2.0

getText() → String

Gets text data stored in the clipboard.

Returns

Type: String

# hasColors

Availability

6.0.0

9.2.0

hasColors() → Boolean

Indicates whether any colors are stored in the clipboard.

Returns

Type: Boolean

# hasData

Availability

1.8.0

1.5.0

9.2.0

hasData([type]) → Boolean

Indicates whether any data of the specified MIME type is stored in the clipboard.

Parameters

Name	Type	Description
`type`	String	MIME type. Must be 'text' or 'text/plain' on Android (or it will return false).

Returns

Type: Boolean

# hasImages

Availability

6.0.0

9.2.0

hasImages() → Boolean

Indicates whether any images are stored in the clipboard.

Returns

Type: Boolean

# hasText

Availability

1.8.0

1.5.0

9.2.0

hasText() → Boolean

Indicates whether any text data is stored in the clipboard.

Returns

Type: Boolean

# hasURLs

Availability

6.0.0

9.2.0

hasURLs() → Boolean

Indicates whether any URLs are stored in the clipboard.

Returns

Type: Boolean

# remove

Availability

6.1.0

9.2.0

remove() → void

Removes the clipboard.

Returns

Type: void

# removeEventListener

Availability

1.8.0

1.5.0

9.2.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
`name`	String	Name of the event.
`callback`	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`.

Returns

Type: void

# setData

Availability

1.8.0

1.5.0

9.2.0

setData(type, data) → void

Stores data of the specified MIME type in the clipboard.

This method will overwrite any existing data for the specified MIME type.

Note that the clipboard is intended to store only one item of data at a time. This method enables different representations/formats of a data item to be saved.

Parameters

Name	Type	Description
`type`	String	MIME type. Must be 'text' or 'text/plain' on Android. Possible types include: `'text', 'text/plain', 'color', 'image', 'url', 'text/uri-list'`. iOS also supports Universal Type Identifiers
`data`	Object \| String \| Titanium.Blob \| Titanium.Filesystem.File \| Titanium.UI.Color	New item of data.

Returns

Type: void

# setItems

Availability

5.5.0

9.2.0

setItems(items) → void

Adds an array of items to a clipboard, and sets privacy options for all included items.

You can pass multiple options to the options object. Note that this API is mime-type based. The key must be a valid mime-type and the value must be the value that matches the given mime-type. If no valid mime-type is provided a a key, receiving items with getItems will crash the app. See the below example for more information on the usage.

Parameters

Name	Type	Description
`items`	ClipboardItemsType	An array of key-value items to add to the clipboard. The key must a valid mime-type matching the mime-type of the value.

Returns

Type: void

# setText

Availability

1.8.0

1.5.0

9.2.0

setText(text) → void

Stores text data in the clipboard.

This method will overwrite any existing text data.

Parameters

Name	Type	Description
`text`	String	New item of data.

Returns

Type: void