1 page.title=Copy and Paste 2 page.tags="clipboardmanager","clipdata","input" 3 @jd:body 4 <div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>Quickview</h2> 7 <ul> 8 <li> 9 A clipboard-based framework for copying and pasting data. 10 </li> 11 <li> 12 Supports both simple and complex data, including text strings, complex data 13 structures, text and binary stream data, and application assets. 14 </li> 15 <li> 16 Copies and pastes simple text directly to and from the clipboard. 17 </li> 18 <li> 19 Copies and pastes complex data using a content provider. 20 </li> 21 <li> 22 Requires API 11. 23 </li> 24 </ul> 25 <h2>In this document</h2> 26 <ol> 27 <li> 28 <a href="#Clipboard">The Clipboard Framework</a> 29 </li> 30 <li> 31 <a href="#ClipboardClasses">Clipboard Classes</a> 32 <ol> 33 <li> 34 <a href="#ClipboardManager">ClipboardManager</a> 35 </li> 36 <li> 37 <a href="#ClipClasses"> 38 ClipData, ClipDescription, and ClipData.Item 39 </a> 40 </li> 41 <li> 42 <a href="#ClipDataMethods">ClipData convenience methods</a> 43 </li> 44 <li> 45 <a href="#CoerceToText">Coercing the clipboard data to text</a> 46 </li> 47 </ol> 48 </li> 49 <li> 50 <a href="#Copying">Copying to the Clipboard</a> 51 </li> 52 <li> 53 <a href="#Pasting">Pasting from the Clipboard</a> 54 <ol> 55 <li> 56 <a href="#PastePlainText">Pasting plain text</a> 57 </li> 58 <li> 59 <a href="#PasteContentUri">Pasting data from a content URI</a> 60 </li> 61 <li> 62 <a href="#PasteIntent">Pasting an Intent</a> 63 </li> 64 </ol> 65 </li> 66 <li> 67 <a href="#Provider">Using Content Providers to Copy Complex Data</a> 68 <ol> 69 <li> 70 <a href="#Encoding">Encoding an identifier on the URI</a> 71 </li> 72 <li> 73 <a href="#Records">Copying data structures</a> 74 </li> 75 <li> 76 <a href="#Streams">Copying data streams</a> 77 </li> 78 </ol> 79 </li> 80 <li> 81 <a href="#DataDesign">Designing Effective Copy/Paste Functionality</a> 82 </li> 83 </ol> 84 <h2>Key classes</h2> 85 <ol> 86 <li> 87 {@link android.content.ClipboardManager ClipboardManager} 88 </li> 89 <li> 90 {@link android.content.ClipData ClipData} 91 </li> 92 <li> 93 {@link android.content.ClipData.Item ClipData.Item} 94 </li> 95 <li> 96 {@link android.content.ClipDescription ClipDescription} 97 </li> 98 <li> 99 {@link android.net.Uri Uri} 100 </li> 101 <li> 102 {@link android.content.ContentProvider} 103 </li> 104 <li> 105 {@link android.content.Intent Intent} 106 </li> 107 </ol> 108 <h2>Related Samples</h2> 109 <ol> 110 <li> 111 <a href="{@docRoot}resources/samples/NotePad/index.html"> 112 Note Pad sample application</a> 113 </li> 114 </ol> 115 <h2>See also</h2> 116 <ol> 117 <li> 118 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> 119 </li> 120 </ol> 121 </div> 122 </div> 123 <p> 124 Android provides a powerful clipboard-based framework for copying and pasting. It 125 supports both simple and complex data types, including text strings, complex data 126 structures, text and binary stream data, and even application assets. Simple text data is stored 127 directly in the clipboard, while complex data is stored as a reference that the pasting 128 application resolves with a content provider. Copying and pasting works both within an 129 application and between applications that implement the framework. 130 </p> 131 132 <p> 133 Since a part of the framework uses content providers, this topic assumes some 134 familiarity with the Android Content Provider API, which is described in the topic 135 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. 136 </p> 137 <h2 id="Clipboard">The Clipboard Framework</h2> 138 <p> 139 When you use the clipboard framework, you put data into a clip object, and then 140 put the clip object on the system-wide clipboard. The clip object can take one of three forms: 141 </p> 142 <dl> 143 <dt>Text</dt> 144 <dd> 145 A text string. You put the string directly into the clip object, which you then put onto 146 the clipboard. To paste the string, you get the clip object from the clipboard and copy 147 the string to into your application's storage. 148 </dd> 149 <dt>URI</dt> 150 <dd> 151 A {@link android.net.Uri} object representing any form of URI. This is primarily for 152 copying complex data from a content provider. To copy data, you put a 153 {@link android.net.Uri} object into a clip object and put the clip object onto 154 the clipboard. To paste the data, you get the clip object, get the 155 {@link android.net.Uri} object, resolve it to a data source such as a content provider, 156 and copy the data from the source into your application's storage. 157 </dd> 158 <dt>Intent</dt> 159 <dd> 160 An {@link android.content.Intent}. This supports copying application shortcuts. To copy 161 data, you create an Intent, put it into a clip object, and put the clip object onto the 162 clipboard. To paste the data, you get the clip object and then copy the Intent object 163 into your application's memory area. 164 </dd> 165 </dl> 166 <p> 167 The clipboard holds only one clip object at a time. When an application puts a clip object on 168 the clipboard, the previous clip object disappears. 169 </p> 170 <p> 171 If you want to allow users to paste data into your application, you don't have to handle all 172 types of data. You can examine the data on the clipboard before you give users the option to 173 paste it. Besides having a certain data form, the clip object also contains metadata that tells 174 you what MIME type or types are available. This metadata helps you decide if your application 175 can do something useful with the clipboard data. For example, if you have an application that 176 primarily handles text you may want to ignore clip objects that contain a URI or Intent. 177 </p> 178 <p> 179 You may also want to allow users to paste text regardless of the form of data on the 180 clipboard. To do this, you can force the clipboard data into a text representation, and then 181 paste this text. This is described in the section <a href="#CoerceToText">Coercing the 182 clipboard to text</a>. 183 </p> 184 <h2 id="ClipboardClasses">Clipboard Classes</h2> 185 <p> 186 This section describes the classes used by the clipboard framework. 187 </p> 188 <h3 id="ClipboardManager">ClipboardManager</h3> 189 <p> 190 In the Android system, the system clipboard is represented by the global 191 {@link android.content.ClipboardManager} class. You do not instantiate this 192 class directly; instead, you get a reference to it by invoking 193 {@link android.content.Context#getSystemService(String) getSystemService(CLIPBOARD_SERVICE)}. 194 </p> 195 <h3 id="ClipClasses">ClipData, ClipData.Item, and ClipDescription</h3> 196 <p> 197 To add data to the clipboard, you create a {@link android.content.ClipData} object that 198 contains both a description of the data and the data itself. The clipboard holds only one 199 {@link android.content.ClipData} at a time. A {@link android.content.ClipData} contains a 200 {@link android.content.ClipDescription} object and one or more 201 {@link android.content.ClipData.Item} objects. 202 </p> 203 <p> 204 A {@link android.content.ClipDescription} object contains metadata about the clip. In 205 particular, it contains an array of available MIME types for the clip's data. When you put a 206 clip on the clipboard, this array is available to pasting applications, which can examine it to 207 see if they can handle any of available the MIME types. 208 </p> 209 <p> 210 A {@link android.content.ClipData.Item} object contains the text, URI, or Intent data: 211 </p> 212 <dl> 213 <dt>Text</dt> 214 <dd> 215 A {@link java.lang.CharSequence}. 216 </dd> 217 <dt>URI</dt> 218 <dd> 219 A {@link android.net.Uri}. This usually contains a content provider URI, although any 220 URI is allowed. The application that provides the data puts the URI on the clipboard. 221 Applications that want to paste the data get the URI from the clipboard and use it to 222 access the content provider (or other data source) and retrieve the data. 223 </dd> 224 <dt>Intent</dt> 225 <dd> 226 An {@link android.content.Intent}. This data type allows you to copy an application shortcut 227 to the clipboard. Users can then paste the shortcut into their applications for later use. 228 </dd> 229 </dl> 230 <p> 231 You can add more than one {@link android.content.ClipData.Item} object to a clip. This allows 232 users to copy and paste multiple selections as a single clip. For example, if you have a list 233 widget that allows the user to select more than one item at a time, you can copy all the items 234 to the clipboard at once. To do this, you create a separate 235 {@link android.content.ClipData.Item} for each list item, and then you add the 236 {@link android.content.ClipData.Item} objects to the {@link android.content.ClipData} object. 237 </p> 238 <h3 id="ClipDataMethods">ClipData convenience methods</h3> 239 <p> 240 The {@link android.content.ClipData} class provides static convenience methods for creating 241 a {@link android.content.ClipData} object with a single {@link android.content.ClipData.Item} 242 object and a simple {@link android.content.ClipDescription} object: 243 </p> 244 <dl> 245 <dt> 246 {@link android.content.ClipData#newPlainText(CharSequence,CharSequence) newPlainText(label, text)} 247 </dt> 248 <dd> 249 Returns a {@link android.content.ClipData} object whose single 250 {@link android.content.ClipData.Item} object contains a text string. The 251 {@link android.content.ClipDescription} object's label is set to <code>label</code>. 252 The single MIME type in {@link android.content.ClipDescription} is 253 {@link android.content.ClipDescription#MIMETYPE_TEXT_PLAIN}. 254 <p> 255 Use 256 {@link android.content.ClipData#newPlainText(CharSequence,CharSequence) newPlainText()} 257 to create a clip from a text string. 258 </dd> 259 <dt> 260 {@link android.content.ClipData#newUri(ContentResolver, CharSequence, Uri) newUri(resolver, label, URI)} 261 </dt> 262 <dd> 263 Returns a {@link android.content.ClipData} object whose single 264 {@link android.content.ClipData.Item} object contains a URI. The 265 {@link android.content.ClipDescription} object's label is set to <code>label</code>. 266 If the URI is a content URI ({@link android.net.Uri#getScheme() Uri.getScheme()} returns 267 <code>content:</code>), the method uses the {@link android.content.ContentResolver} object 268 provided in <code>resolver</code> to retrieve the available MIME types from the 269 content provider and store them in {@link android.content.ClipDescription}. For a URI that 270 is not a <code>content:</code> URI, the method sets the MIME type to 271 {@link android.content.ClipDescription#MIMETYPE_TEXT_URILIST}. 272 <p> 273 Use 274 {@link android.content.ClipData#newUri(ContentResolver, CharSequence, Uri) newUri()} 275 to create a clip from a URI, particularly a <code>content:</code> URI. 276 </p> 277 </dd> 278 <dt> 279 {@link android.content.ClipData#newIntent(CharSequence, Intent) newIntent(label, intent)} 280 </dt> 281 <dd> 282 Returns a {@link android.content.ClipData} object whose single 283 {@link android.content.ClipData.Item} object contains an {@link android.content.Intent}. 284 The {@link android.content.ClipDescription} object's label is set to <code>label</code>. 285 The MIME type is set to {@link android.content.ClipDescription#MIMETYPE_TEXT_INTENT}. 286 <p> 287 Use 288 {@link android.content.ClipData#newIntent(CharSequence, Intent) newIntent()} 289 to create a clip from an Intent object. 290 </dd> 291 </dl> 292 <h3 id="CoerceToText">Coercing the clipboard data to text</h3> 293 <p> 294 Even if your application only handles text, you can copy non-text data from the 295 clipboard by converting it with the method 296 {@link android.content.ClipData.Item#coerceToText(Context) ClipData.Item.coerceToText()}. 297 </p> 298 <p> 299 This method converts the data in {@link android.content.ClipData.Item} to text and 300 returns a {@link java.lang.CharSequence}. The value that 301 {@link android.content.ClipData.Item#coerceToText(Context) ClipData.Item.coerceToText()} 302 returns is based on the form of data in {@link android.content.ClipData.Item}: 303 </p> 304 <dl> 305 <dt><em>Text</em></dt> 306 <dd> 307 If {@link android.content.ClipData.Item} is text 308 ({@link android.content.ClipData.Item#getText()} is not null), 309 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} returns the 310 text. 311 </dd> 312 <dt><em>URI</em></dt> 313 <dd> 314 If {@link android.content.ClipData.Item} is a URI 315 ({@link android.content.ClipData.Item#getUri()} is not null), 316 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} tries to use 317 it as a content URI: 318 <ul> 319 <li> 320 If the URI is a content URI and the provider can return a text stream, 321 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} returns 322 a text stream. 323 </li> 324 <li> 325 If the URI is a content URI but the provider does not offer a text stream, 326 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} returns 327 a representation of the URI. The representation is the same as that returned by 328 {@link android.net.Uri#toString() Uri.toString()}. 329 </li> 330 <li> 331 If the URI is not a content URI, 332 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} returns 333 a representation of the URI. The representation is the same as that returned by 334 {@link android.net.Uri#toString() Uri.toString()}. 335 </li> 336 </ul> 337 </dd> 338 <dt><em>Intent</em></dt> 339 <dd> 340 If {@link android.content.ClipData.Item} is an Intent 341 ({@link android.content.ClipData.Item#getIntent()} is not null), 342 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} converts it to 343 an Intent URI and returns it. The representation is the same as that returned by 344 {@link android.content.Intent#toUri(int) Intent.toUri(URI_INTENT_SCHEME)}. 345 </dd> 346 </dl> 347 <p> 348 The clipboard framework is summarized in Figure 1. To copy data, an application puts a 349 {@link android.content.ClipData} object on the {@link android.content.ClipboardManager} global 350 clipboard. The {@link android.content.ClipData} contains one or more 351 {@link android.content.ClipData.Item} objects and one 352 {@link android.content.ClipDescription} object. To paste data, an application gets the 353 {@link android.content.ClipData}, gets its MIME type from the 354 {@link android.content.ClipDescription}, and gets the data either from 355 the {@link android.content.ClipData.Item} or from the content provider referred to by 356 {@link android.content.ClipData.Item}. 357 </p> 358 <a name="framework"></a> 359 <img 360 src="{@docRoot}images/ui/clipboard/copy_paste_framework.png" 361 alt="A block diagram of the copy and paste framework" height="400px" id="figure1" /> 362 <p class="img-caption"> 363 <strong>Figure 1.</strong> The Android clipboard framework 364 </p> 365 <h2 id="Copying">Copying to the Clipboard</h2> 366 <p> 367 As described previously, to copy data to the clipboard you get a handle to the global 368 {@link android.content.ClipboardManager} object, create a {@link android.content.ClipData} 369 object, add a {@link android.content.ClipDescription} and one or more 370 {@link android.content.ClipData.Item} objects to it, and add the finished 371 {@link android.content.ClipData} object to the {@link android.content.ClipboardManager} object. 372 This is described in detail in the following procedure: 373 </p> 374 <ol> 375 <li> 376 If you are copying data using a content URI, set up a content 377 provider. 378 <p> 379 The <a href="{@docRoot}resources/samples/NotePad/index.html"> 380 Note Pad</a> sample application is an example of using a content provider for 381 copying and pasting. The 382 <a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NotePadProvider.html"> 383 NotePadProvider</a> class implements the content provider. The 384 <a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NotePad.html"> 385 NotePad</a> class defines a contract between the provider and other applications, 386 including the supported MIME types. 387 </p> 388 </li> 389 <li> 390 Get the system clipboard: 391 <pre> 392 393 ... 394 395 // if the user selects copy 396 case R.id.menu_copy: 397 398 // Gets a handle to the clipboard service. 399 ClipboardManager clipboard = (ClipboardManager) 400 getSystemService(Context.CLIPBOARD_SERVICE); 401 </pre> 402 </li> 403 <li> 404 <p> 405 Copy the data to a new {@link android.content.ClipData} object: 406 </p> 407 <ul> 408 <li> 409 <h4>For text</h4> 410 <pre> 411 // Creates a new text clip to put on the clipboard 412 ClipData clip = ClipData.newPlainText("simple text","Hello, World!"); 413 </pre> 414 </li> 415 <li> 416 <h4>For a URI</h4> 417 <p> 418 This snippet constructs a URI by encoding a record ID onto the content URI 419 for the provider. This technique is covered in more detail 420 in the section <a href="#Encoding">Encoding an identifier on the URI</a>: 421 </p> 422 <pre> 423 // Creates a Uri based on a base Uri and a record ID based on the contact's last name 424 // Declares the base URI string 425 private static final String CONTACTS = "content://com.example.contacts"; 426 427 // Declares a path string for URIs that you use to copy data 428 private static final String COPY_PATH = "/copy"; 429 430 // Declares the Uri to paste to the clipboard 431 Uri copyUri = Uri.parse(CONTACTS + COPY_PATH + "/" + lastName); 432 433 ... 434 435 // Creates a new URI clip object. The system uses the anonymous getContentResolver() object to 436 // get MIME types from provider. The clip object's label is "URI", and its data is 437 // the Uri previously created. 438 ClipData clip = ClipData.newUri(getContentResolver(),"URI",copyUri); 439 </pre> 440 </li> 441 <li> 442 <h4>For an Intent</h4> 443 <p> 444 This snippet constructs an Intent for an application 445 and then puts it in the clip object: 446 </p> 447 <pre> 448 // Creates the Intent 449 Intent appIntent = new Intent(this, com.example.demo.myapplication.class); 450 451 ... 452 453 // Creates a clip object with the Intent in it. Its label is "Intent" and its data is 454 // the Intent object created previously 455 ClipData clip = ClipData.newIntent("Intent",appIntent); 456 </pre> 457 </li> 458 </ul> 459 </li> 460 <li> 461 Put the new clip object on the clipboard: 462 <pre> 463 // Set the clipboard's primary clip. 464 clipboard.setPrimaryClip(clip); 465 </pre> 466 </li> 467 </ol> 468 <h2 id="Pasting">Pasting from the Clipboard</h2> 469 <p> 470 As described previously, you paste data from the clipboard by getting the global clipboard 471 object, getting the clip object, looking at its data, and if possible copying the data from 472 the clip object to your own storage. This section describes in detail how to do this for 473 the three forms of clipboard data. 474 </p> 475 <h3 id="PastePlainText">Pasting plain text</h3> 476 <p> 477 To paste plain text, first get the global clipboard and verify that it can return plain text. 478 Then get the clip object and copy its text to your own storage using 479 {@link android.content.ClipData.Item#getText()}, as described in the following procedure: 480 </p> 481 <ol> 482 <li> 483 Get the global {@link android.content.ClipboardManager} object using 484 {@link android.content.Context#getSystemService(String) getSystemService(CLIPBOARD_SERVICE)}. Also 485 declare a global variable to contain the pasted text: 486 <pre> 487 ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE); 488 489 String pasteData = ""; 490 491 </pre> 492 </li> 493 <li> 494 Next, determine if you should enable or disable the "paste" option in the 495 current Activity. You should verify that the clipboard contains a clip and that you 496 can handle the type of data represented by the clip: 497 <pre> 498 // Gets the ID of the "paste" menu item 499 MenuItem mPasteItem = menu.findItem(R.id.menu_paste); 500 501 // If the clipboard doesn't contain data, disable the paste menu item. 502 // If it does contain data, decide if you can handle the data. 503 if (!(clipboard.hasPrimaryClip())) { 504 505 mPasteItem.setEnabled(false); 506 507 } else if (!(clipboard.getPrimaryClipDescription().hasMimeType(MIMETYPE_TEXT_PLAIN))) { 508 509 // This disables the paste menu item, since the clipboard has data but it is not plain text 510 mPasteItem.setEnabled(false); 511 } else { 512 513 // This enables the paste menu item, since the clipboard contains plain text. 514 mPasteItem.setEnabled(true); 515 } 516 } 517 </pre> 518 </li> 519 <li> 520 Copy the data from the clipboard. This point in the program is only reachable if the 521 "paste" menu item is enabled, so you can assume that the clipboard contains 522 plain text. You do not yet know if it contains a text string or a URI that points to plain 523 text. The following snippet tests this, but it only shows the code for handling plain text: 524 <pre> 525 // Responds to the user selecting "paste" 526 case R.id.menu_paste: 527 528 // Examines the item on the clipboard. If getText() does not return null, the clip item contains the 529 // text. Assumes that this application can only handle one item at a time. 530 ClipData.Item item = clipboard.getPrimaryClip().getItemAt(0); 531 532 // Gets the clipboard as text. 533 pasteData = item.getText(); 534 535 // If the string contains data, then the paste operation is done 536 if (pasteData != null) { 537 return; 538 539 // The clipboard does not contain text. If it contains a URI, attempts to get data from it 540 } else { 541 Uri pasteUri = item.getUri(); 542 543 // If the URI contains something, try to get text from it 544 if (pasteUri != null) { 545 546 // calls a routine to resolve the URI and get data from it. This routine is not 547 // presented here. 548 pasteData = resolveUri(Uri); 549 return; 550 } else { 551 552 // Something is wrong. The MIME type was plain text, but the clipboard does not contain either 553 // text or a Uri. Report an error. 554 Log.e("Clipboard contains an invalid data type"); 555 return; 556 } 557 } 558 </pre> 559 </li> 560 </ol> 561 <h3 id="PasteContentUri">Pasting data from a content URI</h3> 562 <p> 563 If the {@link android.content.ClipData.Item} object contains a content URI and you 564 have determined that you can handle one of its MIME types, create a 565 {@link android.content.ContentResolver} and then call the appropriate content provider 566 method to retrieve the data. 567 </p> 568 <p> 569 The following procedure describes how to get data from a content provider based on a 570 content URI on the clipboard. It checks that a MIME type that the application can use 571 is available from the provider: 572 </p> 573 <ol> 574 <li> 575 Declare a global variable to contain the MIME type: 576 <pre> 577 // Declares a MIME type constant to match against the MIME types offered by the provider 578 public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact" 579 </pre> 580 </li> 581 <li> 582 Get the global clipboard. Also get a content resolver so you can access the content 583 provider: 584 <pre> 585 // Gets a handle to the Clipboard Manager 586 ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE); 587 588 // Gets a content resolver instance 589 ContentResolver cr = getContentResolver(); 590 </pre> 591 </li> 592 <li> 593 Get the primary clip from the clipboard, and get its contents as a URI: 594 <pre> 595 // Gets the clipboard data from the clipboard 596 ClipData clip = clipboard.getPrimaryClip(); 597 598 if (clip != null) { 599 600 // Gets the first item from the clipboard data 601 ClipData.Item item = clip.getItemAt(0); 602 603 // Tries to get the item's contents as a URI 604 Uri pasteUri = item.getUri(); 605 </pre> 606 </li> 607 <li> 608 Test to see if the URI is a content URI by calling 609 {@link android.content.ContentResolver#getType(Uri) getType(Uri)}. This method returns 610 null if <code>Uri</code> does not point to a valid content provider: 611 <pre> 612 // If the clipboard contains a URI reference 613 if (pasteUri != null) { 614 615 // Is this a content URI? 616 String uriMimeType = cr.getType(pasteUri); 617 </pre> 618 </li> 619 <li> 620 Test to see if the content provider supports a MIME type that the current application 621 understands. If it does, call 622 {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) 623 ContentResolver.query()} to get the data. The return value is a 624 {@link android.database.Cursor}: 625 <pre> 626 // If the return value is not null, the Uri is a content Uri 627 if (uriMimeType != null) { 628 629 // Does the content provider offer a MIME type that the current application can use? 630 if (uriMimeType.equals(MIME_TYPE_CONTACT)) { 631 632 // Get the data from the content provider. 633 Cursor pasteCursor = cr.query(uri, null, null, null, null); 634 635 // If the Cursor contains data, move to the first record 636 if (pasteCursor != null) { 637 if (pasteCursor.moveToFirst()) { 638 639 // get the data from the Cursor here. The code will vary according to the 640 // format of the data model. 641 } 642 } 643 644 // close the Cursor 645 pasteCursor.close(); 646 } 647 } 648 } 649 } 650 </pre> 651 </li> 652 </ol> 653 <h3 id="PasteIntent">Pasting an Intent</h3> 654 <p> 655 To paste an Intent, first get the global clipboard. Examine the 656 {@link android.content.ClipData.Item} object to see if it contains an Intent. Then call 657 {@link android.content.ClipData.Item#getIntent()} to copy the Intent to your own storage. 658 The following snippet demonstrates this: 659 </p> 660 <pre> 661 // Gets a handle to the Clipboard Manager 662 ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE); 663 664 // Checks to see if the clip item contains an Intent, by testing to see if getIntent() returns null 665 Intent pasteIntent = clipboard.getPrimaryClip().getItemAt(0).getIntent(); 666 667 if (pasteIntent != null) { 668 669 // handle the Intent 670 671 } else { 672 673 // ignore the clipboard, or issue an error if your application was expecting an Intent to be 674 // on the clipboard 675 } 676 </pre> 677 <h2 id="Provider">Using Content Providers to Copy Complex Data</h2> 678 <p> 679 Content providers support copying complex data such as database records or file streams. 680 To copy the data, you put a content URI on the clipboard. Pasting applications then get this 681 URI from the clipboard and use it to retrieve database data or file stream descriptors. 682 </p> 683 <p> 684 Since the pasting application only has the content URI for your data, it needs to know which 685 piece of data to retrieve. You can provide this information by encoding an identifier for the 686 data on the URI itself, or you can provide a unique URI that will return the data you want to 687 copy. Which technique you choose depends on the organization of your data. 688 </p> 689 <p> 690 The following sections describe how to set up URIs, how to provide complex data, and how to 691 provide file streams. The descriptions assume that you are familiar with the general principles 692 of content provider design. 693 </p> 694 <h3 id="Encoding">Encoding an identifier on the URI</h3> 695 <p> 696 A useful technique for copying data to the clipboard with a URI is to encode an identifier for 697 the data on the URI itself. Your content provider can then get the identifier from the URI and 698 use it to retrieve the data. The pasting application doesn't have to know that the identifier 699 exists; all it has to do is get your "reference" (the URI plus the identifier) from 700 the clipboard, give it your content provider, and get back the data. 701 </p> 702 <p> 703 You usually encode an identifier onto a content URI by concatenating it to the end of the URI. 704 For example, suppose you define your provider URI as the following string: 705 </p> 706 <pre> 707 "content://com.example.contacts" 708 </pre> 709 <p> 710 If you want to encode a name onto this URI, you would use the following snippet: 711 </p> 712 <pre> 713 String uriString = "content://com.example.contacts" + "/" + "Smith" 714 715 // uriString now contains content://com.example.contacts/Smith. 716 717 // Generates a uri object from the string representation 718 Uri copyUri = Uri.parse(uriString); 719 </pre> 720 <p> 721 If you are already using a content provider, you may want to add a new URI path that indicates 722 the URI is for copying. For example, suppose you already have the following URI paths: 723 </p> 724 <pre> 725 "content://com.example.contacts"/people 726 "content://com.example.contacts"/people/detail 727 "content://com.example.contacts"/people/images 728 </pre> 729 <p> 730 You could add another path that is specific to copy URIs: 731 </p> 732 <pre> 733 "content://com.example.contacts/copying" 734 </pre> 735 <p> 736 You could then detect a "copy" URI by pattern-matching and handle it with code that 737 is specific for copying and pasting. 738 </p> 739 <p> 740 You normally use the encoding technique if you're already using a content provider, internal 741 database, or internal table to organize your data. In these cases, you have multiple pieces of 742 data you want to copy, and presumably a unique identifier for each piece. In response to a 743 query from the pasting application, you can look up the data by its identifier and return it. 744 </p> 745 <p> 746 If you don't have multiple pieces of data, then you probably don't need to encode an identifier. 747 You can simply use a URI that is unique to your provider. In response to a query, your provider 748 would return the data it currently contains. 749 </p> 750 <p> 751 Getting a single record by ID is used in the 752 <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application to 753 open a note from the notes list. The sample uses the <code>_id</code> field from an SQL 754 database, but you can have any numeric or character identifier you want. 755 </p> 756 <h3 id="Records">Copying data structures</h3> 757 <p> 758 You set up a content provider for copying and pasting complex data as a subclass of the 759 {@link android.content.ContentProvider} component. You should also encode the URI you put on 760 the clipboard so that it points to the exact record you want to provide. In addition, you 761 have to consider the existing state of your application: 762 </p> 763 <ul> 764 <li> 765 If you already have a content provider, you can add to its functionality. You may only 766 need to modify its 767 {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) query()} 768 method to handle URIs coming from applications that want to paste data. You will 769 probably want to modify the method to handle a "copy" URI pattern. 770 </li> 771 <li> 772 If your application maintains an internal database, you may 773 want to move this database into a content provider to facilitate copying from it. 774 </li> 775 <li> 776 If you are not currently using a database, you can implement a simple content provider 777 whose sole purpose is to offer data to applications that are pasting from the 778 clipboard. 779 </li> 780 </ul> 781 <p> 782 In the content provider, you will want to override at least the following methods: 783 </p> 784 <dl> 785 <dt> 786 {@link android.content.ContentResolver#query(Uri, String[], String, String[], String) query()} 787 </dt> 788 <dd> 789 Pasting applications will assume that they can get your data by using this method with 790 the URI you put on the clipboard. To support copying, you should have this method 791 detect URIs that contain a special "copy" path. Your application can then 792 create a "copy" URI to put on the clipboard, containing the copy path and 793 a pointer to the exact record you want to copy. 794 </dd> 795 <dt> 796 {@link android.content.ContentProvider#getType(Uri) getType()} 797 </dt> 798 <dd> 799 This method should return the MIME type or types for the data you intend to copy. The method 800 {@link android.content.ClipData#newUri(ContentResolver, CharSequence, Uri) newUri()} calls 801 {@link android.content.ContentProvider#getType(Uri) getType()} in order to put the MIME 802 types into the new {@link android.content.ClipData} object. 803 <p> 804 MIME types for complex data are described in the topic 805 <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. 806 </p> 807 </dd> 808 </dl> 809 <p> 810 Notice that you don't have to have any of the other content provider methods such as 811 {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} or 812 {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) update()}. 813 A pasting application only needs to get your supported MIME types and copy data from your 814 provider. If you already have these methods, they won't interfere with copy operations. 815 </p> 816 <p> 817 The following snippets demonsrate how to set up your application to copy complex data: 818 </p> 819 <ol> 820 <li> 821 <p> 822 In the global constants for your application, 823 declare a base URI string and a path that identifies URI strings you are 824 using to copy data. Also declare a MIME type for the copied data: 825 </p> 826 <pre> 827 // Declares the base URI string 828 private static final String CONTACTS = "content://com.example.contacts"; 829 830 // Declares a path string for URIs that you use to copy data 831 private static final String COPY_PATH = "/copy"; 832 833 // Declares a MIME type for the copied data 834 public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact" 835 </pre> 836 </li> 837 <li> 838 In the Activity from which users copy data, 839 set up the code to copy data to the clipboard. In response to a copy request, put 840 the URI on the clipboard: 841 <pre> 842 public class MyCopyActivity extends Activity { 843 844 ... 845 846 // The user has selected a name and is requesting a copy. 847 case R.id.menu_copy: 848 849 // Appends the last name to the base URI 850 // The name is stored in "lastName" 851 uriString = CONTACTS + COPY_PATH + "/" + lastName; 852 853 // Parses the string into a URI 854 Uri copyUri = Uri.parse(uriString); 855 856 // Gets a handle to the clipboard service. 857 ClipboardManager clipboard = (ClipboardManager) 858 getSystemService(Context.CLIPBOARD_SERVICE); 859 860 ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri); 861 862 // Set the clipboard's primary clip. 863 clipboard.setPrimaryClip(clip); 864 </pre> 865 </li> 866 867 <li> 868 <p> 869 In the global scope of your content provider, create a URI matcher and add a URI 870 pattern that will match URIs you put on the clipboard: 871 </p> 872 <pre> 873 public class MyCopyProvider extends ContentProvider { 874 875 ... 876 877 // A Uri Match object that simplifies matching content URIs to patterns. 878 private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH); 879 880 // An integer to use in switching based on the incoming URI pattern 881 private static final int GET_SINGLE_CONTACT = 0; 882 883 ... 884 885 // Adds a matcher for the content URI. It matches 886 // "content://com.example.contacts/copy/*" 887 sUriMatcher.addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT); 888 </pre> 889 </li> 890 <li> 891 <p> 892 Set up the 893 {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) query()} 894 method. This method can handle different URI patterns, depending on how you code it, but 895 only the pattern for the clipboard copying operation is shown: 896 </p> 897 <pre> 898 // Sets up your provider's query() method. 899 public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, 900 String sortOrder) { 901 902 ... 903 904 // Switch based on the incoming content URI 905 switch (sUriMatcher.match(uri)) { 906 907 case GET_SINGLE_CONTACT: 908 909 // query and return the contact for the requested name. Here you would decode 910 // the incoming URI, query the data model based on the last name, and return the result 911 // as a Cursor. 912 913 ... 914 915 } 916 </pre> 917 </li> 918 <li> 919 <p> 920 Set up the {@link android.content.ContentProvider#getType(Uri) getType()} method to 921 return an appropriate MIME type for copied data: 922 </p> 923 <pre> 924 // Sets up your provider's getType() method. 925 public String getType(Uri uri) { 926 927 ... 928 929 switch (sUriMatcher.match(uri)) { 930 931 case GET_SINGLE_CONTACT: 932 933 return (MIME_TYPE_CONTACT); 934 </pre> 935 </li> 936 </ol> 937 <p> 938 The section <a href="#PasteContentUri">Pasting data from a content URI</a> 939 describes how to get a content URI from the clipboard and use it to get and paste data. 940 </p> 941 <h3 id="Streams">Copying data streams</h3> 942 <p> 943 You can copy and paste large amounts of text and binary data as streams. The data can have 944 forms such as the following: 945 </p> 946 <ul> 947 <li> 948 Files stored on the actual device. 949 </li> 950 <li> 951 Streams from sockets. 952 </li> 953 <li> 954 Large amounts of data stored in a provider's underlying database system. 955 </li> 956 </ul> 957 <p> 958 A content provider for data streams provides access to its data with a file descriptor object 959 such as {@link android.content.res.AssetFileDescriptor} instead of a 960 {@link android.database.Cursor} object. The pasting application reads the data stream using 961 this file descriptor. 962 </p> 963 <p> 964 To set up your application to copy a data stream with a provider, follow these steps: 965 </p> 966 <ol> 967 <li> 968 Set up a content URI for the data stream you are putting on the clipboard. Options 969 for doing this include the following: 970 <ul> 971 <li> 972 Encode an identifier for the data stream onto the URI, 973 as described in the section 974 <a href="#Encoding">Encoding an identifier on the URI</a>, and then maintain a 975 table in your provider that contains identifiers and the corresponding stream name. 976 </li> 977 <li> 978 Encode the stream name directly on the URI. 979 </li> 980 <li> 981 Use a unique URI that always returns the current stream from the provider. If you 982 use this option, you have to remember to update your provider to point to a 983 different stream whenever you copy the stream to the clipboard via the URI. 984 </li> 985 </ul> 986 </li> 987 <li> 988 Provide a MIME type for each type of data stream you plan to offer. Pasting applications 989 need this information to determine if they can paste the data on the clipboard. 990 </li> 991 <li> 992 Implement one of the {@link android.content.ContentProvider} methods that returns 993 a file descriptor for a stream. If you encode identifiers on the content URI, use this 994 method to determine which stream to open. 995 </li> 996 <li> 997 To copy the data stream to the clipboard, construct the content URI and place it 998 on the clipboard. 999 </li> 1000 </ol> 1001 <p> 1002 To paste a data stream, an application gets the clip from the clipboard, gets the URI, and 1003 uses it in a call to a {@link android.content.ContentResolver} file descriptor method that 1004 opens the stream. The {@link android.content.ContentResolver} method calls the corresponding 1005 {@link android.content.ContentProvider} method, passing it the content URI. Your provider 1006 returns the file descriptor to {@link android.content.ContentResolver} method. The pasting 1007 application then has the responsibility to read the data from the stream. 1008 </p> 1009 <p> 1010 The following list shows the most important file descriptor methods for a content provider. 1011 Each of these has a corresponding {@link android.content.ContentResolver} method with the 1012 string "Descriptor" appended to the method name; for example, the 1013 {@link android.content.ContentResolver} analog of 1014 {@link android.content.ContentProvider#openAssetFile(Uri, String) openAssetFile()} is 1015 {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) openAssetFileDescriptor()}: 1016 </p> 1017 <dl> 1018 <dt> 1019 {@link android.content.ContentProvider#openTypedAssetFile(Uri,String,Bundle) openTypedAssetFile()} 1020 </dt> 1021 <dd> 1022 This method should return an asset file descriptor, but only if the provided MIME type is 1023 supported by the provider. The caller (the application doing the pasting) provides a MIME 1024 type pattern. The content provider (of the application that has copied a URI to the 1025 clipboard) returns an {@link android.content.res.AssetFileDescriptor} file handle if it 1026 can provide that MIME type, or throws an exception if it can not. 1027 <p> 1028 This method handles subsections of files. You can use it to read assets that the 1029 content provider has copied to the clipboard. 1030 </p> 1031 </dd> 1032 <dt> 1033 {@link android.content.ContentProvider#openAssetFile(Uri, String) openAssetFile()} 1034 </dt> 1035 <dd> 1036 This method is a more general form of 1037 {@link android.content.ContentProvider#openTypedAssetFile(Uri,String,Bundle) openTypedAssetFile()}. 1038 It does not filter for allowed MIME types, but it can read subsections of files. 1039 </dd> 1040 <dt> 1041 {@link android.content.ContentProvider#openFile(Uri, String) openFile()} 1042 </dt> 1043 <dd> 1044 This is a more general form of 1045 {@link android.content.ContentProvider#openAssetFile(Uri, String) openAssetFile()}. It can't 1046 read subsections of files. 1047 </dd> 1048 </dl> 1049 <p> 1050 You can optionally use the 1051 {@link android.content.ContentProvider#openPipeHelper(Uri, String, Bundle, T, ContentProvider.PipeDataWriter) openPipeHelper()} 1052 method with your file descriptor method. This allows the pasting application to read the 1053 stream data in a background thread using a pipe. To use this method, you need to implement the 1054 {@link android.content.ContentProvider.PipeDataWriter} interface. An example of doing this is 1055 given in the <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample 1056 application, in the <code>openTypedAssetFile()</code> method of 1057 <code>NotePadProvider.java</code>. 1058 </p> 1059 <h2 id="DataDesign">Designing Effective Copy/Paste Functionality</h2> 1060 <p> 1061 To design effective copy and paste functionality for your application, remember these 1062 points: 1063 </p> 1064 <ul> 1065 <li> 1066 At any time, there is only one clip on the clipboard. A new copy operation by 1067 any application in the system overwrites the previous clip. Since the user may 1068 navigate away from your application and do a copy before returning, you can't assume 1069 that the clipboard contains the clip that the user previously copied in <em>your</em> 1070 application. 1071 </li> 1072 <li> 1073 The intended purpose of multiple {@link android.content.ClipData.Item} 1074 objects per clip is to support copying and pasting of multiple selections rather than 1075 different forms of reference to a single selection. You usually want all of the 1076 {@link android.content.ClipData.Item} objects in a clip to have the same form, that is, 1077 they should all be simple text, content URI, or {@link android.content.Intent}, but not 1078 a mixture. 1079 </li> 1080 <li> 1081 When you provide data, you can offer different MIME representations. Add the MIME types 1082 you support to the {@link android.content.ClipDescription}, and then 1083 implement the MIME types in your content provider. 1084 </li> 1085 <li> 1086 When you get data from the clipboard, your application is responsible for checking the 1087 available MIME types and then deciding which one, if any, to use. Even if there is a 1088 clip on the clipboard and the user requests a paste, your application is not required 1089 to do the paste. You <em>should</em> do the paste if the MIME type is compatible. You 1090 may choose to coerce the data on the clipboard to text using 1091 {@link android.content.ClipData.Item#coerceToText(Context) coerceToText()} if you 1092 choose. If your application supports more than one of the available MIME types, you can 1093 allow the user to choose which one to use. 1094 </li> 1095 </ul> 1096
