Titanium.UI.Clipboard

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.

Extends: Titanium.Module · Since: 1.8.0, 1.5.0, 1.5.0, 9.2.0 · Platforms: android, iphone, ipad, macos

Properties #

allowCreation#

creation only

Type: 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#

extended

Type: 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, Button
returns Ti.UI.Button.

bubbleParent#

extended

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

lifecycleContainer#

extended

Type: 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

Type: 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

Type: 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 #

extended

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

Parameters:

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

applyProperties #

extended

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	Summary	Optional
`props`	`Dictionary`	A dictionary of properties to apply.	No

clearData #

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	Summary	Optional
`type`	`String`	MIME type. Ignored on Android.	Yes

clearText #

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.

fireEvent #

extended

Fires a synthesized event to any registered listeners.

Parameters:

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

getData #

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

Parameters:

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

Returns: String, Titanium.Blob

getItems #

Gets the items that have been specified earlier using Titanium.UI.Clipboard.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: Array<Dictionary>

getText #

Gets text data stored in the clipboard.

Returns: String

hasColors #

Indicates whether any colors are stored in the clipboard.

Returns: Boolean

hasData #

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

Parameters:

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

Returns: Boolean

hasImages #

Indicates whether any images are stored in the clipboard.

Returns: Boolean

hasText #

Indicates whether any text data is stored in the clipboard.

Returns: Boolean

hasURLs #

Indicates whether any URLs are stored in the clipboard.

Returns: Boolean

remove #

Removes the clipboard.

removeEventListener #

extended

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	Summary	Optional
`name`	`String`	Name of the event.	No
`callback`	`Callback<Titanium.Event>`	Callback function to remove. Must be the same function passed to `addEventListener`.	No

setData #

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	Summary	Optional
`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	No
`data`	`Object, String, Titanium.Blob, Titanium.Filesystem.File, Titanium.UI.Color`	New item of data.	No

setItems #

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:

Name	Type	Summary	Optional
`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.	No

setText #

Stores text data in the clipboard.

This method will overwrite any existing text data.

Parameters:

Name	Type	Summary	Optional
`text`	`String`	New item of data.	No

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());

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.UI.Clipboard ​

Clipboard Data Types ​

Properties #

allowCreation#

apiName#

bubbleParent#

lifecycleContainer#

name#

unique#

Methods #

addEventListener #

applyProperties #

clearData #

clearText #

fireEvent #

getData #

getItems #

getText #

hasColors #

hasData #

hasImages #

hasText #

hasURLs #

remove #

removeEventListener #

setData #

setItems #

setText #

Examples #

Copy Text to the Clipboard

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

Use of named clipboard in iOS

Use of unique named clipboard in iOS

Titanium.UI.Clipboard

Clipboard Data Types