Konsep utama

Bagian berikut menjelaskan beberapa konsep utama untuk proses tarik lalu lepas.

Proses tarik lalu lepas

Ada empat langkah atau status dalam proses {i>drag-and-drop<i}: dimulai, melanjutkan, menurun, dan berakhir.

Dimulai

Sebagai respons terhadap gestur tarik pengguna, aplikasi Anda akan memanggil startDragAndDrop() untuk memberi tahu sistem agar memulai operasi tarik lalu lepas. Tujuan argumen metode menyediakan hal berikut:

• Data yang akan ditarik.
• Callback untuk menggambar bayangan tarik
• Metadata yang menjelaskan data yang ditarik
• Sistem merespons dengan melakukan callback ke aplikasi Anda untuk mendapatkan tarikan bayangan. Sistem kemudian menampilkan bayangan tarik di perangkat.
• Selanjutnya, sistem mengirimkan peristiwa tarik dengan jenis tindakan ACTION_DRAG_STARTED ke peristiwa tarik pemroses semua objek View dalam tata letak saat ini. Kepada terus menerima peristiwa tarik—termasuk kemungkinan penurunan —pemroses peristiwa tarik harus menampilkan true. Ini mendaftarkan pemroses dengan sistem. Hanya pemroses terdaftar yang melanjutkan ke menerima peristiwa tarik. Pada tahap ini, pemroses juga dapat mengubah tampilan objek View target lepasnya untuk menunjukkan bahwa tampilan dapat menerima peristiwa penurunan.
• Jika pemroses peristiwa tarik menampilkan false, pemroses tersebut tidak akan menerima tarik untuk operasi saat ini hingga sistem mengirimkan peristiwa tarik dengan jenis tindakan ACTION_DRAG_ENDED. Dengan menampilkan false, pemroses memberi tahu sistem bahwa ia tidak tertarik dalam operasi tarik lalu lepas dan tidak ingin menerima data yang ditarik.

Catatan: Nilai hasil false dari Pemicu View.OnDragListener pengendali onDragEvent() tampilan.

Melanjutkan

Pengguna melanjutkan tarikan. Saat bayangan {i>drag<i} berpotongan dengan kotak pembatas target lepas, sistem akan mengirim satu atau beberapa peristiwa tarik ke pemroses peristiwa tarik target. Pemroses mungkin mengubah tampilan target lepas View sebagai respons terhadap peristiwa. Misalnya, jika acara menunjukkan bahwa bayangan penyeretan memasuki kotak pembatas dari pelepasan target—jenis tindakan ACTION_DRAG_ENTERED —pemroses dapat bereaksi dengan menandai View.

Dilepas

Pengguna melepaskan bayangan tarik di dalam kotak pembatas lepas target. Sistem mengirimkan peristiwa tarik ke pemroses target lepas dengan tindakan ketik ACTION_DROP. Objek peristiwa tarik berisi data yang diteruskan ke sistem dalam panggilan ke startDragAndDrop() yang memulai operasi. Pemrosesnya adalah diharapkan akan menampilkan boolean true ke sistem jika pemroses berhasil memproses data yang dilepaskan. : Langkah ini hanya terjadi jika pengguna melepaskan bayangan tarik di dalam kotak pembatas View yang pemrosesnya terdaftar untuk menerima peristiwa tarik (target penurunan). Jika pengguna melepas bayangan tarik di situasi ini, tidak ada peristiwa tarik ACTION_DROP yang dikirim.

Berakhir

Setelah pengguna melepaskan bayangan penyeretan, dan setelah sistem mengirim

peristiwa tarik dengan jenis tindakan ACTION_DROP, jika perlu, sistem mengirim peristiwa tarik dengan jenis tindakan ACTION_DRAG_ENDED untuk menunjukkan bahwa operasi tarik lalu lepas selesai. Hal ini dilakukan di mana pun pengguna melepaskan bayangan {i>drag<i}. Peristiwa ini dikirim ke setiap pemroses yang terdaftar untuk menerima kejadian seret, bahkan jika pemroses juga menerima Peristiwa ACTION_DROP.

Masing-masing langkah ini dijelaskan secara lebih rinci di bagian yang disebut Operasi tarik lalu lepas.

Catatan: Jika aplikasi berjalan dalam mode multi-aplikasi, pengguna dapat menarik data dari satu aplikasi ke negara lain. Untuk informasi selengkapnya, lihat Tarik dan penurunan di bagian Dukungan mode multi-aplikasi.

Peristiwa tarik

Sistem mengirimkan peristiwa tarik dalam bentuk objek DragEvent, yang berisi jenis tindakan yang menjelaskan apa yang terjadi dalam mode tarik lalu lepas {i>checkout<i}. Tergantung pada jenis tindakan, objek juga dapat berisi data lain.

Pemroses peristiwa tarik menerima objek DragEvent. Untuk mendapatkan jenis tindakan, pemroses memanggil DragEvent.getAction(). Ada enam kemungkinan nilai yang ditentukan oleh konstanta di class DragEvent, yang dijelaskan dalam tabel 1:

Tabel 1. Jenis tindakan DragEvent

Jenis tindakan	Arti
ACTION_DRAG_STARTED	Aplikasi memanggil startDragAndDrop() dan memperoleh bayangan tarik. Jika pemroses ingin terus menerima peristiwa tarik untuk operasi ini, parameter harus menampilkan boolean true ke sistem file.
ACTION_DRAG_ENTERED	Bayangan tarik memasuki kotak pembatas dari pemroses peristiwa tarik View. Ini adalah jenis tindakan peristiwa pertama yang diproses terima ketika bayangan {i>drag<i} memasuki kotak pembatas.
ACTION_DRAG_LOCATION	Setelah Peristiwa ACTION_DRAG_ENTERED, bayangan tarik diam di dalam kotak pembatas dari pemroses peristiwa tarik View.
ACTION_DRAG_EXITED	Mengikuti ACTION_DRAG_ENTERED dan setidaknya satu Peristiwa ACTION_DRAG_LOCATION, bayangan tarik bergerak di luar kotak pembatas dari pemroses peristiwa tarik View.
ACTION_DROP	Bayangan tarik dilepas di atas pemroses peristiwa tarik View. Jenis tindakan ini dikirim ke View pemroses objek hanya jika pemroses menampilkan boolean true sebagai respons terhadap Peristiwa tarik ACTION_DRAG_STARTED. Jenis tindakan ini bukan dikirim jika pengguna melepaskan bayangan tarik di atas View yang pemrosesnya tidak terdaftar atau jika pengguna melepas fungsi tarik bayangan di atas apa pun yang bukan bagian dari tata letak saat ini. Pemroses menampilkan boolean true jika berhasil memproses pelepasan tersebut. Jika tidak, elemen ini harus menampilkan false.
ACTION_DRAG_ENDED	Sistem mengakhiri operasi tarik lalu lepas. Jenis tindakan ini tidak harus didahului oleh peristiwa ACTION_DROP. Jika sistem akan mengirimkan ACTION_DROP, yang menerima Jenis tindakan ACTION_DRAG_ENDED tidak menyiratkan bahwa berhasil dilepas. Pemroses harus memanggil getResult(), seperti yang ditunjukkan pada tabel 2, untuk mendapatkan nilai yang ditampilkan sebagai respons terhadap ACTION_DROP. Jika Peristiwa ACTION_DROP tidak dikirim, maka getResult() menampilkan false.

Objek DragEvent juga berisi data dan metadata yang diperlukan aplikasi yang diberikan ke sistem dalam panggilan ke startDragAndDrop(). Sebagian datanya hanya berlaku untuk jenis tindakan tertentu seperti yang diringkas dalam tabel 2. Untuk selengkapnya informasi tentang peristiwa dan data yang terkait, lihat bagian yang disebut A operasi tarik lalu lepas.

Tabel 2. Data DragEvent yang valid menurut jenis tindakan

getAction() nilai	getClipDescription() nilai	getLocalState() nilai	getX() nilai	getY() nilai	getClipData() nilai	getResult() nilai
ACTION_DRAG_STARTED	&periksa;	&periksa;
ACTION_DRAG_ENTERED	&periksa;	&periksa;
ACTION_DRAG_LOCATION	&periksa;	&periksa;	&periksa;	&periksa;
ACTION_DRAG_EXITED	&periksa;	&periksa;
ACTION_DROP	&periksa;	&periksa;	&periksa;	&periksa;	&periksa;
ACTION_DRAG_ENDED		&periksa;				&periksa;

Metode DragEvent berupa getAction(), describeContents(), writeToParcel(), dan toString() selalu mengembalikan data yang valid.

Jika sebuah metode tidak berisi data yang valid untuk jenis tindakan tertentu, metode ini akan menampilkan null atau 0, bergantung pada jenis hasilnya.

Bayangan tarik

Selama operasi tarik lalu lepas, sistem akan menampilkan gambar yang menarik. Untuk pemindahan data, gambar ini mewakili data yang sedang ditarik. Untuk operasi lainnya, gambar ini mewakili beberapa aspek operasi tarik.

Gambar ini disebut bayangan tarik. Anda membuatnya dengan metode yang Anda deklarasikan untuk suatu View.DragShadowBuilder . Anda meneruskan builder ke sistem saat Anda memulai operasi tarik lalu lepas operasi menggunakan startDragAndDrop(). Sebagai bagian dari responsnya terhadap startDragAndDrop(), sistem akan memanggil metode callback yang Anda tentukan di View.DragShadowBuilder untuk mendapatkan bayangan tarik.

Class View.DragShadowBuilder memiliki dua konstruktor:

View.DragShadowBuilder(View)

Konstruktor ini menerima objek View apa pun dari aplikasi Anda. Konstruktor menyimpan objek View dalam objek View.DragShadowBuilder, sehingga callback dapat mengaksesnya untuk mengonstruksi bayangan tarik. Tampilan tidak harus berupa View yang dipilih pengguna untuk memulai operasi tarik.

Jika menggunakan konstruktor ini, Anda tidak perlu memperluas View.DragShadowBuilder atau mengganti metodenya. Secara default, Anda mendapatkan tarik bayangan yang tampilannya sama dengan View yang Anda teruskan sebagai argumen, yang terpusat di bawah lokasi pengguna menyentuh layar.

View.DragShadowBuilder()

Jika Anda menggunakan konstruktor ini, tidak ada objek View yang tersedia di Objek View.DragShadowBuilder. Kolom ditetapkan ke null. Anda harus memperluas View.DragShadowBuilder lalu ganti metodenya, atau Anda akan mendapatkan bayangan tarik yang tidak terlihat. Sistem tidak menampilkan error.

Class View.DragShadowBuilder memiliki dua metode yang bersama-sama membuat operasi tarik {i>shadow<i}:

onProvideShadowMetrics()

Sistem akan memanggil metode ini segera setelah Anda memanggil startDragAndDrop(). Gunakan metode ini untuk mengirim dimensi dan titik sentuh bayangan tarik ke sistem. Metode ini memiliki dua parameter:

outShadowSize: Point . Lebar bayangan penyeretan masuk x, dan tingginya masuk y.

outShadowTouchPoint: objek Point. Titik sentuh adalah lokasi dalam bayangan penyeretan yang harus berada di bawah jari pengguna selama penyeretan. Posisi X-nya masuk di x dan posisi Y-nya masuk di y.

onDrawShadow()

Segera setelah panggilan ke onProvideShadowMetrics(), sistem akan memanggil onDrawShadow() untuk membuat bayangan tarik. Metode ini memiliki satu , objek Canvas yang konstruksi sistem dari parameter yang Anda berikan dalam onProvideShadowMetrics(). Metode ini menggambar bayangan tarik pada elemen Canvas.

Untuk meningkatkan performa, pertahankan ukuran bayangan tarik agar tetap kecil. Untuk satu item, Anda mungkin ingin menggunakan ikon. Untuk pilihan beberapa item, Anda dapat ingin menggunakan ikon dalam tumpukan daripada gambar penuh yang tersebar di seluruh layar.

Pemroses peristiwa tarik dan metode callback

View menerima peristiwa tarik dengan pemroses peristiwa tarik yang mengimplementasikan View.OnDragListener atau dengan metode callback onDragEvent() tampilan. Kapan sistem memanggil metode atau pemroses, sistem akan menyediakan Argumen DragEvent.

Umumnya, saat menggunakan pemroses lebih baik menggunakan metode callback. Saat mendesain UI, biasanya Anda tidak membuat subclass untuk class View, tetapi menggunakan metode callback akan memaksa Anda membuat subclass untuk mengganti metode. Sebagai perbandingan, Anda dapat mengimplementasikan satu class pemroses lalu menggunakannya dengan beberapa objek View yang berbeda. Anda juga dapat mengimplementasikannya sebagai class inline anonim atau ekspresi lambda. Untuk menetapkan pemroses bagi objek View, panggil setOnDragListener().

Sebagai alternatif, Anda dapat mengubah implementasi default onDragEvent() tanpa mengganti metodenya. Setel OnReceiveContentListener pada tampilan; untuk detail selengkapnya, lihat setOnReceiveContentListener(). Metode onDragEvent() kemudian akan melakukan hal berikut secara default:

• Menampilkan true (benar) sebagai respons terhadap panggilan ke startDragAndDrop().

• Panggilan performReceiveContent() jika data tarik lalu lepas dilepaskan pada tampilan. Data diteruskan ke sebagai objek ContentInfo. Tujuan metode akan memanggil OnReceiveContentListener.

• Menampilkan true (benar) jika data tarik lalu lepas dilepas pada tampilan dan OnReceiveContentListener menggunakan semua konten.

Tentukan OnReceiveContentListener guna menangani data secara khusus untuk . Untuk kompatibilitas mundur hingga API level 24, gunakan versi Jetpack dari OnReceiveContentListener

Anda dapat memiliki pemroses peristiwa tarik dan metode callback untuk objek View, di dalam hal ini sistem akan terlebih dahulu memanggil pemroses. Sistem tidak memanggil metode callback kecuali jika pemroses menampilkan false.

Kombinasi metode onDragEvent() dan View.OnDragListener adalah setara dengan kombinasi onTouchEvent() dan View.OnTouchListener digunakan pada kejadian sentuh.

Istilah Penting: Bagian berikut merujuk pada metode yang menerima peristiwa tarik sebagai pemroses peristiwa tarik. Namun, metode ini dapat berupa onDragEvent() callback, metode View.OnDragListener, atau keduanya.