-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
TIDOC-353 APIDOC UI.Clipboard rewrite #2269
Merged
Merged
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
41807cc
TIDOC-353 APIDOC UI.Clipboard rewrite
hal-gh 0b5e6df
TIDOC-353 APIDOC UI.Clipboard rewrite - rev1
hal-gh 6938ffa
TIDOC-353 APIDOC UI.Clipboard rewrite - rev2
hal-gh 785b03a
Merge branch 'master' of git://github.com/appcelerator/titanium_mobil…
hal-gh 58b212b
TIDOC-353 APIDOC UI.Clipboard rewrite - rev3
hal-gh 262bf87
Merge branch 'master' of git://github.com/appcelerator/titanium_mobil…
hal-gh 1384253
TIDOC-353 APIDOC UI.Clipboard rewrite - rev4
hal-gh 418601d
TIDOC-353 APIDOC UI.Clipboard rewrite - rev5
hal-gh File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,73 +1,135 @@ | ||
--- | ||
name: Titanium.UI.Clipboard | ||
summary: A module used for accessing clipboard data. | ||
description: | | ||
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 and Mobile Web, the module's `*Data()` methods enable multiple representations of the | ||
same data item to be stored together with their respective | ||
[MIME type](http://en.wikipedia.org/wiki/Internet_media_type) to describe their format. For | ||
example, `'text'` and `'text/plain'` for text, and `'image/jpg'` and `'image/png'` for an image. | ||
|
||
When working with text, either the `*Data()` methods may be used with a `'text/plain'` type, or | ||
the `*Text()` methods without the need to specify the type. | ||
|
||
Android currently only supports text type of data to be stored. | ||
|
||
#### Clipboard Data Types | ||
|
||
The `*Text()` methods are equivalent to calling `*Data()` 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.5" | ||
platforms: [android, iphone, ipad, mobileweb] | ||
|
||
methods: | ||
- name: clearData | ||
summary: Clear data of the given mime-type from the clipboard. If no mime-type is given, clear all data from the clipboard. | ||
summary: | | ||
Deletes data of the specified MIME type stored in the clipboard. If omitted, all data is | ||
deleted. | ||
description: On Android, identical to `clearText` method. | ||
parameters: | ||
- name: type | ||
summary: (optional) The mime-type of the data to clear. | ||
summary: MIME type. Ignored on Android. | ||
type: String | ||
optional: true | ||
|
||
- name: clearText | ||
summary: Clear the text portion of the clipboard. | ||
summary: Deletes all text data stored in the clipboard. | ||
description: | | ||
This method deletes any data saved using the `setText` method, or that has a `text` or | ||
`text/plain` MIME type. | ||
|
||
- name: getData | ||
summary: Get the data on the clipboard from the portion which contains data of the given mime-type. | ||
summary: Gets data of the specified MIME type stored in the clipboard. | ||
description: | | ||
This method does not work correctly due to the following issues: | ||
* Android: [TIMOB-9263](https://jira.appcelerator.org/browse/TIMOB-9263) | ||
* iOS: [TIMOB-9222](https://jira.appcelerator.org/browse/TIMOB-9222) | ||
returns: | ||
- type: String | ||
- type: Blob | ||
parameters: | ||
- name: type | ||
summary: The mime-type of the data to get. | ||
summary: MIME type. Must be text type on Android. | ||
type: String | ||
|
||
- name: getText | ||
summary: Get the current text on the clipboard. | ||
summary: Gets text data stored in the clipboard. | ||
returns: | ||
type: String | ||
|
||
- name: hasData | ||
summary: Return true if there is any content of the given mime-type on the clipboard. | ||
summary: Indicates whether any data of the specified MIME type is stored in the clipboard. | ||
description: | | ||
This method does not work correctly due to the following issues: | ||
* Android: [TIMOB-9263](https://jira.appcelerator.org/browse/TIMOB-9263) | ||
* iOS: [TIMOB-9222](https://jira.appcelerator.org/browse/TIMOB-9222) | ||
returns: | ||
type: Boolean | ||
parameters: | ||
- name: type | ||
summary: (optional) The mime-type of the data to check. | ||
summary: MIME type. Must be text type on Android. | ||
type: String | ||
|
||
- name: hasText | ||
summary: Return true if there is any content in the text portion of the clipboard. | ||
summary: Indicates whether any text data is stored in the clipboard. | ||
description: | | ||
On Android, returns Boolean. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Mobile Web also returns a Boolean. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed in next update. |
||
|
||
On iOS, returns `1` or `0` for `true` or `false`, respectively. | ||
returns: | ||
- type: Boolean | ||
- type: Number | ||
|
||
- name: setData | ||
summary: Set the data on the clipboard given a mime-type and the new data. This method will set data on the appropriate portion of the clipboard for the given mime-type. | ||
summary: Stores data of the specified MIME type in the clipboard. | ||
description: | | ||
This method does not work correctly due to the following issues: | ||
* Android: [TIMOB-9263](https://jira.appcelerator.org/browse/TIMOB-9263) | ||
|
||
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: The mime-type of the data to set. | ||
summary: MIME type. Must be text type on Android. | ||
type: String | ||
|
||
- name: data | ||
summary: The new clipboard text. | ||
summary: New item of data. | ||
type: Object | ||
|
||
- name: setText | ||
summary: Set the text on the clipboard. This will overwrite the current contents of the clipboard. | ||
summary: Stores text data in the clipboard. | ||
description: This method will overwrite any existing text data. | ||
parameters: | ||
- name: text | ||
summary: The new clipboard text. If the text is an empty string | ||
summary: New item of data. | ||
type: String | ||
|
||
examples: | ||
- title: Copying text to the clipboard | ||
- title: Copy Text to the Clipboard | ||
example: | | ||
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. | ||
|
||
copyButton.addEventListener('click', function() { | ||
Ti.UI.Clipboard.setText(data.url); | ||
}); | ||
|
||
- title: Pasting text from the clipboard | ||
example: | | ||
|
||
if (Ti.UI.Clipboard.hasText()) { | ||
doSomethingWith(Ti.UI.Clipboard.getText()); | ||
} else { | ||
alert('Hey there was no text.'); | ||
} | ||
|
||
- title: Clipboard data types | ||
example: | | ||
|
||
The *Text() functions are equivalent to calling *Data() with 'text' or 'text/plain' types, and work with plain Unicode strings. | ||
|
||
On Android, only plain text is supported; other MIME types will be ignored. | ||
|
||
On iOS, images will be returned as a <Titanium.Blob>; the special type 'image' or an explicit MIME type may be specified. URLs can be fetched with the special 'URL' or 'text/uri-list' types, and will return strings. Other data types may or may not be correctly mapped to clipboard types by the system, and will be retrieved as binary data in a <Titanium.Blob>. | ||
|
||
Ti.API.log('Deleting all text in Clipboard'); | ||
Ti.UI.Clipboard.clearText(); | ||
Ti.API.log('Clipboard.getText(): ' + Ti.UI.Clipboard.getText()); // returns empty string on Android and undefined on iOS | ||
Ti.API.log('Set text Clipboard to hello'); | ||
Ti.UI.Clipboard.setText('hello'); | ||
Ti.API.log('Clipboard.hasText(), should be true: ' + Ti.UI.Clipboard.hasText()); // returns true on Android and 1 on iOS | ||
Ti.API.log('Clipboard.getText(), should be hello: ' + Ti.UI.Clipboard.getText()); |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do you think it would beneficial if it said
If MIME type omitted
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I think that makes it clearer. Thank you.
Fixed in next update.