You are reading 12.6.0. See this page in 13.4.1.
Titanium.UI.Clipboard
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
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.
Inherited from Titanium.Proxy
The name of the API that this proxy corresponds to.
Inherited from Titanium.Proxy
Indicates if the proxy will bubble an event to its parent.
Default: true
Inherited from Titanium.Proxy
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
Create a new named clipboard.
Create a new clipboard with a given name. See the example on how to use this.
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 | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. 4 fields
|
applyProperties
since 3.0.0Inherited from Titanium.Proxy
Applies the properties to the proxy.
| Parameters | Type | Description |
|---|---|---|
| props | Dictionary | A dictionary of properties to apply. |
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 | Type | Description |
|---|---|---|
| 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 | 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. |
Gets data of the specified MIME type stored in the clipboard. Returns null if non-text mimetype on Android.
| Parameters | Type | Description |
|---|---|---|
| type | String | MIME type. Must be 'text' or 'text/plain' on Android, or else null is returned. |
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.
Gets text data stored in the clipboard.
Indicates whether any colors are stored in the clipboard.
Indicates whether any data of the specified MIME type is stored in the clipboard.
| Parameters | Type | Description |
|---|---|---|
| type? | String | MIME type. Must be 'text' or 'text/plain' on Android (or it will return false). |
Indicates whether any images are stored in the clipboard.
Indicates whether any text data is stored in the clipboard.
Indicates whether any URLs are stored in the clipboard.
Removes the clipboard.
Inherited from Titanium.Proxy
Removes the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to 4 fields
|
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 | Type | Description |
|---|---|---|
| type | String | MIME type. Must be 'text' or 'text/plain' on Android.
Possible types include: |
| data | Object | String | Titanium.Blob | Titanium.Filesystem.File | Titanium.UI.Color | New item of data. |
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 | 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. 2 fields
|
Stores text data in the clipboard.
This method will overwrite any existing text data.
| Parameters | Type | Description |
|---|---|---|
| text | String | New item of data. |