Skip to content
Titanium SDK
Version13.1.1

You are reading 13.1.1. See this page in 13.4.1.

Titanium.UI.Clipboard

moduleAndroidiPhoneiPadmacOSsince Android 1.8.0, iPhone 1.5.0, iPad 1.5.0, macOS 9.2.0

Extends Titanium.ModuleTitanium.Proxy

A module used for accessing clipboard data.

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 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.

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 6

allowCreation

BooleaniPhoneiPadmacOSsince 6.1.0

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

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

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

Default: true

name

StringiPhoneiPadmacOSsince 6.1.0

Create a new named clipboard.

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

unique

BooleaniPhoneiPadmacOSsince 6.1.0

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 18

Inherited from Titanium.Proxy

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

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to invoke when the event is fired.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

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
ParametersTypeDescription
type?String

MIME type. Ignored on Android.

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.

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
ParametersTypeDescription
nameString

Name of the event.

event?Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

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

Parameters
ParametersTypeDescription
typeString

MIME type. Must be 'text' or 'text/plain' on Android, or else null is returned.

Returns String | Titanium.Blob

Gets text data stored in the clipboard.

Returns String

hasColors

iPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

Indicates whether any colors are stored in the clipboard.

Returns Boolean

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

Parameters
ParametersTypeDescription
type?String

MIME type. Must be 'text' or 'text/plain' on Android (or it will return false).

Returns Boolean

hasImages

iPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

Indicates whether any images are stored in the clipboard.

Returns Boolean

Indicates whether any text data is stored in the clipboard.

Returns Boolean

hasURLs

iPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, macOS 9.2.0

Indicates whether any URLs are stored in the clipboard.

Returns Boolean

remove

iPhoneiPadmacOSsince 6.1.0

Removes the clipboard.

Inherited from Titanium.Proxy

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

Parameters
ParametersTypeDescription
nameString

Name of the event.

callbackCallback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

4 fields
bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.

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
ParametersTypeDescription
typeString

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

dataObject | String | Titanium.Blob | Titanium.Filesystem.File | Titanium.UI.Color

New item of data.

setItems

iPhoneiPadmacOSsince iPhone 5.5.0, iPad 5.5.0, macOS 9.2.0

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 Titanium.UI.Clipboard.getItems will crash the app. See the below example for more information on the usage.

Parameters
ParametersTypeDescription
itemsClipboardItemsType

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.

2 fields
items Array<Dictionary>

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. Alterntaively, iOS supports using Universal Type Identifiers

options Dictionary

The privacy options to apply to all the items on the clipboard. The available options are described in Ti.UI.CLIPBOARD_OPTION_*. Depending on the key, the value can be a Date or Boolean.

Stores text data in the clipboard.

This method will overwrite any existing text data.

Parameters
ParametersTypeDescription
textString

New item of data.