diff options
Diffstat (limited to 'docs/html-intl/intl/in')
33 files changed, 21264 insertions, 0 deletions
diff --git a/docs/html-intl/intl/in/guide/components/activities.jd b/docs/html-intl/intl/in/guide/components/activities.jd new file mode 100644 index 000000000000..6cac69638f49 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/activities.jd @@ -0,0 +1,756 @@ +page.title=Aktivitas +page.tags=aktivitas,intent +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#Creating">Membuat Aktivitas</a> + <ol> + <li><a href="#UI">Mengimplementasikan antarmuka pengguna</a></li> + <li><a href="#Declaring">Mendeklarasikan aktivitas dalam manifes</a></li> + </ol> + </li> + <li><a href="#StartingAnActivity">Memulai Aktivitas</a> + <ol> + <li><a href="#StartingAnActivityForResult">Memulai aktivitas agar berhasil</a></li> + </ol> + </li> + <li><a href="#ShuttingDown">Mematikan Aktivitas</a></li> + <li><a href="#Lifecycle">Mengelola Daur Hidup Aktivitas</a> + <ol> + <li><a href="#ImplementingLifecycleCallbacks">Mengimplementasikan callback daur hidup</a></li> + <li><a href="#SavingActivityState">Menyimpan status aktivitas</a></li> + <li><a href="#ConfigurationChanges">Menangani perubahan konfigurasi</a></li> + <li><a href="#CoordinatingActivities">Mengoordinasikan aktivitas</a></li> + </ol> + </li> +</ol> + +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.app.Activity}</li> +</ol> + +<h2>Lihat juga</h2> +<ol> + <li><a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tugas dan +Back-Stack</a></li> +</ol> + +</div> +</div> + + + +<p>{@link android.app.Activity} adalah sebuah komponen aplikasi yang menyediakan layar yang digunakan +pengguna untuk berinteraksi guna melakukan sesuatu, misalnya memilih nomor telepon, mengambil foto, mengirim email, atau +menampilkan peta. Tiap aktivitas diberi sebuah jendela untuk menggambar antarmuka penggunanya. Jendela ini +biasanya mengisi layar, namun mungkin lebih kecil daripada layar dan mengambang di atas +jendela lain.</p> + +<p> Sebuah aplikasi biasanya terdiri atas beberapa aktivitas yang terikat secara longgar +satu sama lain. Biasanya, satu aktivitas dalam aplikasi ditetapkan sebagai aktivitas "utama", yang +ditampilkan kepada pengguna saat membuka aplikasi untuk pertama kali. Tiap +aktivitas kemudian bisa memulai aktivitas lain untuk melakukan berbagai tindakan. Tiap kali +aktivitas baru dimulai, aktivitas sebelumnya akan dihentikan, namun sistem mempertahankan aktivitas +dalam sebuah tumpukan ("back-stack"). Bila sebuah aktivitas baru dimulai, aktivitas itu akan didorong ke atas back-stack dan +mengambil fokus pengguna. Back-stack mematuhi mekanisme dasar tumpukan "masuk terakhir, keluar pertama", +jadi, bila pengguna selesai dengan aktivitas saat ini dan menekan tombol <em>Back</em>, aktivitas +akan dikeluarkan dari tumpukan (dan dimusnahkan) dan aktivitas sebelumnya akan dilanjutkan. (Back-stack +dibahas selengkapnya dalam dokumen <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tugas +dan Back-Stack</a>.)</p> + +<p>Bila aktivitas dihentikan karena ada aktivitas baru yang dimulai, aktivitas lama akan diberi tahu tentang perubahan status ini +melalui metode callback daur hidupnya. +Ada beberapa metode callback yang mungkin diterima aktivitas, karena sebuah perubahan dalam +statusnya—apakah sistem sedang membuatnya, menghentikannya, melanjutkannya, atau menghapuskannya—dan +masing-masing callback memberi Anda kesempatan melakukan pekerjaan tertentu yang +sesuai untuk perubahan status itu. Misalnya, bila dihentikan, aktivitas Anda harus melepas +objek besar, seperti koneksi jaringan atau database. Bila aktivitas dilanjutkan, Anda bisa +memperoleh kembali sumber daya yang diperlukan dan melanjutkan tindakan yang terputus. Transisi status ini +semuanya bagian dari daur hidup aktivitas.</p> + +<p>Bagian selebihnya dari dokumen ini membahas dasar-dasar cara membuat dan menggunakan aktivitas, +yang meliputi satu pembahasan lengkap tentang cara kerja daur hidup aktivitas, sehingga Anda bisa dengan benar mengelola +transisi di antara berbagai status aktivitas.</p> + + + +<h2 id="Creating">Membuat Aktivitas</h2> + +<p>Untuk membuat sebuah aktivitas, Anda harus membuat subkelas {@link android.app.Activity} (atau +subkelasnya yang ada). Dalam subkelas itu, Anda perlu mengimplementasikan metode-metode callback yang +dipanggil sistem saat aktivitas bertransisi di antara berbagai status daur hidupnya, misalnya saat +aktivitas sedang dibuat, dihentikan, dilanjutkan, atau dimusnahkan. Dua metode callback +terpenting adalah:</p> + +<dl> + <dt>{@link android.app.Activity#onCreate onCreate()}</dt> + <dd>Anda harus mengimplementasikan metode ini. Sistem memanggilnya saat membuat + aktivitas Anda. Dalam implementasi, Anda harus menginisialisasi komponen-komponen esensial +aktivitas. + Yang terpenting, inilah tempat Anda harus memanggil {@link android.app.Activity#setContentView + setContentView()} untuk mendefinisikan layout untuk antarmuka pengguna aktivitas.</dd> + <dt>{@link android.app.Activity#onPause onPause()}</dt> + <dd>Sistem memanggil metode ini sebagai pertanda pertama bahwa pengguna sedang meninggalkan +aktivitas Anda (walau itu tidak selalu berarti aktivitas sedang dimusnahkan). Inilah biasanya tempat Anda +harus mengikat setiap perubahan yang harus dipertahankan selepas sesi pengguna saat ini (karena +pengguna mungkin tidak kembali).</dd> +</dl> + +<p>Ada beberapa metode callback daur hidup lainnya yang harus Anda gunakan untuk memberikan +pengalaman pengguna yang mengalir di antara aktivitas dan menangani interupsi tidak terduga yang menyebabkan aktivitas Anda +dihentikan dan bahkan dimusnahkan. Semua metode callback daur hidup akan dibahas nanti, di +bagian tentang <a href="#Lifecycle">Mengelola Daur Hidup Aktivitas</a>.</p> + + + +<h3 id="UI">Mengimplementasikan antarmuka pengguna</h3> + +<p> Antarmuka pengguna aktivitas disediakan oleh hierarki objek—tampilan yang diturunkan +dari kelas {@link android.view.View}. Tiap tampilan mengontrol sebuah ruang persegi panjang tertentu +dalam jendela aktivitas dan bisa merespons interaksi pengguna. Misalnya, sebuah tampilan mungkin berupa sebuah +tombol yang mengawali suatu tindakan bila pengguna menyentuhnya.</p> + +<p>Android menyediakan sejumlah tampilan siap-dibuat yang bisa Anda gunakan untuk mendesain dan mengatur +layout. "Widget" adalah tampilan yang menyediakan elemen-elemen visual (dan interaktif) untuk layar, +misalnya tombol, bidang teks, kotak cek, atau sekadar sebuah gambar. "Layout" adalah tampilan yang diturunkan dari {@link +android.view.ViewGroup} yang memberikan sebuah model layout unik untuk tampilan anaknya, misalnya +layout linier, layout grid, atau layout relatif. Anda juga bisa mensubkelaskan kelas-kelas {@link android.view.View} dan +{@link android.view.ViewGroup} (atau subkelas yang ada) untuk membuat widget dan +layout Anda sendiri dan menerapkannya ke layout aktivitas Anda.</p> + +<p>Cara paling umum untuk mendefinisikan layout dengan menggunakan tampilan adalah dengan file layout XML yang disimpan dalam +sumber daya aplikasi Anda. Dengan cara ini, Anda bisa memelihara desain antarmuka pengguna Anda secara terpisah dari +kode yang mendefinisikan perilaku aktivitas. Anda bisa mengatur layout sebagai UI +aktivitas Anda dengan {@link android.app.Activity#setContentView(int) setContentView()}, dengan meneruskan +ID sumber daya untuk layout itu. Akan tetapi, Anda juga bisa membuat {@link android.view.View} baru dalam +kode aktivitas dan membuat hierarki tampilan dengan menyisipkan {@link +android.view.View} baru ke dalam {@link android.view.ViewGroup}, kemudian menggunakan layout itu dengan meneruskan akar +{@link android.view.ViewGroup} ke {@link android.app.Activity#setContentView(View) +setContentView()}.</p> + +<p>Untuk informasi tentang cara membuat antarmuka pengguna, lihat dokumentasi <a href="{@docRoot}guide/topics/ui/index.html">Antarmuka Pengguna</a>.</p> + + + +<h3 id="Declaring">Mendeklarasikan aktivitas dalam manifes</h3> + +<p>Anda harus mendeklarasikan aktivitas dalam file manifes agar file itu +bisa diakses oleh sistem. Untuk mendeklarasikan aktivitas, bukalah file manifes Anda dan tambahkan sebuah elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +sebagai anak elemen <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +. Misalnya:</p> + +<pre> +<manifest ... > + <application ... > + <activity android:name=".ExampleActivity" /> + ... + </application ... > + ... +</manifest > +</pre> + +<p>Ada beberapa atribut lain yang bisa Anda sertakan dalam elemen ini, untuk mendefinisikan properti +misalnya label untuk aktivitas, ikon untuk aktivitas, atau tema untuk memberi gaya ke +UI aktivitas. Atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">{@code android:name}</a> + adalah satu-satunya atribut yang diperlukan—atribut ini menetapkan nama kelas aktivitas. Setelah +Anda mempublikasikan aplikasi, Anda tidak boleh mengubah nama ini, karena jika melakukannya, Anda bisa merusak +sebagian fungsionalitas, misalnya pintasan aplikasi (bacalah posting blog berjudul <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things +That Cannot Change</a>).</p> + +<p>Lihat acuan elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +untuk informasi selengkapnya tentang cara mendeklarasikan aktivitas Anda dalam manifes.</p> + + +<h4>Menggunakan filter intent</h4> + +<p>Elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> juga bisa menetapkan berbagai filter intent—dengan menggunakan elemen <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> —untuk mendeklarasikan cara komponen aplikasi lain +mengaktifkannya.</p> + +<p>Bila Anda membuat aplikasi baru dengan Android SDK Tools, aktivitas stub +yang dibuat untuk Anda secara otomatis menyertakan filter intent yang mendeklarasikan respons +aktivitas pada tindakan "main" (utama) dan harus diletakkan dalam kategori "launcher"). Filter intent +terlihat seperti ini:</p> + +<pre> +<activity android:name=".ExampleActivity" android:icon="@drawable/app_icon"> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> +</activity> +</pre> + +<p>Elemen <a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a> menetapkan bahwa ini adalah titik masuk "main" ke aplikasi. Elemen <a href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a> menetapkan bahwa aktivitas ini harus tercantum dalam launcher aplikasi +sistem (untuk memungkinkan pengguna meluncurkan aktivitas ini).</p> + +<p>Jika Anda bermaksud agar aplikasi dimuat dengan sendirinya dan tidak memperbolehkan aplikasi lain +mengaktifkan aktivitasnya, maka Anda tidak memerlukan filter intent lain. Hanya satu aktivitas yang boleh +memiliki tindakan "main" dan kategori "launcher", seperti dalam contoh sebelumnya. Aktivitas yang +tidak ingin Anda sediakan untuk aplikasi lain tidak boleh memiliki filter intent dan Anda bisa +memulai sendiri aktivitas dengan menggunakan intent secara eksplisit (seperti dibahas di bagian berikut).</p> + +<p>Akan tetapi, jika ingin aktivitas Anda merespons intent implisit yang dikirim dari +aplikasi lain (dan aplikasi Anda sendiri), maka Anda harus mendefinisikan filter intent tambahan untuk +aktivitas. Untuk masing-masing tipe intent yang ingin direspons, Anda harus menyertakan sebuah <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> yang menyertakan elemen +<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a> dan, opsional, sebuah elemen <a href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a> dan/atau elemen <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code +<data>}</a>. Elemen-elemen ini menetapkan tipe intent yang bisa +direspons oleh aktivitas Anda.</p> + +<p>Untuk informasi selengkapnya tentang cara aktivitas Anda merespons intent, lihat dokumen <a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter Intent</a>. +</p> + + + +<h2 id="StartingAnActivity">Memulai Aktivitas</h2> + +<p>Anda bisa memulai aktivitas lain dengan memanggil {@link android.app.Activity#startActivity + startActivity()}, dengan meneruskan sebuah {@link android.content.Intent} yang menjelaskan aktivitas + yang ingin Anda mulai. Intent menetapkan aktivitas persis yang ingin Anda mulai atau menjelaskan + tipe tindakan yang ingin Anda lakukan (dan sistem akan memilih aktivitas yang sesuai untuk Anda, +yang bahkan + bisa berasal dari aplikasi berbeda). Intent juga bisa membawa sejumlah kecil data untuk + digunakan oleh aktivitas yang dimulai.</p> + +<p>Saat bekerja dalam aplikasi sendiri, Anda nanti akan sering meluncurkan aktivitas yang dikenal saja. + Anda bisa melakukannya dengan membuat intent yang mendefinisikan secara eksplisit aktivitas yang ingin Anda mulai, +dengan menggunakan nama kelas. Misalnya, beginilah cara satu aktivitas memulai aktivitas lain bernama {@code +SignInActivity}:</p> + +<pre> +Intent intent = new Intent(this, SignInActivity.class); +startActivity(intent); +</pre> + +<p>Akan tetapi, aplikasi Anda mungkin juga perlu melakukan beberapa tindakan, misalnya mengirim email, + pesan teks, atau pembaruan status, dengan menggunakan data dari aktivitas Anda. Dalam hal ini, aplikasi Anda mungkin + tidak memiliki aktivitasnya sendiri untuk melakukan tindakan tersebut, sehingga Anda bisa memanfaatkan aktivitas + yang disediakan oleh aplikasi lain pada perangkat, yang bisa melakukan tindakan itu untuk Anda. Inilah saatnya +intent benar-benar berharga—Anda bisa membuat intent yang menjelaskan tindakan yang ingin +dilakukan dan sistem + akan meluncurkan aktivitas yang tepat dari aplikasi lain. Jika ada + beberapa aktivitas yang bisa menangani intent itu, pengguna bisa memilih aktivitas yang akan digunakan. Misalnya, + jika Anda ingin memperbolehkan pengguna mengirim pesan email, Anda bisa membuat + intent berikut:</p> + +<pre> +Intent intent = new Intent(Intent.ACTION_SEND); +intent.putExtra(Intent.EXTRA_EMAIL, recipientArray); +startActivity(intent); +</pre> + +<p>Ekstra {@link android.content.Intent#EXTRA_EMAIL} yang ditambahkan ke intent adalah sebuah larik string + alamat email yang menjadi tujuan pengiriman email. Bila aplikasi email merespons intent ini, + aplikasi itu akan membaca larik string yang disediakan dalam ekstra dan meletakkannya dalam bidang "to" + pada formulir penulisan email. Dalam situasi ini, aktivitas aplikasi email dimulai dan bila + pengguna selesai, aktivitas Anda akan dilanjutkan.</p> + + + + +<h3 id="StartingAnActivityForResult">Memulai aktivitas agar berhasil</h3> + +<p>Kadang-kadang, Anda mungkin ingin menerima hasil dari aktivitas yang Anda mulai. Dalam hal itu, + mulailah aktivitas dengan memanggil {@link android.app.Activity#startActivityForResult + startActivityForResult()} (sebagai ganti {@link android.app.Activity#startActivity + startActivity()}). Untuk menerima hasil dari +aktivitas selanjutnya nanti, implementasikan metode callback {@link android.app.Activity#onActivityResult onActivityResult()} +. Bila aktivitas selanjutnya selesai, aktivitas akan mengembalikan hasil dalam {@link +android.content.Intent} kepada metode {@link android.app.Activity#onActivityResult onActivityResult()} +Anda.</p> + +<p>Misalnya, mungkin Anda ingin pengguna mengambil salah satu kontaknya, sehingga aktivitas Anda bisa +melakukan sesuatu dengan informasi dalam kontak itu. Begini caranya membuat intent tersebut dan +menangani hasilnya:</p> + +<pre> +private void pickContact() { + // Create an intent to "pick" a contact, as defined by the content provider URI + Intent intent = new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI); + startActivityForResult(intent, PICK_CONTACT_REQUEST); +} + +@Override +protected void onActivityResult(int requestCode, int resultCode, Intent data) { + // If the request went well (OK) and the request was PICK_CONTACT_REQUEST + if (resultCode == Activity.RESULT_OK && requestCode == PICK_CONTACT_REQUEST) { + // Perform a query to the contact's content provider for the contact's name + Cursor cursor = getContentResolver().query(data.getData(), + new String[] {Contacts.DISPLAY_NAME}, null, null, null); + if (cursor.moveToFirst()) { // True if the cursor is not empty + int columnIndex = cursor.getColumnIndex(Contacts.DISPLAY_NAME); + String name = cursor.getString(columnIndex); + // Do something with the selected contact's name... + } + } +} +</pre> + +<p>Contoh ini menunjukkan logika dasar yang harus Anda gunakan dalam metode {@link +android.app.Activity#onActivityResult onActivityResult()} Anda untuk menangani +hasil aktivitas. Syarat pertama memeriksa apakah permintaan berhasil—jika ya, maka + {@code resultCode} akan berupa {@link android.app.Activity#RESULT_OK}—dan apakah permintaan +yang direspons hasil ini dikenal—dalam hal ini, {@code requestCode} cocok dengan +parameter kedua yang dikirim dengan {@link android.app.Activity#startActivityForResult +startActivityForResult()}. Dari sana, kode akan menangani hasil aktivitas dengan membuat query +data yang dihasilkan dalam{@link android.content.Intent} (parameter {@code data}).</p> + +<p>Yang terjadi adalah {@link +android.content.ContentResolver} melakukan query terhadap penyedia konten, yang menghasilkan +{@link android.database.Cursor} yang memperbolehkan data query dibaca. Untuk informasi selengkapnya, lihat dokumen +<a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia Konten</a>.</p> + +<p>Untuk informasi selengkapnya tentang menggunakan intent, lihat dokumen <a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter +Intent</a>.</p> + + +<h2 id="ShuttingDown">Mematikan Aktivitas</h2> + +<p>Anda bisa mematikan aktivitas dengan memanggil metode {@link android.app.Activity#finish +finish()}-nya. Anda juga bisa mematikan aktivitas terpisah yang sebelumnya Anda mulai dengan memanggil +{@link android.app.Activity#finishActivity finishActivity()}.</p> + +<p class="note"><strong>Catatan:</strong> Pada umumnya, Anda tidak boleh secara eksplisit mengakhiri aktivitas +dengan menggunakan metode-metode ini. Seperti yang dibahas di bagian berikut tentang daur hidup aktivitas, +sistem Android mengelola hidup aktivitas untuk Anda, sehingga Anda tidak perlu menyelesaikan sendiri +aktivitas tersebut. Memanggil metode-metode ini bisa berpengaruh negatif pada pengalaman +pengguna yang diharapkan dan hanya boleh digunakan bila Anda benar-benar tidak ingin pengguna kembali ke +instance aktivitas ini.</p> + + +<h2 id="Lifecycle">Mengelola Daur Hidup Aktivitas</h2> + +<p>Mengelola daur hidup aktivitas dengan mengimplementasikan metode-metode callback sangat +penting untuk mengembangkan +aplikasi yang kuat dan fleksibel. Daur hidup aktivitas dipengaruhi langsung oleh kaitannya dengan +aktivitas lain, tugasnya, serta back-stack.</p> + +<p>Pada dasarnya, sebuah aktivitas bisa berada dalam tiga status:</p> + +<dl> + <dt><i>Dilanjutkan</i></dt> + <dd>Aktivitas berada di latar depan layar dan mendapatkan fokus pengguna. (Status ini +kadang-kadang disebut juga dengan "running" (berjalan).)</dd> + + <dt><i>Dihentikan sementara</i></dt> + <dd>Aktivitas lain berada di latar depan dan mendapat fokus, namun aktivitas ini masih terlihat. Yakni, +aktivitas lain terlihat di atas aplikasi ini dan aktivitas itu setengah transparan atau tidak +menuutpi seluruh layar. Aktivitas yang dihentikan sementara adalah benar-benar hidup (objek {@link android.app.Activity} +dipertahankan dalam memori, objek itu memelihara semua informasi status dan anggota, dan tetap dikaitkan dengan +window manager), namun bisa dimatikan oleh sistem dalam situasi memori sangat rendah.</dd> + + <dt><i>Dihentikan</i></dt> + <dd>Aktivitas ditutupi sepenuhnya oleh aktivitas lain (aktivitas sekarang berada di +"latar belakang"). Aktivitas yang dihentikan juga masih hidup (objek {@link android.app.Activity} +dipertahankan dalam memori, objek itu menjaga semua informasi status dan anggota, namun <em>tidak</em> +dikaitkan dengan window manager). Akan tetapi, aktivitas tidak lagi terlihat bagi pengguna dan +bisa dimatikan oleh sistem bila memori diperlukan di lain.</dd> +</dl> + +<p>Jika aktivitas dihentikan sementara atau dihentikan, sistem bisa mengeluarkannya dari memori baik dengan memintanya agar +diakhiri (memanggil metode {@link android.app.Activity#finish finish()}-nya), atau sekadar mematikan +prosesnya. Bila dibuka lagi (setelah diakhiri atau dimatikan), aktivitas harus dibuat dari +awal.</p> + + + +<h3 id="ImplementingLifecycleCallbacks">Mengimplementasikan callback daur hidup</h3> + +<p>Saat bertransisi ke dalam dan ke luar berbagai status yang dijelaskan di atas, aktivitas diberi tahu +melalui berbagai metode callback. Semua metode callback adalah sangkutan yang +bisa Anda kesampingkan untuk melakukan pekerjaan yang sesuai saat status aktivitas Anda berubah. Aktivitas skeleton +berikut menyertakan setiap metode daur hidup mendasar:</p> + + +<pre> +public class ExampleActivity extends Activity { + @Override + public void {@link android.app.Activity#onCreate onCreate}(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + // The activity is being created. + } + @Override + protected void {@link android.app.Activity#onStart onStart()} { + super.onStart(); + // The activity is about to become visible. + } + @Override + protected void {@link android.app.Activity#onResume onResume()} { + super.onResume(); + // The activity has become visible (it is now "resumed"). + } + @Override + protected void {@link android.app.Activity#onPause onPause()} { + super.onPause(); + // Another activity is taking focus (this activity is about to be "paused"). + } + @Override + protected void {@link android.app.Activity#onStop onStop()} { + super.onStop(); + // The activity is no longer visible (it is now "stopped") + } + @Override + protected void {@link android.app.Activity#onDestroy onDestroy()} { + super.onDestroy(); + // The activity is about to be destroyed. + } +} +</pre> + +<p class="note"><strong>Catatan:</strong> Implementasi Anda terhadap metode-metode daur hidup ini harus +selalu memanggil implementasi superkelas sebelum melakukan pekerjaan apa pun, seperti yang ditampilkan dalam contoh-contoh di atas.</p> + +<p>Bersama-sama, semua metode ini mendefinisikan seluruh daur hidup sebuah aktivitas. Dengan mengimplementasikan +metode-metode ini, Anda bisa memantau tiga loop tersarang (nested loop) dalam daur hidup aktivitas: </p> + +<ul> +<li><b>Seluruh masa hidup</b> aktivitas berlangsung antara panggilan ke {@link +android.app.Activity#onCreate onCreate()} dan panggilan ke {@link +android.app.Activity#onDestroy}. Aktivitas Anda harus melakukan penyiapan +status "global" (misalnya mendefinisikan layout) dalam {@link android.app.Activity#onCreate onCreate()}, dan +melepas semua sisa sumber daya dalam {@link android.app.Activity#onDestroy}. Misalnya, jika +aktivitas Anda memiliki sebuah thread yang berjalan di latar belakang untuk mengunduh data dari jaringan, aktivitas itu bisa membuat +thread itu dalam {@link android.app.Activity#onCreate onCreate()} kemudian menghentikan thread dalam {@link +android.app.Activity#onDestroy}.</li> + +<li><p><b>Masa pakai terlihat</b> (visible lifetime) aktivitas berlangsung antara panggilan ke {@link +android.app.Activity#onStart onStart()} dan panggilan ke {@link +android.app.Activity#onStop onStop()}. Selama ini, pengguna bisa melihat aktivitas +pada layar dan berinteraksi dengannya. Misalnya, {@link android.app.Activity#onStop onStop()} dipanggil +bila sebuah aktivitas baru dimulai dan aktivitas ini tidak lagi terlihat. Di antara dua metode ini, Anda bisa +memelihara sumber daya yang diperlukan untuk menampilkan aktivitas kepada pengguna. Misalnya, Anda bisa mendaftarkan sebuah +{@link android.content.BroadcastReceiver} dalam {@link +android.app.Activity#onStart onStart()} untuk memantau perubahan yang berdampak pada UI Anda, dan mencabut pendaftarannya +dalam {@link android.app.Activity#onStop onStop()} bila pengguna tidak bisa lagi melihat apa yang sedang Anda +tampilkan. Sistem bisa memanggil {@link android.app.Activity#onStart onStart()} dan {@link +android.app.Activity#onStop onStop()} beberapa kali selama masa pakai aktivitas, sambil +aktivitas berganti-ganti antara terlihat dan tersembunyi bagi pengguna.</p></li> + +<li><p><b>Masa pakai latar depan</b> aktivitas berlangsung antara panggilan ke {@link +android.app.Activity#onResume onResume()} dan panggilan ke {@link android.app.Activity#onPause +onPause()}. Selama waktu ini, aktivitas berada di depan semua aktivitas lain pada layar dan mendapatkan +fokus input pengguna. Aktivitas bisa sering bertransisi ke dalam dan ke luar latar depan—misalnya, + {@link android.app.Activity#onPause onPause()} dipanggil bila perangkat masuk ke mode tidur atau +bila dialog muncul. Karena status ini bisa sering bertransisi, kode dalam dua metode ini harus +cukup ringan untuk menghindari transisi lamban yang membuat pengguna menunggu.</p></li> +</ul> + +<p>Gambar 1 mengilustrasikan loop dan path yang mungkin diambil sebuah aktivitas di antara status-status. +Persegi panjang mewakili metode callback yang bisa Anda implementasikan untuk melakukan operasi saat +aktivitas bertransisi di antara status. <p> + +<img src="{@docRoot}images/activity_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Daur hidup aktivitas.</p> + +<p>Metode-metode callback daur hidup yang sama tercantum dalam tabel 1, yang menjelaskan setiap metode callback +secara lebih detail dan menentukan lokasinya masing-masing dalam +daur hidup aktivitas keseluruhan, termasuk apakah sistem bisa mematikan aktivitas setelah +metode callback selesai.</p> + +<p class="table-caption"><strong>Tabel 1.</strong> Rangkuman metode callback +daur hidup aktivitas.</p> + +<table border="2" width="85%" frame="hsides" rules="rows"> +<colgroup align="left" span="3"></colgroup> +<colgroup align="left"></colgroup> +<colgroup align="center"></colgroup> +<colgroup align="center"></colgroup> + +<thead> +<tr><th colspan="3">Metode</th> <th>Keterangan</th> <th>Bisa dimatikan setelahnya?</th> <th>Berikutnya</th></tr> +</thead> + +<tbody> +<tr> + <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td> + <td>Dipanggil saat aktivitas pertama kali dibuat. + Di sinilah Anda harus melakukan semua persiapan statis normal — + membuat tampilan, mengikat data ke daftar, dan sebagainya. Metode ini diberi + sebuah objek Bundle yang berisi status aktivitas sebelumnya, jika + status itu tertangkap (lihat <a href="#actstate">Menyimpan Status Aktivitas</a>, + nanti). + <p>Selalu diikuti oleh {@code onStart()}.</p></td> + <td align="center">Tidak</td> + <td align="center">{@code onStart()}</td> +</tr> + +<tr> + <td rowspan="5" style="border-left: none; border-right: none;"> </td> + <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart +onRestart()}</code></td> + <td>Dipanggil setelah aktivitas dihentikan, tepat sebelum + dimulai lagi. + <p>Selalu diikuti oleh {@code onStart()}</p></td> + <td align="center">Tidak</td> + <td align="center">{@code onStart()}</td> +</tr> + +<tr> + <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td> + <td>Dipanggil tepat sebelum aktivitas menjadi terlihat bagi pengguna. + <p>Diikuti oleh {@code onResume()} jika aktivitas maju + ke latar depan, atau {@code onStop()} jika menjadi tersembunyi.</p></td> + <td align="center">Tidak</td> + <td align="center">{@code onResume()} <br/>atau<br/> {@code onStop()}</td> +</tr> + +<tr> + <td rowspan="2" style="border-left: none;"> </td> + <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td> + <td>Dipanggil tepat sebelum aktivitas mulai + berinteraksi dengan pengguna. Pada titik ini, aktivitas berada di + puncak tumpukan aktivitas, dengan input pengguna menuju kepadanya. + <p>Selalu diikuti oleh {@code onPause()}.</p></td> + <td align="center">Tidak</td> + <td align="center">{@code onPause()}</td> +</tr> + +<tr> + <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td> + <td>Dipanggil bila sistem akan memulai pelanjutan + aktivitas lain. Metode ini biasanya digunakan untuk menerapkan (commit) perubahan yang tidak tersimpan pada + data persisten, menghentikan animasi dan hal-hal lain yang mungkin menghabiskan + CPU, dan sebagainya. Metode ini harus melakukan apa saja yang dilakukannya dengan sangat cepat, karena + aktivitas berikutnya tidak akan dilanjutkan hingga aktivitas ini kembali. + <p>Diikuti oleh {@code onResume()} jika aktivitas + kembali ke depan, atau oleh {@code onStop()} jika menjadi + tidak terlihat bagi pengguna.</td> + <td align="center"><strong style="color:#800000">Ya</strong></td> + <td align="center">{@code onResume()} <br/>atau<br/> {@code onStop()}</td> +</tr> + +<tr> + <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td> + <td>Dipanggil bila aktivitas tidak lagi terlihat bagi pengguna. Hal ini + bisa terjadi karena aktivitas sedang dimusnahkan, atau karena aktivitas lain + (aktivitas yang ada atau yang baru) telah dilanjutkan dan sedang menutupinya. + <p>Diikuti oleh {@code onRestart()} jika + aktivitas kembali untuk berinteraksi dengan pengguna, atau oleh + {@code onDestroy()} jika aktivitas ini akan menghilang.</p></td> + <td align="center"><strong style="color:#800000">Ya</strong></td> + <td align="center">{@code onRestart()} <br/>atau<br/> {@code onDestroy()}</td> +</tr> + +<tr> + <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy +onDestroy()}</code></td> + <td>Dipanggil sebelum aktivitas dimusnahkan. Inilah panggilan terakhir + yang akan diterima aktivitas. Metode ini bisa dipanggil karena + aktivitas selesai (seseorang memanggil <code>{@link android.app.Activity#finish + finish()}</code> padanya), atau karena sistem memusnahkan sementara + instance aktivitas ini untuk menghemat tempat. Anda bisa membedakan + kedua skenario ini dengan metode <code>{@link + android.app.Activity#isFinishing isFinishing()}</code>.</td> + <td align="center"><strong style="color:#800000">Ya</strong></td> + <td align="center"><em>tidak ada</em></td> +</tr> +</tbody> +</table> + +<p>Kolom berlabel "Bisa dimatikan setelahnya?" menunjukkan apakah sistem bisa +atau tidak mematikan proses yang menjadi host aktivitas kapan saja <em>setelah metode kembali</em>, tanpa +menjalankan baris lain pada kode aktivitas. Tiga metode ini ditandai "ya": ({@link +android.app.Activity#onPause +onPause()}, {@link android.app.Activity#onStop onStop()}, dan {@link android.app.Activity#onDestroy +onDestroy()}). Karena {@link android.app.Activity#onPause onPause()} adalah yang pertama +dari tiga, begitu aktivitas dibuat, {@link android.app.Activity#onPause onPause()} adalah +metode terakhir yang dipastikan akan dipanggil sebelum proses <em>bisa</em> dimatikan—jika +sistem harus memulihkan memori dalam keadaan darurat, maka {@link +android.app.Activity#onStop onStop()} dan {@link android.app.Activity#onDestroy onDestroy()} mungkin +tidak dipanggil. Karena itu, Anda harus menggunakan {@link android.app.Activity#onPause onPause()} untuk menulis +data persisten yang penting (misalnya hasil edit pengguna) ke penyimpanan. Akan tetapi, Anda harus selektif dalam hal +informasi yang harus dipertahankan selama {@link android.app.Activity#onPause onPause()}, karena setiap +prosedur pemblokiran dalam metode ini akan memblokir transisi ke aktivitas berikutnya dan memperlambat +pengalaman pengguna.</p> + +<p> Metode-metode yang ditandai "Tidak" dalam kolom <b>Bisa dimatikan</b> melindungi proses yang menjadi host +aktivitas dari dimatikan sejak saat metode dipanggil. Jadi, aktivitas bisa dimatikan +sejak {@link android.app.Activity#onPause onPause()} kembali hingga waktu +{@link android.app.Activity#onResume onResume()} dipanggil. Aktivitas tidak akan lagi bisa dimatikan hingga +{@link android.app.Activity#onPause onPause()} dipanggil lagi dan kembali. </p> + +<p class="note"><strong>Catatan:</strong> Aktivitas yang tidak "bisa dimatikan" secara teknis oleh +definisi dalam tabel 1 masih bisa dimatikan oleh sistem—namun itu hany terjadi dalam +situasi ekstrem bila tidak ada jalan lain. Kapan aktivitas bisa dimatikan +akan dibahas selengkapnya dalam dokumen <a href="{@docRoot}guide/components/processes-and-threads.html">Proses dan +Threading</a>.</p> + + +<h3 id="SavingActivityState">Menyimpan status aktivitas</h3> + +<p>Pengantar untuk <a href="#Lifecycle">Mengelola Daur Hidup Aktivitas</a> secara ringkas menyebutkan +bahwa +bila aktivitas dihentikan sementara atau dihentikan, status aktivitas akan dipertahankan. Hal itu terjadi karena +objek {@link android.app.Activity} masih ditahan dalam memori saat aktivitas dihentikan sementara atau +dihentikan—semua informasi tentang anggota dan statusnya saat ini masih hidup. Jadi, setiap perubahan +yang dibuat pengguna dalam aktivitas akan dipertahankan sehingga bila aktivitas kembali ke +latar depan (bila "dilanjutkan"), perubahan itu masih ada.</p> + +<p>Akan tetapi, bila sistem memusnahkan aktivitas untuk memulihkan memori, objek {@link +android.app.Activity} akan dimusnahkan, sehingga sistem tidak bisa sekadar melanjutkan aktivitas dengan status +tidak berubah. Sebagai gantinya, sistem harus membuat ulang objek {@link android.app.Activity} jika pengguna +menyusuri kembali ke aktivitas tersebut. Namun, pengguna tidak menyadari +bahwa sistem memusnahkan aktivitas dan membuatnya kembali dan, karena itu, mungkin +mengharapkan aktivitas untuk sama persis dengan sebelumnya. Dalam situasi ini, Anda bisa memastikan bahwa +informasi penting tentang status aktivitas tetap terjaga dengan mengimplementasikan +metode callback tambahan yang memungkinkan Anda menyimpan informasi tentang status aktivitas: {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> + +<p>Sistem memanggil {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +sebelum membuat aktivitas rawan terhadap pemusnahan. Sistem meneruskan ke metode ini +sebuah {@link android.os.Bundle} tempat Anda bisa menyimpan +informasi status tentang aktivitas sebagai pasangan nama-nilai, dengan menggunakan metode-metode misalnya {@link +android.os.Bundle#putString putString()} dan {@link +android.os.Bundle#putInt putInt()}. Kemudian, jika sistem mematikan proses aplikasi Anda +dan pengguna menyusuri kembali ke aktivitas tersebut, sistem akan membuat kembali aktivitas dan meneruskan +{@link android.os.Bundle} ke {@link android.app.Activity#onCreate onCreate()} maupun {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}. Dengan menggunakan salah satu +metode ini, Anda bisa mengekstrak status tersimpan dari {@link android.os.Bundle} dan memulihkan +status aktivitas. Jika tidak ada informasi status untuk dipulihkan, maka {@link +android.os.Bundle} yang diteruskan kepada adalah Anda null (yang akan terjadi bila aktivitas dibuat untuk +pertama kali).</p> + +<img src="{@docRoot}images/fundamentals/restore_instance.png" alt="" /> +<p class="img-caption"><strong>Gambar 2.</strong> Ada dua cara yang bisa digunakan aktivitas untuk kembali ke fokus pengguna +dengan status tetap: aktivitas dimusnahkan, kemudian dibuat kembali, dan aktivitas harus memulihkan +status yang disimpan sebelumnya, atau aktivitas dihentikan, kemudian dilanjutkan dengan status aktivitas +tetap.</p> + +<p class="note"><strong>Catatan:</strong> Tidak ada jaminan bahwa {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} akan dipanggil sebelum +aktivitas Anda dimusnahkan, karena bisa saja terjadi aktivitas tidak perlu menyimpan status +(misalnya saat pengguna meninggalkan aktivitas Anda dengan menggunakan tombol <em>Back</em>, karena pengguna menutup aktivitas +secara eksplisit +). Jika sistem memanggil {@link android.app.Activity#onSaveInstanceState +onSaveInstanceState()}, ini akan dilakukan sebelum {@link +android.app.Activity#onStop onStop()} dan mungkin sebelum {@link android.app.Activity#onPause +onPause()}.</p> + +<p>Akan tetapi, sekalipun Anda tidak melakukan apa-apa dan tidak mengimplementasikan {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()}, beberapa status aktivitas +akan dipulihkan oleh implementasi default {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} dalam kelas {@link android.app.Activity}. Khususnya, +implementasi default akan memanggil metode {@link +android.view.View#onSaveInstanceState onSaveInstanceState()} yang sesuai untuk setiap {@link +android.view.View} dalam layout, yang memungkinkan setiap tampilan untuk memberi informasi tentang dirinya +yang harus disimpan. Hampir setiap widget dalam kerangka kerja Android mengimplementasikan metode ini +sebagaimana mestinya, sehingga setiap perubahan yang terlihat pada UI akan disimpan dan dipulihkan secara otomatis bila +aktivitas Anda dibuat kembali. Misalnya, widget {@link android.widget.EditText} menyimpan teks apa saja +yang dimasukkan oleh pengguna dan widget {@link android.widget.CheckBox} menyimpan baik teks itu diperiksa maupun +tidak. Satu-satunya pekerjaan yang Anda perlukan adalah memberikan ID unik (dengan atribut <a href="{@docRoot}guide/topics/resources/layout-resource.html#idvalue">{@code android:id}</a> +) untuk masing-masing widget yang ingin disimpan statusnya. Jika widget tidak memiliki ID, maka sistem +tidak bisa menyimpan statusnya.</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<p>Anda juga bisa menghentikan secara eksplisit sebuah tampilan dalam layout Anda agar tidak menyimpan statusnya dengan mengatur atribut +{@link android.R.attr#saveEnabled android:saveEnabled} ke {@code "false"} atau dengan memanggil +metode {@link android.view.View#setSaveEnabled setSaveEnabled()}. Biasanya, Anda tidak boleh +menonaktifkannya, namun Anda boleh melakukannya jika ingin memulihkan status UI aktivitas secara berbeda.</p> +</div> +</div> + +<p>Walaupun implementasi default {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} menyimpan informasi yang berguna tentang +UI aktivitas, Anda mungkin masih perlu mengesampingkannya untuk menyimpan informasi tambahan. +Misalnya, Anda mungkin perlu menyimpan nilai-nilai anggota yang berubah selama masa pakai aktivitas (yang +mungkin berkorelasi dengan nilai-nilai yang dipulihkan dalam UI, namun anggota-anggota yang menyimpan nilai-nilai UI itu tidak +dipulihkan, secara default).</p> + +<p>Karena implementasi default {@link +android.app.Activity#onSaveInstanceState onSaveInstanceState()} membantu menyimpan status UI, jika +Anda mengesampingkan metode ini untuk menyimpan informasi tambahan status, Anda harus selalu memanggil +implementasi superkelas {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +sebelum melakukan pekerjaan apa pun. Demikian pula, Anda juga harus memanggil implementasi superkelas {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} jika Anda mengesampingkannya, sehingga +implementasi default bisa memulihkan status tampilan.</p> + +<p class="note"><strong>Catatan:</strong> Karena {@link android.app.Activity#onSaveInstanceState +onSaveInstanceState()} tidak dijamin +akan dipanggil, Anda harus menggunakannya hanya untuk mencatat status aktivitas sementara (transient) (status +UI)—Anda tidak boleh menggunakannya untuk menyimpan data persisten. Sebagai gantinya, Anda harus menggunakan {@link +android.app.Activity#onPause onPause()} untuk menyimpan data persisten (misalnya data yang harus disimpan +ke database) saat pengguna meninggalkan aktivitas.</p> + +<p>Salah satu cara yang baik untuk menguji kemampuan aplikasi dalam memulihkan statusnya adalah cukup dengan memutar +perangkat sehingga orientasi layarnya berubah. Bila orientasi layar berubah, sistem +akan memusnahkan dan membuat kembali aktivitas untuk menerapkan sumber daya alternatif yang mungkin tersedia +untuk konfigurasi layar baru. Karena alasan ini saja, sangat penting bahwa aktivitas Anda +memulihkan statusnya secara lengkap saat dibuat kembali, karena pengguna memutar layar secara rutin saat +menggunakan aplikasi.</p> + + +<h3 id="ConfigurationChanges">Menangani perubahan konfigurasi</h3> + +<p>Sebagian konfigurasi perangkat bisa berubah saat runtime (misalnya orientasi layar, ketersediaan keyboard +, dan bahasa). Bila terjadi perubahan demikian, Android akan membuat kembali aktivitas yang berjalan +(sistem akan memanggil {@link android.app.Activity#onDestroy}, kemudian segera memanggil {@link +android.app.Activity#onCreate onCreate()}). Perilaku ini +didesain untuk membantu aplikasi Anda menyesuaikan diri dengan konfigurasi baru dengan cara memuat ulang +aplikasi Anda secara otomatis dengan sumber daya alternatif yang telah Anda sediakan (misalnya layout yang berbeda untuk +layar orientasi dan ukuran yang berbeda).</p> + +<p>Jika Anda mendesain aktivitas dengan benar untuk menangani restart karena perubahan orientasi layar dan +memulihkan status aktivitas seperti yang dijelaskan di atas, aplikasi Anda akan lebih tahan terhadap +kejadian tidak terduga lainnya dalam daur hidup aktivitas.</p> + +<p>Cara terbaik menangani restart tersebut adalah + menyimpan dan memulihkan status aktivitas Anda dengan menggunakan {@link + android.app.Activity#onSaveInstanceState onSaveInstanceState()} dan {@link +android.app.Activity#onRestoreInstanceState onRestoreInstanceState()} (atau {@link +android.app.Activity#onCreate onCreate()}), seperti yang dibahas di bagian sebelumnya.</p> + +<p>Untuk informasi selengkapnya tentang konfigurasi perubahan yang terjadi saat program berjalan dan cara menanganinya +, bacalah panduan untuk <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Menangani +Perubahan Runtime</a>.</p> + + + +<h3 id="CoordinatingActivities">Mengoordinasikan aktivitas</h3> + + <p>Bila suatu aktivitas memulai aktivitas lain, keduanya akan mengalami transisi daur hidup. Aktivitas pertama +akan berhenti sementara dan berhenti sama sekali (walau tidak akan berhenti jika masih terlihat di latar belakang), saat +aktivitas lain dibuat. Jika aktivitas-aktivitas ini berbagi data yang disimpan ke disk atau di tempat lain, Anda perlu +memahami bahwa aktivitas pertama tidak dihentikan sepenuhnya sebelum aktivitas kedua dibuat. +Sebagai gantinya, proses akan memulai aktivitas kedua secara tumpang tindih dengan proses penghentian +aktivitas pertama.</p> + +<p>Urutan callback daur hidup didefinisikan dengan baik, khususnya bila kedua aktivitas berada dalam +proses yang sama dan salah satunya memulai yang lain. Berikut ini adalah urutan operasi yang terjadi bila Aktivitas +A memulai Aktivitas B: </p> + +<ol> +<li>Metode {@link android.app.Activity#onPause onPause()} Aktivitas A berjalan.</li> + +<li>Metode-metode {@link android.app.Activity#onCreate onCreate()}, {@link +android.app.Activity#onStart onStart()}, dan {@link android.app.Activity#onResume onResume()} +Aktivitas B berjalan secara berurutan. (Aktivitas B sekarang mendapatkan fokus pengguna.)</li> + +<li>Kemudian, jika Aktivitas A tidak lagi terlihat di layar, metode {@link +android.app.Activity#onStop onStop()}-nya akan dijalankan.</li> +</ol> + + <p>Urutan callback daur hidup yang bisa diramalkan ini memungkinkan Anda mengelola transisi +informasi dari satu aktivitas ke aktivitas lainnya. Misalnya, jika Anda harus menulis ke database saat +aktivitas pertama berhenti agar aktivitas berikutnya bisa membacanya, maka Anda harus menulis ke +database selama {@link android.app.Activity#onPause onPause()} sebagai ganti selama {@link +android.app.Activity#onStop onStop()}.</p> + +<!-- +<h2>Beginner's Path</h2> + +<p>For more information about how Android maintains a history of activities and +enables user multitasking, continue with the <b><a +href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back +Stack</a></b> document.</p> +--> diff --git a/docs/html-intl/intl/in/guide/components/bound-services.jd b/docs/html-intl/intl/in/guide/components/bound-services.jd new file mode 100644 index 000000000000..5d1f65ed7c8e --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/bound-services.jd @@ -0,0 +1,658 @@ +page.title=Layanan Terikat +parent.title=Layanan +parent.link=services.html +@jd:body + + +<div id="qv-wrapper"> +<ol id="qv"> +<h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#Basics">Dasar-Dasar</a></li> + <li><a href="#Creating">Membuat Layanan Terikat</a> + <ol> + <li><a href="#Binder">Memperluas kelas Binder</a></li> + <li><a href="#Messenger">Menggunakan Messenger</a></li> + </ol> + </li> + <li><a href="#Binding">Mengikat ke Layanan</a></li> + <li><a href="#Lifecycle">Mengelola Daur Hidup Layanan Terikat</a></li> +</ol> + +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.app.Service}</li> + <li>{@link android.content.ServiceConnection}</li> + <li>{@link android.os.IBinder}</li> +</ol> + +<h2>Contoh</h2> +<ol> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code + RemoteService}</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code + LocalService}</a></li> +</ol> + +<h2>Lihat juga</h2> +<ol> + <li><a href="{@docRoot}guide/components/services.html">Layanan</a></li> +</ol> +</div> + + +<p>Layanan terikat adalah server di antarmuka klien-server. Layanan terikat memungkinkan komponen-komponen +(seperti aktivitas) untuk diikat ke layanan, mengirim permintaan, menerima respons, dan bahkan melakukan +komunikasi antarproses (IPC). Layanan terikat biasanya hidup hanya saat melayani +komponen aplikasi lain dan tidak berjalan di latar belakang terus-menerus.</p> + +<p>Dokumen ini menampilkan cara membuat layanan terikat, termasuk cara mengikat +ke layanan dari komponen aplikasi lain. Akan tetapi, Anda juga harus mengacu dokumen <a href="{@docRoot}guide/components/services.html">Layanan</a> untuk +informasi tambahan tentang layanan secara umum, seperti cara menyampaikan pemberitahuan dari layanan, mengatur +layanan agar berjalan di latar depan, dan lain-lain.</p> + + +<h2 id="Basics">Dasar-Dasar</h2> + +<p>Layanan terikat adalah implementasi kelas {@link android.app.Service} yang memungkinkan +aplikasi lain diikat padanya dan berinteraksi dengannya. Untuk menyediakan pengikatan bagi sebuah +layanan, Anda harus mengimplementasikan metode callback {@link android.app.Service#onBind onBind()}. Metode ini +menghasilkan objek {@link android.os.IBinder} yang mendefinisikan antarmuka pemprograman yang +bisa digunakan klien untuk berinteraksi dengan layanan.</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Mengikat ke Layanan yang Sudah Dimulai</h3> + +<p>Seperti dibahas dalam dokumen <a href="{@docRoot}guide/components/services.html">Layanan</a> +, Anda bisa membuat layanan yang dimulai sekaligus diikat. Yakni, layanan bisa +dimulai dengan memanggil {@link android.content.Context#startService startService()}, yang memungkinkan +layanan berjalan terus-menerus, dan juga membolehkan klien untuk mengikat ke layanan dengan memanggil {@link +android.content.Context#bindService bindService()}. + <p>Jika Anda mengizinkan layanan dimulai dan diikat, lalu ketika layanan telah +dimulai, sistem <em>tidak</em> menghapus layanan ketika semua klien melepas ikatan. Sebagai gantinya, Anda harus +menghentikan layanan secara eksplisit, dengan memanggil {@link android.app.Service#stopSelf stopSelf()} atau {@link +android.content.Context#stopService stopService()}.</p> + +<p>Walaupun Anda biasanya harus mengimplementasikan {@link android.app.Service#onBind onBind()} +<em>atau</em> {@link android.app.Service#onStartCommand onStartCommand()}, kadang-kadang perlu +mengimplementasikan keduanya. Misalnya, sebuah pemutar musik bisa merasakan manfaatnya karena layanannya boleh berjalan +terus-menerus dan juga menyediakan pengikatan. Dengan cara ini, sebuah aktivitas bisa memulai layanan untuk memutar beberapa +lagu dan musik terus dimainkan sekalipun pengguna meninggalkan aplikasi. Lalu, bila pengguna +kembali ke aplikasi, aktivitas bisa mengikat ke layanan untuk mendapatkan kembali kontrol atas pemutaran.</p> + +<p>Pastikan membaca bagian tentang <a href="#Lifecycle">Mengelola Daur Hidup Layanan +Terikat</a>, untuk informasi selengkapnya tentang daur hidup layanan saat menambahkan pengikatan ke +layanan yang sudah dimulai.</p> +</div> +</div> + +<p>Klien bisa mengikat ke layanan dengan memanggil {@link android.content.Context#bindService +bindService()}. Bila itu dilakukan, klien harus menyediakan implementasi {@link +android.content.ServiceConnection}, yang memantau koneksi dengan layanan. Metode {@link +android.content.Context#bindService bindService()} kembali dengan serta-merta tanpa sebuah nilai, namun +bila sistem Android membuat koneksi antara klien +dan layanan, sistem akan memanggil {@link +android.content.ServiceConnection#onServiceConnected onServiceConnected()} pada {@link +android.content.ServiceConnection} untuk mengirim {@link android.os.IBinder} yang +bisa digunakan klien untuk berkomunikasi dengan layanan.</p> + +<p>Beberapa klien bisa terhubung ke layanan dengan serentak. Akan tetapi, sistem akan memanggil metode +{@link android.app.Service#onBind onBind()} layanan Anda untuk mengambil {@link android.os.IBinder} hanya +bila klien pertama mengikat. Sistem lalu memberikan {@link android.os.IBinder} yang sama ke setiap +klien tambahan yang mengikat, tanpa memanggil {@link android.app.Service#onBind onBind()} lagi.</p> + +<p>Bila klien terakhir melepas ikatan dari layanan, sistem akan menghapus layanan (kecuali jika +layanan juga dimulai oleh {@link android.content.Context#startService startService()}).</p> + +<p>Bila Anda mengimplementasikan layanan terikat, yang terpenting adalah mendefinisikan antarmuka +yang dihasilkan metode callback {@link android.app.Service#onBind onBind()} Anda. Ada sedikit +cara mendefinisikan antarmuka {@link android.os.IBinder} layanan Anda dan bagian berikut +akan membahas masing-masing teknik.</p> + + + +<h2 id="Creating">Membuat Layanan Terikat</h2> + +<p>Saat membuat layanan yang menyediakan pengikatan, Anda harus menyediakan {@link android.os.IBinder} +yang menyediakan antarmuka pemrograman yang bisa digunakan klien untuk berinteraksi dengan layanan. Ada +tiga cara untuk mendefinisikan antarmuka:</p> + +<dl> + <dt><a href="#Binder">Memperluas kelas Binder</a></dt> + <dd>Jika layanan Anda bersifat privat untuk aplikasi Anda sendiri dan berjalan dalam proses yang sama dengan klien +(biasanya), Anda harus membuat antarmuka dengan memperluas kelas {@link android.os.Binder} +dan menghasilkan instance dari +{@link android.app.Service#onBind onBind()}. Klien akan menerima {@link android.os.Binder} dan +bisa menggunakannya untuk mengakses langsung metode publik yang tersedia dalam implementasi {@link android.os.Binder} +atau bahkan {@link android.app.Service}. + <p>Inilah teknik yang lebih disukai bila layanan Anda sekadar pekerja latar belakang untuk aplikasi Anda +sendiri. Satu-satunya alasan tidak membuat antarmuka dengan cara ini adalah karena +layanan Anda akan digunakan oleh aplikasi lain atau pada proses-proses terpisah.</dd> + + <dt><a href="#Messenger">Menggunakan Messenger</a></dt> + <dd>Jika antarmuka Anda perlu bekerja lintas proses, Anda bisa membuat +antarmuka untuk layanan dengan {@link android.os.Messenger}. Dengan cara ini, layanan +mendefinisikan {@link android.os.Handler} yang akan merespons aneka tipe objek {@link +android.os.Message}. {@link android.os.Handler} +ini adalah dasar bagi {@link android.os.Messenger} yang nanti bisa berbagi {@link android.os.IBinder} +dengan klien, sehingga memungkinkan klien mengirim perintah ke layanan dengan menggunakan objek {@link +android.os.Message}. Selain itu, klien bisa mendefinisikan sendiri {@link android.os.Messenger} +sehingga layanan bisa mengirim balik pesan. + <p>Inilah cara termudah melakukan komunikasi antarproses (IPC), karena {@link +android.os.Messenger} akan mengantre semua permintaan ke dalam satu thread sehingga Anda tidak perlu mendesain +layanan agar thread-safe.</p> + </dd> + + <dt>Menggunakan AIDL</dt> + <dd>AIDL (Android Interface Definition Language) melakukan semua pekerjaan untuk mengurai objek menjadi +primitif yang bisa dipahami dan diarahkan oleh sistem operasi ke berbagai proses untuk melakukan +IPC. Teknik sebelumnya, dengan menggunakan {@link android.os.Messenger}, sebenarnya berdasarkan AIDL sebagai +struktur yang mendasarinya. Seperti disebutkan di atas, {@link android.os.Messenger} membuat antrean +semua permintaan klien dalam satu thread, sehingga layanan akan menerima permintaan satu per satu. Akan tetapi, +jika ingin layanan Anda menangani beberapa permintaan sekaligus, Anda bisa menggunakan AIDL +secara langsung. Dalam hal ini, layanan Anda harus mampu multi-thread dan dibuat thread-safe. + <p>Untuk menggunakan AIDL secara langsung, Anda harus +membuat file {@code .aidl} yang mendefinisikan antarmuka pemrograman. Alat Android SDK menggunakan +file ini untuk menghasilkan kelas abstrak yang mengimplementasikan antarmuka dan menangani IPC, yang nanti +bisa Anda perluas dalam layanan.</p> + </dd> +</dl> + + <p class="note"><strong>Catatan:</strong> Umumnya aplikasi <strong>tidak boleh</strong> menggunakan AIDL untuk +membuat layanan terikat, karena hal itu mungkin memerlukan kemampuan multi-thread dan +bisa mengakibatkan implementasi yang lebih rumit. Dengan demikian, AIDL tidak cocok untuk sebagian besar aplikasi +dan dokumen ini tidak membahas cara menggunakannya untuk layanan Anda. Jika Anda yakin perlu +menggunakan AIDL secara langsung, lihat dokumen <a href="{@docRoot}guide/components/aidl.html">AIDL</a> +.</p> + + + + +<h3 id="Binder">Memperluas kelas Binder</h3> + +<p>Jika layanan Anda hanya digunakan oleh aplikasi lokal dan tidak perlu bekerja lintas proses, +maka Anda bisa mengimplementasikan kelas {@link android.os.Binder} Anda sendiri yang memberi klien Anda +akses langsung ke metode publik dalam layanan.</p> + +<p class="note"><strong>Catatan:</strong> Hal ini hanya berhasil jika klien dan layanan berada dalam +aplikasi dan proses yang sama, suatu kondisi yang paling umum. Misalnya, cara ini sangat cocok untuk sebuah aplikasi musik +yang perlu mengikat aktivitas ke layanannya sendiri, yakni memutar musik di +latar belakang.</p> + +<p>Berikut cara menyiapkannya:</p> +<ol> + <li>Dalam layanan Anda, buat sebuah instance {@link android.os.Binder} yang: + <ul> + <li>berisi metode publik yang bisa dipanggil klien</li> + <li>menghasilkan instance {@link android.app.Service} saat ini, yang memiliki metode publik yang +bisa dipanggil klien</li> + <li>atau, menghasilkan instance kelas lain yang host-nya di layanan dengan metode publik yang +bisa dipanggil klien</li> + </ul> + <li>Hasilkan instance {@link android.os.Binder} ini dari metode callback {@link +android.app.Service#onBind onBind()}.</li> + <li>Di klien, terima {@link android.os.Binder} dari metode callback {@link +android.content.ServiceConnection#onServiceConnected onServiceConnected()} dan +buat panggilan ke layanan terikat dengan menggunakan metode yang disediakan.</li> +</ol> + +<p class="note"><strong>Catatan:</strong> Alasan layanan dan klien harus berada dalam aplikasi yang sama +adalah agar klien bisa mengkonversi objek yang dihasilkan dan memanggil API-nya dengan benar. Layanan +dan klien juga harus berada dalam proses yang sama, karena teknik ini tidak melakukan +pengarahan (marshalling) apa pun untuk lintas proses.</p> + +<p>Misalnya, berikut ini adalah layanan yang memberi klien akses ke metode-metode dalam layanan melalui +implementasi {@link android.os.Binder}:</p> + +<pre> +public class LocalService extends Service { + // Binder given to clients + private final IBinder mBinder = new LocalBinder(); + // Random number generator + private final Random mGenerator = new Random(); + + /** + * Class used for the client Binder. Because we know this service always + * runs in the same process as its clients, we don't need to deal with IPC. + */ + public class LocalBinder extends Binder { + LocalService getService() { + // Return this instance of LocalService so clients can call public methods + return LocalService.this; + } + } + + @Override + public IBinder onBind(Intent intent) { + return mBinder; + } + + /** method for clients */ + public int getRandomNumber() { + return mGenerator.nextInt(100); + } +} +</pre> + +<p>{@code LocalBinder} menyediakan {@code getService()} metode bagi klien untuk mengambil +instance {@code LocalService} saat ini. Cara ini memungkinkan klien memanggil metode publik dalam +layanan. Misalnya, klien bisa memanggil {@code getRandomNumber()} dari layanan.</p> + +<p>Berikut ini adalah aktivitas yang mengikat ke {@code LocalService} dan memanggil {@code getRandomNumber()} +bila tombol diklik:</p> + +<pre> +public class BindingActivity extends Activity { + LocalService mService; + boolean mBound = false; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } + + @Override + protected void onStart() { + super.onStart(); + // Bind to LocalService + Intent intent = new Intent(this, LocalService.class); + bindService(intent, mConnection, Context.BIND_AUTO_CREATE); + } + + @Override + protected void onStop() { + super.onStop(); + // Unbind from the service + if (mBound) { + unbindService(mConnection); + mBound = false; + } + } + + /** Called when a button is clicked (the button in the layout file attaches to + * this method with the android:onClick attribute) */ + public void onButtonClick(View v) { + if (mBound) { + // Call a method from the LocalService. + // However, if this call were something that might hang, then this request should + // occur in a separate thread to avoid slowing down the activity performance. + int num = mService.getRandomNumber(); + Toast.makeText(this, "number: " + num, Toast.LENGTH_SHORT).show(); + } + } + + /** Defines callbacks for service binding, passed to bindService() */ + private ServiceConnection mConnection = new ServiceConnection() { + + @Override + public void onServiceConnected(ComponentName className, + IBinder service) { + // We've bound to LocalService, cast the IBinder and get LocalService instance + LocalBinder binder = (LocalBinder) service; + mService = binder.getService(); + mBound = true; + } + + @Override + public void onServiceDisconnected(ComponentName arg0) { + mBound = false; + } + }; +} +</pre> + +<p>Contoh di atas menampilkan cara klien mengikat ke layanan dengan menggunakan implementasi +{@link android.content.ServiceConnection} dan callback {@link +android.content.ServiceConnection#onServiceConnected onServiceConnected()}. Bagian +berikut menyediakan informasi selengkapnya tentang proses pengikatan ke layanan.</p> + +<p class="note"><strong>Catatan:</strong> Contoh di atas tidak secara eksplisit melepas ikatan dari layanan, +namun semua klien harus melepas ikatan pada waktu yang tepat (seperti saat aktivitas sedang jeda).</p> + +<p>Untuk contoh kode selengkapnya, lihat kelas <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code +LocalService.java}</a> dan kelas <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.html">{@code +LocalServiceActivities.java}</a> dalam <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> + + + + + +<h3 id="Messenger">Menggunakan Messenger</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h4>Dibandingkan dengan AIDL</h4> + <p>Bila Anda perlu melakukan IPC, menggunakan {@link android.os.Messenger} untuk antarmuka +lebih sederhana daripada mengimplementasikannya dengan AIDL, karena {@link android.os.Messenger} mengantre +semua panggilan ke layanan, sementara antarmuka AIDL murni mengirim permintaan serentak ke +layanan, yang nanti harus menangani multi-threading.</p> + <p>Untuk sebagian besar aplikasi, layanan tidak perlu melakukan multi-threading, jadi dengan menggunakan {@link +android.os.Messenger} memungkinkan layanan menangani panggilan satu per satu. Jika +layanan harus multi-thread, Anda harus menggunakan <a href="{@docRoot}guide/components/aidl.html">AIDL</a> untuk mendefinisikan antarmuka.</p> +</div> +</div> + +<p>Jika layanan perlu berkomunikasi dengan proses jauh, Anda bisa menggunakan +{@link android.os.Messenger} untuk menyediakan antarmuka bagi layanan Anda. Teknik ini memungkinkan +Anda melakukan komunikasi antarproses (IPC) tanpa harus menggunakan AIDL.</p> + +<p>Berikut ini rangkuman cara menggunakan {@link android.os.Messenger}:</p> + +<ul> + <li>Layanan mengimplementasikan {@link android.os.Handler} yang menerima callback untuk tiap +panggilan dari klien.</li> + <li>{@link android.os.Handler} digunakan untuk membuat objek {@link android.os.Messenger} +(yang merupakan acuan ke {@link android.os.Handler}).</li> + <li>{@link android.os.Messenger} membuat {@link android.os.IBinder} yang +dikembalikan layanan ke klien dari {@link android.app.Service#onBind onBind()}.</li> + <li>Klien menggunakan {@link android.os.IBinder} untuk membuat instance {@link android.os.Messenger} +(yang mengacu {@link android.os.Handler} layanan), yang digunakan klien untuk mengirim +objek {@link android.os.Message} ke layanan.</li> + <li>Layanan menerima setiap {@link android.os.Message} dalam {@link +android.os.Handler}—secara spesifik, dalam metode {@link android.os.Handler#handleMessage +handleMessage()}.</li> +</ul> + + +<p>Dengan cara ini, tidak ada "metode" untuk dipanggil klien pada layanan. Sebagai gantinya, +klien mengirim "pesan" (objek-objek {@link android.os.Message}) yang diterima layanan dalam +{@link android.os.Handler}-nya.</p> + +<p>Berikut ini contoh layanan sederhana yang menggunakan antarmuka {@link android.os.Messenger}:</p> + +<pre> +public class MessengerService extends Service { + /** Command to the service to display a message */ + static final int MSG_SAY_HELLO = 1; + + /** + * Handler of incoming messages from clients. + */ + class IncomingHandler extends Handler { + @Override + public void handleMessage(Message msg) { + switch (msg.what) { + case MSG_SAY_HELLO: + Toast.makeText(getApplicationContext(), "hello!", Toast.LENGTH_SHORT).show(); + break; + default: + super.handleMessage(msg); + } + } + } + + /** + * Target we publish for clients to send messages to IncomingHandler. + */ + final Messenger mMessenger = new Messenger(new IncomingHandler()); + + /** + * When binding to the service, we return an interface to our messenger + * for sending messages to the service. + */ + @Override + public IBinder onBind(Intent intent) { + Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show(); + return mMessenger.getBinder(); + } +} +</pre> + +<p>Perhatikan bahwa metode {@link android.os.Handler#handleMessage handleMessage()} dalam +{@link android.os.Handler} adalah tempat layanan menerima {@link android.os.Message} +yang masuk dan memutuskan aksi yang harus dilakukan, berdasarkan anggota {@link android.os.Message#what}.</p> + +<p>Klien tinggal membuat {@link android.os.Messenger} berdasarkan {@link +android.os.IBinder} yang dihasilkan layanan dan mengirim pesan menggunakan {@link +android.os.Messenger#send send()}. Misalnya, berikut ini adalah aktivitas sederhana yang mengikat ke +layanan dan mengirim pesan {@code MSG_SAY_HELLO} ke layanan:</p> + +<pre> +public class ActivityMessenger extends Activity { + /** Messenger for communicating with the service. */ + Messenger mService = null; + + /** Flag indicating whether we have called bind on the service. */ + boolean mBound; + + /** + * Class for interacting with the main interface of the service. + */ + private ServiceConnection mConnection = new ServiceConnection() { + public void onServiceConnected(ComponentName className, IBinder service) { + // This is called when the connection with the service has been + // established, giving us the object we can use to + // interact with the service. We are communicating with the + // service using a Messenger, so here we get a client-side + // representation of that from the raw IBinder object. + mService = new Messenger(service); + mBound = true; + } + + public void onServiceDisconnected(ComponentName className) { + // This is called when the connection with the service has been + // unexpectedly disconnected -- that is, its process crashed. + mService = null; + mBound = false; + } + }; + + public void sayHello(View v) { + if (!mBound) return; + // Create and send a message to the service, using a supported 'what' value + Message msg = Message.obtain(null, MessengerService.MSG_SAY_HELLO, 0, 0); + try { + mService.send(msg); + } catch (RemoteException e) { + e.printStackTrace(); + } + } + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } + + @Override + protected void onStart() { + super.onStart(); + // Bind to the service + bindService(new Intent(this, MessengerService.class), mConnection, + Context.BIND_AUTO_CREATE); + } + + @Override + protected void onStop() { + super.onStop(); + // Unbind from the service + if (mBound) { + unbindService(mConnection); + mBound = false; + } + } +} +</pre> + +<p>Perhatikan bahwa contoh ini tidak menampilkan cara layanan merespons klien. Jika ingin +layanan merespons, Anda juga perlu membuat {@link android.os.Messenger} di klien. Lalu +saat menerima callback {@link android.content.ServiceConnection#onServiceConnected +onServiceConnected()}, klien akan mengirim {@link android.os.Message} ke layanan yang berisi +{@link android.os.Messenger} klien dalam parameter {@link android.os.Message#replyTo} +metode {@link android.os.Messenger#send send()}.</p> + +<p>Anda bisa melihat contoh cara menyediakan pertukaran pesan dua arah dalam contoh <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.html">{@code +MessengerService.java}</a> (layanan) dan <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.html">{@code +MessengerServiceActivities.java}</a> (klien).</p> + + + + + +<h2 id="Binding">Mengikat ke Layanan</h2> + +<p>Komponen-komponen aplikasi (klien) bisa mengikat ke layanan dengan memanggil +{@link android.content.Context#bindService bindService()}. Sistem Android +lalu memanggil metode {@link android.app.Service#onBind +onBind()} layanan, yang menghasilkan {@link android.os.IBinder} untuk berinteraksi dengan layanan.</p> + +<p>Pengikatan ini bersifat asinkron. {@link android.content.Context#bindService +bindService()} segera kembali dan <em>tidak</em> mengembalikan {@link android.os.IBinder} ke +klien. Untuk menerima {@link android.os.IBinder}, klien harus membuat instance {@link +android.content.ServiceConnection} dan meneruskannya ke {@link android.content.Context#bindService +bindService()}. {@link android.content.ServiceConnection} berisi metode callback yang +dipanggil sistem untuk mengirim {@link android.os.IBinder}.</p> + +<p class="note"><strong>Catatan:</strong> Hanya aktivitas, layanan, dan penyedia konten yang bisa mengikat +ke layanan yang—Anda <strong>tidak bisa</strong> ikat ke layanan dari penerima siaran.</p> + +<p>Jadi, untuk mengikat ke layanan dari klien, Anda harus: </p> +<ol> + <li>Mengimplementasikan {@link android.content.ServiceConnection}. + <p>Implementasi Anda harus mengesampingkan dua metode callback:</p> + <dl> + <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt> + <dd>Sistem memanggil ini untuk mengirim {@link android.os.IBinder} yang dihasilkan oleh +metode {@link android.app.Service#onBind onBind()} layanan.</dd> + <dt>{@link android.content.ServiceConnection#onServiceDisconnected +onServiceDisconnected()}</dt> + <dd>Sistem Android memanggil ini bila koneksi ke layanan putus +tanpa terduga, seperti ketika layanan mengalami crash atau dimatikan. Ini <em>tidak</em> dipanggil ketika +klien melepas ikatan.</dd> + </dl> + </li> + <li>Panggil {@link +android.content.Context#bindService bindService()}, dengan meneruskan implementasi {@link +android.content.ServiceConnection}. </li> + <li>Bila sistem memanggil metode callback {@link android.content.ServiceConnection#onServiceConnected +onServiceConnected()}, Anda bisa mulai membuat panggilan ke layanan, dengan menggunakan +metode yang didefinisikan oleh antarmuka.</li> + <li>Untuk memutus koneksi dari layanan, panggil {@link +android.content.Context#unbindService unbindService()}. + <p>Bila telah dimusnahkan (destroyed), klien Anda akan melepas ikatan dari layanan, namun Anda harus selalu melepas ikatan +bila sudah selesai berinteraksi dengan layanan atau bila aktivitas Anda sedang jeda sehingga layanan bisa +dimatikan saat tidak sedang digunakan. (Waktu yang tepat untuk mengikat dan melepas ikatan dibahas +selengkapnya di bawah ini.)</p> + </li> +</ol> + +<p>Misalnya, cuplikan berikut menghubungkan klien ke layanan yang dibuat di atas dengan +<a href="#Binder">memperluas kelas Binder</a>, sehingga tinggal mengkonversi +{@link android.os.IBinder} yang dihasilkan ke kelas {@code LocalService} dan meminta instance {@code +LocalService}:</p> + +<pre> +LocalService mService; +private ServiceConnection mConnection = new ServiceConnection() { + // Called when the connection with the service is established + public void onServiceConnected(ComponentName className, IBinder service) { + // Because we have bound to an explicit + // service that is running in our own process, we can + // cast its IBinder to a concrete class and directly access it. + LocalBinder binder = (LocalBinder) service; + mService = binder.getService(); + mBound = true; + } + + // Called when the connection with the service disconnects unexpectedly + public void onServiceDisconnected(ComponentName className) { + Log.e(TAG, "onServiceDisconnected"); + mBound = false; + } +}; +</pre> + +<p>Dengan {@link android.content.ServiceConnection} ini, klien bisa mengikat ke layanan dengan meneruskannya +ke {@link android.content.Context#bindService bindService()}. Misalnya:</p> + +<pre> +Intent intent = new Intent(this, LocalService.class); +bindService(intent, mConnection, Context.BIND_AUTO_CREATE); +</pre> + +<ul> + <li>Parameter pertama {@link android.content.Context#bindService bindService()} adalah sebuah +{@link android.content.Intent} yang secara eksplisit menyebutkan layanan yang akan diikat (walaupun intent +boleh implisit).</li> +<li>Parameter kedua adalah objek {@link android.content.ServiceConnection}.</li> +<li>Parameter ketiga adalah tanda (flag) yang menunjukkan opsi pengikatan. Tanda ini biasanya harus {@link +android.content.Context#BIND_AUTO_CREATE} agar dapat membuat layanan jika belum hidup. +Nilai-nilai lain yang memungkinkan adalah {@link android.content.Context#BIND_DEBUG_UNBIND} +dan {@link android.content.Context#BIND_NOT_FOREGROUND}, atau {@code 0} untuk tidak satu pun.</li> +</ul> + + +<h3>Catatan tambahan</h3> + +<p>Berikut ini beberapa catatan penting tentang mengikat ke layanan:</p> +<ul> + <li>Anda harus selalu menjebak eksepsi {@link android.os.DeadObjectException}, yang dilontarkan +bila koneksi terputus. Inilah satu-satunya eksepsi yang dilontarkan oleh metode jauh.</li> + <li>Objek adalah acuan yang dihitung lintas proses. </li> + <li>Anda biasanya harus memasangkan pengikatan dan pelepasan ikatan selama +memasangkan momen membuat dan menghapus daur hidup klien. Misalnya: + <ul> + <li>Jika Anda hanya perlu berinteraksi dengan layanan saat aktivitas terlihat, Anda +harus mengikat selama {@link android.app.Activity#onStart onStart()} dan melepas ikatan selama {@link +android.app.Activity#onStop onStop()}.</li> + <li>Jika Anda ingin aktivitas menerima tanggapan bahkan saat dihentikan di +latar belakang, Anda bisa mengikat selama {@link android.app.Activity#onCreate onCreate()} dan melepas ikatan +selama {@link android.app.Activity#onDestroy onDestroy()}. Berhati-hatilah karena hal ini menyiratkan aktivitas +Anda perlu menggunakan layanan selama dijalankan (sekalipun di latar belakang), jadi jika +layanan berada dalam proses lain, Anda meningkatkan bobot proses dan semakin besar +kemungkinan sistem akan mematikannya.</li> + </ul> + <p class="note"><strong>Catatan:</strong> Anda biasanya <strong>tidak</strong> boleh mengikat dan melepas ikatan +selama {@link android.app.Activity#onResume onResume()} aktivitas Anda dan {@link +android.app.Activity#onPause onPause()}, karena callback ini terjadi pada setiap transisi daur hidup +dan Anda harus menjaga pemrosesan yang terjadi pada transisi ini tetap minim. Juga, jika +banyak aktivitas dalam aplikasi Anda mengikat ke layanan yang sama dan ada transisi antara +dua aktivitas, layanan bisa dimusnahkan dan dibuat lagi sambil aktivitas saat ini melepas ikatan +(selama jeda) sebelum aktivitas berikutnya mengikat (selama lanjutkan). (Transisi aktivitas ini untuk cara +aktivitas mengoordinasikan daur hidupnya dijelaskan dalam dokumen <a href="{@docRoot}guide/components/activities.html#CoordinatingActivities">Aktivitas</a> +.)</p> +</ul> + +<p>Untuk contoh kode selengkapnya, yang menampilkan cara mengikat ke layanan, lihat kelas <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code +RemoteService.java}</a> dalam <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> + + + + + +<h2 id="Lifecycle">Mengelola Daur Hidup Layanan Terikat</h2> + +<p>Bila layanan dilepas ikatannya dari semua klien, sistem Android akan menghapusnya (kecuali jika layanan juga +dimulai dengan {@link android.app.Service#onStartCommand onStartCommand()}). Dengan demikian, Anda tidak harus +mengelola daur hidup layanan jika layanan itu murni sebuah layanan +terikat—yang dikelola sistem Android untuk Anda berdasarkan apakah layanan terikat ke klien atau tidak.</p> + +<p>Akan tetapi, Jika Anda memilih untuk mengimplementasikan metode callback {@link android.app.Service#onStartCommand +onStartCommand()}, maka Anda harus menghentikan layanan secara eksplisit, karena layanan +sekarang dianggap telah <em>dimulai</em>. Dalam hal ini, layanan akan berjalan hingga layanan +menghentikan dirinya sendiri dengan {@link android.app.Service#stopSelf()} atau panggilan komponen lain {@link +android.content.Context#stopService stopService()}, terlepas dari apakah layanan terikat ke +klien atau tidak.</p> + +<p>Selain itu, jika layanan Anda telah dimulai dan menerima pengikatan, maka saat sistem memanggil +metode {@link android.app.Service#onUnbind onUnbind()}, Anda bisa memilih untuk mengembalikan +{@code true} jika ingin menerima panggilan ke {@link android.app.Service#onRebind +onRebind()} bila nanti klien mengikat ke layanan (sebagai ganti menerima panggilan ke {@link +android.app.Service#onBind onBind()}). {@link android.app.Service#onRebind +onRebind()} akan menghasilkan void, namun klien tetap menerima {@link android.os.IBinder} dalam callback +{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}. +Di bawah ini adalah gambar 1 yang mengilustrasikan logika untuk jenis daur hidup ini.</p> + + +<img src="{@docRoot}images/fundamentals/service_binding_tree_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Daur hidup untuk layanan yang dimulai +dan juga memungkinkan pengikatan.</p> + + +<p>Untuk informasi selengkapnya tentang daur hidup layanan yang telah dimulai, lihat dokumen <a href="{@docRoot}guide/components/services.html#Lifecycle">Layanan</a>.</p> + + + + diff --git a/docs/html-intl/intl/in/guide/components/fragments.jd b/docs/html-intl/intl/in/guide/components/fragments.jd new file mode 100644 index 000000000000..14d4ef3eccbf --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/fragments.jd @@ -0,0 +1,812 @@ +page.title=Fragmen +parent.title=Aktivitas +parent.link=activities.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#Design">Filosofi Desain</a></li> + <li><a href="#Creating">Membuat Fragmen</a> + <ol> + <li><a href="#UI">Menambahkan antarmuka pengguna</a></li> + <li><a href="#Adding">Menambahkan fragmen ke aktivitas</a></li> + </ol> + </li> + <li><a href="#Managing">Mengelola Fragmen</a></li> + <li><a href="#Transactions">Melakukan Transaksi Fragmen</a></li> + <li><a href="#CommunicatingWithActivity">Berkomunikasi dengan Aktivitas</a> + <ol> + <li><a href="#EventCallbacks">Membuat callback kejadian pada aktivitas</a></li> + <li><a href="#ActionBar">Menambahkan item ke Action-Bar</a></li> + </ol> + </li> + <li><a href="#Lifecycle">Menangani Daur Hidup Fragmen</a> + <ol> + <li><a href="#CoordinatingWithActivity">Mengoordinasi dengan daur hidup aktivitas</a></li> + </ol> + </li> + <li><a href="#Example">Contoh</a></li> + </ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.app.Fragment}</li> + <li>{@link android.app.FragmentManager}</li> + <li>{@link android.app.FragmentTransaction}</li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="{@docRoot}training/basics/fragments/index.html">Membangun UI Dinamis dengan Fragmen</a></li> + <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Mendukung Tablet +dan Handset</a></li> + </ol> +</div> +</div> + +<p>{@link android.app.Fragment} mewakili perilaku atau bagian dari antarmuka pengguna dalam +{@link android.app.Activity}. Anda bisa mengombinasikan beberapa fragmen dalam satu aktivitas untuk membangun UI +multipanel dan menggunakan kembali sebuah fragmen dalam beberapa aktivitas. Anda bisa menganggap fragmen sebagai bagian +modular dari aktivitas, yang memiliki daur hidup sendiri, menerima kejadian input sendiri, dan +yang bisa Anda tambahkan atau hapus saat aktivitas berjalan (semacam "sub aktivitas" yang +bisa digunakan kembali dalam aktivitas berbeda).</p> + +<p>Fragmen harus selalu tertanam dalam aktivitas dan daur hidup fragmen secara langsung +dipengaruhi oleh daur hidup aktivitas host-nya. Misalnya, saat aktivitas dihentikan sementara, +semua fragmen di dalamnya juga dihentikan sementara, dan bila aktivitas dimusnahkan, semua fragmen juga demikian. Akan tetapi, saat +aktivitas berjalan (dalam <a href="{@docRoot}guide/components/activities.html#Lifecycle">status daur hidup</a> <em>dilanjutkan</em>, Anda bisa +memanipulasi setiap fragmen secara terpisah, seperti menambah atau menghapusnya. Saat melakukan transaksi +fragmen, Anda juga bisa menambahkannya ke back-stack yang dikelola oleh aktivitas +—setiap entri back-stack merupakan record transaksi fragmen yang +terjadi. Dengan back-stack pengguna dapat membalikkan transaksi fragmen (mengarah mundur), +dengan menekan tombol <em>Back</em>.</p> + +<p>Bila Anda menambahkan fragmen sebagai bagian dari layout aktivitas, fragmen itu berada dalam {@link +android.view.ViewGroup} di hierarki tampilan aktivitas tersebut dan fragmen mendefinisikan +layout +tampilannya sendiri. Anda bisa menyisipkan fragmen ke dalam layout aktivitas dengan mendeklarasikan fragmen dalam file layout aktivitas +, sebagai elemen {@code <fragment>}, atau dari kode aplikasi dengan menambahkannya ke + {@link android.view.ViewGroup} yang ada. Akan tetapi, fragmen tidak harus menjadi bagian dari +layout aktivitas; Anda juga bisa menggunakan fragmen tanpa UI-nya sendiri sebagai pekerja tak terlihat untuk +aktivitas tersebut.</p> + +<p>Dokumen ini menjelaskan cara membangun aplikasi menggunakan fragmen, termasuk +cara fragmen mempertahankan statusnya bila ditambahkan ke back-stack aktivitas, berbagi +kejadian dengan aktivitas, dan fragmen lain dalam aktivitas, berkontribusi pada action-bar +aktivitas, dan lainnya.</p> + + +<h2 id="Design">Filosofi Desain</h2> + +<p>Android memperkenalkan fragmen di Android 3.0 (API level 11), terutama untuk mendukung desain UI yang lebih +dinamis dan fleksibel pada layar besar, seperti tablet. Karena +layar tablet jauh lebih besar daripada layar handset, maka lebih banyak ruang untuk mengombinasikan dan +bertukar komponen UI. Fragmen memungkinkan desain seperti itu tanpa perlu mengelola perubahan +kompleks pada hierarki tampilan. Dengan membagi layout aktivitas menjadi beberapa fragmen, Anda bisa +mengubah penampilan aktivitas saat runtime dan mempertahankan perubahan itu di back-stack +yang dikelola oleh aktivitas.</p> + +<p>Misalnya, aplikasi berita bisa menggunakan satu fragmen untuk menampilkan daftar artikel di +sebelah kiri dan fragmen lainnya untuk menampilkan artikel di sebelah kanan—kedua fragmen ini muncul di satu +aktivitas, berdampingan, dan masing-masing fragmen memiliki serangkaian metode callback daur hidup dan menangani kejadian input +penggunanya sendiri. Sehingga, sebagai ganti menggunakan satu aktivitas untuk memilih +artikel dan aktivitas lainnya untuk membaca artikel, pengguna bisa memilih artikel dan membaca semuanya dalam +aktivitas yang sama, sebagaimana diilustrasikan dalam layout tablet pada gambar 1.</p> + +<p>Anda harus mendesain masing-masing fragmen sebagai komponen aktivitas modular dan bisa digunakan kembali. Yakni, karena +setiap fragmen mendefinisikan layoutnya dan perilakunya dengan callback daur hidupnya sendiri, Anda bisa memasukkan +satu fragmen dalam banyak aktivitas, sehingga Anda harus mendesainnya untuk digunakan kembali dan mencegah +memanipulasi satu fragmen dari fragmen lain secara langsung. Ini terutama penting karena dengan +fragmen modular Anda bisa mengubah kombinasi fragmen untuk ukuran layar berbeda. Saat mendesain aplikasi +untuk mendukung tablet maupun handset, Anda bisa menggunakan kembali fragmen dalam +konfigurasi layout berbeda untuk mengoptimalkan pengalaman pengguna berdasarkan ruang layar yang tersedia. Misalnya +, pada handset, fragmen mungkin perlu dipisahkan untuk menyediakan UI panel tunggal +bila lebih dari satu yang tidak cocok dalam aktivitas yang sama.</p> + +<img src="{@docRoot}images/fundamentals/fragments.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Contoh cara dua modul UI yang didefinisikan oleh + fragmen bisa digabungkan ke dalam satu aktivitas untuk desain tablet, namun dipisahkan untuk +desain handset.</p> + +<p>Misalnya—untuk melanjutkan contoh aplikasi berita— aplikasi bisa menanamkan +dua fragmen dalam <em>Aktivitas A</em>, saat berjalan pada perangkat berukuran tablet. Akan tetapi, pada +layar berukuran handset, ruang untuk kedua fragmen tidak cukup, sehingga <em>Aktivitas A</em> hanya +menyertakan fragmen untuk daftar artikel, dan saat pengguna memilih artikel, +<em>Aktivitas B</em> akan dimulai, termasuk fragmen kedua untuk membaca artikel. Sehingga, aplikasi mendukung +tablet dan handset dengan menggunakan kembali fragmen dalam kombinasi berbeda, seperti diilustrasikan dalam +gambar 1.</p> + +<p>Untuk informasi selengkapnya tentang mendesain aplikasi menggunakan kombinasi fragmen berbeda +untuk konfigurasi layar berbeda, lihat panduan untuk <a href="{@docRoot}guide/practices/tablets-and-handsets.html">Mendukung Tablet dan Handset</a>.</p> + + + +<h2 id="Creating">Membuat Fragmen</h2> + +<div class="figure" style="width:327px"> +<img src="{@docRoot}images/fragment_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Gambar 2.</strong> Daur hidup fragmen (saat + aktivitasnya berjalan).</p> +</div> + +<p>Untuk membuat fragmen, Anda harus membuat subkelas {@link android.app.Fragment} (atau +subkelasnya yang ada). Kelas {@link android.app.Fragment} memiliki kode yang mirip seperti +{@link android.app.Activity}. Kelas ini memiliki metode callback yang serupa dengan aktivitas, seperti + {@link android.app.Fragment#onCreate onCreate()}, {@link android.app.Fragment#onStart onStart()}, +{@link android.app.Fragment#onPause onPause()}, dan {@link android.app.Fragment#onStop onStop()}. Sebenarnya +, jika Anda mengkonversi aplikasi Android saat ini untuk menggunakan fragmen, Anda mungkin cukup memindahkan +kode dari metode callback aktivitas ke masing-masing metode callback +fragmen.</p> + +<p>Biasanya, Anda harus mengimplementasikan setidaknya metode daur hidup berikut ini:</p> + +<dl> + <dt>{@link android.app.Fragment#onCreate onCreate()}</dt> + <dd>Sistem akan memanggilnya saat membuat fragmen. Dalam implementasi, Anda harus +menginisialisasi komponen penting dari fragmen yang ingin dipertahankan saat fragmen +dihentikan sementara atau dihentikan, kemudian dilanjutkan.</dd> + <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> + <dd>Sistem akan memanggilnya saat fragmen menggambar antarmuka penggunanya +untuk yang pertama kali. Untuk menggambar UI fragmen, Anda harus mengembalikan {@link android.view.View} dari metode +ini yang menjadi akar layout fragmen. Hasil yang dikembalikan bisa berupa null jika +fragmen tidak menyediakan UI.</dd> + <dt>{@link android.app.Activity#onPause onPause()}</dt> + <dd>Sistem akan memanggil metode ini sebagai indikasi pertama bahwa pengguna sedang meninggalkan +fragmen Anda (walau itu tidak selalu berarti fragmen sedang dimusnahkan). Inilah biasanya tempat Anda +harus mengikat setiap perubahan yang harus dipertahankan selepas sesi pengguna saat ini (karena +pengguna mungkin tidak kembali).</dd> +</dl> + +<p>Kebanyakan aplikasi harus mengimplementasikan setidaknya tiga metode ini untuk setiap fragmen, namun ada +beberapa metode callback lain yang juga harus Anda gunakan untuk menangani berbagai tahap +daur hidup fragmen. Semua metode callback daur hidup akan dibahas secara lebih detail, di bagian +tentang <a href="#Lifecycle">Menangani Daur Hidup Fragmen</a>.</p> + + +<p>Ada juga beberapa subkelas yang mungkin ingin diperpanjang, sebagai ganti kelas basis {@link +android.app.Fragment}:</p> + +<dl> + <dt>{@link android.app.DialogFragment}</dt> + <dd>Menampilkan dialog mengambang. Penggunaan kelas ini untuk membuat dialog merupakan alternatif yang baik dari +penggunaan metode helper dialog di kelas {@link android.app.Activity}, karena Anda bisa +menyatukan dialog fragmen ke dalam back-stack fragmen yang dikelola oleh aktivitas, +sehingga pengguna bisa kembali ke fragmen yang ditinggalkan.</dd> + + <dt>{@link android.app.ListFragment}</dt> + <dd>Menampilkan daftar item yang dikelola oleh adaptor (seperti {@link +android.widget.SimpleCursorAdapter}), serupa dengan {@link android.app.ListActivity}. Menampilkan +beberapa metode pengelolaan daftar tampilan seperti callback {@link +android.app.ListFragment#onListItemClick(ListView,View,int,long) onListItemClick()} untuk +menangani kejadian klik.</dd> + + <dt>{@link android.preference.PreferenceFragment}</dt> + <dd>Menampilkan hierarki objek {@link android.preference.Preference} sebagai daftar, serupa dengan +{@link android.preference.PreferenceActivity}. Hal ini berguna saat membuat aktivitas +"pengaturan" untuk aplikasi Anda.</dd> +</dl> + + +<h3 id="UI">Menambahkan antarmuka pengguna</h3> + +<p>Fragmen biasanya digunakan sebagai bagian dari antarmuka pengguna aktivitas dan menyumbangkan +layoutnya sendiri ke aktivitas.</p> + +<p>Untuk menyediakan layout fragmen, Anda harus mengimplementasikan metode callback {@link +android.app.Fragment#onCreateView onCreateView()}, yang dipanggil sistem Android +bila tiba saatnya fragmen menggambar layoutnya. Implementasi Anda atas metode ini harus mengembalikan +{@link android.view.View} yang menjadi akar layout fragmen.</p> + +<p class="note"><strong>Catatan:</strong> Jika fragmen adalah subkelas {@link +android.app.ListFragment}, implementasi default akan mengembalikan {@link android.widget.ListView} dari +{@link android.app.Fragment#onCreateView onCreateView()}, sehingga Anda tidak perlu mengimplementasikannya.</p> + +<p>Untuk mengembalikan layout dari {@link +android.app.Fragment#onCreateView onCreateView()}, Anda bisa memekarkannya dari <a href="{@docRoot}guide/topics/resources/layout-resource.html">sumber daya layout</a> yang didefinisikan di XML. Untuk +membantu melakukannya, {@link android.app.Fragment#onCreateView onCreateView()} menyediakan objek +{@link android.view.LayoutInflater}.</p> + +<p>Misalnya, ini adalah subkelas {@link android.app.Fragment} yang memuat layout dari file +{@code example_fragment.xml}:</p> + +<pre> +public static class ExampleFragment extends Fragment { + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // Inflate the layout for this fragment + return inflater.inflate(R.layout.example_fragment, container, false); + } +} +</pre> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Membuat layout</h3> + <p>Dalam contoh di atas, {@code R.layout.example_fragment} merupakan acuan ke sumber daya layout +bernama {@code example_fragment.xml} yang tersimpan dalam sumber daya aplikasi. Untuk informasi tentang cara +membuat layout di XML, lihat dokumentasi +<a href="{@docRoot}guide/topics/ui/index.html">Antarmuka Pengguna</a>.</p> +</div> +</div> + +<p>Parameter {@code container} yang diteruskan ke {@link android.app.Fragment#onCreateView +onCreateView()} adalah induk {@link android.view.ViewGroup} (dari layout aktivitas) tempat +layout fragmen +akan disisipkan. Parameter {@code savedInstanceState} adalah {@link android.os.Bundle} yang +menyediakan data tentang instance fragmen sebelumnya, jika fragmen dilanjutkan +(status pemulihan dibahas selengkapnya di bagian tentang <a href="#Lifecycle">Menangani +Daur Hidup Fragmen</a>).</p> + +<p>Metode {@link android.view.LayoutInflater#inflate(int,ViewGroup,boolean) inflate()} membutuhkan +tiga argumen:</p> +<ul> + <li>ID sumber daya layout yang ingin dimekarkan.</li> + <li>{@link android.view.ViewGroup} akan menjadi induk dari layout yang dimekarkan. {@code +container} perlu diteruskan agar sistem menerapkan parameter layout ke tampilan akar layout +yang dimekarkan, yang ditetapkan dalam tampilan induk yang akan dituju.</li> + <li>Boolean yang menunjukkan apakah layout akan dimekarkan harus ditempelkan pada {@link +android.view.ViewGroup} (parameter kedua) selama pemekaran. (Dalam hal ini, ini +salah karena sistem sudah memasukkan layout yang dimekarkan ke dalam {@code +container}—meneruskan benar akan membuat tampilan grup yang berlebihan dalam layout akhir.)</li> +</ul> + +<p>Anda kini telah melihat cara membuat fragmen yang menyediakan layout. Berikutnya, Anda perlu menambahkan +fragmen ke aktivitas.</p> + + + +<h3 id="Adding">Menambahkan fragmen ke aktivitas</h3> + +<p>Biasanya, fragmen berkontribusi pada sebagian UI ke aktivitas host, yang ditanamkan sebagai +bagian dari hierarki tampilan keseluruhan aktivitas. Ada dua cara untuk menambahkan fragmen ke layout +aktivitas:</p> + +<ul> + <li><b>Deklarasikan fragmen dalam file layout aktivitas.</b> +<p>Dalam hal ini, Anda bisa +menetapkan properti layout fragmen seakan-akan sebuah tampilan. Misalnya, berikut ini adalah file +layout untuk aktivitas dengan dua fragmen:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <fragment android:name="com.example.news.ArticleListFragment" + android:id="@+id/list" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="match_parent" /> + <fragment android:name="com.example.news.ArticleReaderFragment" + android:id="@+id/viewer" + android:layout_weight="2" + android:layout_width="0dp" + android:layout_height="match_parent" /> +</LinearLayout> +</pre> + <p>Atribut {@code android:name} dalam {@code <fragment>} menetapkan kelas {@link +android.app.Fragment} untuk dibuat instance-nya dalam layout.</p> + +<p>Saat sistem membuat layout aktivitas, sistem membuat instance setiap fragmen sebagaimana yang ditetapkan dalam layout +dan memanggil metode {@link android.app.Fragment#onCreateView onCreateView()} masing-masing, +untuk mengambil setiap fragmen. Sistem akan menyisipkan {@link android.view.View} yang dikembalikan langsung oleh fragmen, + menggantikan elemen {@code <fragment>}.</p> + +<div class="note"> + <p><strong>Catatan:</strong> Setiap fragmen memerlukan identifier +unik yang bisa digunakan sistem untuk memulihkan fragmen jika aktivitas dimulai kembali (dan identifier yang bisa digunakan menangkap +fragmen untuk melakukan transaksi, seperti menghapusnya). Ada tiga cara untuk memberikan +ID bagi fragmen:</p> + <ul> + <li>Memberikan atribut {@code android:id} bersama ID unik.</li> + <li>Memberikan atribut {@code android:tag} bersama string unik.</li> + <li>Jika Anda tidak memberikan dua hal tersebut, sistem akan menggunakan ID +tampilan kontainer.</li> + </ul> +</div> + </li> + + <li><b>Atau, secara programatis tambahkan fragmen ke {@link android.view.ViewGroup} yang ada.</b> +<p>Kapan saja saat aktivitas berjalan, Anda bisa menambahkan fragmen ke layout aktivitas. Anda +cukup menetapkan {@link +android.view.ViewGroup} di tempat memasukkan fragmen.</p> + <p>Untuk membuat transaksi fragmen dalam aktivitas (seperti menambah, menghapus, atau mengganti +fragmen), Anda harus menggunakan API dari {@link android.app.FragmentTransaction}. Anda bisa mengambil instance + {@link android.app.FragmentTransaction} dari {@link android.app.Activity} seperti ini:</p> + +<pre> +FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()} +FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()}; +</pre> + +<p>Selanjutnya Anda bisa menambahkan fragmen menggunakan metode {@link +android.app.FragmentTransaction#add(int,Fragment) add()}, dengan menetapkan fragmen yang akan ditambahkan dan +tampilan tempat menyisipkannya. Misalnya:</p> + +<pre> +ExampleFragment fragment = new ExampleFragment(); +fragmentTransaction.add(R.id.fragment_container, fragment); +fragmentTransaction.commit(); +</pre> + + <p>Argumen pertama yang diteruskan ke {@link android.app.FragmentTransaction#add(int,Fragment) add()} + adalah {@link android.view.ViewGroup} tempat fragmen harus dimasukkan, yang ditetapkan oleh +ID sumber daya, dan parameter kedua merupakan fragmen yang akan ditambahkan.</p> + <p>Setelah membuat perubahan dengan +{@link android.app.FragmentTransaction}, Anda harus + memanggil {@link android.app.FragmentTransaction#commit} untuk menerapkan perubahan.</p> + </li> +</ul> + + +<h4 id="AddingWithoutUI">Menambahkan fragmen tanpa UI</h4> + +<p>Contoh di atas menampilkan cara menambahkan fragmen ke aktivitas untuk menyediakan UI. Akan tetapi, +Anda juga bisa menggunakan fragmen untuk menyediakan perilaku latar belakang bagi aktivitas tanpa menampilkan UI +tambahan.</p> + +<p>Untuk menambahkan fragmen tanpa UI, tambahkan fragmen dari aktivitas menggunakan {@link +android.app.FragmentTransaction#add(Fragment,String)} (dengan menyediakan string unik "tag" untuk fragmen +, bukan ID tampilan). Ini akan menambahkan fragmen, namun, karena tidak dikaitkan dengan tampilan +dalam layout aktivitas, ini tidak akan menerima panggilan ke {@link +android.app.Fragment#onCreateView onCreateView()}. Jadi Anda tidak perlu mengimplementasikan metode itu.</p> + +<p>Menyediakan tag string untuk fragmen tidak hanya untuk fragmen non-UI—Anda juga bisa +menyediakan tag string untuk fragmen yang memiliki UI—namun jika fragmen tidak memiliki UI +, maka tag string adalah satu-satunya cara untuk mengidentifikasinya. Jika Anda ingin mendapatkan fragmen dari +aktivitas nantinya, Anda perlu menggunakan {@link android.app.FragmentManager#findFragmentByTag +findFragmentByTag()}.</p> + +<p>Untuk contoh aktivitas yang menggunakan fragmen sebagai pekerja latar belakang, tanpa UI, lihat sampel {@code +FragmentRetainInstance.java}, yang disertakan dalam sampel SDK (tersedia melalui +Android SDK Manager) dan terletak di sistem Anda sebagai +<code><sdk_root>/APIDemos/app/src/main/java/com/example/android/apis/app/FragmentRetainInstance.java</code>.</p> + + + +<h2 id="Managing">Mengelola Fragmen</h2> + +<p>Untuk mengelola fragmen dalam aktivitas, Anda perlu menggunakan {@link android.app.FragmentManager}. Untuk +mendapatkannya, panggil {@link android.app.Activity#getFragmentManager()} dari aktivitas Anda.</p> + +<p>Beberapa hal yang dapat Anda lakukan dengan {@link android.app.FragmentManager} antara lain:</p> + +<ul> + <li>Dapatkan fragmen yang ada di aktivitas dengan {@link +android.app.FragmentManager#findFragmentById findFragmentById()} (untuk fragmen yang menyediakan UI dalam +layout aktivitas) atau {@link android.app.FragmentManager#findFragmentByTag +findFragmentByTag()} (untuk fragmen yang menyediakan atau tidak menyediakan UI).</li> + <li>Tarik fragmen dari back-stack, dengan {@link +android.app.FragmentManager#popBackStack()} (mensimulasikan perintah <em>Back</em> oleh pengguna).</li> + <li>Daftarkan listener untuk perubahan pada back-stack, dengan {@link +android.app.FragmentManager#addOnBackStackChangedListener addOnBackStackChangedListener()}.</li> +</ul> + +<p>Untuk informasi selengkapnya tentang metode ini dan hal lainnya, lihat dokumentasi kelas {@link +android.app.FragmentManager}.</p> + +<p>Seperti yang ditunjukkan di bagian sebelumnya, Anda juga bisa menggunakan {@link android.app.FragmentManager} +untuk membuka {@link android.app.FragmentTransaction}, sehingga Anda bisa melakukan transaksi, seperti +menambah dan menghapus fragmen.</p> + + +<h2 id="Transactions">Melakukan Transaksi Fragmen</h2> + +<p>Fitur menarik terkait penggunaan fragmen di aktivitas adalah kemampuan menambah, menghapus, mengganti, +dan melakukan tindakan lain dengannya, sebagai respons atas interaksi pengguna. Setiap set perubahan +yang Anda lakukan untuk aktivitas disebut transaksi dan Anda bisa melakukan transaksi menggunakan API di {@link +android.app.FragmentTransaction}. Anda juga bisa menyimpan setiap transaksi ke back-stack yang dikelola +aktivitas, sehingga pengguna bisa mengarah mundur melalui perubahan fragmen (mirip mengarah +mundur melalui aktivitas).</p> + +<p>Anda bisa mengambil instance {@link android.app.FragmentTransaction} dari {@link +android.app.FragmentManager} seperti ini:</p> + +<pre> +FragmentManager fragmentManager = {@link android.app.Activity#getFragmentManager()}; +FragmentTransaction fragmentTransaction = fragmentManager.{@link android.app.FragmentManager#beginTransaction()}; +</pre> + +<p>Setiap transaksi merupakan serangkaian perubahan yang ingin dilakukan pada waktu yang sama. Anda bisa +mengatur semua perubahan yang ingin dilakukan untuk transaksi mana saja menggunakan metode seperti {@link +android.app.FragmentTransaction#add add()}, {@link android.app.FragmentTransaction#remove remove()}, +dan {@link android.app.FragmentTransaction#replace replace()}. Kemudian, untuk menerapkan transaksi +pada aktivitas, Anda harus memanggil {@link android.app.FragmentTransaction#commit()}.</p> +</dl> + +<p>Akan tetapi, sebelum memanggil {@link +android.app.FragmentTransaction#commit()}, Anda mungkin perlu memanggil {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()}, untuk menambahkan transaksi +ke back-stack dari transaksi fragmen. Back-stack ini dikelola oleh aktivitas dan memungkinkan +pengguna kembali ke status fragmen sebelumnya, dengan menekan tombol <em>Back</em>.</p> + +<p>Misalnya, berikut ini cara mengganti satu fragmen dengan yang fragmen yang lain, dan mempertahankan +status sebelumnya di back-stack:</p> + +<pre> +// Create new fragment and transaction +Fragment newFragment = new ExampleFragment(); +FragmentTransaction transaction = getFragmentManager().beginTransaction(); + +// Replace whatever is in the fragment_container view with this fragment, +// and add the transaction to the back stack +transaction.replace(R.id.fragment_container, newFragment); +transaction.addToBackStack(null); + +// Commit the transaction +transaction.commit(); +</pre> + +<p>Dalam contoh ini, {@code newFragment} menggantikan fragmen apa saja (jika ada) yang saat ini berada dalam +kontainer layout yang diidentifikasi oleh ID {@code R.id.fragment_container}. Dengan memanggil @link +android.app.FragmentTransaction#addToBackStack addToBackStack()}, transaksi yang diganti +disimpan ke back-stack sehingga pengguna bisa membalikkan transaksi dan mengembalikan fragmen +sebelumnya dengan menekan tombol <em>Back</em>.</p> + +<p>Jika Anda menambahkan beberapa perubahan pada transaksi (seperti {@link +android.app.FragmentTransaction#add add()} atau {@link android.app.FragmentTransaction#remove +remove()}) dan panggil {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()}, maka semua perubahan akan diterapkan +sebelum Anda memanggil {@link android.app.FragmentTransaction#commit commit()} akan ditambahkan ke +back-stack sebagai satu transaksi dan tombol <em>Back</em> akan membalikannya semua.</p> + +<p>Urutan menambahkan perubahan pada {@link android.app.FragmentTransaction} tidak berpengaruh, +kecuali:</p> +<ul> + <li>Anda harus memanggil {@link android.app.FragmentTransaction#commit()} paling akhir</li> + <li>Jika Anda menambahkan beberapa fragmen ke kontainer yang sama, maka +urutan penambahannya akan menentukan urutan munculnya dalam hierarki tampilan</li> +</ul> + +<p>Jika Anda tidak memanggil {@link android.app.FragmentTransaction#addToBackStack(String) +addToBackStack()} saat melakukan transaksi yang menghapus fragmen, maka fragmen itu +akan dimusnahkan bila transaksi diikat dan pengguna tidak bisa mengarah kembali ke sana. Sedangkan, jika +Anda memanggil {@link android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} saat +menghapus fragmen, maka fragmen itu akan <em>dihentikan</em> dan akan dilanjutkan jika pengguna mengarah +kembali.</p> + +<p class="note"><strong>Tip:</strong> Untuk setiap transaksi fragmen, Anda bisa menerapkan animasi +transisi, dengan memanggil {@link android.app.FragmentTransaction#setTransition setTransition()} sebelum +mengikatnya.</p> + +<p>Memanggil {@link android.app.FragmentTransaction#commit()} tidak akan langsung menjalankan +transaksi. Namun sebuah jadwal akan dibuat untuk dijalankan pada thread UI aktivitas (thread "utama") +begitu thread bisa melakukannya. Akan tetapi, jika perlu Anda bisa memanggil {@link +android.app.FragmentManager#executePendingTransactions()} dari thread UI untuk segera +mengeksekusi transaksi yang diserahkan oleh {@link android.app.FragmentTransaction#commit()}. Hal itu +biasanya tidak perlu kecuali jika transaksi merupakan dependensi bagi pekerjaan dalam thread lain.</p> + +<p class="caution"><strong>Perhatian:</strong> Anda bisa mengikat transaksi menggunakan {@link +android.app.FragmentTransaction#commit commit()} hanya sebelum aktivitas <a href="{@docRoot}guide/components/activities.html#SavingActivityState">menyimpan +statusnya</a> (saat pengguna meninggalkan aktivitas). Jika Anda mencoba mengikatnya setelah itu, +eksepsi akan dilontarkan. Ini karena status setelah pengikatan bisa hilang jika aktivitas +perlu dipulihkan. Untuk situasi yang memperbolehkan Anda meniadakan pengikatan (commit), gunakan {@link +android.app.FragmentTransaction#commitAllowingStateLoss()}.</p> + + + + +<h2 id="CommunicatingWithActivity">Berkomunikasi dengan Aktivitas</h2> + +<p>Meskipun {@link android.app.Fragment} diimplementasikan sebagai objek yang tidak bergantung pada +{@link android.app.Activity} dan bisa digunakan dalam banyak aktivitas, instance tertentu +dari fragmen secara langsung terkait dengan aktivitas yang dimuatnya.</p> + +<p>Khususnya, fragmen bisa mengakses instance {@link android.app.Activity} dengan {@link +android.app.Fragment#getActivity()} dan dengan mudah melakukan tugas-tugas seperti mencari tampilan dalam + layout aktivitas:</p> + +<pre> +View listView = {@link android.app.Fragment#getActivity()}.{@link android.app.Activity#findViewById findViewById}(R.id.list); +</pre> + +<p>Demikian pula, aktivitas Anda bisa memanggil metode di fragmen dengan meminta acuan ke +{@link android.app.Fragment} dari {@link android.app.FragmentManager}, menggunakan {@link +android.app.FragmentManager#findFragmentById findFragmentById()} atau {@link +android.app.FragmentManager#findFragmentByTag findFragmentByTag()}. Misalnya:</p> + +<pre> +ExampleFragment fragment = (ExampleFragment) getFragmentManager().findFragmentById(R.id.example_fragment); +</pre> + + +<h3 id="EventCallbacks">Membuat callback kejadian pada aktivitas</h3> + +<p>Dalam beberapa kasus, Anda mungkin perlu fragmen untuk berbagi kejadian dengan aktivitas. Cara yang baik untuk melakukannya +adalah mendefinisikan antarmuka callback di dalam fragmen dan mengharuskan aktivitas host +mengimplementasikannya. Saat aktivitas menerima callback melalui antarmuka, aktivitas akan bisa berbagi informasi itu +dengan fragmen lain dalam layout jika perlu.</p> + +<p>Misalnya, jika sebuah aplikasi berita memiliki dua fragmen dalam aktivitas—satu untuk menampilkan daftar +artikel (fragmen A) dan satu lagi untuk menampilkan artikel (fragmen B)—maka fragmen A harus +memberi tahu aktivitas bila item daftar dipilih sehingga aktivitas bisa memberi tahu fragmen B untuk menampilkan artikel. Dalam +hal ini, antarmuka {@code OnArticleSelectedListener} dideklarasikan di dalam fragmen A:</p> + +<pre> +public static class FragmentA extends ListFragment { + ... + // Container Activity must implement this interface + public interface OnArticleSelectedListener { + public void onArticleSelected(Uri articleUri); + } + ... +} +</pre> + +<p>Selanjutnya aktivitas yang menjadi host fragmen akan mengimplementasikan antarmuka {@code OnArticleSelectedListener} + dan +mengesampingkan {@code onArticleSelected()} untuk memberi tahu fragmen B mengenai kejadian dari fragmen A. Untuk memastikan +bahwa aktivitas host mengimplementasikan antarmuka ini, metode callback fragmen A {@link +android.app.Fragment#onAttach onAttach()} (yang dipanggil sistem saat menambahkan +fragmen ke aktivitas) membuat instance {@code OnArticleSelectedListener} dengan +membuat {@link android.app.Activity} yang diteruskan ke {@link android.app.Fragment#onAttach +onAttach()}:</p> + +<pre> +public static class FragmentA extends ListFragment { + OnArticleSelectedListener mListener; + ... + @Override + public void onAttach(Activity activity) { + super.onAttach(activity); + try { + mListener = (OnArticleSelectedListener) activity; + } catch (ClassCastException e) { + throw new ClassCastException(activity.toString() + " must implement OnArticleSelectedListener"); + } + } + ... +} +</pre> + +<p>Jika aktivitas belum mengimplementasikan antarmuka, maka fragmen akan melontarkan +{@link java.lang.ClassCastException}. +Jika berhasil, anggota {@code mListener} yang menyimpan acuan ke implementasi aktivitas +{@code OnArticleSelectedListener}, sehingga fragmen A bisa berbagi kejadian dengan aktivitas, dengan memanggil metode +yang didefinisikan oleh antarmuka {@code OnArticleSelectedListener}. Misalnya, jika fragmen A adalah +ekstensi dari {@link android.app.ListFragment}, maka setiap kali +pengguna mengklik item daftar, sistem akan memanggil {@link android.app.ListFragment#onListItemClick +onListItemClick()} di fragmen, yang selanjutnya memanggil {@code onArticleSelected()} untuk berbagi +kejadian dengan aktivitas:</p> + +<pre> +public static class FragmentA extends ListFragment { + OnArticleSelectedListener mListener; + ... + @Override + public void onListItemClick(ListView l, View v, int position, long id) { + // Append the clicked item's row ID with the content provider Uri + Uri noteUri = ContentUris.{@link android.content.ContentUris#withAppendedId withAppendedId}(ArticleColumns.CONTENT_URI, id); + // Send the event and Uri to the host activity + mListener.onArticleSelected(noteUri); + } + ... +} +</pre> + +<p>Parameter {@code id} yang diteruskan ke {@link +android.app.ListFragment#onListItemClick onListItemClick()} merupakan ID baris dari item yang diklik, +yang digunakan aktivitas (atau fragmen lain) untuk mengambil artikel dari {@link +android.content.ContentProvider} aplikasi.</p> + +<p><!--To see a complete implementation of this kind of callback interface, see the <a +href="{@docRoot}resources/samples/NotePad/index.html">NotePad sample</a>. -->Informasi selengkapnya tentang +menggunakan penyedia konten tersedia dalam dokumen <a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia Konten</a>.</p> + + + +<h3 id="ActionBar">Menambahkan item ke Action-Bar</h3> + +<p>Fragmen Anda bisa menyumbangkan item menu ke <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Menu Opsi</a> aktivitas (dan, konsekuensinya, <a href="{@docRoot}guide/topics/ui/actionbar.html">Action-Bar</a>) dengan mengimplementasikan +{@link android.app.Fragment#onCreateOptionsMenu(Menu,MenuInflater) onCreateOptionsMenu()}. Agar +metode ini bisa menerima panggilan, Anda harus memanggil {@link +android.app.Fragment#setHasOptionsMenu(boolean) setHasOptionsMenu()} selama {@link +android.app.Fragment#onCreate(Bundle) onCreate()}, untuk menunjukkan bahwa fragmen +ingin menambahkan item ke Menu Opsi (jika tidak, fragmen tidak akan menerima panggilan ke +{@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()}).</p> + +<p>Setiap item yang selanjutnya Anda tambahkan ke Menu Opsi dari fragmen akan ditambahkan ke item menu +yang ada. Fragmen juga menerima callback ke {@link +android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} bila item menu +dipilih.</p> + +<p>Anda juga bisa mendaftarkan tampilan dalam layout fragmen untuk menyediakan menu konteks dengan memanggil {@link +android.app.Fragment#registerForContextMenu(View) registerForContextMenu()}. Bila pengguna +membuka menu konteks, fragmen akan menerima panggilan ke {@link +android.app.Fragment#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) +onCreateContextMenu()}. Bila pengguna memilih item, fragmen akan menerima panggilan ke @link +android.app.Fragment#onContextItemSelected(MenuItem) onContextItemSelected()}.</p> + +<p class="note"><strong>Catatan:</strong> Walaupun fragmen menerima callback pada item yang dipilih +untuk setiap item menu yang ditambahkannya, aktivitaslah yang pertama kali menerima masing-masing callback saat pengguna +memilih item menu. Jika implementasi aktivitas dari callback bila-item-dipilih, +tidak menangani item yang dipilih, maka kejadian akan diteruskan ke callback fragmen. Ini berlaku +untuk Menu Opsi dan menu konteks.</p> + +<p>Untuk informasi selengkapnya tentang menu, lihat panduan pengembang <a href="{@docRoot}guide/topics/ui/menus.html">Menu</a> dan <a href="{@docRoot}guide/topics/ui/actionbar.html">Action-Bar</a>.</p> + + + + +<h2 id="Lifecycle">Menangani Daur Hidup Fragmen</h2> + +<div class="figure" style="width:350px"> +<img src="{@docRoot}images/activity_fragment_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Gambar 3.</strong> Efek daur hidup aktivitas pada daur hidup +fragmen.</p> +</div> + +<p>Mengelola daur hidup fragmen mirip sekali dengan mengelola daur hidup aktivitas. Seperti +aktivitas, fragmen bisa berada dalam tiga status:</p> + +<dl> + <dt><i>Dilanjutkan</i></dt> + <dd>Fragmen terlihat dalam aktivitas yang berjalan.</dd> + + <dt><i>Dihentikan sementara</i></dt> + <dd>Aktivitas lain berada di latar depan dan memiliki fokus, namun aktivitas tempat fragmen berada +masih terlihat (aktivitas latar depan sebagian terlihat atau tidak menutupi +seluruh layar).</dd> + + <dt><i>Dihentikan</i></dt> + <dd>Fragmen tidak terlihat. Aktivitas host telah dihentikan atau +fragmen telah dihapus dari aktivitas namun ditambahkan ke back-stack. Fragmen yang dihentikan +masih hidup (semua status dan informasi anggota masih disimpan oleh sistem). Akan tetapi, fragmen +tidak terlihat lagi oleh pengguna dan akan dimatikan jika aktivitas dimatikan.</dd> +</dl> + +<p>Seperti halnya aktivitas, Anda bisa mempertahankan status fragmen menggunakan {@link +android.os.Bundle}, jika proses aktivitas dimatikan dan Anda harus memulihkan status +fragmen bila aktivitas dibuat kembali. Anda bisa menyimpan status selama callback {@link +android.app.Fragment#onSaveInstanceState onSaveInstanceState()} fragmen dan memulihkannya selama +{@link android.app.Fragment#onCreate onCreate()}, {@link +android.app.Fragment#onCreateView onCreateView()}, atau {@link +android.app.Fragment#onActivityCreated onActivityCreated()}. Untuk informasi selengkapnya tentang menyimpan +status, lihat dokumen <a href="{@docRoot}guide/components/activities.html#SavingActivityState">Aktivitas</a> +.</p> + +<p>Perbedaan paling signifikan dalam daur hidup antara aktivitas dan fragmen ada +pada cara penyimpanannya dalam back-stack masing-masing. Aktivitas ditempatkan ke back-stack aktivitas +yang dikelola oleh sistem saat dihentikan, secara default (sehingga pengguna bisa mengarah kembali +ke aktivitas dengan tombol <em>Back</em>, seperti yang dibahas dalam <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tugas dan Back-Stack</a>). +Akan tetapi, fragmen yang ditempatkan ke back-stack dikelola oleh aktivitas host hanya saat +Anda secara eksplisit meminta agar instance disimpan dengan memanggil {@link +android.app.FragmentTransaction#addToBackStack(String) addToBackStack()} selama transaksi yang +menghapus fragmen.</p> + +<p>Jika tidak, pengelolaan daur hidup fragmen mirip sekali dengan mengelola daur hidup +aktivitas. Jadi, praktik yang sama untuk <a href="{@docRoot}guide/components/activities.html#Lifecycle">mengelola daur hidup +aktivitas</a> juga berlaku untuk fragmen. Namun yang perlu juga Anda pahami adalah bagaimana hidup +aktivitas memengaruhi hidup fragmen.</p> + +<p class="caution"><strong>Perhatian:</strong> Jika Anda memerlukan objek {@link android.content.Context} + dalam {@link android.app.Fragment}, Anda bisa memanggil {@link android.app.Fragment#getActivity()}. +Akan tetapi, berhati-hatilah memanggil {@link android.app.Fragment#getActivity()} hanya bila fragmen +terkait dengan aktivitas. Bila fragmen belum terkait, atau terlepas selama akhir daur +hidupnya, {@link android.app.Fragment#getActivity()} akan kembali nol.</p> + + +<h3 id="CoordinatingWithActivity">Mengoordinasi dengan daur hidup aktivitas</h3> + +<p>Daur hidup aktivitas tempat fragmen berada akan memengaruhi langsung siklus hidup +fragmen sedemikian rupa sehingga setiap callback daur hidup aktivitas menghasilkan callback yang sama untuk masing-masing +fragmen. Misalnya, bila aktivitas menerima {@link android.app.Activity#onPause}, masing-masing +fragmen dalam aktivitas akan menerima {@link android.app.Fragment#onPause}.</p> + +<p>Namun fragmen memiliki beberapa callback daur hidup ekstra, yang menangani interaksi +unik dengan aktivitas untuk melakukan tindakan seperti membangun dan memusnahkan UI fragmen. Metode callback +tambahan ini adalah:</p> + +<dl> + <dt>{@link android.app.Fragment#onAttach onAttach()}</dt> + <dd>Dipanggil bila fragmen telah dikaitkan dengan aktivitas ({@link +android.app.Activity} diteruskan di sini).</dd> + <dt>{@link android.app.Fragment#onCreateView onCreateView()}</dt> + <dd>Dipanggil untuk membuat hierarki tampilan yang dikaitkan dengan fragmen.</dd> + <dt>{@link android.app.Fragment#onActivityCreated onActivityCreated()}</dt> + <dd>Dipanggil bila metode {@link android.app.Activity#onCreate +onCreate()} aktivitas telah dikembalikan.</dd> + <dt>{@link android.app.Fragment#onDestroyView onDestroyView()}</dt> + <dd>Dipanggil bila hierarki tampilan yang terkait dengan fragmen dihapus.</dd> + <dt>{@link android.app.Fragment#onDetach onDetach()}</dt> + <dd>Dipanggil bila fragmen diputuskan dari aktivitas.</dd> +</dl> + +<p>Aliran daur hidup fragmen, karena dipengaruhi oleh aktivitas host-nya, diilustrasikan oleh +gambar 3. Dalam gambar ini, Anda bisa melihat bagaimana setiap status aktivitas menentukan +metode callback mana yang mungkin diterima fragmen. Misalnya, saat aktivitas menerima call back {@link +android.app.Activity#onCreate onCreate()}, fragmen dalam aktivitas akan menerima tidak lebih +dari callback {@link android.app.Fragment#onActivityCreated onActivityCreated()}.</p> + +<p>Setelah status aktivitas diteruskan kembali, Anda bisa bebas menambah dan menghapus fragmen untuk +aktivitas tersebut. Sehingga, hanya saat aktivitas berada dalam status dilanjutkan, daur hidup fragmen bisa +berubah secara independen.</p> + +<p>Akan tetapi, saat aktivitas meninggalkan status dilanjutkan, fragmen akan kembali didorong +melalui daur hidupnya oleh aktivitas.</p> + + + + +<h2 id="Example">Contoh</h2> + +<p>Untuk merangkum semua yang telah dibahas dalam dokumen ini, berikut ini contoh aktivitas +yang menggunakan dua fragmen untuk membuat layout dua panel. Aktivitas di bawah ini menyertakan satu fragmen untuk +menampilkan daftar putar Shakespeare dan fragmen lainnya menampilkan rangkuman pemutaran bila dipilih dari +daftar. Aktivitas ini juga menunjukkan cara menyediakan konfigurasi fragmen berbeda, +berdasarkan konfigurasi layar.</p> + +<p class="note"><strong>Catatan:</strong> Kode sumber lengkap untuk aktivitas ini tersedia di +<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.html">{@code +FragmentLayout.java}</a>.</p> + +<p>Aktivitas utama akan menerapkan layout seperti biasa, selama {@link +android.app.Activity#onCreate onCreate()}:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java main} + +<p>Layout yang diterapkan adalah {@code fragment_layout.xml}:</p> + +{@sample development/samples/ApiDemos/res/layout-land/fragment_layout.xml layout} + +<p>Dengan layout ini, sistem akan membuat instance {@code TitlesFragment} (yang mencantumkan +judul) segera setelah aktivitas memuat layout, sementara {@link android.widget.FrameLayout} + (lokasi penempatan fragmen untuk menampilkan rangkuman pemutaran) menempati ruang di sisi kanan +layar, namun pada awalnya masih kosong. Seperti yang akan Anda lihat di bawah ini, sampai pengguna memilih item +dari daftar maka fragmen baru akan ditempatkan ke dalam {@link android.widget.FrameLayout}.</p> + +<p>Akan tetapi, tidak semua konfigurasi layar cukup lebar untuk menampilkan +daftar putar dan rangkuman secara berdampingan. Sehingga, layout di atas hanya digunakan untuk konfigurasi +layar mendatar, dengan menyimpannya di {@code res/layout-land/fragment_layout.xml}.</p> + +<p>Sehingga, bila layar berada dalam orientasi tegak, sistem akan menerapkan layout berikut, yang +tersimpan di {@code res/layout/fragment_layout.xml}:</p> + +{@sample development/samples/ApiDemos/res/layout/fragment_layout.xml layout} + +<p>Layout ini hanya menyertakan {@code TitlesFragment}. Ini artinya saat perangkat berada dalam +orientasi tegak, hanya judul daftar putar yang terlihat. Jadi, saat pengguna mengklik item +daftar dalam konfigurasi ini, aplikasi akan memulai aktivitas baru untuk menampilkan rangkuman, +sebagai ganti pemuatan fragmen kedua.</p> + +<p>Berikutnya, Anda bisa melihat bagaimana hal ini dilakukan dalam kelas fragmen. Pertama adalah {@code +TitlesFragment}, yang menampilkan judul daftar putar Shakespeare. Fragmen ini membuat ekstensi {@link +android.app.ListFragment} dan mengandalkannya itu untuk menangani sebagian besar pekerjaan tampilan daftar.</p> + +<p>Saat Anda memeriksa kode ini, perhatikan bahwa ada dua kemungkinan perilaku saat pengguna mengklik +item daftar: bergantung pada layout mana yang aktif, bisa membuat dan menampilkan fragmen +baru untuk menampilkan detail dalam aktivitas yang sama (menambahkan fragmen ke {@link +android.widget.FrameLayout}), atau memulai aktivitas baru (tempat fragmen ditampilkan).</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java titles} + +<p>Fragmen kedua, {@code DetailsFragment} menampilkan rangkuman pemutaran untuk item yang dipilih dari +daftar dari {@code TitlesFragment}:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details} + +<p>Ingatlah dari kelas {@code TitlesFragment}, bahwa, jika pengguna mengklik item daftar dan +layout saat ini <em>tidak</em> menyertakan tampilan {@code R.id.details} (yaitu tempat +{@code DetailsFragment} berada), maka aplikasi memulai aktivitas {@code DetailsActivity} +untuk menampilkan konten item.</p> + +<p>Berikut ini adalah {@code DetailsActivity}, yang hanya menanamkan {@code DetailsFragment} untuk menampilkan rangkuman pemutaran +yang dipilih saat layar dalam orientasi tegak:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java +details_activity} + +<p>Perhatikan bahwa aktivitas ini selesai sendiri jika konfigurasi mendatar, sehingga aktivitas utama +bisa mengambil alih dan menampilkan {@code DetailsFragment} bersama {@code TitlesFragment}. +Ini bisa terjadi jika pengguna memulai {@code DetailsActivity} saat dalam orientasi tegak, namun kemudian +memutarnya menjadi mendatar (yang akan memulai lagi aktivitas saat ini).</p> + + +<p>Untuk contoh lainnya mengenai penggunaan fragmen (dan file sumber lengkap untuk contoh ini), +lihat aplikasi contoh Demo API yang tersedia di <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment"> +ApiDemos</a> (bisa diunduh dari <a href="{@docRoot}resources/samples/get.html">Komponen contoh SDK</a>).</p> + + diff --git a/docs/html-intl/intl/in/guide/components/fundamentals.jd b/docs/html-intl/intl/in/guide/components/fundamentals.jd new file mode 100644 index 000000000000..bd9a500f77a5 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/fundamentals.jd @@ -0,0 +1,480 @@ +page.title=Dasar-Dasar Aplikasi +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> +<li><a href="#Components">Komponen Aplikasi</a> + <ol> + <li><a href="#ActivatingComponents">Mengaktifkan komponen</a></li> + </ol> +</li> +<li><a href="#Manifest">File Manifes</a> + <ol> + <li><a href="#DeclaringComponents">Mendeklarasikan komponen</a></li> + <li><a href="#DeclaringRequirements">Mendeklarasikan kebutuhan aplikasi</a></li> + </ol> +</li> +<li><a href="#Resources">Sumber Daya Aplikasi</a></li> +</ol> +</div> +</div> + +<p>Aplikasi Android ditulis dalam bahasa pemrograman Java. Android SDK Tools mengkompilasi +kode Anda—bersama data dan file sumber daya —ke dalam APK: <i>Paket Android</i>, +yaitu file arsip berekstensi {@code .apk}. Satu file APK berisi semua konten +aplikasi Android dan merupakan file yang digunakan perangkat berbasis Android untuk menginstal aplikasi.</p> + +<p>Setelah diinstal di perangkat, setiap aplikasi Android tinggal di sandbox keamanannya sendiri: </p> + +<ul> + <li>Sistem operasi Android merupakan sistem Linux multi-pengguna yang di dalamnya setiap +aplikasi adalah pengguna berbeda.</li> + +<li>Secara default, sistem menetapkan ID pengguna Linux unik kepada setiap aplikasi (ID ini hanya + digunakan oleh sistem dan tidak diketahui aplikasi). Sistem menetapkan izin +bagi semua file dalam aplikasi sehingga hanya ID pengguna yang diizinkan yang bisa mengaksesnya. </li> + +<li>Setiap proses memiliki mesin virtual (VM) sendiri, sehingga kode aplikasi yang berjalan secara terisolasi dari +aplikasi lainnya.</li> + +<li>Secara default, setiap aplikasi berjalan dalam proses Linux-nya sendiri. Android memulai proses +bila ada komponen aplikasi yang perlu dijalankan, kemudian mematikan proses bila tidak lagi diperlukan +atau bila sistem harus memulihkan memori untuk digunakan aplikasi lain.</li> +</ul> + +<p>Dengan cara ini, sistem Android mengimplementasikan <em>prinsip privilese minim</em>. Ini berarti, +secara default aplikasi hanya memiliki akses ke komponen yang diperlukannya untuk melakukan pekerjaannya dan +tidak lebih dari itu. Hal ini menghasilkan lingkungan yang sangat aman sehingga aplikasi tidak bisa mengakses bagian +sistem bila tidak diberi izin.</p> + +<p>Akan tetapi, ada beberapa cara bagi aplikasi untuk berbagi data dengan aplikasi lain dan bagi aplikasi +untuk mengakses layanan sistem:</p> + +<ul> + <li>Dua aplikasi bisa diatur untuk menggunakan ID pengguna Linux yang sama, +dalam hal ini keduanya bisa saling mengakses file masing-masing. Untuk menghemat sumber daya sistem, aplikasi dengan ID +pengguna yang sama juga bisa diatur agar berjalan dalam proses Linux yang sama dan menggunakan VM yang sama ( +aplikasi juga harus ditandatangani dengan sertifikat yang sama).</li> + <li>Aplikasi bisa meminta izin akses ke data perangkat seperti kontak +pengguna, pesan SMS, penyimpanan lepas-pasang (kartu SD), kamera, Bluetooth, dan lainnya. Semua +izin aplikasi harus diberikan oleh pengguna saat menginstal.</li> +</ul> + +<p>Hal tersebut mencakup dasar-dasar tentang cara aplikasi Android berada di dalam sistem. Bagian dokumen +selanjutnya memperkenalkan Anda pada:</p> +<ul> + <li>Komponen kerangka kerja inti yang mendefinisikan aplikasi.</li> + <li>File manifes tempat Anda mendeklarasikan komponen dan fitur yang diperlukan perangkat +untuk aplikasi.</li> + <li>Sumber daya yang terpisah dari kode aplikasi dan memungkinkan +aplikasi mengoptimalkan perilakunya untuk beragam konfigurasi perangkat.</li> +</ul> + + + +<h2 id="Components">Komponen Aplikasi</h2> + +<p>Komponen aplikasi adalah blok pembangun penting dari aplikasi Android. +Setiap komponen merupakan titik berbeda yang digunakan sistem untuk memasuki aplikasi. Tidak semua komponen +merupakan titik masuk sebenarnya bagi pengguna dan sebagian saling bergantung, namun masing-masing komponen tersedia +sebagai kesatuan sendiri dan memainkan peran tertentu—masing-masing merupakan +blok pembangun unik yang mendefinisikan perilaku aplikasi secara keseluruhan.</p> + +<p>Ada empat macam tipe komponen aplikasi. Setiap tipe memiliki kegunaan tersendiri +dan daur hidupnya sendiri yang mendefinisikan cara komponen dibuat dan dimusnahkan.</p> + +<p>Berikut ini empat tipe komponen aplikasi:</p> + +<dl> + +<dt><b>Aktivitas</b></dt> + +<dd>Sebuah <i>aktivitas</i> mewakili satu layar dengan antarmuka pengguna. Misalnya, +aplikasi email mungkin memiliki satu aktivitas yang menampilkan daftar email +baru, aktivitas lain untuk menulis email, dan aktivitas satunya lagi untuk membaca email. Walaupun +semua aktivitas bekerja sama untuk membentuk pengalaman pengguna yang kohesif dalam aplikasi email, +masing-masing tidak saling bergantung. Karenanya, aplikasi berbeda bisa memulai +salah satu aktivitas ini (jika aplikasi email mengizinkannya). Misalnya, aplikasi kamera bisa memulai +aktivitas dalam aplikasi email yang membuat email baru agar pengguna bisa berbagi gambar. + +<p>Aktivitas diimplementasikan sebagai subkelas {@link android.app.Activity} dan Anda bisa mengetahui selengkapnya +tentang hal ini dalam panduan pengembang <a href="{@docRoot}guide/components/activities.html">Aktivitas</a> +.</p> +</dd> + + +<dt><b>Layanan</b></dt> + +<dd>Sebuah <i>layanan</i> adalah komponen yang berjalan di latar belakang untuk melakukan +operasi yang berjalan lama atau untuk melakukan pekerjaan bagi proses jarak jauh. Layanan +tidak menyediakan antarmuka pengguna. Misalnya, sebuah layanan bisa memutar musik di latar belakang sementara +pengguna berada dalam aplikasi lain, atau layanan bisa menarik data lewat jaringan tanpa +memblokir interaksi pengguna dengan aktivitas. Komponen lain, seperti aktivitas, bisa memulai +layanan dan membiarkannya berjalan atau mengikat layanan untuk berinteraksi dengannya. + +<p>Layanan diimplementasikan sebagai subkelas {@link android.app.Service} dan Anda bisa mengetahui selengkapnya +tentang hal ini dalam panduan +pengembang <a href="{@docRoot}guide/components/services.html">Layanan</a>.</p> +</dd> + + +<dt><b>Penyedia konten</b></dt> + +<dd>Sebuah <i>penyedia konten</i> mengelola seperangkat data-bersama aplikasi. Anda bisa menyimpan data +dalam sistem file, database SQLite, di web, atau lokasi penyimpanan permanen lainnya +yang bisa diakses aplikasi. Melalui penyedia konten, aplikasi lain bisa melakukan query atau bahkan +memodifikasi data (jika penyedia konten mengizinkannya). Misalnya, sistem Android menyediakan penyedia +konten yang mengelola informasi kontak pengguna. Karenanya, setiap aplikasi +dengan izin yang sesuai bisa melakukan query mengenai bagian dari penyedia konten (seperti {@link +android.provider.ContactsContract.Data}) untuk membaca dan menulis informasi tentang orang tertentu. + +<p>Penyedia konten juga berguna untuk membaca dan menulis data privat ke aplikasi Anda +dan tidak dibagikan. Misalnya, aplikasi contoh <a href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> menggunakan +penyedia konten untuk menyimpan catatan.</p> + +<p>Penyedia konten diimplementasikan sebagai subkelas {@link android.content.ContentProvider} +dan harus mengimplementasikan seperangkat standar API yang memungkinkan aplikasi +lain melakukan transaksi. Untuk informasi selengkapnya, lihat panduan pengembang +<a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia Konten</a>.</p> +</dd> + + +<dt><b>Penerima siaran</b></dt> + +<dd>Sebuah <i>penerima siaran</i> adalah komponen yang merespons pengumuman siaran dalam lingkup +sistem. Banyak siaran yang berasal dari sistem—misalnya, siaran yang mengumumkan bahwa +layar telah dimatikan, baterai lemah, atau gambar telah direkam. +Aplikasi juga bisa memulai siaran—misalnya untuk menginformasikan ke +aplikasi lain bahwa sebagian data telah diunduh ke perangkat dan bisa digunakan aplikasi lain tersebut. Walaupun penerima +siaran tidak menampilkan antarmuka pengguna, penerima bisa <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">membuat pemberitahuan baris status</a> +untuk memberi tahu pengguna kapan kejadian siaran dilakukan. Meskipun penerima siaran umumnya cuma menjadi +"gerbang" untuk komponen lain dan dimaksudkan untuk melakukan pekerjaan dalam jumlah sangat minim. Misalnya +, penerima siaran bisa menjalankan layanan untuk melakukan beberapa pekerjaan berdasarkan kejadian. + +<p>Penerima siaran diimplementasikan sebagai subkelas {@link android.content.BroadcastReceiver} +dan setiap siaran dikirim sebagai objek {@link android.content.Intent}. Untuk informasi selengkapnya, +lihat kelas {@link android.content.BroadcastReceiver}.</p> +</dd> + +</dl> + + + +<p>Aspek unik dari desain sistem Android adalah aplikasi mana pun bisa memulai +komponen aplikasi lain. Misalnya, jika Anda menginginkan pengguna mengambil +foto dengan kamera perangkat, bisa saja aplikasi lain yang melakukannya dan aplikasi +Anda bisa menggunakannya, sebagai ganti mengembangkan aktivitas sendiri untuk mengambil foto. Anda tidak +harus menyatukan atau bahkan menautkan ke kode dari aplikasi kamera. +Sebagai gantinya, Anda tinggal memulai aktivitas di aplikasi kamera yang akan mengambil +foto. Bila selesai, foto akan dikembalikan ke aplikasi sehingga Anda bisa menggunakannya. Bagi pengguna, +kamera seakan menjadi bagian dari aplikasi Anda.</p> + +<p>Saat sistem memulai komponen, sistem akan memulai proses untuk aplikasi itu (jika +belum berjalan) dan membuat instance kelas yang diperlukan untuk komponen. Misalnya, jika aplikasi Anda +memulai aktivitas dalam aplikasi kamera yang mengambil foto, aktivitas itu akan +berjalan dalam proses yang dimiliki oleh aplikasi kamera, bukan dalam proses aplikasi Anda. +Karenanya, tidak seperti aplikasi di sebagian besar sistem lain, aplikasi Android tidak memiliki titik +masuk tunggal (misalnya tidak ada fungsi {@code main()}).</p> + +<p>Karena sistem menjalankan setiap aplikasi dalam proses terpisah dengan izin file yang +membatasi akses ke aplikasi lain, aplikasi Anda tidak bisa langsung mengaktifkan komponen dari aplikasi lain. Akan tetapi, sistem +Android bisa melakukannya. Jadi, untuk mengaktifkan +komponen dalam aplikasi lain, Anda harus mengirim pesan ke sistem yang menetapkan <em>intent</em> Anda untuk memulai +komponen tertentu. Selanjutnya sistem akan mengaktifkan komponen untuk Anda.</p> + + +<h3 id="ActivatingComponents">Mengaktifkan Komponen</h3> + +<p>Tiga dari empat tipe komponen—aktivitas, layanan, dan +penerima siaran—diaktifkan oleh pesan asinkron yang disebut <em>intent</em>. +Intent saling mengikat setiap komponen saat runtime (Anda bisa menganggapnya +sebagai pembawa pesan yang meminta tindakan dari komponen lain), baik komponen itu milik aplikasi Anda +atau milik aplikasi lain.</p> + +<p>Intent dibuat dengan objek {@link android.content.Intent}, yang mendefinisikan pesan untuk +mengaktifkan komponen tertentu atau komponen <em>tipe</em> komponen tertentu—masing-masing intent +bisa eksplisit atau implisit.</p> + +<p>Untuk aktivitas dan layanan, intent mendefinisikan tindakan yang akan dilakukan (misalnya, untuk "melihat" atau +"mengirim" sesuatu) dan mungkin menetapkan URI data untuk ditindaklanjuti (salah satu hal yang mungkin perlu diketahui +oleh komponen yang akan dimulai). Misalnya, intent mungkin menyampaikan permintaan suatu +aktivitas untuk menampilkan gambar atau membuka halaman web. Dalam beberapa kasus, Anda bisa memulai +aktivitas untuk menerima hasil, dalam hal ini, aktivitas juga akan mengembalikan hasil +dalam {@link android.content.Intent} (misalnya Anda bisa mengeluarkan intent agar +pengguna bisa memilih kontak pribadi dan memintanya dikembalikan kepada Anda—intent yang dikembalikan menyertakan URI yang +menunjuk ke kontak yang dipilih).</p> + +<p>Untuk penerima siaran, intent hanya mendefinisikan +pengumuman yang sedang disiarkan (misalnya, siaran untuk menunjukkan baterai perangkat hampir habis +hanya menyertakan string tindakan yang menunjukkan "baterai hampir habis").</p> + +<p>Tipe komponen lainnya dan penyedia konten, tidak diaktifkan oleh intent. Melainkan +diaktifkan saat ditargetkan oleh permintaan dari {@link android.content.ContentResolver}. Resolver +konten menangani semua transaksi langsung dengan penyedia konten sehingga komponen yang melakukan +transaksi dengan penyedia tidak perlu dan sebagai gantinya memanggil metode pada objek {@link +android.content.ContentResolver}. Ini membuat lapisan abstraksi antara penyedia +konten dan komponen yang meminta informasi (demi keamanan).</p> + +<p>Ada beberapa metode terpisah untuk mengaktifkan masing-masing tipe komponen:</p> +<ul> + <li>Anda bisa memulai aktivitas (atau memberinya pekerjaan baru) dengan +meneruskan {@link android.content.Intent} ke {@link android.content.Context#startActivity +startActivity()} atau {@link android.app.Activity#startActivityForResult startActivityForResult()} +(bila Anda ingin aktivitas mengembalikan hasil).</li> + <li>Anda bisa memulai layanan (atau memberikan instruksi baru ke layanan yang sedang berlangsung) dengan +meneruskan {@link android.content.Intent} ke {@link android.content.Context#startService +startService()}. Atau Anda bisa mengikat ke layanan dengan meneruskan {@link android.content.Intent} ke +{@link android.content.Context#bindService bindService()}.</li> + <li>Anda bisa memulai siaran dengan meneruskan {@link android.content.Intent} ke metode seperti +{@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, {@link +android.content.Context#sendOrderedBroadcast(Intent, String) sendOrderedBroadcast()}, atau {@link +android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</li> + <li>Anda bisa melakukan query ke penyedia konten dengan memanggil {@link +android.content.ContentProvider#query query()} pada {@link android.content.ContentResolver}.</li> +</ul> + +<p>Untuk informasi selengkapnya tentang menggunakan intent, lihat dokumen <a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter + Intent</a>. Informasi selengkapnya tentang mengaktifkan komponen +tertentu juga tersedia dalam dokumen berikut: <a href="{@docRoot}guide/components/activities.html">Aktivitas</a>, <a href="{@docRoot}guide/components/services.html">Layanan</a>, {@link +android.content.BroadcastReceiver} dan <a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia Konten</a>.</p> + + +<h2 id="Manifest">File Manifes</h2> + +<p>Sebelum sistem Android bisa memulai komponen aplikasi, sistem harus mengetahui +keberadaan komponen dengan membaca file {@code AndroidManifest.xml} aplikasi (file +"manifes"). Aplikasi Anda harus mendeklarasikan semua komponennya dalam file ini, yang harus menjadi akar +dari direktori proyek aplikasi.</p> + +<p>Manifes melakukan banyak hal selain mendeklarasikan komponen aplikasi, +seperti:</p> +<ul> + <li>Mengidentifikasi izin pengguna yang diperlukan aplikasi, seperti akses Internet atau +akses-baca ke kontak pengguna.</li> + <li>Mendeklarasikan <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Level</a> + minimum yang diperlukan aplikasi, berdasarkan API yang digunakan aplikasi.</li> + <li>Mendeklarasikan fitur perangkat keras dan perangkat lunak yang diperlukan aplikasi, seperti kamera, +layanan Bluetooth, atau layar multisentuh.</li> + <li>Pustaka API aplikasi perlu ditautkan (selain +API kerangka kerja Android), seperti pustaka +<a href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps.</a></li> + <li>Dan lainnya</li> +</ul> + + +<h3 id="DeclaringComponents">Mendeklarasikan komponen</h3> + +<p>Tugas utama manifes adalah menginformasikan komponen aplikasi pada sistem. Misalnya, +file manifes bisa mendeklarasikan aktivitas sebagai berikut: </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest ... > + <application android:icon="@drawable/app_icon.png" ... > + <activity android:name="com.example.project.ExampleActivity" + android:label="@string/example_label" ... > + </activity> + ... + </application> +</manifest></pre> + +<p>Dalam elemen <code><a +href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +, atribut {@code android:icon} menunjuk ke sumber daya untuk ikon yang mengidentifikasi +aplikasi.</p> + +<p>Dalam elemen <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +atribut {@code android:name} menetapkan nama kelas yang sepenuhnya memenuhi syarat subkelas {@link +android.app.Activity} dan atribut {@code android:label} menetapkan string yang akan +digunakan sebagai label yang terlihat oleh pengguna untuk aktivitas tersebut.</p> + +<p>Anda harus mendeklarasikan semua komponen aplikasi dengan cara ini:</p> +<ul> + <li>Elemen <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> untuk +aktivitas</li> + <li>Elemen <code><a +href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> untuk +layanan</li> + <li>Elemen <code><a +href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> untuk +penerima siaran</li> + <li>Elemen <code><a +href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> untuk +penyedia konten</li> +</ul> + +<p>Aktivitas, layanan, dan penyedia konten yang Anda sertakan dalam kode sumber, namun tidak +dideklarasikan dalam manifes, tidak akan terlihat pada sistem dan, akibatnya, tidak pernah bisa berjalan. Akan tetapi, +penerima siaran +bisa dideklarasikan dalam manifes atau dibuat secara dinamis dalam kode (sebagai objek +{@link android.content.BroadcastReceiver}) dan didaftarkan pada sistem dengan memanggil +{@link android.content.Context#registerReceiver registerReceiver()}.</p> + +<p>Untuk informasi selengkapnya tentang cara menstrukturkan file manifes untuk aplikasi Anda, +lihat dokumentasi <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">File AndroidManifest.xml</a>. </p> + + + +<h3 id="DeclaringComponentCapabilities">Mendeklarasikan kemampuan komponen</h3> + +<p>Seperti telah dibahas di atas, dalam <a href="#ActivatingComponents">Mengaktifkan Komponen</a>, Anda bisa menggunakan +{@link android.content.Intent} untuk memulai aktivitas, layanan, dan penerima siaran. Anda bisa +melakukannya dengan menamai komponen sasaran secara eksplisit (menggunakan nama kelas komponen) dalam intent. Akan tetapi, +kemampuan intent sebenarnya ada pada konsep <em>intent implisit</em>. Intent implisit +cuma menjelaskan tipe tindakan yang akan dilakukan (dan, secara opsional, data tempat Anda ingin +melakukan tindakan) dan memungkinkan sistem untuk menemukan komponen pada perangkat yang bisa melakukan +tindakan tersebut dan memulainya. Jika ada banyak komponen yang bisa melakukan tindakan yang dijelaskan oleh intent, +maka pengguna bisa memilih komponen yang akan digunakan.</p> + +<p>Cara sistem mengidentifikasi komponen yang bisa merespons intent adalah dengan membandingkan +intent yang diterima dengan <i>filter intent</i> yang disediakan dalam file manifes aplikasi lainnya pada +perangkat.</p> + +<p>Bila mendeklarasikan aktivitas dalam manifes aplikasi, secara opsional Anda bisa menyertakan +filter intent yang mendeklarasikan kemampuan aktivitas agar bisa merespons intent dari +aplikasi lain. Anda bisa mendeklarasikan filter intent untuk komponen dengan +menambahkan elemen <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code +<intent-filter>}</a> sebagai anak elemen deklarasi komponen.</p> + +<p>Misalnya, jika Anda telah membangun aplikasi email dengan aktivitas untuk menulis email baru, Anda bisa +mendeklarasikan filter intent untuk merespons intent "kirim" (untuk mengirim email baru) seperti ini:</p> +<pre> +<manifest ... > + ... + <application ... > + <activity android:name="com.example.project.ComposeEmailActivity"> + <intent-filter> + <action android:name="android.intent.action.SEND" /> + <data android:type="*/*" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> + </activity> + </application> +</manifest> +</pre> + +<p>Kemudian, jika aplikasi lain membuat intent dengan tindakan {@link +android.content.Intent#ACTION_SEND} dan meneruskannya ke {@link android.app.Activity#startActivity +startActivity()}, sistem bisa memulai aktivitas Anda agar pengguna bisa menulis draf dan mengirim +email.</p> + +<p>Untuk informasi selengkapnya tentang membuat filter intent, lihat dokumen <a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter Intent</a>. +</p> + + + +<h3 id="DeclaringRequirements">Mendeklarasikan kebutuhan aplikasi</h3> + +<p>Ada berbagai macam perangkat yang didukung oleh Android dan tidak +semuanya menyediakan fitur dan kemampuan yang sama. Agar aplikasi Anda tidak dihapus pada perangkat yang tidak memiliki +fitur yang diperlukan aplikasi, Anda harus jelas mendefinisikan profil mengenai +tipe perangkat yang didukung aplikasi dengan mendeklarasikan kebutuhan perangkat dan perangkat lunak dalam file +manifes. Kebanyakan deklarasi ini hanya bersifat informasi dan sistem tidak +membacanya, namun layanan eksternal seperti Google Play akan membacanya untuk menyediakan +penyaringan bagi pengguna saat mereka mencari aplikasi dari perangkat.</p> + +<p>Misalnya, jika aplikasi memerlukan kamera dan menggunakan API yang disediakan dalam Android 2.1 (<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Level</a> 7) +, Anda harus mendeklarasikannya sebagai kebutuhan dalam file manifes seperti ini:</p> + +<pre> +<manifest ... > + <uses-feature android:name="android.hardware.camera.any" + android:required="true" /> + <uses-sdk android:minSdkVersion="7" android:targetSdkVersion="19" /> + ... +</manifest> +</pre> + +<p>Sekarang, perangkat yang <em>tidak</em> memiliki kamera dan menggunakan +Android versi <em>lebih rendah</em> dari 2.1 tidak bisa menginstal aplikasi Anda dari Google Play.</p> + +<p>Akan tetapi, bisa juga mendeklarasikan bahwa aplikasi Anda menggunakan kamera, namun tidak +<em>mengharuskannya</em>. Dalam hal itu, aplikasi Anda harus mengatur atribut <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#required">{@code required}</a> + ke {@code "false"} dan memeriksa saat runtime apakah +perangkat memiliki kamera dan menonaktifkan setiap fitur kamera yang sesuai.</p> + +<p>Informasi selengkapnya tentang cara mengelola kompatibilitas aplikasi dengan +perangkat yang berbeda disediakan dalam dokumen +<a href="{@docRoot}guide/practices/compatibility.html">Kompatibilitas Perangkat</a>.</p> + + + +<h2 id="Resources">Sumber Daya Aplikasi</h2> + +<p>Aplikasi Android tidak hanya terdiri dari kode—Aplikasi memerlukan sumber daya yang +terpisah dari kode sumber, seperti gambar, file audio, dan apa saja yang berkaitan dengan +presentasi visual dari aplikasi. Misalnya, Anda harus mendefinisikan animasi, menu, gaya, warna, +dan layout antarmuka pengguna aktivitas dengan file XML. Penggunaan sumber daya aplikasi +mempermudah pembaruan berbagai karakteristik aplikasi Anda tanpa memodifikasi kode dan—dengan menyediakan +seperangkat sumber daya alternatif—memungkinkan Anda mengoptimalkan aplikasi untuk berbagai konfigurasi +perangkat berbeda (seperti bahasa dan ukuran layar yang berbeda).</p> + +<p>Untuk setiap sumber daya yang Anda sertakan dalam proyek Android, alat bawaan SDK akan mendefinisikan ID integer +unik, yang bisa Anda gunakan untuk mengacu sumber daya dari kode aplikasi atau dari sumber daya lainnya yang +didefinisikan dalam XML. Misalnya, jika aplikasi berisi file gambar bernama {@code +logo.png} (disimpan dalam direktori {@code res/drawable/}), alat SDK akan menghasilkan ID sumber daya +bernama {@code R.drawable.logo}, yang bisa Anda gunakan untuk mengacu gambar dan memasukkannya dalam +antarmuka pengguna.</p> + +<p>Salah satu aspek paling penting dari penyediaan sumber daya yang terpisah dari +kode sumber adalah kemampuan Anda menyediakan sumber daya alternatif untuk konfigurasi perangkat +yang berbeda. Misalnya, dengan mendefinisikan string UI dalam XML, Anda bisa menerjemahkan string ke dalam +bahasa lain dan menyimpan string itu dalam file terpisah. Kemudian, berdasarkan <em>qualifier</em> +bahasa yang ditambahkan ke nama direktori sumber daya (seperti {@code res/values-fr/} untuk nilai +string Prancis) dan pengaturan bahasa pengguna, sistem Android akan menerapkan string bahasa yang sesuai +untuk UI Anda.</p> + +<p>Android mendukung banyak <em>qualifier</em> berbeda untuk sumber daya alternatif Anda. Qualifier +adalah string pendek yang Anda sertakan dalam nama direktori sumber +daya untuk mendefinisikan konfigurasi perangkat yang harus digunakan sumber daya tersebut. Contoh lainnya, +Anda harus sering membuat layout berbeda untuk aktivitas, bergantung pada +orientasi layar dan ukuran perangkat. Misalnya, saat layar perangkat dalam orientasi +tegak, Anda mungkin ingin layout tombolnya vertikal, tetapi saat layar dalam orientasi +mendatar, tombolnya harus sejajar horizontal. Untuk mengubah layout +sesuai orientasi, Anda bisa mendefinisikan dua layout berbeda dan menerapkan qualifier yang +tepat untuk setiap nama direktori layout. Kemudian, sistem secara otomatis menerapkan +layout yang tepat sesuai dengan orientasi perangkat saat ini.</p> + +<p>Untuk informasi selengkapnya tentang berbagai jenis sumber daya yang bisa disertakan dalam aplikasi dan cara +membuat sumber daya alternatif untuk konfigurasi perangkat berbeda, bacalah <a href="{@docRoot}guide/topics/resources/providing-resources.html">Menyediakan Sumber Daya</a>.</p> + + + +<div class="next-docs"> +<div class="col-6"> + <h2 class="norule">Teruskan membaca tentang:</h2> + <dl> + <dt><a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter Intent</a> + </dt> + <dd>Informasi tentang cara menggunakan API {@link android.content.Intent} untuk + mengaktifkan komponen aplikasi, seperti aktivitas dan layanan, dan cara menyediakan komponen aplikasi + untuk digunakan oleh aplikasi lain.</dd> + <dt><a href="{@docRoot}guide/components/activities.html">Aktivitas</a></dt> + <dd>Informasi tentang cara membuat instance kelas {@link android.app.Activity}, +yang menyediakan layar tersendiri dalam aplikasi bersama antarmuka pengguna.</dd> + <dt><a href="{@docRoot}guide/topics/resources/providing-resources.html">Menyediakan Sumber Daya</a></dt> + <dd>Informasi tentang cara aplikasi Android disusun untuk memisahkan sumber daya aplikasi dari +kode aplikasi, termasuk cara Anda bisa menyediakan sumber daya alternatif untuk +konfigurasi perangkat tertentu. + </dd> + </dl> +</div> +<div class="col-6"> + <h2 class="norule">Anda juga mungkin tertarik dengan:</h2> + <dl> + <dt><a href="{@docRoot}guide/practices/compatibility.html">Kompatibilitas Perangkat</a></dt> + <dd>Informasi tentang cara kerja Android pada berbagai tipe perangkat dan +pengenalan mengenai cara mengoptimalkan aplikasi untuk setiap perangkat atau membatasi ketersediaan aplikasi Anda untuk +perangkat berbeda.</dd> + <dt><a href="{@docRoot}guide/topics/security/permissions.html">Izin Sistem</a></dt> + <dd>Informasi tentang cara Android membatasi akses aplikasi pada API tertentu dengan sistem izin +yang mengharuskan persetujuan pengguna agar aplikasi dapat menggunakan API tersebut.</dd> + </dl> +</div> +</div> + diff --git a/docs/html-intl/intl/in/guide/components/index.jd b/docs/html-intl/intl/in/guide/components/index.jd new file mode 100644 index 000000000000..a8dd5f8820fc --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/index.jd @@ -0,0 +1,57 @@ +page.title=Komponen Aplikasi +page.landing=true +page.landing.intro=Kerangka kerja aplikasi Android memungkinkan Anda membuat aplikasi yang kaya dan inovatif menggunakan seperangkat komponen yang dapat digunakan kembali. Bagian ini menjelaskan cara membangun komponen yang mendefinisikan blok pembangun aplikasi Anda dan cara menghubungkannya bersama menggunakan intent. +page.metaDescription=Kerangka kerja aplikasi Android memungkinkan Anda membuat aplikasi yang kaya dan inovatif menggunakan seperangkat komponen yang dapat digunakan kembali. Bagian ini menjelaskan cara membangun komponen yang mendefinisikan blok pembangun aplikasi Anda dan cara menghubungkannya bersama menggunakan intent. +page.landing.image=images/develop/app_components.png +page.image=images/develop/app_components.png + +@jd:body + +<div class="landing-docs"> + + <div class="col-6"> + <h3>Artikel Blog</h3> + + <a href="http://android-developers.blogspot.com/2012/05/using-dialogfragments.html"> + <h4>Menggunakan DialogFragments</h4> + <p>Dalam posting ini, saya akan menunjukkan cara menggunakan DialogFragments dengan pustaka dukungan v4 (untuk kompatibilitas mundur pada perangkat sebelum Honeycomb) untuk menunjukkan dialog edit sederhana dan mengembalikan hasil ke Aktivitas pemanggil menggunakan antarmuka.</p> + </a> + + <a href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html"> + <h4>Fragmen Untuk Semua</h4> + <p>Hari ini kami telah merilis pustaka statis yang memperlihatkan API Fragment yang sama (serta LoaderManager baru dan beberapa kelas lain) agar aplikasi yang kompatibel dengan Android 1.6 atau yang lebih baru bisa menggunakan fragmen untuk membuat antarmuka pengguna yang kompatibel dengan tablet. </p> + </a> + + <a href="http://android-developers.blogspot.com/2010/07/multithreading-for-performance.html"> + <h4>Multithreading untuk Kinerja</h4> + <p>Praktik yang baik dalam membuat aplikasi yang responsif adalah memastikan thread UI utama Anda +melakukan pekerjaan minimum. Setiap tugas yang berpotensi lama dan dapat membuat aplikasi mogok harus +ditangani di thread berbeda.</p> + </a> + </div> + + <div class="col-6"> + <h3>Pelatihan</h3> + + <a href="http://developer.android.com/training/basics/activity-lifecycle/index.html"> + <h4>Mengelola Daur Hidup Aktivitas</h4> + <p>Bagian ini menjelaskan pentingnya metode callback daur hidup yang diterima setiap instance Aktivitas +dan cara menggunakannya sehingga aktivitas Anda melakukan yang diharapkan pengguna dan tidak menghabiskan sumber daya sistem +saat aktivitas tidak membutuhkannya.</p> + </a> + + <a href="http://developer.android.com/training/basics/fragments/index.html"> + <h4>Membangun UI Dinamis dengan Fragmen</h4> + <p>Bagian ini menunjukkan kepada Anda cara membuat pengalaman pengguna yang dinamis dengan fragmen dan mengoptimalkan +pengalaman pengguna aplikasi Anda dengan berbagai ukuran layar, sekaligus terus mendukung +perangkat yang menjalankan versi sebelumnya, sesudah versi Android 1.6.</p> + </a> + + <a href="http://developer.android.com/training/sharing/index.html"> + <h4>Berbagi Konten</h4> + <p>Bagian ini membahas beberapa cara umum untuk mengirim dan menerima konten antar +aplikasi menggunakan API Intent dan objek ActionProvider.</p> + </a> + </div> + +</div> diff --git a/docs/html-intl/intl/in/guide/components/intents-filters.jd b/docs/html-intl/intl/in/guide/components/intents-filters.jd new file mode 100644 index 000000000000..9b2eb48fd069 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/intents-filters.jd @@ -0,0 +1,901 @@ +page.title=Intent dan Filter Intent +page.tags="IntentFilter" +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#Types">Tipe Intent</a></li> + <li><a href="#Building">Membangun Intent</a> + <ol> + <li><a href="#ExampleExplicit">Contoh intent eksplisit</a></li> + <li><a href="#ExampleSend">Contoh intent implisit</a></li> + <li><a href="#ForceChooser">Memaksakan pemilih aplikasi</a></li> + </ol> + </li> + <li><a href="#Receiving">Menerima Intent Implisit</a> + <ol> + <li><a href="#ExampleFilters">Contoh filter</a></li> + </ol> + </li> + <li><a href="#PendingIntent">Menggunakan Intent Tertunda</a></li> + <li><a href="#Resolution">Resolusi Intent</a> + <ol> + <li><a href="#ActionTest">Pengujian tindakan</a></li> + <li><a href="#CategoryTest">Pengujian kategori</a></li> + <li><a href="#DataTest">Pengujian data</a></li> + <li><a href="#imatch">Pencocokan intent</a></li> + </ol> + </li> +</ol> + +<h2>Lihat juga</h2> +<ol> +<li><a href="{@docRoot}training/basics/intents/index.html">Berinteraksi dengan Aplikasi Lain</a></li> +<li><a href="{@docRoot}training/sharing/index.html">Berbagi Konten</a></li> +</ol> + +</div> +</div> + + + + +<p>{@link android.content.Intent} merupakan objek pertukaran pesan yang bisa Anda gunakan untuk meminta tindakan +dari <a href="{@docRoot}guide/components/fundamentals.html#Components">komponen aplikasi</a> lain. +Walaupun intent memudahkan komunikasi antarkomponen dalam beberapa cara, ada tiga +kasus-penggunaan dasar:</p> + +<ul> +<li><b>Untuk memulai aktivitas:</b> +<p>{@link android.app.Activity} menyatakan satu layar dalam aplikasi. Anda bisa memulai instance +baru {@link android.app.Activity} dengan meneruskan {@link android.content.Intent} +ke {@link android.content.Context#startActivity startActivity()}. {@link android.content.Intent} +menjelaskan aktivitas yang akan dimulai dan membawa data yang diperlukan.</p> + +<p>Jika Anda ingin menerima hasil dari aktivitas bila selesai, +panggil {@link android.app.Activity#startActivityForResult +startActivityForResult()}. Aktivitas Anda menerima hasil +sebagai objek {@link android.content.Intent} terpisah dalam callback {@link +android.app.Activity#onActivityResult onActivityResult()} aktivitas Anda. +Untuk informasi selengkapnya, lihat panduan <a href="{@docRoot}guide/components/activities.html">Aktivitas</a>.</p></li> + +<li><b>Untuk memulai layanan:</b> +<p>{@link android.app.Service} adalah komponen yang melakukan operasi di latar belakang +tanpa antarmuka pengguna. Anda bisa memulai layanan untuk melakukan operasi satu-kali +(misalnya mengunduh file) dengan meneruskan {@link android.content.Intent} +ke {@link android.content.Context#startService startService()}. {@link android.content.Intent} +menjelaskan layanan yang akan dimulai dan membawa data yang diperlukan.</p> + +<p>Jika layanan didesain dengan antarmuka pengguna klien-server, Anda bisa mengikat ke layanan +dari komponen lain dengan meneruskan {@link android.content.Intent} ke {@link +android.content.Context#bindService bindService()}</code>. Untuk informasi selengkapnya, lihat panduan <a href="{@docRoot}guide/components/services.html">Layanan</a>.</p></li> + +<li><b>Untuk mengirim siaran:</b> +<p>Siaran adalah pesan yang bisa diterima aplikasi apa saja. Sistem menyampaikan beragam siaran +untuk kejadian sistem, misalnya saat sistem booting atau saat perangkat mulai mengisi daya. +Anda bisa mengirim siaran ke aplikasi lain dengan meneruskan {@link android.content.Intent} +ke {@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, +{@link android.content.Context#sendOrderedBroadcast(Intent, String) +sendOrderedBroadcast()}, atau {@link +android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</p> +</li> +</ul> + + + + +<h2 id="Types">Tipe Intent</h2> + +<p>Ada dua tipe intent:</p> + +<ul> +<li><b>Intent eksplisit</b> menetapkan komponen untuk memulai dengan nama ( +nama kelas yang sepenuhnya memenuhi syarat). Anda biasanya akan menggunakan intent eksplisit untuk memulai sebuah komponen +dalam aplikasi sendiri, karena Anda mengetahui nama kelas dari aktivitas atau layanan yang ingin dimulai. +Misalnya, mulai aktivitas baru sebagai respons terhadap tindakan pengguna atau mulai layanan untuk mengunduh +file di latar belakang.</li> + +<li><b>Intent implisit</b> tidak menetapkan komponen tertentu, melainkan mendeklarasikan tindakan umum +yang dilakukan, yang memungkinkan komponen aplikasi lain untuk menanganinya. Misalnya, jika Anda ingin +menampilkan sebuah lokasi di peta pada pengguna, Anda bisa menggunakan intent implisit untuk meminta aplikasi lain +yang mampu untuk menunjukkan lokasi yang telah ditetapkan di peta tersebut.</li> +</ul> + +<p>Saat Anda membuat intent eksplisit untuk memulai aktivitas atau layanan, sistem akan segera +memulai komponen aplikasi yang telah ditetapkan dalam objek {@link android.content.Intent}.</p> + +<div class="figure" style="width:446px"> +<img src="{@docRoot}images/components/intent-filters@2x.png" width="446" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Ilustrasi yang menggambarkan cara intent implisit +disampaikan melalui sistem untuk memulai aktivitas lain: <b>[1]</b> <em>Aktivitas A</em> membuat sebuah +{@link android.content.Intent} dengan keterangan tindakan dan meneruskannya ke {@link +android.content.Context#startActivity startActivity()}. <b>[2]</b> Sistem Android akan mencari semua +aplikasi untuk filter intent yang cocok dengan intent tersebut. Bila cocok, <b>[3]</b> sistem akan +memulai aktivitas mencocokkan (<em>Aktivitas B</em>) dengan memanggil metode {@link +android.app.Activity#onCreate onCreate()} dan meneruskannya ke {@link android.content.Intent}. +</p> +</div> + +<p>Bila Anda membuat intent implisit, sistem Android akan menemukan komponen yang sesuai untuk memulai +dengan membandingkan konten intent dengan <em>filter intent</em> yang dideklarasikan dalam <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">file manifes</a> aplikasi lain di +perangkat. Jika intent cocok dengan filter intent, sistem akan memulai komponen tersebut dan mengiriminya +objek {@link android.content.Intent}. Jika banyak filter intent yang kompatibel, sistem +menampilkan dialog sehingga pengguna bisa memilih aplikasi yang akan digunakan.</p> + +<p>Filter intent adalah ekspresi dalam file manifes aplikasi yang +menetapkan tipe intent yang akan diterima +komponen. Misalnya, dengan mendeklarasikan intent filter untuk aktivitas, +Anda akan memungkinkan aplikasi lain untuk langsung memulai aktivitas Anda dengan intent tertentu. +Demikian pula, jika Anda <em>tidak</em> mendeklarasikan filter intent untuk suatu aktivitas, maka aktivitas tersebut hanya bisa dimulai +dengan intent eksplisit.</p> + +<p class="caution"><strong>Perhatian:</strong> Untuk memastikan aplikasi Anda aman, selalu gunakan intent +eksplisit saat memulai {@link android.app.Service} dan jangan +mendeklarasikan filter intent untuk layanan. Menggunakan intent implisit untuk memulai layanan akan menimbulkan +bahaya keamanan karena Anda tidak bisa memastikan layanan apa yang akan merespons intent, +dan pengguna tidak bisa melihat layanan mana yang dimulai. Mulai dari Android 5.0 (API level 21), sistem +melontarkan eksepsi jika Anda memanggil {@link android.content.Context#bindService bindService()} +dengan intent implisit.</p> + + + + + +<h2 id="Building">Membangun Intent</h2> + +<p>Objek {@link android.content.Intent} membawa informasi yang digunakan sistem Android +untuk menentukan komponen mana yang akan dimulai (misalnya nama persis dari suatu komponen atau kategori +komponen yang seharusnya menerima intent), ditambah informasi yang digunakan komponen penerima untuk +melakukan tindakan dengan benar (misalnya tindakan yang harus dilakukan dan data yang harus diolah).</p> + + +<p>Informasi utama yang dimuat dalam {@link android.content.Intent} adalah sebagai berikut:</p> + +<dl> + +<dt><b>Nama komponen</b></dt> +<dd>Nama komponen yang akan dimulai. + +<p>Ini opsional, namun merupakan bagian informasi penting yang membuat intent +menjadi <b>eksplisit</b>, yaitu intent harus dikirim hanya ke komponen aplikasi +yang didefinisikan oleh nama komponen. Tanpa nama komponen, intent menjadi <b>implisit</b> dan +sistem akan memutuskan komponen mana yang harus menerima intent berdasarkan informasi intent lain +(misalnya tindakan, data, dan kategori—yang dijelaskan di bawah ini). Jadi jika Anda ingin memulai komponen +tertentu dalam aplikasi, Anda harus menetapkan nama komponen tersebut.</p> + +<p class="note"><strong>Catatan:</strong> Saat memulai {@link android.app.Service}, Anda harus +<strong>selalu menetapkan nama komponen</strong>. Jika tidak, maka Anda tidak bisa memastikan layanan apa +yang akan merespons intent tersebut, dan pengguna tidak bisa melihat layanan mana yang dimulai.</p> + +<p>Bidang {@link android.content.Intent} ini adalah objek +{@link android.content.ComponentName}, yang bisa Anda tetapkan menggunakan +nama kelas yang sepenuhnya memenuhi syarat dari komponen target, termasuk nama paket aplikasi. Misalnya, +{@code com.example.ExampleActivity}. Anda bisa mengatur nama komponen dengan {@link +android.content.Intent#setComponent setComponent()}, {@link android.content.Intent#setClass +setClass()}, {@link android.content.Intent#setClassName(String, String) setClassName()}, atau dengan konstruktor +{@link android.content.Intent}.</p> + +</dd> + +<p><dt><b>Tindakan</b></dt> +<dd>String yang menetapkan tindakan generik untuk dilakukan (misalnya <em>lihat</em> atau <em>pilih</em>). + +<p>Dalam hal intent siaran, ini adalah tindakan yang terjadi dan dilaporkan. +Tindakan ini sangat menentukan bagaimana keseluruhan intent disusun—terutama +apa yang dimuat dalam data dan ekstra. + +<p>Anda bisa menetapkan tindakan sendiri yang akan digunakan oleh intent dalam aplikasi Anda (atau digunakan oleh aplikasi +lain untuk memanggil komponen dalam aplikasi Anda), namun Anda harus menggunakan konstanta tindakan +yang didefinisikan oleh kelas {@link android.content.Intent} atau kelas kerangka kerja lain. Berikut ini adalah beberapa +tindakan umum untuk memulai sebuah aktivitas:</p> + +<dl> +<dt>{@link android.content.Intent#ACTION_VIEW}</dt> + <dd>Gunakan tindakan ini dalam intent dengan {@link + android.content.Context#startActivity startActivity()} saat Anda memiliki beberapa informasi yang + bisa ditampilkan aktivitas kepada pengguna, misalnya foto yang bisa dilihat dalam aplikasi galeri, atau alamat + yang bisa dilihat dalam aplikasi peta.</dd> + +<dt>{@link android.content.Intent#ACTION_SEND}</dt> + <dd>Juga dikenal dengan intent "berbagi", Anda harus menggunakannya dalam intent dengan {@link + android.content.Context#startActivity startActivity()} bila Anda memiliki data yang bisa digunakan pengguna untuk + berbagi melalui aplikasi lain, misalnya aplikasi email atau aplikasi jaringan sosial.</dd> +</dl> + +<p>Lihat referensi kelas {@link android.content.Intent} untuk konstanta +selengkapnya yang mendefinisikan tindakan generik. Tindakan lain yang didefinisikan +di tempat lain dalam kerangka kerja Android, misalnya dalam {@link android.provider.Settings} untuk tindakan +yang membuka layar tertentu dalam aplikasi Settings di sistem.</p> + +<p>Anda bisa menetapkan tindakan untuk sebuah intent dengan {@link android.content.Intent#setAction +setAction()} atau dengan konstruktor {@link android.content.Intent}.</p> + +<p>Jika mendefinisikan tindakan Anda sendiri, pastikan untuk memasukkan nama paket aplikasi Anda +sebagai awalan. Misalnya:</p> +<pre>static final String ACTION_TIMETRAVEL = "com.example.action.TIMETRAVEL";</pre> +</dd> + +<dt><b>Data</b></dt> +<dd>URI (objek {@link android.net.Uri}) yang mengacu data untuk diolah dan/atau +tipe MIME dari data tersebut. Tipe data yang disediakan umumnya didikte oleh tindakan intent. +Misalnya, jika tindakan merupakan {@link android.content.Intent#ACTION_EDIT}, data harus berisi +URI dari dokumen untuk diedit. + +<p>Saat membuat intent, +seringkali tipe data (tipe MIME-nya) selain URI perlu ditetapkan. +Misalnya, aktivitas yang mampu menampilkan gambar mungkin tidak mampu +memutar file audio, walaupun format URI mungkin serupa. +Jadi menetapkan tipe MIME data Anda akan membantu sistem +Android menemukan komponen terbaik untuk diterima intent. +Akan tetapi, tipe MIME seringkali bisa diambil dari URI—terutama saat datanya merupakan URI +{@code content:}, yang menunjukkan data tersebut berada di perangkat dan dikontrol oleh +{@link android.content.ContentProvider}, yang membuat data tipe MIME terlihat di sistem.</p> + +<p>Untuk mengatur data URI saja, panggil {@link android.content.Intent#setData setData()}. +Untuk mengatur tipe MIME saja, panggil {@link android.content.Intent#setType setType()}. Jika perlu, Anda +bisa mengatur keduanya secara eksplisit dengan {@link +android.content.Intent#setDataAndType setDataAndType()}.</p> + +<p class="caution"><strong>Perhatian:</strong> Jika ingin mengatur tipe URI dan MIME, +<strong>jangan</strong> panggil {@link android.content.Intent#setData setData()} dan +{@link android.content.Intent#setType setType()} karena mereka saling menghapuskan nilai satu sama lain. +Selalu gunakan {@link android.content.Intent#setDataAndType setDataAndType()} untuk mengatur +tipe URI maupun MIME.</p> +</dd> + +<p><dt><b>Kategori</b></dt> +<dd>String yang berisi informasi tambahan tentang jenis komponen +yang harus menangani intent. Keterangan kategori dalam jumlah berapa pun bisa +dimasukkan dalam intent, namun sebagian besar intent tidak memerlukan kategori. +Berikut ini adalah beberapa kategori umum: + +<dl> +<dt>{@link android.content.Intent#CATEGORY_BROWSABLE}</dt> + <dd>Aktivitas target memungkinkannya dimulai oleh browser web untuk menampilkan data +yang diacu oleh tautan—misalnya gambar atau pesan e-mail. + </dd> +<dt>{@link android.content.Intent#CATEGORY_LAUNCHER}</dt> + <dd>Aktivitas tersebut adalah aktivitas awal dari sebuah tugas dan dicantumkan dalam + launcher aplikasi sistem. + </dd> +</dl> + +<p>Lihat keterangan kelas {@link android.content.Intent} untuk mengetahui daftar lengkap +kategori.</p> + +<p>Anda bisa menetapkan kategori dengan {@link android.content.Intent#addCategory addCategory()}.</p> +</dd> +</dl> + + +<p>Properti yang tercantum di atas (nama komponen, tindakan, data, dan kategori) menyatakan +karakteristik yang mendefinisikan intent. Dengan membaca properti ini, sistem Android +mampu memutuskan komponen aplikasi yang harus dimulainya.</p> + +<p>Akan tetapi, intent bisa membawa informasi tambahan yang tidak memengaruhi +cara intent ditetapkan pada komponen aplikasi. Intent juga bisa menyediakan:</p> + +<dl> +<dt><b>Ekstra</b></dt> +<dd>Pasangan nilai-kunci yang membawa informasi yang diperlukan untuk menghasilkan tindakan yang diminta. +Seperti halnya beberapa tindakan menggunakan jenis tertentu URI data, beberapa tindakan juga menggunakan ekstra tertentu. + +<p>Anda bisa menambahkan data ekstra dengan beragam metode {@link android.content.Intent#putExtra putExtra()}, +masing-masing menerima dua parameter: nama kunci dan nilainya. +Anda juga bisa membuat objek {@link android.os.Bundle} dengan semua data ekstra, kemudian memasukkan +{@link android.os.Bundle} dalam {@link android.content.Intent} dengan {@link +android.content.Intent#putExtras putExtras()}.</p> + +<p>Misalnya, saat membuat intent yang akan dikirimkan bersama email +{@link android.content.Intent#ACTION_SEND}, Anda bisa menetapkan penerima "kepada" dengan kunci +{@link android.content.Intent#EXTRA_EMAIL}, dan menetapkan "subjek" dengan kunci +{@link android.content.Intent#EXTRA_SUBJECT}.</p> + +<p>Kelas {@link android.content.Intent} menetapkan beberapa konstanta {@code EXTRA_*} +untuk tipe data standar. Jika Anda ingin mendeklarasikan kunci ekstra sendiri (untuk intent yang +diterima aplikasi Anda), pastikan untuk memasukkan nama paket aplikasi +sebagai awalan. Misalnya:</p> +<pre>static final String EXTRA_GIGAWATTS = "com.example.EXTRA_GIGAWATTS";</pre> +</dd> + +<dt><b>Flag</b></dt> +<dd>Flag didefinisikan dalam kelas {@link android.content.Intent} yang berfungsi sebagai metadata untuk +intent. Flag menginstruksikan cara meluncurkan aktivitas (misalnya, +<a href="{@docRoot}guide/components/tasks-and-back-stack.html">tugas</a> mana yang harus dimiliki suatu aktivitas +) dan cara memperlakukannya setelah diluncurkan (misalnya, apakah aktivitas tersebut masuk ke dalam daftar aktivitas +terbaru) pada sistem Android. + +<p>Untuk informasi selengkapnya, lihat metode {@link android.content.Intent#setFlags setFlags()} .</p> +</dd> + +</dl> + + + + +<h3 id="ExampleExplicit">Contoh intent eksplisit</h3> + +<p>Intent eksplisit adalah intent yang Anda gunakan untuk meluncurkan komponen aplikasi tertentu, seperti +aktivitas tertentu atau layanan dalam aplikasi Anda. Untuk membuat intent eksplisit, definisikan +nama komponen untuk objek {@link android.content.Intent} —semua +properti intent lain bersifat opsional.</p> + +<p>Misalnya, jika Anda ingin membangun layanan dalam aplikasi Anda, bernama {@code DownloadService}, +yang didesain untuk mengunduh file dari web, Anda bisa memulainya dengan kode berikut ini:</p> + +<pre> +// Executed in an Activity, so 'this' is the {@link android.content.Context} +// The fileUrl is a string URL, such as "http://www.example.com/image.png" +Intent downloadIntent = new Intent(this, DownloadService.class); +downloadIntent.setData({@link android.net.Uri#parse Uri.parse}(fileUrl)); +startService(downloadIntent); +</pre> + +<p>Konstruktor {@link android.content.Intent#Intent(Context,Class)} + menyediakan {@link android.content.Context} aplikasi dan +objek {@link java.lang.Class} pada komponen. Dengan demikian, +intent ini memulai secara eksplisit kelas {@code DownloadService} dalam aplikasi.</p> + +<p>Untuk informasi selengkapnya tentang membangun dan memulai layanan, lihat panduan +<a href="{@docRoot}guide/components/services.html">Layanan</a>.</p> + + + + +<h3 id="ExampleSend">Contoh intent implisit</h3> + +<p>Intent implisit menetapkan tindakan yang bisa memanggil aplikasi pada perangkat yang mampu +melakukan tindakan. Menggunakan intent implisit berguna bila aplikasi Anda tidak bisa melakukan +tindakan, namun aplikasi lain mungkin bisa melakukannya dan Anda ingin pengguna untuk memilih aplikasi mana yang ingin digunakan.</p> + +<p>Misalnya, jika memiliki konten yang Anda ingin agar pengguna berbagi konten itu dengan orang lain, buatlah intent +dengan tindakan {@link android.content.Intent#ACTION_SEND} +dan tambahkan ekstra yang menetapkan konten yang akan dibagikan. Bila Anda memanggil +{@link android.content.Context#startActivity startActivity()} dengan intent tersebut, pengguna bisa +memilih aplikasi yang akan digunakan untuk berbagi konten.</p> + +<p class="caution"><strong>Perhatian:</strong> Ada kemungkinan pengguna tidak memiliki <em>suatu</em> +aplikasi yang menangani intent implisit yang Anda kirimkan ke {@link android.content.Context#startActivity +startActivity()}. Jika itu terjadi, panggilan akan gagal dan aplikasi Anda akan crash. Untuk memeriksa +apakah aktivitas bisa menerima intent, panggil {@link android.content.Intent#resolveActivity +resolveActivity()} pada objek {@link android.content.Intent} Anda. Jika hasilnya bukan nol, +berarti setidaknya ada satu aplikasi yang bisa menangani intent tersebut dan aman untuk memanggil +{@link android.content.Context#startActivity startActivity()}. Jika hasilnya nol, +Anda tidak boleh menggunakan intent tersebut dan, jika memungkinkan, Anda harus menonaktifkan fitur yang mengeluarkan +intent tersebut.</p> + + +<pre> +// Create the text message with a string +Intent sendIntent = new Intent(); +sendIntent.setAction(Intent.ACTION_SEND); +sendIntent.putExtra(Intent.EXTRA_TEXT, textMessage); +sendIntent.setType({@link + org.apache.http.protocol.HTTP#PLAIN_TEXT_TYPE + HTTP.PLAIN_TEXT_TYPE}); // "text/plain" MIME type + +// Verify that the intent will resolve to an activity +if (sendIntent.resolveActivity(getPackageManager()) != null) { + startActivity(sendIntent); +} +</pre> + +<p class="note"><strong>Catatan:</strong> Dalam hal ini, URI tidak digunakan, namun tipe data intent +dideklarasikan untuk menetapkan konten yang dibawa oleh ekstra.</p> + + +<p>Saat {@link android.content.Context#startActivity startActivity()} dipanggil, sistem akan +memeriksa semua aplikasi yang terinstal untuk menentukan aplikasi mana yang bisa menangani intent jenis ini ( +intent dengan tindakan {@link android.content.Intent#ACTION_SEND} dan yang membawa data +"teks/polos"). Jika hanya ada satu aplikasi yang bisa menanganinya, aplikasi tersebut akan langsung terbuka dan diberi +intent tersebut. Jika banyak aktivitas menerima intent, sistem akan +menampilkan dialog sehingga pengguna bisa memilih aplikasi mana yang digunakan.</p> + + +<div class="figure" style="width:200px"> + <img src="{@docRoot}images/training/basics/intent-chooser.png" alt=""> + <p class="img-caption"><strong>Gambar 2.</strong> Dialog pemilih.</p> +</div> + +<h3 id="ForceChooser">Memaksakan pemilih aplikasi</h3> + +<p>Bila ada lebih dari satu aplikasi yang merespons intent implisit Anda, +pengguna bisa memilih aplikasi mana yang digunakan dan membuat aplikasi tersebut pilihan default untuk +tindakan tersebut. Ini sangat membantu saat melakukan tindakan di mana pengguna +mungkin ingin menggunakan aplikasi yang sama untuk seterusnya, seperti saat membuka halaman web (pengguna +biasanya memilih hanya satu browser web).</p> + +<p>Akan tetapi, jika ada banyak aplikasi yang bisa merespons intent tersebut dan pengguna mungkin ingin menggunakan aplikasi +yang berbeda untuk setiap kalinya, Anda harus menampilkan dialog pemilih secara eksplisit. Dialog pemilih akan meminta +pengguna memilih aplikasi yang akan digunakan untuk tindakan tertentu setiap kali (pengguna tidak bisa memilih aplikasi default untuk +tindakan tersebut). Misalnya, saat aplikasi Anda melakukan "berbagi" dengan tindakan {@link +android.content.Intent#ACTION_SEND}, pengguna mungkin ingin berbagi menggunakan aplikasi berbeda sesuai +dengan situasi mereka saat itu, jadi Anda harus selalu menggunakan dialog pemilih, seperti yang ditampilkan dalam gambar 2.</p> + + + + +<p>Untuk menampilkan pemilih, buatlah {@link android.content.Intent} menggunakan {@link +android.content.Intent#createChooser createChooser()} dan teruskan ke {@link +android.app.Activity#startActivity startActivity()}. Misalnya:</p> + +<pre> +Intent sendIntent = new Intent(Intent.ACTION_SEND); +... + +// Always use string resources for UI text. +// This says something like "Share this photo with" +String title = getResources().getString(R.string.chooser_title); +// Create intent to show the chooser dialog +Intent chooser = Intent.createChooser(sendIntent, title); + +// Verify the original intent will resolve to at least one activity +if (sendIntent.resolveActivity(getPackageManager()) != null) { + startActivity(chooser); +} +</pre> + +<p>Ini menampilkan dialog dengan daftar aplikasi yang merespons intent yang diteruskan ke metode {@link +android.content.Intent#createChooser createChooser()} dan menggunakan teks yang disediakan sebagai +judul dialog.</p> + + + + + + + + + +<h2 id="Receiving">Menerima Intent Implisit</h2> + +<p>Untuk mengiklankan intent implisit yang bisa diterima aplikasi Anda, deklarasikan satu atau beberapa filter intent untuk +tiap komponen aplikasi dengan elemen <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> +dalam <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">file manifes</a> Anda. +Tiap filter intent menetapkan tipe intent yang diterimanya berdasarkan tindakan intent, +data, dan kategori. Sistem akan mengirim intent implisit ke komponen aplikasi Anda hanya jika +intent tersebut bisa diteruskan melalui salah satu filter intent.</p> + +<p class="note"><strong>Catatan:</strong> Intent eksplisit selalu dikirimkan ke targetnya, +apa pun filter intent yang dideklarasikan komponen.</p> + +<p>Komponen aplikasi harus mendeklarasikan filter terpisah untuk setiap pekerjaan unik yang bisa dilakukannya. +Misalnya, satu aktivitas dalam aplikasi galeri gambar bisa memiliki dua filter: satu filter +untuk melihat gambar, dan filter lainnya untuk mengedit gambar. Bila aktivitas dimulai, +aktivitas akan memeriksa {@link android.content.Intent} dan menentukan cara berperilaku berdasarkan informasi +dalam {@link android.content.Intent} (misalnya menampilkan kontrol editor atau tidak).</p> + +<p>Tiap filter intent didefinisikan oleh elemen <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a> +dalam file manifes aplikasi, yang tersarang dalam komponen aplikasi terkait (seperti +elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +). Di dalam <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code <intent-filter>}</a>, +Anda bisa menetapkan tipe intent yang akan diterima dengan menggunakan salah satu atau beberapa +dari tiga elemen ini:</p> + +<dl> +<dt><a href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a></dt> + <dd>Mendeklarasikan tindakan intent yang diterima, dalam atribut {@code name}. Nilai + haruslah nilai string literal dari tindakan, bukan konstanta kelas.</dd> +<dt><a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a></dt> + <dd>Mendeklarasikan tipe data yang diterima, menggunakan salah satu atau beberapa atribut yang menetapkan beragam + aspek URI data (<code>scheme</code>, <code>host</code>, <code>port</code>, + <code>path</code>, dll.) dan tipe MIME.</dd> +<dt><a href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a></dt> + <dd>Mendeklarasikan kategori intent yang diterima, dalam atribut {@code name}. Nilai + haruslah nilai string literal dari tindakan, bukan konstanta kelas. + + <p class="note"><strong>Catatan:</strong> Untuk menerima intent implisit, Anda + <strong>harus menyertakan</strong> kategori +{@link android.content.Intent#CATEGORY_DEFAULT} dalam filter intent. Metode + {@link android.app.Activity#startActivity startActivity()}dan + {@link android.app.Activity#startActivityForResult startActivityForResult()} memperlakukan semua intent + seolah-olah mendeklarasikan kategori {@link android.content.Intent#CATEGORY_DEFAULT}. + Jika tidak mendeklarasikan kategori ini dalam filter intent Anda, tidak ada intent implisit yang ditetapkan untuk + aktivitas Anda.</p> + </dd> +</dl> + +<p>Misalnya, ini adalah deklarasi aktivitas dengan filter intent yang diterima intent +{@link android.content.Intent#ACTION_SEND} bila tipe data berupa teks:</p> + +<pre> +<activity android:name="ShareActivity"> + <intent-filter> + <action android:name="android.intent.action.SEND"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:mimeType="text/plain"/> + </intent-filter> +</activity> +</pre> + +<p>Anda bisa membuat filter yang menyertakan lebih dari satu instance +<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code <action>}</a>, +<a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a>, atau +<a href="{@docRoot}guide/topics/manifest/category-element.html">{@code <category>}</a>. +Jika Anda melakukannya, Anda hanya perlu memastikan bahwa komponen bisa menangani semua kombinasi +elemen filter tersebut.</p> + +<p>Bila ingin menangani beragam jenis intent, namun hanya dalam kombinasi +tindakan, data, dan tipe kategori tertentu, maka Anda harus membuat banyak filter intent.</p> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Membatasi akses ke komponen</h2> +<p>Menggunakan filter intent bukanlah cara yang aman untuk mencegah aplikasi lain memulai +komponen Anda. Walaupun filter intent membatasi komponen agar hanya merespons +jenis intent implisit tertentu, aplikasi lain bisa saja memulai komponen aplikasi Anda +dengan menggunakan intent eksplisit jika pengembangnya menentukan nama komponen Anda. +Jika perlu <em>hanya aplikasi Anda sendiri</em> yang mampu memulai salah satu komponen, +atur atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#exported">{@code +exported}</a> ke {@code "false"} untuk komponen itu. +</p> +</div> +</div> + +<p>Intent implisit diuji terhadap filter dengan membandingkan intent dengan masing-masing +dari ketiga elemen. Agar dikirim ke komponen, intent harus lolos ketiga pengujian tersebut. +Jika intent gagal dalam salah satu pengujian, sistem Android tidak akan mengirim intent ke +komponen. Akan tetapi, karena sebuah komponen dapat memiliki beberapa filter intent, intent yang tidak +lolos melalui salah satu filter komponen mungkin akan lolos di filter lain. +Informasi selengkapnya tentang cara sistem menetapkan intent disediakan dalam bagian di bawah ini +tentang <a href="#Resolution">Resolusi Intent</a>.</p> + +<p class="caution"><strong>Perhatian:</strong> Untuk menghindari menjalankan +{@link android.app.Service} aplikasi yang berbeda secara tidak sengaja, selalu gunakan intent eksplisit untuk memulai layanan Anda sendiri dan jangan +deklarasikan filter intent untuk layanan Anda.</p> + +<p class="note"><strong>Catatan:</strong> +Untuk semua aktivitas, Anda harus mendeklarasikan filter intent dalam file manifes. +Akan tetapi, filter untuk penerima siaran bisa didaftarkan secara dinamis dengan memanggil +{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, +Handler) registerReceiver()}. Anda nanti bisa mencabut pendaftaran penerima dengan {@link +android.content.Context#unregisterReceiver unregisterReceiver()}. Dengan begitu aplikasi Anda +bisa mendengarkan siaran tertentu hanya selama periode waktu yang telah ditetapkan saat aplikasi Anda +berjalan.</p> + + + + + + + +<h3 id="ExampleFilters">Contoh filter</h3> + +<p>Untuk lebih memahami beberapa perilaku filter intent, lihatlah cuplikan berikut +dari file manifes aplikasi berbagi di jaringan sosial.</p> + +<pre> +<activity android:name="MainActivity"> + <!-- This activity is the main entry, should appear in app launcher --> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> +</activity> + +<activity android:name="ShareActivity"> + <!-- This activity handles "SEND" actions with text data --> + <intent-filter> + <action android:name="android.intent.action.SEND"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:mimeType="text/plain"/> + </intent-filter> + <!-- This activity also handles "SEND" and "SEND_MULTIPLE" with media data --> + <intent-filter> + <action android:name="android.intent.action.SEND"/> + <action android:name="android.intent.action.SEND_MULTIPLE"/> + <category android:name="android.intent.category.DEFAULT"/> + <data android:mimeType="application/vnd.google.panorama360+jpg"/> + <data android:mimeType="image/*"/> + <data android:mimeType="video/*"/> + </intent-filter> +</activity> +</pre> + +<p>Aktivitas pertama, {@code MainActivity}, merupakan titik masuk utama aplikasi—aplikasi yang +terbuka saat pengguna meluncurkan aplikasi dengan ikon launcher:</p> +<ul> + <li>Tindakan {@link android.content.Intent#ACTION_MAIN} + menunjukkan ini adalah titik masuk utama dan tidak mengharapkan data intent apa pun.</li> + <li>Kategori {@link android.content.Intent#CATEGORY_LAUNCHER} menunjukjkan bahwa ikon + aktivitas ini harus ditempatkan dalam launcher aplikasi sistem. Jika elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> + tidak menetapkan ikon dengan{@code icon}, maka sistem akan menggunakan ikon dari elemen +<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>.</li> +</ul> +<p>Keduanya harus dipasangkan bersama agar aktivitas muncul dalam launcher aplikasi.</p> + +<p>Aktivitas kedua, {@code ShareActivity}, dimaksudkan untuk memudahkan berbagi teks dan konten +media. Walaupun pengguna mungkin memasuki aktivitas ini dengan mengarah ke aktivitas dari {@code MainActivity}, +pengguna juga bisa memasukkan {@code ShareActivity} secara langsung dari aplikasi lain yang mengeluarkan intent +implisit yang cocok dengan salah satu dari kedua filter intent.</p> + +<p class="note"><strong>Catatan:</strong> Tipe MIME, +<a href="https://developers.google.com/panorama/android/">{@code +application/vnd.google.panorama360+jpg}</a>, merupakan tipe data khusus yang menetapkan +foto panorama, yang bisa Anda tangani dengan API <a href="{@docRoot}reference/com/google/android/gms/panorama/package-summary.html">panorama +Google</a>.</p> + + + + + + + + + + + + + +<h2 id="PendingIntent">Menggunakan Intent Tertunda</h2> + +<p>Objek {@link android.app.PendingIntent} merupakan pembungkus objek {@link +android.content.Intent}. Tujuan utama {@link android.app.PendingIntent} +adalah memberikan izin pada aplikasi asing +untuk menggunakan {@link android.content.Intent} yang termuat seolah-olah dieksekusi dari +proses aplikasi Anda sendiri.</p> + +<p>Kasus penggunaan utama untuk intent tertunda antara lain:</p> +<ul> + <li>Mendeklarasikan intent untuk dieksekusi saat pengguna melakukan tindakan dengan <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Pemberitahuan</a> + ({@link android.app.NotificationManager} + sistem Android akan mengeksekusi {@link android.content.Intent}) Anda. + <li>Mendeklarasikan intent untuk dieksekusi saat pengguna melakukan tindakan dengan +<a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> + (aplikasi layar Home mengeksekusi {@link android.content.Intent}). + <li>Mendeklarasikan intent untuk dieksekusi di waktu yang telah ditetapkan di masa mendatang +({@link android.app.AlarmManager} sistem Android akan mengeksekusi {@link android.content.Intent}). +</ul> + +<p>Karena setiap objek {@link android.content.Intent} didesain untuk ditangani oleh tipe +tertentu dari komponen aplikasi (baik {@link android.app.Activity}, {@link android.app.Service}, maupun + {@link android.content.BroadcastReceiver}), jadi {@link android.app.PendingIntent} harus +dibuat dengan pertimbangan yang sama. Saat menggunakan intent tertunda, aplikasi Anda tidak akan +mengeksekusi intent dengan panggilan seperti {@link android.content.Context#startActivity +startActivity()}. Anda harus mendeklarasikan tipe komponen yang dimaksud saat membuat +{@link android.app.PendingIntent} dengan memanggil metode kreator masing-masing:</p> + +<ul> + <li>{@link android.app.PendingIntent#getActivity PendingIntent.getActivity()} untuk + {@link android.content.Intent} yang memulai {@link android.app.Activity}.</li> + <li>{@link android.app.PendingIntent#getService PendingIntent.getService()} untuk + {@link android.content.Intent} yang memulai {@link android.app.Service}.</li> + <li>{@link android.app.PendingIntent#getBroadcast PendingIntent.getBroadcast()} untuk + {@link android.content.Intent} yang memulai {@link android.content.BroadcastReceiver}.</li> +</ul> + +<p>Kecuali jika aplikasi Anda <em>menerima</em> intent tertunda dari aplikasi lain, +metode di atas untuk membuat {@link android.app.PendingIntent} menjadi satu-satunya metode +{@link android.app.PendingIntent} yang mungkin Anda butuhkan.</p> + +<p>Tiap metode mengambil {@link android.content.Context} aplikasi saat itu, +{@link android.content.Intent} yang ingin Anda bungkus, dan satu atau beberapa flag yang menetapkan +cara penggunaan intent (misalnya apakah intent bisa digunakan lebih dari sekali).</p> + +<p>Informasi selengkapnya tentang intent tertunda disediakan pada dokumentasi untuk setiap +kasus penggunaan yang bersangkutan, seperti dalam panduan API <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> +dan <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a>.</p> + + + + + + + +<h2 id="Resolution">Resolusi Intent</h2> + + +<p>Saat sistem menerima intent implisit yang memulai suatu aktivitas, sistem tersebut akan mencari +aktivitas terbaik untuk intent dengan membandingkan intent dengan filter intent berdasarkan tiga aspek:</p> + +<ul> + <li>Tindakan intent + <li>Data intent (baik URI maupun tipe data) + <li>Kategori intent +</ul> + +<p>Bagian berikut menjelaskan cara pencocokan intent dengan komponen yang sesuai +sehubungan dengan cara pendeklarasian filter intent dalam file manifes aplikasi.</p> + + +<h3 id="ActionTest">Pengujian tindakan</h3> + +<p>Untuk menetapkan tindakan intent yang diterima, filter intent bisa mendeklarasikan nol atau beberapa elemen +<a href="{@docRoot}guide/topics/manifest/action-element.html">{@code +<action>}</a>. Misalnya:</p> + +<pre> +<intent-filter> + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.VIEW" /> + ... +</intent-filter> +</pre> + +<p>Untuk melewati filter ini, tindakan yang ditetapkan dalam {@link android.content.Intent} +harus sesuai dengan salah satu tindakan yang tercantum dalam filter.</p> + +<p>Jika filter tidak mencantumkan tindakan apa pun, maka tidak ada intent +yang dicocokkan, jadi semua intent gagal dalam pengujian. Akan tetapi, jika sebuah {@link android.content.Intent} +tidak menetapkan suatu tindakan, maka akan lolos pengujian (asalkan filter +berisi setidaknya satu tindakan).</p> + + + +<h3 id="CategoryTest">Pengujian kategori</h3> + +<p>Untuk menetapkan kategori intent yang diterima, filter intent bisa mendeklarasikan nol atau beberapa elemen +<a href="{@docRoot}guide/topics/manifest/category-element.html">{@code +<category>}</a>. Misalnya:</p> + +<pre> +<intent-filter> + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.BROWSABLE" /> + ... +</intent-filter> +</pre> + +<p>Agar intent bisa lolos pengujian kategori, setiap kategori dalam {@link android.content.Intent} +harus sesuai dengan kategori dalam filter. Kebalikannya tidak diperlukan—filter intent bisa +mendeklarasikan kategori lebih banyak daripada yang ditetapkan dalam {@link android.content.Intent} dan +{@link android.content.Intent} tetap akan lolos. Oleh karena itu, intent tanpa kategori harus +selalu lolos pengujian ini, kategori apa pun yang dideklarasikan dalam filter.</p> + +<p class="note"><strong>Catatan:</strong> +Android secara otomatis menerapkan kategori {@link android.content.Intent#CATEGORY_DEFAULT} +untuk semua intent implisit yang diteruskan ke {@link +android.content.Context#startActivity startActivity()} dan {@link +android.app.Activity#startActivityForResult startActivityForResult()}. +Jadi jika ingin aktivitas Anda menerima intent implisit, aktivitas tersebut harus +menyertakan kategori untuk{@code "android.intent.category.DEFAULT"} dalam filter intent (seperti +yang ditampilkan dalam contoh{@code <intent-filter>} sebelumnya.</p> + + + +<h3 id="DataTest">Pengujian data</h3> + +<p>Untuk menetapkan data intent yang diterima, filter intent bisa mendeklarasikan nol atau beberapa elemen +<a href="{@docRoot}guide/topics/manifest/data-element.html">{@code +<data>}</a>. Misalnya:</p> + +<pre> +<intent-filter> + <data android:mimeType="video/mpeg" android:scheme="http" ... /> + <data android:mimeType="audio/mpeg" android:scheme="http" ... /> + ... +</intent-filter> +</pre> + +<p>Tiap elemen <code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +bisa menetapkan struktur URI dan tipe data (tipe media MIME). Ada atribut +terpisah — {@code scheme}, {@code host}, {@code port}, +dan {@code path} — untuk setiap bagian URI: +</p> + +<p style="margin-left: 2em">{@code <scheme>://<host>:<port>/<path>}</p> + +<p> +Misalnya: +</p> + +<p style="margin-left: 2em">{@code content://com.example.project:200/folder/subfolder/etc}</p> + +<p>Dalam URI ini, skemanya adalah {@code content}, host-nya adalah {@code com.example.project}, +port-nya adalah {@code 200}, dan path-nya adalah {@code folder/subfolder/etc}. +</p> + +<p>Tiap atribut bersifat opsional dalam elemen <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a>, +namun ada dependensi linear:</p> +<ul> + <li>Jika skema tidak ditetapkan, host akan diabaikan.</li> + <li>Jika host tidak ditetapkan, port akan diabaikan.</li> + <li>Jika skema dan host tidak ditetapkan, path akan diabaikan.</li> +</ul> + +<p>Bila URI dalam intent dibandingkan dengan spesifikasi URI dalam filter, +pembandingannya hanya dengan bagian URI yang disertakan dalam filter. Misalnya:</p> +<ul> + <li>Jika sebuah filter menetapkan hanya satu skema, semua URI dengan skema tersebut akan cocok +dengan filter.</li> + <li>Jika sebuah filter menetapkan satu skema dan satu otoritas namun tanpa path, semua URI +dengan skema dan otoritas yang sama akan lolos dari filter, apa pun path-nya.</li> + <li>Jika sebuah filter menetapkan satu skema, otoritas dan path, hanya URI dengan skema, +otoritas, dan path sama yang bisa lolos dari filter.</li> +</ul> + +<p class="note"><strong>Catatan:</strong> Spesifikasi path bisa berisi +wildcard bintang (*) untuk hanya mencocokkan nama path secara parsial.</p> + +<p>Pengujian data membandingkan URI maupun tipe MIME dalam intent dengan URI +dan tipe MIME yang ditetapkan dalam filter. Aturannya adalah sebagai berikut: +</p> + +<ol type="a"> +<li>Intent yang tidak berisi URI maupun tipe MIME hanya akan lolos +pengujian jika filter tersebut tidak menetapkan URI atau tipe MIME apa pun.</li> + +<li>Intent yang berisi URI namun tidak berisi tipe MIME (baik secara eksplisit maupun tidak langsung dari +URI) hanya akan lolos pengujian jika URI-nya cocok dengan format URI filter +dan filternya juga tidak menetapkan tipe MIME.</li> + +<li>Intent yang berisi tipe MIME namun tidak berisi URI hanya akan lolos pengujian +jika filter mencantumkan tipe MIME yang sama dan tidak menetapkan format URI.</li> + +<li>Intent yang berisi URI maupun tipe MIME (baik secara eksplisit maupun tidak langsung dari +URI) hanya akan lolos pengujian bagian tipe MIME jika +tipe tersebut cocok dengan tipe yang dicantumkan dalam filter. Ini akan lolos pengujian bagian URI +jika URI-nya cocok dengan URI dalam filter atau memiliki {@code content:} +atau URI {@code file:} dan filter tidak menetapkan URI. Dengan kata lain, +komponen dianggap mendukung data {@code content:} dan {@code file:} jika +filternya <em>hanya</em> mencantumkan tipe MIME.</p></li> +</ol> + +<p> +Aturan terakhir ini, aturan (d), mencerminkan harapan +bahwa komponen mampu mendapatkan data lokal dari file atau penyedia konten. +Oleh karena itu, filter mereka mencatumkan tipe data saja dan tidak secara eksplisit +harus menamai skema {@code content:} dan {@code file:}. +Ini adalah kasus umum. Elemen <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> +seperti berikut ini, misalnya, memberi tahu Android bahwa komponen bisa mengambil data gambar dari penyedia +konten dan menampilkannya: +</p> + +<pre> +<intent-filter> + <data android:mimeType="image/*" /> + ... +</intent-filter></pre> + +<p> +Karena sebagian besar data yang tersedia dikeluarkan oleh penyedia konten, filter yang +menetapkan tipe data namun bukan URI mungkin adalah yang paling umum. +</p> + +<p> +Konfigurasi umum yang lain adalah filter dengan skema dan tipe data. Misalnya +, elemen <a href="{@docRoot}guide/topics/manifest/data-element.html">{@code <data>}</a> + seperti berikut ini akan memberi tahu Android bahwa +komponen bisa mengambil data video dari jaringan untuk melakukan tindakan: +</p> + +<pre> +<intent-filter> + <data android:scheme="http" android:type="video/*" /> + ... +</intent-filter></pre> + + + +<h3 id="imatch">Pencocokan intent</h3> + +<p>Intent dicocokkan dengan filter intent selain untuk menemukan komponen +target yang akan diaktifkan, juga untuk menemukan sesuatu tentang rangkaian +komponen pada perangkat. Misalnya, aplikasi Home akan menempatkan launcher aplikasi +dengan mencari semua aktivitas dengan filter intent yang menetapkan tindakan +{@link android.content.Intent#ACTION_MAIN} dan +kategori {@link android.content.Intent#CATEGORY_LAUNCHER}.</p> + +<p>Aplikasi Anda bisa menggunakan pencocokan intent dengan cara serupa. +{@link android.content.pm.PackageManager} memiliki seperangkat metode {@code query...()} +yang mengembalikan semua komponen yang bisa menerima intent tertentu, dan +serangkaian metode{@code resolve...()} serupa yang menentukan komponen +terbaik untuk merespons intent. Misalnya, +{@link android.content.pm.PackageManager#queryIntentActivities +queryIntentActivities()} akan mengembalikan daftar semua aktivitas yang bisa melakukan +intent yang diteruskan sebagai argumen, dan {@link +android.content.pm.PackageManager#queryIntentServices +queryIntentServices()} akan mengembalikan daftar layanan serupa. +Tidak ada metode yang akan mengaktifkan komponen; mereka hanya mencantumkan komponen yang +bisa merespons. Ada metode serupa, +{@link android.content.pm.PackageManager#queryBroadcastReceivers +queryBroadcastReceivers()}, untuk penerima siaran. +</p> + + + + diff --git a/docs/html-intl/intl/in/guide/components/loaders.jd b/docs/html-intl/intl/in/guide/components/loaders.jd new file mode 100644 index 000000000000..cd0379bf1cd9 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/loaders.jd @@ -0,0 +1,494 @@ +page.title=Aktivitas +parent.title=Loader +parent.link=activities.html +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#summary">Rangkuman Loader API</a></li> + <li><a href="#app">Menggunakan Loader dalam Aplikasi</a> + <ol> + <li><a href="#requirements"></a></li> + <li><a href="#starting">Memulai Loader</a></li> + <li><a href="#restarting">Me-restart Loader</a></li> + <li><a href="#callback">Menggunakan Callback LoaderManager</a></li> + </ol> + </li> + <li><a href="#example">Contoh</a> + <ol> + <li><a href="#more_examples">Contoh Selengkapnya</a></li> + </ol> + </li> + </ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.app.LoaderManager}</li> + <li>{@link android.content.Loader}</li> + + </ol> + + <h2>Contoh-contoh terkait</h2> + <ol> + <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html"> +LoaderCursor</a></li> + <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> +LoaderThrottle</a></li> + </ol> + </div> +</div> + +<p>Diperkenalkan di Android 3.0, loader memudahkan pemuatan data asinkron +dalam aktivitas atau fragmen. Loader memiliki karakteristik ini:</p> + <ul> + <li>Loader tersedia untuk setiap {@link android.app.Activity} dan {@link +android.app.Fragment}.</li> + <li>Loader menyediakan pemuatan data asinkron.</li> + <li>Loader memantau sumber data mereka dan memberikan hasil baru bila +konten berubah.</li> + <li>Loader secara otomatis menghubungkan kembali ke kursor loader lalu saat +dibuat kembali setelah perubahan konfigurasi. Karena itu, loader tidak perlu melakukan query ulang +datanya.</li> + </ul> + +<h2 id="summary">Rangkuman Loader API</h2> + +<p>Ada beberapa kelas dan antarmuka yang mungkin dilibatkan dalam menggunakan +loader pada aplikasi. Semuanya dirangkum dalam tabel ini:</p> + +<table> + <tr> + <th>Kelas/Antarmuka</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.app.LoaderManager}</td> + <td>Kelas abstrak yang dikaitkan dengan {@link android.app.Activity} atau +{@link android.app.Fragment} untuk mengelola satu atau beberapa instance {@link +android.content.Loader}. Ini membantu aplikasi mengelola +operasi berjalan lebih lama bersamaan dengan daur hidup {@link android.app.Activity} +atau {@link android.app.Fragment}; penggunaan paling umumnya adalah dengan +{@link android.content.CursorLoader}, akan tetapi aplikasi bebas menulis loader-nya + sendiri untuk memuat tipe data lainnya. + <br /> + <br /> + Hanya ada satu {@link android.app.LoaderManager} per aktivitas atau fragmen. Namun {@link android.app.LoaderManager} bisa memiliki +beberapa loader.</td> + </tr> + <tr> + <td>{@link android.app.LoaderManager.LoaderCallbacks}</td> + <td>Antarmuka callback untuk klien berinteraksi dengan {@link +android.app.LoaderManager}. Misalnya, Anda menggunakan metode callback {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} +untuk membuat loader baru.</td> + </tr> + <tr> + <td>{@link android.content.Loader}</td> + <td>Kelas abstrak yang melakukan pemuatan data asinkron. Ini +adalah kelas dasar untuk loader. Biasanya Anda akan menggunakan {@link +android.content.CursorLoader}, namun Anda bisa menerapkan subkelas sendiri. Selagi +loader aktif, loader harus memantau sumber datanya dan memberikan hasil +baru bila konten berubah. </td> + </tr> + <tr> + <td>{@link android.content.AsyncTaskLoader}</td> + <td>Loader abstrak yang menyediakan {@link android.os.AsyncTask} untuk melakukan pekerjaan.</td> + </tr> + <tr> + <td>{@link android.content.CursorLoader}</td> + <td>Subkelas {@link android.content.AsyncTaskLoader} yang meng-query +{@link android.content.ContentResolver} dan mengembalikan {@link +android.database.Cursor}. Kelas ini mengimplementasikan protokol {@link +android.content.Loader} dengan cara standar untuk query kursor, +yang dibuat berdasarkan {@link android.content.AsyncTaskLoader} untuk melakukan query kursor +pada thread latar belakang agar tidak memblokir UI aplikasi. Menggunakan loader +ini merupakan cara terbaik untuk memuat data secara asinkron dari {@link +android.content.ContentProvider}, sebagai ganti melakukan query terkelola melalui +fragmen atau API aktivitas.</td> + </tr> +</table> + +<p>Kelas dan antarmuka dalam tabel di atas merupakan komponen +esensial yang akan Anda gunakan untuk mengimplementasikan loader dalam aplikasi Anda. Anda tidak memerlukan semuanya +untuk setiap loader yang dibuat, namun Anda akan selalu memerlukan acuan ke {@link +android.app.LoaderManager} untuk memulai loader dan implementasi +kelas {@link android.content.Loader} seperti {@link +android.content.CursorLoader}. Bagian berikut ini menunjukkan kepada Anda cara menggunakan +kelas dan antarmuka ini dalam aplikasi.</p> + +<h2 id ="app">Menggunakan Loader dalam Aplikasi</h2> +<p>Bagian ini menjelaskan cara menggunakan loader dalam aplikasi Android. Aplikasi +yang menggunakan loader biasanya berisi yang berikut ini:</p> +<ul> + <li>{@link android.app.Activity} atau {@link android.app.Fragment}.</li> + <li>Instance {@link android.app.LoaderManager}.</li> + <li>{@link android.content.CursorLoader} akan memuat data yang didukung oleh {@link +android.content.ContentProvider}. Atau, Anda dapat mengimplementasikan subkelas sendiri + dari {@link android.content.Loader} atau {@link android.content.AsyncTaskLoader} untuk +memuat data dari beberapa sumber lain.</li> + <li>Implementasi untuk {@link android.app.LoaderManager.LoaderCallbacks}. +Di sinilah Anda membuat loader baru dan mengelola acuan bagi loader +yang ada.</li> +<li>Cara menampilkan data loader, seperti {@link +android.widget.SimpleCursorAdapter}.</li> + <li>Sumber data, seperti {@link android.content.ContentProvider}, saat menggunakan +{@link android.content.CursorLoader}.</li> +</ul> +<h3 id="starting">Memulai Loader</h3> + +<p>{@link android.app.LoaderManager} mengelola satu atau beberapa instance {@link +android.content.Loader} dalam {@link android.app.Activity} atau +{@link android.app.Fragment}. Hanya ada satu {@link +android.app.LoaderManager} per aktivitas atau fragmen.</p> + +<p>Anda biasanya +memulai {@link android.content.Loader} dalam metode {@link +android.app.Activity#onCreate onCreate()} aktivitas, atau dalam metode +{@link android.app.Fragment#onActivityCreated onActivityCreated()} fragmen. Anda +melakukannya dengan cara berikut ini:</p> + +<pre>// Prepare the loader. Either re-connect with an existing one, +// or start a new one. +getLoaderManager().initLoader(0, null, this);</pre> + +<p>Metode {@link android.app.LoaderManager#initLoader initLoader()} mengambil +parameter berikut:</p> +<ul> + <li>ID unik yang mengidentifikasi loader. Dalam contoh ini, ID-nya adalah 0.</li> +<li>Argumen opsional untuk dipasok ke loader +pada saat pembuatan (dalam contoh ini <code>null</code>).</li> + +<li>Implementasi {@link android.app.LoaderManager.LoaderCallbacks}, yang +akan dipanggil {@link android.app.LoaderManager} untuk melaporkan kejadian loader. Dalam contoh +ini, kelas lokal mengimplementasikan antarmuka {@link +android.app.LoaderManager.LoaderCallbacks}, sehingga meneruskan acuan +ke dirinya sendiri, {@code this}.</li> +</ul> +<p>Panggilan {@link android.app.LoaderManager#initLoader initLoader()} memastikan bahwa loader +telah dimulai dan aktif. Ia memiliki dua kemungkinan hasil:</p> +<ul> + <li>Jika loader yang disebutkan oleh ID sudah ada, loader yang dibuat terakhir akan digunakan +kembali.</li> + <li>Jika loader yang disebutkan oleh ID <em>tidak</em> ada, +{@link android.app.LoaderManager#initLoader initLoader()} akan memicu metode +{@link android.app.LoaderManager.LoaderCallbacks} {@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. +Di sinilah Anda mengimplementasikan kode untuk membuat instance dan mengembalikan loader baru. +Untuk diskusi selengkapnya, lihat bagian <a href="#onCreateLoader">onCreateLoader</a>.</li> +</ul> +<p>Dalam hal ini, implementasi {@link android.app.LoaderManager.LoaderCallbacks} +yang ditentukan akan dikaitkan dengan loader, dan akan dipanggil bila +status loader berubah. Jika saat panggilan ini status pemanggil sudah +dimulai, dan loader yang diminta sudah ada dan telah menghasilkan +datanya, maka sistem segera memanggil {@link +android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} +(selama {@link android.app.LoaderManager#initLoader initLoader()}), +sehingga Anda harus siap bila hal ini terjadi. Lihat <a href="#onLoadFinished"> +onLoadFinished</a> untuk diskusi selengkapnya mengenai callback ini</p> + +<p>Perhatikan bahwa metode {@link android.app.LoaderManager#initLoader initLoader()} +mengembalikan {@link android.content.Loader} yang dibuat, namun Anda tidak +perlu menangkap acuan ke sana. {@link android.app.LoaderManager} mengelola +masa hidup loader secara otomatis. {@link android.app.LoaderManager} +memulai dan menghentikan pemuatan jika perlu, dan menjaga status loader +dan konten terkaitnya. Seperti yang tersirat di sini, Anda akan jarang berinteraksi dengan loader +secara langsung (meskipun misalnya menggunakan metode loader untuk menyempurnakan perilaku +loader, lihat contoh <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a>). +Anda paling sering akan menggunakan metode {@link +android.app.LoaderManager.LoaderCallbacks} untuk mengintervensi proses +pemuatan saat terjadi kejadian tertentu. Untuk diskusi selengkapnya mengenai topik ini, lihat <a href="#callback">Menggunakan Callback LoaderManager</a>.</p> + +<h3 id="restarting">Me-restart Loader</h3> + +<p>Bila Anda menggunakan {@link android.app.LoaderManager#initLoader initLoader()}, seperti +ditampilkan di atas, loader yang ada akan digunakan dengan ID yang ditetapkan jika ada. +Jika tidak ada, ID akan dibuat. Namun kadang-kadang Anda perlu membuang data lama +dan mulai dari awal.</p> + +<p>Untuk membuang data lama, gunakan {@link +android.app.LoaderManager#restartLoader restartLoader()}. Misalnya, implementasi +{@link android.widget.SearchView.OnQueryTextListener} ini akan me-restart +bila query pengguna berubah. Loader perlu di-restart +agar dapat menggunakan filter pencarian yang telah direvisi untuk melakukan query baru:</p> + +<pre> +public boolean onQueryTextChanged(String newText) { + // Called when the action bar search text has changed. Update + // the search filter, and restart the loader to do a new query + // with this filter. + mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; + getLoaderManager().restartLoader(0, null, this); + return true; +}</pre> + +<h3 id="callback">Menggunakan Callback LoaderManager</h3> + +<p>{@link android.app.LoaderManager.LoaderCallbacks} adalah antarmuka callback +yang memungkinkan klien berinteraksi dengan {@link android.app.LoaderManager}. </p> +<p>Loader, khususnya {@link android.content.CursorLoader}, diharapkan +mempertahankan datanya setelah dihentikan. Ini memungkinkan aplikasi mempertahankan +datanya di aktivitas atau metode {@link android.app.Activity#onStop +onStop()} fragmen dan {@link android.app.Activity#onStart onStart()}, sehingga +bila pengguna kembali ke aplikasi, mereka tidak harus menunggu data +dimuat kembali. Anda menggunakan metode {@link android.app.LoaderManager.LoaderCallbacks} +untuk mengetahui waktu membuat loader baru, dan memberi tahu aplikasi kapan +berhenti menggunakan data loader.</p> + +<p>{@link android.app.LoaderManager.LoaderCallbacks} berisi metode +ini:</p> +<ul> + <li>{@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} — +Membuat instance dan mengembalikan {@link android.content.Loader} baru untuk ID yang diberikan. +</li></ul> +<ul> + <li> {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} +— Dipanggil bila loader yang dibuat sebelumnya selesai dimuat. +</li></ul> +<ul> + <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()} + — Dipanggil bila loader yang dibuat sebelumnya sedang di-reset, sehingga datanya +tidak tersedia. +</li> +</ul> +<p>Metode ini dijelaskan lebih detail dalam bagian berikutnya.</p> + +<h4 id ="onCreateLoader">onCreateLoader</h4> + +<p>Saat Anda mencoba mengakses loader (misalnya, melalui {@link +android.app.LoaderManager#initLoader initLoader()}), ia akan memeriksa untuk mengetahui adanya +loader yang ditetapkan oleh ID. Jika tidak ada, ia akan memicu metode {@link +android.app.LoaderManager.LoaderCallbacks} {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. Di +sinilah Anda membuat loader baru. Biasanya ini adalah {@link +android.content.CursorLoader}, namun Anda bisa mengimplementasikan sendiri subkelas {@link +android.content.Loader}. </p> + +<p>Dalam contoh ini, metode callback {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} + akan membuat {@link android.content.CursorLoader}. Anda harus membuat +{@link android.content.CursorLoader} menggunakan metode konstruktornya, yang +memerlukan set informasi lengkap untuk melakukan query ke {@link +android.content.ContentProvider}. Secara khusus, ia memerlukan:</p> +<ul> + <li><em>uri</em> — URI untuk konten yang akan diambil. </li> + <li><em>projection</em> — Daftar berisi kolom yang akan dikembalikan. Meneruskan +<code>null</code> akan mengembalikan semua kolom, jadi tidak efisien. </li> + <li><em>selection</em> — Filter yang mendeklarasikan baris yang akan dikembalikan, +diformat sebagai klausa SQL WHERE (tidak termasuk WHERE itu sendiri). Meneruskan +<code>null</code> akan mengembalikan semua baris untuk URI yang diberikan. </li> + <li><em>selectionArgs</em> — Anda dapat menyertakan ?s dalam pilihan, yang akan +digantikan dengan nilai dari <em>selectionArgs</em>, agar muncul dalam +pilihan. Nilai-nilai akan diikat sebagai String. </li> + <li><em>sortOrder</em> — Cara menyusun baris, diformat sebagai klausa SQL +ORDER BY (tidak termasuk ORDER BY itu sendiri). Meneruskan <code>null</code> akan +menggunakan urutan sortir default, yang mungkin tidak berurutan.</li> +</ul> +<p>Misalnya:</p> +<pre> + // If non-null, this is the current filter the user has provided. +String mCurFilter; +... +public Loader<Cursor> onCreateLoader(int id, Bundle args) { + // This is called when a new Loader needs to be created. This + // sample only has one Loader, so we don't care about the ID. + // First, pick the base URI to use depending on whether we are + // currently filtering. + Uri baseUri; + if (mCurFilter != null) { + baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, + Uri.encode(mCurFilter)); + } else { + baseUri = Contacts.CONTENT_URI; + } + + // Now create and return a CursorLoader that will take care of + // creating a Cursor for the data being displayed. + String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" + + Contacts.HAS_PHONE_NUMBER + "=1) AND (" + + Contacts.DISPLAY_NAME + " != '' ))"; + return new CursorLoader(getActivity(), baseUri, + CONTACTS_SUMMARY_PROJECTION, select, null, + Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); +}</pre> +<h4 id="onLoadFinished">onLoadFinished</h4> + +<p>Metode ini dipanggil bila loader yang dibuat sebelumnya selesai dimuat. +Metode ini dijamin dipanggil sebelum pelepasan data terakhir +yang disediakan untuk loader ini. Di titik ini Anda harus menyingkirkan semua penggunaan +data lama (karena akan segera dilepas), namun jangan melepas sendiri +data tersebut karena loader memilikinya dan akan menanganinya.</p> + + +<p>Loader akan melepas data setelah mengetahui bahwa aplikasi tidak +lagi menggunakannya. Misalnya, jika data adalah kursor dari {@link +android.content.CursorLoader}, Anda tidak boleh memanggil {@link +android.database.Cursor#close close()} sendiri. Jika kursor ditempatkan +dalam {@link android.widget.CursorAdapter}, Anda harus menggunakan metode {@link +android.widget.SimpleCursorAdapter#swapCursor swapCursor()} agar +{@link android.database.Cursor} lama tidak ditutup. Misalnya:</p> + +<pre> +// This is the Adapter being used to display the list's data.<br +/>SimpleCursorAdapter mAdapter; +... + +public void onLoadFinished(Loader<Cursor> loader, Cursor data) { + // Swap the new cursor in. (The framework will take care of closing the + // old cursor once we return.) + mAdapter.swapCursor(data); +}</pre> + +<h4 id="onLoaderReset">onLoaderReset</h4> + +<p>Metode ini dipanggil bila loader yang dibuat sebelumnya sedang di-reset, sehingga datanya +tidak tersedia. Callback ini memungkinkan Anda mengetahui +kapan data akan dilepas sehingga dapat menghapus acuannya ke callback. </p> +<p>Implementasi ini memanggil +{@link android.widget.SimpleCursorAdapter#swapCursor swapCursor()} +dengan nilai <code>null</code>:</p> + +<pre> +// This is the Adapter being used to display the list's data. +SimpleCursorAdapter mAdapter; +... + +public void onLoaderReset(Loader<Cursor> loader) { + // This is called when the last Cursor provided to onLoadFinished() + // above is about to be closed. We need to make sure we are no + // longer using it. + mAdapter.swapCursor(null); +}</pre> + + +<h2 id="example">Contoh</h2> + +<p>Sebagai contoh, berikut ini adalah implementasi penuh {@link +android.app.Fragment} yang menampilkan {@link android.widget.ListView} berisi +hasil query terhadap penyedia konten kontak. Ia menggunakan {@link +android.content.CursorLoader} untuk mengelola query pada penyedia.</p> + +<p>Agar aplikasi dapat mengakses kontak pengguna, seperti yang ditampilkan dalam contoh ini, +manifesnya harus menyertakan izin +{@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS}.</p> + +<pre> +public static class CursorLoaderListFragment extends ListFragment + implements OnQueryTextListener, LoaderManager.LoaderCallbacks<Cursor> { + + // This is the Adapter being used to display the list's data. + SimpleCursorAdapter mAdapter; + + // If non-null, this is the current filter the user has provided. + String mCurFilter; + + @Override public void onActivityCreated(Bundle savedInstanceState) { + super.onActivityCreated(savedInstanceState); + + // Give some text to display if there is no data. In a real + // application this would come from a resource. + setEmptyText("No phone numbers"); + + // We have a menu item to show in action bar. + setHasOptionsMenu(true); + + // Create an empty adapter we will use to display the loaded data. + mAdapter = new SimpleCursorAdapter(getActivity(), + android.R.layout.simple_list_item_2, null, + new String[] { Contacts.DISPLAY_NAME, Contacts.CONTACT_STATUS }, + new int[] { android.R.id.text1, android.R.id.text2 }, 0); + setListAdapter(mAdapter); + + // Prepare the loader. Either re-connect with an existing one, + // or start a new one. + getLoaderManager().initLoader(0, null, this); + } + + @Override public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) { + // Place an action bar item for searching. + MenuItem item = menu.add("Search"); + item.setIcon(android.R.drawable.ic_menu_search); + item.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM); + SearchView sv = new SearchView(getActivity()); + sv.setOnQueryTextListener(this); + item.setActionView(sv); + } + + public boolean onQueryTextChange(String newText) { + // Called when the action bar search text has changed. Update + // the search filter, and restart the loader to do a new query + // with this filter. + mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; + getLoaderManager().restartLoader(0, null, this); + return true; + } + + @Override public boolean onQueryTextSubmit(String query) { + // Don't care about this. + return true; + } + + @Override public void onListItemClick(ListView l, View v, int position, long id) { + // Insert desired behavior here. + Log.i("FragmentComplexList", "Item clicked: " + id); + } + + // These are the Contacts rows that we will retrieve. + static final String[] CONTACTS_SUMMARY_PROJECTION = new String[] { + Contacts._ID, + Contacts.DISPLAY_NAME, + Contacts.CONTACT_STATUS, + Contacts.CONTACT_PRESENCE, + Contacts.PHOTO_ID, + Contacts.LOOKUP_KEY, + }; + public Loader<Cursor> onCreateLoader(int id, Bundle args) { + // This is called when a new Loader needs to be created. This + // sample only has one Loader, so we don't care about the ID. + // First, pick the base URI to use depending on whether we are + // currently filtering. + Uri baseUri; + if (mCurFilter != null) { + baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, + Uri.encode(mCurFilter)); + } else { + baseUri = Contacts.CONTENT_URI; + } + + // Now create and return a CursorLoader that will take care of + // creating a Cursor for the data being displayed. + String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" + + Contacts.HAS_PHONE_NUMBER + "=1) AND (" + + Contacts.DISPLAY_NAME + " != '' ))"; + return new CursorLoader(getActivity(), baseUri, + CONTACTS_SUMMARY_PROJECTION, select, null, + Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); + } + + public void onLoadFinished(Loader<Cursor> loader, Cursor data) { + // Swap the new cursor in. (The framework will take care of closing the + // old cursor once we return.) + mAdapter.swapCursor(data); + } + + public void onLoaderReset(Loader<Cursor> loader) { + // This is called when the last Cursor provided to onLoadFinished() + // above is about to be closed. We need to make sure we are no + // longer using it. + mAdapter.swapCursor(null); + } +}</pre> +<h3 id="more_examples">Contoh Selengkapnya</h3> + +<p>Ada beberapa contoh berbeda dalam <strong>ApiDemos</strong> yang +mengilustrasikan cara menggunakan loader:</p> +<ul> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html"> +LoaderCursor</a> — Versi lengkap dari +cuplikan yang ditampilkan di atas.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> — Contoh cara penggunaan throttling untuk +mengurangi jumlah query dari penyedia konten saat datanya berubah.</li> +</ul> + +<p>Untuk informasi tentang mengunduh dan menginstal contoh SDK, lihat <a href="http://developer.android.com/resources/samples/get.html"> Mendapatkan +Contoh</a>. </p> + diff --git a/docs/html-intl/intl/in/guide/components/processes-and-threads.jd b/docs/html-intl/intl/in/guide/components/processes-and-threads.jd new file mode 100644 index 000000000000..44051bf492e0 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/processes-and-threads.jd @@ -0,0 +1,411 @@ +page.title=Proses dan Thread +page.tags=daur hidup,latar belakang + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> +<li><a href="#Processes">Proses</a> + <ol> + <li><a href="#Lifecycle">Daur hidup proses</a></li> + </ol> +</li> +<li><a href="#Threads">Thread</a> + <ol> + <li><a href="#WorkerThreads">Thread pekerja</a></li> + <li><a href="#ThreadSafe">Metode thread-safe</a></li> + </ol> +</li> +<li><a href="#IPC">Komunikasi antarproses</a></li> +</ol> + +</div> +</div> + +<p>Bila komponen aplikasi dimulai dan tidak ada komponen aplikasi lain yang +berjalan, sistem Android akan memulai proses Linux baru untuk aplikasi dengan satu thread +eksekusi. Secara default, semua komponen aplikasi yang sama berjalan dalam proses dan +thread yang sama (disebut thread "utama"). Jika komponen aplikasi dimulai dan sudah ada +proses untuk aplikasi itu (karena komponen lain dari aplikasi itu sudah ada), maka komponen +akan dimulai dalam proses itu dan menggunakan thread eksekusi yang sama. Akan tetapi, Anda bisa +mengatur komponen berbeda di aplikasi agar berjalan di proses terpisah, dan Anda bisa membuat thread tambahan untuk +setiap proses.</p> + +<p>Dokumen ini membahas cara kerja proses dan thread di aplikasi Android.</p> + + +<h2 id="Processes">Proses</h2> + +<p>Secara default, semua komponen aplikasi yang sama berjalan dalam proses yang sama dan kebanyakan +aplikasi tidak boleh mengubah ini. Akan tetapi, jika Anda merasa perlu mengontrol proses milik +komponen tertentu, Anda dapat melakukannya dalam file manifes.</p> + +<p>Entri manifes untuk setiap tipe elemen komponen—<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>, <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code +<service>}</a>, <a href="{@docRoot}guide/topics/manifest/receiver-element.html">{@code +<receiver>}</a>, dan <a href="{@docRoot}guide/topics/manifest/provider-element.html">{@code +<provider>}</a>—mendukung atribut {@code android:process} yang bisa menetapkan +dalam proses mana komponen harus dijalankan. Anda bisa mengatur atribut ini agar setiap komponen +berjalan dalam prosesnya sendiri atau agar beberapa komponen menggunakan proses yang sama sementara yang lainnya tidak. Anda juga bisa mengatur +{@code android:process} agar komponen aplikasi yang berbeda berjalan dalam proses yang sama +—sepanjang aplikasi menggunakan ID Linux yang sama dan ditandatangani +dengan sertifikat yang sama.</p> + +<p>Elemen <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> juga mendukung atribut {@code android:process}, untuk mengatur +nilai default yang berlaku bagi semua komponen.</p> + +<p>Android bisa memutuskan untuk mematikan proses pada waktu tertentu, bila memori tinggal sedikit dan diperlukan oleh +proses lain yang lebih mendesak untuk melayani pengguna. Komponen +aplikasi yang berjalan dalam proses yang dimatikan maka sebagai konsekuensinya juga akan dimusnahkan. Proses dimulai +kembali untuk komponen itu bila ada lagi pekerjaan untuk mereka lakukan.</p> + +<p>Saat memutuskan proses yang akan dimatikan, sistem Android akan mempertimbangkan kepentingan relatifnya bagi +pengguna. Misalnya, sistem lebih mudah menghentikan proses yang menjadi host aktivitas yang tidak + lagi terlihat di layar, dibandingkan dengan proses yang menjadi host aktivitas yang terlihat. Karena itu, keputusan +untuk menghentikan proses bergantung pada keadaan komponen yang berjalan dalam proses tersebut. Aturan +yang digunakan untuk menentukan proses yang akan dihentikan dibahas di bawah ini. </p> + + +<h3 id="Lifecycle">Daur hidup proses</h3> + +<p>Sistem Android mencoba mempertahankan proses aplikasi selama mungkin, namun +pada akhirnya perlu menghapus proses lama untuk mengambil kembali memori bagi proses baru atau yang lebih penting. Untuk +menentukan proses yang akan +dipertahankan dan yang harus dimatikan, sistem menempatkan setiap proses ke dalam "hierarki prioritas" berdasarkan +komponen yang berjalan dalam proses dan status komponen tersebut. Proses yang memiliki +prioritas terendah akan dimatikan terlebih dahulu, kemudian yang terendah berikutnya, dan seterusnya, jika perlu +untuk memulihkan sumber daya sistem.</p> + +<p>Ada lima tingkatan dalam hierarki prioritas. Daftar berikut berisi beberapa +tipe proses berdasarkan urutan prioritas (proses pertama adalah yang <em>terpenting</em> dan +<em>dimatikan terakhir</em>):</p> + +<ol> + <li><b>Proses latar depan</b> + <p>Proses yang diperlukan untuk aktivitas yang sedang dilakukan pengguna. Proses +dianggap berada di latar depan jika salah satu kondisi berikut terpenuhi:</p> + + <ul> + <li>Proses menjadi host {@link android.app.Activity} yang berinteraksi dengan pengguna dengan metode ({@link +android.app.Activity}{@link android.app.Activity#onResume onResume()} telah +dipanggil).</li> + + <li>Proses menjadi host {@link android.app.Service} yang terikat dengan aktivitas yang sedang berinteraksi dengan +pengguna.</li> + + <li>Proses menjadi host {@link android.app.Service} yang berjalan "di latar depan"— +layanan telah memanggil{@link android.app.Service#startForeground startForeground()}. + + <li>Proses menjadi host {@link android.app.Service} yang menjalankan salah satu callback +daur hidupnya ({@link android.app.Service#onCreate onCreate()}, {@link android.app.Service#onStart +onStart()}, atau {@link android.app.Service#onDestroy onDestroy()}).</li> + + <li>Proses menjadi host {@link android.content.BroadcastReceiver} yang menjalankan metode {@link + android.content.BroadcastReceiver#onReceive onReceive()}-nya.</li> + </ul> + + <p>Secara umum, hanya ada beberapa proses latar depan pada waktu yang diberikan. Proses dimatikan hanya sebagai +upaya terakhir— jika memori hampir habis sehingga semuanya tidak bisa terus berjalan. Pada umumnya, pada +titik itu, perangkat dalam keadaan memory paging, sehingga menghentikan beberapa proses latar depan +diperlukan agar antarmuka pengguna tetap responsif.</p></li> + + <li><b>Proses yang terlihat</b> + <p>Proses yang tidak memiliki komponen latar depan, namun masih bisa +memengaruhi apa yang dilihat pengguna di layar. Proses dianggap terlihat jika salah satu kondisi +berikut terpenuhi:</p> + + <ul> + <li>Proses ini menjadi host {@link android.app.Activity} yang tidak berada di latar depan, namun masih +terlihat oleh penggunanya (metode {@link android.app.Activity#onPause onPause()} telah dipanggil). +Ini bisa terjadi, misalnya, jika aktivitas latar depan memulai dialog, sehingga +aktivitas sebelumnya terlihat berada di belakangnya.</li> + + <li>Proses menjadi host {@link android.app.Service} yang terikat dengan aktivitas yang terlihat (atau latar +depan)</li> + </ul> + + <p>Proses yang terlihat dianggap sangat penting dan tidak akan dimatikan kecuali jika hal itu +diperlukan agar semua proses latar depan tetap berjalan. </p> + </li> + + <li><b>Proses layanan</b> + <p>Proses yang menjalankan layanan yang telah dimulai dengan metode {@link +android.content.Context#startService startService()} dan tidak termasuk dalam salah satu dari dua kategori +yang lebih tinggi. Walaupun proses pelayanan tidak langsung terkait dengan semua yang dilihat oleh pengguna, proses ini +umumnya melakukan hal-hal yang dipedulikan pengguna (seperti memutar musik di latar belakang +atau mengunduh data di jaringan), jadi sistem membuat proses tetap berjalan kecuali memori tidak cukup untuk +mempertahankannya bersama semua proses latar depan dan proses yang terlihat. </p> + </li> + + <li><b>Proses latar belakang</b> + <p>Proses yang menampung aktivitas yang saat ini tidak terlihat oleh pengguna (metode +{@link android.app.Activity#onStop onStop()} aktivitas telah dipanggil). Proses ini tidak memiliki dampak +langsung pada pengalaman pengguna, dan sistem bisa menghentikannya kapan saja untuk memperoleh kembali memori bagi +proses latar depan, proses yang terlihat, +atau proses layanan. Biasanya ada banyak proses latar belakang yang berjalan, sehingga disimpan +dalam daftar LRU (least recently used atau paling sedikit digunakan) untuk memastikan bahwa proses dengan aktivitas yang paling baru +terlihat oleh pengguna sebagai yang terakhir untuk dimatikan. Jika aktivitas mengimplementasikan metode + daur hidupnya dengan benar, dan menyimpan statusnya saat ini, menghentikan prosesnya tidak akan memiliki efek +yang terlihat pada pengalaman pengguna, karena ketika pengguna kembali ke aktivitas, aktivitas itu memulihkan +semua statusnya yang terlihat. Lihat dokumen <a href="{@docRoot}guide/components/activities.html#SavingActivityState">Aktivitas</a> + untuk mendapatkan informasi tentang menyimpan dan memulihkan status.</p> + </li> + + <li><b>Proses kosong</b> + <p>Sebuah proses yang tidak berisi komponen aplikasi aktif apa pun. Alasan satu-satunya mempertahankan proses +seperti ini tetap hidup adalah untuk keperluan caching, meningkatkan waktu mulai (startup) bila +nanti komponen perlu dijalankan di dalamnya. Sistem sering menghentikan proses ini untuk menyeimbangkan sumber +daya sistem secara keseluruhan antara proses cache dan cache kernel yang mendasarinya.</p> + </li> +</ol> + + + <p>Android sebisa mungkin memeringkat proses setinggi +mungkin, berdasarkan prioritas komponen yang sedang aktif dalam proses. Misalnya, jika suatu proses menjadi host sebuah layanan dan +aktivitas yang terlihat, proses akan diperingkat sebagai proses yang terlihat, bukan sebagai proses layanan.</p> + + <p>Selain itu, peringkat proses dapat meningkat karena adanya proses lain yang bergantung padanya +—proses yang melayani proses lain tidak bisa diperingkat lebih rendah daripada proses yang +sedang dilayaninya. Misalnya, jika penyedia konten dalam proses A melayani klien dalam proses B, atau +jika layanan dalam proses A terikat dengan komponen dalam proses B, proses A selalu dipertimbangkan sebagai paling rendah +prioritasnya dibandingkan dengan proses B.</p> + + <p>Karena proses yang menjalankan layanan diperingkat lebih tinggi daripada aktivitas latar belakang, +aktivitas yang memulai operasi yang berjalan lama mungkin lebih baik memulai <a href="{@docRoot}guide/components/services.html">layanan</a> untuk operasi itu, daripada hanya +membuat thread pekerja—khususnya jika operasi mungkin akan berlangsung lebih lama daripada aktivitas. + Misalnya, aktivitas yang mengunggah gambar ke situs web harus memulai layanan +untuk mengunggah sehingga unggahan bisa terus berjalan di latar belakang meskipun pengguna meninggalkan aktivitas tersebut. +Menggunakan layanan akan memastikan operasi paling tidak memiliki prioritas "proses layanan", +apa pun yang terjadi pada aktivitas. Ini menjadi alasan yang sama yang membuat penerima siaran harus +menjalankan layanan daripada hanya menempatkan operasi yang menghabiskan waktu di thread.</p> + + + + +<h2 id="Threads">Thread</h2> + +<p>Bila aplikasi diluncurkan, sistem akan membuat thread eksekusi untuk aplikasi tersebut, yang diberi nama, +"main". Thread ini sangat penting karena bertugas mengirim kejadian ke widget +antarmuka pengguna yang sesuai, termasuk kejadian menggambar. Ini juga merupakan thread yang +membuat aplikasi berinteraksi dengan komponen dari Android UI toolkit (komponen dari paket {@link +android.widget} dan {@link android.view}). Karena itu, thread 'main' juga terkadang +disebut thread UI.</p> + +<p>Sistem ini <em>tidak</em> membuat thread terpisah untuk setiap instance komponen. Semua +komponen yang berjalan di proses yang sama akan dibuat instance-nya dalam thread UI, dan sistem akan memanggil +setiap komponen yang dikirim dari thread itu. Akibatnya, metode yang merespons callback sistem + (seperti {@link android.view.View#onKeyDown onKeyDown()} untuk melaporkan tindakan pengguna atau metode callback daur hidup) + selalu berjalan di thread UI proses.</p> + +<p>Misalnya saat pengguna menyentuh tombol pada layar, thread UI aplikasi akan mengirim kejadian +sentuh ke widget, yang selanjutnya menetapkan status ditekan dan mengirim permintaan yang tidak divalidasi ke +antrean kejadian. Thread UI akan menghapus antrean permintaan dan memberi tahu widget bahwa widget harus menggambar +dirinya sendiri.</p> + +<p>Saat aplikasi melakukan pekerjaan intensif sebagai respons terhadap interaksi pengguna, model +thread tunggal ini bisa menghasilkan kinerja yang buruk kecuali jika Anda mengimplementasikan aplikasi dengan benar. Khususnya jika + semua terjadi di thread UI, melakukan operasi yang panjang seperti akses ke jaringan atau query +database akan memblokir seluruh UI. Bila thread diblokir, tidak ada kejadian yang bisa dikirim, +termasuk kejadian menggambar. Dari sudut pandang pengguna, aplikasi +tampak mogok (hang). Lebih buruk lagi, jika thread UI diblokir selama lebih dari beberapa detik +(saat ini sekitar 5 detik) pengguna akan ditampilkan dialog "<a href="http://developer.android.com/guide/practices/responsiveness.html">aplikasi tidak +merespons</a>" (ANR) yang populer karena reputasi buruknya. Pengguna nanti bisa memutuskan untuk keluar dari aplikasi dan menghapus aplikasi +jika mereka tidak suka.</p> + +<p>Selain itu, toolkit Android UI <em>bukan</em> thread-safe. Jadi, Anda tidak harus memanipulasi +UI dari thread pekerja—Anda harus melakukan semua manipulasi pada antarmuka pengguna dari thread +UI. Sehingga hanya ada dua aturan untuk model thread tunggal Android:</p> + +<ol> +<li>Jangan memblokir thread UI +<li>Jangan mengakses toolkit Android UI dari luar thread UI +</ol> + +<h3 id="WorkerThreads">Thread pekerja</h3> + +<p>Karena model thread tunggal yang dijelaskan di atas, Anda dilarang memblokir thread +UI demi daya respons UI aplikasi. Jika memiliki operasi untuk dijalankan +yang tidak seketika, Anda harus memastikan untuk melakukannya di thread terpisah (thread "latar belakang" atau +thread "pekerja").</p> + +<p>Misalnya, berikut ini beberapa kode untuk listener klik yang mengunduh gambar dari +thread terpisah dan menampilkannya dalam {@link android.widget.ImageView}:</p> + +<pre> +public void onClick(View v) { + new Thread(new Runnable() { + public void run() { + Bitmap b = loadImageFromNetwork("http://example.com/image.png"); + mImageView.setImageBitmap(b); + } + }).start(); +} +</pre> + +<p>Awalnya hal ini tampak bekerja dengan baik, karena menciptakan thread baru untuk menangani +operasi jaringan. Akan tetapi, hal tersebut melanggar aturan kedua model thread tunggal: <em>jangan mengakses + toolkit Android UI dari luar thread UI</em>—sampel ini memodifikasi {@link +android.widget.ImageView} dari thread pekerja sebagai ganti thread UI. Ini bisa +mengakibatkan perilaku yang tidak terdefinisi dan tidak diharapkan, yang bisa menyulitkan dan menghabiskan waktu untuk melacaknya.</p> + +<p>Untuk memperbaiki masalah ini, Android menawarkan beberapa cara untuk mengakses thread UI dari +thread lainnya. Berikut ini daftar metode yang bisa membantu:</p> + +<ul> +<li>{@link android.app.Activity#runOnUiThread(java.lang.Runnable) +Activity.runOnUiThread(Runnable)}</li> +<li>{@link android.view.View#post(java.lang.Runnable) View.post(Runnable)}</li> +<li>{@link android.view.View#postDelayed(java.lang.Runnable, long) View.postDelayed(Runnable, +long)}</li> +</ul> + +<p>Misalnya, Anda bisa memperbaiki kode di atas dengan menggunakan metode {@link +android.view.View#post(java.lang.Runnable) View.post(Runnable)}:</p> + +<pre> +public void onClick(View v) { + new Thread(new Runnable() { + public void run() { + final Bitmap bitmap = loadImageFromNetwork("http://example.com/image.png"); + mImageView.post(new Runnable() { + public void run() { + mImageView.setImageBitmap(bitmap); + } + }); + } + }).start(); +} +</pre> + +<p>Kini implementasi ini thread-safe: operasi jaringan dilakukan terpisah dari thread + sementara {@link android.widget.ImageView} dimanipulasi dari thread UI.</p> + +<p>Akan tetapi, karena operasi semakin kompleks, jenis kode seperti ini bisa semakin rumit +dan sulit dipertahankan. Untuk menangani interaksi yang lebih kompleks dengan thread pekerja, Anda bisa mempertimbangkan + penggunaan {@link android.os.Handler}di thread pekerja, untuk memproses pesan yang dikirim dari + thread UI. Mungkin solusi terbaiknya adalah memperpanjang kelas {@link android.os.AsyncTask}, +yang akan menyederhanakan eksekusi tugas-tugas thread pekerja yang perlu berinteraksi dengan UI.</p> + + +<h4 id="AsyncTask">Menggunakan AsyncTask</h4> + +<p>Dengan {@link android.os.AsyncTask}, Anda bisa melakukan pekerjaan asinkron pada antarmuka +pengguna. AsyncTask memblokir operasi di thread pekerja kemudian mempublikasikan hasilnya +di thread UI, tanpa mengharuskan Anda untuk menangani sendiri thread dan/atau handler sendiri.</p> + +<p>Untuk menggunakannya, Anda harus menempatkan {@link android.os.AsyncTask} sebagai subkelas dan mengimplementasikan metode callback {@link +android.os.AsyncTask#doInBackground doInBackground()} yang berjalan di kumpulan +thread latar belakang. Untuk memperbarui UI, Anda harus mengimplementasikan {@link +android.os.AsyncTask#onPostExecute onPostExecute()}, yang memberikan hasil dari {@link +android.os.AsyncTask#doInBackground doInBackground()} dan berjalan di thread UI, jadi Anda bisa +memperbarui UI dengan aman. Selanjutnya Anda bisa menjalankan tugas dengan memanggil {@link android.os.AsyncTask#execute execute()} +dari thread UI.</p> + +<p>Misalnya, Anda bisa mengimplementasikan contoh sebelumnya menggunakan {@link android.os.AsyncTask} dengan cara +ini:</p> + +<pre> +public void onClick(View v) { + new DownloadImageTask().execute("http://example.com/image.png"); +} + +private class DownloadImageTask extends AsyncTask<String, Void, Bitmap> { + /** The system calls this to perform work in a worker thread and + * delivers it the parameters given to AsyncTask.execute() */ + protected Bitmap doInBackground(String... urls) { + return loadImageFromNetwork(urls[0]); + } + + /** The system calls this to perform work in the UI thread and delivers + * the result from doInBackground() */ + protected void onPostExecute(Bitmap result) { + mImageView.setImageBitmap(result); + } +} +</pre> + +<p>Kini UI aman dan kode jadi lebih sederhana, karena memisahkan pekerjaan ke +dalam bagian-bagian yang harus dilakukan pada thread pekerja dan thread UI.</p> + +<p>Anda harus membaca acuan {@link android.os.AsyncTask} untuk memahami sepenuhnya +cara menggunakan kelas ini, namun berikut ini ikhtisar singkat cara kerjanya:</p> + +<ul> +<li>Anda bisa menetapkan tipe parameter, nilai kemajuan, dan nilai + akhir tugas, dengan menggunakan generik</li> +<li>Metode {@link android.os.AsyncTask#doInBackground doInBackground()} berjalan secara otomatis pada +thread pekerja</li> +<li>{@link android.os.AsyncTask#onPreExecute onPreExecute()}, {@link +android.os.AsyncTask#onPostExecute onPostExecute()}, dan {@link +android.os.AsyncTask#onProgressUpdate onProgressUpdate()} semuanya dipanggil pada thread UI</li> +<li>Nilai yang dikembalikan oleh {@link android.os.AsyncTask#doInBackground doInBackground()} akan dikirim ke +{@link android.os.AsyncTask#onPostExecute onPostExecute()}</li> +<li>Anda bisa memangil {@link android.os.AsyncTask#publishProgress publishProgress()} setiap saat di {@link +android.os.AsyncTask#doInBackground doInBackground()} untuk mengeksekusi {@link +android.os.AsyncTask#onProgressUpdate onProgressUpdate()} pada thread UI</li> +<li>Anda bisa membatalkan tugas ini kapan saja, dari thread mana saja</li> +</ul> + +<p class="caution"><strong>Perhatian:</strong> Masalah lain yang mungkin Anda temui saat menggunakan +thread pekerja adalah restart tak terduga dalam aktivitas karena <a href="{@docRoot}guide/topics/resources/runtime-changes.html">perubahan konfigurasi runtime</a> + (seperti saat pengguna mengubah orientasi layar), yang bisa memusnahkan thread pekerja. Untuk +melihat cara mempertahankan tugas selama restart ini dan cara membatalkan +tugas dengan benar saat aktivitas dimusnahkan, lihat kode sumber untuk aplikasi sampel <a href="http://code.google.com/p/shelves/">Shelves</a>.</p> + + +<h3 id="ThreadSafe">Metode thread-safe</h3> + +<p> Dalam beberapa situasi, metode yang Anda implementasikan bisa dipanggil dari lebih dari satu thread, +dan karena itu harus ditulis agar menjadi thread-safe. </p> + +<p>Ini terutama terjadi untuk metode yang bisa dipanggil dari jauh —seperti metode dalam <a href="{@docRoot}guide/components/bound-services.html">layanan terikat</a>. Bila sebuah panggilan pada +metode yang dijalankan dalam {@link android.os.IBinder} berasal dari proses yang sama di mana +{@link android.os.IBinder IBinder} berjalan, metode ini akan dieksekusi di thread pemanggil. +Akan tetapi, bila panggilan berasal proses lain, metode akan dieksekusi dalam thread yang dipilih dari + kumpulan (pool) thread yang dipertahankan sistem dalam proses yang sama seperti{@link android.os.IBinder +IBinder} (tidak dieksekusi dalam thread UI proses). Misalnya, karena metode +{@link android.app.Service#onBind onBind()} layanan akan dipanggil dari thread UI +proses layanan, metode yang diimplementasikan dalam objek yang dikembalikan {@link android.app.Service#onBind +onBind()} (misalnya, subkelas yang mengimplementasikan metode RPC) akan dipanggil dari thread +di pool. Karena layanan bisa memiliki lebih dari satu klien, maka lebih dari satu pool thread bisa melibatkan + metode {@link android.os.IBinder IBinder} yang sama sekaligus. Metode {@link android.os.IBinder +IBinder} karenanya harus diimplementasikan sebagai thread-safe.</p> + +<p> Penyedia konten juga bisa menerima permintaan data yang berasal dalam proses lain. +Meskipun kelas {@link android.content.ContentResolver} dan {@link android.content.ContentProvider} + menyembunyikan detail cara komunikasi antarproses dikelola, metode {@link +android.content.ContentProvider} yang merespons permintaan itu—metode {@link +android.content.ContentProvider#query query()}, {@link android.content.ContentProvider#insert +insert()}, {@link android.content.ContentProvider#delete delete()}, {@link +android.content.ContentProvider#update update()}, dan {@link android.content.ContentProvider#getType +getType()}— dipanggil dari pool thread pada proses penyedia konten, bukan thread UI +untuk proses tersebut. Mengingat metode ini bisa dipanggil dari thread mana pun +sekaligus, metode-metode ini juga harus diimplementasikan sebagai thread-safe. </p> + + +<h2 id="IPC">Komunikasi Antarproses</h2> + +<p>Android menawarkan mekanisme komunikasi antarproses (IPC) menggunakan panggilan prosedur jauh + (RPC), yang mana metode ini dipanggil oleh aktivitas atau komponen aplikasi lain, namun dieksekusi dari +jauh (di proses lain), bersama hasil yang dikembalikan ke +pemanggil. Ini mengharuskan penguraian panggilan metode dan datanya ke tingkat yang bisa +dipahami sistem operasi, mentransmisikannya dari proses lokal dan ruang alamat untuk proses jauh +dan ruang proses, kemudian merakit kembali dan menetapkannya kembali di sana. Nilai-nilai yang dikembalikan +akan ditransmisikan dalam arah berlawanan. Android menyediakan semua kode untuk melakukan transaksi IPC + ini, sehingga Anda bisa fokus pada pendefinisian dan implementasi antarmuka pemrograman RPC. </p> + +<p>Untuk melakukan IPC, aplikasi Anda harus diikat ke layanan, dengan menggunakan {@link +android.content.Context#bindService bindService()}. Untuk informasi selengkapnya, lihat panduan pengembang <a href="{@docRoot}guide/components/services.html">Layanan</a>.</p> + + +<!-- +<h2>Beginner's Path</h2> + +<p>For information about how to perform work in the background for an indefinite period of time +(without a user interface), continue with the <b><a +href="{@docRoot}guide/components/services.html">Services</a></b> document.</p> +--> diff --git a/docs/html-intl/intl/in/guide/components/recents.jd b/docs/html-intl/intl/in/guide/components/recents.jd new file mode 100644 index 000000000000..dcfcda7a7d5f --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/recents.jd @@ -0,0 +1,256 @@ +page.title=Layar Ikhtisar +page.tags="recents","overview" + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#adding">Menambahkan Tugas ke Layar Ikhtisar</a> + <ol> + <li><a href="#flag-new-doc">Menggunakan flag Intent untuk menambahkan tugas</a></li> + <li><a href="#attr-doclaunch">Menggunakan atribut Aktivitas untuk menambahkan tugas</a></li> + </ol> + </li> + <li><a href="#removing">Menghapus Tugas</a> + <ol> + <li><a href="#apptask-remove">Menggunakan kelas AppTask untuk menghapus tugas</a></li> + <li><a href="#retain-finished">Mempertahankan tugas yang telah selesai</a></li> + </ol> + </li> + </ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.app.ActivityManager.AppTask}</li> + <li>{@link android.content.Intent}</li> + </ol> + + <h2>Kode contoh</h2> + <ol> + <li><a href="{@docRoot}samples/DocumentCentricApps/index.html">Aplikasi yang berorientasi dokumen</a></li> + </ol> + +</div> +</div> + +<p>Layar ikhtisar (juga disebut sebagai layar terbaru, daftar tugas terbaru, atau aplikasi terbaru) +UI tingkat sistem yang mencantumkan <a href="{@docRoot}guide/components/activities.html"> +aktivitas</a> dan <a href="{@docRoot}guide/components/tasks-and-back-stack.html">tugas</a> yang baru saja diakses. Pengguna +bisa menyusuri daftar ini dan memilih satu tugas untuk dilanjutkan, atau pengguna bisa menghapus tugas dari +daftar dengan gerakan mengusap. Dengan dirilisnya Android 5.0 (API level 21), beberapa instance aktivitas yang +sama yang berisi dokumen berbeda dapat muncul sebagai tugas di layar ikhtisar. Misalnya, +Google Drive mungkin memiliki satu tugas untuk setiap beberapa dokumen Google. Setiap dokumen muncul sebagai +tugas dalam layar ikhtisar.</p> + +<img src="{@docRoot}images/components/recents.png" alt="" width="284" /> +<p class="img-caption"><strong>Gambar 1.</strong> Layar ikhtisar menampilkan tiga dokumen +Google Drive, masing-masing dinyatakan sebagai tugas terpisah.</p> + +<p>Biasanya Anda harus mengizinkan sistem mendefinisikan cara menyatakan tugas dan +aktivitas di layar ikhtisar, dan Anda tidak perlu memodifikasi perilaku ini. +Akan tetapi, aplikasi Anda dapat menentukan cara dan waktu munculnya aktivitas di layar ikhtisar. Kelas +{@link android.app.ActivityManager.AppTask} memungkinkan Anda mengelola tugas, dan flag + aktivitas kelas {@link android.content.Intent} memungkinkan Anda menentukan kapan aktivitas ditambahkan atau dihapus dari +layar ikhtisar. Selain itu, atribut <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"> +<activity></a></code> memungkinkan Anda menetapkan perilaku di manifes.</p> + +<h2 id="adding">Menambahkan Tugas ke Layar Ikhtisar</h2> + +<p>Penggunaan flag kelas {@link android.content.Intent} untuk menambahkan tugas memberi kontrol lebih besar +atas waktu dan cara dokumen dibuka atau dibuka kembali di layar ikhtisar. Bila menggunakan atribut +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +, Anda dapat memilih antara selalu membuka dokumen dalam tugas baru atau menggunakan kembali tugas +yang ada untuk dokumen tersebut.</p> + +<h3 id="flag-new-doc">Menggunakan flag Intent untuk menambahkan tugas</h3> + +<p>Bila membuat dokumen baru untuk aktivitas, Anda memanggil metode +{@link android.app.ActivityManager.AppTask#startActivity(android.content.Context, android.content.Intent, android.os.Bundle) startActivity()} + dari kelas {@link android.app.ActivityManager.AppTask}, dengan meneruskannya ke intent yang +menjalankan aktivitas tersebut. Untuk menyisipkan jeda logis agar sistem memperlakukan aktivitas Anda sebagai tugas +baru di layar ikhtisar, teruskan flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} +dalam metode {@link android.content.Intent#addFlags(int) addFlags()} dari {@link android.content.Intent} +yang memulai aktivitas itu.</p> + +<p class="note"><strong>Catatan:</strong> Flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} +menggantikan flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}, +yang tidak digunakan lagi pada Android 5.0 (API level 21).</p> + +<p>Jika Anda menetapkan flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} saat membuat +dokumen baru, sistem akan selalu membuat tugas baru dengan aktivitas target sebagai akar. +Dengan pengaturan ini, dokumen yang sama dapat dibuka di lebih dari satu tugas. Kode berikut memperagakan +cara aktivitas utama melakukannya:</p> + +<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> +DocumentCentricActivity.java</a></p> +<pre> +public void createNewDocument(View view) { + final Intent newDocumentIntent = newDocumentIntent(); + if (useMultipleTasks) { + newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_MULTIPLE_TASK); + } + startActivity(newDocumentIntent); + } + + private Intent newDocumentIntent() { + boolean useMultipleTasks = mCheckbox.isChecked(); + final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class); + newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT); + newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet()); + return newDocumentIntent; + } + + private static int incrementAndGet() { + Log.d(TAG, "incrementAndGet(): " + mDocumentCounter); + return mDocumentCounter++; + } +} +</pre> + +<p class="note"><strong>Catatan:</strong> Aktivitas yang dimulai dengan flag {@code FLAG_ACTIVITY_NEW_DOCUMENT} + harus telah menetapkan nilai atribut {@code android:launchMode="standard"} (default) dalam +manifes.</p> + +<p>Bila aktivitas utama memulai aktivitas baru, sistem akan mencari tugas yang intent +-nya cocok dengan nama komponen intent dalam tugas-tugas yang sudah ada dan mencari aktivitas dalam data Intent. Jika tugas +tidak ditemukan, atau intent ada dalam flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK} +, tugas baru akan dibuat dengan aktivitas tersebut sebagai akarnya. Jika ditemukan, sistem akan +mengedepankan tugas itu dan meneruskan intent baru ke {@link android.app.Activity#onNewIntent onNewIntent()}. +Aktivitas baru akan mendapatkan intent dan membuat dokumen baru di layar ikhtisar, seperti dalam +contoh berikut:</p> + +<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> +NewDocumentActivity.java</a></p> +<pre> +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_new_document); + mDocumentCount = getIntent() + .getIntExtra(DocumentCentricActivity.KEY_EXTRA_NEW_DOCUMENT_COUNTER, 0); + mDocumentCounterTextView = (TextView) findViewById( + R.id.hello_new_document_text_view); + setDocumentCounterText(R.string.hello_new_document_counter); +} + +@Override +protected void onNewIntent(Intent intent) { + super.onNewIntent(intent); + /* If FLAG_ACTIVITY_MULTIPLE_TASK has not been used, this activity + is reused to create a new document. + */ + setDocumentCounterText(R.string.reusing_document_counter); +} +</pre> + + +<h3 id="#attr-doclaunch">Menggunakan atribut Aktivitas untuk menambahkan tugas</h3> + +<p>Aktivitas juga dapat menetapkan dalam manifesnya agar selalu dimulai ke dalam tugas baru dengan menggunakan +atribut <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +, <a href="{@docRoot}guide/topics/manifest/activity-element.html#dlmode"> +{@code android:documentLaunchMode}</a>. Atribut ini memiliki empat nilai yang menghasilkan efek berikut +bila pengguna membuka dokumen dengan aplikasi:</p> + +<dl> + <dt>"{@code intoExisting}"</dt> + <dd>Aktivitas menggunakan kembali tugas yang ada untuk dokumen tersebut. Ini sama dengan mengatur flag + {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} <em>tanpa</em> mengatur flag + {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}, seperti dijelaskan dalam + <a href="#flag-new-doc">Menggunakan flag Intent untuk menambahkan tugas</a>, di atas.</dd> + + <dt>"{@code always}"</dt> + <dd>Aktivitas ini membuat tugas baru untuk dokumen, meski dokumen sudah dibuka. Menggunakan + nilai ini sama dengan menetapkan flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} + maupun {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}.</dd> + + <dt>"{@code none”}"</dt> + <dd>Aktivitas ini tidak membuat tugas baru untuk dokumen. Layar ikhtisar memperlakukan + aktivitas seperti itu secara default: satu tugas ditampilkan untuk aplikasi, yang +dilanjutkan dari aktivitas apa pun yang terakhir dipanggil pengguna.</dd> + + <dt>"{@code never}"</dt> + <dd>Aktivitas ini tidak membuat tugas baru untuk dokumen. Mengatur nilai ini akan mengesampingkan + perilaku flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_DOCUMENT} + dan {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}, jika salah satunya ditetapkan di +intent, dan layar ikhtisar menampilkan satu tugas untuk aplikasi, yang dilanjutkan dari + aktivitas apa pun yang terakhir dipanggil pengguna.</dd> +</dl> + +<p class="note"><strong>Catatan:</strong> Untuk nilai selain {@code none} dan {@code never}, +aktivitas harus didefinisikan dengan {@code launchMode="standard"}. Jika atribut ini tidak ditetapkan, maka +{@code documentLaunchMode="none"} akan digunakan.</p> + +<h2 id="removing">Menghapus Tugas</h2> + +<p>Secara default, tugas dokumen secara otomatis dihapus dari layar ikhtisar bila aktivitasnya +selesai. Anda bisa mengesampingkan perilaku ini dengan kelas {@link android.app.ActivityManager.AppTask}, +dengan flag {@link android.content.Intent} atau atribut <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"> +<activity></a></code>.</p> + +<p>Kapan saja Anda bisa mengecualikan tugas dari layar ikhtisar secara keseluruhan dengan menetapkan atribut +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +, <a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude"> +{@code android:excludeFromRecents}</a> hingga {@code true}.</p> + +<p>Anda bisa menetapkan jumlah maksimum tugas yang dapat disertakan aplikasi Anda dalam layar ikhtisar dengan menetapkan +atribut <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + <a href="{@docRoot}guide/topics/manifest/activity-element.html#maxrecents">{@code android:maxRecents} +</a> ke satu nilai integer. Nilai default-nya adalah 16. Bila telah mencapai jumlah maksimum, tugas yang terakhir +digunakan akan dihapus dari layar ikhtisar. Nilai maksimum {@code android:maxRecents} + adalah 50 (25 pada perangkat dengan memori sedikit); nilai yang kurang dari 1 tidak berlaku.</p> + +<h3 id="#apptask-remove">Menggunakan kelas AppTask untuk menghapus tugas</h3> + +<p>Dalam aktivitas yang membuat tugas baru di layar ikhtisar, Anda bisa +menetapkan kapan menghapus tugas dan menyelesaikan semua aktivitas yang terkait dengannya +dengan memanggil metode {@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()}.</p> + +<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> +NewDocumentActivity.java</a></p> +<pre> +public void onRemoveFromRecents(View view) { + // The document is no longer needed; remove its task. + finishAndRemoveTask(); +} +</pre> + +<p class="note"><strong>Catatan:</strong> Penggunaan metode +{@link android.app.ActivityManager.AppTask#finishAndRemoveTask() finishAndRemoveTask()} +akan mengesampingkan penggunaan tag {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS}, seperti +dibahas di bawah ini.</p> + +<h3 id="#retain-finished">Mempertahankan tugas yang telah selesai</h3> + +<p>Jika Anda ingin mempertahankan tugas di layar ikhtisar, sekalipun aktivitas sudah selesai, teruskan +flag {@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS} dalam metode +{@link android.content.Intent#addFlags(int) addFlags()} dari Intent yang memulai aktivitas itu.</p> + +<p class="code-caption"><a href="{@docRoot}samples/DocumentCentricApps/index.html"> +DocumentCentricActivity.java</a></p> +<pre> +private Intent newDocumentIntent() { + final Intent newDocumentIntent = new Intent(this, NewDocumentActivity.class); + newDocumentIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT | + android.content.Intent.FLAG_ACTIVITY_RETAIN_IN_RECENTS); + newDocumentIntent.putExtra(KEY_EXTRA_NEW_DOCUMENT_COUNTER, incrementAndGet()); + return newDocumentIntent; +} +</pre> + +<p>Untuk memperoleh efek yang sama, tetapkan atribut +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + <a href="{@docRoot}guide/topics/manifest/activity-element.html#autoremrecents"> +{@code android:autoRemoveFromRecents}</a> hingga {@code false}. Nilai default-nya adalah {@code true} +untuk aktivitas dokumen, dan {@code false} untuk aktivitas biasa. Penggunaan atribut ini akan mengesampingkan flag +{@link android.content.Intent#FLAG_ACTIVITY_RETAIN_IN_RECENTS}, yang telah dibahas sebelumnya.</p> + + + + + + + diff --git a/docs/html-intl/intl/in/guide/components/services.jd b/docs/html-intl/intl/in/guide/components/services.jd new file mode 100644 index 000000000000..7ecd8cd38db9 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/services.jd @@ -0,0 +1,813 @@ +page.title=Layanan +@jd:body + +<div id="qv-wrapper"> +<ol id="qv"> +<h2>Dalam dokumen ini</h2> +<ol> +<li><a href="#Basics">Dasar-Dasar</a></li> +<ol> + <li><a href="#Declaring">Mendeklarasikan layanan dalam manifes</a></li> +</ol> +<li><a href="#CreatingAService">Membuat Layanan yang Sudah Dimulai</a> + <ol> + <li><a href="#ExtendingIntentService">Memperluas kelas IntentService</a></li> + <li><a href="#ExtendingService">Memperluas kelas Layanan</a></li> + <li><a href="#StartingAService">Memulai layanan</a></li> + <li><a href="#Stopping">Menghentikan layanan</a></li> + </ol> +</li> +<li><a href="#CreatingBoundService">Membuat Layanan Terikat</a></li> +<li><a href="#Notifications">Mengirim Pemberitahuan ke Pengguna</a></li> +<li><a href="#Foreground">Menjalankan Layanan di Latar Depan</a></li> +<li><a href="#Lifecycle">Mengelola Daur Hidup Layanan</a> +<ol> + <li><a href="#LifecycleCallbacks">Mengimplementasikan callback daur hidup</a></li> +</ol> +</li> +</ol> + +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.app.Service}</li> + <li>{@link android.app.IntentService}</li> +</ol> + +<h2>Contoh</h2> +<ol> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ServiceStartArguments.html">{@code + ServiceStartArguments}</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code + LocalService}</a></li> +</ol> + +<h2>Lihat juga</h2> +<ol> +<li><a href="{@docRoot}guide/components/bound-services.html">Layanan Terikat</a></li> +</ol> + +</div> + + +<p>{@link android.app.Service} adalah sebuah komponen aplikasi yang bisa melakukan +operasi yang berjalan lama di latar belakang dan tidak menyediakan antarmuka pengguna. Komponen +aplikasi lain bisa memulai layanan dan komponen aplikasi tersebut akan terus berjalan +di latar belakang walaupun pengguna beralih ke aplikasi lain. Selain itu, komponen bisa mengikat ke layanan +untuk berinteraksi dengannya dan bahkan melakukan komunikasi antarproses (IPC). Misalnya, layanan mungkin +menangani transaksi jaringan, memutar musik, melakukan file I/O, atau berinteraksi dengan penyedia konten +dari latar belakang.</p> + +<p>Ada dua bentuk dasar layanan:</p> + +<dl> + <dt>Sudah Dimulai</dt> + <dd>Layanan "sudah dimulai" bila komponen aplikasi (misalnya aktivitas) memulainya dengan +memanggil {@link android.content.Context#startService startService()}. Sesudah dimulai, layanan +bisa berjalan terus-menerus di latar belakang walaupun komponen yang memulainya telah dimusnahkan. Biasanya, +layanan yang sudah dimulai akan melakukan operasi tunggal dan tidak mengembalikan hasil ke pemanggilnya. +Misalnya, layanan bisa mengunduh atau mengunggah file melalui jaringan. Bila operasi selesai, +layanan seharusnya berhenti sendiri.</dd> + <dt>Terikat</dt> + <dd>Layanan "terikat" bila komponen aplikasi mengikat kepadanya dengan memanggil {@link +android.content.Context#bindService bindService()}. Layanan terikat menawarkan antarmuka +klien-server yang memungkinkan komponen berinteraksi dengan layanan tersebut, mengirim permintaan, mendapatkan hasil dan bahkan +melakukannya pada sejumlah proses dengan komunikasi antarproses (IPC). Layanan terikat hanya berjalan selama +ada komponen aplikasi lain yang terikat padanya. Sejumlah komponen bisa terikat pada layanan secara bersamaan, +namun bila semuanya melepas ikatan, layanan tersebut akan dimusnahkan.</dd> +</dl> + +<p>Walaupun dokumentasi ini secara umum membahas kedua jenis layanan secara terpisah, layanan +Anda bisa menggunakan keduanya—layanan bisa dimulai (untuk berjalan terus-menerus) sekaligus memungkinkan pengikatan. +Cukup mengimplementasikan dua metode callback: {@link +android.app.Service#onStartCommand onStartCommand()} untuk memungkinkan komponen memulainya dan {@link +android.app.Service#onBind onBind()} untuk memungkinkan pengikatan.</p> + +<p>Apakah aplikasi Anda sudah dimulai, terikat, atau keduanya, semua komponen aplikasi +bisa menggunakan layanan (bahkan dari aplikasi terpisah), demikian pula semua komponen bisa menggunakan +suatu aktivitas—dengan memulainya dengan {@link android.content.Intent}. Akan tetapi, Anda bisa mendeklarasikan +layanan sebagai privat, pada file manifes, dan memblokir akses dari aplikasi lain. Hal ini +dibahas selengkapnya di bagian tentang <a href="#Declaring">Mendeklarasikan layanan dalam +manifes</a>.</p> + +<p class="caution"><strong>Perhatian:</strong> Layanan berjalan di +thread utama proses yang menjadi host-nya—layanan <strong>tidak</strong> membuat thread-nya sendiri +dan <strong>tidak</strong> berjalan pada proses terpisah (kecuali bila Anda tentukan demikian). Artinya, +jika layanan Anda akan melakukan pekerjaan yang membutuhkan tenaga CPU besar atau operasi yang memblokir (seperti +pemutaran MP3 atau jaringan), Anda perlu membuat thread baru dalam layanan untuk melakukan pekerjaan tersebut. Dengan menggunakan +thread terpisah, Anda mengurangi risiko terjadinya kesalahan Aplikasi Tidak Merespons (Application Not Responding/ANR) dan +thread utama aplikasi bisa tetap dikhususkan pada interaksi pengguna dengan aktivitas Anda.</p> + + +<h2 id="Basics">Dasar-Dasar</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Haruskah menggunakan layanan atau thread?</h3> + <p>Layanan sekadar komponen yang bisa berjalan di latar belakang walaupun pengguna sedang tidak +berinteraksi dengan aplikasi Anda. Sehingga, Anda harus membuat layanan bila memang itu +yang dibutuhkan.</p> + <p>Bila Anda perlu melakukan pekerjaan di luar thread utama, namun hanya bila pengguna sedang berinteraksi +dengan aplikasi, maka Anda harus membuat thread baru sebagai ganti layanan baru. Misalnya, +bila Anda ingin memutar musik, namun hanya saat aktivitas Anda berjalan, Anda bisa membuat +thread dalam {@link android.app.Activity#onCreate onCreate()}, mulai menjalankannya di {@link +android.app.Activity#onStart onStart()}, kemudian menghentikannya di {@link android.app.Activity#onStop +onStop()}. Pertimbangkan juga untuk menggunakan {@link android.os.AsyncTask} atau {@link android.os.HandlerThread}, +sebagai ganti kelas {@link java.lang.Thread} yang lazim digunakan. Lihat dokumen <a href="{@docRoot}guide/components/processes-and-threads.html#Threads">Proses dan +Threading</a> untuk informasi selengkapnya tentang thread.</p> + <p>Ingatlah jika menggunakan layanan, layanan tersebut tetap berjalan di thread utama aplikasi Anda secara +default, jadi Anda harus tetap membuat thread baru dalam layanan bila layanan tersebut melakukan operasi yang intensif +atau operasi yang memblokir.</p> +</div> +</div> + +<p>Untuk membuat layanan, Anda harus membuat subkelas {@link android.app.Service} (atau +salah satu dari subkelasnya yang ada). Dalam implementasi, Anda perlu mengesampingkan sebagian metode callback yang +menangani aspek utama daur hidup layanan dan memberikan mekanisme bagi komponen untuk mengikat +pada layanan, bila dibutuhkan. Metode callback terpenting yang perlu Anda kesampingkan adalah:</p> + +<dl> + <dt>{@link android.app.Service#onStartCommand onStartCommand()}</dt> + <dd>Sistem akan memanggil metode ini bila komponen lain, misalnya aktivitas, +meminta dimulainya layanan, dengan memanggil {@link android.content.Context#startService +startService()}. Setelah metode ini dieksekusi, layanan akan dimulai dan bisa berjalan di +latar belakang terus-menerus. Jika mengimplementasikan ini, Anda bertanggung jawab menghentikan layanan bila +bila pekerjaannya selesai, dengan memanggil {@link android.app.Service#stopSelf stopSelf()} atau {@link +android.content.Context#stopService stopService()}. (Jika hanya ingin menyediakan pengikatan, Anda tidak +perlu mengimplementasikan metode ini.)</dd> + <dt>{@link android.app.Service#onBind onBind()}</dt> + <dd>Sistem akan memanggil metode ini bila komponen lain ingin mengikat pada +layanan (misalnya untuk melakukan RPC), dengan memanggil {@link android.content.Context#bindService +bindService()}. Dalam mengimplementasikan metode ini, Anda harus menyediakan antarmuka yang digunakan +klien untuk berkomunikasi dengan layanan, dengan mengembalikan {@link android.os.IBinder}. Anda harus selalu +mengimplementasikan metode ini, namun jika tidak ingin mengizinkan pengikatan, Anda perlu mengembalikan null.</dd> + <dt>{@link android.app.Service#onCreate()}</dt> + <dd>Sistem memanggil metode ini bila layanan dibuat untuk pertama kalinya, untuk melakukan prosedur +penyiapan satu kali (sebelum memanggil {@link android.app.Service#onStartCommand onStartCommand()} atau +{@link android.app.Service#onBind onBind()}). Bila layanan sudah berjalan, metode ini tidak +dipanggil.</dd> + <dt>{@link android.app.Service#onDestroy()}</dt> + <dd>Sistem memanggil metode ini bila layanan tidak lagi digunakan dan sedang dimusnahkan. +Layanan Anda perlu mengimplementasikannya untuk membersihkan sumber daya seperti thread, listener +terdaftar, penerima, dll. Ini adalah panggilan terakhir yang diterima layanan.</dd> +</dl> + +<p>Bila komponen memulai layanan dengan memanggil {@link +android.content.Context#startService startService()} (yang menyebabkan panggilan ke {@link +android.app.Service#onStartCommand onStartCommand()}), maka layanan +terus berjalan hingga terhenti sendiri dengan {@link android.app.Service#stopSelf()} atau bila komponen +lain menghentikannya dengan memanggil {@link android.content.Context#stopService stopService()}.</p> + +<p>Bila komponen memanggil +{@link android.content.Context#bindService bindService()} untuk membuat layanan (dan {@link +android.app.Service#onStartCommand onStartCommand()} <em>tidak</em> dipanggil), maka layanan hanya berjalan +selama komponen terikat kepadanya. Setelah layanan dilepas ikatannya dari semua klien, +sistem akan menghancurkannya.</p> + +<p>Sistem Android akan menghentikan paksa layanan hanya bila memori tinggal sedikit dan sistem harus memulihkan +sumber daya sistem untuk aktivitas yang mendapatkan fokus pengguna. Jika layanan terikat pada suatu aktivitas yang mendapatkan +fokus pengguna, layanan tersebut lebih kecil kemungkinannya untuk dimatikan, dan jika layanan dideklarasikan untuk <a href="#Foreground">berjalan di latar depan</a> (akan dibahas kemudian), maka sudah hampir pasti ia tidak akan dimatikan. +Sebaliknya, bila layanan sudah dimulai dan berjalan lama, maka sistem akan menurunkan posisinya +dalam daftar tugas latar belakang seiring waktu dan layanan akan sangat rentan untuk +dimatikan—bila layanan Anda dimulai, maka Anda harus mendesainnya agar bisa menangani restart +oleh sistem dengan baik. Jika sistem mematikan layanan Anda, layanan akan dimulai kembali begitu sumber daya +kembali tersedia (tetapi ini juga bergantung pada nilai yang Anda kembalikan dari {@link +android.app.Service#onStartCommand onStartCommand()}, sebagaimana akan dibahas nanti). Untuk informasi selengkapnya +tentang kapan sistem mungkin akan memusnahkan layanan, lihat dokumen +<a href="{@docRoot}guide/components/processes-and-threads.html">Proses dan Threading</a>.</p> + +<p>Dalam bagian selanjutnya, Anda akan melihat bagaimana membuat masing-masing tipe layanan dan cara menggunakannya +dari komponen aplikasi lain.</p> + + + +<h3 id="Declaring">Mendeklarasikan layanan dalam manifes</h3> + +<p>Sebagaimana aktivitas (dan komponen lainnya), Anda harus mendeklarasikan semua layanan dalam file manifes +aplikasi Anda.</p> + +<p>Untuk mendeklarasikan layanan Anda, tambahkan sebuah elemen <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> +sebagai anak +elemen <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>. Misalnya:</p> + +<pre> +<manifest ... > + ... + <application ... > + <service android:name=".ExampleService" /> + ... + </application> +</manifest> +</pre> + +<p>Lihat acuan elemen <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> +untuk informasi selengkapnya tentang cara mendeklarasikan layanan Anda dalam manifes.</p> + +<p>Ada atribut lain yang bisa Anda sertakan dalam elemen <a href="{@docRoot}guide/topics/manifest/service-element.html">{@code <service>}</a> untuk +mendefinisikan properti seperti izin yang dibutuhkan untuk memulai layanan dan proses +tempat berjalannya layanan. <a href="{@docRoot}guide/topics/manifest/service-element.html#nm">{@code android:name}</a> adalah satu-satunya atribut yang diperlukan +—atribut tersebut menetapkan nama kelas layanan. Setelah +mempublikasikan aplikasi, Anda tidak boleh mengubah nama ini, karena jika melakukannya, Anda bisa merusak +kode karena dependensi terhadap intent eksplisit untuk memulai atau mengikat layanan (bacalah posting blog berjudul <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">Things +That Cannot Change</a>). + +<p>Untuk memastikan aplikasi Anda aman, <strong>selalu gunakan intent eksplisit saat memulai atau mengikat +{@link android.app.Service} Anda</strong> dan jangan mendeklarasikan filter intent untuk layanan. Jika +Anda perlu membiarkan adanya ambiguitas tentang layanan mana yang dimulai, Anda bisa +menyediakan filter intent bagi layanan dan tidak memasukkan nama komponen pada {@link +android.content.Intent}, namun Anda juga harus menyesuaikan paket bagi intent tersebut dengan {@link +android.content.Intent#setPackage setPackage()}, yang memberikan klarifikasi memadai bagi +target layanan.</p> + +<p>Anda juga bisa memastikan layanan tersedia hanya bagi aplikasi Anda dengan +menyertakan atribut <a href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> +dan mengaturnya ke {@code "false"}. Hal ini efektif menghentikan aplikasi lain agar tidak memulai +layanan Anda, bahkan saat menggunakan intent eksplisit.</p> + + + + +<h2 id="CreatingStartedService">Membuat Layanan yang Sudah Dimulai</h2> + +<p>Layanan yang sudah dimulai adalah layanan yang dimulai komponen lain dengan memanggil {@link +android.content.Context#startService startService()}, yang menyebabkan panggilan ke metode +{@link android.app.Service#onStartCommand onStartCommand()} layanan.</p> + +<p>Bila layanan sudah dimulai, layanan tersebut memiliki daur hidup yang tidak bergantung pada +komponen yang memulainya dan bisa berjalan terus-menerus di latar belakang walaupun +komponen yang memulainya dimusnahkan. Dengan sendirinya, layanan akan berhenti sendiri bila pekerjaannya +selesai dengan memanggil {@link android.app.Service#stopSelf stopSelf()}, atau komponen lain bisa menghentikannya +dengan memanggil {@link android.content.Context#stopService stopService()}.</p> + +<p>Komponen aplikasi seperti aktivitas bisa memulai layanan dengan memanggil {@link +android.content.Context#startService startService()} dan meneruskan {@link android.content.Intent} +yang menetapkan layanan dan menyertakan data untuk digunakan layanan. Layanan menerima +{@link android.content.Intent} ini dalam metode {@link android.app.Service#onStartCommand +onStartCommand()}.</p> + +<p>Sebagai contoh, anggaplah aktivitas perlu menyimpan data ke database online. Aktivitas tersebut bisa +memulai layanan pendamping dan mengiriminya data untuk disimpan dengan meneruskan intent ke {@link +android.content.Context#startService startService()}. Layanan akan menerima intent dalam {@link +android.app.Service#onStartCommand onStartCommand()}, menghubungkan ke Internet dan melakukan +transaksi database. Bila transaksi selesai, layanan akan berhenti sendiri dan +dimusnahkan.</p> + +<p class="caution"><strong>Perhatian:</strong> Layanan berjalan dalam proses yang sama dengan aplikasi +tempatnya dideklarasikan dan dalam thread utama aplikasi tersebut, secara default. Jadi, bila layanan Anda +melakukan operasi yang intensif atau operasi pemblokiran saat pengguna berinteraksi dengan aktivitas dari +aplikasi yang sama, layanan akan memperlambat kinerja aktivitas. Agar tidak memengaruhi +kinerja aplikasi, Anda harus memulai thread baru di dalam layanan.</p> + +<p>Biasanya, ada dua kelas yang bisa Anda perluas untuk membuat layanan yang sudah dimulai:</p> +<dl> + <dt>{@link android.app.Service}</dt> + <dd>Ini adalah kelas dasar untuk semua layanan. Bila memperluas kelas ini, Anda perlu +membuat thread baru sebagai tempat melaksanakan semua pekerjaan layanan tersebut, karena layanan +menggunakan thread utama aplikasi Anda secara default, dan hal ini bisa memperlambat +kinerja aktivitas yang dijalankan aplikasi Anda.</dd> + <dt>{@link android.app.IntentService}</dt> + <dd>Ini adalah subkelas {@link android.app.Service} yang menggunakan thread pekerja untuk menangani +semua permintaan memulai, satu per satu. Ini adalah pilihan terbaik jika Anda tidak mengharuskan layanan +menangani beberapa permintaan sekaligus. Anda cukup mengimplementasikan {@link +android.app.IntentService#onHandleIntent onHandleIntent()}, yang menerima intent untuk setiap +permintaan memulai agar bisa melakukan pekerjaan latar belakang.</dd> +</dl> + +<p>Bagian selanjutnya membahas cara mengimplementasikan layanan Anda menggunakan +salah satu dari kelas-kelas ini.</p> + + +<h3 id="ExtendingIntentService">Memperluas kelas IntentService</h3> + +<p>Mengingat kebanyakan layanan yang sudah dimulai tidak perlu menangani beberapa permintaan +sekaligus (yang bisa berupa skenario multi-threading berbahaya), mungkin Anda sebaiknya mengimplementasikan +layanan menggunakan kelas {@link android.app.IntentService}.</p> + +<p>Berikut ini yang dilakukan {@link android.app.IntentService}:</p> + +<ul> + <li>Membuat thread pekerja default yang menjalankan semua intent yang disampaikan ke {@link +android.app.Service#onStartCommand onStartCommand()} terpisah dari thread utama aplikasi +Anda.</li> + <li>Membuat antrean pekerjaan yang meneruskan intent satu per satu ke implementasi {@link +android.app.IntentService#onHandleIntent onHandleIntent()}, sehingga Anda tidak perlu +mengkhawatirkan multi-threading.</li> + <li>Menghentikan layanan setelah semua permintaan memulai telah ditangani, jadi Anda tidak perlu memanggil +{@link android.app.Service#stopSelf}.</li> + <li>Menyediakan implementasi default {@link android.app.IntentService#onBind onBind()} yang +mengembalikan null.</li> + <li>Menyediakan implementasi default {@link android.app.IntentService#onStartCommand +onStartCommand()} yang mengirimkan intent ke antrean pekerjaan kemudian ke implementasi {@link +android.app.IntentService#onHandleIntent onHandleIntent()} Anda.</li> +</ul> + +<p>Oleh karena itu, Anda hanya perlu mengimplementasikan {@link +android.app.IntentService#onHandleIntent onHandleIntent()} untuk melakukan pekerjaan yang diberikan oleh +klien. (Akan tetapi, Anda juga perlu menyediakan konstruktor kecil bagi layanan.)</p> + +<p>Berikut ini contoh implementasi {@link android.app.IntentService}:</p> + +<pre> +public class HelloIntentService extends IntentService { + + /** + * A constructor is required, and must call the super {@link android.app.IntentService#IntentService} + * constructor with a name for the worker thread. + */ + public HelloIntentService() { + super("HelloIntentService"); + } + + /** + * The IntentService calls this method from the default worker thread with + * the intent that started the service. When this method returns, IntentService + * stops the service, as appropriate. + */ + @Override + protected void onHandleIntent(Intent intent) { + // Normally we would do some work here, like download a file. + // For our sample, we just sleep for 5 seconds. + long endTime = System.currentTimeMillis() + 5*1000; + while (System.currentTimeMillis() < endTime) { + synchronized (this) { + try { + wait(endTime - System.currentTimeMillis()); + } catch (Exception e) { + } + } + } + } +} +</pre> + +<p>Anda hanya memerlukan: konstruktor dan implementasi {@link +android.app.IntentService#onHandleIntent onHandleIntent()}.</p> + +<p>Jika Anda memutuskan untuk juga mengesampingkan metode callback lain, seperti {@link +android.app.IntentService#onCreate onCreate()}, {@link +android.app.IntentService#onStartCommand onStartCommand()}, atau {@link +android.app.IntentService#onDestroy onDestroy()}, pastikan memanggil implementasi super, sehingga +{@link android.app.IntentService} bisa menangani hidup thread pekerja dengan baik.</p> + +<p>Misalnya, {@link android.app.IntentService#onStartCommand onStartCommand()} harus mengembalikan +implementasi default (yang merupakan cara penyampaian intent ke {@link +android.app.IntentService#onHandleIntent onHandleIntent()}):</p> + +<pre> +@Override +public int onStartCommand(Intent intent, int flags, int startId) { + Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show(); + return super.onStartCommand(intent,flags,startId); +} +</pre> + +<p>Selain {@link android.app.IntentService#onHandleIntent onHandleIntent()}, satu-satunya metode lain +yang tidak mengharuskan Anda memanggil super kelas adalah {@link android.app.IntentService#onBind +onBind()} (namun Anda hanya perlu mengimplementasikannya bila layanan mengizinkan pengikatan).</p> + +<p>Dalam bagian berikutnya, Anda akan melihat bagaimana layanan serupa diimplementasikan saat +memperluas kelas {@link android.app.Service} basis, yang membutuhkan kode lebih banyak lagi, namun mungkin +cocok jika Anda perlu menangani beberapa permintaan memulai sekaligus.</p> + + +<h3 id="ExtendingService">Memperluas kelas Layanan</h3> + +<p>Seperti telah Anda lihat di bagian sebelumnya, menggunakan {@link android.app.IntentService} membuat +implementasi layanan yang sudah dimulai jadi sangat sederhana. Namun, bila Anda mengharuskan layanan untuk +melakukan multi-threading (sebagai ganti memproses permintaan memulai melalui antrean pekerjaan), maka Anda +bisa memperluas kelas {@link android.app.Service} untuk menangani masing-masing intent.</p> + +<p>Sebagai perbandingan, contoh kode berikut ini adalah implementasi kelas {@link +android.app.Service} yang melakukan pekerjaan yang persis sama dengan contoh di atas menggunakan {@link +android.app.IntentService}. Artinya, untuk setiap permintaan memulai, kode tersebut akan menggunakan thread pekerja +untuk melakukan pekerjaan dan memproses permintaan satu per satu.</p> + +<pre> +public class HelloService extends Service { + private Looper mServiceLooper; + private ServiceHandler mServiceHandler; + + // Handler that receives messages from the thread + private final class ServiceHandler extends Handler { + public ServiceHandler(Looper looper) { + super(looper); + } + @Override + public void handleMessage(Message msg) { + // Normally we would do some work here, like download a file. + // For our sample, we just sleep for 5 seconds. + long endTime = System.currentTimeMillis() + 5*1000; + while (System.currentTimeMillis() < endTime) { + synchronized (this) { + try { + wait(endTime - System.currentTimeMillis()); + } catch (Exception e) { + } + } + } + // Stop the service using the startId, so that we don't stop + // the service in the middle of handling another job + stopSelf(msg.arg1); + } + } + + @Override + public void onCreate() { + // Start up the thread running the service. Note that we create a + // separate thread because the service normally runs in the process's + // main thread, which we don't want to block. We also make it + // background priority so CPU-intensive work will not disrupt our UI. + HandlerThread thread = new HandlerThread("ServiceStartArguments", + Process.THREAD_PRIORITY_BACKGROUND); + thread.start(); + + // Get the HandlerThread's Looper and use it for our Handler + mServiceLooper = thread.getLooper(); + mServiceHandler = new ServiceHandler(mServiceLooper); + } + + @Override + public int onStartCommand(Intent intent, int flags, int startId) { + Toast.makeText(this, "service starting", Toast.LENGTH_SHORT).show(); + + // For each start request, send a message to start a job and deliver the + // start ID so we know which request we're stopping when we finish the job + Message msg = mServiceHandler.obtainMessage(); + msg.arg1 = startId; + mServiceHandler.sendMessage(msg); + + // If we get killed, after returning from here, restart + return START_STICKY; + } + + @Override + public IBinder onBind(Intent intent) { + // We don't provide binding, so return null + return null; + } + + @Override + public void onDestroy() { + Toast.makeText(this, "service done", Toast.LENGTH_SHORT).show(); + } +} +</pre> + +<p>Seperti yang bisa Anda lihat, ini membutuhkan lebih banyak pekerjaan daripada menggunakan {@link android.app.IntentService}.</p> + +<p>Akan tetapi, karena Anda menangani sendiri setiap panggilan ke {@link android.app.Service#onStartCommand +onStartCommand()}, Anda bisa melakukan beberapa permintaan sekaligus. Itu bukan yang +dilakukan contoh ini, namun jika itu yang diinginkan, Anda bisa membuat thread baru untuk setiap +permintaan dan langsung menjalankannya (sebagai ganti menunggu permintaan sebelumnya selesai).</p> + +<p>Perhatikan bahwa metode {@link android.app.Service#onStartCommand onStartCommand()} harus mengembalikan +integer. Integer tersebut merupakan nilai yang menjelaskan cara sistem melanjutkan layanan dalam +kejadian yang dimatikan oleh sistem (sebagaimana dibahas di atas, implementasi default {@link +android.app.IntentService} menangani hal ini untuk Anda, walaupun Anda bisa memodifikasinya). Nilai yang dikembalikan +dari {@link android.app.Service#onStartCommand onStartCommand()} harus berupa salah satu +konstanta berikut ini:</p> + +<dl> + <dt>{@link android.app.Service#START_NOT_STICKY}</dt> + <dd>Jika sistem mematikan layanan setelah {@link android.app.Service#onStartCommand +onStartCommand()} dikembalikan, <em>jangan</em> membuat lagi layanan tersebut, kecuali jika ada intent +tertunda yang akan disampaikan. Inilah pilihan teraman untuk menghindari menjalankan layanan Anda +bila tidak diperlukan dan bila aplikasi Anda bisa me-restart pekerjaan yang belum selesai.</dd> + <dt>{@link android.app.Service#START_STICKY}</dt> + <dd>Jika sistem mematikan layanan setelah {@link android.app.Service#onStartCommand +onStartCommand()} dikembalikan, buat kembali layanan dan panggil {@link +android.app.Service#onStartCommand onStartCommand()}, namun <em>jangan</em> menyampaikan ulang intent terakhir. +Sebagai gantinya, sistem akan memanggil {@link android.app.Service#onStartCommand onStartCommand()} dengan +intent null, kecuali jika ada intent tertunda untuk memulai layanan, dan dalam hal ini, +intent tersebut disampaikan. Ini cocok bagi pemutar media (atau layanan serupa) yang tidak +mengeksekusi perintah, namun berjalan terus-menerus dan menunggu pekerjaan.</dd> + <dt>{@link android.app.Service#START_REDELIVER_INTENT}</dt> + <dd>Jika sistem mematikan layanan setelah {@link android.app.Service#onStartCommand +onStartCommand()} kembali, buat kembali layanan dan panggil {@link +android.app.Service#onStartCommand onStartCommand()} dengan intent terakhir yang disampaikan ke +layanan. Intent yang tertunda akan disampaikan pada gilirannya. Ini cocok bagi layanan yang +aktif melakukan pekerjaan yang harus segera dilanjutkan, misalnya mengunduh file.</dd> +</dl> +<p>Untuk detail selengkapnya tentang nilai pengembalian ini, lihat dokumentasi acuan untuk setiap +konstanta.</p> + + + +<h3 id="StartingAService">Memulai Layanan</h3> + +<p>Anda bisa memulai layanan dari aktivitas atau komponen aplikasi lain dengan meneruskan +{@link android.content.Intent} (yang menetapkan layanan yang akan dimulai) ke {@link +android.content.Context#startService startService()}. Sistem Android akan memanggil metode {@link +android.app.Service#onStartCommand onStartCommand()} layanan dan meneruskan {@link +android.content.Intent} padanya. (Jangan sekali-kali memanggil {@link android.app.Service#onStartCommand +onStartCommand()} secara langsung.)</p> + +<p>Misalnya, aktivitas bisa memulai contoh layanan di bagian sebelumnya ({@code +HelloSevice}) menggunakan intent eksplisit dengan {@link android.content.Context#startService +startService()}:</p> + +<pre> +Intent intent = new Intent(this, HelloService.class); +startService(intent); +</pre> + +<p>Metode {@link android.content.Context#startService startService()} segera kembali dan +sistem Android akan memanggil metode {@link android.app.Service#onStartCommand +onStartCommand()} layanan. Jika layanan belum berjalan, sistem mula-mula memanggil {@link +android.app.Service#onCreate onCreate()}, kemudian memanggil {@link android.app.Service#onStartCommand +onStartCommand()}.</p> + +<p>Jika layanan juga tidak menyediakan pengikatan, intent yang disampaikan dengan {@link +android.content.Context#startService startService()} adalah satu-satunya mode komunikasi antara +komponen aplikasi dan layanan. Akan tetapi, jika Anda ingin agar layanan mengirimkan hasilnya kembali, maka +klien yang memulai layanan bisa membuat {@link android.app.PendingIntent} untuk siaran +(dengan {@link android.app.PendingIntent#getBroadcast getBroadcast()}) dan menyampaikannya ke layanan +dalam {@link android.content.Intent} yang memulai layanan. Layanan kemudian bisa menggunakan +siaran untuk menyampaikan hasil.</p> + +<p>Beberapa permintaan untuk memulai layanan menghasilkan beberapa panggilan pula ke +{@link android.app.Service#onStartCommand onStartCommand()} layanan. Akan tetapi, hanya satu permintaan untuk menghentikan +layanan (dengan {@link android.app.Service#stopSelf stopSelf()} atau {@link +android.content.Context#stopService stopService()}) dibutuhkan untuk menghentikannya.</p> + + +<h3 id="Stopping">Menghentikan layanan</h3> + +<p>Layanan yang sudah dimulai harus mengelola daur hidupnya sendiri. Artinya, sistem tidak menghentikan atau +memusnahkan layanan kecuali jika harus memulihkan memori sistem dan layanan +terus berjalan setelah {@link android.app.Service#onStartCommand onStartCommand()} kembali. Jadi, +layanan tersebut harus berhenti sendiri dengan memanggil {@link android.app.Service#stopSelf stopSelf()} atau +komponen lain bisa menghentikannya dengan memanggil {@link android.content.Context#stopService stopService()}.</p> + +<p>Setelah diminta untuk berhenti dengan {@link android.app.Service#stopSelf stopSelf()} atau {@link +android.content.Context#stopService stopService()}, sistem akan menghapus layanan +secepatnya.</p> + +<p>Akan tetapi, bila layanan Anda menangani beberapa permintaan ke {@link +android.app.Service#onStartCommand onStartCommand()} sekaligus, Anda tidak boleh menghentikan +layanan bila Anda baru selesai memproses permintaan memulai, karena setelah itu mungkin Anda sudah menerima permintaan memulai +yang baru (berhenti pada permintaan pertama akan menghentikan permintaan kedua). Untuk menghindari +masalah ini, Anda bisa menggunakan {@link android.app.Service#stopSelf(int)} untuk memastikan bahwa permintaan +Anda untuk menghentikan layanan selalu berdasarkan pada permintaan memulai terbaru. Artinya, bila Anda memanggil {@link +android.app.Service#stopSelf(int)}, Anda akan meneruskan ID permintaan memulai (<code>startId</code> +yang disampaikan ke {@link android.app.Service#onStartCommand onStartCommand()}) yang terkait dengan permintaan berhenti +Anda. Kemudian jika layanan menerima permintaan memulai baru sebelum Anda bisa memanggil {@link +android.app.Service#stopSelf(int)}, maka ID tidak akan sesuai dan layanan tidak akan berhenti.</p> + +<p class="caution"><strong>Perhatian:</strong> Aplikasi Anda perlu menghentikan layanannya +bila selesai bekerja untuk menghindari pemborosan sumber daya sistem dan tenaga baterai. Jika perlu, +komponen lain bisa menghentikan layanan secara eksplisit dengan memanggil {@link +android.content.Context#stopService stopService()}. Bahkan jika Anda mengaktifkan pengikatan bagi layanan, +Anda harus selalu menghentikan layanan sendiri jika layanan tersebut menerima panggilan ke {@link +android.app.Service#onStartCommand onStartCommand()}.</p> + +<p>Untuk informasi selengkapnya tentang daur hidup layanan, lihat bagian di bawah ini tentang <a href="#Lifecycle">Mengelola Daur Hidup Layanan</a>.</p> + + + +<h2 id="CreatingBoundService">Membuat Layanan Terikat</h2> + +<p>Layanan terikat adalah layanan yang memungkinkan komponen aplikasi untuk mengikatnya dengan memanggil {@link +android.content.Context#bindService bindService()} guna membuat koneksi yang berlangsung lama +(dan umumnya tidak mengizinkan komponen untuk <em>memulainya</em> dengan memanggil {@link +android.content.Context#startService startService()}).</p> + +<p>Anda sebaiknya membuat layanan terikat bila ingin berinteraksi dengan layanan dari aktivitas +dan komponen lain dalam aplikasi Anda atau mengeskpos sebagian fungsionalitas aplikasi Anda ke +ke aplikasi lain, melalui komunikasi antarproses (IPC).</p> + +<p>Untuk membuat layanan terikat, Anda harus mengimplementasikan metode callback {@link +android.app.Service#onBind onBind()} untuk mengembalikan {@link android.os.IBinder} yang +mendefinisikan antarmuka bagi komunikasi dengan layanan. Komponen aplikasi lain kemudian bisa memanggil +{@link android.content.Context#bindService bindService()} untuk mengambil antarmuka dan +mulai memanggil metode pada layanan. Layanan hanya hidup untuk melayani komponen aplikasi yang +terikat padanya, jadi bila tidak ada komponen yang terikat pada layanan, sistem akan memusnahkannya +(Anda <em>tidak</em> perlu menghentikan layanan terikat seperti halnya bila layanan dimulai +melalui {@link android.app.Service#onStartCommand onStartCommand()}).</p> + +<p>Untuk membuat layanan terikat, hal yang perlu dilakukan pertama kali adalah mendefinisikan antarmuka yang menetapkan +cara klien berkomunikasi dengan layanan. Antarmuka antara layanan +dan klien ini harus berupa implementasi {@link android.os.IBinder} dan yang harus dikembalikan +layanan Anda dari metode callback {@link android.app.Service#onBind +onBind()}. Setelah menerima {@link android.os.IBinder}, klien bisa mulai +berinteraksi dengan layanan melalui antarmuka tersebut.</p> + +<p>Beberapa klien bisa mengikat ke layanan sekaligus. Bila klien selesai berinteraksi dengan +layanan, klien akan memanggil {@link android.content.Context#unbindService unbindService()} untuk melepas ikatan. Bila +tidak ada klien yang terikat pada layanan, sistem akan menghapus layanan tersebut.</p> + +<p>Ada beberapa cara untuk mengimplementasikan layanan terikat dan implementasinya lebih +rumit daripada layanan yang sudah dimulai, jadi layanan terikat dibahas dalam dokumen +terpisah tentang <a href="{@docRoot}guide/components/bound-services.html">Layanan Terikat</a>.</p> + + + +<h2 id="Notifications">Mengirim Pemberitahuan ke Pengguna</h2> + +<p>Setelah berjalan, layanan bisa memberi tahu pengguna tentang suatu kejadian menggunakan <a href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Pemberitahuan Toast</a> atau <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Pemberitahuan Baris Status</a>.</p> + +<p>Pemberitahuan Toast adalah pesan yang muncul sebentar pada permukaan jendela saat ini +kemudian menghilang, sementara pemberitahuan baris status memberikan ikon di baris status dengan +pesan yang bisa dipilih oleh pengguna untuk melakukan suatu tindakan (misalnya memulai suatu aktivitas).</p> + +<p>Biasanya, pemberitahuan baris status adalah teknik terbaik bila ada pekerjaan latar belakang yang sudah selesai +(misalnya file selesai +diunduh) dan pengguna kini bisa menggunakannya. Bila pengguna memilih pemberitahuan dari +tampilan diperluas, pemberitahuan akan bisa memulai aktivitas (misalnya menampilkan file yang baru diunduh).</p> + +<p>Lihat panduan pengembang <a href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Pemberitahuan Toast</a> atau <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Pemberitahuan Baris Status</a> +untuk informasi selengkapnya.</p> + + + +<h2 id="Foreground">Menjalankan Layanan di Latar Depan</h2> + +<p>Layanan latar depan adalah layanan yang dianggap sebagai sesuatu yang +diketahui secara aktif oleh pengguna, jadi bukan sesuatu yang akan dihapus oleh sistem bila memori menipis. Sebuah +layanan latar depan harus memberikan pemberitahuan bagi baris status, yang ditempatkan pada +heading "Ongoing" yang artinya pemberitahuan tersebut tidak bisa diabaikan kecuali jika layanan +dihentikan atau dihapus dari latar depan.</p> + +<p>Misalnya, pemutar musik yang memutar musik dari suatu layanan harus diatur untuk berjalan di +latar depan, karena pengguna mengetahui operasi tersebut +secara eksplisit. Pemberitahuan di baris status bisa menunjukkan lagu saat ini dan memungkinkan +pengguna untuk menjalankan suatu aktivitas untuk berinteraksi dengan pemutar musik.</p> + +<p>Untuk meminta agar layanan Anda berjalan di latar depan, panggil {@link +android.app.Service#startForeground startForeground()}. Metode ini memerlukan dua parameter: sebuah integer +yang mengidentifikasi pemberitahuan secara unik dan {@link +android.app.Notification} untuk baris status. Misalnya:</p> + +<pre> +Notification notification = new Notification(R.drawable.icon, getText(R.string.ticker_text), + System.currentTimeMillis()); +Intent notificationIntent = new Intent(this, ExampleActivity.class); +PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); +notification.setLatestEventInfo(this, getText(R.string.notification_title), + getText(R.string.notification_message), pendingIntent); +startForeground(ONGOING_NOTIFICATION_ID, notification); +</pre> + +<p class="caution"><strong>Perhatian:</strong> ID integer yang Anda berikan ke {@link +android.app.Service#startForeground startForeground()} tidak boleh 0.</p> + + +<p>Untuk menghapus layanan dari latar depan, panggil {@link +android.app.Service#stopForeground stopForeground()}. Metode ini memerlukan boolean, yang menunjukkan +apakah pemberitahuan baris status juga akan dihapus. Metode ini <em>tidak</em> menghentikan +layanan. Akan tetapi, jika Anda menghentikan layanan saat masih berjalan di latar depan +maka pemberitahuan juga akan dihapus.</p> + +<p>Untuk informasi selengkapnya tentang pemberitahuan, lihat <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Membuat Pemberitahuan +Baris Status</a>.</p> + + + +<h2 id="Lifecycle">Mengelola Daur Hidup Layanan</h2> + +<p>Daur hidup layanan jauh lebih sederhana daripada daur hidup aktivitas. Akan tetapi, lebih penting lagi adalah +memerhatikan dengan cermat bagaimana layanan Anda dibuat dan dimusnahkan, karena suatu layanan +bisa berjalan di latar belakang tanpa disadari oleh pengguna.</p> + +<p>Daur hidup layanan—dari saat dibuat hingga dimusnahkan—bisa mengikuti +dua path berbeda:</p> + +<ul> +<li>Layanan yang sudah dimulai + <p>Layanan dibuat bila komponen lain memanggil {@link +android.content.Context#startService startService()}. Layanan kemudian berjalan terus-menerus dan harus +berhenti sendiri dengan memanggil {@link +android.app.Service#stopSelf() stopSelf()}. Komponen lain juga bisa menghentikan +layanan dengan memanggil {@link android.content.Context#stopService +stopService()}. Bila layanan dihentikan, sistem akan menghancurkannya.</p></li> + +<li>Layanan terikat + <p>Layanan dibuat bila komponen lain (klien) memanggil {@link +android.content.Context#bindService bindService()}. Klien kemudian berkomunikasi dengan layanan +melalui antarmuka {@link android.os.IBinder}. Klien bisa menutup koneksi dengan memanggil +{@link android.content.Context#unbindService unbindService()}. Sejumlah klien bisa mengikat pada +layanan yang sama dan bila semuanya melepas ikatan, sistem akan memusnahkan layanan tersebut. (Layanan +<em>tidak</em> perlu berhenti sendiri.)</p></li> +</ul> + +<p>Kedua path tersebut tidak benar-benar terpisah. Artinya, Anda bisa mengikat ke layanan yang sudah +dimulai dengan {@link android.content.Context#startService startService()}. Misalnya, layanan +musik latar belakang bisa dimulai dengan memanggil {@link android.content.Context#startService +startService()} dengan {@link android.content.Intent} yang mengidentifikasi musik yang akan diputar. Kemudian, +mungkin saat pengguna ingin mengontrol pemutar musik atau mendapatkan informasi +tentang lagu yang diputar, aktivitas bisa mengikat ke layanan dengan memanggil {@link +android.content.Context#bindService bindService()}. Dalam kasus seperti ini, {@link +android.content.Context#stopService stopService()} atau {@link android.app.Service#stopSelf +stopSelf()} tidak menghentikan layanan sampai semua klien melepas ikatan. </p> + + +<h3 id="LifecycleCallbacks">Mengimplementasikan callback daur hidup</h3> + +<p>Seperti halnya aktivitas, layanan memiliki metode callback daur hidup yang bisa Anda implementasikan +untuk memantau perubahan status layanan dan melakukan pekerjaan pada waktu yang tepat. Layanan skeleton +berikut memperagakan setiap metode daur hidup:</p> + +<pre> +public class ExampleService extends Service { + int mStartMode; // indicates how to behave if the service is killed + IBinder mBinder; // interface for clients that bind + boolean mAllowRebind; // indicates whether onRebind should be used + + @Override + public void {@link android.app.Service#onCreate onCreate}() { + // The service is being created + } + @Override + public int {@link android.app.Service#onStartCommand onStartCommand}(Intent intent, int flags, int startId) { + // The service is starting, due to a call to {@link android.content.Context#startService startService()} + return <em>mStartMode</em>; + } + @Override + public IBinder {@link android.app.Service#onBind onBind}(Intent intent) { + // A client is binding to the service with {@link android.content.Context#bindService bindService()} + return <em>mBinder</em>; + } + @Override + public boolean {@link android.app.Service#onUnbind onUnbind}(Intent intent) { + // All clients have unbound with {@link android.content.Context#unbindService unbindService()} + return <em>mAllowRebind</em>; + } + @Override + public void {@link android.app.Service#onRebind onRebind}(Intent intent) { + // A client is binding to the service with {@link android.content.Context#bindService bindService()}, + // after onUnbind() has already been called + } + @Override + public void {@link android.app.Service#onDestroy onDestroy}() { + // The service is no longer used and is being destroyed + } +} +</pre> + +<p class="note"><strong>Catatan:</strong> Tidak seperti metode callback daur hidup aktivitas, Anda +<em>tidak</em> perlu memanggil implementasi superkelas metode callback tersebut.</p> + +<img src="{@docRoot}images/service_lifecycle.png" alt="" /> +<p class="img-caption"><strong>Gambar 2.</strong> Daur hidup layanan. Diagram di sebelah kiri +menampilkan daur hidup bila layanan dibuat dengan {@link android.content.Context#startService +startService()} dan diagram di sebelah kanan menampilkan daur hidup bila layanan dibuat +dengan {@link android.content.Context#bindService bindService()}.</p> + +<p>Dengan mengimplementasikan metode-metode ini, Anda bisa memantau dua loop tersarang (nested loop) daur hidup layanan: </p> + +<ul> +<li><strong>Seluruh masa pakai</strong> layanan terjadi antara saat {@link +android.app.Service#onCreate onCreate()} dipanggil dan saat {@link +android.app.Service#onDestroy} kembali. Seperti halnya aktivitas, layanan melakukan penyiapan awal di +{@link android.app.Service#onCreate onCreate()} dan melepaskan semua sisa sumber daya yang ada di {@link +android.app.Service#onDestroy onDestroy()}. Misalnya, +layanan pemutar musik bisa membuat thread tempat musik akan diputar dalam {@link +android.app.Service#onCreate onCreate()}, kemudian menghentikan thread tersebut dalam {@link +android.app.Service#onDestroy onDestroy()}. + +<p>Metode {@link android.app.Service#onCreate onCreate()} dan {@link android.app.Service#onDestroy +onDestroy()} diperlukan semua layanan, baik yang +dibuat oleh {@link android.content.Context#startService startService()} maupun {@link +android.content.Context#bindService bindService()}.</p></li> + +<li><strong>Masa pakai aktif</strong> layanan dimulai dengan panggilan ke {@link +android.app.Service#onStartCommand onStartCommand()} atau {@link android.app.Service#onBind onBind()}. +Masing-masing metode diberikan {@link +android.content.Intent} yang diteruskan ke {@link android.content.Context#startService +startService()} atau {@link android.content.Context#bindService bindService()}. +<p>Jika layanan telah dimulai, masa pakai aktif akan berakhir pada saat yang sama dengan +berakhirnya seluruh masa pakai (layanan masih aktif bahkan setelah {@link android.app.Service#onStartCommand +onStartCommand()} kembali). Jika layanan tersebut terikat, masa pakai aktifnya akan berakhir bila {@link +android.app.Service#onUnbind onUnbind()} kembali.</p> +</li> +</ul> + +<p class="note"><strong>Catatan:</strong> Meskipun layanan yang sudah dimulai dihentikan dengan panggilan ke +{@link android.app.Service#stopSelf stopSelf()} atau {@link +android.content.Context#stopService stopService()}, tidak ada callback tersendiri bagi +layanan tersebut (tidak ada callback {@code onStop()}). Jadi, kecuali jika layanan terikat ke klien, +sistem akan memusnahkannya bila layanan dihentikan—{@link +android.app.Service#onDestroy onDestroy()} adalah satu-satunya callback yang diterima.</p> + +<p>Gambar 2 mengilustrasikan metode callback yang lazim bagi suatu layanan. Walaupun gambar tersebut memisahkan +layanan yang dibuat oleh {@link android.content.Context#startService startService()} dari layanan +yang dibuat oleh {@link android.content.Context#bindService bindService()}, ingatlah +bahwa suatu layanan, bagaimana pun dimulainya, bisa memungkinkan klien mengikat padanya. +Jadi, suatu layanan yang awalnya dimulai dengan {@link android.app.Service#onStartCommand +onStartCommand()} (oleh klien yang memanggil {@link android.content.Context#startService startService()}) +masih bisa menerima panggilan ke {@link android.app.Service#onBind onBind()} (bila klien memanggil +{@link android.content.Context#bindService bindService()}).</p> + +<p>Untuk informasi selengkapnya tentang membuat layanan yang menyediakan pengikatan, lihat dokumen <a href="{@docRoot}guide/components/bound-services.html">Layanan Terikat</a>, +yang menyertakan informasi selengkapnya tentang metode callback {@link android.app.Service#onRebind onRebind()} +di bagian tentang <a href="{@docRoot}guide/components/bound-services.html#Lifecycle">Mengelola Daur Hidup +Layanan Terikat</a>.</p> + + +<!-- +<h2>Beginner's Path</h2> + +<p>To learn how to query data from the system or other applications (such as contacts or media +stored on the device), continue with the <b><a +href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></b> +document.</p> +--> diff --git a/docs/html-intl/intl/in/guide/components/tasks-and-back-stack.jd b/docs/html-intl/intl/in/guide/components/tasks-and-back-stack.jd new file mode 100644 index 000000000000..279442f2ab38 --- /dev/null +++ b/docs/html-intl/intl/in/guide/components/tasks-and-back-stack.jd @@ -0,0 +1,578 @@ +page.title=Tugas dan Back-Stack +parent.title=Aktivitas +parent.link=activities.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> +<li><a href="#ActivityState">Menyimpan Status Aktivitas</a></li></li> +<li><a href="#ManagingTasks">Mengelola Tugas</a> + <ol> + <li><a href="#TaskLaunchModes">Mendefinisikan mode peluncuran</a></li> + <li><a href="#Affinities">Menangani afinitas</a></li> + <li><a href="#Clearing">Menghapus back-stack</a></li> + <li><a href="#Starting">Memulai tugas</a></li> + </ol> +</li> +</ol> + +<h2>Artikel</h2> +<ol> + <li><a href="http://android-developers.blogspot.com/2010/04/multitasking-android-way.html"> + Multitasking Ala Android</a></li> +</ol> + +<h2>Lihat juga</h2> +<ol> + <li><a href="{@docRoot}design/patterns/navigation.html">Desain Android: +Navigasi</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html">Elemen manifes +{@code <activity>}</a></li> + <li><a href="{@docRoot}guide/components/recents.html">Layar Ikhtisar</a></li> +</ol> +</div> +</div> + + +<p>Sebuah aplikasi biasanya berisi beberapa <a href="{@docRoot}guide/components/activities.html">aktivitas</a>. Setiap aktivitas +harus didesain dengan jenis tindakan tertentu yang bisa dilakukan pengguna dan bisa memulai aktivitas +lain. Misalnya, aplikasi email mungkin memiliki satu aktivitas untuk menampilkan daftar pesan baru. +Bila pengguna memilih sebuah pesan, aktivitas baru akan terbuka untuk melihat pesan tersebut.</p> + +<p>Aktivitas bahkan bisa memulai aktivitas yang ada dalam aplikasi lain di perangkat. Misalnya +, jika aplikasi Anda ingin mengirim pesan email, Anda bisa mendefinisikan intent untuk melakukan tindakan +"kirim" dan menyertakan sejumlah data, seperti alamat email dan pesan. Aktivitas dari aplikasi +lain yang mendeklarasikan dirinya untuk menangani jenis intent ini akan terbuka. Dalam hal ini, intent +tersebut untuk mengirim email, sehingga aktivitas "menulis" pada aplikasi email akan dimulai (jika beberapa aktivitas +mendukung intent yang sama, maka sistem akan memungkinkan pengguna memilih mana yang akan digunakan). Bila email telah +dikirim, aktivitas Anda akan dilanjutkan dan seolah-olah aktivitas email adalah bagian dari aplikasi Anda. Meskipun +aktivitas mungkin dari aplikasi yang berbeda, Android akan tetap mempertahankan pengalaman pengguna yang mulus +dengan menjalankan kedua aktivitas dalam <em>tugas</em> yang sama.</p> + +<p>Tugas adalah kumpulan aktivitas yang berinteraksi dengan pengguna +saat melakukan pekerjaan tertentu. Aktivitas tersebut diatur dalam tumpukan (<em>back-stack</em>), dalam +urutan membuka setiap aktivitas.</p> + +<!-- SAVE FOR WHEN THE FRAGMENT DOC IS ADDED +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h3>Adding fragments to a task's back stack</h3> + +<p>Your activity can also include {@link android.app.Fragment}s to the back stack. For example, +suppose you have a two-pane layout using fragments, one of which is a list view (fragment A) and the +other being a layout to display an item from the list (fragment B). When the user selects an item +from the list, fragment B is replaced by a new fragment (fragment C). In this case, it might be +desireable for the user to navigate back to reveal fragment B, using the <em>Back</em> button.</p> +<p>In order to add fragment B to the back stack so that this is possible, you must call {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()} before you {@link +android.app.FragmentTransaction#commit()} the transaction that replaces fragment B with fragment +C.</p> +<p>For more information about using fragments and adding them to the back stack, see the {@link +android.app.Fragment} class documentation.</p> + +</div> +</div> +--> + +<p>Layar Home perangkat adalah tempat memulai hampir semua tugas. Bila pengguna menyentuh ikon di launcher +aplikasi +(atau pintasan pada layar Home), tugas aplikasi tersebut akan muncul pada latar depan. Jika tidak ada +tugas untuk aplikasi (aplikasi tidak digunakan baru-baru ini), maka tugas baru +akan dibuat dan aktivitas "utama" untuk aplikasi tersebut akan terbuka sebagai aktivitas akar dalam back-stack.</p> + +<p>Bila aktivitas saat ini dimulai lagi, aktivitas baru akan didorong ke atas back-stack dan +mengambil fokus. Aktivitas sebelumnya tetap dalam back-stack, namun dihentikan. Bila aktivitas +dihentikan, sistem akan mempertahankan status antarmuka penggunanya saat ini. Bila pengguna menekan tombol +<em>Back</em> +, aktivitas saat ini akan dikeluarkan dari atas back-stack (aktivitas dimusnahkan) dan + aktivitas sebelumnya dilanjutkan (status UI sebelumnya dipulihkan). Aktivitas dalam back-stack +tidak pernah disusun ulang, hanya didorong dan dikeluarkan dari back-stack—yang didorong ke back-stack saat dimulai oleh +aktivitas saat ini dan dikeluarkan bila pengguna meninggalkannya menggunakan tombol <em>Back</em>. Dengan demikian, +back-stack +beroperasi sebagai struktur objek "masuk terakhir, keluar pertama". Gambar 1 melukiskan perilaku +ini dengan jangka waktu yang menunjukkan kemajuan antar aktivitas beserta +back-stack pada setiap waktu.</p> + +<img src="{@docRoot}images/fundamentals/diagram_backstack.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Representasi tentang cara setiap aktivitas baru dalam +tugas menambahkan item ke back-stack. Bila pengguna menekan tombol <em>Back</em>, aktivitas +saat ini +akan dimusnahkan dan aktivitas sebelumnya dilanjutkan.</p> + + +<p>Jika pengguna terus menekan <em>Back</em>, maka setiap aktivitas dalam back-stack akan dikeluarkan untuk +menampilkan +yang sebelumnya, sampai pengguna kembali ke layar Home (atau aktivitas mana pun yang sedang dijalankan saat tugas +dimulai. Bila semua aktivitas telah dihapus dari back-stack, maka tugas tidak akan ada lagi.</p> + +<div class="figure" style="width:287px"> +<img src="{@docRoot}images/fundamentals/diagram_multitasking.png" alt="" /> <p +class="img-caption"><strong>Gambar 2.</strong> Dua tugas: Tugas B menerima interaksi pengguna +di latar depan, sedangkan Tugas A di latar belakang, menunggu untuk dilanjutkan.</p> +</div> +<div class="figure" style="width:215px"> + <img src="{@docRoot}images/fundamentals/diagram_multiple_instances.png" alt="" /> <p +class="img-caption"><strong>Gambar 3.</strong> Satu aktivitas dibuat instance-nya beberapa kali.</p> +</div> + +<p>Tugas adalah unit kohesif yang bisa dipindahkan ke "latar belakang" bila pengguna memulai tugas baru atau masuk ke +layar Home, melalui tombol<em>Home</em>. Sementara di latar belakang, semua aktivitas dalam +tugas +dihentikan, namun back-stack untuk tugas tidak berubah—tugas kehilangan fokus saat +tugas lain berlangsung, seperti yang ditampilkan dalam gambar 2. Kemudian, tugas bisa kembali ke "latar depan" agar pengguna +bisa melanjutkan tugas di tempat menghentikannya. Anggaplah, misalnya, tugas saat ini (Tugas A) memiliki tiga +aktivitas dalam back-stack—dua pada aktivitas saat ini. Pengguna menekan tombol <em>Home</em> +, kemudian +memulai aplikasi baru dari launcher aplikasi. Bila muncul layar Home, Tugas A akan beralih +ke latar belakang. Bila aplikasi baru dimulai, sistem akan memulai tugas untuk aplikasi tersebut +(Tugas B) dengan back-stack aktivitas sendiri. Setelah berinteraksi dengan aplikasi +tersebut, pengguna akan kembali ke Home lagi dan memilih aplikasi yang semula +memulai Tugas A. Sekarang, Tugas A muncul di +latar depan—ketiga aktivitas dalam back-stack tidak berubah dan aktivitas di atas +back-stack akan dilanjutkan. Pada +titik ini pengguna juga bisa beralih kembali ke Tugas B dengan masuk ke Home dan memilih ikon aplikasi +yang memulai tugas tersebut (atau dengan memilih tugas aplikasi dari +<a href="{@docRoot}guide/components/recents.html">layar ikhtisar</a>). +Ini adalah contoh dari melakukan multitasking di Android.</p> + +<p class="note"><strong>Catatan:</strong> Beberapa tugas bisa berlangsung di latar belakang secara bersamaan. +Akan tetapi, jika pengguna menjalankan banyak tugas di latar belakang sekaligus, sistem mungkin mulai +menghapus aktivitas latar belakang untuk memulihkan memori, yang akan menyebabkan status aktivitas hilang. +Lihat bagian berikut tentang <a href="#ActivityState">Status aktivitas</a>.</p> + +<p>Karena aktivitas di back-stack tidak pernah diatur ulang, jika aplikasi Anda memungkinkan +pengguna untuk memulai aktivitas tertentu dari lebih dari satu aktivitas, instance baru +aktivitas tersebut akan dibuat dan didorong ke back-stack (bukannya memunculkan instance sebelumnya dari +aktivitas ke atas). Dengan demikian, satu aktivitas pada aplikasi Anda mungkin dibuat beberapa +kali (bahkan dari beberapa tugas), seperti yang ditampilkan dalam gambar 3. Dengan demikian, jika pengguna mengarahkan mundur +menggunakan tombol <em>Back</em>, setiap instance aktivitas ini akan ditampilkan dalam urutan saat +dibuka (masing-masing +dengan status UI sendiri). Akan tetapi, Anda bisa memodifikasi perilaku ini jika tidak ingin aktivitas +dibuat instance-nya lebih dari sekali. Caranya dibahas di bagian selanjutnya tentang <a href="#ManagingTasks">Mengelola Tugas</a>.</p> + + +<p>Untuk meringkas perilaku default aktivitas dan tugas:</p> + +<ul> + <li>Bila Aktivitas A memulai Aktivitas B, Aktivitas A dihentikan, namun sistem mempertahankan statusnya +(seperti posisi gulir dan teks yang dimasukkan ke dalam formulir). +Jika pengguna menekan tombol <em>Back</em> saat dalam Aktivitas B, Aktivitas A akan dilanjutkan dengan status +yang dipulihkan.</li> + <li>Bila pengguna meninggalkan tugas dengan menekan tombol <em>Home</em> aktivitas saat ini akan +dihentikan dan +tugas beralih ke latar belakang. Sistem akan mempertahankan status setiap aktivitas dalam tugas. Jika +nanti pengguna melanjutkan tugas dengan memilih ikon launcher yang memulai tugas, tugas tersebut akan +beralih ke latar depan dan melanjutkan aktivitas di atas back-stack.</li> + <li>Jika pengguna menekan tombol <em>Back</em>, aktivitas saat ini akan dikeluarkan dari back-stack +dan +dimusnahkan. Aktivitas sebelumnya dalam back-stack akan dilanjutkan. Bila suatu aktivitas dimusnahkan, sistem +<em>tidak akan</em>mempertahankan status aktivitas.</li> + <li>Aktivitas bisa dibuat instance-nya beberapa kali, bahkan dari tugas-tugas lainnya.</li> +</ul> + + +<div class="note design"> +<p><strong>Desain Navigasi</strong></p> + <p>Untuk mengetahui selengkapnya tentang cara kerja navigasi aplikasi di Android, baca panduan <a href="{@docRoot}design/patterns/navigation.html">Navigasi</a> Desain Android.</p> +</div> + + +<h2 id="ActivityState">Menyimpan Status Aktivitas</h2> + +<p>Seperti dibahas di atas, perilaku default sistem akan mempertahankan status aktivitas bila +dihentikan. Dengan cara ini, bila pengguna mengarah kembali ke aktivitas sebelumnya, antarmuka pengguna akan muncul +seperti saat ditinggalkan. Akan tetapi, Anda bisa—dan <strong>harus</strong>—secara proaktif mempertahankan +status aktivitas menggunakan metode callback, jika aktivitas ini dimusnahkan dan harus +dibuat kembali.</p> + +<p>Bila sistem menghentikan salah satu aktivitas (seperti saat aktivitas baru dimulai atau tugas +dipindah ke latar belakang), sistem mungkin memusnahkan aktivitas sepenuhnya jika perlu memulihkan +memori sistem. Bila hal ini terjadi, informasi tentang status aktivitas akan hilang. Jika hal ini terjadi, sistem +masih +mengetahui bahwa aktivitas memiliki tempat di back-stack, namun saat aktivitas tersebut dibawa ke bagian teratas +back-stack, sistem harus membuatnya kembali (bukan melanjutkannya). Untuk +menghindari hilangnya pekerjaan pengguna, Anda harus secara proaktif mempertahankannya dengan menerapkan metode callback +{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} +dalam aktivitas.</p> + +<p>Untuk informasi selengkapnya tentang cara menyimpan status aktivitas Anda, lihat dokumen +<a href="{@docRoot}guide/components/activities.html#SavingActivityState">Aktivitas</a>.</p> + + + +<h2 id="ManagingTasks">Mengelola Tugas</h2> + +<p>Cara Android mengelola tugas dan back-stack, seperti yang dijelaskan di atas—dengan menempatkan semua +aktivitas yang dimulai secara berurutan dalam tugas yang sama dan dalam back-stack "masuk terakhir, keluar pertama"—berfungsi +dengan baik untuk kebanyakan aplikasi dan Anda tidak perlu khawatir tentang cara mengaitkan aktivitas +dengan tugas atau cara penempatannya di back-stack. Akan tetapi, Anda bisa memutuskan apakah ingin menyela +perilaku normal. Mungkin Anda ingin agar suatu aktivitas dalam aplikasi untuk memulai tugas baru bila telah +dimulai (sebagai ganti menempatkannya dalam tugas saat ini); atau, bila memulai aktivitas, Anda ingin +memajukan instance yang ada (sebagai ganti membuat instance +baru pada bagian teratas back-stack); atau, Anda ingin back-stack dihapus dari semua +aktivitas selain untuk aktivitas akar bila pengguna meninggalkan tugas.</p> + +<p>Anda bisa melakukan semua ini dan lainnya, dengan atribut dalam elemen manifes +<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +dan dengan flag pada intent yang Anda teruskan ke +{@link android.app.Activity#startActivity startActivity()}.</p> + +<p>Dalam hal ini, atribut<a href="{@docRoot}guide/topics/manifest/activity-element.html"> +{@code <activity>}</a> utama yang bisa Anda gunakan adalah:</p> + +<ul class="nolist"> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff"> + {@code taskAffinity}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode"> + {@code launchMode}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent"> + {@code allowTaskReparenting}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#clear"> + {@code clearTaskOnLaunch}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#always"> + {@code alwaysRetainTaskState}</a></li> + <li><a href="{@docRoot}guide/topics/manifest/activity-element.html#finish"> + {@code finishOnTaskLaunch}</a></li> +</ul> + +<p>Dan flag intent utama yang bisa Anda gunakan adalah:</p> + +<ul class="nolist"> + <li>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</li> + <li>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</li> + <li>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</li> +</ul> + +<p>Dalam bagian berikut, Anda akan melihat cara menggunakan beberapa atribut manifes ini dan flag +intent untuk mendefinisikan cara mengaitkan aktivitas dengan tugas dan cara perilakunya di back-stack.</p> + +<p>Juga, pertimbangan cara menyatakan dan mengelola tugas dan aktivitas +dibahas secara terpisah di layar ikhtisar. Lihat <a href="{@docRoot}guide/components/recents.html">Layar Ikhtisar</a> +untuk informasi selengkapnya. Biasanya Anda harus mengizinkan sistem mendefinisikan cara menyatakan tugas dan +aktivitas di layar ikhtisar, dan Anda tidak perlu memodifikasi perilaku ini.</p> + +<p class="caution"><strong>Perhatian:</strong> Kebanyakan aplikasi tidak harus menyela perilaku +default untuk aktivitas dan tugas. Jika merasa bahwa aktivitas Anda perlu memodifikasi +perilaku default, lakukan dengan hati-hati dan pastikan menguji kegunaan aktivitas selama +dijalankan dan saat mengarahkan kembali ke sana dari aktivitas dan tugas lain dengan tombol <em>Back</em>. +Pastikan menguji perilaku navigasi yang mungkin bertentangan dengan perilaku yang diharapkan pengguna.</p> + + +<h3 id="TaskLaunchModes">Mendefinisikan mode peluncuran</h3> + +<p>Mode peluncuran memungkinkan Anda mendefinisikan cara mengaitkan instance baru dari suatu aktivitas dengan +tugas saat ini. Anda bisa mendefinisikan beragam mode peluncuran dalam dua cara:</p> +<ul class="nolist"> + <li><a href="#ManifestForTasks">Menggunakan file manifes</a> + <p>Bila Anda mendeklarasikan aktivitas dalam file manifes, Anda bisa menetapkan cara mengaitkan aktivitas +dengan tugas-tugas saat mulai.</li> + <li><a href="#IntentFlagsForTasks">Menggunakan flag intent</a> + <p>Saat memanggil{@link android.app.Activity#startActivity startActivity()}, +Anda bisa menyertakan flag dalam {@link android.content.Intent} yang menyatakan cara (atau +apakah) aktivitas baru tersebut harus dikaitkan dengan tugas saat ini.</p></li> +</ul> + +<p>Dengan demikian, jika Aktivitas A memulai Aktivitas B, Aktivitas B bisa mendefinisikan dalam manifesnya cara +mengaitkan dengan tugas saat ini (jika sama sekali) dan Aktivitas A juga bisa meminta cara mengaitkan Aktivitas B +dengan tugas saat ini. Jika kedua aktivitas mendefinisikan cara mengaitkan Aktivitas B +dengan tugas, maka permintaan Aktivitas A (sebagaimana didefinisikan dalam intent) lebih dihargai daripada +permintaan Aktivitas B (sebagaimana didefinisikan dalam manifesnya).</p> + +<p class="note"><strong>Catatan:</strong> Beberapa mode peluncuran yang tersedia untuk file manifes +tidak tersedia sebagai flag untuk intent dan, juga, beberapa mode peluncuran yang tersedia sebagai flag +untuk intent tidak bisa didefinisikan dalam manifest.</p> + + +<h4 id="ManifestForTasks">Menggunakan file manifes</h4> + +<p>Saat mendeklarasikan aktivitas dalam file manifes, Anda bisa menetapkan cara mengaitkan aktivitas +dengan tugas menggunakan <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +melalui atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code +launchMode}</a> elemen.</p> + +<p>Atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code +launchMode}</a> menetapkan instruksi tentang cara meluncurkan aktivitas +ke dalam tugas. Ada empat macam mode peluncuran yang bisa Anda tetapkan ke atribut +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> +:</p> + +<dl> +<dt>{@code "standard"} (mode default)</dt> + <dd>Default. Sistem membuat instance baru aktivitas dalam tugas yang +akan menjadi tempat memulainya dan mengarahkan intent ke sana. Aktivitas ini bisa dibuat instance-nya beberapa kali, +masing-masing instance bisa dimiliki oleh tugas berbeda, dan satu tugas bisa memiliki beberapa instance.</dd> +<dt>{@code "singleTop"}</dt> + <dd>Jika instance aktivitas sudah ada di bagian teratas tugas saat ini, sistem +akan mengarahkan intent ke instance tersebut melalui panggilan ke metode {@link +android.app.Activity#onNewIntent onNewIntent()}, bukan membuat instance baru dari +aktivitas tersebut. Aktivitas bisa dibuat instance-nya beberapa kali, masing-masing instance bisa dimiliki +oleh tugas berbeda, dan satu tugas bisa memiliki beberapa instance (namun hanya jika +aktivitas di bagian teratas back-stack <em>bukan</em> instance yang ada dari aktivitas tersebut). + <p>Misalnya, anggaplah back-stack tugas terdiri dari aktivitas A akar dengan aktivitas B, C, +dan D di bagian teratas (back-stack adalah A-B-C-D; D yang teratas). Intent masuk untuk aktivitas tipe D. +Jika D memiliki mode peluncuran {@code "standard"} default, instance baru dari kelas ini akan diluncurkan dan +back-stack menjadi A-B-C-D-D. Namun, jika mode peluncuran D adalah {@code "singleTop"}, instance +yang ada dari D akan menerima intent melalui {@link +android.app.Activity#onNewIntent onNewIntent()}, karena ada di bagian teratas back-stack— +back-stack tetap A-B-C-D. Akan tetapi, jika intent masuk untuk aktivitas tipe B, maka +instance B baru akan ditambahkan ke back-stack, sekalipun mode peluncuran adalah{@code "singleTop"}.</p> + <p class="note"><strong>Catatan:</strong> Bila instance dari aktivitas baru telah dibuat, +pengguna bisa menekan tombol <em>Back</em> untuk kembali ke aktivitas sebelumnya. Namun bila instance +yang ada dari +aktivitas menangani intent baru, pengguna tidak bisa menekan tombol <em>Back</em> untuk kembali ke +status +aktivitas sebelum intent baru masuk di {@link android.app.Activity#onNewIntent +onNewIntent()}.</p> +</dd> + +<dt>{@code "singleTask"}</dt> + <dd>Sistem membuat tugas baru dan membuat instance aktivitas di akar tugas baru. +Akan tetapi, jika instance aktivitas sudah ada dalam tugas terpisah, sistem akan mengarahkan +intent ke instance yang ada melalui panggilan ke metode {@link +android.app.Activity#onNewIntent onNewIntent()}, bukan membuat instance baru. Hanya +boleh ada satu instance aktivitas untuk setiap kalinya. + <p class="note"><strong>Catatan:</strong> Meskipun aktivitas dimulai di tugas baru, tombol +<em>Back</em> tetap akan mengembalikan pengguna ke aktivitas sebelumnya.</p></dd> +<dt>{@code "singleInstance"}.</dt> + <dd>Sama seperti {@code "singleTask"}, namun sistem tidak meluncurkan aktivitas lain ke +tugas yang menyimpan instance. Aktivitas selalu satu dan satu-satunya anggota dari tugasnya; +aktivitas apa pun yang dimulai dengan ini akan dibuka di tugas yang terpisah.</dd> +</dl> + + +<p>Sebagai contoh lainnya, aplikasi Browser Android mendeklarasikan bahwa aktivitas browser web harus +selalu dibuka dalam tugasnya sendiri—dengan menetapkan mode pembuka {@code singleTask} dalam elemen<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a>. +Ini berarti bahwa jika aplikasi Anda mengeluarkan +intent untuk membuka Browser Android, aktivitasnya <em>tidak</em> akan ditempatkan dalam tugas +yang sama seperti aplikasi Anda. Sebagai gantinya, tugas baru akan dimulai untuk Browser atau, jika Browser +sudah memiliki tugas yang berjalan di latar belakang, tugas tersebut akan dimajukan untuk menangani intent +baru.</p> + +<p>Baik aktivitas dimulai dalam tugas baru atau maupun dalam tugas yang sama seperti aktivitas yang memulainya, tombol +<em>Back</em> selalu membawa pengguna ke aktivitas sebelumnya. Akan tetapi, jika +Anda memulai aktivitas yang menetapkan mode pembuka {@code singleTask}, maka jika instance +aktivitas tersebut ada dalam tugas latar belakang, seluruh tugas tersebut akan dibawa ke latar depan. Pada titik +ini, back-stack sekarang menyertakan semua aktivitas dari tugas yang dimajukan, di atas +back-stack. Gambar 4 mengilustrasikan tipe skenario ini.</p> + +<img src="{@docRoot}images/fundamentals/diagram_backstack_singletask_multiactivity.png" alt="" /> +<p class="img-caption"><strong>Gambar 4.</strong> Representasi tentang cara aktivitas dengan +mode pembuka "singleTask" ditambahkan ke back-stack. Jika aktivitas tersebut sudah menjadi bagian dari +tugas latar belakang dengan back-stack sendiri, maka seluruh back-stack juga +dimajukan, di atas tugas saat ini.</p> + +<p>Untuk informasi selengkapnya tentang menggunakan mode pembuka dalam file manifes, lihat dokumentasi elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +, di mana atribut {@code launchMode} dan nilai-nilai yang diterima +akan dibahas selengkapnya.</p> + +<p class="note"><strong>Catatan:</strong> Perilaku yang Anda tentukan untuk aktivitas dengan atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> +bisa dikesampingkan dengan flag yang disertakan bersama intent yang memulai aktivitas Anda, seperti dibahas dalam +bagian berikutnya.</p> + + + +<h4 id="#IntentFlagsForTasks">Menggunakan flag Intent</h4> + +<p>Saat memulai aktivitas, Anda bisa memodifikasi asosiasi default aktivitas pada tugasnya + dengan menyertakan flag dalam intent yang Anda kirimkan ke {@link +android.app.Activity#startActivity startActivity()}. Flag yang bisa Anda gunakan untuk memodifikasi perilaku default +adalah:</p> + +<p> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</dt> + <dd>Memulai aktivitas dalam tugas baru. Jika tugas sudah dijalankan untuk aktivitas yang sekarang +Anda mulai, tugas tersebut akan dibawa ke latar depan dengan status terakhir yang dipulihkan dan aktivitas +akan menerima intent baru dalam {@link android.app.Activity#onNewIntent onNewIntent()}. + <p>Ini menghasilkan perilaku yang sama dengan nilai {@code "singleTask"} <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> +yang dibahas di bagian sebelumnya.</p></dd> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}</dt> + <dd>Jika aktivitas yang dimulai adalah aktivitas saat ini (di bagian teratas back-stack), maka +instance yang ada akan menerima panggilan ke {@link android.app.Activity#onNewIntent onNewIntent()} +sebagai ganti membuat instance baru aktivitas. + <p>Ini menghasilkan perilaku yang sama dengan nilai {@code "singleTop"} <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> +yang dibahas di bagian sebelumnya.</p></dd> + <dt>{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}</dt> + <dd>Jika aktivitas yang dimulai sudah berjalan dalam tugas saat ini, maka sebagai +ganti meluncurkan instance baru aktivitas tersebut, semua kegiatan lain di atasnya akan +dimusnahkan dan intent ini akan disampaikan ke instance aktivitas yang dilanjutkan (sekarang di atas), +melalui {@link android.app.Activity#onNewIntent onNewIntent()}). + <p>Tidak ada nilai untuk atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">{@code launchMode}</a> + yang menghasilkan perilaku ini.</p> + <p>{@code FLAG_ACTIVITY_CLEAR_TOP} paling sering digunakan bersama dengan + {@code FLAG_ACTIVITY_NEW_TASK}. +Bila digunakan bersama-sama, flag ini adalah cara penempatan aktivitas yang ada +dalam tugas lain dan meletakkannya dalam posisi yang memungkinkannya merespons intent. </p> + <p class="note"><strong>Catatan:</strong> Jika mode pembuka aktivitas yang didesain adalah +{@code "standard"}, +ini juga akan dihapus dari back-stack dan instance baru akan diluncurkan di tempatnya untuk menangani +intent yang masuk. Itu karena instance baru selalu dibuat untuk intent baru bila +mode peluncuran adalah {@code "standard"}. </p> +</dd> +</dl> + + + + + +<h3 id="Affinities">Menangani afinitas</h3> + +<p><em>Afinitas</em> menunjukkan tugas mana yang disukai aktivitas untuk dimiliki. Secara default, semua +aktivitas aplikasi yang sama memiliki afinitas untuk satu sama lain. Jadi, secara default, semua +aktivitas dalam aplikasi yang sama lebih menyukai berada dalam tugas yang sama. Akan tetapi, Anda bisa memodifikasi +afinitas default untuk suatu aktivitas. Aktivitas yang didefinisikan dalam +aplikasi yang berbeda bisa berbagi afinitas, atau aktivitas yang didefinisikan dalam aplikasi yang sama bisa +diberi afinitas tugas yang berbeda.</p> + +<p>Anda bisa memodifikasi afinitas untuk setiap yang diberikan +dengan atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> +elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a>.</p> + +<p>Atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> +mengambil nilai string, yang harus unik dari nama paket default +yang dideklarasikan dalam elemen <a href="{@docRoot}guide/topics/manifest/manifest-element.html"> +{@code <manifest>} +</a>, karena sistem menggunakan nama untuk mengidentifikasi afinitas +tugas default untuk aplikasi.</p> + +<p>Afinitas berperan dalam dua keadaan:</p> +<ul> + <li>Bila intent yang meluncurkan aktivitas berisi flag + {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} +. + +<p>Aktivitas baru, secara default, diluncurkan ke dalam tugas aktivitas +yang disebut {@link android.app.Activity#startActivity startActivity()}. Ini didorong ke back-stack +yang sama seperti caller. Akan tetapi, jika intent yang diteruskan ke +{@link android.app.Activity#startActivity startActivity()} +berisi flag {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} +, maka sistem akan mencari tugas yang berbeda untuk menampung aktivitas baru. Sering kali, itu adalah tugas baru. +Akan tetapi, tidak harus demikian. Jika sudah ada tugas lama dengan afinitas yang sama seperti +aktivitas baru, aktivitas ini akan diluncurkan ke dalam tugas tersebut. Jika tidak, tugas baru akan dimulai.</p> + +<p>Jika flag ini menyebabkan aktivitas memulai tugas baru dan pengguna menekan tombol <em>Home</em> +untuk meninggalkannya, +harus ada cara bagi pengguna untuk mengarahkan kembali ke tugas. Beberapa entitas (seperti +notification manager) selalu memulai aktivitas dalam tugas eksternal, tidak pernah sebagai bagian dari miliknya sendiri, jadi +selalu menempatkan {@code FLAG_ACTIVITY_NEW_TASK} dalam intent yang diteruskan ke +{@link android.app.Activity#startActivity startActivity()}. +Jika Anda memiliki aktivitas yang bisa dipanggil melalui +entitas eksternal yang mungkin menggunakan flag ini, hati-hatilah karena pengguna memiliki cara independen untuk kembali +ke tugas yang telah dimulai, seperti dengan ikon launcher (aktivitas akar dari tugas +memiliki filter intent {@link android.content.Intent#CATEGORY_LAUNCHER}; lihat bagian <a href="#Starting">Memulai tugas</a> di bawah ini).</p> +</li> + + <li>Bila aktivitas memiliki atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent"> +{@code allowTaskReparenting}</a> sendiri yang diatur ke {@code "true"}. + <p>Dalam hal ini, aktivitas bisa berpindah dari tugas yang dimulainya ke tugas yang afinitasnya +dimilikinya, bila tugas tersebut di bawa ke latar depan.</p> + <p>Misalnya, anggaplah sebuah aktivitas melaporkan kondisi cuaca di sejumlah kota terpilih +yang didefinisikan sebagai bagian dari aplikasi perjalanan. Aktivitas memiliki afinitas yang sama dengan aktivitas lain dalam aplikasi +yang sama (afinitas aplikasi default) dan aktivitas ini memungkinkan re-parenting dengan atribut ini. +Bila salah satu aktivitas Anda memulai aktivitas laporan cuaca, awalnya aktivitas ini dimiliki oleh tugas +yang sama dengan aktivitas Anda. Akan tetapi, bila tugas aplikasi perjalanan di bawa ke latar depan, +aktivitas laporan cuaca akan ditetapkan kembali ke tugas itu dan ditampilkan di dalamnya.</p> +</li> +</ul> + +<p class="note"><strong>Tip:</strong> Jika file {@code .apk} berisi lebih dari satu "aplikasi" +dari sudut pandang pengguna, Anda mungkin perlu menggunakan atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">{@code taskAffinity}</a> + untuk menetapkan afinitas berbeda pada aktivitas yang terkait dengan setiap "aplikasi".</p> + + + +<h3 id="Clearing">Menghapus back-stack</h3> + +<p>Jika pengguna meninggalkan tugas dalam waktu yang lama, sistem akan menghapus tugas semua aktivitas kecuali +aktivitas akar. Bila pengguna kembali ke tugas itu lagi, hanya aktivitas akar yang akan dipulihkan. +Sistem berperilaku seperti ini, karena, setelah sekian waktu, pengguna mungkin telah mengabaikan +apa yang mereka kerjakan sebelum dan kembali ke tugas itu untuk memulai sesuatu yang baru. </p> + +<p>Ada beberapa atribut aktivitas yang bisa Anda gunakan untuk memodifikasi perilaku ini: </p> + +<dl> +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code> +</dt> +<dd>Jika atribut ini ditetapkan ke {@code "true"} dalam aktivitas akar tugas, +perilaku default yang baru dijelaskan tidak akan terjadi. + Tugas akan mempertahankan semua aktivitas dalam back-stack bahkan setelah sekian lama.</dd> + +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code></dt> +<dd>Jika atribut ini diatur ke {@code "true"} dalam aktivitas akar tugas, back- +stack akan dihapus hingga aktivitas akar bila pengguna meninggalkan tugas +dan kembali lagi. Dengan kata lain, ini adalah lawan dari +<a href="{@docRoot}guide/topics/manifest/activity-element.html#always"> +{@code alwaysRetainTaskState}</a>. Pengguna selalu kembali ke tugas dengan +status awalnya, walaupun hanya sebentar meninggalkan tugas.</dd> + +<dt><code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code> +</dt> +<dd>Atribut ini seperti <a href="{@docRoot}guide/topics/manifest/activity-element.html#clear">{@code clearTaskOnLaunch}</a>, +namun beroperasi pada +satu aktivitas, bukan pada seluruh tugas. Hal ini juga bisa menyebabkan aktivitas +hilang, termasuk aktivitas akar. Bila ini diatur ke {@code "true"}, +aktivitas akan tetap menjadi bagian dari tugas hanya untuk sesi saat ini. Jika pengguna +keluar dan kemudian kembali ke tugas tersebut, tugas tidak akan ada lagi.</dd> +</dl> + + + + +<h3 id="Starting">Memulai tugas</h3> + +<p>Anda bisa mengatur aktivitas sebagai titik masuk untuk tugas dengan memberikan filter intent dengan +{@code "android.intent.action.MAIN"} sebagai tindakan yang ditetapkan dan +{@code "android.intent.category.LAUNCHER"} +sebagai kategori yang ditetapkan. Misalnya:</p> + +<pre> +<activity ... > + <intent-filter ... > + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> + ... +</activity> +</pre> + +<p>Filter intent semacam ini akan menyebabkan ikon dan label untuk +aktivitas ditampilkan dalam launcher aplikasi, yang akan memberi cara kepada pengguna untuk meluncurkan aktivitas dan +kembali ke tugas yang dibuatnya kapan saja setelah ia telah diluncurkan. +</p> + +<p>Kemampuan kedua ini penting: Pengguna harus bisa meninggalkan tugas dan kemudian kembali ke tugas tersebut +nanti dengan menggunakan launcher aktivitas ini. Karena itu, kedua <a href="#LaunchModes">mode +pembuka</a> yang menandai aktivitas selalu memulai tugas, {@code "singleTask"} dan +{@code "singleInstance"}, hanya boleh digunakan bila aktivitas memiliki filter +{@link android.content.Intent#ACTION_MAIN} +dan {@link android.content.Intent#CATEGORY_LAUNCHER}. Bayangkan, misalnya, apa yang akan +terjadi jika filter tidak ada: Intent meluncurkan aktivitas{@code "singleTask"}, memulai +tugas yang baru, dan pengguna menghabiskan lebih banyak waktu mengerjakan tugas tersebut. Pengguna kemudian menekan tombol +<em>Home</em>. Tugas kini dikirim ke latar belakang dan tidak terlihat. Sekarang pengguna tidak memiliki cara untuk kembali +ke tugas tersebut, karena tidak dinyatakan dalam launcher aplikasi.</p> + +<p>Untuk kasus-kasus di mana Anda tidak ingin pengguna bisa kembali ke aktivitas, atur dalam +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + pada +<a href="{@docRoot}guide/topics/manifest/activity-element.html#finish">{@code finishOnTaskLaunch}</a> +elemen ke {@code "true"} (lihat <a href="#Clearing">Menghapus back-stack</a>).</p> + +<p>Informasi lebih jauh tentang cara menyatakan dan mengelola tugas dan aktivitas dalam +layar ikhtisar tersedia dalam<a href="{@docRoot}guide/components/recents.html"> +Layar Ikhtisar</a>.</p> + +<!-- +<h2>Beginner's Path</h2> + +<p>For more information about how to use intents to +activate other application components and publish the intents to which your components +respond, continue with the <b><a +href="{@docRoot}guide/components/intents-filters.html">Intents and Intent +Filters</a></b> document.</p> +--> diff --git a/docs/html-intl/intl/in/guide/index.jd b/docs/html-intl/intl/in/guide/index.jd new file mode 100644 index 000000000000..f24fab690ed9 --- /dev/null +++ b/docs/html-intl/intl/in/guide/index.jd @@ -0,0 +1,74 @@ +page.title=Pengantar Android + +@jd:body + + +<div class="sidebox" style="width:220px"><!-- width to match col-4 below --> +<p>Untuk mempelajari cara kerja aplikasi, mulailah dengan +<a href="{@docRoot}guide/components/fundamentals.html">Dasar-Dasar Aplikasi</a>.</p> +<p>Untuk langsung memulai pemrograman, bacalah <a href="{@docRoot}training/basics/firstapp/index.html">Membangun Aplikasi Pertama Anda.</a></p> +</div> + +<p>Android menyediakan kerangka kerja aplikasi yang kaya dan memungkinkan Anda membangun aplikasi dan permainan +inovatif untuk perangkat seluler di lingkungan bahasa pemrograman Java. Dokumen yang tercantum di navigasi +sebelah kiri menyediakan detail tentang cara membangun aplikasi menggunakan berbagai API Android.</p> + +<p>Jika Anda masih baru dengan pengembangan Android, Anda perlu memahami +konsep dasar berikut mengenai kerangka kerja aplikasi Android:</p> + + +<div class="landing-banner"> + +<div class="col-6"> + +<h4>Aplikasi menyediakan beberapa titik masuk</h4> + +<p>Aplikasi Android dibangun sebagai kombinasi beragam komponen yang bisa dipanggil +satu per satu. Misalnya, satu <em>aktivitas</em> individual menyediakan satu +layar untuk antarmuka pengguna, dan <em>layanan</em> yang secara terpisah melakukan +tugas di latar belakang.</p> + +<p>Dari satu komponen Anda dapat memulai komponen lainnya menggunakan <em>intent</em>. Anda bahkan dapat memulai +satu komponen dalam aplikasi berbeda, seperti aktivitas dalam aplikasi peta untuk menampilkan alamat. Model ini +menyediakan beberapa titik masuk untuk aplikasi tunggal dan memungkinkan setiap aplikasi untuk berfungsi sebagai "default" +pengguna bagi tindakan yang dapat dipanggil aplikasi lain.</p> + + +<p><b>Ketahui selengkapnya:</b></p> +<ul class="nolist"> +<li><a href="{@docRoot}guide/components/fundamentals.html">Dasar-Dasar Aplikasi</a> +<li><a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter Intent</a> +<li><a href="{@docRoot}guide/components/activities.html">Aktivitas</a> +</ul> + +</div> + + +<div class="col-6"> + +<h4>Aplikasi beradaptasi dengan perangkat berbeda</h4> + +<p>Android menyediakan kerangka kerja aplikasi adaptif yang memungkinkan Anda menyediakan sumber daya unik +bagi konfigurasi perangkat yang berbeda-beda. Misalnya, Anda bisa membuat berbagai file layout +XML untuk ukuran layar yang berbeda-beda dan sistem akan menentukan +layout yang akan diterapkan berdasarkan ukuran layar perangkat yang ada saat ini.</p> + +<p>Anda dapat melakukan query ketersediaan fitur perangkat saat dijalankan (runtime) jika ada fitur aplikasi yang memerlukan +perangkat keras spesifik seperti kamera. Jika diperlukan, Anda juga bisa mendeklarasikan fitur yang dibutuhkan aplikasi +agar pasar aplikasi seperti Google Play Store tidak mengizinkan instalasi pada perangkat yang tidak +mendukung fitur itu.</p> + + +<p><b>Ketahui selengkapnya:</b></p> +<ul class="nolist"> +<li><a href="{@docRoot}guide/practices/compatibility.html">Kompatibilitas Perangkat</a> +<li><a href="{@docRoot}guide/topics/resources/overview.html">Ikhtisar Sumber Daya</a> +<li><a href="{@docRoot}guide/topics/ui/overview.html">Ikhtisar Antarmuka Pengguna</a> +</ul> + +</div> + +</div><!-- end landing-banner --> + + + diff --git a/docs/html-intl/intl/in/guide/topics/manifest/manifest-intro.jd b/docs/html-intl/intl/in/guide/topics/manifest/manifest-intro.jd new file mode 100644 index 000000000000..6d6a3ad252db --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/manifest/manifest-intro.jd @@ -0,0 +1,517 @@ +page.title=Manifes Aplikasi +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> +<li><a href="#filestruct">Struktur File Manifes</a></li> +<li><a href="#filec">Konvensi File</a> +<li><a href="#filef">Fitur File</a> + <ol> + <li><a href="#ifs">Filter Intent</a></li> + <li><a href="#iconlabel">Ikon dan Label</a></li> + <li><a href="#perms">Izin</a></li> + <li><a href="#libs">Pustaka</a></li> + </ol></li> +</ol> +</div> +</div> + +<p> + Setiap aplikasi harus memiliki file AndroidManifest.xml (bernama persis seperti ini) di direktori akar. + <span itemprop="description">File manifes + menyediakan informasi penting tentang aplikasi ke sistem Android, + informasi yang harus dimiliki sistem agar bisa menjalankan setiap kode +aplikasi.</span> Di antaranya, manifes melakukan hal berikut ini: +</p> + +<ul> +<li>Menamai paket Java untuk aplikasi. +Nama paket berfungsi sebagai identifier unik untuk aplikasi.</li> + +<li>Menjelaskan berbagai komponen aplikasi—aktivitas, + layanan, penerima siaran, dan penyedia konten +yang membentuk aplikasi. Menamai kelas yang mengimplementasikan setiap komponen dan +mempublikasikan kemampuannya (misalnya, pesan {@link android.content.Intent +Intent} mana yang bisa ditanganinya). Deklarasi ini memberi tahu sistem Android mengenai +komponennya dan dalam kondisi apa bisa diluncurkan.</li> + +<li>Menentukan proses yang akan menjadi host komponen aplikasi.</li> + +<li>Mendeklarasikan izin aplikasi mana yang harus dimiliki untuk +mengakses bagian yang dilindungi pada API dan berinteraksi dengan aplikasi lain.</li> + +<li>Juga mendeklarasikan izin lain yang harus dimiliki untuk +untuk berinteraksi dengan komponen aplikasi.</li> + +<li>Mencantumkan daftar kelas {@link android.app.Instrumentation} yang memberikan +profil dan informasi lain saat aplikasi berjalan. Deklarasi ini +hanya ada di manifes saat aplikasi dibuat dan diuji; + deklarasi dihapus sebelum aplikasi dipublikasikan.</li> + +<li>Mendeklarasikan tingkat minimum API Android yang diperlukan +aplikasi.</li> + +<li>Mencantumkan daftar pustaka yang harus ditautkan aplikasi.</li> +</ul> + + +<h2 id="filestruct">Struktur File Manifes</h2> + +<p> +Diagram di bawah ini menampilkan struktur umum file manifes dan setiap +elemen yang bisa ditampungnya. Setiap elemen, bersama +atributnya, didokumentasikan secara lengkap dalam file terpisah. Untuk melihat +informasi terperinci tentang setiap elemen, klik nama elemen dalam diagram, +dalam daftar abjad elemen yang mengikuti diagram, atau penyebutan nama +elemen lainnya. +</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> + +<a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> + + <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission /></a> + <a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission /></a> + <a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree /></a> + <a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group /></a> + <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation /></a> + <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk /></a> + <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration /></a> <!-- ##api level 3## --> + <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature /></a> <!-- ##api level 4## --> + <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens /></a> <!-- ##api level 4## --> + <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html"><compatible-screens /></a> <!-- ##api level 9## --> + <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture /></a> <!-- ##api level 11## --> + + <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> + + <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> + <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> + <a href="{@docRoot}guide/topics/manifest/action-element.html"><action /></a> + <a href="{@docRoot}guide/topics/manifest/category-element.html"><category /></a> + <a href="{@docRoot}guide/topics/manifest/data-element.html"><data /></a> + <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> + <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> + <a href="{@docRoot}guide/topics/manifest/activity-element.html"></activity></a> + + <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a> + <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> + <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> + <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"></activity-alias></a> + + <a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a> + <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> + <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data/></a> + <a href="{@docRoot}guide/topics/manifest/service-element.html"></service></a> + + <a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a> + <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> + <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> + <a href="{@docRoot}guide/topics/manifest/receiver-element.html"></receiver></a> + + <a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a> + <a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission /></a> + <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> + <a href="{@docRoot}guide/topics/manifest/path-permission-element.html"><path-permission /></a> + <a href="{@docRoot}guide/topics/manifest/provider-element.html"></provider></a> + + <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library /></a> + + <a href="{@docRoot}guide/topics/manifest/application-element.html"></application></a> + +<a href="{@docRoot}guide/topics/manifest/manifest-element.html"></manifest></a> +</pre> + +<p> +Semua elemen yang bisa muncul dalam file manifes tercantum di bawah ini +dalam urutan abjad. Ini adalah satu-satunya elemen legal; Anda tidak bisa +menambahkan elemen atau atribut sendiri. +</p> + +<p style="margin-left: 2em"> +<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code> <!-- ##api level 4## --> +<br/><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code> <!-- ##api level 3## --> +<br/><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code> <!-- ##api level 4## --> +<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> +<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> +</p> + + + + +<h2 id="filec">Konvensi File</h2> + +<p> +Sebagian konvensi dan aturan berlaku secara umum untuk semua elemen +dan atribut di manifes: +</p> + +<dl> +<dt><b>Elemen</b></dt> +<dd>Hanya elemen +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> dan +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +yang diwajibkan, masing-masing harus ada dan hanya boleh terjadi sekali. +Umumnya elemen lain bisa terjadi berkali-kali atau sama sekali tidak terjadi — meskipun +setidaknya sebagian dari elemen itu harus ada untuk agar manifes mencapai sesuatu yang +berarti. + +<p> +Jika elemen tidak berisi apa pun, berarti elemen itu berisi elemen lain. +Semua nilai diatur melalui atribut, bukan sebagai data karakter dalam elemen. +</p> + +<p> +Elemen yang sama tingkatan umumnya tidak diurutkan. Misalnya, elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>, dan +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> +bisa dicampur dalam urutan apa pun. (Elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> + merupakan eksepsi untuk aturan ini: Elemen ini harus mengikuti +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +ini aliasnya.) +</p></dd> + +<dt><b>Atribut</b></dt> +<dd>Secara formal, semua atribut opsional. Akan tetapi, ada sebagian +yang harus ditetapkan agar elemen bisa mencapai tujuannya. Gunakan +dokumentasi sebagai panduan. Bagi atribut yang benar-benar opsional, ini menyebutkan +nilai default atau menyatakan apa yang terjadi jika tidak ada spesifikasi. + +<p>Selain untuk beberapa atribut elemen akar +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code>, + semua nama atribut dimulai dengan awalan {@code android:} — +misalnya, {@code android:alwaysRetainTaskState}. Karena awalan ini universal, dokumentasi umumnya meniadakannya saat mengacu atribut +dengan nama. +</p></dd> + +<dt><b>Mendeklarasikan nama kelas</b></dt> +<dd>Banyak elemen berhubungan dengan objek Java, termasuk elemen +aplikasi itu sendiri (elemen +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +) dan aktivitas komponen — utamanya +(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>), +layanan +(<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>), +penerima siaran +(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>), +dan penyedia konten +(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>). + +<p> +Jika mendefinisikan subkelas, seperti yang selalu Anda definisikan untuk kelas komponen +({@link android.app.Activity}, {@link android.app.Service}, +{@link android.content.BroadcastReceiver}, dan {@link android.content.ContentProvider}), +subkelas dideklarasikan melalui atribut {@code name}. Nama harus menyertakan tujuan +paket lengkap. +Misalnya, subkelas {@link android.app.Service} mungkin dideklarasikan sebagai berikut: +</p> + +<pre><manifest . . . > + <application . . . > + <service android:name="com.example.project.SecretService" . . . > + . . . + </service> + . . . + </application> +</manifest></pre> + +<p> +Akan tetapi, sebagai shorthand, jika karakter pertama string adalah titik, +string akan ditambahkan ke nama paket aplikasi (seperti yang ditetapkan dalam elemen +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> + melalui atribut +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code> +). Penetapan berikut sama dengan di atas: +</p> + +<pre><manifest package="com.example.project" . . . > + <application . . . > + <service android:name=".SecretService" . . . > + . . . + </service> + . . . + </application> +</manifest></pre> + +<p> +Saat memulai komponen, Android akan membuat instance subkelas yang diberi nama. +Jika subkelas tidak ditetapkan, maka akak dibuat instance kelas dasar. +</p></dd> + +<dt><b>Banyak nilai</b></dt> +<dd>Jika lebih dari satu nilai yang dapat ditetapkan, elemen ini hampir selalu +diulangi, bukan menampilkan daftar banyak nilai dalam satu elemen. +Misalnya, filter intent dapat mencantumkan beberapa tindakan: + +<pre><intent-filter . . . > + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.INSERT" /> + <action android:name="android.intent.action.DELETE" /> + . . . +</intent-filter></pre></dd> + +<dt><b>Nilai sumber daya</b></dt> +<dd>Beberapa atribut memiliki nilai yang bisa ditampilkan kepada pengguna — misalnya +, label dan ikon aktivitas. Nilai atribut ini +harus dilokalkan dan karenanya ditetapkan dari sumber daya atau tema. Nilai sumber +daya dinyatakan dalam format berikut,</p> + +<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>:<i>name</i>}</p> + +<p> +dalam hal ini nama <i>package</i> boleh dihilangkan jika sumber daya ada dalam paket yang sama dengan +dengan aplikasi, <i>type</i> adalah tipe sumber daya — seperti "string" atau +"drawable" — dan <i>name</i> adalah nama yang mengidentifikasi sumber daya tertentu. +Misalnya: +</p> + +<pre><activity android:icon="@drawable/smallPic" . . . ></pre> + +<p> +Nilai tema diekspresikan dengan cara yang sama, namun dengan awal '{@code ?}' +dan bukan '{@code @}': +</p> + +<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>:<i>name</i>} +</p></dd> + +<dt><b>Nilai-nilai string</b></dt> +<dd>Bila nilai atribut adalah string, dua garis miring kiri ('{@code \\}') +harus digunakan untuk meninggalkan karakter — misalnya, '{@code \\n}' untuk +baris baru atau '{@code \\uxxxx}' untuk karakter Unicode.</dd> +</dl> + + +<h2 id="filef">Fitur File</h2> + +<p> +Bagian berikut menjelaskan cara menerapkan sebagian fitur Android +dalam file manifest. +</p> + + +<h3 id="ifs">Filter Intent</h3> + +<p> +Komponen inti dari aplikasi (aktivitasnya, layanannya, dan penerima +siaran) diaktifkan oleh <i>intent</i>. Intent adalah +sekumpulan informasi (objek {@link android.content.Intent}) yang menjelaskan +tindakan yang diinginkan — termasuk data yang akan ditindaklanjuti, kategori +komponen yang harus melakukan tindakan, dan petunjuk terkait lainnya. +Android mencari komponen yang sesuai untuk merespons intent, meluncurkan +instance komponen baru jika diperlukan, dan meneruskannya ke +objek Intent. +</p> + +<p> +Komponen mengiklankan kemampuannya — jenis intent yang bisa diresponsnya + — melalui <i>filter intent</i>. Karena sistem Android +harus mempelajari intent yang dapat ditangani komponen sebelum meluncurkan komponen, +filter intent ditetapkan dalam manifes sebagai elemen +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +. Sebuah komponen dapat memiliki filter dalam jumlah berapa saja, masing-masing menjelaskan +kemampuan yang berbeda. +</p> + +<p> +Intent yang secara eksplisit menamai komponen target akan mengaktifkan komponen itu; +filter tidak berperan. Namun intent yang tidak menetapkan target +dengan nama dapat mengaktifkan komponen hanya jika dapat melewati salah satu filter +komponen. +</p> + +<p> +Untuk informasi tentang cara objek Intent diuji terhadap filter intent, +lihat dokumen terpisah, +<a href="{@docRoot}guide/components/intents-filters.html">Intent +dan Filter Intent</a>. +</p> + + +<h3 id="iconlabel">Ikon dan Label</h3> + +<p> +Sejumlah elemen memiliki atribut {@code icon} dan {@code label} untuk +ikon kecil dan label teks yang bisa ditampilkan kepada pengguna. Sebagian ada juga yang memiliki atribut +{@code description}untuk teks penjelasan yang lebih panjang yang juga bisa +ditampilkan pada layar. Misalnya, elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> + memiliki ketiga atribut ini, jadi saat pengguna ditanya apakah akan +memberi izin bagi aplikasi yang memintanya, ikon yang mewakili +izin, nama izin, dan keterangan yang +mengikutinya bisa ditampilkan kepada pengguna. +</p> + +<p> +Dalam setiap kasus, ikon dan label yang ditetapkan dalam elemen yang memuatnya menjadi +{@code icon} default dan pengaturan {@code label} untuk semua subelemen kontainer ini. +Karena itu, ikon dan label yang ditetapkan dalam elemen +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +adalah ikon dan label default untuk setiap komponen aplikasi. +Demikian pula, ikon dan label yang ditetapkan untuk komponen — misalnya, elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +— adalah pengaturan default untuk setiap elemen komponen +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +. Jika elemen +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +menetapkan label, namun suatu aktivitas dan filter intent-nya tidak menetapkan label, +maka label aplikasi akan dianggap sama-sama sebagai label aktvitas dan +filter intent. +</p> + +<p> +Ikon dan label yang ditetapkan untuk filter intent digunakan untuk mewakili komponen +kapan saja komponen ditampilkan kepada pengguna saat memenuhi fungsi yang +diiklankan oleh filter. Misalnya, filter dengan pengaturan +"{@code android.intent.action.MAIN}" dan +"{@code android.intent.category.LAUNCHER}" mengiklankan aktivitas +sebagai aktivitas yang memulai aplikasi—, yaitu +sebagai salah satu aktivitas yang harus ditampilkan dalam launcher aplikasi. Ikon dan label yang +diatur dalam filter karenanya adalah ikon dan label yang ditampilkan dalam launcher. +</p> + + +<h3 id="perms">Izin</h3> + +<p> +Sebuah <i>izin</i> adalah pembatasan yang membatasi akses ke bagian +kode atau ke data pada perangkat. Pembatasan diberlakukan untuk melindungi data dan kode +penting yang bisa disalahgunakan untuk mengganggu atau merusak pengalaman pengguna. +</p> + +<p> +Setiap izin diidentifikasi melalui label yang unik. Sering kali, label menunjukkan +tindakan yang dibatasi. Misalnya, berikut ini adalah beberapa izin yang didefinisikan +oleh Android: +</p> + +<p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS} +<br/>{@code android.permission.READ_OWNER_DATA} +<br/>{@code android.permission.SET_WALLPAPER} +<br/>{@code android.permission.DEVICE_POWER}</p> + +<p> +Sebuah fitur bisa dilindungi paling banyak oleh satu izin. +</p> + +<p> +Jika aplikasi memerlukan akses ke fitur yang dilindungi oleh izin, +aplikasi harus mendeklarasikan bahwa aplikasi memerlukan izin itu dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> + dalam manifes. Kemudian, bila aplikasi telah diinstal pada +perangkat, installer akan menentukan apakah izin yang diminta akan diberikan atau tidak +dengan memeriksa otoritas yang menandatangani +sertifikat aplikasi dan, dalam beberapa kasus, bertanya pada pengguna. +Jika izin diberikan, aplikasi tersebut bisa menggunakan +fitur yang dilindungi. Jika tidak, upaya aplikasi untuk mengakses fitur tersebut akan gagal +tanpa ada pemberitahuan apa pun kepada pengguna. +</p> + +<p> +Aplikasi juga bisa melindungi komponennya sendiri (aktivitas, layanan, +penerima siaran, dan penyedia konten) dengan izin. Aplikasi bisa menerapkan +izin mana pun yang didefinisikan oleh Android (tercantum dalam +{@link android.Manifest.permission android.Manifest.permission}) atau dideklarasikan +oleh aplikasi lain. Atau aplikasi bisa mendefinisikannya sendiri. Izin baru dideklarasikan +dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +. Misalnya, aktivitas dapat dilindungi sebagai berikut: +</p> + +<pre> +<manifest . . . > + <permission android:name="com.example.project.DEBIT_ACCT" . . . /> + <uses-permission android:name="com.example.project.DEBIT_ACCT" /> + . . . + <application . . .> + <activity android:name="com.example.project.FreneticActivity" + android:permission="com.example.project.DEBIT_ACCT" + . . . > + . . . + </activity> + </application> +</manifest> +</pre> + +<p> +Perhatikan, dalam contoh ini izin {@code DEBIT_ACCT} tidak hanya +dideklarasikan dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +, penggunaannya juga diminta dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> +. Penggunaannya harus diminta agar komponen +aplikasi lainnya bisa menjalankan aktivitas yang dilindungi, meskipun perlindungan itu +diberlakukan oleh aplikasi itu sendiri. +</p> + +<p> +Dalam contoh yang sama, jika atribut {@code permission} ditetapkan +untuk izin yang dideklarasikan di tempat lain +lain (seperti {@code android.permission.CALL_EMERGENCY_NUMBERS}, maka atribut +tidak perlu mendeklarasikannya lagi dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +. Akan tetapi, penggunaannya masih perlu dengan +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code>. +</p> + +<p> +Elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> +mendeklarasikan namespace untuk grup izin yang akan didefinisikan dalam +kode. Dan +<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> +mendefinisikan label untuk seperangkat izin (yang sama-sama dideklarasikan dalam manifes dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +dan yang dideklarasikan di tempat lain). Ini hanya memengaruhi cara izin +dikelompokkan saat ditampilkan kepada pengguna. Elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> + tidak menetapkan izin mana dimiliki grup; +elemen hanya memberi nama grup. Izin ditempatkan dalam grup +dengan memberikan nama grup ke elemen +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> + melalui atribut +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code> +. +</p> + + +<h3 id="libs">Pustaka</h3> + +<p> +Setiap aplikasi ditautkan dengan pustaka default Android, yang +menyertakan paket dasar untuk membangun aplikasi (dengan kelas umum +seperti Activity, Service, Intent, View, Button, Application, ContentProvider, +dan sebagainya). +</p> + +<p> +Akan tetapi, sebagian paket berada dalam pustakanya sendiri. Jika aplikasi Anda +menggunakan kode salah satu paket ini, aplikasi secara eksplisit meminta untuk ditautkan dengan +paket tersebut. Manifes harus berisi elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> yang +terpisah untuk menamai setiap pustaka. (Nama pustaka bisa ditemukan +dalam dokumentasi paket.) +</p> diff --git a/docs/html-intl/intl/in/guide/topics/providers/calendar-provider.jd b/docs/html-intl/intl/in/guide/topics/providers/calendar-provider.jd new file mode 100644 index 000000000000..76bc9915cbd7 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/calendar-provider.jd @@ -0,0 +1,1184 @@ +page.title=Penyedia Kalender +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#overview">Dasar-Dasar</a></li> + <li><a href="#manifest">Izin Pengguna</a></li> + <li><a href="#calendar">Tabel kalender</a> +<ol> + <li><a href="#query">Membuat query kalender</a></li> + <li><a href="#modify-calendar">Memodifikasi kalender</a></li> + <li><a href="#insert-calendar">Menyisipkan kalender</a></li> + </ol> + </li> + <li><a href="#events">Tabel Events</a> +<ol> + <li><a href="#add-event">Menambahkan Kejadian</a></li> + <li><a href="#update-event">Memperbarui Kejadian</a></li> + <li><a href="#delete-event">Menghapus Kejadian</a></li> + </ol> + </li> + <li><a href="#attendees">Tabel peserta</a> +<ol> + <li><a href="#add-attendees">Menambahkan Peserta</a></li> + </ol> + </li> + <li><a href="#reminders">Tabel pengingat</a> +<ol> + <li><a href="#add-reminders">Menambahkan Pengingat</a></li> + </ol> + </li> + <li><a href="#instances">Tabel Instances</a> + <ol> + <li><a href="#query-instances">Membuat query tabel Instance</a></li> + </ol></li> + <li><a href="#intents">Intent Kalender</a> + <ol> + <li><a href="#intent-insert">Menggunakan intent untuk menyisipkan kejadian</a></li> + <li><a href="#intent-edit">Menggunakan intent untuk mengedit kejadian</a></li> + <li><a href="#intent-view">Menggunakan intent untuk menampilkan data kalender</a></li> + </ol> + </li> + + <li><a href="#sync-adapter">Adaptor Sinkronisasi</a></li> +</ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.provider.CalendarContract.Calendars}</li> + <li>{@link android.provider.CalendarContract.Events}</li> + <li>{@link android.provider.CalendarContract.Attendees}</li> + <li>{@link android.provider.CalendarContract.Reminders}</li> + </ol> +</div> +</div> + +<p>Penyedia Kalender adalah repository untuk kejadian kalender seorang pengguna. API +Penyedia Kalender memungkinkan Anda melakukan query, menyisipkan, memperbarui, dan menghapus +pada kalender, kejadian, peserta, pengingat, dan seterusnya.</p> + + +<p>API Penyedia Kalender bisa digunakan oleh aplikasi dan adaptor sinkronisasi. Aturannya +bervariasi menurut tipe program yang membuat panggilan. Dokumen ini +terutama berfokus pada penggunaan API Penyedia Kalender sebagai sebuah aplikasi. Untuk +pembahasan ragam adaptor sinkronisasi, lihat +<a href="#sync-adapter">Adaptor Sinkronisasi</a>.</p> + + +<p>Biasanya, untuk membaca atau menulis data kalender, manifes aplikasi harus +berisi izin yang sesuai, yang dijelaskan dalam <a href="#manifest">Izin +Pengguna</a>. Untuk mempermudah dilakukannya operasi umum, +Penyedia Kalender menyediakan satu set intent, seperti dijelaskan dalam <a href="#intents">Intent +Kalender</a>. Semua intent ini membawa pengguna ke aplikasi Kalender untuk menyisipkan, menampilkan, +dan mengedit kejadian. Pengguna berinteraksi dengan aplikasi Kalender kemudian +kembali ke aplikasi semula. Jadi, aplikasi Anda tidak perlu meminta izin, +juga tidak perlu menyediakan antarmuka pengguna untuk menampilkan atau membuat kejadian.</p> + +<h2 id="overview">Dasar-Dasar</h2> + +<p><a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia konten</a> menyimpan data dan menjadikannya bisa diakses oleh +aplikasi. Penyedia konten yang ditawarkan oleh platform Android (termasuk Penyedia Kalender) biasanya mengekspos data sebagai satu set tabel berdasarkan +model database relasional, dengan tiap baris berupa record dan tiap kolom berupa data +yang memiliki tipe dan arti tertentu. Melalui API Penyedia Kalender, aplikasi +dan adaptor sinkronisasi bisa mendapatkan akses baca/tulis ke tabel-tabel database yang menyimpan +data kalender seorang pengguna.</p> + +<p>Setiap penyedia konten membuka sebuah URI publik (yang dibungkus sebagai objek +{@link android.net.Uri} +) yang mengidentifikasikan set datanya secara unik. Penyedia konten yang mengontrol + beberapa set data (beberapa tabel) mengekspos URI terpisah untuk tiap set. Semua +URI untuk penyedia diawali dengan string "content://". String ini +mengidentifikasi data sebagai dikontrol oleh penyedia konten. Penyedia Kalender +mendefinisikan konstanta untuk URI masing-masing kelas (tabel). URI ini +memiliki format <code><em><class></em>.CONTENT_URI</code>. Misalnya, +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}.</p> + +<p>Gambar 1 menampilkan representasi grafis model data Penyedia Kalender. Gambar ini menampilkan +tabel dan bidang utama yang saling berkaitan.</p> + +<img src="{@docRoot}images/providers/datamodel.png" alt="Calendar Provider Data Model" /> +<p class="img-caption"><strong>Gambar 1.</strong> Model data Penyedia Kalender.</p> + +<p>Seorang pengguna bisa memiliki beberapa kalender, dan kalender yang berbeda bisa dikaitkan dengan tipe akun yang berbeda (Google Calendar, Exchange, dan seterusnya).</p> + +<p>{@link android.provider.CalendarContract} mendefinisikan model data dari informasi yang terkait dengan kalender dan kejadian. Data ini disimpan di sejumlah tabel, yang dicantumkan di bawah ini.</p> + +<table> + <tr> + <th>Tabel (Kelas)</th> + <th>Keterangan</th> + </tr> + <tr> + <td><p>{@link android.provider.CalendarContract.Calendars}</p></td> + + <td>Tabel ini menyimpan +informasi khusus kalender. Tiap baris dalam tabel ini berisi data untuk +satu kalender, seperti nama, warna, informasi sinkronisasi, dan seterusnya.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Events}</td> + + <td>Tabel ini menyimpan +informasi khusus kejadian. Tiap baris dalam tabel ini berisi informasi untuk satu +kejadian—misalnya, judul kejadian, lokasi, waktu mulai, waktu +selesai, dan seterusnya. Kejadian bisa terjadi satu kali atau bisa berulang beberapa kali. Peserta, +pengingat, dan properti perluasan disimpan dalam tabel terpisah. +Masing-masing memiliki sebuah {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +yang mengacu {@link android.provider.BaseColumns#_ID} dalam tabel Events.</td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances}</td> + + <td>Tabel ini menyimpan +waktu mulai dan waktu selesai setiap bentuk kejadian. Tiap baris dalam tabel ini +mewakili satu bentuk kejadian. Untuk kejadian satu kali ada pemetaan 1:1 +antara instance dan kejadian. Untuk kejadian berulang, beberapa baris akan dibuat +secara otomatis yang sesuai dengan beberapa kejadian itu.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Attendees}</td> + + <td>Tabel ini menyimpan +informasi peserta (tamu) kejadian. Tiap baris mewakili satu tamu +kejadian. Ini menetapkan tipe tamu dan respons kehadiran tamu +untuk kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Reminders}</td> + + <td>Tabel ini menyimpan +data peringatan/pemberitahuan. Tiap baris mewakili satu peringatan untuk sebuah kejadian. Sebuah +kejadian bisa memiliki beberapa pengingat. Jumlah maksimum pengingat per kejadian +ditetapkan dalam +{@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS}, +yang diatur oleh adaptor sinkronisasi yang +memiliki kalender yang diberikan. Pengingat ditetapkan dalam menit sebelum kejadian +dan memiliki metode yang menentukan cara pengguna akan diperingatkan.</td> + </tr> + +</table> + +<p>API Penyedia Kalender didesain agar luwes dan tangguh. Sementara itu +, Anda perlu memberikan pengalaman pengguna akhir yang baik dan +melindungi integritas kalender dan datanya. Untuk mencapainya, berikut ini adalah +beberapa hal yang harus diingat saat menggunakan API ini:</p> + +<ul> + +<li><strong>Menyisipkan, memperbarui, dan menampilkan kejadian kalender.</strong> Untuk menyisipkan, mengubah, dan membaca kejadian secara langsung dari Penyedia Kalender, Anda memerlukan <a href="#manifest">izin</a> yang sesuai. Akan tetapi, jika Anda tidak sedang membuat aplikasi atau adaptor sinkronisasi kalender berfitur lengkap, maka tidak perlu meminta izin. Sebagai gantinya, Anda bisa menggunakan intent yang didukung oleh aplikasi Kalender Android untuk menyerahkan operasi baca dan tulis ke aplikasi itu. Bila menggunakan intent, aplikasi Anda akan mengirim pengguna ke aplikasi Kalender untuk melakukan operasi yang diinginkan +dalam sebuah formulir yang sudah diisi. Setelah operasi selesai, formulir dikembalikan ke aplikasi Anda. +Dengan mendesain aplikasi untuk melakukan operasi umum melalui Kalender, +Anda akan memberi pengguna sebuah antarmuka pengguna yang konsisten dan tangguh. Inilah +pendekatan yang disarankan. Untuk informasi selengkapnya, lihat <a href="#intents">Intent +Kalender</a>.</p> + + +<li><strong>Adaptor sinkronisasi.</strong> Adaptor sinkronisasi menyinkronkan data kalender +pada perangkat pengguna dengan server atau sumber data lain. Dalam tabel +{@link android.provider.CalendarContract.Calendars} dan +{@link android.provider.CalendarContract.Events}, +ada kolom yang dicadangkan untuk digunakan adaptor sinkronisasi. +Penyedia dan aplikasi tidak boleh memodifikasinya. Sebenarnya, tabel-tabel itu tidak +terlihat kecuali jika diakses sebagai adaptor sinkronisasi. Untuk informasi selengkapnya tentang +adaptor sinkronisasi, lihat <a href="#sync-adapter">Adaptor Sinkronisasi</a>.</li> + +</ul> + + +<h2 id="manifest">Izin Pengguna</h2> + +<p>Untuk membaca data kalender, aplikasi harus menyertakan izin {@link +android.Manifest.permission#READ_CALENDAR} dalam file manifesnya. File +harus menyertakan izin {@link android.Manifest.permission#WRITE_CALENDAR} +untuk menghapus, menyisipkan, atau memperbarui data kalender:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android"...> + <uses-sdk android:minSdkVersion="14" /> + <uses-permission android:name="android.permission.READ_CALENDAR" /> + <uses-permission android:name="android.permission.WRITE_CALENDAR" /> + ... +</manifest> +</pre> + + +<h2 id="calendar">Tabel Kalender</h2> + +<p>Tabel {@link android.provider.CalendarContract.Calendars} berisi data +untuk tiap kalender. Kolom-kolom +berikut ini bisa ditulisi oleh aplikasi maupun <a href="#sync-adapter">adaptor sinkronisasi</a>. +Untuk mengetahui daftar lengkap bidang-bidang yang didukung, lihat +acuan {@link android.provider.CalendarContract.Calendars}.</p> +<table> + <tr> + <th>Konstanta</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#NAME}</td> + <td>Nama kalender.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#CALENDAR_DISPLAY_NAME}</td> + <td>Nama kalender ini yang ditampilkan kepada pengguna.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Calendars#VISIBLE}</td> + + <td>Sebuah boolean yang menunjukkan apakah kalender dipilih untuk ditampilkan. Nilai +0 menunjukkan bahwa kejadian yang terkait dengan kalender ini tidak boleh +ditampilkan. Nilai 1 menunjukkan bahwa kejadian yang terkait dengan kalender ini harus +ditampilkan. Nilai ini memengaruhi pembuatan baris dalam tabel {@link +android.provider.CalendarContract.Instances}.</td> + + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.CalendarColumns#SYNC_EVENTS}</td> + + <td>Sebuah boolean yang menunjukkan apakah kalender harus disinkronkan dan apakah +kejadiannya harus disimpan pada perangkat. Nilai 0 berarti jangan menyinkronkan kalender ini atau +simpan kejadiannya pada perangkat. Nilai 1 berarti menyinkronkan kejadian untuk kalender ini +dan simpan kejadiannya pada perangkat.</td> + </tr> +</table> + +<h3 id="query">Membuat query kalender</h3> + +<p>Berikut ini adalah contoh yang menampilkan cara mendapatkan kalender yang dimiliki oleh +pengguna tertentu. Untuk memudahkan, dalam contoh ini, operasi query ditampilkan dalam +thread antarmuka pengguna ("thread utama"). Dalam praktiknya, hal ini harus dilakukan dalam +thread asinkron, sebagai ganti pada thread utama. Untuk diskusi selengkapnya, lihat +<a href="{@docRoot}guide/components/loaders.html">Loader</a>. Jika Anda tidak sekadar +membaca data melainkan memodifikasinya, lihat {@link android.content.AsyncQueryHandler}. +</p> + + +<pre> +// Projection array. Creating indices for this array instead of doing +// dynamic lookups improves performance. +public static final String[] EVENT_PROJECTION = new String[] { + Calendars._ID, // 0 + Calendars.ACCOUNT_NAME, // 1 + Calendars.CALENDAR_DISPLAY_NAME, // 2 + Calendars.OWNER_ACCOUNT // 3 +}; + +// The indices for the projection array above. +private static final int PROJECTION_ID_INDEX = 0; +private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; +private static final int PROJECTION_DISPLAY_NAME_INDEX = 2; +private static final int PROJECTION_OWNER_ACCOUNT_INDEX = 3;</pre> + + +<div class="sidebox-wrapper"> <div class="sidebox"> <h3>Mengapa Anda harus menyertakan +ACCOUNT_TYPE?</h3> <p>Jika Anda membuat query pada {@link +android.provider.CalendarContract.Calendars#ACCOUNT_NAME +Calendars.ACCOUNT_NAME}, Anda juga harus menyertakan +{@link android.provider.CalendarContract.Calendars#ACCOUNT_TYPE Calendars.ACCOUNT_TYPE} +dalam pemilihan. Itu karena akun yang bersangkutan +hanya dianggap unik mengingat <code>ACCOUNT_NAME</code> dan +<code>ACCOUNT_TYPE</code>-nya. <code>ACCOUNT_TYPE</code> adalah string yang sesuai dengan +autentikator akun yang digunakan bila akun didaftarkan dengan +{@link android.accounts.AccountManager}. Ada juga sebuah tipe akun khusus yang disebut {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} untuk kalender +yang tidak terkait dengan akun perangkat. Akun {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} tidak +disinkronkan.</p> </div> </div> + + +<p> Di bagian berikutnya pada contoh ini, Anda akan membuat query. Pemilihan +akan menetapkan kriteria untuk query. Dalam contoh ini, query mencari +kalender yang memiliki <code>ACCOUNT_NAME</code> +"sampleuser@google.com", <code>ACCOUNT_TYPE</code> +"com.google", dan <code>OWNER_ACCOUNT</code> +"sampleuser@google.com". Jika Anda ingin melihat semua kalender yang +telah ditampilkan pengguna, bukan hanya kalender yang dimiliki pengguna, hilangkan <code>OWNER_ACCOUNT</code>. +Query tersebut akan menghasilkan objek {@link android.database.Cursor} +yang bisa Anda gunakan untuk menyusuri set hasil yang dikembalikan oleh +query database. Untuk diskusi selengkapnya tentang penggunaan query dalam penyedia konten, +lihat <a href="{@docRoot}guide/topics/providers/content-providers.html">Penyedia Kalender</a>.</p> + + +<pre>// Run query +Cursor cur = null; +ContentResolver cr = getContentResolver(); +Uri uri = Calendars.CONTENT_URI; +String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" + + Calendars.ACCOUNT_TYPE + " = ?) AND (" + + Calendars.OWNER_ACCOUNT + " = ?))"; +String[] selectionArgs = new String[] {"sampleuser@gmail.com", "com.google", + "sampleuser@gmail.com"}; +// Submit the query and get a Cursor object back. +cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);</pre> + +<p>Bagian berikutnya ini menggunakan kursor untuk merunut set hasil. Bagian ini menggunakan +konstanta yang disiapkan pada awal contoh ini untuk menghasilkan nilai-nilai +bagi tiap bidang.</p> + +<pre>// Use the cursor to step through the returned records +while (cur.moveToNext()) { + long calID = 0; + String displayName = null; + String accountName = null; + String ownerName = null; + + // Get the field values + calID = cur.getLong(PROJECTION_ID_INDEX); + displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX); + accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX); + ownerName = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX); + + // Do something with the values... + + ... +} +</pre> + +<h3 id="modify-calendar">Memodifikasi kalender</h3> + +<p>Untuk melakukan pembaruan kalender, Anda bisa menyediakan {@link +android.provider.BaseColumns#_ID} kalender itu baik sebagai ID yang ditambahkan ke +URI + +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +atau sebagai item pemilihan pertama. Pemilihan +harus diawali dengan <code>"_id=?"</code>, dan +<code>selectionArg</code> pertama harus berupa {@link +android.provider.BaseColumns#_ID} kalender. +Anda juga bisa melakukan pembaruan dengan menuliskan kode ID dalam URI. Contoh ini mengubah +nama tampilan kalender dengan pendekatan +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +:</p> + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long calID = 2; +ContentValues values = new ContentValues(); +// The new display name for the calendar +values.put(Calendars.CALENDAR_DISPLAY_NAME, "Trevor's Calendar"); +Uri updateUri = ContentUris.withAppendedId(Calendars.CONTENT_URI, calID); +int rows = getContentResolver().update(updateUri, values, null, null); +Log.i(DEBUG_TAG, "Rows updated: " + rows);</pre> + +<h3 id="insert-calendar">Menyisipkan kalender</h2> + +<p>Kalender didesain untuk dikelola terutama oleh sebuah adaptor sinkronisasi, sehingga Anda +hanya boleh menyisipkan kalender baru sebagai adaptor sinkronisasi. Biasanya, +aplikasi hanya bisa membuat perubahan semu pada kalender, misalnya mengubah nama tampilan. Jika +perlu membuat sebuah kalender lokal, aplikasi bisa melakukannya dengan melakukan +penyisipan kalender sebagai adaptor sinkronisasi, menggunakan {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} dari {@link +android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}. +{@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} +adalah sebuah tipe akun khusus untuk kalender yang tidak +terkait dengan akun perangkat. Kalender tipe ini tidak disinkronkan dengan server. Untuk +diskusi tentang adaptor sinkronisasi, lihat <a href="#sync-adapter">Adaptor Sinkronisasi</a>.</p> + +<h2 id="events">Tabel Events</h2> + +<p>Tabel {@link android.provider.CalendarContract.Events} berisi detail +untuk tiap kejadian. Untuk menambah, memperbarui, atau menghapus kejadian, aplikasi harus +menyertakan izin {@link android.Manifest.permission#WRITE_CALENDAR} dalam +<a href="#manifest">file manifesnya</a>.</p> + +<p>Kolom-kolom Events berikut ini bisa ditulis oleh aplikasi maupun +adaptor sinkronisasi. Untuk mengetahui daftar lengkap bidang-bidang yang didukung, lihat acuan {@link +android.provider.CalendarContract.Events}.</p> + +<table> + <tr> + <th>Konstanta</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#CALENDAR_ID}</td> + <td>{@link android.provider.BaseColumns#_ID} kalender yang dimiliki kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#ORGANIZER}</td> + <td>Email pengatur (pemilik) kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#TITLE}</td> + <td>Judul kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION}</td> + <td>Tempat kejadian. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION}</td> + <td>Keterangan kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DTSTART}</td> + <td>Waktu mulai kejadian dalam milidetik UTC sejak waktu patokan. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DTEND}</td> + <td>Waktu selesai kejadian dalam milidetik UTC sejak waktu patokan. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}</td> + <td>Zona waktu kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_END_TIMEZONE}</td> + <td>Zona waktu untuk waktu selesai kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DURATION}</td> + + <td>Durasi kejadian dalam format <a href="http://tools.ietf.org/html/rfc5545#section-3.8.2.5">RFC5545</a>. +Misalnya, nilai <code>"PT1H"</code> menyatakan bahwa kejadian +akan berlangsung satu jam, dan nilai <code>"P2W"</code> menunjukkan +durasi 2 minggu. </td> + + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#ALL_DAY}</td> + + <td>Nilai 1 menunjukkan kejadian ini memakan waktu sehari penuh, seperti yang didefinisikan oleh +zona waktu lokal. Nilai 0 menunjukkan kejadian adalah kejadian biasa yang mungkin dimulai +dan selesai pada sembarang waktu selama suatu hari.</td> + + + </tr> + + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#RRULE}</td> + + <td>Aturan perulangan untuk format kejadian. Misalnya, +<code>"FREQ=WEEKLY;COUNT=10;WKST=SU"</code>. Anda bisa menemukan +contoh selengkapnya <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.3">di sini</a>.</td> + + </tr> + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#RDATE}</td> + <td>Tanggal perulangan kejadian. + Anda biasanya menggunakan {@link android.provider.CalendarContract.EventsColumns#RDATE} + bersama dengan {@link android.provider.CalendarContract.EventsColumns#RRULE} + untuk mendefinisikan satu set agregat +kejadian berulang. Untuk diskusi selengkapnya, lihat <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.2">Spesifikasi RFC5545</a>.</td> +</tr> + + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY}</td> + + <td>Jika kejadian ini dihitung sebagai waktu sibuk atau waktu bebas yang bisa +dijadwalkan. </td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_MODIFY}</td> + <td>Apakah tamu bisa memodifikasi kejadian atau tidak. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_INVITE_OTHERS}</td> + <td>Apakah tamu bisa mengundang tamu lain atau tidak. </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_SEE_GUESTS}</td> + <td>Apakah tamu bisa membaca daftar peserta atau tidak.</td> + </tr> +</table> + +<h3 id="add-event">Menambahkan Kejadian</h3> + +<p>Bila aplikasi Anda menyisipkan kejadian baru, sebaiknya Anda menggunakan +Intent {@link android.content.Intent#ACTION_INSERT INSERT}, seperti dijelaskan dalam <a href="#intent-insert">Menggunakan intent untuk menyisipkan kejadian</a>. Akan tetapi, jika +perlu, Anda bisa menyisipkan kejadian secara langsung. Bagian ini menjelaskan +caranya.</p> + + +<p>Berikut ini adalah aturan untuk menyisipkan kejadian baru: </p> +<ul> + + <li>Anda harus menyertakan {@link +android.provider.CalendarContract.EventsColumns#CALENDAR_ID} dan {@link +android.provider.CalendarContract.EventsColumns#DTSTART}.</li> + +<li>Anda harus menyertakan {@link +android.provider.CalendarContract.EventsColumns#EVENT_TIMEZONE}. Untuk mendapatkan daftar +ID zona waktu yang diinstal pada sistem, gunakan {@link +java.util.TimeZone#getAvailableIDs()}. Perhatikan bahwa aturan ini tidak berlaku jika +Anda menyisipkan kejadian melalui Intent {@link +android.content.Intent#ACTION_INSERT INSERT}, yang dijelaskan dalam <a href="#intent-insert">Menggunakan intent untuk menyisipkan kejadian</a>—dalam +skenario itu, sebuah zona waktu default akan diberikan.</li> + + <li>Untuk kejadian tidak-berulang, Anda harus menyertakan {@link +android.provider.CalendarContract.EventsColumns#DTEND}. </li> + + + <li>Untuk kejadian berulang, Anda harus menyertakan sebuah {@link +android.provider.CalendarContract.EventsColumns#DURATION} selain {@link +android.provider.CalendarContract.EventsColumns#RRULE} atau {@link +android.provider.CalendarContract.EventsColumns#RDATE}. Perhatikan bahwa aturan ini tidak berlaku jika +Anda menyisipkan kejadian melalui Intent {@link +android.content.Intent#ACTION_INSERT INSERT}, yang dijelaskan dalam <a href="#intent-insert">Menggunakan intent untuk menyisipkan kejadian</a>—dalam +skenario itu, Anda bisa menggunakan {@link +android.provider.CalendarContract.EventsColumns#RRULE} bersama {@link android.provider.CalendarContract.EventsColumns#DTSTART} dan {@link android.provider.CalendarContract.EventsColumns#DTEND}, dan aplikasi Calendar +akan mengubahnya menjadi durasi secara otomatis.</li> + +</ul> + +<p>Berikut ini adalah contoh penyisipan kejadian. Penyisipan ini dilakukan dalam thread UI +demi kemudahan. Dalam praktiknya, penyisipan dan pembaruan harus dilakukan di +thread asinkron untuk memindahkan tindakan ke dalam thread latar belakang. Untuk +informasi selengkapnya, lihat {@link android.content.AsyncQueryHandler}.</p> + + +<pre> +long calID = 3; +long startMillis = 0; +long endMillis = 0; +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2012, 9, 14, 7, 30); +startMillis = beginTime.getTimeInMillis(); +Calendar endTime = Calendar.getInstance(); +endTime.set(2012, 9, 14, 8, 45); +endMillis = endTime.getTimeInMillis(); +... + +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Events.DTSTART, startMillis); +values.put(Events.DTEND, endMillis); +values.put(Events.TITLE, "Jazzercise"); +values.put(Events.DESCRIPTION, "Group workout"); +values.put(Events.CALENDAR_ID, calID); +values.put(Events.EVENT_TIMEZONE, "America/Los_Angeles"); +Uri uri = cr.insert(Events.CONTENT_URI, values); + +// get the event ID that is the last element in the Uri +long eventID = Long.parseLong(uri.getLastPathSegment()); +// +// ... do something with event ID +// +//</pre> + +<p class="note"><strong>Catatan:</strong> Perhatikan cara contoh ini menangkap ID kejadian +setelah kejadian dibuat. Inilah cara termudah untuk mendapatkan ID kejadian. Anda akan sering +memerlukan ID kejadian untuk melakukan operasi kalender lainnya—misalnya, untuk menambahkan +peserta atau pengingat ke kejadian.</p> + + +<h3 id="update-event">Memperbarui Kejadian</h3> + +<p>Bila aplikasi Anda ingin memperbolehkan pengguna mengedit kejadian, sebaiknya +gunakan Intent {@link android.content.Intent#ACTION_EDIT EDIT}, seperti +dijelaskan dalam <a href="#intent-edit">Menggunakan intent untuk mengedit kejadian</a>. +Akan tetapi, jika perlu, Anda bisa mengedit kejadian secara langsung. Untuk melakukan pembaruan +suatu kejadian, Anda bisa memberikan <code>_ID</code> +kejadian itu sebagai ID yang ditambahkan ke URI ({@link +android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +atau sebagai item pemilihan pertama. +Pemilihan harus dimulai dengan <code>"_id=?"</code>, dan +<code>selectionArg</code> yang pertama harus berupa <code>_ID</code> kejadian. Anda juga bisa +melakukan pembaruan dengan menggunakan pemilihan tanpa ID. Berikut ini adalah contoh pembaruan +kejadian. Contoh ini mengubah judul kejadian dengan pendekatan +{@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()} +:</p> + + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long eventID = 188; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +Uri updateUri = null; +// The new title for the event +values.put(Events.TITLE, "Kickboxing"); +updateUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +int rows = getContentResolver().update(updateUri, values, null, null); +Log.i(DEBUG_TAG, "Rows updated: " + rows); </pre> + +<h3 id="delete-event">Menghapus Kejadian</h3> + +<p>Anda bisa menghapus kejadian dengan {@link +android.provider.BaseColumns#_ID} sebagai ID yang ditambahkan pada URI, atau dengan +pemilihan standar. Jika Anda menggunakan ID yang ditambahkan, Anda tidak bisa melakukan pemilihan. +Ada dua versi penghapusan: sebagai aplikasi dan sebagai adaptor sinkronisasi. Penghapusan +aplikasi mengatur kolom yang <em>dihapus</em> ke 1. Flag ini yang memberi tahu +adaptor sinkronisasi bahwa baris telah dihapus dan bahwa penghapusan ini harus +diberitahukan ke server. Penghapusan adaptor sinkronisasi menghapus kejadian dari +database bersama semua data terkaitnya. Berikut ini adalah contoh aplikasi +yang menghapus kejadian melalui {@link android.provider.BaseColumns#_ID}-nya:</p> + + +<pre>private static final String DEBUG_TAG = "MyActivity"; +... +long eventID = 201; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +Uri deleteUri = null; +deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +int rows = getContentResolver().delete(deleteUri, null, null); +Log.i(DEBUG_TAG, "Rows deleted: " + rows); +</pre> + +<h2 id="attendees">Tabel Peserta</h2> + +<p>Tiap baris tabel {@link android.provider.CalendarContract.Attendees} +mewakili satu peserta atau tamu dari sebuah kejadian. Memanggil +{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} +akan menghasilkan daftar peserta untuk +kejadian dengan {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} yang diberikan. +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} ini +harus cocok dengan {@link +android.provider.BaseColumns#_ID} kejadian tertentu.</p> + +<p>Tabel berikut mencantumkan +bidang-bidang yang bisa ditulis. Saat menyisipkan peserta baru, Anda harus menyertakan semuanya +kecuali <code>ATTENDEE_NAME</code>. +</p> + + +<table> + <tr> + <th>Konstanta</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}</td> + <td>ID kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_NAME}</td> + <td>Nama peserta.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_EMAIL}</td> + <td>Alamat email peserta.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_RELATIONSHIP}</td> + <td><p>Hubungan peserta dengan kejadian. Salah satu dari:</p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ATTENDEE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_NONE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_ORGANIZER}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_PERFORMER}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#RELATIONSHIP_SPEAKER}</li> + </ul> + </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_TYPE}</td> + <td><p>Tipe peserta. Salah satu dari: </p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_REQUIRED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#TYPE_OPTIONAL}</li> + </ul></td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS}</td> + <td><p>Status kehadiran peserta. Salah satu dari:</p> + <ul> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_ACCEPTED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_DECLINED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_INVITED}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_NONE}</li> + <li>{@link android.provider.CalendarContract.AttendeesColumns#ATTENDEE_STATUS_TENTATIVE}</li> + </ul></td> + </tr> +</table> + +<h3 id="add-attendees">Menambahkan Peserta</h3> + +<p>Berikut ini adalah contoh yang menambahkan satu peserta ke kejadian. Perhatikan bahwa +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +diperlukan:</p> + +<pre> +long eventID = 202; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Attendees.ATTENDEE_NAME, "Trevor"); +values.put(Attendees.ATTENDEE_EMAIL, "trevor@example.com"); +values.put(Attendees.ATTENDEE_RELATIONSHIP, Attendees.RELATIONSHIP_ATTENDEE); +values.put(Attendees.ATTENDEE_TYPE, Attendees.TYPE_OPTIONAL); +values.put(Attendees.ATTENDEE_STATUS, Attendees.ATTENDEE_STATUS_INVITED); +values.put(Attendees.EVENT_ID, eventID); +Uri uri = cr.insert(Attendees.CONTENT_URI, values); +</pre> + +<h2 id="reminders">Tabel Pengingat</h2> + +<p>Tiap baris tabel {@link android.provider.CalendarContract.Reminders} +mewakili satu pengingat untuk sebuah kejadian. Memanggil +{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} akan menghasilkan daftar pengingat untuk +kejadian dengan +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} yang diberikan.</p> + + +<p>Tabel berikut mencantumkan bidang-bidang yang bisa ditulis untuk pengingat. Semua bidang harus +disertakan saat menyisipkan pengingat baru. Perhatikan bahwa adaptor sinkronisasi menetapkan +tipe pengingat yang didukungnya dalam tabel {@link +android.provider.CalendarContract.Calendars}. Lihat +{@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS} +untuk detailnya.</p> + + +<table> + <tr> + <th>Konstanta</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#EVENT_ID}</td> + <td>ID kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#MINUTES}</td> + <td>Menit yang ditunggu untuk memicu kejadian pengingat.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.RemindersColumns#METHOD}</td> + <td><p>Metode alarm, seperti yang diatur pada server. Salah satu dari:</p> + <ul> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_ALERT}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_DEFAULT}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_EMAIL}</li> + <li>{@link android.provider.CalendarContract.RemindersColumns#METHOD_SMS}</li> + </ul></td> + </tr> +</table> + +<h3 id="add-reminders">Menambahkan Pengingat</h3> + +<p>Contoh ini menambahkan pengingat ke kejadian. Pengingat dipicu 15 +menit sebelum kejadian.</p> +<pre> +long eventID = 221; +... +ContentResolver cr = getContentResolver(); +ContentValues values = new ContentValues(); +values.put(Reminders.MINUTES, 15); +values.put(Reminders.EVENT_ID, eventID); +values.put(Reminders.METHOD, Reminders.METHOD_ALERT); +Uri uri = cr.insert(Reminders.CONTENT_URI, values);</pre> + +<h2 id="instances">Tabel Instances</h2> + +<p>Tabel +{@link android.provider.CalendarContract.Instances} menyimpan +waktu mulai dan waktu selesai kejadian. Tiap baris dalam tabel ini +mewakili satu bentuk kejadian. Tabel instance tidak bisa ditulis dan hanya +menyediakan sebuah cara untuk membuat query kejadian. </p> + +<p>Tabel berikut mencantumkan beberapa bidang yang bisa Anda query untuk suatu instance. Perhatikan +bahwa zona waktu didefinisikan oleh +{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE} +dan +{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_INSTANCES}.</p> + + +<table> + <tr> + <th>Konstanta</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#BEGIN}</td> + <td>Waktu mulai instance, dalam milidetik UTC.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END}</td> + <td>Waktu selesai instance, dalam milidetik UTC.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END_DAY}</td> + + <td>Hari selesai Julian dari instance, relatif terhadap +zona waktu Kalender. + +</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#END_MINUTE}</td> + + <td>Menit selesai dari instance yang diukur dari tengah malam di zona waktu +Kalender.</td> + + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#EVENT_ID}</td> + <td>Kejadian <code>_ID</code> untuk instance ini.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#START_DAY}</td> + <td>Hari mulai Julian dari instance, relatif terhadap zona waktu Kalender. + </td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.Instances#START_MINUTE}</td> + + <td>Menit mulai dari instance yang diukur dari tengah malam, relatif terhadap +zona waktu Kalender. +</td> + + </tr> + +</table> + +<h3 id="query-instances">Membuat query tabel Instance</h3> + +<p>Untuk membuat query tabel Instances, Anda perlu menetapkan rentang waktu query +dalam URI. Dalam contoh ini, {@link android.provider.CalendarContract.Instances} +mendapatkan akses ke bidang {@link +android.provider.CalendarContract.EventsColumns#TITLE} melalui +implementasi antarmuka {@link android.provider.CalendarContract.EventsColumns}-nya. +Dengan kata lain, {@link +android.provider.CalendarContract.EventsColumns#TITLE} dihasilkan melalui +tampilan database, bukan melalui query terhadap tabel {@link +android.provider.CalendarContract.Instances} mentah.</p> + +<pre> +private static final String DEBUG_TAG = "MyActivity"; +public static final String[] INSTANCE_PROJECTION = new String[] { + Instances.EVENT_ID, // 0 + Instances.BEGIN, // 1 + Instances.TITLE // 2 + }; + +// The indices for the projection array above. +private static final int PROJECTION_ID_INDEX = 0; +private static final int PROJECTION_BEGIN_INDEX = 1; +private static final int PROJECTION_TITLE_INDEX = 2; +... + +// Specify the date range you want to search for recurring +// event instances +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2011, 9, 23, 8, 0); +long startMillis = beginTime.getTimeInMillis(); +Calendar endTime = Calendar.getInstance(); +endTime.set(2011, 10, 24, 8, 0); +long endMillis = endTime.getTimeInMillis(); + +Cursor cur = null; +ContentResolver cr = getContentResolver(); + +// The ID of the recurring event whose instances you are searching +// for in the Instances table +String selection = Instances.EVENT_ID + " = ?"; +String[] selectionArgs = new String[] {"207"}; + +// Construct the query with the desired date range. +Uri.Builder builder = Instances.CONTENT_URI.buildUpon(); +ContentUris.appendId(builder, startMillis); +ContentUris.appendId(builder, endMillis); + +// Submit the query +cur = cr.query(builder.build(), + INSTANCE_PROJECTION, + selection, + selectionArgs, + null); + +while (cur.moveToNext()) { + String title = null; + long eventID = 0; + long beginVal = 0; + + // Get the field values + eventID = cur.getLong(PROJECTION_ID_INDEX); + beginVal = cur.getLong(PROJECTION_BEGIN_INDEX); + title = cur.getString(PROJECTION_TITLE_INDEX); + + // Do something with the values. + Log.i(DEBUG_TAG, "Event: " + title); + Calendar calendar = Calendar.getInstance(); + calendar.setTimeInMillis(beginVal); + DateFormat formatter = new SimpleDateFormat("MM/dd/yyyy"); + Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime())); + } + }</pre> + +<h2 id="intents">Intent Kalender</h2> +<p>Aplikasi Anda tidak memerlukan <a href="#manifest">izin</a> untuk membaca dan menulis data kalender. Sebagai gantinya, aplikasi bisa menggunakan intent yang didukung oleh aplikasi Kalender Android untuk menyerahkan operasi baca dan tulis ke aplikasi itu. Tabel berikut mencantumkan intent yang didukung oleh Penyedia Kalender:</p> +<table> + <tr> + <th>Tindakan</th> + <th>URI</th> + + <th>Keterangan</th> + <th>Ekstra</th> + </tr> + <tr> + <td><br> + {@link android.content.Intent#ACTION_VIEW VIEW} <br></td> + <td><p><code>content://com.android.calendar/time/<ms_since_epoch></code></p> + Anda juga bisa mengacu ke URI dengan +{@link android.provider.CalendarContract#CONTENT_URI CalendarContract.CONTENT_URI}. +Untuk contoh yang menggunakan intent ini, lihat <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Menggunakan intent untuk menampilkan data kalender</a>. + + </td> + <td>Membuka kalender pada waktu yang ditetapkan oleh <code><ms_since_epoch></code>.</td> + <td>Tidak ada.</td> + </tr> + <tr> + <td><p>{@link android.content.Intent#ACTION_VIEW VIEW} </p> + + </td> + <td><p><code>content://com.android.calendar/events/<event_id></code></p> + + Anda juga bisa mengacu ke URI dengan +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +Untuk contoh yang menggunakan intent ini, lihat <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Menggunakan intent untuk menampilkan data kalender</a>. + + </td> + <td>Menampilkan kejadian yang ditetapkan oleh <code><event_id></code>.</td> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br> + <br> + <br> + {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td> + </tr> + + <tr> + <td>{@link android.content.Intent#ACTION_EDIT EDIT} </td> + <td><p><code>content://com.android.calendar/events/<event_id></code></p> + + Anda juga bisa mengacu ke URI dengan +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +Untuk contoh penggunaan intent ini, lihat <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-edit">Menggunakan intent untuk mengedit kejadian</a>. + + + </td> + <td>Mengedit kejadian yang ditetapkan oleh <code><event_id></code>.</td> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}<br> + <br> + <br> + {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td> + </tr> + + <tr> + <td>{@link android.content.Intent#ACTION_EDIT EDIT} <br> + <br> + {@link android.content.Intent#ACTION_INSERT INSERT} </td> + <td><p><code>content://com.android.calendar/events</code></p> + + Anda juga bisa mengacu ke URI dengan +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. +Untuk contoh penggunaan intent ini, lihat <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-insert">Menggunakan intent untuk menyisipkan kejadian</a>. + + </td> + + <td>Membuat sebuah kejadian.</td> + <td>Ekstra apa saja yang tercantum dalam tabel di bawah.</td> + </tr> +</table> + +<p>Tabel berikut mencantumkan ekstra intent yang didukung oleh Penyedia Kalender: +</p> +<table> + <tr> + <th>Ekstra Intent</th> + <th>Keterangan</th> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#TITLE Events.TITLE}</td> + <td>Nama kejadian.</td> + </tr> + <tr> + + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME +CalendarContract.EXTRA_EVENT_BEGIN_TIME}</td> + <td>Waktu mulai kejadian dalam milidetik sejak waktu patokan.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME +CalendarContract.EXTRA_EVENT_END_TIME}</td> + + <td>Waktu selesai kejadian dalam milidetik sejak waktu patokan.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY +CalendarContract.EXTRA_EVENT_ALL_DAY}</td> + + <td>Sebuah boolean yang menunjukkan bahwa kejadian sehari penuh. Nilai bisa +<code>true</code> atau <code>false</code>.</td> </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION +Events.EVENT_LOCATION}</td> + + <td>Lokasi kejadian.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION +Events.DESCRIPTION}</td> + + <td>Keterangan kejadian.</td> + </tr> + <tr> + <td> + {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}</td> + <td>Alamat email mereka yang harus diundang berupa daftar yang dipisahkan koma.</td> + </tr> + <tr> + <td> + {@link android.provider.CalendarContract.EventsColumns#RRULE Events.RRULE}</td> + <td>Aturan perulangan kejadian.</td> + </tr> + <tr> + <td> + {@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL +Events.ACCESS_LEVEL}</td> + + <td>Apakah kejadian bersifat privat atau publik.</td> + </tr> + <tr> + <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY +Events.AVAILABILITY}</td> + + <td>Jika kejadian ini dihitung sebagai waktu sibuk atau waktu bebas yang bisa dijadwalkan.</td> + +</table> +<p>Bagian berikut menjelaskan cara menggunakan semua intent ini.</p> + + +<h3 id="intent-insert">Menggunakan intent untuk menyisipkan kejadian</h3> + +<p>Penggunaan Intent {@link android.content.Intent#ACTION_INSERT INSERT} +akan memungkinkan aplikasi Anda menyerahkan tugas penyisipan kejadian ke Kalender itu sendiri. +Dengan pendekatan ini, aplikasi Anda bahkan tidak perlu menyertakan izin {@link +android.Manifest.permission#WRITE_CALENDAR} dalam <a href="#manifest">file manifesnya</a>.</p> + + +<p>Bila pengguna menjalankan aplikasi yang menggunakan pendekatan ini, aplikasi akan mengirim +izin ke Kalender untuk menyelesaikan penambahan kejadian. Intent {@link +android.content.Intent#ACTION_INSERT INSERT} menggunakan bidang-bidang ekstra +untuk mengisi formulir lebih dahulu dengan detail kejadian dalam Kalender. Pengguna nanti bisa +membatalkan kejadian, mengedit formulir sebagaimana diperlukan, atau menyimpan kejadian ke +kalender mereka.</p> + + + +<p>Berikut ini adalah cuplikan kode yang menjadwalkan kejadian pada tanggal 19 Januari 2012, yang berjalan +dari 7:30 pagi hingga 8:30 pagi Perhatikan hal-hal berikut tentang cuplikan kode ini:</p> + +<ul> + <li>Cuplikan kode ini menetapkan {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} + sebagai URI-nya.</li> + + <li>Cuplikan kode ini menggunakan bidang-bidang ekstra {@link +android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME +CalendarContract.EXTRA_EVENT_BEGIN_TIME} dan {@link +android.provider.CalendarContract#EXTRA_EVENT_END_TIME +CalendarContract.EXTRA_EVENT_END_TIME} untuk mengisi dahulu formulir +dengan waktu kejadian. Nilai-nilai untuk waktu ini harus dalam milidetik UTC +sejak waktu patokan.</li> + + <li>Cuplikan kode ini menggunakan bidang ekstra {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL} +untuk memberikan daftar undangan yang dipisah koma, yang ditetapkan melalui alamat email.</li> + +</ul> +<pre> +Calendar beginTime = Calendar.getInstance(); +beginTime.set(2012, 0, 19, 7, 30); +Calendar endTime = Calendar.getInstance(); +endTime.set(2012, 0, 19, 8, 30); +Intent intent = new Intent(Intent.ACTION_INSERT) + .setData(Events.CONTENT_URI) + .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, beginTime.getTimeInMillis()) + .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, endTime.getTimeInMillis()) + .putExtra(Events.TITLE, "Yoga") + .putExtra(Events.DESCRIPTION, "Group class") + .putExtra(Events.EVENT_LOCATION, "The gym") + .putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY) + .putExtra(Intent.EXTRA_EMAIL, "rowan@example.com,trevor@example.com"); +startActivity(intent); +</pre> + +<h3 id="intent-edit">Menggunakan intent untuk mengedit kejadian</h3> + +<p>Anda bisa memperbarui kejadian secara langsung, seperti dijelaskan dalam <a href="#update-event">Memperbarui kejadian</a>. Namun penggunaan Intent {@link +android.content.Intent#ACTION_EDIT EDIT} memungkinkan aplikasi yang +tidak memiliki izin untuk menyerahkan pengeditan kejadian ke aplikasi Kalender. +Bila pengguna selesai mengedit kejadian dalam Kalender, pengguna akan dikembalikan ke +aplikasi semula.</p> <p>Berikut ini adalah contoh intent yang mengatur +judul baru bagi kejadian yang ditetapkan dan memungkinkan pengguna mengedit kejadian dalam Kalender.</p> + + +<pre>long eventID = 208; +Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +Intent intent = new Intent(Intent.ACTION_EDIT) + .setData(uri) + .putExtra(Events.TITLE, "My New Title"); +startActivity(intent);</pre> + +<h3 id="intent-view">Menggunakan intent untuk menampilkan data kalender</h3> +<p>Penyedia Kalender menyediakan dua cara menggunakan Intent {@link android.content.Intent#ACTION_VIEW VIEW}:</p> +<ul> + <li>Untuk membuka Kalender pada tanggal tertentu.</li> + <li>Untuk menampilkan sebuah kejadian.</li> + +</ul> +<p>Berikut ini adalah contoh yang menampilkan cara membuka Kalender pada tanggal tertentu:</p> +<pre>// A date-time specified in milliseconds since the epoch. +long startMillis; +... +Uri.Builder builder = CalendarContract.CONTENT_URI.buildUpon(); +builder.appendPath("time"); +ContentUris.appendId(builder, startMillis); +Intent intent = new Intent(Intent.ACTION_VIEW) + .setData(builder.build()); +startActivity(intent);</pre> + +<p>Berikut ini adalah contoh yang menampilkan cara membuka kejadian untuk menampilkan:</p> +<pre>long eventID = 208; +... +Uri uri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); +Intent intent = new Intent(Intent.ACTION_VIEW) + .setData(uri); +startActivity(intent); +</pre> + + +<h2 id="sync-adapter">Adaptor Sinkronisasi</h2> + + +<p>Hanya ada perbedaan kecil dalam cara aplikasi dan adaptor sinkronisasi +mengakses Penyedia Kalender:</p> + +<ul> + <li>Adaptor sinkronisasi perlu menetapkan bahwa dirinya sebuah adaptor sinkronisasi dengan mengatur {@link android.provider.CalendarContract#CALLER_IS_SYNCADAPTER} ke <code>true</code>.</li> + + + <li>Adaptor sinkronisasi perlu memberikan {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_NAME} dan {@link +android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} sebagai parameter query dalam URI. </li> + + <li>Adaptor sinkronisasi memiliki akses tulis ke lebih banyak kolom daripada aplikasi atau widget. + Misalnya, aplikasi hanya bisa mengubah sedikit karakteristik kalender, + misalnya nama, nama tampilan, pengaturan visibilitas, dan apakah kalender + disinkronkan atau tidak. Sebagai perbandingan, adaptor sinkronisasi bisa mengakses bukan hanya kolom-kolom itu, namun banyak kolom lainnya, + misalnya warna kalender, zona waktu, tingkat akses, lokasi, dan seterusnya. +Akan tetapi, adaptor sinkronisasi dibatasi pada <code>ACCOUNT_NAME</code> dan +<code>ACCOUNT_TYPE</code> yang ditetapkannya.</li> </ul> + +<p>Berikut ini adalah metode pembantu yang bisa Anda gunakan untuk menghasilkan URI bagi penggunaan dengan adaptor sinkronisasi:</p> +<pre> static Uri asSyncAdapter(Uri uri, String account, String accountType) { + return uri.buildUpon() + .appendQueryParameter(android.provider.CalendarContract.CALLER_IS_SYNCADAPTER,"true") + .appendQueryParameter(Calendars.ACCOUNT_NAME, account) + .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build(); + } +</pre> +<p>Untuk contoh implementasi adaptor sinkronisasi (yang tidak terkait secara khusus dengan Kalender), lihat +<a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>. diff --git a/docs/html-intl/intl/in/guide/topics/providers/contacts-provider.jd b/docs/html-intl/intl/in/guide/topics/providers/contacts-provider.jd new file mode 100644 index 000000000000..28652fd7c998 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/contacts-provider.jd @@ -0,0 +1,2356 @@ +page.title=Penyedia Kontak +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>Tampilan Cepat</h2> +<ul> + <li>Repository informasi Android tentang orang.</li> + <li> + Sinkronisasi dengan web. + </li> + <li> + Mengintegrasikan data aliran sosial. + </li> +</ul> +<h2>Dalam dokumen ini</h2> +<ol> + <li> + <a href="#InformationTypes">Organisasi Penyedia Kontak</a> + </li> + <li> + <a href="#RawContactBasics">Kontak mentah</a> + </li> + <li> + <a href="#DataBasics">Data</a> + </li> + <li> + <a href="#ContactBasics">Kontak</a> + </li> + <li> + <a href="#Sources">Data Dari Adaptor Sinkronisasi</a> + </li> + <li> + <a href="#Permissions">Izin yang Diperlukan</a> + </li> + <li> + <a href="#UserProfile">Profil Pengguna</a> + </li> + <li> + <a href="#ContactsProviderMetadata">Metadata Penyedia Kontak</a> + </li> + <li> + <a href="#Access">Akses Penyedia Kontak</a> + <li> + </li> + <li> + <a href="#SyncAdapters">Adaptor Sinkronisasi Penyedia Kontak</a> + </li> + <li> + <a href="#SocialStream">Data Aliran Sosial</a> + </li> + <li> + <a href="#AdditionalFeatures">Fitur Tambahan Penyedia Kontak</a> + </li> +</ol> +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.provider.ContactsContract.Contacts}</li> + <li>{@link android.provider.ContactsContract.RawContacts}</li> + <li>{@link android.provider.ContactsContract.Data}</li> + <li>{@link android.provider.ContactsContract.StreamItems}</li> +</ol> +<h2>Contoh-Contoh Terkait</h2> +<ol> + <li> + <a href="{@docRoot}resources/samples/ContactManager/index.html"> + Contact Manager + </a> + </li> + <li> + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Contoh Adaptor Sinkronisasi</a> + </li> +</ol> +<h2>Lihat Juga</h2> +<ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten + </a> + </li> +</ol> +</div> +</div> +<p> + Penyedia Kontak adalah komponen Android yang tangguh dan fleksibel dalam mengelola + repository data pusat tentang orang di perangkat. Penyedia Kontak adalah sumber data + yang Anda lihat dalam aplikasi kontak perangkat, dan Anda juga bisa mengakses datanya dalam aplikasi + Anda sendiri serta mentransfer data antara perangkat dan layanan online. Penyedia mengakomodasi + berbagai sumber data dan mencoba mengelola data sebanyak mungkin untuk setiap orang, sehingga + organisasinya menjadi kompleks. Karena itu, API penyedia menyertakan + satu set kelas kontrak dan antarmuka ekstensif yang membantu pengambilan dan + modifikasi data. +</p> +<p> + Panduan ini menjelaskan hal-hal berikut: +</p> + <ul> + <li> + Struktur penyedia dasar. + </li> + <li> + Cara mengambil data dari penyedia. + </li> + <li> + Cara memodifikasi data di penyedia. + </li> + <li> + Cara menulis adaptor sinkronisasi untuk menyinkronkan data dari server Anda ke + Penyedia Kontak. + </li> + </ul> +<p> + Panduan ini beranggapan bahwa Anda mengetahui dasar-dasar penyedia konten Android. Untuk mengetahui selengkapnya + tentang penyedia konten Android, bacalah + panduan<a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a>. Contoh aplikasi + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync Adapter</a> + adalah contoh penggunaan adaptor sinkronisasi untuk mentransfer data antara Penyedia Kontak + dan contoh aplikasi yang memiliki host di Google Web Services. +</p> +<h2 id="InformationTypes">Organisasi Penyedia Kontak</h2> +<p> + Penyedia Kontak adalah komponen penyedia konten Android. Komponen ini memelihara tiga tipe + data tentang seseorang, masing-masing disesuaikan dengan tabel yang ditawarkan oleh penyedia, seperti + yang terlihat dalam gambar 1: +</p> +<img src="{@docRoot}images/providers/contacts_structure.png" alt="" height="364" id="figure1" /> +<p class="img-caption"> + <strong>Gambar 1.</strong> Struktur tabel Penyedia Kontak. +</p> +<p> + Ketiga tabel disebut secara umum menurut nama kelas kontrak. Kelas + mendefinisikan konstanta untuk URI konten, nama kolom, dan nilai kolom yang digunakan oleh tabel-tabel: +</p> +<dl> + <dt> + Tabel {@link android.provider.ContactsContract.Contacts} + </dt> + <dd> + Baris mewakili orang yang berbeda, berdasarkan agregrasi baris kontak mentah. + </dd> + <dt> + Tabel {@link android.provider.ContactsContract.RawContacts} + </dt> + <dd> + Baris berisi rangkuman data seseorang, untuk tipe dan akun pengguna tertentu. + </dd> + <dt> + Tabel {@link android.provider.ContactsContract.Data} + </dt> + <dd> + Baris berisi data untuk kontak mentah, seperti alamat email atau nomor telepon. + </dd> +</dl> +<p> + Tabel lain yang diwakili oleh kelas kontrak dalam {@link android.provider.ContactsContract} + adalah tabel tambahan yang digunakan Penyedia Kontak untuk mengelola operasinya atau mendukung + fungsi tertentu dalam kontak atau aplikasi telepon perangkat. +</p> +<h2 id="RawContactBasics">Kontak mentah</h2> +<p> + Kontak mentah mewakili data seseorang yang berasal dari satu tipe akun dan nama + akun. Karena Penyedia Kontak memungkinkan lebih dari satu layanan online sebagai sumber + data untuk satu orang, Penyedia Kontak memungkinkan multikontak mentah untuk orang yang sama. + Multikontak mentah juga memungkinkan seorang pengguna mengombinasikan data seseorang dari lebih dari satu akun + bertipe akun yang sama. +</p> +<p> + Sebagian besar data untuk kontak mentah tidak disimpan dalam + tabel {@link android.provider.ContactsContract.RawContacts}. Sebagai gantinya, data tersebut disimpan dalam satu atau beberapa baris + dalam tabel {@link android.provider.ContactsContract.Data}. Setiap baris data memiliki kolom + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID Data.RAW_CONTACT_ID} yang + berisi nilai {@link android.provider.BaseColumns#_ID RawContacts._ID} dari + baris {@link android.provider.ContactsContract.RawContacts} induknya. +</p> +<h3 id="RawContactsColumns">Kolom-kolom kontak mentah yang penting</h3> +<p> + Kolom-kolom penting dalam tabel {@link android.provider.ContactsContract.RawContacts} + tercantum pada tabel 1. Bacalah catatan yang diberikan setelah tabel: +</p> +<p class="table-caption" id="table1"> + <strong>Tabel 1.</strong> Kolom-kolom kontak mentah yang penting. +</p> +<table> + <tr> + <th scope="col">Nama kolom</th> + <th scope="col">Kegunaan</th> + <th scope="col">Catatan</th> + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_NAME} + </td> + <td> + Nama akun untuk tipe akun yang merupakan sumber kontak mentah ini. + Misalnya, nama akun dari akun Google adalah salah satu alamat Gmail + pemilik perangkat. Lihat entri berikutnya untuk + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} untuk informasi + selengkapnya. + </td> + <td> + Format nama ini khusus untuk tipe akun ini. Format ini tidak + harus alamat email. + </td> + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.SyncColumns#ACCOUNT_TYPE} + </td> + <td> + Tipe akun yang merupakan sumber kontak mentah ini. Misalnya, tipe + akun dari akun Google adalah <code>com.google</code>. Selalu batasi tipe akun Anda + dengan identifier domain untuk domain yang Anda miliki atau kontrol. Hal ini akan memastikan bahwa tipe + akun Anda bersifat unik. + </td> + <td> + Tipe akun yang menawarkan data kontak biasanya memiliki adaptor sinkronisasi terkait yang + menyinkronkan dengan Penyedia Kontak. + </tr> + <tr> + <td> + {@link android.provider.ContactsContract.RawContactsColumns#DELETED} + </td> + <td> + Flag "deleted" untuk kontak mentah. + </td> + <td> + Flag ini memungkinkan Penyedia Kontak memelihara baris secara internal hingga adaptor + sinkronisasi bisa menghapus baris dari server mereka dan akhirnya menghapus baris + dari repository. + </td> + </tr> +</table> +<h4>Catatan</h4> +<p> + Berikut ini adalah catatan penting tentang + tabel {@link android.provider.ContactsContract.RawContacts}: +</p> +<ul> + <li> + Nama kontak mentah tidak disimpan di barisnya dalam + {@link android.provider.ContactsContract.RawContacts}. Sebagai gantinya, nama tersebut disimpan dalam + tabel {@link android.provider.ContactsContract.Data}, pada + baris {@link android.provider.ContactsContract.CommonDataKinds.StructuredName}. Kontak mentah + hanya memiliki satu baris dari tipe ini dalam tabel {@link android.provider.ContactsContract.Data}. + </li> + <li> + <strong>Perhatian:</strong> Untuk menggunakan data akun sendiri dalam baris kontak mentah, akun harus + didaftarkan lebih dahulu dengan {@link android.accounts.AccountManager}. Caranya, mintalah + pengguna untuk menambahkan tipe akun dan nama akun ke dalam daftar akun. Jika Anda tidak + melakukannya, Penyedia Kontak secara otomatis akan menghapus baris kontak mentah Anda. + <p> + Misalnya, Anda menginginkan aplikasi memelihara data kontak untuk layanan berbasis web + dengan domain {@code com.example.dataservice}, dan akun pengguna untuk layanan Anda + adalah {@code becky.sharp@dataservice.example.com}, pengguna harus menambahkan lebih dahulu "type" + akun ({@code com.example.dataservice}) dan "name" akun + ({@code becky.smart@dataservice.example.com}) sebelum aplikasi Anda bisa menambahkan baris kontak mentah. + Anda bisa menjelaskan ketentuan ini kepada pengguna dalam dokumentasi, atau meminta + pengguna untuk menambahkan tipe dan nama, atau keduanya. Tipe akun dan nama akun + dijelaskan lebih detail di bagian berikutnya. + </li> +</ul> +<h3 id="RawContactsExample">Sumber data kontak mentah</h3> +<p> + Untuk memahami cara kerja kontak mentah, perhatikan pengguna "Emily Dickinson" yang mendefinisikan + tiga akun pengguna berikut pada perangkatnya: +</p> +<ul> + <li><code>emily.dickinson@gmail.com</code></li> + <li><code>emilyd@gmail.com</code></li> + <li>Akun Twitter "belle_of_amherst"</li> +</ul> +<p> + Pengguna ini telah mengaktifkan <em>Sync Contacts</em> untuk ketiga akun dalam pengaturan + <em>Accounts</em>. +</p> +<p> + Anggaplah Emily Dickinson membuka jendela browser, masuk ke Gmail sebagai + <code>emily.dickinson@gmail.com</code>, membuka + Contacts, dan menambahkan "Thomas Higginson". Kemudian, ia masuk ke Gmail sebagai + <code>emilyd@gmail.com</code> dan mengirimkan email kepada "Thomas Higginson", yang + menambahkan Thomas secara otomatis sebagai kontak. Ia juga mengikuti "colonel_tom" (ID Twitter Thomas Higginson) di + Twitter. +</p> +<p> + Penyedia Kontak membuat tiga kontak mentah akibat pekerjaan ini: +</p> +<ol> + <li> + Kontak mentah untuk "Thomas Higginson" yang dikaitkan dengan <code>emily.dickinson@gmail.com</code>. + Tipe akun penggunanya adalah Google. + </li> + <li> + Kontak mentah kedua untuk "Thomas Higginson" yang dikaitkan dengan <code>emilyd@gmail.com</code>. + Tipe akun pengguna juga Google. Ada kontak mentah kedua + meskipun nama tersebut identik dengan nama sebelumnya karena orang bersangkutan ditambahkan untuk + akun pengguna yang berbeda. + </li> + <li> + Kontak mentah ketiga untuk "Thomas Higginson" yang dikaitkan dengan "belle_of_amherst". Tipe + akun penggunanya adalah Twitter. + </li> +</ol> +<h2 id="DataBasics">Data</h2> +<p> + Seperti yang telah disebutkan, data untuk kontak mentah disimpan dalam + baris {@link android.provider.ContactsContract.Data} yang ditautkan dengan nilai + <code>_ID</code> kontak mentah. Cara ini memungkinkan satu kontak mentah memiliki beberapa instance tipe data + yang sama dengan alamat email atau nomor telepon. Misalnya, jika + "Thomas Higginson" untuk {@code emilyd@gmail.com} (baris kontak mentah untuk Thomas Higginson + yang dikaitkan dengan akun Google <code>emilyd@gmail.com</code>) memiliki alamat email rumah + <code>thigg@gmail.com</code> dan alamat email kerja + <code>thomas.higginson@gmail.com</code>, Penyedia Kontak akan menyimpan dua baris alamat + email dan menautkan keduanya ke kontak mentah. +</p> +<p> + Perhatikan bahwa tipe data yang berbeda disimpan dalam satu tabel ini. Baris-baris nama tampilan, + nomor telepon, email, alamat surat, foto, dan data situs web semuanya bisa ditemukan dalam + tabel {@link android.provider.ContactsContract.Data}. Untuk membantu mengelola ini, + tabel {@link android.provider.ContactsContract.Data} memiliki beberapa kolom dengan nama deskriptif, + dalam kolom lain dengan nama generik. Konten kolom bernama deskriptif memiliki arti yang sama + terlepas dari tipe data dalam barisnya, sedangkan konten kolom bernama generik memiliki + arti yang berbeda-beda sesuai dengan tipe data. +</p> +<h3 id="DescriptiveColumns">Nama kolom deskriptif</h3> +<p> + Beberapa contoh nama kolom deskriptif adalah: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.Data#RAW_CONTACT_ID} + </dt> + <dd> + Nilai kolom <code>_ID</code> kontak mentah untuk data ini. + </dd> + <dt> + {@link android.provider.ContactsContract.Data#MIMETYPE} + </dt> + <dd> + Tipe data yang disimpan dalam baris ini, dinyatakan berupa tipe MIME custom. Penyedia Kontak + menggunakan tipe MIME yang didefinisikan dalam subkelas + {@link android.provider.ContactsContract.CommonDataKinds}. Tipe MIME ini adalah sumber terbuka, + dan bisa digunakan oleh setiap aplikasi atau adaptor sinkronisasi yang bisa digunakan bersama Penyedia Kontak. + </dd> + <dt> + {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} + </dt> + <dd> + Jika tipe baris data ini bisa terjadi lebih dari satu kali untuk suatu kontak mentah, + kolom {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY} + menandai baris data yang berisi data utama untuk tipe itu. Misalnya, jika + pengguna menekan lama sebuah nomor telepon untuk kontak dan memilih <strong>Set default</strong>, + maka baris {@link android.provider.ContactsContract.Data} yang berisi angka itu + mengatur kolom {@link android.provider.ContactsContract.DataColumns#IS_PRIMARY}-nya ke suatu + nilai bukan nol. + </dd> +</dl> +<h3 id="GenericColumns">Nama kolom generik</h3> +<p> + Ada 15 kolom generik bernama <code>DATA1</code> hingga + <code>DATA15</code> yang tersedia secara umum dan empat kolom generik + tambahan <code>SYNC1</code> hingga <code>SYNC4</code> yang harus digunakan hanya oleh adaptor + sinkronisasi. Konstanta nama kolom generik selalu berfungsi, terlepas dari tipe + data dalam baris . +</p> +<p> + Kolom <code>DATA1</code> diindeks. Penyedia Kontak selalu menggunakan kolom ini untuk + data yang diharapkan penyedia akan menjadi target yang paling sering dari suatu query. Misalnya, + dalam baris email, kolom ini berisi alamat email sebenarnya. +</p> +<p> + Sesuai konvensi, kolom <code>DATA15</code> dicadangkan untuk menyimpan data Binary Large Object + (BLOB) seperti thumbnail foto. +</p> +<h3 id="TypeSpecificNames">Nama kolom bertipe spesifik</h3> +<p> + Guna memudahkan pekerjaan dengan kolom untuk tipe baris tertentu, Penyedia Kontak + juga menyediakan konstanta nama kolom bertipe spesifik, yang didefinisikan dalam subkelas + {@link android.provider.ContactsContract.CommonDataKinds}. Konstanta cuma memberikan nama + konstanta yang berbeda ke nama kolom yang sama, yang membantu Anda mengakses data dalam baris + bertipe spesifik. +</p> +<p> + Misalnya, kelas {@link android.provider.ContactsContract.CommonDataKinds.Email} mendefinisikan + konstanta nama kolom bertipe spesifik untuk baris {@link android.provider.ContactsContract.Data} + yang memiliki tipe MIME + {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE + Email.CONTENT_ITEM_TYPE}. Kelas ini berisi konstanta + {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} untuk kolom + alamat email. Nilai sesungguhnya dari + {@link android.provider.ContactsContract.CommonDataKinds.Email#ADDRESS} adalah "data1", yang + sama dengan nama generik kolom. +</p> +<p class="caution"> + <strong>Perhatian:</strong> Jangan tambahkan data custom Anda sendiri ke + tabel {@link android.provider.ContactsContract.Data} dengan menggunakan baris yang memiliki salah satu + tipe MIME yang telah didefinisikan penyedia. Jika melakukannya, Anda bisa kehilangan data atau menyebabkan penyedia + gagal berfungsi. Misalnya, Anda seharusnya tidak menambahkan baris bertipe MIME + {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE + Email.CONTENT_ITEM_TYPE} yang berisi nama pengguna sebagai ganti alamat email dalam + kolom <code>DATA1</code>. Jika Anda menggunakan tipe MIME custom sendiri untuk baris bersangkutan, maka Anda bebas + untuk mendefinisikan nama kolom bertipe spesifik dan menggunakan kolom sekehendak Anda. +</p> +<p> + Gambar 2 menampilkan cara kolom deskriptif dan kolom data muncul dalam + baris {@link android.provider.ContactsContract.Data}, dan cara nama kolom bertipe spesifik "melapisi" + nama kolom generik +</p> +<img src="{@docRoot}images/providers/data_columns.png" alt="How type-specific column names map to generic column names" height="311" id="figure2" /> +<p class="img-caption"> + <strong>Gambar 2.</strong> Nama kolom bertipe spesifik dan nama kolom generik. +</p> +<h3 id="ColumnMaps">Kelas nama kolom bertipe spesifik</h3> +<p> + Tabel 2 berisi daftar kelas nama kolom bertipe spesifik yang paling umum digunakan: +</p> +<p class="table-caption" id="table2"> + <strong>Tabel 2.</strong> Kelas nama kolom bertipe spesifik</p> +<table> + <tr> + <th scope="col">Kelas pemetaan</th> + <th scope="col">Tipe data</th> + <th scope="col">Catatan</th> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredName}</td> + <td>Data nama untuk kontak mentah yang dikaitkan dengan baris data ini.</td> + <td>Kontak mentah hanya memiliki salah satu baris ini.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.Photo}</td> + <td>Foto utama untuk kontak mentah yang dikaitkan dengan baris data ini.</td> + <td>Kontak mentah hanya memiliki salah satu baris ini.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.Email}</td> + <td>Alamat email untuk kontak mentah yang dikaitkan dengan baris data ini.</td> + <td>Kontak mentah bisa memiliki beberapa alamat email.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal}</td> + <td>Alamat pos untuk kontak mentah yang dikaitkan dengan baris data ini.</td> + <td>Kontak mentah bisa memiliki beberapa alamat email.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}</td> + <td>Identifier yang menautkan kontak mentah ke salah satu grup dalam Penyedia Kontak.</td> + <td> + Grup adalah fitur opsional pada tipe akun dan nama akun. Grup dijelaskan + lebih detail di bagian <a href="#Groups">Grup kontak</a>. + </td> + </tr> +</table> +<h3 id="ContactBasics">Kontak</h3> +<p> + Penyedia Kontak mengombinasikan baris kontak mentah di semua tipe akun dan nama akun + untuk membentuk <strong>kontak</strong>. Hal ini memudahkan menampilkan dan memodifikasi semua data + yang telah dikumpulkan pengguna untuk seseorang. Penyedia Kontak mengelola pembuatan baris + kontak baru, dan agregasi kontak mentah dengan baris kontak yang ada. Baik aplikasi maupun adaptor sinkronisasi + tidak boleh menambahkan kontak dan sebagian kolom dalam baris kontak yang bersifat hanya baca. +</p> +<p class="note"> + <strong>Catatan:</strong> Jika Anda mencoba menambahkan kontak ke Penyedia Kontak dengan + {@link android.content.ContentResolver#insert(Uri,ContentValues) insert()}, Anda akan mendapatkan + eksepsi {@link java.lang.UnsupportedOperationException}. Jika Anda mencoba memperbarui sebuah kolom + yang tercantum sebagai "hanya-baca", pembaruan akan diabaikan. +</p> +<p> + Penyedia Kontak membuat kontak baru untuk merespons penambahan kontak mentah baru + yang tidak cocok dengan kontak yang ada. Penyedia juga melakukan ini jika data + kontak mentah yang ada berubah sehingga tidak lagi cocok dengan kontak yang + sebelumnya dihubungkan. Jika aplikasi atau adaptor sinkronisasi membuat kontak mentah baru yang + <em>memang</em> cocok dengan kontak yang ada, kontak mentah baru akan diagregasikan ke kontak + yang ada. +</p> +<p> + Penyedia Kontak menautkan baris kontak ke baris kontak mentahnya dengan kolom + <code>_ID</code> dari baris kontak dalam tabel {@link android.provider.ContactsContract.Contacts Contacts}. + Kolom <code>CONTACT_ID</code> tabel kontak mentah + {@link android.provider.ContactsContract.RawContacts} berisi nilai <code>_ID</code> untuk + baris kontak yang dikaitkan dengan tiap baris kontak mentah. +</p> +<p> + Tabel {@link android.provider.ContactsContract.Contacts} juga memiliki kolom + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} yang merupakan + tautan "permanen" ke baris kontak. Karena memelihara kontak + secara otomatis, Penyedia Kontak bisa mengubah nilai {@link android.provider.BaseColumns#_ID} baris kontak + untuk merespons agregasi atau sinkronisasi. Sekalipun ini terjadi, URI konten + {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} yang dikombinasikan dengan + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} kontak akan tetap + menunjuk ke baris kontak itu, sehingga Anda bisa menggunakan + {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} + untuk memelihara tautan ke kontak "favorit", dan seterusnya. Kolom ini memiliki formatnya sendiri, yang + tidak terkait dengan format kolom {@link android.provider.BaseColumns#_ID}. +</p> +<p> + Gambar 3 menampilkan cara ketiga tabel utama terkait satu sama lain. +</p> +<img src="{@docRoot}images/providers/contacts_tables.png" alt="Contacts provider main tables" height="514" id="figure4" /> +<p class="img-caption"> + <strong>Gambar 3.</strong> Hubungan tabel Contacts, Raw Contacts, dan Details. +</p> +<h2 id="Sources">Data Dari Adaptor Sinkronisasi</h2> +<p> + Pengguna memasukkan data kontak secara langsung ke dalam perangkat, namun data juga mengalir masuk ke Penyedia Kontak + dari layanan web melalui <strong>adaptor sinkronisasi</strong>, yang mengotomatiskan + transfer data antara perangkat dan layanan. Adaptor sinkronisasi berjalan di latar belakang + di bawah kontrol sistem, dan memanggil metode {@link android.content.ContentResolver} + untuk mengelola data. +</p> +<p> + Di Android, layanan web yang digunakan adaptor sinkronisasi diidentifikasi melalui tipe akun. + Setiap adaptor sinkronisasi bekerja dengan satu tipe akun, tetapi bisa mendukung beberapa nama akun untuk + tipe itu. Tipe akun dan nama akun dijelaskan secara singkat di bagian + <a href="#RawContactsExample">Sumber data kontak mentah</a>. Definisi berikut menyediakan + detail selengkapnya, dan menjelaskan cara tipe dan nama akun berkaitan dengan adaptor sinkronisasi dan layanan. +</p> +<dl> + <dt> + Tipe akun + </dt> + <dd> + Mengidentifikasi layanan tempat pengguna menyimpan data. Sering kali, pengguna harus + mengautentikasi diri dengan layanan. Misalnya, Google Contacts adalah tipe akun, yang diidentifikasi + dengan kode <code>google.com</code>. Nilai ini sesuai dengan tipe akun yang digunakan oleh + {@link android.accounts.AccountManager}. + </dd> + <dt> + Nama akun + </dt> + <dd> + Mengidentifikasi akun atau login tertentu untuk suatu tipe akun. Akun Google Contacts + sama dengan akun Google, yang memiliki alamat email sebagai nama akun. + Layanan lain mungkin menggunakan nama pengguna satu-kata atau identitas berupa angka. + </dd> +</dl> +<p> + Tipe akun tidak harus unik. Pengguna boleh mengonfigurasi beberapa akun Google Contacts + dan mengunduh data ke Penyedia Kontak; ini mungkin terjadi jika pengguna memiliki satu set + kontak pribadi untuk satu nama akun pribadi, dan satu set lagi untuk pekerjaan. Nama akun + biasanya unik. Bersama-sama, keduanya mengidentifikasi aliran data tertentu antara Penyedia Kontak dan + layanan eksternal. +</p> +<p> + Jika Anda ingin mentransfer data layanan ke Penyedia Kontak, Anda perlu menulis + adaptor sinkronisasi sendiri. Hal ini dijelaskan lebih detail di bagian + <a href="#SyncAdapters">Adaptor Sinkronisasi Penyedia Kontak</a>. +</p> +<p> + Gambar 4 menampilkan cara Penyedia Kontak dimasukkan ke dalam aliran data + tentang orang. Dalam kotak bertanda "sync adapters", setiap adaptor diberi label menurut tipe akunnya. +</p> +<img src="{@docRoot}images/providers/ContactsDataFlow.png" alt="Flow of data about people" height="252" id="figure5" /> +<p class="img-caption"> + <strong>Gambar 4.</strong> Aliran data Penyedia Kontak. +</p> +<h2 id="Permissions">Izin yang Diperlukan</h2> +<p> + Aplikasi yang ingin mengakses Penyedia Kontak harus meminta izin + berikut: +</p> +<dl> + <dt>Akses baca ke satu atau beberapa tabel</dt> + <dd> + {@link android.Manifest.permission#READ_CONTACTS}, yang ditetapkan dalam + <code>AndroidManifest.xml</code> dengan elemen + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> sebagai + <code><uses-permission android:name="android.permission.READ_CONTACTS"></code>. + </dd> + <dt>Akses tulis ke satu atau beberapa tabel</dt> + <dd> + {@link android.Manifest.permission#WRITE_CONTACTS}, yang ditetapkan dalam + <code>AndroidManifest.xml</code> dengan elemen + <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> + <uses-permission></a></code> sebagai + <code><uses-permission android:name="android.permission.WRITE_CONTACTS"></code>. + </dd> +</dl> +<p> + Izin ini tidak diperluas ke data profil pengguna. Profil pengguna dan izin + yang diperlukan dibahas di bagian berikut, + <a href="#UserProfile">Profil Pengguna</a>. +</p> +<p> + Ingatlah bahwa data kontak pengguna bersifat pribadi dan sensitif. Pengguna mempersoalkan + privasinya, sehingga tidak ingin aplikasi mengumpulkan data tentang diri atau kontak mereka. + Jika alasan Anda memerlukan izin untuk mengakses data kontak tidak jelas, pengguna mungkin memberi + aplikasi Anda peringkat rendah atau langsung menolak menginstalnya. +</p> +<h2 id="UserProfile">Profil Pengguna</h2> +<p> + Tabel {@link android.provider.ContactsContract.Contacts} berisi satu baris yang berisi + data profil untuk pengguna perangkat. Data ini menjelaskan data perangkat <code>user</code> bukannya + salah satu kontak pengguna. Baris kontak profil ditautkan ke baris + kontak mentah untuk setiap sistem yang menggunakan profil. + Setiap baris kontak mentah profil bisa memiliki beberapa baris data. Konstanta untuk mengakses profil + pengguna tersedia dalam kelas {@link android.provider.ContactsContract.Profile}. +</p> +<p> + Akses ke profil pengguna memerlukan izin khusus. Selain itu, izin + {@link android.Manifest.permission#READ_CONTACTS} dan + {@link android.Manifest.permission#WRITE_CONTACTS} diperlukan untuk membaca dan menulis, akses + ke profil pengguna memerlukan masing-masing izin {@link android.Manifest.permission#READ_PROFILE} dan + {@link android.Manifest.permission#WRITE_PROFILE} untuk akses baca dan tulis. + +</p> +<p> + Ingatlah bahwa Anda harus mempertimbangkan profil pengguna bersifat sensitif. Izin + {@link android.Manifest.permission#READ_PROFILE} memungkinkan Anda mengakses data yang mengidentifikasi secara pribadi + pengguna perangkat. Pastikan memberi tahu pengguna alasan + Anda memerlukan izin akses profil pengguna dalam keterangan aplikasi Anda. +</p> +<p> + Untuk mengambil baris kontak berisi profil pengguna, + panggil {@link android.content.ContentResolver#query(Uri,String[], String, String[], String) + ContentResolver.query()}. Atur URI konten ke + {@link android.provider.ContactsContract.Profile#CONTENT_URI} dan jangan sediakan + kriteria pemilihan apa pun. Anda juga bisa menggunakan URI konten ini sebagai URI dasar untuk mengambil kontak + mentah atau data untuk profil. Misalnya, cuplikan kode ini mengambil data untuk profil: +</p> +<pre> +// Sets the columns to retrieve for the user profile +mProjection = new String[] + { + Profile._ID, + Profile.DISPLAY_NAME_PRIMARY, + Profile.LOOKUP_KEY, + Profile.PHOTO_THUMBNAIL_URI + }; + +// Retrieves the profile from the Contacts Provider +mProfileCursor = + getContentResolver().query( + Profile.CONTENT_URI, + mProjection , + null, + null, + null); +</pre> +<p class="note"> + <strong>Catatan:</strong> Jika Anda mengambil beberapa baris kontak, dan ingin menentukan apakah salah satu baris + adalah profil pengguna, uji + kolom {@link android.provider.ContactsContract.ContactsColumns#IS_USER_PROFILE} pada baris tersebut. Kolom ini + diatur ke "1" jika kontak adalah profil pengguna. +</p> +<h2 id="ContactsProviderMetadata">Metadata Penyedia Kontak</h2> +<p> + Penyedia Kontak mengelola data yang mencatat status data kontak dalam + repository. Metadata repository ini disimpan di berbagai tempat, termasuk baris-baris tabel + Raw Contacts, Data, dan Contacts, + tabel {@link android.provider.ContactsContract.Settings}, dan + tabel {@link android.provider.ContactsContract.SyncState}. Tabel berikut menampilkan + efek setiap potongan metadata ini: +</p> +<p class="table-caption" id="table3"> + <strong>Tabel 3.</strong> Metadata di Penyedia Kontak</p> +<table> + <tr> + <th scope="col">Tabel</th> + <th scope="col">Kolom</th> + <th scope="col">Nilai</th> + <th scope="col">Arti</th> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.RawContacts}</td> + <td rowspan="2">{@link android.provider.ContactsContract.SyncColumns#DIRTY}</td> + <td>"0" - tidak berubah sejak sinkronisasi terakhir.</td> + <td rowspan="2"> + Menandai kontak mentah yang berubah pada perangkat dan telah disinkronkan kembali ke + server. Nilai diatur secara otomatis oleh Penyedia Kontak bila aplikasi + Android memperbarui baris. + <p> + Adaptor sinkronisasi yang memodifikasi kontak mentah atau tabel data harus selalu menambahkan + string {@link android.provider.ContactsContract#CALLER_IS_SYNCADAPTER} ke + URI konten yang digunakannya. Ini mencegah penyedia menandai baris sebagai kotor. + Sebaliknya, modifikasi oleh adaptor sinkronisasi tampak seperti modifikasi lokal dan + dikirim ke server, meskipun server adalah sumber modifikasi. + </p> + </td> + </tr> + <tr> + <td>"1" - berubah sejak sinkronisasi terakhir, harus disinkronkan kembali ke server.</td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.RawContacts}</td> + <td>{@link android.provider.ContactsContract.SyncColumns#VERSION}</td> + <td>Nomor versi baris ini.</td> + <td> + Penyedia Kontak menambahkan nilai ini secara otomatis bila baris atau + data terkaitnya berubah. + </td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.Data}</td> + <td>{@link android.provider.ContactsContract.DataColumns#DATA_VERSION}</td> + <td>Nomor versi baris ini.</td> + <td> + Penyedia Kontak menambahkan nilai ini secara otomatis bila baris data + berubah. + </td> + </tr> + <tr> + <td>{@link android.provider.ContactsContract.RawContacts}</td> + <td>{@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}</td> + <td> + Nilai string yang mengidentifikasi secara unik kontak mentah ini ke akun tempat + kontak dibuat. + </td> + <td> + Bila adaptor sinkronisasi membuat kontak mentah baru, kolom ini harus diatur ke + ID unik server untuk kontak mentah itu. Bila aplikasi Android membuat kontak mentah + baru, aplikasi harus membiarkan kolom ini kosong. Ini mengisyaratkan pada adaptor + sinkronisasi bahwa adaptor harus membuat kontak mentah baru pada server, dan mendapatkan + nilai untuk {@link android.provider.ContactsContract.SyncColumns#SOURCE_ID}. + <p> + Khususnya, id sumber harus <strong>unik</strong> untuk setiap tipe + akun dan stabil di semua sinkronisasi: + </p> + <ul> + <li> + Unik: Setiap kontak mentah untuk satu akun harus memiliki id sumbernya sendiri. Jika Anda + tidak memberlakukan aturan ini, masalah akan timbul dalam aplikasi kontak. + Perhatikan bahwa dua kontak mentah untuk tipe akun yang <em>sama</em> boleh memiliki + id sumber yang sama. Misalnya, kontak mentah "Thomas Higginson" untuk + akun {@code emily.dickinson@gmail.com} boleh memiliki id sumber + yang sama dengan kontak mentah "Thomas Higginson" untuk akun + {@code emilyd@gmail.com}. + </li> + <li> + Stabil: Id sumber adalah bagian tetap dari data layanan online untuk + kontak mentah. Misalnya, jika pengguna membersihkan Contacts Storage dari + pengaturan aplikasi dan menyinkronkan ulang, kontak mentah yang dipulihkan akan memiliki id sumber + yang sama dengan sebelumnya. Jika Anda tidak memberlakukan hal ini, pintasan akan berhenti + berfungsi. + </li> + </ul> + </td> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.Groups}</td> + <td rowspan="2">{@link android.provider.ContactsContract.GroupsColumns#GROUP_VISIBLE}</td> + <td>"0" - Kontak dalam grup ini tidak boleh terlihat dalam UI aplikasi Android.</td> + <td> + Kolom ini digunakan untuk kompatibilitas dengan server yang memungkinkan pengguna menyembunyikan kontak dalam + grup tertentu. + </td> + </tr> + <tr> + <td>"1" - Kontak dalam grup ini boleh terlihat dalam UI aplikasi.</td> + </tr> + <tr> + <td rowspan="2">{@link android.provider.ContactsContract.Settings}</td> + <td rowspan="2"> + {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE}</td> + <td> + "0" - Untuk akun dan tipe akun ini, kontak yang bukan milik grup + tidak akan terlihat pada UI aplikasi Android. + </td> + <td rowspan="2"> + Secara default, kontak tidak terlihat jika tidak satu pun kontak mentahnya milik grup + (Keanggotaan grup untuk kontak mentah ditandai oleh satu atau beberapa baris + {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership} + dalam tabel {@link android.provider.ContactsContract.Data}). + Dengan mengatur flag ini dalam baris tabel {@link android.provider.ContactsContract.Settings} + untuk tipe akun dan akun, Anda bisa memaksakan kontak tanpa grup agar terlihat. + Satu kegunaan flag ini adalah menampilkan kontak dari server yang tidak menggunakan grup. + </td> + </tr> + <tr> + <td> + "1" - Untuk akun dan tipe akun ini, kontak yang bukan milik grup + akan terlihat pada UI aplikasi. + </td> + + </tr> + <tr> + <td>{@link android.provider.ContactsContract.SyncState}</td> + <td>(semua)</td> + <td> + Gunakan tabel ini untuk menyimpan metadata bagi adaptor sinkronisasi Anda. + </td> + <td> + Dengan tabel ini, Anda bisa menyimpan status sinkronisasi dan data lain yang terkait dengan sinkronisasi secara persisten pada + perangkat. + </td> + </tr> +</table> +<h2 id="Access">Akses Penyedia Kontak</h2> +<p> + Bagian ini menjelaskan panduan untuk mengakses data dari Penyedia Kontak, yang berfokus pada + hal-hal berikut: +</p> +<ul> + <li> + Query entitas. + </li> + <li> + Modifikasi batch. + </li> + <li> + Pengambilan dan modifikasi dengan intent. + </li> + <li> + Integritas data. + </li> +</ul> +<p> + Membuat modifikasi dari adaptor sinkronisasi juga secara lebih detail di bagian + <a href="#SyncAdapters">Adaptor Sinkronisasi Penyedia Kontak</a>. +</p> +<h3 id="Entities">Membuat query entitas</h3> +<p> + Karena disusun secara hierarki, tabel-tabel Penyedia Kontak sering kali berguna untuk + mengambil baris dan semua baris "anak" yang ditautkan dengannya. Misalnya, untuk menampilkan + semua informasi untuk satu orang, Anda mungkin ingin mengambil semua + baris {@link android.provider.ContactsContract.RawContacts} untuk satu baris + {@link android.provider.ContactsContract.Contacts}, atau semua + baris {@link android.provider.ContactsContract.CommonDataKinds.Email} untuk satu baris + {@link android.provider.ContactsContract.RawContacts}. Untuk memudahkan hal ini, Penyedia Kontak + menawarkan konstruksi <strong>entitas</strong>, yang berfungsi seperti gabungan database di antara + tabel-tabel. +</p> +<p> + Entitas adalah seperti tabel yang terdiri atas kolom-kolom terpilih dari tabel induk dan tabel anaknya. + Bila membuat query sebuah entitas, Anda memberikan proyeksi dan kriteria pencarian berdasarkan kolom-kolom + yang tersedia dari entitas itu. Hasilnya adalah sebuah {@link android.database.Cursor} yang + berisi satu baris untuk setiap baris tabel anak yang diambil. Misalnya, jika Anda membuat query + {@link android.provider.ContactsContract.Contacts.Entity} untuk satu nama kontak + dan semua baris {@link android.provider.ContactsContract.CommonDataKinds.Email} untuk semua + kontak mentah bagi nama itu, Anda akan mendapatkan kembali {@link android.database.Cursor} berisi satu baris + untuk setiap baris {@link android.provider.ContactsContract.CommonDataKinds.Email}. +</p> +<p> + Entitas menyederhanakan query. Dengan entitas, Anda bisa mengambil semua data kontak untuk satu + kontak atau kontak mentah sekaligus, sebagai ganti harus membuat query tabel induk terlebih dahulu untuk mendapatkan + ID, lalu harus membuat query tabel anak dengan ID itu. Selain itu, Penyedia Kontak akan memproses + query terhadap entitas dalam satu transaksi, yang memastikan bahwa data yang diambil + konsisten secara internal. +</p> +<p class="note"> + <strong>Catatan:</strong> Entitas biasanya tidak berisi semua kolom tabel induk dan + anak. Jika Anda mencoba menggunakan nama kolom yang tidak ada dalam daftar konstanta + nama kolom untuk entitas, Anda akan mendapatkan {@link java.lang.Exception}. +</p> +<p> + Cuplikan berikut menampilkan cara mengambil semua baris kontak mentah untuk sebuah kontak. Cuplikan ini + adalah bagian dari aplikasi lebih besar yang memiliki dua aktivitas, "main" dan "detail". Aktivitas utama + menampilkan daftar baris kontak; bila pengguna memilih satu baris, aktivitas akan mengirimkan ID-nya ke aktivitas + detail. Aktivitas detail menggunakan{@link android.provider.ContactsContract.Contacts.Entity} + untuk menampilkan semua baris data dari semua kontak mentah yang dikaitkan dengan kontak + terpilih. +</p> +<p> + Cuplikan ini diambil dari aktivitas "detail": +</p> +<pre> +... + /* + * Appends the entity path to the URI. In the case of the Contacts Provider, the + * expected URI is content://com.google.contacts/#/entity (# is the ID value). + */ + mContactUri = Uri.withAppendedPath( + mContactUri, + ContactsContract.Contacts.Entity.CONTENT_DIRECTORY); + + // Initializes the loader identified by LOADER_ID. + getLoaderManager().initLoader( + LOADER_ID, // The identifier of the loader to initialize + null, // Arguments for the loader (in this case, none) + this); // The context of the activity + + // Creates a new cursor adapter to attach to the list view + mCursorAdapter = new SimpleCursorAdapter( + this, // the context of the activity + R.layout.detail_list_item, // the view item containing the detail widgets + mCursor, // the backing cursor + mFromColumns, // the columns in the cursor that provide the data + mToViews, // the views in the view item that display the data + 0); // flags + + // Sets the ListView's backing adapter. + mRawContactList.setAdapter(mCursorAdapter); +... +@Override +public Loader<Cursor> onCreateLoader(int id, Bundle args) { + + /* + * Sets the columns to retrieve. + * RAW_CONTACT_ID is included to identify the raw contact associated with the data row. + * DATA1 contains the first column in the data row (usually the most important one). + * MIMETYPE indicates the type of data in the data row. + */ + String[] projection = + { + ContactsContract.Contacts.Entity.RAW_CONTACT_ID, + ContactsContract.Contacts.Entity.DATA1, + ContactsContract.Contacts.Entity.MIMETYPE + }; + + /* + * Sorts the retrieved cursor by raw contact id, to keep all data rows for a single raw + * contact collated together. + */ + String sortOrder = + ContactsContract.Contacts.Entity.RAW_CONTACT_ID + + " ASC"; + + /* + * Returns a new CursorLoader. The arguments are similar to + * ContentResolver.query(), except for the Context argument, which supplies the location of + * the ContentResolver to use. + */ + return new CursorLoader( + getApplicationContext(), // The activity's context + mContactUri, // The entity content URI for a single contact + projection, // The columns to retrieve + null, // Retrieve all the raw contacts and their data rows. + null, // + sortOrder); // Sort by the raw contact ID. +} +</pre> +<p> + Bila selesai dimuat, {@link android.app.LoaderManager} akan memicu callback ke + {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished(Loader, D) + onLoadFinished()}. Salah satu argumen masuk pada metode ini adalah + {@link android.database.Cursor} bersama hasil query. Dalam aplikasi Anda sendiri, Anda bisa memperoleh + data dari {@link android.database.Cursor} ini untuk menampilkannya atau menggunakannya lebih jauh. +</p> +<h3 id="Transactions">Modifikasi batch</h3> +<p> + Bila memungkinkan, Anda harus menyisipkan, memperbarui, dan menghapus data dalam Penyedia Kontak dengan + "batch mode", dengan membuat {@link java.util.ArrayList} dari + objek-objek {@link android.content.ContentProviderOperation} dan memanggil + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Karena + Penyedia Kontak menjalankan semua operasi dalam satu + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} transaksi, + modifikasi Anda tidak akan pernah meninggalkan repository kontak dalam keadaan + tidak konsisten. Modifikasi batch juga memudahkan penyisipan kontak mentah dan data detailnya + sekaligus. +</p> +<p class="note"> + <strong>Catatan:</strong> Untuk memodifikasi <em>satu</em> kontak mentah, pertimbangkan untuk mengirim intent ke + aplikasi kontak perangkat daripada menangani modifikasi dalam aplikasi Anda. + Cara ini dijelaskan lebih detail di bagian + <a href="#Intents">Pengambilan dan modifikasi dengan intent</a>. +</p> +<h4>Yield point</h4> +<p> + Modifikasi batch yang berisi operasi dalam jumlah besar bisa memblokir proses lain, + yang mengakibatkan pengalaman pengguna yang buruk secara keseluruhan. Untuk menata semua modifikasi yang ingin Anda + jalankan dalam sesedikit mungkin daftar terpisah, sambil mencegah modifikasi dari + memblokir sistem, Anda harus menetapkan <strong>yield point</strong> untuk satu atau beberapa operasi. + Yield point (titik hasil) adalah objek {@link android.content.ContentProviderOperation} yang mengatur + nilai {@link android.content.ContentProviderOperation#isYieldAllowed()}-nya ke + <code>true</code>. Bila menemui yield point, Penyedia Kontak akan menghentikan pekerjaannya untuk + membiarkan proses lain berjalan dan menutup transaksi saat ini. Bila dimulai lagi, penyedia akan + melanjutkan dengan operasi berikutnya di {@link java.util.ArrayList} dan memulai transaksi + baru. +</p> +<p> + Yield point memang menyebabkan lebih dari satu transaksi per panggilan ke + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Karena + itu, Anda harus menetapkan yield point pada operasi terakhir untuk satu set baris terkait. + Misalnya, Anda harus menetapkan yield point pada operasi terakhir di satu set yang menambahkan + baris kontak mentah dan baris data terkait, atau operasi terakhir untuk satu set baris yang terkait + dengan satu kontak. +</p> +<p> + Yield point juga merupakan unit operasi atomis. Semua akses antara dua yield point bisa + saja berhasil atau gagal sebagai satu unit. Jika Anda mengatur yield point, operasi + atomis terkecil adalah seluruh batch operasi. Jika menggunakan yield point, Anda akan mencegah + operasi menurunkan kinerja sistem, sekaligus memastikan subset + operasi bersifat atomis. +</p> +<h4>Acuan balik modifikasi</h4> +<p> + Saat Anda menyisipkan baris kontak mentah baru dan baris data terkaitnya sebagai satu set + objek {@link android.content.ContentProviderOperation}, Anda harus menautkan baris data ke + baris kontak mentah dengan memasukkan nilai + {@link android.provider.BaseColumns#_ID} kontak mentah sebagai + nilai {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. Akan tetapi, nilai + ini tidak tersedia saat Anda membuat {@link android.content.ContentProviderOperation} + untuk baris data, karena Anda belum menerapkan + {@link android.content.ContentProviderOperation} untuk baris kontak mentah. Solusinya, + kelas {@link android.content.ContentProviderOperation.Builder} memiliki metode + {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()}. + Metode ini memungkinkan Anda menyisipkan atau mengubah kolom dengan + hasil dari operasi sebelumnya. +</p> +<p> + Metode {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + memiliki dua argumen: +</p> + <dl> + <dt> + <code>key</code> + </dt> + <dd> + Kunci dari pasangan kunci-nilai. Nilai argumen ini harus berupa nama kolom + dalam tabel yang Anda modifikasi. + </dd> + <dt> + <code>previousResult</code> + </dt> + <dd> + Indeks berbasis 0 dari nilai pada larik + objek {@link android.content.ContentProviderResult} dari + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. Saat + operasi batch diterapkan, hasil tiap operasi akan disimpan dalam + larik hasil antara. Nilai <code>previousResult</code> adalah indeks + dari salah satu hasil ini, yang diambil dan disimpan bersama nilai <code>key</code>. + Cara ini memungkinkan Anda menyisipkan record kontak mentah baru dan mendapatkan kembali nilai + {@link android.provider.BaseColumns#_ID}-nya, lalu membuat "acuan balik" ke + nilai itu saat Anda menambahkan baris {@link android.provider.ContactsContract.Data}. + <p> + Seluruh larik hasil dibuat saat Anda memanggil + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} untuk pertama kali, + dengan ukuran setara dengan ukuran {@link java.util.ArrayList} dari + objek {@link android.content.ContentProviderOperation} yang Anda sediakan. Akan tetapi, semua + elemen dalam larik hasil diatur ke <code>null</code>, dan jika Anda mencoba + melakukan acuan balik ke hasil untuk operasi yang belum diterapkan, +{@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + akan mengeluarkan {@link java.lang.Exception}. + + </p> + </dd> + </dl> +<p> + Cuplikan kode berikut menampilkan cara menyisipkan kontak mentah baru dan data secara batch. Cuplikan kode ini + menyertakan kode yang menetapkan yield point dan menggunakan acuan balik. Cuplikan kode ini adalah + versi perluasan dari metode<code>createContacEntry()</code>, yang merupakan bagian dari kelas + <code>ContactAdder</code> dalam + aplikasi contoh <code><a href="{@docRoot}resources/samples/ContactManager/index.html"> + Contact Manager</a></code>. +</p> +<p> + Cuplikan pertama mengambil data kontak dari UI. Pada saat ini, pengguna sudah + memilih akun tempat kontak mentah baru harus ditambahkan. +</p> +<pre> +// Creates a contact entry from the current UI values, using the currently-selected account. +protected void createContactEntry() { + /* + * Gets values from the UI + */ + String name = mContactNameEditText.getText().toString(); + String phone = mContactPhoneEditText.getText().toString(); + String email = mContactEmailEditText.getText().toString(); + + int phoneType = mContactPhoneTypes.get( + mContactPhoneTypeSpinner.getSelectedItemPosition()); + + int emailType = mContactEmailTypes.get( + mContactEmailTypeSpinner.getSelectedItemPosition()); +</pre> +<p> + Cuplikan berikutnya membuat operasi untuk menyisipkan baris kontak mentah ke dalam + tabel {@link android.provider.ContactsContract.RawContacts}: +</p> +<pre> + /* + * Prepares the batch operation for inserting a new raw contact and its data. Even if + * the Contacts Provider does not have any data for this person, you can't add a Contact, + * only a raw contact. The Contacts Provider will then add a Contact automatically. + */ + + // Creates a new array of ContentProviderOperation objects. + ArrayList<ContentProviderOperation> ops = + new ArrayList<ContentProviderOperation>(); + + /* + * Creates a new raw contact with its account type (server type) and account name + * (user's account). Remember that the display name is not stored in this row, but in a + * StructuredName data row. No other data is required. + */ + ContentProviderOperation.Builder op = + ContentProviderOperation.newInsert(ContactsContract.RawContacts.CONTENT_URI) + .withValue(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()) + .withValue(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); +</pre> +<p> + Berikutnya, kode akan membuat baris data untuk baris-baris nama tampilan, telepon, dan email. +</p> +<p> + Setiap objek pembangun operasi menggunakan + {@link android.content.ContentProviderOperation.Builder#withValueBackReference(String, int) withValueBackReference()} + untuk mendapatkan + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}. Acuan menunjuk + balik ke objek {@link android.content.ContentProviderResult} dari operasi pertama, + yang menambahkan baris kontak mentah dan mengembalikan nilai {@link android.provider.BaseColumns#_ID} + barunya. Hasilnya, setiap data ditautkan secara otomatis oleh + {@link android.provider.ContactsContract.DataColumns#RAW_CONTACT_ID}-nya + ke baris {@link android.provider.ContactsContract.RawContacts} baru yang memilikinya. +</p> +<p> + Objek {@link android.content.ContentProviderOperation.Builder} yang menambahkan baris email + diberi flag {@link android.content.ContentProviderOperation.Builder#withYieldAllowed(boolean) + withYieldAllowed()}, yang mengatur yield point: +</p> +<pre> + // Creates the display name for the new raw contact, as a StructuredName data row. + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * withValueBackReference sets the value of the first argument to the value of + * the ContentProviderResult indexed by the second argument. In this particular + * call, the raw contact ID column of the StructuredName data row is set to the + * value of the result returned by the first operation, which is the one that + * actually adds the raw contact row. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to StructuredName + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.StructuredName.CONTENT_ITEM_TYPE) + + // Sets the data row's display name to the name in the UI. + .withValue(ContactsContract.CommonDataKinds.StructuredName.DISPLAY_NAME, name); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); + + // Inserts the specified phone number and type as a Phone data row + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * Sets the value of the raw contact id column to the new raw contact ID returned + * by the first operation in the batch. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to Phone + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE) + + // Sets the phone number and type + .withValue(ContactsContract.CommonDataKinds.Phone.NUMBER, phone) + .withValue(ContactsContract.CommonDataKinds.Phone.TYPE, phoneType); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); + + // Inserts the specified email and type as a Phone data row + op = + ContentProviderOperation.newInsert(ContactsContract.Data.CONTENT_URI) + /* + * Sets the value of the raw contact id column to the new raw contact ID returned + * by the first operation in the batch. + */ + .withValueBackReference(ContactsContract.Data.RAW_CONTACT_ID, 0) + + // Sets the data row's MIME type to Email + .withValue(ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE) + + // Sets the email address and type + .withValue(ContactsContract.CommonDataKinds.Email.ADDRESS, email) + .withValue(ContactsContract.CommonDataKinds.Email.TYPE, emailType); + + /* + * Demonstrates a yield point. At the end of this insert, the batch operation's thread + * will yield priority to other threads. Use after every set of operations that affect a + * single contact, to avoid degrading performance. + */ + op.withYieldAllowed(true); + + // Builds the operation and adds it to the array of operations + ops.add(op.build()); +</pre> +<p> + Cuplikan terakhir menampilkan panggilan ke + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()} yang + menyisipkan baris-baris kontak mentah dan data baru. +</p> +<pre> + // Ask the Contacts Provider to create a new contact + Log.d(TAG,"Selected account: " + mSelectedAccount.getName() + " (" + + mSelectedAccount.getType() + ")"); + Log.d(TAG,"Creating contact: " + name); + + /* + * Applies the array of ContentProviderOperation objects in batch. The results are + * discarded. + */ + try { + + getContentResolver().applyBatch(ContactsContract.AUTHORITY, ops); + } catch (Exception e) { + + // Display a warning + Context ctx = getApplicationContext(); + + CharSequence txt = getString(R.string.contactCreationFailure); + int duration = Toast.LENGTH_SHORT; + Toast toast = Toast.makeText(ctx, txt, duration); + toast.show(); + + // Log exception + Log.e(TAG, "Exception encountered while inserting contact: " + e); + } +} +</pre> +<p> + Operasi batch juga memungkinkan Anda menerapkan <strong>kontrol konkurensi optimistis</strong>, + sebuah metode yang menerapkan transaksi modifikasi tanpa harus mengunci repository yang mendasari. + Untuk menggunakan metode ini, terapkan transaksi dan periksa modifikasi lain yang + mungkin telah dibuat bersamaan. Jika ternyata modifikasi tidak konsisten, Anda + mengembalikan transaksi ke kondisi semula dan mencobanya kembali. +</p> +<p> + Kontrol konkurensi optimistis berguna untuk perangkat seluler, apabila hanya ada satu pengguna setiap + kalinya, dan akses simultan ke repository data jarang terjadi. Karena penguncian tidak digunakan, + tidak ada waktu yang terbuang untuk memasang kunci atau menunggu transaksi lain untuk melepas kunci. +</p> +<p> + Untuk menggunakan kontrol konkurensi optimistis saat memperbarui satu baris + {@link android.provider.ContactsContract.RawContacts}, ikuti langkah-langkah ini: +</p> +<ol> + <li> + Ambil kolom {@link android.provider.ContactsContract.SyncColumns#VERSION} + kontak mentah bersama data lain yang Anda ambil. + </li> + <li> + Buat sebuah objek {@link android.content.ContentProviderOperation.Builder} yang cocok untuk + memberlakukan batasan, dengan menggunakan metode + {@link android.content.ContentProviderOperation#newAssertQuery(Uri)}. Untuk URI konten, + gunakan {@link android.provider.ContactsContract.RawContacts#CONTENT_URI + RawContacts.CONTENT_URI} + dengan {@link android.provider.BaseColumns#_ID} kontak mentah yang ditambahkan padanya. + </li> + <li> + Untuk objek {@link android.content.ContentProviderOperation.Builder}, panggil + {@link android.content.ContentProviderOperation.Builder#withValue(String, Object) + withValue()} untuk membandingkan kolom {@link android.provider.ContactsContract.SyncColumns#VERSION} + dengan nomor versi yang baru saja Anda ambil. + </li> + <li> + Untuk {@link android.content.ContentProviderOperation.Builder} yang sama, panggil + {@link android.content.ContentProviderOperation.Builder#withExpectedCount(int) + withExpectedCount()} untuk memastikan bahwa hanya satu baris yang diuji oleh pernyataan ini. + </li> + <li> + Panggil {@link android.content.ContentProviderOperation.Builder#build()} untuk membuat + objek {@link android.content.ContentProviderOperation}, kemudian tambahkan objek ini sebagai + objek pertama di {@link java.util.ArrayList} yang Anda teruskan ke + {@link android.content.ContentResolver#applyBatch(String, ArrayList) applyBatch()}. + </li> + <li> + Terapkan transaksi batch. + </li> +</ol> +<p> + Jika baris kontak mentah diperbarui oleh operasi lain antara waktu Anda membaca baris dan + waktu Anda mencoba memodifikasinya, "asert" {@link android.content.ContentProviderOperation} + akan gagal, dan seluruh batch operasi akan dibatalkan. Anda nanti bisa memilih untuk mencoba ulang + batch atau melakukan tindakan lain. +</p> +<p> + Cuplikan berikut memperagakan cara membuat "asert" + {@link android.content.ContentProviderOperation} setelah membuat query satu kontak mentah yang menggunakan + {@link android.content.CursorLoader}: +</p> +<pre> +/* + * The application uses CursorLoader to query the raw contacts table. The system calls this method + * when the load is finished. + */ +public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) { + + // Gets the raw contact's _ID and VERSION values + mRawContactID = cursor.getLong(cursor.getColumnIndex(BaseColumns._ID)); + mVersion = cursor.getInt(cursor.getColumnIndex(SyncColumns.VERSION)); +} + +... + +// Sets up a Uri for the assert operation +Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, mRawContactID); + +// Creates a builder for the assert operation +ContentProviderOperation.Builder assertOp = ContentProviderOperation.netAssertQuery(rawContactUri); + +// Adds the assertions to the assert operation: checks the version and count of rows tested +assertOp.withValue(SyncColumns.VERSION, mVersion); +assertOp.withExpectedCount(1); + +// Creates an ArrayList to hold the ContentProviderOperation objects +ArrayList ops = new ArrayList<ContentProviderOperationg>; + +ops.add(assertOp.build()); + +// You would add the rest of your batch operations to "ops" here + +... + +// Applies the batch. If the assert fails, an Exception is thrown +try + { + ContentProviderResult[] results = + getContentResolver().applyBatch(AUTHORITY, ops); + + } catch (OperationApplicationException e) { + + // Actions you want to take if the assert operation fails go here + } +</pre> +<h3 id="Intents">Pengambilan dan modifikasi dengan intent</h3> +<p> + Mengirimkan intent ke aplikasi kontak perangkat memungkinkan Anda mengakses Penyedia Kontak + secara tidak langsung. Intent akan memulai UI aplikasi kontak perangkat, tempat pengguna bisa + melakukan pekerjaan yang terkait dengan kontak. Dengan tipe akses ini, pengguna bisa: + <ul> + <li>Memilih kontak dari daftar dan meneruskannya ke aplikasi untuk pekerjaan lebih jauh.</li> + <li>Mengedit data kontak yang ada.</li> + <li>Memasukkan kontak mentah baru untuk akun mereka.</li> + <li>Menghapus kontak atau data kontak.</li> + </ul> +<p> + Jika pengguna menyisipkan atau memperbarui data, Anda bisa mengumpulkan data lebih dahulu dan mengirimkannya sebagai + bagian dari intent. +</p> +<p> + Bila Anda menggunakan intent untuk mengakses Penyedia Kontak melalui aplikasi kontak perangkat, Anda + tidak perlu menulis UI atau kode sendiri untuk mengakses penyedia. Anda juga tidak harus + meminta izin untuk membaca dari atau menulis ke penyedia. Aplikasi kontak perangkat bisa + mendelegasikan izin membaca untuk kontak kepada Anda, dan karena Anda membuat modifikasi pada + penyedia melalui aplikasi lain, Anda tidak perlu memiliki izin menulis. +</p> +<p> + Proses umum pengiriman intent untuk mengakses penyedia dijelaskan secara detail dalam panduan + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a> di bagian "Akses data melalui intent". Tindakan, + tipe MIME, dan nilai data yang Anda gunakan untuk tugas yang tersedia dirangkum dalam Tabel 4, sedangkan + nilai ekstra yang bisa Anda gunakan bersama + {@link android.content.Intent#putExtra(String, String) putExtra()} tercantum dalam + dokumentasi acuan untuk {@link android.provider.ContactsContract.Intents.Insert}: +</p> +<p class="table-caption" id="table4"> + <strong>Tabel 4.</strong> Intent Penyedia Kontak. +</p> +<table style="width:75%"> + <tr> + <th scope="col" style="width:10%">Tugas</th> + <th scope="col" style="width:5%">Tindakan</th> + <th scope="col" style="width:10%">Data</th> + <th scope="col" style="width:10%">Tipe MIME</th> + <th scope="col" style="width:25%">Catatan</th> + </tr> + <tr> + <td><strong>Memilih kontak dari daftar</strong></td> + <td>{@link android.content.Intent#ACTION_PICK}</td> + <td> + Salah satu dari: + <ul> + <li> +{@link android.provider.ContactsContract.Contacts#CONTENT_URI Contacts.CONTENT_URI}, + yang menampilkan daftar kontak. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.Phone#CONTENT_URI Phone.CONTENT_URI}, + yang menampilkan daftar nomor telepon untuk kontak mentah. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.StructuredPostal#CONTENT_URI +StructuredPostal.CONTENT_URI}, + yang menampilkan daftar alamat pos untuk kontak mentah. + </li> + <li> +{@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_URI Email.CONTENT_URI}, + yang menampilkan daftar alamat email untuk kontak baru. + </li> + </ul> + </td> + <td> + Tidak digunakan + </td> + <td> + Menampilkan daftar kontak mentah atau daftar data dari kontak mentah, sesuai dengan tipe + URI konten yang Anda sediakan. + <p> + Panggil + {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, + yang menghasilkan URI konten dari baris terpilih. Bentuk URI adalah + URI konten tabel dengan <code>LOOKUP_ID</code> baris yang ditambahkan padanya. + Aplikasi kontak perangkat mendelegasikan izin membaca dan menulis untuk URI konten ini + selama masa pakai aktivitas Anda. Lihat panduan + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a> untuk detail selengkapnya. + </p> + </td> + </tr> + <tr> + <td><strong>Menyisipkan kontak mentah baru</strong></td> + <td>{@link android.provider.ContactsContract.Intents.Insert#ACTION Insert.ACTION}</td> + <td>N/A</td> + <td> + {@link android.provider.ContactsContract.RawContacts#CONTENT_TYPE + RawContacts.CONTENT_TYPE}, tipe MIME untuk satu set kontak mentah. + </td> + <td> + Menampilkan layar <strong>Add Contact</strong> aplikasi kontak perangkat. Nilai + ekstra yang Anda tambahkan ke intent akan ditampilkan. Jika dikirimkan bersama + {@link android.app.Activity#startActivityForResult(Intent, int) startActivityForResult()}, + URI konten dari kontak mentah yang baru saja ditambahkan akan dikembalikan ke + {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()} + metode callback aktivitas Anda pada argumen {@link android.content.Intent}, di + bidang "data". Untuk mendapatkan nilainya, panggil {@link android.content.Intent#getData()}. + </td> + </tr> + <tr> + <td><strong>Mengedit kontak</strong></td> + <td>{@link android.content.Intent#ACTION_EDIT}</td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI} untuk + kontak. Aktivitas editor memungkinkan pengguna mengedit setiap data yang dikaitkan + dengan kontak ini. + </td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE + Contacts.CONTENT_ITEM_TYPE}, kontak tunggal.</td> + <td> + Menampilkan layar Edit Contact dalam aplikasi kontak. Nilai ekstra yang Anda tambahkan + ke intent akan ditampilkan. Bila pengguna mengklik <strong>Done</strong> untuk menyimpan + hasil edit, aktivitas Anda kembali ke latar depan. + </td> + </tr> + <tr> + <td><strong>Menampilkan picker yang juga bisa menambahkan data.</strong></td> + <td>{@link android.content.Intent#ACTION_INSERT_OR_EDIT}</td> + <td> + N/A + </td> + <td> + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE} + </td> + <td> + Intent ini selalu menampilkan layar picker aplikasi kontak. Pengguna bisa memilih + kontak untuk diedit, atau menambahkan kontak baru. Layar edit atau layar tambah + akan muncul, sesuai dengan pilihan pengguna, dan data ekstra yang Anda kirimkan dalam intent + akan ditampilkan. Jika aplikasi Anda menampilkan data kontak seperti email atau nomor telepon, gunakan + intent ini untuk memungkinkan pengguna menambahkan data ke kontak yang ada. + + <p class="note"> + <strong>Catatan:</strong> Tidak perlu mengirimkan nilai nama dalam ekstra intent ini, + karena pengguna selalu mengambil nama yang ada atau menambahkan nama baru. Lebih-lebih, + jika Anda mengirimkan nama, dan pengguna memilih untuk melakukan edit, aplikasi kontak akan + menampilkan nama yang Anda kirimkan, yang menimpa nilai sebelumnya. Jika pengguna tidak + menyadari hal ini dan menyimpan hasil edit, nilai lama akan hilang. + </p> + </td> + </tr> +</table> +<p> + Aplikasi kontak perangkat tidak memperbolehkan Anda menghapus kontak mentah atau datanya dengan + intent. Sebagai gantinya, untuk menghapus kontak mentah, gunakan + {@link android.content.ContentResolver#delete(Uri, String, String[]) ContentResolver.delete()} + atau {@link android.content.ContentProviderOperation#newDelete(Uri) + ContentProviderOperation.newDelete()}. +</p> +<p> + Cuplikan berikut menampilkan cara menyusun dan mengirimkan intent yang menyisipkan kontak dan data + mentah baru: +</p> +<pre> +// Gets values from the UI +String name = mContactNameEditText.getText().toString(); +String phone = mContactPhoneEditText.getText().toString(); +String email = mContactEmailEditText.getText().toString(); + +String company = mCompanyName.getText().toString(); +String jobtitle = mJobTitle.getText().toString(); + +// Creates a new intent for sending to the device's contacts application +Intent insertIntent = new Intent(ContactsContract.Intents.Insert.ACTION); + +// Sets the MIME type to the one expected by the insertion activity +insertIntent.setType(ContactsContract.RawContacts.CONTENT_TYPE); + +// Sets the new contact name +insertIntent.putExtra(ContactsContract.Intents.Insert.NAME, name); + +// Sets the new company and job title +insertIntent.putExtra(ContactsContract.Intents.Insert.COMPANY, company); +insertIntent.putExtra(ContactsContract.Intents.Insert.JOB_TITLE, jobtitle); + +/* + * Demonstrates adding data rows as an array list associated with the DATA key + */ + +// Defines an array list to contain the ContentValues objects for each row +ArrayList<ContentValues> contactData = new ArrayList<ContentValues>(); + + +/* + * Defines the raw contact row + */ + +// Sets up the row as a ContentValues object +ContentValues rawContactRow = new ContentValues(); + +// Adds the account type and name to the row +rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_TYPE, mSelectedAccount.getType()); +rawContactRow.put(ContactsContract.RawContacts.ACCOUNT_NAME, mSelectedAccount.getName()); + +// Adds the row to the array +contactData.add(rawContactRow); + +/* + * Sets up the phone number data row + */ + +// Sets up the row as a ContentValues object +ContentValues phoneRow = new ContentValues(); + +// Specifies the MIME type for this data row (all data rows must be marked by their type) +phoneRow.put( + ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Phone.CONTENT_ITEM_TYPE +); + +// Adds the phone number and its type to the row +phoneRow.put(ContactsContract.CommonDataKinds.Phone.NUMBER, phone); + +// Adds the row to the array +contactData.add(phoneRow); + +/* + * Sets up the email data row + */ + +// Sets up the row as a ContentValues object +ContentValues emailRow = new ContentValues(); + +// Specifies the MIME type for this data row (all data rows must be marked by their type) +emailRow.put( + ContactsContract.Data.MIMETYPE, + ContactsContract.CommonDataKinds.Email.CONTENT_ITEM_TYPE +); + +// Adds the email address and its type to the row +emailRow.put(ContactsContract.CommonDataKinds.Email.ADDRESS, email); + +// Adds the row to the array +contactData.add(emailRow); + +/* + * Adds the array to the intent's extras. It must be a parcelable object in order to + * travel between processes. The device's contacts app expects its key to be + * Intents.Insert.DATA + */ +insertIntent.putParcelableArrayListExtra(ContactsContract.Intents.Insert.DATA, contactData); + +// Send out the intent to start the device's contacts app in its add contact activity. +startActivity(insertIntent); +</pre> +<h3 id="DataIntegrity">Integritas data</h3> +<p> + Karena repository kontak berisi data penting dan sensitif yang diharapkan pengguna agar + benar dan terbaru. Penyedia Kontak memiliki aturan yang didefinisikan dengan baik demi integritas data. Anda + bertanggung jawab untuk mematuhi aturan ini saat memodifikasi data kontak. Aturan-aturan penting itu + dicantumkan di sini: +</p> +<dl> + <dt> + Selalu tambahkan baris {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} + untuk setiap baris {@link android.provider.ContactsContract.RawContacts} yang Anda tambahkan. + </dt> + <dd> + Baris {@link android.provider.ContactsContract.RawContacts} tanpa + baris {@link android.provider.ContactsContract.CommonDataKinds.StructuredName} dalam + tabel {@link android.provider.ContactsContract.Data} bisa menyebabkan masalah selama + agregasi. + </dd> + <dt> + Selalu tautkan baris {@link android.provider.ContactsContract.Data} baru ke baris + {@link android.provider.ContactsContract.RawContacts} induknya. + </dt> + <dd> + Baris {@link android.provider.ContactsContract.Data} yang tidak ditautkan ke + {@link android.provider.ContactsContract.RawContacts} tidak akan terlihat dalam aplikasi kontak + perangkat, dan itu bisa menimbulkan masalah dengan adaptor sinkronisasi. + </dd> + <dt> + Ubah data hanya untuk kontak mentah yang Anda miliki. + </dt> + <dd> + Ingatlah bahwa Penyedia Kontak biasanya mengelola data dari berbagai + tipe akun/layanan online. Anda harus memastikan bahwa aplikasi Anda hanya memodifikasi + atau menghapus data untuk baris milik Anda, dan bahwa aplikasi hanya menyisipkan data dengan + tipe akun dan nama yang Anda kontrol. + </dd> + <dt> + Selalu gunakan konstanta yang didefinisikan dalam {@link android.provider.ContactsContract} dan + subkelasnya untuk otoritas, URI konten, URI path, nama kolom, tipe MIME, dan + nilai {@link android.provider.ContactsContract.CommonDataKinds.CommonColumns#TYPE}. + </dt> + <dd> + Menggunakan konstanta ini membantu Anda menghindari kesalahan. Anda juga akan diberi tahu dengan peringatan + compiler jika salah satu konstanta sudah usang. + </dd> +</dl> +<h3 id="CustomData">Baris data custom</h3> +<p> + Dengan membuat dan menggunakan tipe MIME custom sendiri, Anda bisa menyisipkan, mengedit, menghapus, dan mengambil + baris data sendiri dalam tabel {@link android.provider.ContactsContract.Data}. Baris Anda + dibatasi untuk menggunakan kolom yang didefinisikan dalam + {@link android.provider.ContactsContract.DataColumns}, meskipun Anda bisa memetakan nama kolom + bertipe spesifik sendiri ke nama kolom default. Dalam aplikasi kontak perangkat, + data untuk baris Anda ditampilkan, tetapi tidak bisa diedit atau dihapus, dan pengguna tidak bisa menambahkan + data lain. Untuk memudahkan pengguna mengubah baris data custom Anda, Anda harus menyediakan aktivitas + editor dalam aplikasi Anda sendiri. +</p> +<p> + Untuk menampilkan data custom, sediakan file <code>contacts.xml</code> berisi elemen + <code><ContactsAccountType></code> dan satu atau beberapa elemen anak + <code><ContactsDataKind></code>. Hal ini dijelaskan lebih detail di + bagian <a href="#SocialStreamDataKind"><code><ContactsDataKind> element</code></a>. +</p> +<p> + Untuk mengetahui selengkapnya tentang tipe MIME custom, bacalah panduan + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Membuat Penyedia Konten</a>. +</p> +<h2 id="SyncAdapters">Adaptor Sinkronisasi Penyedia Kontak</h2> +<p> + Penyedia Kontak didesain khusus untuk menangani <strong>sinkronisasi</strong> + data kontak antara perangkat dan layanan online. Hal ini memungkinkan pengguna mengunduh + data yang ada dari perangkat baru dan mengunggah data yang ada ke akun baru. + Sinkronisasi juga memastikan bahwa pengguna memiliki data terbaru, apa pun + sumber penambahan dan perubahan itu. Keuntungan lain dari sinkronisasi adalah membuat + data kontak tersedia sekalipun perangkat tidak terhubung ke jaringan. +</p> +<p> + Walaupun Anda bisa menerapkan sinkronisasi dengan berbagai cara, sistem Android menyediakan + kerangka kerja sinkronisasi plug-in yang mengotomatiskan tugas-tugas berikut: + <ul> + + <li> + Memeriksa ketersediaan jaringan. + </li> + <li> + Menjadwalkan dan menjalankan sinkronisasi, berdasarkan preferensi pengguna. + </li> + <li> + Memulai kembali sinkronisasi yang telah berhenti. + </li> + </ul> +<p> + Untuk menggunakan kerangka kerja ini, Anda harus menyediakan plug-in adaptor sinkronisasi. Setiap adaptor sinkronisasi bersifat unik bagi + layanan dan penyedia konten, tetapi mampu menangani beberapa nama akun untuk layanan yang sama. Kerangka + kerja ini juga memungkinkan beberapa adaptor sinkronisasi untuk layanan dan penyedia yang sama. +</p> +<h3 id="SyncClassesFiles">Kelas dan file adaptor sinkronisasi</h3> +<p> + Anda mengimplementasikan adaptor sinkronisasi sebagai subkelas + {@link android.content.AbstractThreadedSyncAdapter} dan menginstalnya sebagai bagian dari aplikasi + Android. Sistem akan mempelajari adaptor sinkronisasi dari elemen-elemen di manifes + aplikasi Anda dan dari file XML khusus yang ditunjuk oleh manifes. File XML mendefinisikan + tipe akun untuk layanan online dan otoritas untuk penyedia konten, yang bersama-sama + mengidentifikasi adaptor secara unik. Adaptor sinkronisasi tidak menjadi aktif hingga pengguna menambahkan + akun untuk tipe akun adaptor sinkronisasi dan memungkinkan sinkronisasi untuk penyedia + konten yang disinkronkan dengan adaptor sinkronisasi. Pada saat itu, sistem mulai mengelola adaptor, + memanggilnya seperlunya untuk menyinkronkan antara penyedia konten dan server. +</p> +<p class="note"> + <strong>Catatan:</strong> Menggunakan tipe akun sebagai bagian dari identifikasi adaptor sinkronisasi memungkinkan + sistem mendeteksi dan menghimpun adaptor-adaptor sinkronisasi yang mengakses berbagai layanan dari + organisasi yang sama. Misalnya, adaptor sinkronisasi untuk semua layanan online Google semuanya memiliki tipe akun + yang sama <code>com.google</code>. Bila pengguna menambahkan akun Google ke perangkatnya, semua + adaptor sinkronisasi yang terinstal untuk layanan Google akan dicantumkan bersama; setiap adaptor sinkronisasi + yang tercantum akan menyinkronkan diri dengan berbagai penyedia konten pada perangkat. +</p> +<p> + Karena sebagian besar layanan mengharuskan pengguna untuk memeriksa identitas sebelum mengakses + data, sistem Android menawarkan kerangka kerja autentikasi yang serupa dengan, dan sering kali + digunakan bersama, kerangka kerja adaptor sinkronisasi. Kerangka kerja autentikasi menggunakan + autentikator plug-in yang merupakan subkelas + {@link android.accounts.AbstractAccountAuthenticator}. Autentikator memeriksa + identitas pengguna dalam langkah-langkah berikut: + <ol> + <li> + Mengumpulkan nama pengguna, kata sandi, atau informasi serupa ( + <strong>kredensial</strong> pengguna). + </li> + <li> + Mengirimkan kredensial ke layanan + </li> + <li> + Memeriksa balasan layanan. + </li> + </ol> +<p> + Jika layanan menerima kredensial, autentikator bisa + menyimpan kredensial itu untuk digunakan nanti. Karena kerangka kerja autentikator plug-in, + {@link android.accounts.AccountManager} bisa menyediakan akses ke setiap token autentikasi yang didukung suatu autentikator + dan dipilihnya untuk diekspos, seperti token autentikasi OAuth2. +</p> +<p> + Meskipun autentikasi tidak diharuskan, sebagian besar layanan kontak menggunakannya. + Akan tetapi, Anda tidak wajib menggunakan kerangka kerja autentikasi Android untuk melakukan autentikasi. +</p> +<h3 id="SyncAdapterImplementing">Implementasi adaptor sinkronisasi</h3> +<p> + Untuk mengimplementasikan adaptor sinkronisasi bagi Penyedia Kontak, perlu Anda memulai dengan membuat + aplikasi Android yang berisi elemen-elemen berikut: +</p> + <dl> + <dt> + Komponen {@link android.app.Service} yang merespons permintaan sistem untuk + mengikat ke adaptor sinkronisasi. + </dt> + <dd> + Bila sistem ingin menjalankan sinkronisasi, sistem akan memanggil metode + {@link android.app.Service#onBind(Intent) onBind()} layanan untuk mendapatkan + {@link android.os.IBinder} bagi adaptor sinkronisasi. Hal ini memungkinkan sistem melakukan + panggilan lintas proses ke metode adaptor. + <p> + Dalam contoh aplikasi <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a>, nama kelas layanan ini adalah + <code>com.example.android.samplesync.syncadapter.SyncService</code>. + </p> + </dd> + <dt> + Adaptor sinkronisasi yang sesungguhnya, diimplementasikan sebagai subkelas konkret dari + {@link android.content.AbstractThreadedSyncAdapter}. + </dt> + <dd> + Kelas ini melakukan pekerjaan mengunduh data dari server, mengunggah data ke + perangkat, dan menyelesaikan konflik. Pekerjaan utama adaptor + diselesaikan dengan metode {@link android.content.AbstractThreadedSyncAdapter#onPerformSync( + Account, Bundle, String, ContentProviderClient, SyncResult) + onPerformSync()}. Instance kelas ini harus dibuat sebagai singleton. + <p> + Dalam contoh aplikasi <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a>, adaptor sinkronisasi didefinisikan dalam kelas + <code>com.example.android.samplesync.syncadapter.SyncAdapter</code>. + </p> + </dd> + <dt> + Subkelas {@link android.app.Application}. + </dt> + <dd> + Kelas ini berfungsi sebagai pabrik untuk singleton adaptor sinkronisasi. Gunakan + metode {@link android.app.Application#onCreate()} untuk membuat instance adaptor sinkronisasi , dan + menyediakan metode "getter" statis untuk mengembalikan singleton ke + metode {@link android.app.Service#onBind(Intent) onBind()} dari layanan + adaptor sinkronisasi. + </dd> + <dt> + <strong>Opsional:</strong> Komponen {@link android.app.Service} yang merespons + permintaan dari sistem untuk autentikasi pengguna. + </dt> + <dd> + {@link android.accounts.AccountManager} memulai layanan ini untuk memulai proses + autentikasi. Metode {@link android.app.Service#onCreate()} layanan membuat instance + objek autentikator. Bila sistem ingin mengautentikasi akun pengguna untuk + adaptor sinkronisasi aplikasi, sistem akan memanggil metode +{@link android.app.Service#onBind(Intent) onBind()} layanan guna mendapatkan + {@link android.os.IBinder} bagi autentikator. Hal ini memungkinkan sistem melakukan + panggilan lintas proses ke metode autentikator. + <p> + Dalam contoh aplikasi <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a>, nama kelas layanan ini adalah + <code>com.example.android.samplesync.authenticator.AuthenticationService</code>. + </p> + </dd> + <dt> + <strong>Opsional:</strong> Subkelas konkret + {@link android.accounts.AbstractAccountAuthenticator} yang menangani permintaan + autentikasi. + </dt> + <dd> + Kelas ini menyediakan metode yang dipicu {@link android.accounts.AccountManager} + untuk mengautentikasi kredensial pengguna dengan layanan. Detail + proses autentikasi sangat bervariasi, berdasarkan teknologi server yang digunakan. Anda harus + mengacu ke dokumentasi bagi perangkat lunak server untuk mengetahui selengkapnya tentang autentikasi. + <p> + Dalam contoh aplikasi <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a>, autentikator didefinisikan dalam kelas + <code>com.example.android.samplesync.authenticator.Authenticator</code>. + </p> + </dd> + <dt> + File XML yang mendefinisikan adaptor sinkronisasi dan autentikator bagi sistem. + </dt> + <dd> + Komponen-komponen layanan adaptor sinkronisasi dan autentikator + didefinisikan dalam elemen-elemen +<code><<a href="{@docRoot}guide/topics/manifest/service-element.html">service</a>></code> + di manifes aplikasi. Elemen-elemen ini + berisi +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> +elemen anak yang menyediakan data tertentu ke + sistem: + <ul> + <li> + Elemen +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> + untuk layanan adaptor sinkronisasi menunjuk ke + file XML <code>res/xml/syncadapter.xml</code>. Pada gilirannya, file ini mendefinisikan + URI untuk layanan web yang akan disinkronkan dengan Penyedia Kontak, + dan tipe akun untuk layanan web. + </li> + <li> + <strong>Opsional:</strong> Elemen +<code><<a href="{@docRoot}guide/topics/manifest/meta-data-element.html">meta-data</a>></code> + untuk autentikator menunjuk ke file XML + <code>res/xml/authenticator.xml</code>. Pada gilirannya, file ini menetapkan + tipe akun yang didukung autentikator, serta sumber daya UI yang + muncul selama proses autentikasi. Tipe akun yang ditetapkan dalam elemen ini + harus sama dengan tipe akun yang ditetapkan untuk adaptor + sinkronisasi. + </li> + </ul> + </dd> + </dl> +<h2 id="SocialStream">Data Aliran Sosial</h2> +<p> + Tabel-tabel {@link android.provider.ContactsContract.StreamItems} dan + {@link android.provider.ContactsContract.StreamItemPhotos} + mengelola data yang masuk dari jaringan sosial. Anda bisa menulis adaptor sinkronisasi yang menambahkan data aliran + dari jaringan Anda sendiri ke tabel-tabel ini, atau Anda bisa membaca data aliran dari tabel-tabel ini dan + menampilkannya dalam aplikasi sendiri, atau keduanya. Dengan fitur-fitur ini, layanan dan aplikasi + jaringan sosial Anda bisa diintegrasikan ke dalam pengalaman jaringan sosial Android. +</p> +<h3 id="StreamText">Teks aliran sosial</h3> +<p> + Item aliran selalu dikaitkan dengan kontak mentah. + {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID} menautkan ke + nilai <code>_ID</code> untuk kontak mentah. Tipe akun dan nama akun kontak + mentah juga disimpan dalam baris item aliran. +</p> +<p> + Simpanlah data dari aliran Anda dalam kolom-kolom berikut: +</p> +<dl> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_TYPE} + </dt> + <dd> + <strong>Diperlukan.</strong> Tipe akun pengguna untuk kontak mentah yang dikaitkan dengan + item aliran ini. Ingatlah untuk mengatur nilai ini saat Anda menyisipkan item aliran. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#ACCOUNT_NAME} + </dt> + <dd> + <strong>Diperlukan.</strong> Nama akun pengguna untuk kontak mentah yang dikaitkan dengan + item aliran ini. Ingatlah untuk mengatur nilai ini saat Anda menyisipkan item aliran. + </dd> + <dt> + Kolom identifier + </dt> + <dd> + <strong>Diperlukan.</strong> Anda harus memasukkan kolom identifier berikut saat + menyisipkan item aliran: + <ul> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_ID}: + Nilai {@link android.provider.BaseColumns#_ID} kontak yang dikaitkan dengan item aliran + ini. + </li> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#CONTACT_LOOKUP_KEY}: + Nilai {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} + kontak yang dikaitkan dengan item aliran ini. + </li> + <li> + {@link android.provider.ContactsContract.StreamItemsColumns#RAW_CONTACT_ID}: + Nilai {@link android.provider.BaseColumns#_ID} kontak mentah yang dikaitkan dengan item aliran + ini. + </li> + </ul> + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#COMMENTS} + </dt> + <dd> + Opsional. Menyimpan informasi rangkuman yang bisa Anda tampilkan di awal item aliran. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#TEXT} + </dt> + <dd> + Teks item aliran, baik konten yang diposting oleh sumber item, + maupun keterangan beberapa tindakan yang menghasilkan item aliran. Kolom ini bisa berisi + sembarang gambar sumber daya pemformatan dan tertanam yang bisa dirender oleh + {@link android.text.Html#fromHtml(String) fromHtml()}. Penyedia bisa memotong atau + menghapus konten yang panjang, tetapi penyedia akan mencoba menghindari memutus tag. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} + </dt> + <dd> + String teks berisi waktu item aliran yang disisipkan atau diperbarui, berupa + <em>milidetik</em> sejak waktu patokan. Aplikasi yang menyisipkan atau memperbarui item aliran + bertanggung jawab memelihara kolom ini; aplikasi tidak dipelihara secara otomatis oleh + Penyedia Kontak. + </dd> +</dl> +<p> + Untuk menampilkan informasi pengidentifikasi item aliran Anda, gunakan + {@link android.provider.ContactsContract.StreamItemsColumns#RES_ICON}, + {@link android.provider.ContactsContract.StreamItemsColumns#RES_LABEL}, dan + {@link android.provider.ContactsContract.StreamItemsColumns#RES_PACKAGE} untuk menautkan ke sumber daya + dalam aplikasi Anda. +</p> +<p> + Tabel {@link android.provider.ContactsContract.StreamItems} juga berisi kolom-kolom + {@link android.provider.ContactsContract.StreamItemsColumns#SYNC1} hingga + {@link android.provider.ContactsContract.StreamItemsColumns#SYNC4} untuk penggunaan eksklusif oleh + adaptor sinkronisasi. +</p> +<h3 id="StreamPhotos">Foto aliran sosial</h3> +<p> + Tabel {@link android.provider.ContactsContract.StreamItemPhotos} menyimpan foto-foto yang dikaitkan + dengan item aliran. Kolom +{@link android.provider.ContactsContract.StreamItemPhotosColumns#STREAM_ITEM_ID} tabel ini + menautkan ke nilai dalam kolom {@link android.provider.BaseColumns#_ID} + tabel {@link android.provider.ContactsContract.StreamItems}. Acuan foto disimpan dalam + tabel pada kolom-kolom ini: +</p> +<dl> + <dt> + Kolom {@link android.provider.ContactsContract.StreamItemPhotos#PHOTO} (BLOB). + </dt> + <dd> + Representasi biner foto, yang diubah ukurannya oleh penyedia untuk penyimpanan dan tampilan. + Kolom ini tersedia untuk kompatibilitas ke belakang dengan versi Penyedia Kontak + sebelumnya yang menggunakannya untuk menyimpan foto. Akan tetapi, pada versi saat ini + Anda tidak boleh menggunakan kolom ini untuk menyimpan foto. Sebagai gantinya, gunakan + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} atau + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} (keduanya + dijelaskan dalam poin-poin berikut) untuk menyimpan foto di file. Kolom ini sekarang + berisi thumbnail foto, yang tersedia untuk dibaca. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_FILE_ID} + </dt> + <dd> + Identifier numerik foto untuk kontak mentah. Tambahkan nilai ini ke konstanta + {@link android.provider.ContactsContract.DisplayPhoto#CONTENT_URI DisplayPhoto.CONTENT_URI} + untuk mendapatkan URI konten yang menunjuk ke satu file foto, kemudian panggil + {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) + openAssetFileDescriptor()} untuk mendapatkan handle ke file foto. + </dd> + <dt> + {@link android.provider.ContactsContract.StreamItemPhotosColumns#PHOTO_URI} + </dt> + <dd> + URI konten menunjuk langsung ke file foto untuk foto yang diwakili oleh baris ini. + Panggillah {@link android.content.ContentResolver#openAssetFileDescriptor(Uri, String) + openAssetFileDescriptor()} dengan URI ini untuk mendapatkan handle ke file foto. + </dd> +</dl> +<h3 id="SocialStreamTables">Menggunakan tabel aliran sosial</h3> +<p> + Tabel-tabel ini sama fungsinya dengan tabel-tabel utama lainnya dalam Penyedia Kontak, kecuali: +</p> + <ul> + <li> + Tabel-tabel ini memerlukan izin akses tambahan. Untuk membaca dari tabel, aplikasi Anda + harus memiliki izin {@link android.Manifest.permission#READ_SOCIAL_STREAM}. Untuk memodifikasi + tabel, aplikasi Anda harus memiliki izin + {@link android.Manifest.permission#WRITE_SOCIAL_STREAM}. + </li> + <li> + Untuk tabel {@link android.provider.ContactsContract.StreamItems}, jumlah baris + yang disimpan bagi setiap kontak mentah adalah terbatas. Setelah batasnya tercapai, + Penyedia Kontak akan membuat ruang untuk baris item aliran baru dengan menghapus secara otomatis + baris yang memiliki + {@link android.provider.ContactsContract.StreamItemsColumns#TIMESTAMP} terlama. Untuk mendapatkan + batas, keluarkan query ke URI konten + {@link android.provider.ContactsContract.StreamItems#CONTENT_LIMIT_URI}. Anda bisa membiarkan + semua argumen selain URI konten diatur ke <code>null</code>. Query + menghasilkan sebuah Kursor yang berisi baris tunggal, dengan kolom tunggal + {@link android.provider.ContactsContract.StreamItems#MAX_ITEMS}. + </li> + </ul> + +<p> + Kelas {@link android.provider.ContactsContract.StreamItems.StreamItemPhotos} mendefinisikan + subtabel {@link android.provider.ContactsContract.StreamItemPhotos} yang berisi + baris foto untuk satu item aliran. +</p> +<h3 id="SocialStreamInteraction">Interaksi aliran sosial</h3> +<p> + Data aliran sosial yang dikelola oleh Penyedia Kontak, bersama aplikasi kontak + perangkat, menawarkan cara andal untuk menghubungkan sistem jaringan sosial Anda + dengan kontak yang ada. Tersedia fitur-fitur berikut: +</p> + <ul> + <li> + Dengan menyinkronkan layanan jaringan sosial ke Penyedia Kontak dengan adaptor + sinkronisasi, Anda bisa mengambil aktivitas terbaru untuk kontak pengguna dan menyimpannya dalam tabel-tabel + {@link android.provider.ContactsContract.StreamItems} dan + {@link android.provider.ContactsContract.StreamItemPhotos} untuk digunakan nanti. + </li> + <li> + Selain sinkronisasi rutin, Anda bisa memicu adaptor sinkronisasi agar mengambil + data tambahan bila pengguna memilih sebuah kontak untuk ditampilkan. Hal ini memungkinkan adaptor sinkronisasi Anda + mengambil foto resolusi tinggi dan item aliran terbaru untuk kontak. + </li> + <li> + Dengan mendaftarkan pemberitahuan pada aplikasi kontak perangkat dan Penyedia Kontak, + Anda bisa <em>menerima</em> intent saat kontak ditampilkan, dan pada saat itu + memperbarui status kontak dari layanan Anda. Pendekatan ini mungkin lebih cepat dan menggunakan + bandwidth lebih sedikit daripada melakukan sinkronisasi penuh dengan adaptor sinkronisasi. + </li> + <li> + Pengguna bisa menambahkan kontak ke layanan jaringan sosial Anda sambil melihat kontak + dalam aplikasi kontak perangkat. Anda mengaktifkannya dengan fitur "invite contact", + yang Anda aktifkan dengan kombinasi aktivitas yang menambahkan kontak yang ada ke jaringan + Anda, dan file XML yang menyediakan aplikasi kontak perangkat dan + Penyedia Kontak dengan detail aplikasi Anda. + </li> + </ul> +<p> + Sinkronisasi rutin item aliran dengan Penyedia Kontak sama dengan + sinkronisasi lainnya. Untuk mengetahui selengkapnya tentang sinkronisasi, lihat bagian + <a href="#SyncAdapters">Adaptor Sinkronisasi Penyedia Kontak</a>. Mendaftarkan pemberitahuan dan + mengundang kontak dibahas dalam dua bagian berikutnya. +</p> +<h4>Pendaftaran untuk menangani tampilan jaringan sosial</h4> +<p> + Untuk mendaftarkan adaptor sinkronisasi agar menerima pemberitahuan saat pengguna menampilkan kontak + yang dikelola oleh adaptor sinkronisasi Anda: +</p> +<ol> + <li> + Buat file yang bernama <code>contacts.xml</code> dalam direktori <code>res/xml/</code> + proyek Anda. Jika sudah memiliki file ini, langkah ini boleh dilewati. + </li> + <li> + Dalam file ini, tambahkan elemen +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + Jika elemen ini sudah ada, langkah ini boleh dilewati. + </li> + <li> + Untuk mendaftarkan layanan yang diberitahukan saat pengguna membuka halaman detail kontak dalam + aplikasi kontak perangkat, tambahkan atribut + <code>viewContactNotifyService="<em>serviceclass</em>"</code> ke elemen, dengan + <code><em>serviceclass</em></code> sebagai nama kelas mutlak (fully qualified) dari layanan + yang seharusnya menerima intent dari aplikasi kontak perangkat. Untuk layanan + notifier, gunakan kelas yang memperluas {@link android.app.IntentService}, guna memudahkan layanan + untuk menerima intent. Data dalam intent yang masuk berisi URI konten dari kontak + mentah yang diklik pengguna. Untuk layanan notifier, Anda bisa mengikatnya ke kemudian memanggil + adaptor sinkronisasi Anda untuk memperbarui data bagi kontak mentah. + </li> +</ol> +<p> + Untuk mendaftarkan aktivitas agar dipanggil saat pengguna mengklik item aliran atau foto atau keduanya: +</p> +<ol> + <li> + Buat file yang bernama <code>contacts.xml</code> dalam direktori <code>res/xml/</code> + proyek Anda. Jika sudah memiliki file ini, langkah ini boleh dilewati. + </li> + <li> + Dalam file ini, tambahkan elemen +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + Jika elemen ini sudah ada, langkah ini boleh dilewati. + </li> + <li> + Untuk mendaftarkan salah satu aktivitas Anda guna menangani klik oleh pengguna pada item aliran dalam + aplikasi kontak perangkat, tambahkan atribut + <code>viewStreamItemActivity="<em>activityclass</em>"</code> ke elemen, dengan + <code><em>activityclass</em></code> sebagai nama kelas mutlak (fully-qualified) dari aktivitas + yang harus menerima intent dari aplikasi kontak perangkat. + </li> + <li> + Untuk mendaftarkan salah satu aktivitas Anda guna menangani klik oleh pengguna pada foto aliran dalam + aplikasi kontak perangkat, tambahkan atribut + <code>viewStreamItemPhotoActivity="<em>activityclass</em>"</code> ke elemen, dengan + <code><em>activityclass</em></code> adalah kelas nama mutlak aktivitas + yang harus menerima intent dari aplikasi kontak perangkat. + </li> +</ol> +<p> + Elemen <code><ContactsAccountType></code> dijelaskan lebih detail di + bagian <a href="#SocialStreamAcctType">Elemen <ContactsAccountType></a>. +</p> +<p> + Intent yang masuk berisi URI konten dari materi atau foto yang diklik pengguna. + Untuk mendapatkan aktivitas terpisah bagi item teks dan foto, gunakan kedua atribut dalam file yang sama. +</p> +<h4>Berinteraksi dengan layanan jaringan sosial Anda</h4> +<p> + Pengguna tidak harus meninggalkan aplikasi perangkat kontak untuk mengundang kontak ke situs + jaringan sosial Anda. Sebagai gantinya, Anda bisa meminta aplikasi kontak perangkat mengirimkan intent untuk mengundang + kontak ke salah satu aktivitas Anda. Untuk mempersiapkannya: +</p> +<ol> + <li> + Buat file yang bernama <code>contacts.xml</code> dalam direktori <code>res/xml/</code> + proyek Anda. Jika sudah memiliki file ini, langkah ini boleh dilewati. + </li> + <li> + Dalam file ini, tambahkan elemen +<code><ContactsAccountType xmlns:android="http://schemas.android.com/apk/res/android"></code>. + Jika elemen ini sudah ada, langkah ini boleh dilewati. + </li> + <li> + Tambahkan atribut-atribut berikut: + <ul> + <li><code>inviteContactActivity="<em>activityclass</em>"</code></li> + <li> + <code>inviteContactActionLabel="@string/<em>invite_action_label</em>"</code> + </li> + </ul> + Nilai <code><em>activityclass</em></code> adalah nama kelas mutlak + aktivitas yang harus menerima intent ini. Nilai <code><em>invite_action_label</em></code> + adalah string teks yang ditampilkan dalam menu <strong>Add Connection</strong> dalam + aplikasi kontak perangkat. + </li> +</ol> +<p class="note"> + <strong>Catatan:</strong> <code>ContactsSource</code> adalah nama tag yang sudah usang untuk + <code>ContactsAccountType</code>. +</p> +<h3 id="ContactsFile">Acuan contacts.xml</h3> +<p> + File <code>contacts.xml</code> berisi elemen XML yang mengontrol interaksi adaptor sinkronisasi + Anda dan aplikasi dengan aplikasi kontak dan Penyedia Kontak. Elemen-elemen ini + dijelaskan di bagian-bagian selanjutnya. +</p> +<h4 id="SocialStreamAcctType">Elemen <ContactsAccountType></h4> +<p> + Elemen <code><ContactsAccountType></code> mengontrol interaksi aplikasi + Anda dengan aplikasi kontak. Sintaksnya adalah sebagai berikut: +</p> +<pre> +<ContactsAccountType + xmlns:android="http://schemas.android.com/apk/res/android" + inviteContactActivity="<em>activity_name</em>" + inviteContactActionLabel="<em>invite_command_text</em>" + viewContactNotifyService="<em>view_notify_service</em>" + viewGroupActivity="<em>group_view_activity</em>" + viewGroupActionLabel="<em>group_action_text</em>" + viewStreamItemActivity="<em>viewstream_activity_name</em>" + viewStreamItemPhotoActivity="<em>viewphotostream_activity_name</em>"> +</pre> +<p> + <strong>dimuat dalam:</strong> +</p> +<p> + <code>res/xml/contacts.xml</code> +</p> +<p> + <strong>bisa berisi:</strong> +</p> +<p> + <strong><code><ContactsDataKind></code></strong> +</p> +<p> + <strong>Keterangan:</strong> +</p> +<p> + Mendeklarasikan komponen Android dan label UI yang memungkinkan pengguna mengundang salah satu kontak ke + jaringan sosial, memberi tahu pengguna bila salah satu aliran jaringan sosial diperbarui, dan + seterusnya. +</p> +<p> + Perhatikan bahwa awalan atribut <code>android:</code> tidak perlu untuk atribut-atribut + <code><ContactsAccountType></code>. +</p> +<p> + <strong>Atribut:</strong> +</p> +<dl> + <dt>{@code inviteContactActivity}</dt> + <dd> + Nama kelas mutlak aktivitas dalam aplikasi yang Anda ingin + aktifkan bila pengguna memilih <strong>Add connection</strong> dari aplikasi kontak + perangkat. + </dd> + <dt>{@code inviteContactActionLabel}</dt> + <dd> + String teks yang ditampilkan untuk aktivitas yang ditetapkan dalam + {@code inviteContactActivity}, dalam menu <strong>Add connection</strong>. + Misalnya, Anda bisa menggunakan string "Ikuti di jaringan saya". Anda bisa menggunakan identifier sumber daya + string untuk tabel ini. + </dd> + <dt>{@code viewContactNotifyService}</dt> + <dd> + Nama kelas mutlak layanan dalam aplikasi Anda yang harus menerima + pemberitahuan saat pengguna menampilkan kontak. Pemberitahuan ini dikirimkan oleh aplikasi kontak + perangkat; hal ini memungkinkan aplikasi Anda menunda operasi yang banyak memproses data + hingga dibutuhkan. Misalnya, aplikasi Anda bisa merespons pemberitahuan ini + dengan membaca dalam dan menampilkan foto resolusi tinggi kontak dan item aliran sosial + terbaru. Fitur ini dijelaskan lebih detail di bagian + <a href="#SocialStreamInteraction">Interaksi aliran sosial</a>. Anda bisa melihat + contoh layanan pemberitahuan dalam file <code>NotifierService.java</code> dalam contoh aplikasi + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">Sample Sync Adapter</a>. + + </dd> + <dt>{@code viewGroupActivity}</dt> + <dd> + Nama kelas mutlak aktivitas dalam aplikasi yang bisa menampilkan + informasi grup. Bila pengguna mengklik label grup dalam aplikasi + kontak perangkat, UI aktivitas ini akan ditampilkan. + </dd> + <dt>{@code viewGroupActionLabel}</dt> + <dd> + Label yang ditampilkan aplikasi kontak untuk kontrol UI yang memungkinkan + pengguna melihat grup dalam aplikasi Anda. + <p> + Misalnya, jika Anda menginstal aplikasi Google+ di perangkat dan menyinkronkan + Google+ dengan aplikasi kontak, Anda akan melihat lingkaran Google+ tercantum sebagai grup + dalam tab <strong>Groups</strong> aplikasi kontak Anda. Jika Anda mengklik + lingkaran Google+, Anda akan melihat orang-orang di lingkaran itu tercantum sebagai satu "grup". Di atas + tampilan, Anda akan melihat ikon Google+; jika mengklik ikon itu, kontrol akan beralih ke + aplikasi Google+. Aplikasi kontak melakukan ini dengan + {@code viewGroupActivity}, yang menggunakan ikon Google+ sebagai nilai + {@code viewGroupActionLabel}. + </p> + <p> + Identifier sumber daya string diperbolehkan untuk atribut ini. + </p> + </dd> + <dt>{@code viewStreamItemActivity}</dt> + <dd> + Nama kelas mutlak aktivitas dalam aplikasi Anda + yang diluncurkan aplikasi kontak perangkat bila pengguna mengklik item aliran untuk kontak mentah. + </dd> + <dt>{@code viewStreamItemPhotoActivity}</dt> + <dd> + Nama kelas mutlak aktivitas yang diluncurkan + aplikasi kontak perangkat bila pengguna mengklik foto dalam item aliran + untuk kontak mentah. + </dd> +</dl> +<h4 id="SocialStreamDataKind">Elemen <ContactsDataKind></h4> +<p> + Elemen <code><ContactsDataKind></code> mengontrol tampilan baris data custom + aplikasi Anda dalam UI aplikasi kontak. Sintaksnya adalah sebagai berikut: +</p> +<pre> +<ContactsDataKind + android:mimeType="<em>MIMEtype</em>" + android:icon="<em>icon_resources</em>" + android:summaryColumn="<em>column_name</em>" + android:detailColumn="<em>column_name</em>"> +</pre> +<p> + <strong>dimuat dalam:</strong> +</p> +<code><ContactsAccountType></code> +<p> + <strong>Keterangan:</strong> +</p> +<p> + Gunakan elemen ini untuk memerintahkan aplikasi kontak agar menampilkan konten baris data custom sebagai + bagian dari detail kontak mentah. Setiap elemen anak <code><ContactsDataKind></code> + <code><ContactsAccountType></code> mewakili tipe baris data custom yang + ditambahkan adaptor sinkronisasi Anda ke tabel {@link android.provider.ContactsContract.Data}. Tambahkan satu + elemen <code><ContactsDataKind></code> untuk setiap tipe MIME custom yang Anda gunakan. Anda tidak harus + menambahkan elemen jika Anda memiliki baris data custom yang datanya tidak ingin ditampilkan. +</p> +<p> + <strong>Atribut:</strong> +</p> +<dl> + <dt>{@code android:mimeType}</dt> + <dd> + Tipe MIME custom yang telah Anda definisikan untuk salah satu tipe baris data custom dalam + tabel {@link android.provider.ContactsContract.Data}. Misalnya, nilai + <code>vnd.android.cursor.item/vnd.example.locationstatus</code> bisa berupa tipe MIME + custom untuk baris data yang mencatat lokasi kontak yang terakhir diketahui. + </dd> + <dt>{@code android:icon}</dt> + <dd> + + <a href="{@docRoot}guide/topics/resources/drawable-resource.html">Sumber daya drawable</a> + Android yang ditampilkan aplikasi kontak di samping data Anda. Gunakan ini untuk menunjukkan kepada + pengguna bahwa data berasal dari layanan Anda. + </dd> + <dt>{@code android:summaryColumn}</dt> + <dd> + Nama kolom untuk yang pertama dari dua nilai yang diambil dari baris data. Nilai + ditampilkan sebagai baris pertama entri untuk baris data ini. Baris pertama + dimaksudkan untuk digunakan sebagai rangkuman data, tetapi itu bersifat opsional. Lihat juga + <a href="#detailColumn">android:detailColumn</a>. + </dd> + <dt>{@code android:detailColumn}</dt> + <dd> + Nama kolom untuk yang kedua dari dua nilai yang diambil dari baris data. Nilai + ditampilkan sebagai baris kedua entri untuk baris data ini. Lihat juga + {@code android:summaryColumn}. + </dd> +</dl> +<h2 id="AdditionalFeatures">Fitur Tambahan Penyedia Kontak</h2> +<p> + Di samping fitur-fitur utama yang dijelaskan di bagian sebelumnya, Penyedia Kontak menawarkan + fitur-fitur berguna ini untuk digunakan bersama data kontak: +</p> + <ul> + <li>Grup kontak</li> + <li>Fitur foto</li> + </ul> +<h3 id="Groups">Grup kontak</h3> +<p> + Penyedia Kontak secara opsional bisa melabeli kumpulan kontak terkait dengan data + <strong>grup</strong>. Jika server yang dikaitkan dengan akun pengguna + ingin mempertahankan grup, adaptor sinkronisasi untuk tipe akun dari akun itu harus mentransfer + data grup antara Penyedia Kontak dan server. Bila pengguna menambahkan kontak baru ke + server, kemudian memasukkan kontak ini dalam grup baru, adaptor sinkronisasi harus menambahkan grup baru + ke tabel {@link android.provider.ContactsContract.Groups}. Grup atau grup-grup yang memiliki kontak + disimpan dalam tabel {@link android.provider.ContactsContract.Data}, dengan menggunakan + tipe MIME {@link android.provider.ContactsContract.CommonDataKinds.GroupMembership}. +</p> +<p> + Jika Anda mendesain adaptor sinkronisasi yang akan menambahkan data kontak mentah dari + server ke Penyedia Kontak, dan Anda tidak menggunakan grup, maka Anda harus memberi tahu + penyedia itu agar membuat data Anda terlihat. Dalam kode yang dijalankan bila pengguna menambahkan akun + ke perangkat, perbarui baris {@link android.provider.ContactsContract.Settings} + yang ditambahkan Penyedia Kontak untuk akunnya. Dalam baris ini, atur nilai kolom + {@link android.provider.ContactsContract.SettingsColumns#UNGROUPED_VISIBLE + Settings.UNGROUPED_VISIBLE} ke 1. Bila melakukannya, Penyedia Kontak akan selalu + membuat data kontak Anda terlihat, meskipun Anda tidak menggunakan grup. +</p> +<h3 id="Photos">Foto kontak</h3> +<p> + Tabel {@link android.provider.ContactsContract.Data} menyimpan foto sebagai baris dengan tipe MIME + {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE + Photo.CONTENT_ITEM_TYPE}. Kolom + {@link android.provider.ContactsContract.RawContactsColumns#CONTACT_ID} baris yang ditautkan ke + kolom {@link android.provider.BaseColumns#_ID} kontak mentah yang memiliki kolom itu. + Kelas {@link android.provider.ContactsContract.Contacts.Photo} mendefinisikan subtabel + {@link android.provider.ContactsContract.Contacts} yang berisi informasi foto untuk foto + utama kontak, yang merupakan foto utama dari kontak mentah utama kontak itu. Demikian pula, + kelas {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} mendefinisikan subtabel + {@link android.provider.ContactsContract.RawContacts} yang berisi informasi foto untuk + foto utama kontak mentah. +</p> +<p> + Dokumentasi acuan untuk {@link android.provider.ContactsContract.Contacts.Photo} dan + {@link android.provider.ContactsContract.RawContacts.DisplayPhoto} berisi contoh-contoh + pengambilan informasi foto. Tidak ada kelas praktis untuk mengambil + thumbnail utama kontak mentah, tetapi Anda bisa mengirim query ke + tabel {@link android.provider.ContactsContract.Data}, dengan memilih + {@link android.provider.BaseColumns#_ID} kontak mentah, + {@link android.provider.ContactsContract.CommonDataKinds.Photo#CONTENT_ITEM_TYPE + Photo.CONTENT_ITEM_TYPE}, dan kolom {@link android.provider.ContactsContract.Data#IS_PRIMARY} + untuk menemukan baris foto utama kontak mentah. +</p> +<p> + Data aliran sosial untuk seseorang bisa juga disertai foto. Data ini disimpan dalam + tabel {@link android.provider.ContactsContract.StreamItemPhotos}, yang dijelaskan lebih detail + di bagian <a href="#StreamPhotos">Foto aliran sosial</a>. +</p> diff --git a/docs/html-intl/intl/in/guide/topics/providers/content-provider-basics.jd b/docs/html-intl/intl/in/guide/topics/providers/content-provider-basics.jd new file mode 100644 index 000000000000..c4003caba88f --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/content-provider-basics.jd @@ -0,0 +1,1196 @@ +page.title=Dasar-Dasar Penyedia Konten +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<!-- In this document --> +<h2>Dalam dokumen ini</h2> +<ol> + <li> + <a href="#Basics">Ikhtisar</a> + <ol> + <li> + <a href="#ClientProvider">Mengakses penyedia</a> + </li> + <li> + <a href="#ContentURIs">URI Konten</a> + </li> + </ol> + </li> + <li> + <a href="#SimpleQuery">Mengambil Data dari Penyedia</a> + <ol> + <li> + <a href="#RequestPermissions">Meminta izin akses baca</a> + </li> + <li> + <a href="#Query">Membuat query</a> + </li> + <li> + <a href="#DisplayResults">Menampilkan hasil query</a> + </li> + <li> + <a href="#GettingResults">Mendapatkan data dari hasil query</a> + </li> + </ol> + </li> + <li> + <a href="#Permissions">Izin Penyedia Konten</a> + </li> + <li> + <a href="#Modifications">Menyisipkan, Memperbarui, dan Menghapus Data</a> + <ol> + <li> + <a href="#Inserting">Menyisipkan data</a> + </li> + <li> + <a href="#Updating">Memperbarui data</a> + </li> + <li> + <a href="#Deleting">Menghapus data</a> + </li> + </ol> + </li> + <li> + <a href="#DataTypes">Tipe Data Penyedia</a> + </li> + <li> + <a href="#AltForms">Bentuk-Bentuk Alternatif Akses Penyedia</a> + <ol> + <li> + <a href="#Batch">Akses batch</a> + </li> + <li> + <a href="#Intents">Akses data melalui intent</a> + </li> + </ol> + </li> + <li> + <a href="#ContractClasses">Kelas-kelas Kontrak</a> + </li> + <li> + <a href="#MIMETypeReference">Acuan Tipe MIME</a> + </li> +</ol> + + <!-- Key Classes --> +<h2>Kelas-kelas utama</h2> + <ol> + <li> + {@link android.content.ContentProvider} + </li> + <li> + {@link android.content.ContentResolver} + </li> + <li> + {@link android.database.Cursor} + </li> + <li> + {@link android.net.Uri} + </li> + </ol> + + <!-- Related Samples --> +<h2>Contoh-Contoh Terkait</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html"> + Kursor (Orang)</a> + </li> + <li> + <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html"> + Kursor (Telepon)</a> + </li> + </ol> + + <!-- See also --> +<h2>Lihat juga</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Membuat Penyedia Konten</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Penyedia Kalender</a> + </li> + </ol> +</div> +</div> + + <!-- Intro paragraphs --> +<p> + Penyedia konten mengelola akses ke repository data pusat. Penyedia + adalah bagian dari aplikasi Android, yang sering menyediakan UI-nya sendiri untuk menggunakan + data. Akan tetapi, penyedia konten terutama dimaksudkan untuk digunakan oleh + aplikasi lain, yang mengakses penyedia itu melalui objek klien penyedia. Bersama-sama, penyedia + dan klien penyedia menawarkan antarmuka standar yang konsisten ke data yang juga menangani + komunikasi antar-proses dan akses data aman. +</p> +<p> + Topik ini menerangkan dasar-dasar dari hal-hal berikut: +</p> + <ul> + <li>Cara kerja penyedia konten.</li> + <li>API yang Anda gunakan untuk mengambil data dari penyedia konten.</li> + <li>API yang Anda gunakan untuk menyisipkan, memperbarui, atau menghapus data dalam penyedia konten.</li> + <li>Fitur API lainnya yang memudahkan kita menggunakan penyedia.</li> + </ul> + + <!-- Basics --> +<h2 id="Basics">Ikhtisar</h2> +<p> + Penyedia konten menyajikan data ke aplikasi eksternal sebagai satu atau beberapa tabel yang + serupa dengan tabel-tabel yang ditemukan dalam database relasional. Sebuah baris mewakili instance beberapa tipe + data yang dikumpulkan penyedia, dan tiap kolom dalam baris mewakili sepotong + data yang dikumpulkan untuk sebuah instance. +</p> +<p> + Misalnya, salah satu penyedia bawaan di platform Android adalah kamus pengguna, yang + menyimpan ejaan kata-kata tidak-standar yang ingin disimpan pengguna. Tabel 1 mengilustrasikan + wujud data yang mungkin ada dalam tabel penyedia ini: +</p> +<p class="table-caption"> + <strong>Tabel 1:</strong> Contoh tabel kamus pengguna. +</p> +<table id="table1" style="width: 50%;"> + <tr> + <th style="width:20%" align="center" scope="col">word</th> + <th style="width:20%" align="center" scope="col">app id</th> + <th style="width:20%" align="center" scope="col">frequency</th> + <th style="width:20%" align="center" scope="col">locale</th> + <th style="width:20%" align="center" scope="col">_ID</th> + </tr> + <tr> + <td align="center" scope="row">mapreduce</td> + <td align="center">user1</td> + <td align="center">100</td> + <td align="center">en_US</td> + <td align="center">1</td> + </tr> + <tr> + <td align="center" scope="row">precompiler</td> + <td align="center">user14</td> + <td align="center">200</td> + <td align="center">fr_FR</td> + <td align="center">2</td> + </tr> + <tr> + <td align="center" scope="row">applet</td> + <td align="center">user2</td> + <td align="center">225</td> + <td align="center">fr_CA</td> + <td align="center">3</td> + </tr> + <tr> + <td align="center" scope="row">const</td> + <td align="center">user1</td> + <td align="center">255</td> + <td align="center">pt_BR</td> + <td align="center">4</td> + </tr> + <tr> + <td align="center" scope="row">int</td> + <td align="center">user5</td> + <td align="center">100</td> + <td align="center">en_UK</td> + <td align="center">5</td> + </tr> +</table> +<p> + Dalam tabel 1, tiap baris mewakili instance sebuah kata yang mungkin tidak + ditemukan dalam kamus standar. Tiap kolom mewakili beberapa data untuk kata itu, misalnya + bahasa lokal tempat kata itu ditemukan kali pertama. Header kolom adalah nama kolom yang disimpan dalam + penyedia. Untuk mengacu ke bahasa lokal suatu baris, Anda mengacu ke kolom <code>locale</code>-nya. Untuk + penyedia ini, kolom <code>_ID</code> berfungsi sebagai "kunci utama" kolom yang + dipelihara oleh penyedia secara otomatis. +</p> +<p class="note"> + <strong>Catatan:</strong> Penyedia tidak diharuskan memiliki kunci utama, dan tidak diharuskan + menggunakan <code>_ID</code> sebagai nama kolom kunci utama jika kunci itu ada. Akan tetapi, + jika Anda ingin mengikat data dari penyedia ke {@link android.widget.ListView}, salah satu + nama kolom harus <code>_ID</code>. Ketentuan ini dijelaskan secara lebih detail di bagian + <a href="#DisplayResults">Menampilkan hasil query</a>. +</p> +<h3 id="ClientProvider">Mengakses penyedia</h3> +<p> + Aplikasi mengakses data dari penyedia konten dengan + sebuah objek klien {@link android.content.ContentResolver}. Objek ini memiliki metode yang memanggil + metode dengan nama identik dalam objek penyedia, instance salah satu + subkelas konkret dari {@link android.content.ContentProvider}. Metode-metode + {@link android.content.ContentResolver} menyediakan fungsi-fungsi dasar + "CRUD" (create, retrieve, update, dan delete) pada penyimpanan yang persisten. +</p> +<p> + Objek {@link android.content.ContentResolver} dalam + proses aplikasi klien dan objek {@link android.content.ContentProvider} dalam aplikasi yang memiliki + penyedia itu secara otomatis akan menangani komunikasi antar-proses. + {@link android.content.ContentProvider} juga berfungsi sebagai lapisan abstraksi antara + repository datanya dan penampilan eksternal data sebagai tabel. +</p> +<p class="note"> + <strong>Catatan:</strong> Untuk mengakses penyedia, aplikasi Anda biasanya harus meminta + izin tertentu dalam file manifesnya. Hal ini dijelaskan lebih detail di bagian + <a href="#Permissions">Izin Penyedia Konten</a> +</p> +<p> + Misalnya, untuk mendapatkan daftar kata dan lokalnya dari Penyedia Kamus Pengguna, + Anda memanggil {@link android.content.ContentResolver#query ContentResolver.query()}. + Metode {@link android.content.ContentResolver#query query()} memanggil + metode {@link android.content.ContentProvider#query ContentProvider.query()} yang didefinisikan oleh + Penyedia Kamus Pengguna. Baris-baris kode berikut menunjukkan sebuah + panggilan {@link android.content.ContentResolver#query ContentResolver.query()}: +<p> +<pre> +// Queries the user dictionary and returns results +mCursor = getContentResolver().query( + UserDictionary.Words.CONTENT_URI, // The content URI of the words table + mProjection, // The columns to return for each row + mSelectionClause // Selection criteria + mSelectionArgs, // Selection criteria + mSortOrder); // The sort order for the returned rows +</pre> +<p> + Tabel 2 menampilkan cara argumen untuk + {@link android.content.ContentResolver#query + query(Uri,projection,selection,selectionArgs,sortOrder)} cocok dengan sebuah pernyataan SELECT di SQL: +</p> +<p class="table-caption"> + <strong>Tabel 2:</strong> Query() dibandingkan dengan query SQL. +</p> +<table id="table2" style="width: 75%;"> + <tr> + <th style="width:25%" align="center" scope="col">Argumen query()</th> + <th style="width:25%" align="center" scope="col">Kata kunci/parameter SELECT</th> + <th style="width:50%" align="center" scope="col">Catatan</th> + </tr> + <tr> + <td align="center"><code>Uri</code></td> + <td align="center"><code>FROM <em>table_name</em></code></td> + <td><code>Uri</code> memetakan ke tabel dalam penyedia yang bernama <em>table_name</em>.</td> + </tr> + <tr> + <td align="center"><code>projection</code></td> + <td align="center"><code><em>col,col,col,...</em></code></td> + <td> + <code>projection</code> adalah satu larik kolom yang harus disertakan untuk tiap baris + yang diambil. + </td> + </tr> + <tr> + <td align="center"><code>selection</code></td> + <td align="center"><code>WHERE <em>col</em> = <em>value</em></code></td> + <td><code>selection</code> menetapkan kriteria untuk memilih baris.</td> + </tr> + <tr> + <td align="center"><code>selectionArgs</code></td> + <td align="center"> + (Tidak ada padanan persis. Argumen pemilihan mengganti <code>?</code> placeholder dalam + klausa pemilihan.) + </td> + </tr> + <tr> + <td align="center"><code>sortOrder</code></td> + <td align="center"><code>ORDER BY <em>col,col,...</em></code></td> + <td> + <code>sortOrder</code> menetapkan urutan munculnya baris dalam + {@link android.database.Cursor} yang dihasilkan. + </td> + </tr> +</table> +<h3 id="ContentURIs">URI Konten</h3> +<p> + <strong>URI konten</strong> adalah URI yang mengidentifikasi data dalam penyedia. URI Konten + menyertakan nama simbolis seluruh penyedia (<strong>otoritas</strong>nya) dan sebuah + nama yang menunjuk ke tabel (<strong>path</strong>). Bila Anda memanggil + metode klien untuk mengakses tabel dalam penyedia, URI konten untuk tabel itu adalah salah satu + argumennya. +</p> +<p> + Dalam baris kode sebelumnya, konstanta + {@link android.provider.UserDictionary.Words#CONTENT_URI} mengandung URI konten dari + tabel "words" kamus pengguna. Objek {@link android.content.ContentResolver} + akan mengurai otoritas URI, dan menggunakannya untuk "mengetahui" penyedia dengan + membandingkan otoritas tersebut dengan sebuah tabel sistem berisi penyedia yang dikenal. +{@link android.content.ContentResolver} kemudian bisa mengirim argumen query ke penyedia + yang benar. +</p> +<p> + {@link android.content.ContentProvider} menggunakan bagian path dari URI konten untuk memilih + tabel yang akan diakses. Penyedia biasanya memiliki <strong>path</strong> untuk tiap tabel yang dieksposnya. +</p> +<p> + Dalam baris kode sebelumnya, URI lengkap untuk tabel "words" adalah: +</p> +<pre> +content://user_dictionary/words +</pre> +<p> + dalam hal ini string <code>user_dictionary</code> adalah otoritas penyedia, dan string + <code>words</code> adalah path tabel. String + <code>content://</code> (<strong>skema</strong>) selalu ada, + dan mengidentifikasinya sebagai URI konten. +</p> +<p> + Banyak penyedia yang memperbolehkan Anda mengakses satu baris dalam tabel dengan menambahkan sebuah ID nilai + ke akhir URI. Misalnya, untuk mengambil sebuah baris yang <code>_ID</code>-nya adalah + <code>4</code> dari kamus pengguna, Anda bisa menggunakan URI konten ini: +</p> +<pre> +Uri singleUri = ContentUris.withAppendedId(UserDictionary.Words.CONTENT_URI,4); +</pre> +<p> + Anda akan sering menggunakan nilai-nilai ID bila telah mengambil satu set baris kemudian ingin memperbarui atau menghapus + salah satunya. +</p> +<p class="note"> + <strong>Catatan:</strong> Kelas-kelas {@link android.net.Uri} dan {@link android.net.Uri.Builder} + berisi metode praktis untuk membangun objek dari string URI yang tersusun dengan baik. +{@link android.content.ContentUris} berisi metode praktis untuk menambahkan nilai ID ke + URI. Cuplikan kode sebelumnya menggunakan {@link android.content.ContentUris#withAppendedId + withAppendedId()} untuk menambahkan id ke URI konten User Dictionary. +</p> + + + <!-- Retrieving Data from the Provider --> +<h2 id="SimpleQuery">Mengambil Data dari Penyedia</h2> +<p> + Bagian ini menerangkan cara mengambil data dari penyedia, dengan menggunakan Penyedia Kamus Pengguna + sebagai contoh. +</p> +<p class="note"> + Demi kejelasan, cuplikan kode di bagian ini memanggil + {@link android.content.ContentResolver#query ContentResolver.query()} pada "UI thread"". Akan tetapi, dalam + kode sesungguhnya, Anda harus melakukan query secara asinkron pada sebuah thread terpisah. Satu cara melakukannya + adalah menggunakan kelas {@link android.content.CursorLoader}, yang dijelaskan + lebih detail dalam panduan <a href="{@docRoot}guide/components/loaders.html"> + Loader</a>. Juga, baris-baris kode tersebut hanyalah cuplikan; tidak menunjukkan sebuah aplikasi + lengkap. +</p> +<p> + Untuk mengambil data dari penyedia, ikutilah langkah-langkah dasar ini: +</p> +<ol> + <li> + Minta izin akses baca untuk penyedia itu. + </li> + <li> + Definisikan kode yang mengirim query ke penyedia. + </li> +</ol> +<h3 id="RequestPermissions">Meminta izin akses baca</h3> +<p> + Untuk mengambil data dari penyedia, aplikasi Anda memerlukan "izin akses baca" untuk + penyedia itu. Anda tidak bisa meminta izin ini saat runtime; sebagai gantinya, Anda harus menetapkan bahwa + Anda memerlukan izin ini dalam manifes, dengan menggunakan elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> + dan nama persis izin yang didefinisikan oleh + penyedia itu. Bila menetapkan elemen ini dalam manifes, Anda secara efektif "meminta" + izin ini untuk aplikasi Anda. Bila pengguna menginstal aplikasi Anda, mereka secara implisit akan memberikan + permintaan ini. +</p> +<p> + Untuk menemukan nama persis dari izin akses baca untuk penyedia yang sedang Anda gunakan, serta + nama-nama izin akses lain yang digunakan oleh penyedia, lihatlah dalam + dokumentasi penyedia. +</p> +<p> + Peran izin dalam yang mengakses penyedia dijelaskan lebih detail di bagian + <a href="#Permissions">Izin Penyedia Konten</a>. +</p> +<p> + Penyedia Kamus Pengguna mendefinisikan izin + <code>android.permission.READ_USER_DICTIONARY</code> dalam file manifesnya, sehingga + aplikasi yang ingin membaca dari penyedia itu harus meminta izin ini. +</p> +<!-- Constructing the query --> +<h3 id="Query">Membuat query</h3> +<p> + Langkah berikutnya dalam mengambil data penyedia adalah membuat query. Cuplikan kode pertama ini + mendefinisikan beberapa variabel untuk mengakses Penyedia Kamus Pengguna: +</p> +<pre class="prettyprint"> + +// A "projection" defines the columns that will be returned for each row +String[] mProjection = +{ + UserDictionary.Words._ID, // Contract class constant for the _ID column name + UserDictionary.Words.WORD, // Contract class constant for the word column name + UserDictionary.Words.LOCALE // Contract class constant for the locale column name +}; + +// Defines a string to contain the selection clause +String mSelectionClause = null; + +// Initializes an array to contain selection arguments +String[] mSelectionArgs = {""}; + +</pre> +<p> + Cuplikan berikutnya menampilkan cara menggunakan + {@link android.content.ContentResolver#query ContentResolver.query()}, dengan menggunakan Penyedia Kamus Pengguna + sebagai contoh. Query klien penyedia serupa dengan query SQL, dan berisi satu + set kolom yang akan dihasilkan, satu set kriteria pemilihan, dan urutan sortir. +</p> +<p> + Set kolom yang harus dikembalikan query disebut dengan <strong>proyeksi</strong> + (variabel <code>mProjection</code>). +</p> +<p> + Ekspresi yang menetapkan baris yang harus diambil dipecah menjadi klausa pemilihan dan + argumen pemilihan. Klausa pemilihan adalah kombinasi ekspresi logis dan boolean, + nama kolom, dan nilai (variabel <code>mSelectionClause</code>). Jika Anda menetapkan + parameter <code>?</code> yang bisa diganti, sebagai ganti nilai, metode query akan mengambil nilai + dari larik argumen pemilihan (variabel <code>mSelectionArgs</code>). +</p> +<p> + Dalam cuplikan berikutnya, jika pengguna tidak memasukkan sebuah kata, klausa pemilihan akan diatur ke + <code>null</code>, dan query menghasilkan semua kata dalam penyedia. Jika pengguna memasukkan + sebuah kata, klausa pemilihan akan diatur ke <code>UserDictionary.Words.WORD + " = ?"</code> dan + elemen pertama larik argumen pemilihan diatur ke kata yang dimasukkan pengguna. +</p> +<pre class="prettyprint"> +/* + * This defines a one-element String array to contain the selection argument. + */ +String[] mSelectionArgs = {""}; + +// Gets a word from the UI +mSearchString = mSearchWord.getText().toString(); + +// Remember to insert code here to check for invalid or malicious input. + +// If the word is the empty string, gets everything +if (TextUtils.isEmpty(mSearchString)) { + // Setting the selection clause to null will return all words + mSelectionClause = null; + mSelectionArgs[0] = ""; + +} else { + // Constructs a selection clause that matches the word that the user entered. + mSelectionClause = UserDictionary.Words.WORD + " = ?"; + + // Moves the user's input string to the selection arguments. + mSelectionArgs[0] = mSearchString; + +} + +// Does a query against the table and returns a Cursor object +mCursor = getContentResolver().query( + UserDictionary.Words.CONTENT_URI, // The content URI of the words table + mProjection, // The columns to return for each row + mSelectionClause // Either null, or the word the user entered + mSelectionArgs, // Either empty, or the string the user entered + mSortOrder); // The sort order for the returned rows + +// Some providers return null if an error occurs, others throw an exception +if (null == mCursor) { + /* + * Insert code here to handle the error. Be sure not to use the cursor! You may want to + * call android.util.Log.e() to log this error. + * + */ +// If the Cursor is empty, the provider found no matches +} else if (mCursor.getCount() < 1) { + + /* + * Insert code here to notify the user that the search was unsuccessful. This isn't necessarily + * an error. You may want to offer the user the option to insert a new row, or re-type the + * search term. + */ + +} else { + // Insert code here to do something with the results + +} +</pre> +<p> + Query ini analog dengan pernyataan SQL: +</p> +<pre> +SELECT _ID, word, locale FROM words WHERE word = <userinput> ORDER BY word ASC; +</pre> +<p> + Dalam pernyataan SQL ini, nama kolom yang sesungguhnya digunakan sebagai ganti konstanta kelas kontrak. +</p> +<h4 id="Injection">Melindungi dari input merusak</h4> +<p> + Jika data dikelola oleh penyedia konten berada dalam database SQL, memasukkan data tak dipercaya eksternal + ke dalam pernyataan SQL mentah bisa menyebabkan injeksi SQL. +</p> +<p> + Perhatikan klausa pemilihan ini: +</p> +<pre> +// Constructs a selection clause by concatenating the user's input to the column name +String mSelectionClause = "var = " + mUserInput; +</pre> +<p> + Jika melakukannya, Anda akan membuat pengguna menyambungkan SQL merusak ke pernyataan SQL Anda. + Misalnya, pengguna bisa memasukkan "nothing; DROP TABLE *;" untuk <code>mUserInput</code>, yang + akan menghasilkan klausa pemilihan <code>var = nothing; DROP TABLE *;</code>. Karena + klausa pemilihan diperlakukan sebagai pernyataan SQL, hal ini bisa menyebabkan penyedia itu menghapus semua + tabel dalam database SQLite yang mendasarinya (kecuali penyedia disiapkan untuk menangkap upaya + <a href="http://en.wikipedia.org/wiki/SQL_injection">injeksi SQL</a>). +</p> +<p> + Untuk menghindari masalah ini, gunakan klausa pemilihan yang menggunakan <code>?</code> sebagai + parameter yang bisa diganti dan larik argumen pemilihan yang terpisah. Bila Anda melakukannya, input pengguna + akan dibatasi secara langsung pada query agar tidak ditafsirkan sebagai bagian dari pernyataan SQL. + Karena tidak diperlakukan sebagai SQL, input pengguna tidak bisa menyuntikkan SQL merusak. Sebagai ganti menggunakan + penyambungan untuk menyertakan input pengguna, gunakan klausa pemilihan ini: +</p> +<pre> +// Constructs a selection clause with a replaceable parameter +String mSelectionClause = "var = ?"; +</pre> +<p> + Buat larik argumen pemilihan seperti ini: +</p> +<pre> +// Defines an array to contain the selection arguments +String[] selectionArgs = {""}; +</pre> +<p> + Masukkan nilai dalam larik argumen pemilihan seperti ini: +</p> +<pre> +// Sets the selection argument to the user's input +selectionArgs[0] = mUserInput; +</pre> +<p> + Sebuah klausa pemilihan yang menggunakan <code>?</code> sebagai parameter yang bisa diganti dan sebuah larik + argumen pemilihan adalah cara yang lebih disukai untuk menyebutkan pemilihan, sekalipun penyedia tidak + dibuat berdasarkan database SQL. +</p> +<!-- Displaying the results --> +<h3 id="DisplayResults">Menampilkan hasil query</h3> +<p> + Metode klien {@link android.content.ContentResolver#query ContentResolver.query()} selalu + menghasilkan {@link android.database.Cursor} berisi kolom-kolom yang ditetapkan oleh + proyeksi query untuk baris yang cocok dengan kriteria pemilihan query. Objek + {@link android.database.Cursor} menyediakan akses baca acak ke baris dan kolom yang + dimuatnya. Dengan metode {@link android.database.Cursor}, Anda bisa mengulang baris-baris dalam + hasil, menentukan tipe data tiap kolom, mengambil data dari kolom, dan memeriksa + properti lain dari hasil. Beberapa implementasi {@link android.database.Cursor} + akan memperbarui objek secara otomatis bila data penyedia berubah, atau memicu metode dalam objek pengamat + bila {@link android.database.Cursor} berubah, atau keduanya. +</p> +<p class="note"> + <strong>Catatan:</strong> Penyedia bisa membatasi akses ke kolom berdasarkan sifat + objek yang membuat query. Misalnya, Penyedia Kontak membatasi akses untuk beberapa kolom pada + adaptor sinkronisasi, sehingga tidak akan mengembalikannya ke aktivitas atau layanan. +</p> +<p> + Jika tidak ada baris yang cocok dengan kriteria pemilihan, penyedia + akan mengembalikan objek {@link android.database.Cursor} dengan + {@link android.database.Cursor#getCount Cursor.getCount()} adalah 0 (kursor kosong). +</p> +<p> + Jika terjadi kesalahan internal, hasil query akan bergantung pada penyedia tertentu. Penyedia bisa + memilih untuk menghasilkan <code>null</code>, atau melontarkan {@link java.lang.Exception}. +</p> +<p> + Karena {@link android.database.Cursor} adalah "daftar" baris, cara yang cocok untuk menampilkan + konten {@link android.database.Cursor} adalah mengaitkannya dengan {@link android.widget.ListView} + melalui {@link android.widget.SimpleCursorAdapter}. +</p> +<p> + Cuplikan berikut melanjutkan kode dari cuplikan sebelumnya. Cuplikan ini membuat + objek {@link android.widget.SimpleCursorAdapter} berisi {@link android.database.Cursor} + yang diambil oleh query, dan mengatur objek ini menjadi adaptor bagi + {@link android.widget.ListView}: +</p> +<pre class="prettyprint"> +// Defines a list of columns to retrieve from the Cursor and load into an output row +String[] mWordListColumns = +{ + UserDictionary.Words.WORD, // Contract class constant containing the word column name + UserDictionary.Words.LOCALE // Contract class constant containing the locale column name +}; + +// Defines a list of View IDs that will receive the Cursor columns for each row +int[] mWordListItems = { R.id.dictWord, R.id.locale}; + +// Creates a new SimpleCursorAdapter +mCursorAdapter = new SimpleCursorAdapter( + getApplicationContext(), // The application's Context object + R.layout.wordlistrow, // A layout in XML for one row in the ListView + mCursor, // The result from the query + mWordListColumns, // A string array of column names in the cursor + mWordListItems, // An integer array of view IDs in the row layout + 0); // Flags (usually none are needed) + +// Sets the adapter for the ListView +mWordList.setAdapter(mCursorAdapter); +</pre> +<p class="note"> + <strong>Catatan:</strong> Untuk mendukung {@link android.widget.ListView} dengan + {@link android.database.Cursor}, kursor harus berisi kolom bernama <code>_ID</code>. + Karena itu, query yang ditampilkan sebelumnya mengambil kolom <code>_ID</code> untuk + tabel "words", walaupun {@link android.widget.ListView} tidak menampilkannya. + Pembatasan ini juga menjelaskan mengapa sebagian besar penyedia memiliki kolom <code>_ID</code> untuk masing-masing + tabelnya. +</p> + + <!-- Getting data from query results --> +<h3 id="GettingResults">Mendapatkan data dari hasil query</h3> +<p> + Daripada sekadar menampilkan hasil query, Anda bisa menggunakannya untuk tugas-tugas lain. Misalnya, + Anda bisa mengambil ejaan dari kamus pengguna kemudian mencarinya dalam + penyedia lain. Caranya, ulangi baris-baris dalam {@link android.database.Cursor}: +</p> +<pre class="prettyprint"> + +// Determine the column index of the column named "word" +int index = mCursor.getColumnIndex(UserDictionary.Words.WORD); + +/* + * Only executes if the cursor is valid. The User Dictionary Provider returns null if + * an internal error occurs. Other providers may throw an Exception instead of returning null. + */ + +if (mCursor != null) { + /* + * Moves to the next row in the cursor. Before the first movement in the cursor, the + * "row pointer" is -1, and if you try to retrieve data at that position you will get an + * exception. + */ + while (mCursor.moveToNext()) { + + // Gets the value from the column. + newWord = mCursor.getString(index); + + // Insert code here to process the retrieved word. + + ... + + // end of while loop + } +} else { + + // Insert code here to report an error if the cursor is null or the provider threw an exception. +} +</pre> +<p> + Implementasi {@link android.database.Cursor} berisi beberapa metode "get" untuk + mengambil berbagai tipe data dari objek. Misalnya, cuplikan sebelumnya + menggunakan {@link android.database.Cursor#getString getString()}. Implementasi juga memiliki + metode {@link android.database.Cursor#getType getType()} yang menghasilkan nilai yang menunjukkan + tipe data kolom. +</p> + + + <!-- Requesting permissions --> +<h2 id="Permissions">Izin Penyedia Konten</h2> +<p> + Aplikasi penyedia bisa menetapkan izin yang harus dimiliki aplikasi lain untuk + mengakses data penyedia. Izin ini akan memastikan bahwa pengguna mengetahui data + yang coba diakses oleh aplikasi. Berdasarkan ketentuan penyedia, aplikasi lain + meminta izin yang diperlukannya untuk mengakses penyedia. Pengguna akhir akan melihat + izin yang diminta saat menginstal aplikasi. +</p> +<p> + Jika aplikasi penyedia tidak menetapkan izin apa pun, maka aplikasi lain tidak memiliki + akses ke data penyedia. Akan tetapi, komponen-komponen dalam aplikasi penyedia selalu memiliki + akses penuh untuk baca dan tulis, izin apa pun yang ditetapkan. +</p> +<p> + Seperti disebutkan sebelumnya, Penyedia Kamus Pengguna mensyaratkan izin + <code>android.permission.READ_USER_DICTIONARY</code> untuk mengambil data darinya. + Penyedia memiliki izin <code>android.permission.WRITE_USER_DICTIONARY</code> + yang terpisah untuk menyisipkan, memperbarui, atau menghapus data. +</p> +<p> + Untuk mendapatkan izin yang diperlukan untuk mengakses penyedia, aplikasi memintanya dengan elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> + dalam file manifesnya. Bila Android Package Manager memasang aplikasi, pengguna + harus menyetujui semua izin yang diminta aplikasi. Jika pengguna menyetujui semuanya, + Package Manager akan melanjutkan instalasi; jika pengguna tidak menyetujui, Package Manager + akan membatalkan instalasi. +</p> +<p> + Elemen +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> + berikut meminta akses baca ke Penyedia Kamus Pengguna: +</p> +<pre> + <uses-permission android:name="android.permission.READ_USER_DICTIONARY"> +</pre> +<p> + Dampak izin pada akses penyedia dijelaskan secara lebih detail dalam panduan + <a href="{@docRoot}guide/topics/security/security.html">Keamanan dan Izin</a>. +</p> + + +<!-- Inserting, Updating, and Deleting Data --> +<h2 id="Modifications">Menyisipkan, Memperbarui, dan Menghapus Data</h2> +<p> + Lewat cara yang sama dengan cara mengambil data dari penyedia, Anda juga menggunakan interaksi antara + klien penyedia dan {@link android.content.ContentProvider} penyedia untuk memodifikasi data. + Anda memanggil metode {@link android.content.ContentResolver} dengan argumen yang diteruskan ke + metode {@link android.content.ContentProvider} yang sesuai. Penyedia dan klien penyedia + menangani secara otomatis keamanan dan komunikasi antar-proses. +</p> +<h3 id="Inserting">Menyisipkan data</h3> +<p> + Untuk menyisipkan data ke penyedia, Anda memanggil metode + {@link android.content.ContentResolver#insert ContentResolver.insert()}. + Metode ini menyisipkan sebuah baris baru ke penyedia itu dan menghasilkan URI konten untuk baris itu. + Cuplikan ini menampilkan cara menyisipkan sebuah kata baru ke Penyedia Kamus Pengguna: +</p> +<pre class="prettyprint"> +// Defines a new Uri object that receives the result of the insertion +Uri mNewUri; + +... + +// Defines an object to contain the new values to insert +ContentValues mNewValues = new ContentValues(); + +/* + * Sets the values of each column and inserts the word. The arguments to the "put" + * method are "column name" and "value" + */ +mNewValues.put(UserDictionary.Words.APP_ID, "example.user"); +mNewValues.put(UserDictionary.Words.LOCALE, "en_US"); +mNewValues.put(UserDictionary.Words.WORD, "insert"); +mNewValues.put(UserDictionary.Words.FREQUENCY, "100"); + +mNewUri = getContentResolver().insert( + UserDictionary.Word.CONTENT_URI, // the user dictionary content URI + mNewValues // the values to insert +); +</pre> +<p> + Data untuk baris baru masuk ke dalam satu objek {@link android.content.ContentValues}, yang + serupa bentuknya dengan kursor satu-baris. Kolom dalam objek ini tidak perlu memiliki + tipe data yang sama, dan jika Anda tidak ingin menetapkan nilai sama sekali, Anda bisa mengatur kolom + ke <code>null</code> dengan menggunakan {@link android.content.ContentValues#putNull ContentValues.putNull()}. +</p> +<p> + Cuplikan ini tidak menambahkan kolom <code>_ID</code>, karena kolom ini dipelihara + secara otomatis. Penyedia menetapkan sebuah nilai unik <code>_ID</code> ke setiap baris yang + ditambahkan. Penyedia biasanya menggunakan nilai ini sebagai kunci utama tabel. +</p> +<p> + URI konten yang dihasilkan dalam <code>newUri</code> akan mengidentifikasi baris yang baru ditambahkan, dengan + format berikut: +</p> +<pre> +content://user_dictionary/words/<id_value> +</pre> +<p> + <code><id_value></code> adalah konten <code>_ID</code> untuk baris baru. + Kebanyakan penyedia bisa mendeteksi bentuk URI konten ini secara otomatis kemudian melakukan + operasi yang diminta pada baris tersebut. +</p> +<p> + Untuk mendapatkan nilai <code>_ID</code> dari {@link android.net.Uri} yang dihasilkan, panggil + {@link android.content.ContentUris#parseId ContentUris.parseId()}. +</p> +<h3 id="Updating">Memperbarui data</h3> +<p> + Untuk memperbarui sebuah baris, gunakan objek {@link android.content.ContentValues} dengan + nilai-nilai yang diperbarui, persis seperti yang Anda lakukan pada penyisipan, dan kriteria pemilihan persis seperti yang Anda lakukan pada query. + Metode klien yang Anda gunakan adalah + {@link android.content.ContentResolver#update ContentResolver.update()}. Anda hanya perlu menambahkan + nilai-nilai ke objek {@link android.content.ContentValues} untuk kolom yang sedang Anda perbarui. Jika Anda + ingin membersihkan konten kolom, aturlah nilai ke <code>null</code>. +</p> +<p> + Cuplikan berikut mengubah semua baris yang kolom lokalnya memiliki bahasa "en" ke + lokal <code>null</code>. Nilai hasil adalah jumlah baris yang diperbarui: +</p> +<pre> +// Defines an object to contain the updated values +ContentValues mUpdateValues = new ContentValues(); + +// Defines selection criteria for the rows you want to update +String mSelectionClause = UserDictionary.Words.LOCALE + "LIKE ?"; +String[] mSelectionArgs = {"en_%"}; + +// Defines a variable to contain the number of updated rows +int mRowsUpdated = 0; + +... + +/* + * Sets the updated value and updates the selected words. + */ +mUpdateValues.putNull(UserDictionary.Words.LOCALE); + +mRowsUpdated = getContentResolver().update( + UserDictionary.Words.CONTENT_URI, // the user dictionary content URI + mUpdateValues // the columns to update + mSelectionClause // the column to select on + mSelectionArgs // the value to compare to +); +</pre> +<p> + Anda juga harus membersihkan input pengguna bila memanggil + {@link android.content.ContentResolver#update ContentResolver.update()}. Untuk mengetahui selengkapnya tentang + hal ini, bacalah bagian <a href="#Injection">Melindungi dari input merusak</a>. +</p> +<h3 id="Deleting">Menghapus data</h3> +<p> + Menghapus baris serupa dengan mengambil baris data: Anda menetapkan kriteria pemilihan untuk baris + yang ingin Anda hapus dan metode klien akan menghasilkan jumlah baris yang dihapus. + Cuplikan berikut menghapus baris yang appid-nya sama dengan "user". Metode menghasilkan + jumlah baris yang dihapus. +</p> +<pre> + +// Defines selection criteria for the rows you want to delete +String mSelectionClause = UserDictionary.Words.APP_ID + " LIKE ?"; +String[] mSelectionArgs = {"user"}; + +// Defines a variable to contain the number of rows deleted +int mRowsDeleted = 0; + +... + +// Deletes the words that match the selection criteria +mRowsDeleted = getContentResolver().delete( + UserDictionary.Words.CONTENT_URI, // the user dictionary content URI + mSelectionClause // the column to select on + mSelectionArgs // the value to compare to +); +</pre> +<p> + Anda juga harus membersihkan input pengguna bila memanggil + {@link android.content.ContentResolver#delete ContentResolver.delete()}. Untuk mengetahui selengkapnya tentang + hal ini, bacalah bagian <a href="#Injection">Melindungi dari input merusak</a>. +</p> +<!-- Provider Data Types --> +<h2 id="DataTypes">Tipe Data Penyedia</h2> +<p> + Penyedia konten bisa menawarkan berbagai tipe data. Penyedia Kamus Pengguna hanya menawarkan + teks, namun penyedia juga bisa menawarkan format berikut: +</p> + <ul> + <li> + integer + </li> + <li> + long integer (long) + </li> + <li> + floating point + </li> + <li> + long floating point (double) + </li> + </ul> +<p> + Tipe data lain yang sering digunakan penyedia adalah Binary Large OBject (BLOB) yang diimplementasikan sebagai + larik byte 64 KB. Anda bisa melihat tipe data yang tersedia dengan memperhatikan metode "get" + kelas {@link android.database.Cursor}. +</p> +<p> + Tipe data tiap kolom dalam penyedia biasanya tercantum dalam dokumentasinya. + Tipe data untuk Penyedia Kamus Pengguna tercantum dalam dokumentasi acuan + untuk kelas kontraknya {@link android.provider.UserDictionary.Words} (kelas kontrak + dijelaskan di bagian <a href="#ContractClasses">Kelas-kelas Kontrak</a>). + Anda juga bisa menentukan tipe data dengan memanggil {@link android.database.Cursor#getType + Cursor.getType()}. +</p> +<p> + Penyedia juga memelihara informasi tipe data MIME untuk tiap URI konten yang didefinisikannya. Anda bisa + menggunakan informasi tipe MIME untuk mengetahui apakah aplikasi Anda bisa menangani data yang + disediakan penyedia, atau memilih tipe penanganan berdasarkan tipe MIME. Anda biasanya memerlukan + tipe MIME saat menggunakan penyedia yang berisi + struktur atau file data yang kompleks. Misalnya, tabel {@link android.provider.ContactsContract.Data} + dalam Penyedia Kontak menggunakan tipe MIME untuk memberi label tipe data kontak yang disimpan di tiap + baris. Untuk mendapatkan tipe MIME yang sesuai dengan URI konten, panggil + {@link android.content.ContentResolver#getType ContentResolver.getType()}. +</p> +<p> + Bagian <a href="#MIMETypeReference">Acuan Tipe MIME</a> menerangkan + sintaks tipe MIME baik yang standar maupun custom. +</p> + + +<!-- Alternative Forms of Provider Access --> +<h2 id="AltForms">Bentuk-Bentuk Alternatif Akses Penyedia</h2> +<p> + Tiga bentuk alternatif akses penyedia adalah penting dalam pengembangan aplikasi: +</p> +<ul> + <li> + <a href="#Batch">Akses batch</a>: Anda bisa membuat sebuah batch panggilan akses dengan metode-metode dalam + kelas {@link android.content.ContentProviderOperation}, kemudian menerapkannya dengan + {@link android.content.ContentResolver#applyBatch ContentResolver.applyBatch()}. + </li> + <li> + Query asinkron: Anda harus melakukan query dalam thread terpisah. Satu cara melakukannya adalah + menggunakan objek {@link android.content.CursorLoader}. Contoh-contoh dalam panduan + <a href="{@docRoot}guide/components/loaders.html">Loader</a> memperagakan + cara melakukannya. + </li> + <li> + <a href="#Intents">Akses data melalui intent</a>: Walaupun tidak bisa mengirim intent + ke penyedia secara langsung, Anda bisa mengirim intent ke aplikasi penyedia, yang + biasanya paling lengkap dibekali untuk memodifikasi data penyedia. + </li> +</ul> +<p> + Akses batch dan modifikasi melalui intent dijelaskan dalam bagian-bagian berikut. +</p> +<h3 id="Batch">Akses batch</h3> +<p> + Akses batch ke penyedia berguna untuk menyisipkan baris dalam jumlah besar, atau menyisipkan + baris ke dalam beberapa tabel dalam panggilan metode yang sama, atau biasanya melakukan satu set + operasi lintas batas proses sebagai transaksi (operasi atomik). +</p> +<p> + Untuk mengakses penyedia dalam "mode batch", + buat satu larik objek {@link android.content.ContentProviderOperation}, kemudian + kirim larik itu ke penyedia konten dengan + {@link android.content.ContentResolver#applyBatch ContentResolver.applyBatch()}. Anda meneruskan + <em>otoritas</em> penyedia konten ke metode ini, daripada URI konten tertentu. + Ini memungkinkan tiap objek {@link android.content.ContentProviderOperation} dalam larik untuk bekerja + terhadap tabel yang berbeda. Panggilan ke {@link android.content.ContentResolver#applyBatch + ContentResolver.applyBatch()} menghasilkan satu larik hasil. +</p> +<p> + Keterangan kelas kontrak {@link android.provider.ContactsContract.RawContacts} + menyertakan cuplikan kode yang memperagakan penyisipan batch. Contoh aplikasi + <a href="{@docRoot}resources/samples/ContactManager/index.html">Contacts Manager</a> + berisi contoh akses batch dalam file sumber <code>ContactAdder.java</code>-nya +. +</p> +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Menampilkan data dengan aplikasi pembantu</h2> +<p> + Jika aplikasi Anda <em>memang</em> memiliki izin akses, Anda masih mungkin perlu menggunakan + intent untuk menampilkan data dalam aplikasi lain. Misalnya, aplikasi Kalender menerima + intent {@link android.content.Intent#ACTION_VIEW}, yang menampilkan tanggal atau kejadian tertentu. + Hal ini memungkinkan Anda menampilkan informasi kalender tanpa harus membuat UI sendiri. + Untuk mengetahui selengkapnya tentang fitur ini, lihat panduan + <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Penyedia Kalender</a>. +</p> +<p> + Aplikasi yang Anda kirimi intent tidak harus aplikasi + yang terkait dengan penyedia. Misalnya, Anda bisa mengambil satu kontak dari + Penyedia Kontak, kemudian mengirim intent {@link android.content.Intent#ACTION_VIEW} + berisi URI konten untuk gambar kontak itu ke penampil gambar. +</p> +</div> +</div> +<h3 id="Intents">Akses data melalui intent</h3> +<p> + Intent bisa menyediakan akses tidak langsung ke penyedia konten. Anda memperbolehkan pengguna mengakses + data dalam penyedia sekalipun aplikasi Anda tidak memiliki izin akses, baik dengan + mendapatkan intent yang dihasilkan aplikasi yang memiliki izin, atau dengan mengaktifkan + aplikasi yang memiliki izin dan membiarkan pengguna melakukan pekerjaan di dalamnya. +</p> +<h4>Mendapatkan akses dengan izin sementara</h4> +<p> + Anda bisa mengakses data dalam penyedia konten, sekalipun tidak memiliki + izin akses yang sesuai, dengan mengirimkan intent ke aplikasi yang memang memiliki izin dan + menerima hasil berupa intent berisi izin "URI". + Inilah izin untuk URI konten tertentu yang berlaku hingga aktivitas yang menerima + izin selesai. Aplikasi yang memiliki izin tetap akan memberikan + izin sementara dengan mengatur flag dalam intent yang dihasilkan: +</p> +<ul> + <li> + <strong>Izin baca:</strong> + {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} + </li> + <li> + <strong>Izin tulis:</strong> + {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} + </li> +</ul> +<p class="note"> + <strong>Catatan:</strong> Flag ini tidak memberikan akses baca atau tulis umum ke penyedia + yang otoritasnya dimuat dalam URI konten. Aksesnya hanya untuk URI itu sendiri. +</p> +<p> + Penyedia mendefinisikan izin URI untuk URI konten dalam manifesnya, dengan menggunakan atribut +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">android:grantUriPermission</a></code> + dari elemen +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> +, serta elemen anak +<code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> + dari elemen +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>. + Mekanisme izin URI dijelaskan secara lebih detail dalam panduan + <a href="{@docRoot}guide/topics/security/security.html">Keamanan dan Izin</a>, + di bagian "Izin URI". +</p> +<p> + Misalnya, Anda bisa mengambil data untuk satu kontak di Penyedia Kontak, sekalipun tidak + memiliki izin {@link android.Manifest.permission#READ_CONTACTS}. Anda mungkin ingin melakukan + ini dalam aplikasi yang mengirim kartu ucapan elektronik ke seorang kenalan pada hari ulang tahunnya. Sebagai ganti + meminta {@link android.Manifest.permission#READ_CONTACTS}, yang memberi Anda akses ke semua + kontak pengguna dan semua informasinya, Anda lebih baik membiarkan pengguna mengontrol + kontak-kontak yang akan digunakan oleh aplikasi Anda. Caranya, gunakan proses berikut: +</p> +<ol> + <li> + Aplikasi Anda akan mengirim intent berisi tindakan + {@link android.content.Intent#ACTION_PICK} dan tipe MIME "contacts" + {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE}, dengan menggunakan + metode {@link android.app.Activity#startActivityForResult + startActivityForResult()}. + </li> + <li> + Karena intent ini cocok dengan filter intent untuk + aktivitas "pemilihan" aplikasi People, aktivitas akan muncul ke latar depan. + </li> + <li> + Dalam aktivitas pemilihan, pengguna memilih sebuah + kontak untuk diperbarui. Bila ini terjadi, aktivitas pemilihan akan memanggil + {@link android.app.Activity#setResult setResult(resultcode, intent)} + untuk membuat intent yang akan diberikan kembali ke aplikasi Anda. Intent itu berisi URI konten + kontak yang dipilih pengguna, dan flag "extras" + {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}. Semua flag ini memberikan + izin URI ke aplikasi Anda untuk membaca data kontak yang ditunjuk oleh + URI konten. Aktivitas pemilihan kemudian memanggil {@link android.app.Activity#finish()} untuk + mengembalikan kontrol ke aplikasi Anda. + </li> + <li> + Aktivitas Anda akan kembali ke latar depan, dan sistem memanggil metode + {@link android.app.Activity#onActivityResult onActivityResult()} + aktivitas Anda. Metode ini menerima intent yang dihasilkan oleh aktivitas pemilihan dalam + aplikasi People. + </li> + <li> + Dengan URI konten dari intent yang dihasilkan, Anda bisa membaca data kontak + dari Penyedia Kontak, sekalipun Anda tidak meminta izin akses baca tetap + ke penyedia dalam manifes Anda. Anda kemudian bisa mendapatkan informasi hari ulang tahun si kontak + atau alamat emailnya, kemudian mengirim kartu ucapan elektronik. + </li> +</ol> +<h4>Menggunakan aplikasi lain</h4> +<p> + Satu cara mudah agar pengguna bisa memodifikasi data yang izin aksesnya tidak Anda miliki adalah + mengaktifkan aplikasi yang memiliki izin dan membiarkan pengguna melakukan pekerjaannya di sana. +</p> +<p> + Misalnya, aplikasi Kalender menerima + intent {@link android.content.Intent#ACTION_INSERT}, yang memungkinkan Anda mengaktifkan + UI penyisipan aplikasi itu. Anda bisa meneruskan data "extras" dalam intent ini, yang + digunakan aplikasi untuk mengisi dahulu UI-nya. Karena kejadian berulang memiliki sintaks yang rumit, + cara yang lebih disukai untuk menyisipkan kejadian ke dalam Penyedia Kalender adalah mengaktifkan aplikasi Kalender dengan + {@link android.content.Intent#ACTION_INSERT}, kemudian membiarkan pengguna menyisipkan kejadian di sana. +</p> +<!-- Contract Classes --> +<h2 id="ContractClasses">Kelas-kelas Kontrak</h2> +<p> + Kelas kontrak mendefinisikan konstanta yang membantu aplikasi menggunakan URI konten, nama + kolom, tindakan intent, dan fitur lain pada penyedia konten. Kelas kontrak tidak + disertakan secara otomatis bersama penyedia; pengembang penyedia harus mendefinisikannya kemudian + membuatnya tersedia bagi pengembang lain. Banyak penyedia yang disertakan pada platform Android + memiliki kelas kontrak yang sesuai dalam {@link android.provider} paketnya. +</p> +<p> + Misalnya, Penyedia Kamus Pengguna memiliki kelas kontrak + {@link android.provider.UserDictionary} yang berisi URI konten dan konstanta nama kolom. URI + konten untuk tabel "words" didefinisikan dalam konstanta + {@link android.provider.UserDictionary.Words#CONTENT_URI UserDictionary.Words.CONTENT_URI}. + Kelas {@link android.provider.UserDictionary.Words} juga berisi konstanta nama kolom, + yang digunakan dalam cuplikan contoh pada panduan ini. Misalnya, sebuah proyeksi query bisa + didefinisikan sebagai: +</p> +<pre> +String[] mProjection = +{ + UserDictionary.Words._ID, + UserDictionary.Words.WORD, + UserDictionary.Words.LOCALE +}; +</pre> +<p> + Kelas kontrak lain adalah {@link android.provider.ContactsContract} untuk Penyedia Kontak. + Dokumentasi acuan untuk kelas ini menyertakan contoh cuplikan kode. Salah satu + subkelasnya, {@link android.provider.ContactsContract.Intents.Insert}, adalah + kelas kontrak yang berisi konstanta untuk intent dan data intent. +</p> + + +<!-- MIME Type Reference --> +<h2 id="MIMETypeReference">Acuan Tipe MIME</h2> +<p> + Penyedia konten bisa menghasilkan tipe media MIME standar, atau string tipe MIME custom, atau keduanya. +</p> +<p> + Tipe MIME memiliki format +</p> +<pre> +<em>type</em>/<em>subtype</em> +</pre> +<p> + Misalnya, tipe MIME <code>text/html</code> yang dikenal luas memiliki tipe <code>text</code> dan + subtipe <code>html</code>. Jika penyedia menghasilkan tipe ini untuk sebuah URI, artinya + query dengan URI itu akan menghasilkan teks berisi tag HTML. +</p> +<p> + String tipe MIME custom, yang juga disebut dengan tipe MIME "khusus vendor", memiliki nilai-nilai + <em>tipe</em> dan <em>subtipe</em> yang lebih kompleks. Nilai <em>tipe</em> selalu +</p> +<pre> +vnd.android.cursor.<strong>dir</strong> +</pre> +<p> + untuk beberapa baris, atau +</p> +<pre> +vnd.android.cursor.<strong>item</strong> +</pre> +<p> + untuk satu baris. +</p> +<p> + <em>Subtipe</em> adalah khusus penyedia. Penyedia bawaan Android biasanya memiliki subtipe + sederhana. Misalnya, bila aplikasi Contacts membuat satu baris untuk nomor telepon, + aplikasi akan mengatur tipe MIME berikut di baris itu: +</p> +<pre> +vnd.android.cursor.item/phone_v2 +</pre> +<p> + Perhatikan bahwa nilai subtipe adalah sekadar <code>phone_v2</code>. +</p> +<p> + Pengembang penyedia lain bisa membuat pola subtipe sendiri berdasarkan + otoritas dan nama-nama tabel penyedia. Misalnya, perhatikan penyedia yang berisi jadwal kereta api. + Otoritas penyedia adalah <code>com.example.trains</code>, dan berisi tabel-tabel + Line1, Line2, dan Line3. Untuk merespons URI konten +</p> +<p> +<pre> +content://com.example.trains/Line1 +</pre> +<p> + untuk tabel Line1, penyedia menghasilkan tipe MIME +</p> +<pre> +vnd.android.cursor.<strong>dir</strong>/vnd.example.line1 +</pre> +<p> + Untuk merespons URI konten +</p> +<pre> +content://com.example.trains/Line2/5 +</pre> +<p> + untuk baris 5 di tabel Line2, penyedia menghasilkan tipe MIME +</p> +<pre> +vnd.android.cursor.<strong>item</strong>/vnd.example.line2 +</pre> +<p> + Kebanyakan penyedia konten mendefinisikan konstanta kelas kontrak untuk tipe MIME yang digunakannya. Kelas kontrak + {@link android.provider.ContactsContract.RawContacts} pada Penyedia Kontak + misalnya, mendefinisikan konstanta + {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE} untuk tipe MIME + baris kontak mentah tunggal. +</p> +<p> + URI konten untuk baris-baris tunggal dijelaskan di bagian + <a href="#ContentURIs">URI Konten</a>. +</p> diff --git a/docs/html-intl/intl/in/guide/topics/providers/content-provider-creating.jd b/docs/html-intl/intl/in/guide/topics/providers/content-provider-creating.jd new file mode 100644 index 000000000000..fefce703c2c8 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/content-provider-creating.jd @@ -0,0 +1,1214 @@ +page.title=Membuat Penyedia Konten +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + + +<h2>Dalam dokumen ini</h2> +<ol> + <li> + <a href="#DataStorage">Mendesain Penyimpanan Data</a> + </li> + <li> + <a href="#ContentURI">Mendesain URI Konten</a> + </li> + <li> + <a href="#ContentProvider">Mengimplementasikan Kelas ContentProvider</a> + <ol> + <li> + <a href="#RequiredAccess">Metode-Metode yang Diperlukan</a> + </li> + <li> + <a href="#Query">Mengimplementasikan metode query()</a> + </li> + <li> + <a href="#Insert">Mengimplementasikan metode insert()</a> + </li> + <li> + <a href="#Delete">Mengimplementasikan metode delete()</a> + </li> + <li> + <a href="#Update">Mengimplementasikan metode update()</a> + </li> + <li> + <a href="#OnCreate">Mengimplementasikan metode onCreate()</a> + </li> + </ol> + </li> + <li> + <a href="#MIMETypes">Mengimplementasikan Tipe MIME Penyedia Konten</a> + <ol> + <li> + <a href="#TableMIMETypes">Tipe MIME untuk tabel</a> + </li> + <li> + <a href="#FileMIMETypes">Tipe MIME untuk file</a> + </li> + </ol> + </li> + <li> + <a href="#ContractClass">Mengimplementasikan Kelas Kontrak</a> + </li> + <li> + <a href="#Permissions">Mengimplementasikan Izin Penyedia Konten</a> + </li> + <li> + <a href="#ProviderElement">Elemen <provider></a> + </li> + <li> + <a href="#Intents">Intent dan Akses Data</a> + </li> +</ol> +<h2>Kelas-kelas utama</h2> + <ol> + <li> + {@link android.content.ContentProvider} + </li> + <li> + {@link android.database.Cursor} + </li> + <li> + {@link android.net.Uri} + </li> + </ol> +<h2>Contoh-Contoh Terkait</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/NotePad/index.html"> + Aplikasi contoh Note Pad + </a> + </li> + </ol> +<h2>Lihat juga</h2> + <ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Penyedia Kalender</a> + </li> + </ol> +</div> +</div> + + +<p> + Penyedia konten mengelola akses ke repository data pusat. Anda mengimplementasikan + penyedia sebagai satu atau beberapa kelas dalam aplikasi Android, bersama elemen-elemen dalam + file manifes. Salah satu kelas Anda mengimplementasikan subkelas + {@link android.content.ContentProvider}, yang merupakan antarmuka antara penyedia Anda dan + aplikasi lain. Walaupun penyedia konten dimaksudkan untuk menyediakan data bagi + aplikasi lain, Anda tentu saja bisa memiliki aktivitas dalam aplikasi yang memungkinkan pengguna + melakukan query dan memodifikasi data yang dikelola oleh penyedia Anda. +</p> +<p> + Bagian selebihnya dalam topik ini adalah daftar langkah-langkah dasar untuk membangun penyedia konten dan daftar + API yang akan digunakan. +</p> + + +<!-- Before You Start Building --> +<h2 id="BeforeYouStart">Sebelum Anda Mulai Membangun</h2> +<p> + Sebelum Anda mulai membangun penyedia, lakukanlah hal-hal berikut: +</p> +<ol> + <li> + <strong>Putuskan apakah Anda memerlukan penyedia konten</strong>. Anda perlu membangun sebuah + penyedia konten jika ingin menyediakan salah satu atau beberapa dari fitur berikut: + <ul> + <li>Anda ingin menawarkan data atau file yang kompleks ke aplikasi lain.</li> + <li>Anda ingin memungkinkan pengguna menyalin data yang kompleks dari aplikasi Anda ke dalam aplikasi lain.</li> + <li>Anda ingin menyediakan saran pencarian custom dengan menggunakan kerangka kerja pencarian.</li> + </ul> + <p> + Anda <em>tidak</em> mengharuskan penyedia untuk menggunakan database SQLite jika hanya digunakan dalam + aplikasi sendiri. + </p> + </li> + <li> + Jika Anda belum siap melakukannya, bacalah topik + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a> untuk mengetahui selengkapnya tentang penyedia. + </li> +</ol> +<p> + Berikutnya, ikuti langkah-langkah ini untuk membangun penyedia: +</p> +<ol> + <li> + Desain penyimpanan mentah untuk data Anda. Penyedia konten menawarkan data dengan dua cara: + <dl> + <dt> + Data file + </dt> + <dd> + Data yang biasanya masuk ke dalam file, misalnya + foto, audio, atau video. Simpan file dalam ruang privat + aplikasi Anda. Untuk merespons permintaan file dari aplikasi lain, + penyedia Anda bisa menawarkan handle ke file tersebut. + </dd> + <dt> + Data "terstruktur" + </dt> + <dd> + Data yang biasanya masuk ke dalam database, larik, atau struktur serupa. + Simpan data dalam bentuk yang kompatibel dengan tabel berisi baris dan kolom. Baris + mewakili entitas, misalnya satu orang atau satu barang inventori. Kolom mewakili + beberapa data untuk entitas itu, misalnya nama orang atau harga barang. Cara umum untuk + menyimpan tipe data ini adalah dalam database SQLite, namun Anda bisa menggunakan tipe + penyimpanan apa saja yang persisten. Untuk mengetahui selengkapnya tentang tipe penyimpanan yang tersedia di + sistem Android, lihat bagian <a href="#DataStorage"> + Mendesain Penyimpanan Data</a>. + </dd> + </dl> + </li> + <li> + Definisikan sebuah implementasi konkret kelas {@link android.content.ContentProvider} dan + metode yang diperlukannya. Kelas ini adalah antarmuka antara data Anda dan bagian selebihnya pada + sistem Android. Untuk informasi selengkapnya tentang kelas ini, lihat bagian + <a href="#ContentProvider">Mengimplementasikan Kelas ContentProvider</a>. + </li> + <li> + Definisikan string otoritas, semua URI isinya, dan nama-nama kolom penyedia. Jika Anda ingin + penyedia aplikasi menangani intent, definisikan juga semua tindakan intent, data ekstra, + dan flag. Definisikan juga izin yang akan Anda syaratkan terhadap aplikasi yang ingin + mengakses data Anda. Anda harus mempertimbangkan pendefinisian semua nilai ini sebagai konstanta di + kelas kontrak terpisah; nantinya, Anda bisa mengekspos kelas ini kepada pengembang lain. Untuk + informasi selengkapnya tentang URI konten, lihat + bagian <a href="#ContentURI">Mendesain URI Konten</a>. + Untuk informasi selengkapnya tentang intent, lihat + bagian <a href="#Intents">Intent dan Akses Data</a>. + </li> + <li> + Tambahkan bagian opsional lainnya, seperti data contoh atau implementasi + {@link android.content.AbstractThreadedSyncAdapter} yang bisa menyinkronkan data antara + penyedia dan data berbasis cloud. + </li> +</ol> + + +<!-- Designing Data Storage --> +<h2 id="DataStorage">Mendesain Penyimpanan Data</h2> +<p> + Penyedia konten adalah antarmuka ke data yang disimpan dalam format terstruktur. Sebelum membuat + antarmuka, Anda harus memutuskan cara menyimpan data. Anda bisa menyimpan data dalam bentuk apa saja yang Anda + sukai, kemudian mendesain antarmuka untuk membaca dan menulis data yang diperlukan. +</p> +<p> + Berikut ini adalah beberapa teknologi penyimpanan data yang tersedia di Android: +</p> +<ul> + <li> + Sistem Android menyertakan API database SQLite yang digunakan penyedia Android sendiri + untuk menyimpan data berorientasi tabel. Kelas + {@link android.database.sqlite.SQLiteOpenHelper} membantu Anda membuat database, dan kelas + {@link android.database.sqlite.SQLiteDatabase} adalah kelas dasar untuk mengakses + database. + <p> + Ingatlah bahwa Anda tidak harus menggunakan database untuk mengimplementasikan repository. Penyedia + muncul secara eksternal sebagai satu set tabel, yang serupa dengan sebuah database relasional, namun ini + bukan persyaratan untuk implementasi internal penyedia. + </p> + </li> + <li> + Untuk menyimpan file data, Android memiliki beragam API berorientasi file. + Untuk mengetahui selengkapnya tentang penyimpanan file, bacalah topik + <a href="{@docRoot}guide/topics/data/data-storage.html">Penyimpanan Data</a>. Jika Anda sedang + mendesain penyedia yang menawarkan data yang terkait dengan media seperti musik atau video, Anda bisa + memiliki penyedia yang mengombinasikan data tabel dan file. + </li> + <li> + Untuk bekerja dengan data berbasis jaringan, gunakan kelas-kelas dalam {@link java.net} dan + {@link android.net}. Anda juga bisa menyinkronkan data berbasis jaringan dengan penyimpanan data lokal + seperti database, kemudian menawarkan data sebagai tabel atau file. + Aplikasi contoh <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Sample Sync Adapter</a> memperagakan tipe sinkronisasi ini. + </li> +</ul> +<h3 id="DataDesign"> + Pertimbangan desain data +</h3> +<p> + Berikut ini adalah beberapa tip untuk mendesain struktur data penyedia: +</p> +<ul> + <li> + Data tabel harus selalu memiliki kolom "kunci utama" yang dipelihara oleh penyedia + sebagai nilai numerik unik untuk setiap baris. Anda bisa menggunakan nilai ini untuk menautkan baris ke + baris yang terkait dalam tabel lain (dengan menggunakannya sebagai "kunci asing"). Walaupun Anda bisa menggunakan nama + apa saja untuk kolom ini, menggunakan {@link android.provider.BaseColumns#_ID BaseColumns._ID} adalah + pilihan terbaik, karena menautkan hasil query penyedia dengan + {@link android.widget.ListView} mensyaratkan bahwa salah satu kolom yang diambil memiliki nama + <code>_ID</code>. + </li> + <li> + Jika Anda ingin untuk menyediakan gambar bitmap atau potongan data berorientasi file lainnya yang berukuran sangat besar, simpanlah + data dalam sebuah file kemudian sediakan secara tidak langsung sebagai ganti menyimpannya secara langsung dalam + tabel. Jika melakukannya, Anda perlu memberi tahu pengguna penyedia Anda bahwa mereka perlu menggunakan metode file + {@link android.content.ContentResolver} untuk mengakses data. + </li> + <li> + Gunakan tipe data Binary Large OBject (BLOB) untuk menyimpan data yang bervariasi ukurannya atau memiliki + struktur yang beragam. Misalnya, Anda bisa menggunakan sebuah kolom BLOB untuk menyimpan + <a href="http://code.google.com/p/protobuf">buffer protokol</a> atau + <a href="http://www.json.org">struktur JSON</a>. + <p> + Anda juga bisa menggunakan BLOB untuk mengimplementasikan tabel yang <em>tidak bergantung skema</em>. Dalam + tipe tabel ini, Anda mendefinisikan kolom kunci utama, kolom tipe MIME, dan satu atau beberapa + kolom generik sebagai BLOB. Arti dari data dalam kolom-kolom BLOB ditunjukkan + oleh nilai dalam kolom tipe MIME. Cara ini memungkinkan Anda menyimpan berbagai tipe baris dalam + tabel yang sama. Tabel "data" + {@link android.provider.ContactsContract.Data} Penyedia Kontak adalah contoh tabel yang tidak bergantung skema + tersebut. + </p> + </li> +</ul> +<!-- Designing Content URIs --> +<h2 id="ContentURI">Mendesain URI Konten</h2> +<p> + <strong>URI konten</strong> adalah URI yang mengidentifikasi data dalam penyedia. URI Konten + berisi nama simbolis seluruh penyedia (<strong>otoritas</strong>nya) dan sebuah + nama yang menunjuk ke tabel atau file (<strong>path</strong>). Bagian id opsional menunjuk ke + satu baris dalam tabel. Setiap metode akses data + {@link android.content.ContentProvider} memiliki sebuah URI konten sebagai argumen; hal ini memungkinkan Anda + menentukan tabel, baris, atau file yang akan diakses. +</p> +<p> + Dasar-dasar URI konten dijelaskan dalam topik + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a>. +</p> +<h3>Mendesain otoritas</h3> +<p> + Penyedia biasanya memiliki otoritas tunggal, yang berfungsi sebagai nama internal Android-nya. Untuk + menghindari konflik dengan penyedia lain, Anda harus menggunakan kepemilikan domain internet (secara terbalik) + sebagai basis otoritas penyedia Anda. Karena saran ini juga berlaku untuk + nama-nama paket Android, Anda bisa mendefinisikan otoritas penyedia sebagai perluasan dari nama + paket yang berisi penyedia. Misalnya, jika nama paket Android Anda adalah + <code>com.example.<appname></code>, Anda harus memberikan penyedia Anda + otoritas <code>com.example.<appname>.provider</code>. +</p> +<h3>Mendesain struktur path</h3> +<p> + Pengembang biasanya membuat URI konten dari otoritas dengan menambahkan path yang menunjuk ke + masing-masing tabel. Misalnya, jika Anda memiliki dua tabel <em>table1</em> dan + <em>table2</em>, Anda mengombinasikan otoritas dari contoh sebelumnya untuk menghasilkan + URI konten + <code>com.example.<appname>.provider/table1</code> dan + <code>com.example.<appname>.provider/table2</code>. Path tidak + dibatasi pada segmen tunggal, dan tidak harus berupa tabel untuk masing-masing tingkat path. +</p> +<h3>Menangani ID URI konten</h3> +<p> + Berdasarkan standar, penyedia menawarkan akses ke satu baris dalam tabel dengan menerima URI konten + dengan sebuah nilai ID untuk baris itu di akhir URI. Juga berdasarkan standar, penyedia mencocokkan + nilai ID dengan kolom <code>_ID</code> tabel, dan melakukan akses yang diminta terhadap baris + yang cocok. +</p> +<p> + Standar ini memudahkan pola desain umum untuk aplikasi yang mengakses penyedia. Aplikasi + melakukan query terhadap penyedia dan menampilkan {@link android.database.Cursor} yang dihasilkan + dalam {@link android.widget.ListView} dengan menggunakan {@link android.widget.CursorAdapter}. + Definisi {@link android.widget.CursorAdapter} mengharuskan salah satu kolom dalam + {@link android.database.Cursor} berupa <code>_ID</code> +</p> +<p> + Pengguna kemudian mengambil salah satu baris yang ditampilkan dari UI untuk menemukan atau memodifikasi + data. Aplikasi mengambil baris yang sesuai dari {@link android.database.Cursor} yang mendukung + {@link android.widget.ListView}, mengambil nilai <code>_ID</code> untuk baris ini, menambahkannya ke + URI konten, dan mengirim permintaan akses ke penyedia. Penyedia nanti bisa melakukan + query atau modifikasi terhadap baris yang persis diambil pengguna. +</p> +<h3>Pola URI konten</h3> +<p> + Untuk membantu Anda memilih tindakan yang diambil bagi URI konten yang masuk, API penyedia menyertakan + kelas praktis {@link android.content.UriMatcher}, yang memetakan "pola-pola" URI konten ke + nilai-nilai integer. Anda bisa menggunakan nilai-nilai integer dalam pernyataan <code>switch</code> yang + memilih tindakan yang diinginkan untuk URI konten atau URI yang cocok dengan pola tertentu. +</p> +<p> + Pola URI konten mencocokkan dengan URI konten menggunakan karakter wildcard: +</p> + <ul> + <li> + <strong><code>*</code>:</strong> Mencocokkan string yang memiliki karakter yang sah dengan panjang berapa saja. + </li> + <li> + <strong><code>#</code>:</strong> Mencocokkan string karakter numerik dengan panjang berapa saja. + </li> + </ul> +<p> + Sebagai contoh desain dan pemrograman penanganan URI konten, perhatikan penyedia dengan + otoritas <code>com.example.app.provider</code> yang mengenali URI konten berikut + yang menunjuk ke tabel-tabel: +</p> +<ul> + <li> + <code>content://com.example.app.provider/table1</code>: Tabel bernama <code>table1</code>. + </li> + <li> + <code>content://com.example.app.provider/table2/dataset1</code>: Tabel bernama + <code>dataset1</code>. + </li> + <li> + <code>content://com.example.app.provider/table2/dataset2</code>: Tabel bernama + <code>dataset2</code>. + </li> + <li> + <code>content://com.example.app.provider/table3</code>: Tabel bernama <code>table3</code>. + </li> +</ul> +<p> + Penyedia juga mengenali URI konten ini jika baris ID ditambahkan ke URI, + misalnya <code>content://com.example.app.provider/table3/1</code> untuk baris yang diidentifikasi oleh + <code>1</code> dalam <code>table3</code>. +</p> +<p> + Pola-pola URI konten berikut akan menjadi mungkin: +</p> +<dl> + <dt> + <code>content://com.example.app.provider/*</code> + </dt> + <dd> + Mencocokkan URI konten di penyedia. + </dd> + <dt> + <code>content://com.example.app.provider/table2/*</code>: + </dt> + <dd> + Mencocokkan URI konten untuk tabel-tabel <code>dataset1</code> + dan <code>dataset2</code>, namun tidak mencocokkan URI konten untuk <code>table1</code> atau + <code>table3</code>. + </dd> + <dt> + <code>content://com.example.app.provider/table3/#</code>: Mencocokkan URI konten + untuk satu baris di <code>table3</code>, misalnya + <code>content://com.example.app.provider/table3/6</code> untuk baris yang diidentifikasi oleh + <code>6</code>. + </dt> +</dl> +<p> + Cuplikan kode berikut menunjukkan cara kerja metode di {@link android.content.UriMatcher}. + Kode ini menangani URI seluruh tabel secara berbeda dengan URI untuk + satu baris, menggunakan pola URI konten + <code>content://<authority>/<path></code> untuk tabel, dan + <code>content://<authority>/<path>/<id></code> untuk satu baris. +</p> +<p> + Metode {@link android.content.UriMatcher#addURI(String, String, int) addURI()} memetakan + otoritas dan path ke nilai integer. Metode {@link android.content.UriMatcher#match(Uri) + match()} menghasilkan nilai integer URI. Pernyataan <code>switch</code> + memilih antara melakukan query seluruh tabel dan melakukan query satu record: +</p> +<pre class="prettyprint"> +public class ExampleProvider extends ContentProvider { +... + // Creates a UriMatcher object. + private static final UriMatcher sUriMatcher; +... + /* + * The calls to addURI() go here, for all of the content URI patterns that the provider + * should recognize. For this snippet, only the calls for table 3 are shown. + */ +... + /* + * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used + * in the path + */ + sUriMatcher.addURI("com.example.app.provider", "table3", 1); + + /* + * Sets the code for a single row to 2. In this case, the "#" wildcard is + * used. "content://com.example.app.provider/table3/3" matches, but + * "content://com.example.app.provider/table3 doesn't. + */ + sUriMatcher.addURI("com.example.app.provider", "table3/#", 2); +... + // Implements ContentProvider.query() + public Cursor query( + Uri uri, + String[] projection, + String selection, + String[] selectionArgs, + String sortOrder) { +... + /* + * Choose the table to query and a sort order based on the code returned for the incoming + * URI. Here, too, only the statements for table 3 are shown. + */ + switch (sUriMatcher.match(uri)) { + + + // If the incoming URI was for all of table3 + case 1: + + if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC"; + break; + + // If the incoming URI was for a single row + case 2: + + /* + * Because this URI was for a single row, the _ID value part is + * present. Get the last path segment from the URI; this is the _ID value. + * Then, append the value to the WHERE clause for the query + */ + selection = selection + "_ID = " uri.getLastPathSegment(); + break; + + default: + ... + // If the URI is not recognized, you should do some error handling here. + } + // call the code to actually do the query + } +</pre> +<p> + Kelas lainnya, {@link android.content.ContentUris}, menyediakan metode praktis untuk menggunakan + bagian <code>id</code> URI konten. Kelas-kelas {@link android.net.Uri} dan + {@link android.net.Uri.Builder} menyertakan metode praktis untuk mengurai + objek {@link android.net.Uri} yang ada dan membuat objek baru. +</p> + +<!-- Implementing the ContentProvider class --> +<h2 id="ContentProvider">Mengimplementasikan Kelas ContentProvider</h2> +<p> + Instance {@link android.content.ContentProvider} mengelola akses + ke satu set data terstruktur dengan menangani permintaan dari aplikasi lain. Semua bentuk + akses pada akhirnya akan memanggil {@link android.content.ContentResolver}, yang kemudian memanggil + metode konkret {@link android.content.ContentProvider} untuk mendapatkan akses. +</p> +<h3 id="RequiredAccess">Metode-metode yang diperlukan</h3> +<p> + Kelas abstrak {@link android.content.ContentProvider} mendefinisikan enam metode abstrak yang + harus Anda implementasikan sebagai bagian dari subkelas konkret Anda sendiri. Semua metode ini kecuali + {@link android.content.ContentProvider#onCreate() onCreate()} dipanggil oleh aplikasi klien + yang berupaya mengakses penyedia konten Anda: +</p> +<dl> + <dt> + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + query()} + </dt> + <dd> + Mengambil data dari penyedia Anda. Menggunakan argumen untuk memilih tabel yang akan + di-query, baris dan kolom yang akan dihasilkan, dan urutan sortir hasilnya. + Menghasilkan data berupa objek {@link android.database.Cursor}. + </dd> + <dt> + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} + </dt> + <dd> + Menyisipkan baris baru ke dalam penyedia Anda. Menggunakan argumen untuk memilih + tabel tujuan dan mendapatkan nilai-nilai kolom yang akan digunakan. Menghasilkan URI konten untuk + baris yang baru disisipkan. + </dd> + <dt> + {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) + update()} + </dt> + <dd> + Memperbarui baris yang ada di penyedia Anda. Menggunakan argumen untuk memilih tabel dan baris + yang akan diperbarui dan mendapatkan nilai-nilai kolom yang diperbarui. Menghasilkan jumlah baris yang diperbarui. + </dd> + <dt> + {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} + </dt> + <dd> + Menghapus baris dari penyedia Anda. Menggunakan argumen untuk memilih tabel dan baris yang akan + dihapus. Menghasilkan jumlah baris yang dihapus. + </dd> + <dt> + {@link android.content.ContentProvider#getType(Uri) getType()} + </dt> + <dd> + Menghasilkan tipe MIME yang sesuai dengan URI konten. Metode ini dijelaskan lebih detail + di bagian <a href="#MIMETypes">Mengimplementasikan Tipe MIME Penyedia Konten</a>. + </dd> + <dt> + {@link android.content.ContentProvider#onCreate() onCreate()} + </dt> + <dd> + Inisialisasi penyedia Anda. Sistem Android memanggil metode ini segera setelah + membuat penyedia Anda. Perhatikan bahwa penyedia Anda tidak dibuat hingga + objek {@link android.content.ContentResolver} mencoba mengaksesnya. + </dd> +</dl> +<p> + Perhatikan bahwa metode-metode ini memiliki signature yang sama dengan + metode-metode {@link android.content.ContentResolver} yang sama namanya. +</p> +<p> + Implementasi metode-metode ini harus memperhitungkan hal-hal berikut: +</p> +<ul> + <li> + Semua metode ini kecuali {@link android.content.ContentProvider#onCreate() onCreate()} + bisa dipanggil oleh beberapa thread sekaligus, jadi harus thread-safe (aman untuk thread). Untuk mengetahui + selengkapnya tentang multi-thread, lihat topik + <a href="{@docRoot}guide/components/processes-and-threads.html"> + Proses dan Thread</a>. + </li> + <li> + Hindari melakukan operasi yang lama dalam {@link android.content.ContentProvider#onCreate() + onCreate()}. Tunda inisialisasi tugas hingga benar-benar diperlukan. + Bagian <a href="#OnCreate">Mengimplementasikan metode onCreate()</a> + membahas hal ini secara lebih detail. + </li> + <li> + Walaupun harus mengimplementasikan metode-metode ini, kode Anda tidak harus melakukan apa pun selain + tipe data yang diharapkan. Misalnya, Anda mungkin ingin mencegah aplikasi lain + menyisipkan data ke dalam beberapa tabel. Caranya, Anda bisa mengabaikan panggilan ke + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} dan menghasilkan + 0. + </li> +</ul> +<h3 id="Query">Mengimplementasikan metode query()</h3> +<p> + Metode + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + ContentProvider.query()} harus menghasilkan objek {@link android.database.Cursor}, atau jika + gagal, melontarkan {@link java.lang.Exception}. Jika menggunakan database SQLite sebagai + penyimpanan data, Anda bisa mengembalikan{@link android.database.Cursor} yang dikembalikan oleh salah satu metode + <code>query()</code> dari kelas {@link android.database.sqlite.SQLiteDatabase}. + Jika query tidak mencocokkan baris apa pun, Anda harus mengembalikan instance {@link android.database.Cursor} + yang metode {@link android.database.Cursor#getCount()}-nya mengembalikan 0. + Anda harus mengembalikan <code>null</code> hanya jika terjadi kesalahan internal selama proses query. +</p> +<p> + Jika Anda tidak menggunakan database SQLite sebagai penyimpanan data, gunakan salah satu subkelas konkret + {@link android.database.Cursor}. Misalnya, kelas {@link android.database.MatrixCursor} + mengimplementasikan kursor dengan masing-masing baris berupa larik {@link java.lang.Object}. Dengan kelas ini, + gunakan {@link android.database.MatrixCursor#addRow(Object[]) addRow()} untuk menambahkan baris baru. +</p> +<p> + Ingatlah bahwa sistem Android harus mampu mengomunikasikan {@link java.lang.Exception} + lintas batas proses. Android bisa melakukannya untuk eksepsi berikut yang mungkin berguna + dalam menangani kesalahan query: +</p> +<ul> + <li> + {@link java.lang.IllegalArgumentException} (Anda bisa saja melontarkannya jika penyedia Anda + menerima URI konten yang tidak sah) + </li> + <li> + {@link java.lang.NullPointerException} + </li> +</ul> +<h3 id="Insert">Mengimplementasikan metode insert()</h3> +<p> + Metode {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} menambahkan satu + baris baru ke tabel yang sesuai, dengan menggunakan nilai-nilai dalam argumen {@link android.content.ContentValues}. + Jika kolom nama tidak ada dalam argumen {@link android.content.ContentValues}, Anda + mungkin perlu menyediakan nilai default untuknya, baik dalam kode penyedia atau dalam skema database + Anda. +</p> +<p> + Metode ini harus mengembalikan URI konten untuk baris baru. Untuk membuatnya, tambahkan nilai + <code>_ID</code> baris baru (atau kunci utama lainnya) ke tabel URI konten, dengan menggunakan + {@link android.content.ContentUris#withAppendedId(Uri, long) withAppendedId()}. +</p> +<h3 id="Delete">Mengimplementasikan metode delete()</h3> +<p> + Metode {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} + tidak harus menghapus baris-baris dari penyimpanan data Anda secara fisik. Jika menggunakan adaptor sinkronisasi + bersama penyedia, Anda harus mempertimbangkan penandaan baris yang dihapus + dengan flag "delete"; bukan menghilangkan baris itu sepenuhnya. Adaptor sinkronisasi bisa + memeriksa baris yang dihapus dan menghilangkannya dari server sebelum menghapusnya dari penyedia. +</p> +<h3 id="Update">Mengimplementasikan metode update()</h3> +<p> + Metode {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[]) + update()} mengambil argumen {@link android.content.ContentValues} yang sama dengan yang digunakan oleh + {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}, dan + argumen-argumen <code>selection</code> dan <code>selectionArgs</code> yang sama dengan yang digunakan oleh + {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} dan + {@link android.content.ContentProvider#query(Uri, String[], String, String[], String) + ContentProvider.query()}. Hal ini bisa memungkinkan Anda menggunakan kembali kode di antara metode-metode ini. +</p> +<h3 id="OnCreate">Mengimplementasikan metode onCreate()</h3> +<p> + Sistem Android memanggil {@link android.content.ContentProvider#onCreate() + onCreate()} saat memulai penyedia. Anda harus melakukan tugas-tugas inisialisasi yang berjalan cepat saja + dalam metode ini, serta menunda pembuatan database dan pemuatan data hingga penyedia benar-benar + menerima permintaan terhadap data. Jika Anda melakukan tugas yang memakan waktu dalam + {@link android.content.ContentProvider#onCreate() onCreate()}, Anda akan memperlambat + startup penyedia. Pada gilirannya, hal ini akan memperlambat respons dari penyedia terhadap + aplikasi lain. +</p> +<p> + Misalnya, jika menggunakan database SQLite, Anda bisa membuat + sebuah objek {@link android.database.sqlite.SQLiteOpenHelper} baru di + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}, + kemudian membuat tabel-tabel SQL saat pertama kali membuka database itu. Untuk memperlancar hal ini, + saat pertama Anda memanggil {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase + getWritableDatabase()}, metode ini memanggil metode + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()} secara otomatis. +</p> +<p> + Dua cuplikan berikut memperagakan interaksi antara + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()} dan + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()}. Cuplikan pertama adalah implementasi + {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}: +</p> +<pre class="prettyprint"> +public class ExampleProvider extends ContentProvider + + /* + * Defines a handle to the database helper object. The MainDatabaseHelper class is defined + * in a following snippet. + */ + private MainDatabaseHelper mOpenHelper; + + // Defines the database name + private static final String DBNAME = "mydb"; + + // Holds the database object + private SQLiteDatabase db; + + public boolean onCreate() { + + /* + * Creates a new helper object. This method always returns quickly. + * Notice that the database itself isn't created or opened + * until SQLiteOpenHelper.getWritableDatabase is called + */ + mOpenHelper = new MainDatabaseHelper( + getContext(), // the application context + DBNAME, // the name of the database) + null, // uses the default SQLite cursor + 1 // the version number + ); + + return true; + } + + ... + + // Implements the provider's insert method + public Cursor insert(Uri uri, ContentValues values) { + // Insert code here to determine which table to open, handle error-checking, and so forth + + ... + + /* + * Gets a writeable database. This will trigger its creation if it doesn't already exist. + * + */ + db = mOpenHelper.getWritableDatabase(); + } +} +</pre> +<p> + Cuplikan berikutnya adalah implementasi + {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase) + SQLiteOpenHelper.onCreate()}, yang menyertakan kelas helper: +</p> +<pre class="prettyprint"> +... +// A string that defines the SQL statement for creating a table +private static final String SQL_CREATE_MAIN = "CREATE TABLE " + + "main " + // Table's name + "(" + // The columns in the table + " _ID INTEGER PRIMARY KEY, " + + " WORD TEXT" + " FREQUENCY INTEGER " + + " LOCALE TEXT )"; +... +/** + * Helper class that actually creates and manages the provider's underlying data repository. + */ +protected static final class MainDatabaseHelper extends SQLiteOpenHelper { + + /* + * Instantiates an open helper for the provider's SQLite data repository + * Do not do database creation and upgrade here. + */ + MainDatabaseHelper(Context context) { + super(context, DBNAME, null, 1); + } + + /* + * Creates the data repository. This is called when the provider attempts to open the + * repository and SQLite reports that it doesn't exist. + */ + public void onCreate(SQLiteDatabase db) { + + // Creates the main table + db.execSQL(SQL_CREATE_MAIN); + } +} +</pre> + + +<!-- Implementing ContentProvider MIME Types --> +<h2 id="MIMETypes">Mengimplementasikan Tipe MIME Penyedia Konten</h2> +<p> + Kelas {@link android.content.ContentProvider} memiliki dua metode untuk menghasilkan tipe-tipe MIME: +</p> +<dl> + <dt> + {@link android.content.ContentProvider#getType(Uri) getType()} + </dt> + <dd> + Salah satu metode wajib yang harus Anda implementasikan untuk setiap penyedia. + </dd> + <dt> + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} + </dt> + <dd> + Sebuah metode yang diharapkan untuk Anda implementasikan jika penyedia Anda menawarkan file. + </dd> +</dl> +<h3 id="TableMIMETypes">Tipe MIME untuk tabel</h3> +<p> + Metode {@link android.content.ContentProvider#getType(Uri) getType()} mengembalikan + {@link java.lang.String} dengan format MIME yang menjelaskan tipe data yang dikembalikan oleh + argumen URI konten. Argumen {@link android.net.Uri} bisa berupa pola, bukannya URI tertentu; + dalam hal ini, Anda harus mengembalikan tipe data terkait URI konten yang cocok dengan + polanya. +</p> +<p> + Untuk tipe data umum misalnya teks, HTML, atau JPEG, + {@link android.content.ContentProvider#getType(Uri) getType()} harus mengembalikan + tipe MIME standar untuk data itu. Daftar lengkap tipe standar ini tersedia di situs web + <a href="http://www.iana.org/assignments/media-types/index.htm">IANA MIME Media Types</a>. + +</p> +<p> + Untuk URI konten yang menunjuk ke baris atau baris-baris data tabel, + {@link android.content.ContentProvider#getType(Uri) getType()} harus mengembalikan + tipe MIME dalam format MIME khusus vendor Android: +</p> +<ul> + <li> + Bagian tipe: <code>vnd</code> + </li> + <li> + Bagian subtipe: + <ul> + <li> + Jika pola URI adalah untuk satu baris: <code>android.cursor.<strong>item</strong>/</code> + </li> + <li> + Jika pola URI adalah untuk lebih dari satu baris: <code>android.cursor.<strong>dir</strong>/</code> + </li> + </ul> + </li> + <li> + Bagian khusus penyedia: <code>vnd.<name></code>.<code><type></code> + <p> + Anda menyediakan <code><name></code> dan <code><type></code>. + Nilai <code><name></code> harus unik secara global, + dan nilai <code><type></code> harus unik bagi pola URI + yang sesuai. Pilihan tepat untuk <code><name></code> adalah nama perusahaan Anda atau + sebagian dari nama paket Android aplikasi Anda. Pilihan tepat untuk + <code><type></code> adalah string yang mengidentifikasi tabel yang terkait dengan + URI. + </p> + + </li> +</ul> +<p> + Misalnya, jika otoritas penyedia adalah + <code>com.example.app.provider</code>, dan penyedia mengekspos tabel bernama + <code>table1</code>, tipe MIME untuk beberapa baris dalam <code>table1</code> adalah: +</p> +<pre> +vnd.android.cursor.<strong>dir</strong>/vnd.com.example.provider.table1 +</pre> +<p> + Untuk satu baris <code>table1</code>, tipe MIME adalah: +</p> +<pre> +vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1 +</pre> +<h3 id="FileMIMETypes">Tipe MIME untuk file</h3> +<p> + Jika penyedia Anda menawarkan file, implementasikan + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}. + Metode ini menghasilkan larik {@link java.lang.String} tipe MIME untuk file + yang bisa dikembalikan penyedia Anda untuk URI konten bersangkutan. Anda harus memfilter tipe MIME yang Anda tawarkan dengan argumen filter + tipe MIME, sehingga Anda hanya mengembalikan tipe MIME yang ingin ditangani klien. +</p> +<p> + Misalnya, perhatikan penyedia yang menawarkan gambar foto sebagai file dalam format <code>.jpg</code>, + <code>.png</code>, dan <code>.gif</code>. + Jika aplikasi memanggil {@link android.content.ContentResolver#getStreamTypes(Uri, String) + ContentResolver.getStreamTypes()} dengan string filter <code>image/*</code> (sesuatu yang + merupakan "gambar"), + maka metode {@link android.content.ContentProvider#getStreamTypes(Uri, String) + ContentProvider.getStreamTypes()} harus mengembalikan larik: +</p> +<pre> +{ "image/jpeg", "image/png", "image/gif"} +</pre> +<p> + Jika aplikasi tertarik pada file <code>.jpg</code>, maka aplikasi bisa memanggil + {@link android.content.ContentResolver#getStreamTypes(Uri, String) + ContentResolver.getStreamTypes()} dengan string filter <code>*\/jpeg</code>, dan + {@link android.content.ContentProvider#getStreamTypes(Uri, String) + ContentProvider.getStreamTypes()} harus mengembalikan: +<pre> +{"image/jpeg"} +</pre> +<p> + Jika penyedia Anda tidak menawarkan tipe MIME apa pun yang diminta dalam string filter, + {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()} + harus mengembalikan <code>null</code>. +</p> + + +<!-- Implementing a Contract Class --> +<h2 id="ContractClass">Mengimplementasikan Kelas Kontrak</h2> +<p> + Kelas kontrak adalah kelas <code>public final</code> yang berisi definisi konstanta untuk URI, nama kolom, tipe MIME, dan +metadata lain yang melekat ke penyedia. Kelas + membentuk sebuah kontrak antara penyedia dan aplikasi lain dengan memastikan bahwa penyedia + bisa diakses dengan benar sekalipun ada perubahan pada nilai URI sesungguhnya, nama kolom, + dan seterusnya. +</p> +<p> + Kelas kontrak juga membantu pengembang karena kelas ini biasanya memiliki nama-nama simbolik untuk konstantanya, + sehingga memperkecil kemungkinan pengembang menggunakan nilai yang salah untuk nama kolom atau URI. Karena berupa + kelas, kelas ini bisa berisi dokumentasi Javadoc. Lingkungan pengembangan terpadu (IDE) seperti + Eclipse secara otomatis bisa melengkapi nama-nama konstanta dari kelas kontrak dan menampilkan Javadoc untuk + konstanta. +</p> +<p> + Pengembang tidak bisa mengakses file kelas milik kelas kontrak dari aplikasi Anda, namun bisa + mengompilasinya secara statis ke dalam aplikasi mereka dari file <code>.jar</code> yang Anda sediakan. +</p> +<p> + Kelas {@link android.provider.ContactsContract} dan kelas-kelas tersarangnya adalah contoh + kelas kontrak. +</p> +<h2 id="Permissions">Mengimplementasikan Izin Penyedia Konten</h2> +<p> + Izin dan akses untuk semua aspek sistem Android dijelaskan secara detail dalam + topik <a href="{@docRoot}guide/topics/security/security.html">Keamanan dan Izin</a>. + Topik <a href="{@docRoot}guide/topics/data/data-storage.html">Penyimpanan Data</a> juga + menjelaskan keamanan dan izin terkait dengan berbagai tipe penyimpanan. + Singkatnya, poin-poin pentingnya adalah: +</p> +<ul> + <li> + Secara default, file data yang disimpan pada penyimpanan internal perangkat bersifat privat bagi + aplikasi dan penyedia Anda. + </li> + <li> + Database {@link android.database.sqlite.SQLiteDatabase} yang Anda buat bersifat privat bagi + aplikasi dan penyedia Anda. + </li> + <li> + Secara default, file data yang Anda simpan ke penyimpanan eksternal bersifat <em>publik</em> dan + <em>bisa dibaca secara global</em>. Anda tidak bisa menggunakan penyedia konten untuk membatasi akses ke file dalam + penyimpanan eksternal, karena aplikasi lain bisa menggunakan panggilan API untuk membaca dan menulis ke file tersebut. + </li> + <li> + Panggilan metode untuk membuka atau membuat file atau database SQLite pada + penyimpanan internal perangkat Anda berpotensi memberikan akses baca maupun tulis ke semua aplikasi lain. Jika Anda + menggunakan file atau database internal sebagai repository penyedia, dan Anda memberinya + akses "world-readable" (bisa dibaca secara global) atau "world-writeable" (bisa ditulis secara global), izin yang Anda atur untuk penyedia dalam + manifesnya tidak akan melindungi data Anda. Akses default untuk file dan database dalam + penyimpanan internal adalah "privat", dan untuk repository penyedia, tidak boleh Anda ubah. + </li> +</ul> +<p> + Jika Anda ingin menggunakan izin penyedia konten untuk mengontrol akses ke data Anda, maka Anda harus + menyimpan data Anda dalam file internal, database SQLite, atau "cloud" (misalnya, + di server jauh), dan Anda harus membuat file dan database tetap privat bagi aplikasi Anda. +</p> +<h3>Mengimplementasikan izin</h3> +<p> + Semua aplikasi bisa membaca dari atau menulis ke penyedia Anda, sekalipun data yang mendasari adalah + privat, karena secara default penyedia Anda tidak mengatur izin. Untuk mengubahnya, + atur izin untuk penyedia dalam file manifes, dengan menggunakan atribut atau elemen anak + dari elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. Anda bisa mengatur izin yang berlaku pada seluruh penyedia, + atau pada tabel tertentu, atau bahkan pada record tertentu, atau ketiganya. +</p> +<p> + Anda mendefinisikan izin untuk penyedia dengan satu atau beberapa elemen + <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"> + <permission></a></code> dalam file manifes. Untuk membuat + izin unik bagi penyedia, gunakan scoping (pengaturan lingkup) bergaya Java untuk + atribut <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#nm"> + android:name</a></code>. Misalnya, beri nama izin membaca dengan + <code>com.example.app.provider.permission.READ_PROVIDER</code>. + +</p> +<p> + Daftar berikut menjelaskan lingkup penyedia izin, mulai dengan + izin yang berlaku pada seluruh penyedia kemudian menjadi semakin sempit. + Izin yang lebih sempit akan didahulukan daripada izin yang berlingkup lebih luas: +</p> +<dl> + <dt> + Izin baca-tulis tunggal tingkat penyedia + </dt> + <dd> + Suatu izin yang mengontrol akses baca-tulis bagi seluruh penyedia, ditetapkan + dengan atribut <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code> dari + elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. + </dd> + <dt> + Izin baca-tulis terpisah tingkat penyedia + </dt> + <dd> + Satu izin baca dan satu izin tulis untuk seluruh penyedia. Anda menetapkan keduanya + dengan atribut <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> + android:readPermission</a></code> dan + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> + android:writePermission</a></code> dari elemen + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. Kedua izin akan didahulukan daripada izin yang diharuskan oleh + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code>. + </dd> + <dt> + Izin tingkat path + </dt> + <dd> + Izin baca, tulis, atau baca/tulis untuk URI konten dalam penyedia Anda. Anda menetapkan + tiap URI yang ingin dikontrol dengan elemen anak + <code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html"> + <path-permission></a></code> dari + elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. Untuk setiap URI konten yang ditetapkan, Anda bisa menetapkan + satu izin baca/tulis, satu izin baca, atau satu izin tulis, atau ketiganya. Izin baca dan + tulis akan didahulukan daripada izin baca/tulis. Juga, + izin tingkat path akan didahulukan daripada izin tingkat penyedia. + </dd> + <dt> + Izin sementara + </dt> + <dd> + Tingkat izin yang memberikan akses sementara ke aplikasi, sekalipun aplikasi itu + tidak memiliki izin yang biasanya diminta. Fitur akses + sementara mengurangi jumlah izin yang harus diminta aplikasi dalam + manifesnya. Bila Anda mengaktifkan izin sementara, satu-satunya aplikasi yang memerlukan + izin "permanen" untuk penyedia adalah aplikasi yang mengakses terus-menerus semua + data Anda. + <p> + Perhatikan izin yang Anda perlukan untuk mengimplementasikan penyedia dan aplikasi email, bila Anda + ingin memperbolehkan aplikasi penampil gambar dari luar menampilkan lampiran foto dari + penyedia Anda. Untuk memberikan akses yang diperlukan kepada penampil gambar tanpa mengharuskan izin, + siapkan izin sementara untuk URI konten bagi foto. Desainlah aplikasi email Anda agar + bila pengguna ingin menampilkan foto, aplikasi itu akan mengirim intent berisi + URI konten foto dan flag izin ke penampil gambar. Penampil gambar nanti bisa + melakukan query penyedia email untuk mengambil foto, sekalipun penampil itu tidak + memiliki izin baca normal untuk penyedia Anda. + </p> + <p> + Untuk mengaktifkan izin sementara, atur atribut + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermissions</a></code> dari + elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>, atau tambahkan satu atau beberapa elemen anak + <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> + <grant-uri-permission></a></code> ke + elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> Anda. Jika menggunakan izin sementara, Anda harus memanggil + {@link android.content.Context#revokeUriPermission(Uri, int) + Context.revokeUriPermission()} kapan saja Anda menghilangkan dukungan untuk URI konten dari + penyedia, dan URI konten dikaitkan dengan izin sementara. + </p> + <p> + Nilai atribut menentukan seberapa banyak penyedia Anda yang dijadikan bisa diakses. + Jika atribut diatur ke <code>true</code>, maka sistem akan memberikan + izin sementara kepada seluruh penyedia, dengan mengesampingkan izin lain yang diharuskan + oleh izin tingkat penyedia atau tingkat path. + </p> + <p> + Jika flag ini diatur ke <code>false</code>, maka Anda harus menambahkan elemen-elemen anak + <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> + <grant-uri-permission></a></code> ke + elemen <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code> Anda. Tiap elemen anak menetapkan URI konten atau + URI yang telah diberi akses sementara. + </p> + <p> + Untuk mendelegasikan akses sementara ke sebuah aplikasi, intent harus berisi + {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} atau flag + {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}, atau keduanya. Keduanya + diatur dengan metode {@link android.content.Intent#setFlags(int) setFlags()}. + </p> + <p> + Jika atribut <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermissions</a></code> tidak ada, atribut ini diasumsikan sebagai + <code>false</code>. + </p> + </dd> +</dl> + + + +<!-- The Provider Element --> +<h2 id="ProviderElement">Elemen <provider></h2> +<p> + Seperti halnya komponen {@link android.app.Activity} dan {@link android.app.Service}, + subkelas {@link android.content.ContentProvider} + harus didefinisikan dalam file manifes untuk aplikasinya, dengan menggunakan elemen + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. Sistem Android mendapatkan informasi berikut dari + elemen: +<dl> + <dt> + Otoritas + (<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code + android:authorities}</a>) + </dt> + <dd> + Nama-nama simbolik yang mengidentifikasi seluruh penyedia dalam sistem. Atribut + ini dijelaskan lebih detail di bagian + <a href="#ContentURI">Mendesain URI Konten</a>. + </dd> + <dt> + Nama kelas penyedia + (<code> +<a href="{@docRoot}guide/topics/manifest/provider-element.html#nm">android:name</a> + </code>) + </dt> + <dd> + Kelas yang mengimplementasikan {@link android.content.ContentProvider}. Kelas ini + dijelaskan lebih detail di bagian + <a href="#ContentProvider">Mengimplementasikan Kelas ContentProvider</a>. + </dd> + <dt> + Izin + </dt> + <dd> + Atribut-atribut yang menetapkan izin yang harus dimiliki aplikasi lain untuk mengakses + data penyedia: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> + android:grantUriPermssions</a></code>: Flag izin sementara. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn"> + android:permission</a></code>: Izin baca/tulis tunggal untuk tingkat penyedia. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn"> + android:readPermission</a></code>: Izin baca untuk tingkat penyedia. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn"> + android:writePermission</a></code>: Izin tulis untuk tingkat penyedia. + </li> + </ul> + <p> + Izin dan atribut-atribut yang sesuai dijelaskan lebih detail + di bagian + <a href="#Permissions">Mengimplementasikan Izin Penyedia Konten</a>. + </p> + </dd> + <dt> + Atribut-atribut startup dan kontrol + </dt> + <dd> + Atribut-atribut ini menentukan cara dan waktu sistem Android memulai penyedia, + karakteristik proses penyedia, dan pengaturan runtime lainnya: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#enabled"> + android:enabled</a></code>: Flag yang memperbolehkan sistem untuk memulai penyedia. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#exported"> + android:exported</a></code>: Flag yang memperbolehkan aplikasi lain untuk menggunakan penyedia ini. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#init"> + android:initOrder</a></code>: Urutan yang digunakan untuk memulai penyedia ini, + relatif terhadap penyedia lain dalam proses yang sama. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#multi"> + android:multiProcess</a></code>: Flag yang memperbolehkan sistem untuk memulai penyedia + dalam proses yang sama dengan proses klien pemanggil. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#proc"> + android:process</a></code>: Nama proses tempat penyedia harus + berjalan. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#sync"> + android:syncable</a></code>: Flag yang menunjukkan bahwa data penyedia harus + disinkronkan dengan data di server. + </li> + </ul> + <p> + Atribut-atribut ini didokumentasikan dengan lengkap dalam topik panduan pengembang untuk elemen + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. + + </p> + </dd> + <dt> + Atribut-atribut informatif + </dt> + <dd> + Ikon dan label opsional untuk penyedia: + <ul> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#icon"> + android:icon</a></code>: Sumber daya drawable, berisi ikon untuk penyedia. + Ikon ini muncul di sebelah label penyedia dalam daftar aplikasi dalam menu + <em>Settings</em> > <em>Apps</em> > <em>All</em>. + </li> + <li> + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#label"> + android:label</a></code>: Label informatif yang menjelaskan penyedia atau + datanya, atau keduanya. Label ini muncul dalam daftar aplikasi di + <em>Settings</em> > <em>Apps</em> > <em>All</em>. + </li> + </ul> + <p> + Atribut-atribut ini didokumentasikan dengan lengkap dalam topik panduan pengembang untuk elemen + <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"> + <provider></a></code>. + </p> + </dd> +</dl> + +<!-- Intent Access --> +<h2 id="Intents">Intent dan Akses Data</h2> +<p> + Aplikasi bisa mengakses penyedia konten secara tidak langsung dengan sebuah {@link android.content.Intent}. + Aplikasi tidak memanggil satu pun dari metode-metode {@link android.content.ContentResolver} atau + {@link android.content.ContentProvider}. Sebagai gantinya, aplikasi mengirim intent yang memulai aktivitas, + yang sering kali merupakan bagian dari aplikasi penyedia sendiri. Aktivitas tujuan bertugas + mengambil dan menampilkan data dalam UI-nya. Bergantung pada tindakan dalam intent, + aktivitas tujuan juga bisa meminta pengguna untuk membuat modifikasi pada data penyedia. + Intent juga bisa berisi data "ekstra" yang menampilkan aktivitas tujuan + dalam UI; pengguna nanti memiliki pilihan untuk mengubah data ini sebelum menggunakannya untuk mengubah + data di penyedia. +</p> +<p> + +</p> +<p> + Anda mungkin perlu menggunakan akses intent guna membantu memastikan integritas data. Penyedia Anda mungkin bergantung + pada data yang disisipkan, diperbarui, dan dihapusnya sesuai dengan logika bisnis yang didefinisikan dengan ketat. Jika + demikian halnya, memperbolehkan aplikasi lain mengubah data Anda secara langsung bisa menyebabkan + data yang tidak sah. Jika Anda ingin pengembang menggunakan akses intent, pastikan untuk mendokumentasikannya secara saksama. + Jelaskan kepada mereka alasan akses intent yang menggunakan UI aplikasi Anda sendiri adalah lebih baik daripada mencoba + memodifikasi data dengan kode mereka. +</p> +<p> + Menangani sebuah intent masuk yang ingin memodifikasi data penyedia Anda tidak berbeda dengan + menangani intent lainnya. Anda bisa mengetahui selengkapnya tentang penggunaan intent dengan membaca topik + <a href="{@docRoot}guide/components/intents-filters.html">Intent dan Filter Intent</a>. +</p> diff --git a/docs/html-intl/intl/in/guide/topics/providers/content-providers.jd b/docs/html-intl/intl/in/guide/topics/providers/content-providers.jd new file mode 100644 index 000000000000..fc6f12b6f569 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/content-providers.jd @@ -0,0 +1,108 @@ +page.title=Penyedia konten +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + + +<!-- In this document --> +<h2>Topik</h2> +<ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Membuat Penyedia Konten</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Penyedia Kalender</a> + </li> + <li> + <a href="{@docRoot}guide/topics/providers/contacts-provider.html">Penyedia Kontak</a> + </li> +</ol> + + <!-- Related Samples --> +<h2>Contoh-Contoh Terkait</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/ContactManager/index.html"> + Aplikasi Contact Manager</a> + </li> + <li> + <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html"> + "Kursor (Orang)" + </a> + </li> + <li> + <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html"> + "Kursor (Telepon)"</a> + </li> + <li> + <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html"> + Contoh Adaptor Sinkronisasi</a> + </li> + </ol> +</div> +</div> +<p> + Penyedia konten mengelola akses ke set data terstruktur. Penyedia ini membungkus + data, dan menyediakan mekanisme untuk mendefinisikan keamanan data. Penyedia konten adalah antarmuka + standar yang menghubungkan data dalam satu proses dengan kode yang berjalan dalam proses lain. +</p> +<p> + Bila Anda ingin mengakses data di penyedia konten, Anda menggunakan + {@link android.content.ContentResolver} objek dalam + {@link android.content.Context} aplikasi untuk berkomunikasi dengan penyedia sebagai klien. + Objek {@link android.content.ContentResolver} berkomunikasi dengan objek penyedia, yakni + instance kelas yang mengimplementasikan {@link android.content.ContentProvider}. Objek penyedia + menerima permintaan data dari klien, melakukan tindakan yang diminta, dan + mengembalikan hasilnya. +</p> +<p> + Anda tidak perlu mengembangkan penyedia sendiri jika tidak bermaksud untuk berbagi data dengan + aplikasi lain. Akan tetapi, Anda memerlukan penyedia buatan sendiri untuk menyediakan saran pencarian custom + dalam aplikasi Anda sendiri. Anda juga memerlukan penyedia sendiri jika ingin menyalin dan +menempelkan data atau file yang kompleks dari aplikasi Anda ke aplikasi lain. +</p> +<p> + Android sendiri berisi penyedia konten yang mengelola data seperti informasi audio, video, gambar, dan + kontak pribadi. Anda bisa melihat sebagian informasi ini tercantum dalam dokumentasi + acuan untuk paket + <code><a href="{@docRoot}reference/android/provider/package-summary.html">android.provider</a> + </code>. Dengan beberapa batasan, semua penyedia ini bisa diakses oleh aplikasi Android + apa saja. +</p><p> + Topik-topik berikut menjelaskan penyedia konten secara lebih detail: +</p> +<dl> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten</a></strong> + </dt> + <dd> + Cara mengakses data di penyedia konten bila data disusun dalam tabel. + </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/content-provider-creating.html"> + Membuat Penyedia Konten</a></strong> + </dt> + <dd> + Cara membuat penyedia konten sendiri. + </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/calendar-provider.html"> + Penyedia Kalender</a></strong> + </dt> + <dd> + Cara mengakses Penyedia Kalender yang merupakan bagian dari platform Android. + </dd> + <dt> + <strong><a href="{@docRoot}guide/topics/providers/contacts-provider.html"> + Penyedia Kontak</a></strong> + </dt> + <dd> + Cara mengakses Penyedia Kontak yang merupakan bagian dari platform Android. + </dd> +</dl> diff --git a/docs/html-intl/intl/in/guide/topics/providers/document-provider.jd b/docs/html-intl/intl/in/guide/topics/providers/document-provider.jd new file mode 100644 index 000000000000..c066e85b283d --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/providers/document-provider.jd @@ -0,0 +1,916 @@ +page.title=Storage Access Framework +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini + <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle"> + <span class="more">tampilkan maksimal</span> + <span class="less" style="display:none">tampilkan minimal</span></a></h2> +<ol id="toc44" class="hide-nested"> + <li> + <a href="#overview">Ikhtisar</a> + </li> + <li> + <a href="#flow">Arus Kontrol</a> + </li> + <li> + <a href="#client">Menulis Aplikasi Klien</a> + <ol> + <li><a href="#search">Mencari dokumen</a></li> + <li><a href="#process">Memproses hasil</a></li> + <li><a href="#metadata">Memeriksa metadata dokumen</a></li> + <li><a href="#open">Membuka dokumen</a></li> + <li><a href="#create">Membuat dokumen baru</a></li> + <li><a href="#delete">Menghapus dokumen</a></li> + <li><a href="#edit">Mengedit dokumen</a></li> + <li><a href="#permissions">Mempertahankan izin</a></li> + </ol> + </li> + <li><a href="#custom">Menulis Penyedia Dokumen Custom</a> + <ol> + <li><a href="#manifest">Manifes</a></li> + <li><a href="#contract">Kontrak</a></li> + <li><a href="#subclass">Subkelas DocumentsProvider</a></li> + <li><a href="#security">Keamanan</a></li> + </ol> + </li> + +</ol> +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.provider.DocumentsProvider}</li> + <li>{@link android.provider.DocumentsContract}</li> +</ol> + +<h2>Video</h2> + +<ol> + <li><a href="http://www.youtube.com/watch?v=zxHVeXbK1P4"> +DevBytes: Android 4.4 Storage Access Framework: Penyedia</a></li> + <li><a href="http://www.youtube.com/watch?v=UFj9AEz0DHQ"> +DevBytes: Android 4.4 Storage Access Framework: Klien</a></li> +</ol> + + +<h2>Contoh Kode</h2> + +<ol> + <li><a href="{@docRoot}samples/StorageProvider/index.html"> +Penyedia Penyimpanan</a></li> + <li><a href="{@docRoot}samples/StorageClient/index.html"> +Klien Penyimpanan</a></li> +</ol> + +<h2>Lihat Juga</h2> +<ol> + <li> + <a href="{@docRoot}guide/topics/providers/content-provider-basics.html"> + Dasar-Dasar Penyedia Konten + </a> + </li> +</ol> + +</div> +</div> + + +<p>Android 4.4 (API level 19) memperkenalkan Storage Access Framework (SAF, Kerangka Kerja Akses Penyimpanan). SAF + memudahkan pengguna menyusuri dan membuka dokumen, gambar, dan file lainnya +di semua penyedia penyimpanan dokumen pilihannya. UI standar yang mudah digunakan +memungkinkan pengguna menyusuri file dan mengakses yang terbaru dengan cara konsisten di antara berbagai aplikasi dan penyedia.</p> + +<p>Layanan penyimpanan cloud atau lokal bisa dilibatkan dalam ekosistem ini dengan mengimplementasikan sebuah +{@link android.provider.DocumentsProvider} yang membungkus layanannya. Aplikasi klien +yang memerlukan akses ke dokumen sebuah penyedia bisa berintegrasi dengan SAF cukup dengan beberapa +baris kode.</p> + +<p>SAF terdiri dari berikut ini:</p> + +<ul> +<li><strong>Penyedia dokumen</strong>—Penyedia konten yang memungkinkan +layanan penyimpanan (seperti Google Drive) untuk menampilkan file yang dikelolanya. Penyedia dokumen +diimplementasikan sebagai subkelas dari kelas {@link android.provider.DocumentsProvider}. +Skema penyedia dokumen berdasarkan hierarki file biasa, +walaupun cara penyedia dokumen Anda secara fisik menyimpan data adalah terserah Anda. +Platform Android terdiri dari beberapa penyedia dokumen bawaan, seperti +Downloads, Images, dan Videos.</li> + +<li><strong>Aplikasi klien</strong>—Aplikasi custom yang memanggil intent +{@link android.content.Intent#ACTION_OPEN_DOCUMENT} dan/atau +{@link android.content.Intent#ACTION_CREATE_DOCUMENT} dan menerima +file yang dihasilkan penyedia dokumen.</li> + +<li><strong>Picker</strong>—UI sistem yang memungkinkan pengguna mengakses dokumen dari semua +penyedia dokumen yang memenuhi kriteria pencarian aplikasi klien.</li> +</ul> + +<p>Beberapa fitur yang disediakan oleh SAF adalah sebagai berikut:</p> +<ul> +<li>Memungkinkan pengguna menyusuri konten dari semua penyedia dokumen, bukan hanya satu aplikasi.</li> +<li>Memungkinkan aplikasi Anda memiliki akses jangka panjang dan tetap ke + dokumen yang dimiliki oleh penyedia dokumen. Melalui akses ini pengguna bisa menambah, mengedit, + menyimpan, dan menghapus file pada penyedia.</li> +<li>Mendukung banyak akun pengguna dan akar jangka pendek seperti penyedia penyimpanan +USB, yang hanya muncul jika drive itu dipasang. </li> +</ul> + +<h2 id ="overview">Ikhtisar</h2> + +<p>SAF berpusat di seputar penyedia konten yang merupakan +subkelas dari kelas {@link android.provider.DocumentsProvider}. Dalam <em>penyedia dokumen</em>, data +distrukturkan sebagai hierarki file biasa:</p> +<p><img src="{@docRoot}images/providers/storage_datamodel.png" alt="data model" /></p> +<p class="img-caption"><strong>Gambar 1.</strong> Model data penyedia dokumen. Root menunjuk ke satu Document, +yang nanti memulai pemekaran seluruh pohon.</p> + +<p>Perhatikan yang berikut ini:</p> +<ul> + +<li>Setiap penyedia dokumen melaporkan satu atau beberapa +"akar" yang merupakan titik awal penyusuran pohon dokumen. +Masing-masing akar memiliki sebuah {@link android.provider.DocumentsContract.Root#COLUMN_ROOT_ID} yang unik, +dan menunjuk ke satu dokumen (satu direktori) +yang mewakili konten di bawah akar itu. +Akar sengaja dibuat dinamis untuk mendukung kasus penggunaan seperti multiakun, +perangkat penyimpanan USB jangka pendek, atau masuk/keluar pengguna.</li> + +<li>Di bawah tiap akar terdapat satu dokumen. Dokumen itu menunjuk ke dokumen-dokumen 1-ke-<em>N</em>, +yang nanti masing-masing bisa menunjuk ke dokumen 1-ke-<em>N</em>. </li> + +<li>Tiap backend penyimpanan memunculkan +masing-masing file dan direktori dengan mengacunya lewat sebuah +{@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} yang unik. +ID dokumen harus unik dan tidak berubah setelah dibuat, karena ID ini digunakan untuk +URI persisten yang diberikan pada saat reboot perangkat.</li> + + +<li>Dokumen bisa berupa file yang bisa dibuka (dengan tipe MIME tertentu), atau +direktori yang berisi dokumen tambahan (dengan tipe MIME +{@link android.provider.DocumentsContract.Document#MIME_TYPE_DIR}).</li> + +<li>Tiap dokumen bisa mempunyai kemampuan berbeda, sebagaimana yang dijelaskan oleh +{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS COLUMN_FLAGS}. +Misalnya, {@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_WRITE}, +{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE}, dan +{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL}. +{@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} yang sama bisa +dimasukkan dalam beberapa direktori.</li> +</ul> + +<h2 id="flow">Arus Kontrol</h2> +<p>Seperti dinyatakan di atas, model data penyedia dokumen dibuat berdasarkan hierarki file +biasa. Akan tetapi, Anda bisa menyimpan secara fisik data dengan cara apa pun yang disukai, +selama data bisa diakses melalui API {@link android.provider.DocumentsProvider}. Misalnya, Anda +bisa menggunakan penyimpanan cloud berbasis tag untuk data Anda.</p> + +<p>Gambar 2 menampilkan contoh cara aplikasi foto bisa menggunakan SAF +untuk mengakses data tersimpan:</p> +<p><img src="{@docRoot}images/providers/storage_dataflow.png" alt="app" /></p> + +<p class="img-caption"><strong>Gambar 2.</strong> Arus Storage Access Framework</p> + +<p>Perhatikan yang berikut ini:</p> +<ul> + +<li>Di SAF, penyedia dan klien tidak berinteraksi +secara langsung. Klien meminta izin untuk berinteraksi +dengan file (yakni, membaca, mengedit, membuat, atau menghapus file).</li> + +<li>Interaksi dimulai bila sebuah aplikasi (dalam contoh ini adalah aplikasi foto) mengeluarkan intent +{@link android.content.Intent#ACTION_OPEN_DOCUMENT} atau {@link android.content.Intent#ACTION_CREATE_DOCUMENT}. Intent bisa berisi filter +untuk mempersempit kriteria—misalnya, "beri saya semua file yang bisa dibuka +yang memiliki tipe MIME 'gambar'".</li> + +<li>Setelah intent dibuat, picker sistem akan pergi ke setiap penyedia yang terdaftar +dan menunjukkan kepada pengguna akar konten yang cocok.</li> + +<li>Picker memberi pengguna antarmuka standar untuk mengakses dokumen, +walaupun penyedia dokumen dasar bisa sangat berbeda. Misalnya, gambar 2 +menunjukkan penyedia Google Drive, penyedia USB, dan penyedia cloud.</li> +</ul> + +<p>Gambar 3 menunjukkan picker yang di digunakan pengguna mencari gambar telah memilih +akun Google Drive:</p> + +<p><img src="{@docRoot}images/providers/storage_picker.png" width="340" alt="picker" style="border:2px solid #ddd" /></p> + +<p class="img-caption"><strong>Gambar 3.</strong> Picker</p> + +<p>Bila pengguna memilih Google Drive, gambar-gambar akan ditampilkan, seperti yang ditampilkan dalam +gambar 4. Dari titik itu, pengguna bisa berinteraksi dengan gambar dengan cara apa pun +yang didukung oleh penyedia dan aplikasi klien. + +<p><img src="{@docRoot}images/providers/storage_photos.png" width="340" alt="picker" style="border:2px solid #ddd" /></p> + +<p class="img-caption"><strong>Gambar 4.</strong> Gambar</p> + +<h2 id="client">Menulis Aplikasi Klien</h2> + +<p>Pada Android 4.3 dan yang lebih rendah, jika Anda ingin aplikasi mengambil file dari +aplikasi lain, aplikasi Anda harus memanggil intent seperti {@link android.content.Intent#ACTION_PICK} +atau {@link android.content.Intent#ACTION_GET_CONTENT}. Pengguna nanti harus memilih +satu aplikasi yang akan digunakan untuk mengambil file dan aplikasi yang dipilih harus menyediakan antarmuka pengguna +bagi untuk menyusuri dan mengambil dari file yang tersedia. </p> + +<p>Pada Android 4.4 dan yang lebih tinggi, Anda mempunyai opsi tambahan dalam menggunakan intent +{@link android.content.Intent#ACTION_OPEN_DOCUMENT}, +yang menampilkan UI picker yang dikontrol oleh sistem yang memungkinkan pengguna +menyusuri semua file yang disediakan aplikasi lain. Dari satu UI ini, pengguna +bisa mengambil file dari aplikasi apa saja yang didukung.</p> + +<p>{@link android.content.Intent#ACTION_OPEN_DOCUMENT} +tidak dimaksudkan untuk menjadi pengganti {@link android.content.Intent#ACTION_GET_CONTENT}. +Yang harus Anda gunakan bergantung pada kebutuhan aplikasi:</p> + +<ul> +<li>Gunakan {@link android.content.Intent#ACTION_GET_CONTENT} jika Anda ingin aplikasi +cuma membaca/mengimpor data. Dengan pendekatan ini, aplikasi akan mengimpor salinan data, +misalnya file gambar.</li> + +<li>Gunakan {@link android.content.Intent#ACTION_OPEN_DOCUMENT} jika Anda ingin aplikasi +memiliki akses jangka panjang dan jangka pendek ke dokumen yang dimiliki oleh penyedia +dokumen. Contohnya adalah aplikasi pengeditan foto yang memungkinkan pengguna mengedit +gambar yang tersimpan dalam penyedia dokumen. </li> + +</ul> + + +<p>Bagian ini menjelaskan cara menulis aplikasi klien berdasarkan +{@link android.content.Intent#ACTION_OPEN_DOCUMENT} dan +intent {@link android.content.Intent#ACTION_CREATE_DOCUMENT}.</p> + + +<h3 id="search">Mencari dokumen</h3> + +<p> +Cuplikan berikut menggunakan {@link android.content.Intent#ACTION_OPEN_DOCUMENT} +untuk mencari penyedia dokumen yang +berisi file gambar:</p> + +<pre>private static final int READ_REQUEST_CODE = 42; +... +/** + * Fires an intent to spin up the "file chooser" UI and select an image. + */ +public void performFileSearch() { + + // ACTION_OPEN_DOCUMENT is the intent to choose a file via the system's file + // browser. + Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); + + // Filter to only show results that can be "opened", such as a + // file (as opposed to a list of contacts or timezones) + intent.addCategory(Intent.CATEGORY_OPENABLE); + + // Filter to show only images, using the image MIME data type. + // If one wanted to search for ogg vorbis files, the type would be "audio/ogg". + // To search for all documents available via installed storage providers, + // it would be "*/*". + intent.setType("image/*"); + + startActivityForResult(intent, READ_REQUEST_CODE); +}</pre> + +<p>Perhatikan yang berikut ini:</p> +<ul> +<li>Saat aplikasi mengeluarkan intent {@link android.content.Intent#ACTION_OPEN_DOCUMENT} +, aplikasi akan menjalankan picker yang menampilkan semua penyedia dokumen yang cocok.</li> + +<li>Menambahkan kategori {@link android.content.Intent#CATEGORY_OPENABLE} ke +intent akan menyaring hasil agar hanya menampilkan dokumen yang bisa dibuka, seperti file gambar.</li> + +<li>Pernyataan {@code intent.setType("image/*")} menyaring lebih jauh agar hanya +menampilkan dokumen yang memiliki tipe data MIME gambar.</li> +</ul> + +<h3 id="results">Memproses Hasil</h3> + +<p>Setelah pengguna memilih dokumen di picker, +{@link android.app.Activity#onActivityResult onActivityResult()} akan dipanggil. +URI yang menunjuk ke dokumen yang dipilih dimasukkan dalam parameter {@code resultData} +. Ekstrak URI dengan {@link android.content.Intent#getData getData()}. +Setelah mendapatkannya, Anda bisa menggunakannya untuk mengambil dokumen yang diinginkan pengguna. Misalnya +:</p> + +<pre>@Override +public void onActivityResult(int requestCode, int resultCode, + Intent resultData) { + + // The ACTION_OPEN_DOCUMENT intent was sent with the request code + // READ_REQUEST_CODE. If the request code seen here doesn't match, it's the + // response to some other intent, and the code below shouldn't run at all. + + if (requestCode == READ_REQUEST_CODE && resultCode == Activity.RESULT_OK) { + // The document selected by the user won't be returned in the intent. + // Instead, a URI to that document will be contained in the return intent + // provided to this method as a parameter. + // Pull that URI using resultData.getData(). + Uri uri = null; + if (resultData != null) { + uri = resultData.getData(); + Log.i(TAG, "Uri: " + uri.toString()); + showImage(uri); + } + } +} +</pre> + +<h3 id="metadata">Memeriksa metadata dokumen</h3> + +<p>Setelah Anda memiliki URI untuk dokumen, Anda akan mendapatkan akses ke metadatanya. Cuplikan +ini memegang metadata sebuah dokumen yang disebutkan oleh URI, dan mencatatnya:</p> + +<pre>public void dumpImageMetaData(Uri uri) { + + // The query, since it only applies to a single document, will only return + // one row. There's no need to filter, sort, or select fields, since we want + // all fields for one document. + Cursor cursor = getActivity().getContentResolver() + .query(uri, null, null, null, null, null); + + try { + // moveToFirst() returns false if the cursor has 0 rows. Very handy for + // "if there's anything to look at, look at it" conditionals. + if (cursor != null && cursor.moveToFirst()) { + + // Note it's called "Display Name". This is + // provider-specific, and might not necessarily be the file name. + String displayName = cursor.getString( + cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)); + Log.i(TAG, "Display Name: " + displayName); + + int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE); + // If the size is unknown, the value stored is null. But since an + // int can't be null in Java, the behavior is implementation-specific, + // which is just a fancy term for "unpredictable". So as + // a rule, check if it's null before assigning to an int. This will + // happen often: The storage API allows for remote files, whose + // size might not be locally known. + String size = null; + if (!cursor.isNull(sizeIndex)) { + // Technically the column stores an int, but cursor.getString() + // will do the conversion automatically. + size = cursor.getString(sizeIndex); + } else { + size = "Unknown"; + } + Log.i(TAG, "Size: " + size); + } + } finally { + cursor.close(); + } +} +</pre> + +<h3 id="open-client">Membuka dokumen</h3> + +<p>Setelah mendapatkan URI dokumen, Anda bisa membuka dokumen atau melakukan apa saja +yang diinginkan padanya.</p> + +<h4>Bitmap</h4> + +<p>Berikut ini adalah contoh cara membuka {@link android.graphics.Bitmap}:</p> + +<pre>private Bitmap getBitmapFromUri(Uri uri) throws IOException { + ParcelFileDescriptor parcelFileDescriptor = + getContentResolver().openFileDescriptor(uri, "r"); + FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor(); + Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor); + parcelFileDescriptor.close(); + return image; +} +</pre> + +<p>Perhatikan bahwa Anda tidak boleh melakukan operasi ini pada thread UI. Lakukan hal ini di latar belakang +, dengan menggunakan {@link android.os.AsyncTask}. Setelah membuka bitmap, Anda +bisa menampilkannya dalam {@link android.widget.ImageView}. +</p> + +<h4>Mendapatkan InputStream</h4> + +<p>Berikut ini adalah contoh cara mendapatkan {@link java.io.InputStream} dari URI. Dalam cuplikan ini +, baris-baris file dibaca ke dalam sebuah string:</p> + +<pre>private String readTextFromUri(Uri uri) throws IOException { + InputStream inputStream = getContentResolver().openInputStream(uri); + BufferedReader reader = new BufferedReader(new InputStreamReader( + inputStream)); + StringBuilder stringBuilder = new StringBuilder(); + String line; + while ((line = reader.readLine()) != null) { + stringBuilder.append(line); + } + fileInputStream.close(); + parcelFileDescriptor.close(); + return stringBuilder.toString(); +} +</pre> + +<h3 id="create">Membuat dokumen baru</h3> + +<p>Aplikasi Anda bisa membuat dokumen baru dalam penyedia dokumen dengan menggunakan intent +{@link android.content.Intent#ACTION_CREATE_DOCUMENT} +. Untuk membuat file, Anda memberikan satu tipe MIME dan satu nama file pada intent, dan +menjalankannya dengan kode permintaan yang unik. Selebihnya akan diurus untuk Anda:</p> + + +<pre> +// Here are some examples of how you might call this method. +// The first parameter is the MIME type, and the second parameter is the name +// of the file you are creating: +// +// createFile("text/plain", "foobar.txt"); +// createFile("image/png", "mypicture.png"); + +// Unique request code. +private static final int WRITE_REQUEST_CODE = 43; +... +private void createFile(String mimeType, String fileName) { + Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT); + + // Filter to only show results that can be "opened", such as + // a file (as opposed to a list of contacts or timezones). + intent.addCategory(Intent.CATEGORY_OPENABLE); + + // Create a file with the requested MIME type. + intent.setType(mimeType); + intent.putExtra(Intent.EXTRA_TITLE, fileName); + startActivityForResult(intent, WRITE_REQUEST_CODE); +} +</pre> + +<p>Setelah membuat dokumen baru, Anda bisa mendapatkan URI-nya dalam +{@link android.app.Activity#onActivityResult onActivityResult()}, sehingga Anda +bisa terus menulis ke dokumen itu.</p> + +<h3 id="delete">Menghapus dokumen</h3> + +<p>Jika Anda memiliki URI dokumen dan +{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS Document.COLUMN_FLAGS} + dokumen berisi +{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE SUPPORTS_DELETE}, +Anda bisa menghapus dokumen tersebut. Misalnya:</p> + +<pre> +DocumentsContract.deleteDocument(getContentResolver(), uri); +</pre> + +<h3 id="edit">Mengedit dokumen</h3> + +<p>Anda bisa menggunakan SAF untuk mengedit dokumen teks langsung di tempatnya. +Cuplikan ini memicu +intent {@link android.content.Intent#ACTION_OPEN_DOCUMENT} dan menggunakan +kategori {@link android.content.Intent#CATEGORY_OPENABLE} untuk menampilkan +dokumen yang bisa dibuka saja. Ini akan menyaring lebih jauh untuk menampilkan file teks saja:</p> + +<pre> +private static final int EDIT_REQUEST_CODE = 44; +/** + * Open a file for writing and append some text to it. + */ + private void editDocument() { + // ACTION_OPEN_DOCUMENT is the intent to choose a file via the system's + // file browser. + Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT); + + // Filter to only show results that can be "opened", such as a + // file (as opposed to a list of contacts or timezones). + intent.addCategory(Intent.CATEGORY_OPENABLE); + + // Filter to show only text files. + intent.setType("text/plain"); + + startActivityForResult(intent, EDIT_REQUEST_CODE); +} +</pre> + +<p>Berikutnya, dari {@link android.app.Activity#onActivityResult onActivityResult()} +(lihat <a href="#results">Memproses hasil</a>) Anda bisa memanggil kode untuk mengedit. +Cuplikan berikut mendapatkan {@link java.io.FileOutputStream} +dari {@link android.content.ContentResolver}. Secara default, snipet menggunakan mode “tulis”. +Inilah praktik terbaik untuk meminta jumlah akses minimum yang Anda perlukan, jadi jangan meminta +baca/tulis jika yang Anda perlukan hanyalah tulis:</p> + +<pre>private void alterDocument(Uri uri) { + try { + ParcelFileDescriptor pfd = getActivity().getContentResolver(). + openFileDescriptor(uri, "w"); + FileOutputStream fileOutputStream = + new FileOutputStream(pfd.getFileDescriptor()); + fileOutputStream.write(("Overwritten by MyCloud at " + + System.currentTimeMillis() + "\n").getBytes()); + // Let the document provider know you're done by closing the stream. + fileOutputStream.close(); + pfd.close(); + } catch (FileNotFoundException e) { + e.printStackTrace(); + } catch (IOException e) { + e.printStackTrace(); + } +}</pre> + +<h3 id="permissions">Mempertahankan izin</h3> + +<p>Bila aplikasi Anda membuka file untuk membaca atau menulis, sistem akan memberi +aplikasi Anda izin URI untuk file itu. Pemberian ini berlaku hingga perangkat pengguna di-restart. +Namun anggaplah aplikasi Anda adalah aplikasi pengeditan gambar, dan Anda ingin pengguna bisa +mengakses 5 gambar terakhir yang dieditnya, langsung dari aplikasi Anda. Jika perangkat pengguna telah +di-restart, maka Anda harus mengirim pengguna kembali ke picker sistem untuk menemukan +file, hal ini jelas tidak ideal.</p> + +<p>Untuk mencegah terjadinya hal ini, Anda bisa mempertahankan izin yang diberikan +sistem ke aplikasi Anda. Secara efektif, aplikasi Anda akan "mengambil" pemberian izin URI yang bisa dipertahankan +yang ditawarkan oleh sistem. Hal ini memberi pengguna akses kontinu ke file +melalui aplikasi Anda, sekalipun perangkat telah di-restart:</p> + + +<pre>final int takeFlags = intent.getFlags() + & (Intent.FLAG_GRANT_READ_URI_PERMISSION + | Intent.FLAG_GRANT_WRITE_URI_PERMISSION); +// Check for the freshest data. +getContentResolver().takePersistableUriPermission(uri, takeFlags);</pre> + +<p>Ada satu langkah akhir. Anda mungkin telah menyimpan +URI terbaru yang diakses aplikasi, namun URI itu mungkin tidak lagi valid,—aplikasi lain +mungkin telah menghapus atau memodifikasi dokumen. Karena itu, Anda harus selalu memanggil +{@code getContentResolver().takePersistableUriPermission()} untuk memeriksa +data terbaru.</p> + +<h2 id="custom">Menulis Penyedia Dokumen Custom</h2> + +<p> +Jika Anda sedang mengembangkan aplikasi yang menyediakan layanan penyimpanan untuk file (misalnya +layanan penyimpanan cloud), Anda bisa menyediakan file melalui +SAF dengan menulis penyedia dokumen custom. Bagian ini menjelaskan +caranya.</p> + + +<h3 id="manifest">Manifes</h3> + +<p>Untuk mengimplementasikan penyedia dokumen custom, tambahkan yang berikut ini ke manifes aplikasi +Anda:</p> +<ul> + +<li>Target berupa API level 19 atau yang lebih tinggi.</li> + +<li>Elemen <code><provider></code> yang mendeklarasikan penyedia penyimpanan custom +Anda. </li> + +<li>Nama penyedia Anda, yaitu nama kelasnya, termasuk nama paket. +Misalnya: <code>com.example.android.storageprovider.MyCloudProvider</code>.</li> + +<li>Nama otoritas Anda, yaitu nama paket Anda (dalam contoh ini, +<code>com.example.android.storageprovider</code>) plus tipe penyedia konten +(<code>documents</code>). Misalnya, {@code com.example.android.storageprovider.documents}.</li> + +<li>Atribut <code>android:exported</code> yang diatur ke <code>"true"</code>. +Anda harus mengekspor penyedia sehingga aplikasi lain bisa membacanya.</li> + +<li>Atribut <code>android:grantUriPermissions</code> yang diatur ke +<code>"true"</code>. Pengaturan ini memungkinkan sistem memberi aplikasi lain akses +ke konten dalam penyedia Anda. Untuk pembahasan cara mempertahankan pemberian bagi +dokumen tertentu, lihat <a href="#permissions">Mempertahankan izin</a>.</li> + +<li>Izin {@code MANAGE_DOCUMENTS}. Secara default, penyedia tersedia +bagi siapa saja. Menambahkan izin ini akan membatasi penyedia Anda pada sistem. +Pembatasan ini penting untuk keamanan.</li> + +<li>Atribut {@code android:enabled} yang diatur ke nilai boolean didefinisikan dalam file +sumber daya. Tujuan atribut ini adalah menonaktifkan penyedia pada perangkat yang menjalankan Android 4.3 atau yang lebih rendah. +Misalnya, {@code android:enabled="@bool/atLeastKitKat"}. Selain +memasukkan atribut ini dalam manifes, Anda perlu melakukan hal-hal berikut: +<ul> +<li>Dalam file sumber daya {@code bool.xml} Anda di bawah {@code res/values/}, tambahkan +baris ini: <pre><bool name="atLeastKitKat">false</bool></pre></li> + +<li>Dalam file sumber daya {@code bool.xml} Anda di bawah {@code res/values-v19/}, tambahkan +baris ini: <pre><bool name="atLeastKitKat">true</bool></pre></li> +</ul></li> + +<li>Sebuah filter intent berisi tindakan +{@code android.content.action.DOCUMENTS_PROVIDER}, agar penyedia Anda +muncul dalam picker saat sistem mencari penyedia.</li> + +</ul> +<p>Berikut ini adalah kutipan contoh manifes berisi penyedia yang:</p> + +<pre><manifest... > + ... + <uses-sdk + android:minSdkVersion="19" + android:targetSdkVersion="19" /> + .... + <provider + android:name="com.example.android.storageprovider.MyCloudProvider" + android:authorities="com.example.android.storageprovider.documents" + android:grantUriPermissions="true" + android:exported="true" + android:permission="android.permission.MANAGE_DOCUMENTS" + android:enabled="@bool/atLeastKitKat"> + <intent-filter> + <action android:name="android.content.action.DOCUMENTS_PROVIDER" /> + </intent-filter> + </provider> + </application> + +</manifest></pre> + +<h4 id="43">Mendukung perangkat yang menjalankan Android 4.3 dan yang lebih rendah</h4> + +<p>Intent +{@link android.content.Intent#ACTION_OPEN_DOCUMENT} hanya tersedia +pada perangkat yang menjalankan Android 4.4 dan yang lebih tinggi. +Jika ingin aplikasi Anda mendukung {@link android.content.Intent#ACTION_GET_CONTENT} +untuk mengakomodasi perangkat yang menjalankan Android 4.3 dan yang lebih rendah, Anda harus +menonaktifkan filter inten {@link android.content.Intent#ACTION_GET_CONTENT} dalam +manifes untuk perangkat yang menjalankan Android 4.4 atau yang lebih tinggi. Penyedia +dokumen dan {@link android.content.Intent#ACTION_GET_CONTENT} harus dianggap +saling eksklusif. Jika Anda mendukung keduanya sekaligus, aplikasi Anda akan +muncul dua kali dalam UI picker sistem, yang menawarkan dua cara mengakses +data tersimpan Anda. Hal ini akan membingungkan pengguna.</p> + +<p>Berikut ini adalah cara yang disarankan untuk menonaktifkan +filter intent {@link android.content.Intent#ACTION_GET_CONTENT} untuk perangkat +yang menjalankan Android versi 4.4 atau yang lebih tinggi:</p> + +<ol> +<li>Dalam file sumber daya {@code bool.xml} Anda di bawah {@code res/values/}, tambahkan +baris ini: <pre><bool name="atMostJellyBeanMR2">true</bool></pre></li> + +<li>Dalam file sumber daya {@code bool.xml} Anda di bawah {@code res/values-v19/}, tambahkan +baris ini: <pre><bool name="atMostJellyBeanMR2">false</bool></pre></li> + +<li>Tambahkan +<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">alias +aktivitas</a> untuk menonaktifkan filter intent {@link android.content.Intent#ACTION_GET_CONTENT} +bagi versi 4.4 (API level 19) dan yang lebih tinggi. Misalnya: + +<pre> +<!-- This activity alias is added so that GET_CONTENT intent-filter + can be disabled for builds on API level 19 and higher. --> +<activity-alias android:name="com.android.example.app.MyPicker" + android:targetActivity="com.android.example.app.MyActivity" + ... + android:enabled="@bool/atMostJellyBeanMR2"> + <intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <category android:name="android.intent.category.OPENABLE" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="image/*" /> + <data android:mimeType="video/*" /> + </intent-filter> +</activity-alias> +</pre> +</li> +</ol> +<h3 id="contract">Kontrak</h3> + +<p>Biasanya bila Anda menulis penyedia konten custom, salah satu tugas adalah +mengimplementasikan kelas kontrak, seperti dijelaskan dalam panduan pengembang +<a href="{@docRoot}guide/topics/providers/content-provider-creating.html#ContractClass"> +Penyedia Konten</a>. Kelas kontrak adalah kelas {@code public final} +yang berisi definisi konstanta untuk URI, nama kolom, tipe MIME, dan +metadata lain yang berkenaan dengan penyedia. SAF +menyediakan kelas-kelas kontrak ini untuk Anda, jadi Anda tidak perlu menulisnya +sendiri:</p> + +<ul> + <li>{@link android.provider.DocumentsContract.Document}</li> + <li>{@link android.provider.DocumentsContract.Root}</li> +</ul> + +<p>Misalnya, berikut ini adalah kolom-kolom yang bisa Anda hasilkan di kursor bila +penyedia dokumen Anda membuat query dokumen atau akar:</p> + +<pre>private static final String[] DEFAULT_ROOT_PROJECTION = + new String[]{Root.COLUMN_ROOT_ID, Root.COLUMN_MIME_TYPES, + Root.COLUMN_FLAGS, Root.COLUMN_ICON, Root.COLUMN_TITLE, + Root.COLUMN_SUMMARY, Root.COLUMN_DOCUMENT_ID, + Root.COLUMN_AVAILABLE_BYTES,}; +private static final String[] DEFAULT_DOCUMENT_PROJECTION = new + String[]{Document.COLUMN_DOCUMENT_ID, Document.COLUMN_MIME_TYPE, + Document.COLUMN_DISPLAY_NAME, Document.COLUMN_LAST_MODIFIED, + Document.COLUMN_FLAGS, Document.COLUMN_SIZE,}; +</pre> + +<h3 id="subclass">Subkelas DocumentsProvider</h3> + +<p>Langkah berikutnya dalam menulis penyedia dokumen custom adalah menjadikan +kelas abstrak sebagai subkelas {@link android.provider.DocumentsProvider}. Setidaknya, Anda perlu + mengimplementasikan metode berikut:</p> + +<ul> +<li>{@link android.provider.DocumentsProvider#queryRoots queryRoots()}</li> + +<li>{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}</li> + +<li>{@link android.provider.DocumentsProvider#queryDocument queryDocument()}</li> + +<li>{@link android.provider.DocumentsProvider#openDocument openDocument()}</li> +</ul> + +<p>Hanya inilah metode yang diwajibkan kepada Anda secara ketat untuk diimplementasikan, namun ada +banyak lagi yang mungkin Anda inginkan. Lihat {@link android.provider.DocumentsProvider} +untuk detailnya.</p> + +<h4 id="queryRoots">Mengimplementasikan queryRoots</h4> + +<p>Implementasi {@link android.provider.DocumentsProvider#queryRoots +queryRoots()} oleh Anda harus menghasilkan {@link android.database.Cursor} yang menunjuk ke semua +direktori akar penyedia dokumen, dengan menggunakan kolom-kolom yang didefinisikan dalam +{@link android.provider.DocumentsContract.Root}.</p> + +<p>Dalam cuplikan berikut, parameter {@code projection} mewakili bidang-bidang +tertentu yang ingin didapatkan kembali oleh pemanggil. Cuplikan ini membuat kursor baru +dan menambahkan satu baris ke satu akar— kursor, satu direktori level atas, seperti +Downloads atau Images. Kebanyakan penyedia hanya mempunyai satu akar. Anda bisa mempunyai lebih dari satu, +misalnya, jika ada banyak akun pengguna. Dalam hal itu, cukup tambahkan sebuah +baris kedua ke kursor.</p> + +<pre> +@Override +public Cursor queryRoots(String[] projection) throws FileNotFoundException { + + // Create a cursor with either the requested fields, or the default + // projection if "projection" is null. + final MatrixCursor result = + new MatrixCursor(resolveRootProjection(projection)); + + // If user is not logged in, return an empty root cursor. This removes our + // provider from the list entirely. + if (!isUserLoggedIn()) { + return result; + } + + // It's possible to have multiple roots (e.g. for multiple accounts in the + // same app) -- just add multiple cursor rows. + // Construct one row for a root called "MyCloud". + final MatrixCursor.RowBuilder row = result.newRow(); + row.add(Root.COLUMN_ROOT_ID, ROOT); + row.add(Root.COLUMN_SUMMARY, getContext().getString(R.string.root_summary)); + + // FLAG_SUPPORTS_CREATE means at least one directory under the root supports + // creating documents. FLAG_SUPPORTS_RECENTS means your application's most + // recently used documents will show up in the "Recents" category. + // FLAG_SUPPORTS_SEARCH allows users to search all documents the application + // shares. + row.add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE | + Root.FLAG_SUPPORTS_RECENTS | + Root.FLAG_SUPPORTS_SEARCH); + + // COLUMN_TITLE is the root title (e.g. Gallery, Drive). + row.add(Root.COLUMN_TITLE, getContext().getString(R.string.title)); + + // This document id cannot change once it's shared. + row.add(Root.COLUMN_DOCUMENT_ID, getDocIdForFile(mBaseDir)); + + // The child MIME types are used to filter the roots and only present to the + // user roots that contain the desired type somewhere in their file hierarchy. + row.add(Root.COLUMN_MIME_TYPES, getChildMimeTypes(mBaseDir)); + row.add(Root.COLUMN_AVAILABLE_BYTES, mBaseDir.getFreeSpace()); + row.add(Root.COLUMN_ICON, R.drawable.ic_launcher); + + return result; +}</pre> + +<h4 id="queryChildDocuments">Mengimplementasikan queryChildDocuments</h4> + +<p>Implementasi +{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()} +oleh Anda harus menghasilkan {@link android.database.Cursor} yang menunjuk ke semua file dalam +direktori yang ditentukan, dengan menggunakan kolom-kolom yang didefinisikan dalam +{@link android.provider.DocumentsContract.Document}.</p> + +<p>Metode ini akan dipanggil bila Anda memilih akar aplikasi dalam picker UI. +Metode mengambil dokumen anak dari direktori di bawah akar. Metode ini bisa dipanggil pada level apa saja dalam +hierarki file, bukan hanya akar. Cuplikan ini +membuat kursor baru dengan kolom-kolom yang diminta, lalu menambahkan informasi tentang +setiap anak langsung dalam direktori induk ke kursor. +Satu anak bisa berupa gambar, direktori lain—file apa saja:</p> + +<pre>@Override +public Cursor queryChildDocuments(String parentDocumentId, String[] projection, + String sortOrder) throws FileNotFoundException { + + final MatrixCursor result = new + MatrixCursor(resolveDocumentProjection(projection)); + final File parent = getFileForDocId(parentDocumentId); + for (File file : parent.listFiles()) { + // Adds the file's display name, MIME type, size, and so on. + includeFile(result, null, file); + } + return result; +} +</pre> + +<h4 id="queryDocument">Mengimplementasikan queryDocument</h4> + +<p>Implementasi +{@link android.provider.DocumentsProvider#queryDocument queryDocument()} +oleh Anda harus menghasilkan {@link android.database.Cursor} yang menunjuk ke file yang disebutkan, +dengan menggunakan kolom-kolom yang didefinisikan dalam {@link android.provider.DocumentsContract.Document}. +</p> + +<p>Metode {@link android.provider.DocumentsProvider#queryDocument queryDocument()} +menghasilkan informasi yang sama yang diteruskan dalam +{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}, +namun untuk file tertentu:</p> + + +<pre>@Override +public Cursor queryDocument(String documentId, String[] projection) throws + FileNotFoundException { + + // Create a cursor with the requested projection, or the default projection. + final MatrixCursor result = new + MatrixCursor(resolveDocumentProjection(projection)); + includeFile(result, documentId, null); + return result; +} +</pre> + +<h4 id="openDocument">Mengimplementasikan openDocument</h4> + +<p>Anda harus mengimplementasikan {@link android.provider.DocumentsProvider#openDocument +openDocument()} untuk menghasilkan {@link android.os.ParcelFileDescriptor} yang mewakili +file yang disebutkan. Aplikasi lain bisa menggunakan {@link android.os.ParcelFileDescriptor} +yang dihasilkan untuk mengalirkan data. Sistem memanggil metode ini setelah pengguna memilih file +dan aplikasi klien meminta akses ke file itu dengan memanggil +{@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}. +Misalnya:</p> + +<pre>@Override +public ParcelFileDescriptor openDocument(final String documentId, + final String mode, + CancellationSignal signal) throws + FileNotFoundException { + Log.v(TAG, "openDocument, mode: " + mode); + // It's OK to do network operations in this method to download the document, + // as long as you periodically check the CancellationSignal. If you have an + // extremely large file to transfer from the network, a better solution may + // be pipes or sockets (see ParcelFileDescriptor for helper methods). + + final File file = getFileForDocId(documentId); + + final boolean isWrite = (mode.indexOf('w') != -1); + if(isWrite) { + // Attach a close listener if the document is opened in write mode. + try { + Handler handler = new Handler(getContext().getMainLooper()); + return ParcelFileDescriptor.open(file, accessMode, handler, + new ParcelFileDescriptor.OnCloseListener() { + @Override + public void onClose(IOException e) { + + // Update the file with the cloud server. The client is done + // writing. + Log.i(TAG, "A file with id " + + documentId + " has been closed! + Time to " + + "update the server."); + } + + }); + } catch (IOException e) { + throw new FileNotFoundException("Failed to open document with id " + + documentId + " and mode " + mode); + } + } else { + return ParcelFileDescriptor.open(file, accessMode); + } +} +</pre> + +<h3 id="security">Keamanan</h3> + +<p>Anggaplah penyedia dokumen Anda sebuah layanan penyimpanan cloud yang dilindungi kata sandi +dan Anda ingin memastikan bahwa pengguna sudah login sebelum Anda mulai berbagi file mereka. +Apakah yang harus dilakukan aplikasi Anda jika pengguna tidak login? Solusinya adalah menghasilkan +akar nol dalam implementasi {@link android.provider.DocumentsProvider#queryRoots +queryRoots()} Anda. Yakni, sebuah kursor akar kosong:</p> + +<pre> +public Cursor queryRoots(String[] projection) throws FileNotFoundException { +... + // If user is not logged in, return an empty root cursor. This removes our + // provider from the list entirely. + if (!isUserLoggedIn()) { + return result; +} +</pre> + +<p>Langkah lainnya adalah memanggil {@code getContentResolver().notifyChange()}. +Ingat {@link android.provider.DocumentsContract}? Kita menggunakannya untuk membuat +URI ini. Cuplikan berikut memberi tahu sistem untuk membuat query akar penyedia dokumen Anda +kapan saja status login pengguna berubah. Jika pengguna tidak +login, panggilan ke {@link android.provider.DocumentsProvider#queryRoots queryRoots()} akan menghasilkan +kursor kosong, seperti yang ditampilkan di atas. Cara ini akan memastikan bahwa dokumen penyedia hanya +tersedia jika pengguna login ke penyedia itu.</p> + +<pre>private void onLoginButtonClick() { + loginOrLogout(); + getContentResolver().notifyChange(DocumentsContract + .buildRootsUri(AUTHORITY), null); +} +</pre>
\ No newline at end of file diff --git a/docs/html-intl/intl/in/guide/topics/resources/accessing-resources.jd b/docs/html-intl/intl/in/guide/topics/resources/accessing-resources.jd new file mode 100644 index 000000000000..e4a0bea1e36a --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/resources/accessing-resources.jd @@ -0,0 +1,337 @@ +page.title=Mengakses Sumber Daya +parent.title=Sumber Daya Aplikasi +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Tampilan Cepat</h2> + <ul> + <li>Sumber daya bisa diacu dari kode dengan menggunakan integer dari {@code R.java}, seperti +{@code R.drawable.myimage}</li> + <li>Sumber daya bisa diacu dari sumber daya dengan menggunakan sintaks XML khusus, seperti {@code +@drawable/myimage}</li> + <li>Anda juga bisa mengakses sumber daya aplikasi Anda dengan berbagai metode di +{@link android.content.res.Resources}</li> + </ul> + + <h2>Kelas-Kelas Utama</h2> + <ol> + <li>{@link android.content.res.Resources}</li> + </ol> + + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#ResourcesFromCode">Mengakses Sumber Daya dari Kode</a></li> + <li><a href="#ResourcesFromXml">Mengakses Sumber Daya dari XML</a> + <ol> + <li><a href="#ReferencesToThemeAttributes">Mengacu atribut gaya</a></li> + </ol> + </li> + <li><a href="#PlatformResources">Mengakses Sumber Daya Platform</a></li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="providing-resources.html">Menyediakan Sumber Daya</a></li> + <li><a href="available-resources.html">Tipe Sumber Daya</a></li> + </ol> +</div> +</div> + + + + +<p>Setelah Anda menyediakan sumber daya dalam aplikasi Anda (yang dibicarakan di <a href="providing-resources.html">Menyediakan Sumber Daya</a>), Anda bisa menerapkannya dengan +mengacu ID sumber dayanya. Semua ID sumber daya didefinisikan di kelas {@code R} proyek Anda, yang +dihasilkan oleh alat {@code aapt} secara otomatis.</p> + +<p>Bila aplikasi Anda dikompilasi, {@code aapt} akan membuat kelas {@code R}, yang berisi +ID sumber daya untuk semua sumber daya dalam direktori {@code +res/} Anda. Untuk masing-masing tipe sumber daya, ada subkelas {@code R} (misalnya, +{@code R.drawable} untuk semua sumber daya yang bisa ditarik), dan untuk masing-masing sumber daya dari tipe itu, ada satu integer statis + (misalnya, {@code R.drawable.icon}). Integer ini adalah ID sumber daya yang bisa Anda gunakan +untuk mengambil sumber daya Anda.</p> + +<p>Walaupun kelas {@code R} adalah tempat menyebutkan ID sumber daya, Anda tidak perlu +melihat ke sana untuk menemukan ID sumber daya. ID sumber daya selalu terdiri dari:</p> +<ul> + <li><em>Tipe sumber daya</em>: Masing-masing sumber daya dikelompokkan menjadi "tipe", misalnya {@code +string}, {@code drawable}, dan {@code layout}. Untuk mengetahui selengkapnya tentang berbagai tipe, lihat <a href="available-resources.html">Tipe Sumber Daya</a>. + </li> + <li><em>Nama sumber daya</em>, bisa berupa: nama file, +tidak termasuk ekstensi; atau nilai dalam atribut {@code android:name} XML, jika +sumber daya itu sebuah nilai sederhana (misalnya sebuah string).</li> +</ul> + +<p>Ada dua cara untuk mengakses sumber daya:</p> +<ul> + <li><strong>Dalam kode:</strong> Menggunakan integer statis dari subkelas dari kelas {@code R} +, misalnya: + <pre class="classic no-pretty-print">R.string.hello</pre> + <p>{@code string} adalah tipe sumber daya dan {@code hello} adalah nama sumber daya. Ada banyak +API Android yang bisa mengakses sumber daya Anda bila Anda menyediakan ID sumber daya dengan format ini. Lihat +<a href="#ResourcesFromCode">Mengakses Sumber Daya dalam Kode</a>.</p> + </li> + <li><strong>Dalam XML:</strong> Menggunakan sebuah sintaks XML khusus yang juga berkaitan dengan +ID sumber daya yang didefinisikan dalam kelas {@code R}, misalnya: + <pre class="classic no-pretty-print">@string/hello</pre> + <p>{@code string} adalah tipe sumber daya dan {@code hello} adalah nama sumber daya. Anda bisa menggunakan +sintaks ini dalam sumber daya XML di mana saja Anda ingin menyediakan sebuah nilai dalam sebuah sumber daya. Lihat <a href="#ResourcesFromXml">Mengakses Sumber Daya dari XML</a>.</p> + </li> +</ul> + + + +<h2 id="ResourcesFromCode">Mengakses Sumber Daya dalam Kode </h2> + +<p>Anda bisa menggunakan sumber daya dalam kode dengan menyalurkan ID sumber daya sebagai sebuah parameter metode. Misalnya, + Anda bisa mengatur sebuah {@link android.widget.ImageView} agar menggunakan sumber daya{@code res/drawable/myimage.png} +dengan menggunakan {@link android.widget.ImageView#setImageResource(int) setImageResource()}:</p> +<pre> +ImageView imageView = (ImageView) findViewById(R.id.myimageview); +imageView.setImageResource(<strong>R.drawable.myimage</strong>); +</pre> + +<p>Anda juga bisa mengambil tiap sumber daya dengan menggunakan berbagai metode di {@link +android.content.res.Resources}, di mana Anda bisa mendapatkan instance + {@link android.content.Context#getResources()}.</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Akses ke File Asli</h2> + +<p>Walaupun tidak lazim, Anda mungkin perlu mengakses file dan direktori asli Anda. Jika demikian, maka +menyimpan file Anda di {@code res/} tidak akan berhasil, karena satu-satunya cara untuk membaca sebuah sumber daya dari +{@code res/} adalah dengan ID sumber daya. Sebagai gantinya, Anda bisa menyimpan sumber daya dalam direktori +{@code assets/}.</p> +<p>File yang tersimpan di direktori {@code assets/} <em>tidak</em> diberi ID +sumber daya, sehingga Anda tidak bisa mengacunya melalui kelas {@code R} atau dari sumber daya XML. Sebagai gantinya, Anda bisa melakukan +query file di direktori {@code assets/} seperti sebuah sistem file biasa dan membaca data mentah dengan menggunakan +{@link android.content.res.AssetManager}.</p> +<p>Akan tetapi, jika yang Anda butuhkan hanya kemampuan membaca data mentah (misalnya sebuah file video atau audio), +maka simpanlah file itu di direktori {@code res/raw/} dan baca aliran byte dengan menggunakan {@link +android.content.res.Resources#openRawResource(int) openRawResource()}.</p> + +</div> +</div> + + +<h3>Sintaks</h3> + +<p>Inilah sintaks untuk mengacu sumber daya dalam kode:</p> + +<pre class="classic no-pretty-print"> +[<em><package_name></em>.]R.<em><resource_type></em>.<em><resource_name></em> +</pre> + +<ul> + <li><em> {@code <package_name>}</em>adalah nama paket yang di dalamnya terdapat sumber daya (tidak +dibutuhkan bila mengacu sumber daya dari paket Anda sendiri).</li> + <li><em>{@code <resource_type>}</em> adalah subkelas {@code R} untuk tipe sumber daya.</li> + <li><em>{@code <resource_name>}</em> bisa berupa nama file sumber daya +tanpa ekstensi atau nilai atribut {@code android:name} dalam elemen XML (untuk nilai +sederhana).</li> +</ul> +<p>Lihat <a href="available-resources.html">Tipe Sumber Daya</a> untuk +informasi selengkapnya tentang masing-masing tipe sumber daya dan cara mengacunya.</p> + + +<h3>Kasus penggunaan</h3> + +<p>Ada banyak metode yang menerima parameter ID sumber daya dan Anda bisa mengambil sumber daya dengan menggunakan +metode di {@link android.content.res.Resources}. Anda bisa mengambil instance {@link +android.content.res.Resources} dengan {@link android.content.Context#getResources +Context.getResources()}.</p> + + +<p>Berikut adalah beberapa contoh cara mengakses sumber daya dalam kode:</p> + +<pre> +// Load a background for the current screen from a drawable resource +{@link android.app.Activity#getWindow()}.{@link +android.view.Window#setBackgroundDrawableResource(int) +setBackgroundDrawableResource}(<strong>R.drawable.my_background_image</strong>) ; + +// Set the Activity title by getting a string from the Resources object, because +// this method requires a CharSequence rather than a resource ID +{@link android.app.Activity#getWindow()}.{@link android.view.Window#setTitle(CharSequence) +setTitle}(getResources().{@link android.content.res.Resources#getText(int) +getText}(<strong>R.string.main_title</strong>)); + +// Load a custom layout for the current screen +{@link android.app.Activity#setContentView(int) +setContentView}(<strong>R.layout.main_screen</strong>); + +// Set a slide in animation by getting an Animation from the Resources object +mFlipper.{@link android.widget.ViewAnimator#setInAnimation(Animation) +setInAnimation}(AnimationUtils.loadAnimation(this, + <strong>R.anim.hyperspace_in</strong>)); + +// Set the text on a TextView object using a resource ID +TextView msgTextView = (TextView) findViewById(<strong>R.id.msg</strong>); +msgTextView.{@link android.widget.TextView#setText(int) +setText}(<strong>R.string.hello_message</strong>); +</pre> + + +<p class="caution"><strong>Perhatian:</strong> Anda tidak boleh memodifikasi file {@code +R.java} secara manual—, ini dihasilkan oleh alat {@code aapt} bila proyek Anda telah +dikompilasi. Perubahan apa pun akan ditimpa bila nanti Anda mengompilasi.</p> + + + +<h2 id="ResourcesFromXml">Mengakses Sumber Daya dari XML</h2> + +<p>Anda bisa mendefinisikan nilai untuk beberapa atribut dan elemen XML dengan menggunakan +acuan ke sumber daya yang ada. Anda akan sering melakukannya saat membuat file layout, untuk +memasok string dan gambar bagi widget Anda.</p> + +<p>Misalnya, jika Anda menambahkan sebuah {@link android.widget.Button} ke layout, Anda harus menggunakan +sebuah <a href="string-resource.html">sumber daya string</a> bagi teks tombolnya:</p> + +<pre> +<Button + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="<strong>@string/submit</strong>" /> +</pre> + + +<h3>Sintaks</h3> + +<p>Berikut adalah sintaks untuk mengacu sumber daya di sumber daya XML:</p> + +<pre class="classic no-pretty-print"> +@[<em><package_name></em>:]<em><resource_type></em>/<em><resource_name></em> +</pre> + +<ul> + <li>{@code <package_name>} adalah nama paket yang di dalamnya terdapat sumber daya (tidak +dibutuhkan bila mengacu sumber daya dari paket yang sama)</li> + <li>{@code <resource_type>} adalah subkelas +{@code R} untuk tipe sumber daya</li> + <li>{@code <resource_name>} bisa berupa nama file sumber daya +tanpa ekstensi atau nilai atribut {@code android:name} dalam elemen XML (untuk nilai +sederhana).</li> +</ul> + +<p>Lihat <a href="available-resources.html">Tipe Sumber Daya</a> untuk +informasi selengkapnya tentang masing-masing tipe sumber daya dan cara mengacunya.</p> + + +<h3>Kasus penggunaan</h3> + +<p>Dalam beberapa kasus, Anda harus menggunakan sumber daya untuk suatu nilai dalam XML (misalnya, untuk menerapkan gambar yang bisa ditarik +pada widget), namun Anda juga bisa menggunakan sumber daya di XML mana saja yang menerima nilai sederhana. Misalnya, jika +Anda mempunyai file sumber daya berikut yang berisi <a href="more-resources.html#Color">sumber daya warna</a> dan <a href="string-resource.html">sumber daya string</a>:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <color name="opaque_red">#f00</color> + <string name="hello">Hello!</string> +</resources> +</pre> + +<p>Anda bisa menggunakan sumber daya ini dalam file layout berikut untuk mengatur warna teks dan +string teks:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:textColor="<strong>@color/opaque_red</strong>" + android:text="<strong>@string/hello</strong>" /> +</pre> + +<p>Dalam hal ini, Anda tidak perlu menyebutkan nama paket dalam sumber daya acuan karena +sumber daya berasal dari paket Anda sendiri. Untuk +mengacu sumber daya sistem, Anda perlu memasukkan nama paketnya. Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:textColor="<strong>@android:color/secondary_text_dark</strong>" + android:text="@string/hello" /> +</pre> + +<p class="note"><strong>Catatan:</strong> Anda harus menggunakan sumber daya string sepanjang +waktu, sehingga aplikasi Anda bisa dilokalkan untuk bahasa lain. +Untuk informasi tentang cara menciptakan +sumber daya alternatif (seperti string lokal), lihat <a href="providing-resources.html#AlternativeResources">Menyediakan Sumber Daya Alternatif +</a>. Untuk panduan lengkap melokalkan aplikasi Anda ke bahasa lain, +lihat <a href="localization.html">Pelokalan</a>.</p> + +<p>Anda bahkan bisa menggunakan sumber daya dalam XML untuk membuat alias. Misalnya, Anda bisa membuat +sumber daya yang bisa ditarik yang merupakan alias bagi sumber daya yang bisa ditarik lainnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<bitmap xmlns:android="http://schemas.android.com/apk/res/android" + android:src="@drawable/other_drawable" /> +</pre> + +<p>Hal ini terdengar berlebihan, namun bisa sangat berguna saat menggunakan sumber daya alternatif. Baca selengkapnya tentang +<a href="providing-resources.html#AliasResources">Membuat sumber daya alias</a>.</p> + + + +<h3 id="ReferencesToThemeAttributes">Mengacu atribut gaya</h3> + +<p>Sumber daya atribut gaya memungkinkan Anda mengacu nilai +suatu atribut dalam tema yang diterapkan saat ini. Dengan mengacu sebuah atribut gaya memungkinkan Anda +menyesuaikan tampilan elemen UI dengan mengatur gayanya agar cocok dengan beragam variasi standar yang dipasok oleh +tema saat ini, sebagai ganti memasok nilai yang ditanamkan (hard-coded). Mengacu sebuah atribut gaya +pada dasarnya adalah "gunakan gaya yang didefinisikan oleh atribut ini, dalam tema saat ini".</p> + +<p>Untuk mengacu sebuah atribut gaya, sintaks namanya hampir sama dengan format sumber daya normal +, namun sebagai ganti simbol @ ({@code @}), gunakan sebuah tanda tanya ({@code ?}), dan +porsi tipe sumber daya bersifat opsional. Sebagai contoh:</p> + +<pre class="classic"> +?[<em><package_name></em>:][<em><resource_type></em>/]<em><resource_name></em> +</pre> + +<p>Misalnya, begini cara Anda mengacu suatu atribut untuk mengatur warna teks agar cocok dengan +warna teks "utama" tema sistem:</p> + +<pre> +<EditText id="text" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:textColor="<strong>?android:textColorSecondary</strong>" + android:text="@string/hello_world" /> +</pre> + +<p>Di sini, atribut {@code android:textColor} menyebutkan nama atribut gaya +dalam tema saat ini. Android kini menggunakan nilai yang diterapkan pada atribut gaya {@code android:textColorSecondary} +sebagai nilai untuk {@code android:textColor} dalam widget ini. Karena alat sumber daya +mengetahui bahwa atribut sumber daya diharapkan dalam konteks ini, +maka Anda tidak perlu menyatakan tipenyanya secara eksplisit (yang akan berupa +<code>?android:attr/textColorSecondary</code>)—Anda bisa mengecualikan tipe {@code attr}.</p> + + + + +<h2 id="PlatformResources">Mengakses Sumber Daya Platform</h2> + +<p>Android berisi sejumlah sumber daya standar, seperti gaya, tema, dan layout. Untuk +mengakses semua sumber daya ini, tetapkan acuan sumber daya Anda dengan nama paket +<code>android</code>. Misalnya, Android menyediakan sumber daya layout yang bisa Anda gunakan untuk +item daftar dalam{@link android.widget.ListAdapter}:</p> + +<pre> +{@link android.app.ListActivity#setListAdapter(ListAdapter) +setListAdapter}(new {@link +android.widget.ArrayAdapter}<String>(this, <strong>android.R.layout.simple_list_item_1</strong>, myarray)); +</pre> + +<p>Dalam contoh ini, {@link android.R.layout#simple_list_item_1} adalah sumber daya layout yang didefinisikan oleh +platform untuk item di {@link android.widget.ListView}. Anda bisa menggunakannya sebagai ganti menciptakan +layout sendiri untuk item daftar. Untuk informasi selengkapnya, lihat panduan pengembang +<a href="{@docRoot}guide/topics/ui/layout/listview.html">List View</a>.</p> + diff --git a/docs/html-intl/intl/in/guide/topics/resources/overview.jd b/docs/html-intl/intl/in/guide/topics/resources/overview.jd new file mode 100644 index 000000000000..966800cf7daa --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/resources/overview.jd @@ -0,0 +1,103 @@ +page.title=Ikhtisar Sumber Daya +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Topik</h2> + <ol> + <li><a href="providing-resources.html">Menyediakan Sumber Daya</a></li> + <li><a href="accessing-resources.html">Mengakses Sumber Daya</a></li> + <li><a href="runtime-changes.html">Menangani Perubahan Runtime</a></li> + <li><a href="localization.html">Pelokalan</a></li> + </ol> + + <h2>Acuan</h2> + <ol> + <li><a href="available-resources.html">Tipe Sumber Daya</a></li> + </ol> +</div> +</div> + + +<p>Anda harus selalu mengeksternalkan sumber daya seperti gambar dan string dari kode +aplikasi, agar Anda bisa memeliharanya secara independen. Mengeksternalkan +sumber daya juga membuat Anda dapat menyediakan sumber daya alternatif yang mendukung konfigurasi +perangkat tertentu seperti bahasa atau ukuran layar yang berbeda, yang semakin penting +seiring semakin banyak tersedianya perangkat berbasis Android dengan konfigurasi berbeda. Untuk +memberikan kompatibilitas dengan konfigurasi berbeda, Anda harus menata sumber daya dalam +direktori {@code res/} proyek Anda, menggunakan berbagai subdirektori yang mengelompokkan sumber daya menurut tipe +dan konfigurasinya.</p> + +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="167" alt="" /> +<p class="img-caption"> +<strong>Gambar 1.</strong> Dua perangkat berbeda, masing-masing menggunakan layout default +(aplikasi tidak menyediakan layout alternatif).</p> +</div> + +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> +<p class="img-caption"> +<strong>Gambar 2.</strong> Dua perangkat berbeda, masing-masing menggunakan layout berbeda yang tersedia untuk +ukuran layar berbeda.</p> +</div> + +<p>Bagi setiap tipe sumber daya, Anda bisa menetapkan sumber daya <em>default</em> dan sumber daya +<em>alternatif</em> untuk aplikasi Anda:</p> +<ul> + <li>Sumber daya default adalah sumber daya yang harus digunakan apa pun +konfigurasi perangkatnya atau jika tidak ada sumber daya alternatif yang sesuai +dengan konfigurasi saat ini.</li> + <li>Sumber daya alternatif adalah sumber daya yang Anda desain untuk digunakan dengan +konfigurasi tertentu. Untuk menetapkan bahwa satu kelompok sumber daya ditujukan bagi konfigurasi tertentu, +tambahkan qualifier konfigurasi yang sesuai ke nama direktori.</li> +</ul> + +<p>Misalnya, walaupun layout +UI default Anda disimpan dalam direktori {@code res/layout/}, Anda dapat menetapkan layout berbeda +untuk digunakan saat layar dalam orientasi lanskap, dengan menyimpannya dalam direktori {@code res/layout-land/} +. Android secara otomatis memberlakukan sumber daya yang sesuai dengan mencocokkan konfigurasi perangkat +saat ini dengan nama direktori sumber daya.</p> + +<p>Gambar 1 mengilustrasikan cara sistem memberlakukan layout yang sama untuk +dua perangkat berbeda saat sumber daya alternatif tidak tersedia. Gambar 2 menunjukkan +aplikasi yang sama saat menambahkan sumber daya layout alternatif untuk layar yang lebih besar.</p> + +<p>Dokumen-dokumen berikut berisi panduan lengkap mengenai cara menata sumber daya aplikasi, +menetapkan sumber daya alternatif, mengaksesnya dalam aplikasi, dan banyak lagi:</p> + +<dl> + <dt><strong><a href="providing-resources.html">Menyediakan Sumber Daya</a></strong></dt> + <dd>Jenis sumber daya yang dapat Anda sediakan dalam aplikasi, tempat menyimpannya, dan cara membuat sumber daya +alternatif untuk konfigurasi perangkat tertentu.</dd> + <dt><strong><a href="accessing-resources.html">Mengakses Sumber Daya</a></strong></dt> + <dd>Cara menggunakan sumber daya yang telah Anda sediakan, baik dengan mengacunya dari kode +aplikasi Anda atau dari sumber daya XML lainnya.</dd> + <dt><strong><a href="runtime-changes.html">Menangani Perubahan Runtime</a></strong></dt> + <dd>Cara mengelola perubahan konfigurasi yang terjadi saat Aktivitas Anda berjalan.</dd> + <dt><strong><a href="localization.html">Pelokalan</a></strong></dt> + <dd>Panduan dari pengalaman untuk melokalkan aplikasi menggunakan sumber daya alternatif. Walaupun ini +hanya satu penggunaan tertentu dari sumber daya alternatif, hal ini sangat penting dalam meraih pengguna lebih +banyak.</dd> + <dt><strong><a href="available-resources.html">Tipe Sumber Daya</a></strong></dt> + <dd>Acuan dari berbagai tipe sumber daya yang dapat Anda sediakan, menjelaskan elemen-elemen XML, +atribut, dan sintaksnya. Misalnya, acuan ini menunjukkan kepada Anda cara membuat sumber daya untuk +menu aplikasi, drawable, animasi, dan lainnya.</dd> +</dl> + +<!-- +<h2>Raw Assets</h2> + +<p>An alternative to saving files in {@code res/} is to save files in the {@code +assets/} directory. This should only be necessary if you need direct access to original files and +directories by name. Files saved in the {@code assets/} directory will not be given a resource +ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can +query data in the {@code assets/} directory like an ordinary file system, search through the +directory and +read raw data using {@link android.content.res.AssetManager}. For example, this can be more useful +when dealing with textures for a game. However, if you only need to read raw data from a file +(such as a video or audio file), then you should save files into the {@code res/raw/} directory and +then read a stream of bytes using {@link android.content.res.Resources#openRawResource(int)}. This +is uncommon, but if you need direct access to original files in {@code assets/}, refer to the {@link +android.content.res.AssetManager} documentation.</p> +--> diff --git a/docs/html-intl/intl/in/guide/topics/resources/providing-resources.jd b/docs/html-intl/intl/in/guide/topics/resources/providing-resources.jd new file mode 100644 index 000000000000..d6bbfc58d911 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/resources/providing-resources.jd @@ -0,0 +1,1094 @@ +page.title=Menyediakan Sumber Daya +parent.title=Sumber Daya Aplikasi +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Tampilan Cepat</h2> + <ul> + <li>Berbagai tipe sumber daya termasuk dalam subdirektori {@code res/}</li> + <li>Sumber daya alternatif menyediakan file sumber daya dengan konfigurasi tertentu</li> + <li>Sertakan selalu sumber daya default agar aplikasi Anda tidak bergantung pada +konfigurasi perangkat tertentu</li> + </ul> + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#ResourceTypes">Mengelompokkan Tipe Sumber Daya</a></li> + <li><a href="#AlternativeResources">Menyediakan Sumber Daya Alternatif</a> + <ol> + <li><a href="#QualifierRules">Aturan penamaan qualifier</a></li> + <li><a href="#AliasResources">Membuat sumber daya alias</a></li> + </ol> + </li> + <li><a href="#Compatibility">Menyediakan Kompatibilitas Perangkat Terbaik dengan Sumber Daya</a></li> + <li><a href="#BestMatch">Cara Android Menemukan Sumber Daya yang Paling Cocok</a></li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="accessing-resources.html">Mengakses Sumber Daya</a></li> + <li><a href="available-resources.html">Tipe Sumber Daya</a></li> + <li><a href="{@docRoot}guide/practices/screens_support.html">Mendukung Beberapa +Layar</a></li> + </ol> +</div> +</div> + +<p>Anda harus selalu mengeksternalkan sumber daya aplikasi seperti gambar dan string dari kode +, agar Anda bisa memeliharanya secara independen. Anda juga harus menyediakan sumber daya alternatif untuk +konfigurasi perangkat tertentu, dengan mengelompokkannya dalam direktori sumber daya bernama khusus. Saat +runtime, Android menggunakan sumber daya yang sesuai berdasarkan konfigurasi saat ini. Misalnya, Anda mungkin +ingin menyediakan layout UI berbeda bergantung pada ukuran layar atau string berbeda bergantung pada +pengaturan bahasa.</p> + +<p>Setelah mengeksternalkan sumber daya aplikasi, Anda dapat mengaksesnya menggunakan +ID sumber daya yang dibuat dalam kelas {@code R} proyek Anda. Cara menggunakan +sumber daya dalam aplikasi dibahas dalam <a href="accessing-resources.html">Mengakses +Sumber Daya</a>. Dokumen ini menampilkan cara mengelompokkan sumber daya +dalam proyek Android Anda dan menyediakan sumber daya alternatif untuk konfigurasi perangkat tertentu.</p> + + +<h2 id="ResourceTypes">Mengelompokkan Tipe Sumber Daya</h2> + +<p>Anda harus menempatkan setiap tipe sumber daya dalam subdirektori spesifik pada direktori +{@code res/} proyek. Misalnya, inilah hierarki file untuk proyek sederhana:</p> + +<pre class="classic no-pretty-print"> +MyProject/ + src/ <span style="color:black"> + MyActivity.java </span> + res/ + drawable/ <span style="color:black"> + graphic.png </span> + layout/ <span style="color:black"> + main.xml + info.xml</span> + mipmap/ <span style="color:black"> + icon.png </span> + values/ <span style="color:black"> + strings.xml </span> +</pre> + +<p>Seperti yang Anda lihat dalam contoh ini, direktori {@code res/} berisi semua sumber daya (dalam +subdirektori): sumber daya gambar, dua sumber daya layout, direktori {@code mipmap/} untuk ikon +launcher, dan satu file sumber daya string. Nama direktori +sumber daya penting dan dijelaskan dalam tabel 1.</p> + +<p class="note"><strong>Catatan:</strong> Untuk informasi selengkapnya tentang menggunakan folder mipmap, lihat +<a href="{@docRoot}tools/projects/index.html#mipmap">Mengelola Ikhtisar Proyek</a>.</p> + +<p class="table-caption" id="table1"><strong>Tabel 1.</strong> Direktori sumber daya +didukung dalam direktori proyek {@code res/}.</p> + +<table> + <tr> + <th scope="col">Direktori</th> + <th scope="col">Tipe Sumber Daya</th> + </tr> + + <tr> + <td><code>animator/</code></td> + <td>File XML yang mendefinisikan <a href="{@docRoot}guide/topics/graphics/prop-animation.html">animasi +properti</a>.</td> + </tr> + + <tr> + <td><code>anim/</code></td> + <td>File XML yang mendefinisikan <a href="{@docRoot}guide/topics/graphics/view-animation.html#tween-animation">animasi +tween</a>. (Animasi properti juga dapat disimpan dalam direktori ini, namun +direktori {@code animator/} lebih disukai bagi animasi properti agar kedua tipe +ini dapat dibedakan.)</td> + </tr> + + <tr> + <td><code>color/</code></td> + <td>File XML yang mendefinisikan daftar status warna. Lihat <a href="color-list-resource.html">Sumber Daya +Daftar Status Warna</a></td> + </tr> + + <tr> + <td><code>drawable/</code></td> + + <td><p>File bitmap ({@code .png}, {@code .9.png}, {@code .jpg}, {@code .gif}) atau file XML yang +dikompilasi menjadi subtipe sumber daya drawable berikut:</p> + <ul> + <li>File bitmap</li> + <li>Nine-Patches (bitmap yang dapat diubah ukurannya)</li> + <li>Daftar status</li> + <li>Bentuk</li> + <li>Drawable animasi</li> + <li>Drawable lainnya</li> + </ul> + <p>Lihat <a href="drawable-resource.html">Sumber Daya Drawable</a>.</p> + </td> + </tr> + + <tr> + <td><code>mipmap/</code></td> + <td>File drawable untuk densitas ikon launcher yang berbeda. Untuk informasi selengkapnya tentang + mengelola ikon launcher dengan folder {@code mipmap/}, lihat +<a href="{@docRoot}tools/project/index.html#mipmap">Mengelola Ikhtisar Proyek</a>.</td> + </tr> + + <tr> + <td><code>layout/</code></td> + <td>File XML yang mendefinisikan layout antarmuka pengguna. + Lihat <a href="layout-resource.html">Sumber Daya Layout</a>.</td> + </tr> + + <tr> + <td><code>menu/</code></td> + <td>File XML yang mendefinisikan menu aplikasi, seperti Menu Opsi, Menu Konteks, atau Sub +Menu. Lihat <a href="menu-resource.html">Sumber Daya Menu</a>.</td> + </tr> + + <tr> + <td><code>raw/</code></td> + <td><p>File tak didukung yang akan disimpan dalam bentuk mentah. Untuk membuka sumber daya ini dengan +{@link java.io.InputStream} mentah, panggil {@link android.content.res.Resources#openRawResource(int) +Resources.openRawResource()} dengan ID sumber daya, yaitu {@code R.raw.<em>filename</em>}.</p> + <p>Akan tetapi, jika Anda butuh akses ke nama file asli dan hierarki file, Anda bisa mempertimbangkan +untuk menyimpan beberapa sumber daya dalam direktori {@code +assets/} (sebagai ganti {@code res/raw/}). File dalam {@code assets/} tidak diberi +ID sumber daya, jadi Anda bisa membacanya hanya dengan menggunakan {@link android.content.res.AssetManager}.</p></td> + </tr> + + <tr> + <td><code>values/</code></td> + <td><p>File XML yang berisi nilai-nilai sederhana, seperti string, integer, dan warna.</p> + <p>Walaupun file sumber daya XML dalam subdirektori {@code res/} lainnya mendefinisikan satu sumber daya +berdasarkan nama file XML, file dalam direktori {@code values/} menggambarkan beberapa sumber daya. +Untuk file dalam direktori ini, setiap anak elemen {@code <resources>} mendefinisikan satu sumber +daya. Misalnya, elemen {@code <string>} membuat sumber daya +{@code R.string} dan elemen {@code <color>} membuat sumber daya {@code R.color} +.</p> + <p>Karena setiap sumber daya didefinisikan dengan elemen XML-nya sendiri, Anda bisa bebas menamai file +ini dan menempatkan tipe sumber daya berbeda dalam satu file. Akan tetapi, agar jelas, Anda mungkin +perlu menempatkan tipe sumber daya unik dalam file berbeda. Misalnya, berikut ini adalah beberapa ketentuan +penamaan file untuk sumber daya yang dapat Anda buat dalam direktori ini:</p> + <ul> + <li>arrays.xml untuk larik sumber daya tipe (<a href="more-resources.html#TypedArray">larik bertipe</a>).</li> + <li>colors.xml untuk <a href="more-resources.html#Color">nilai warna</a></li> + <li>dimens.xml untuk <a href="more-resources.html#Dimension">nilai dimensi</a>.</li> + <li>strings.xml untuk <a href="string-resource.html">nilai +string</a>.</li> + <li>styles.xml untuk <a href="style-resource.html">gaya</a>.</li> + </ul> + <p>Lihat <a href="string-resource.html">Sumber Daya String</a>, + <a href="style-resource.html">Sumber Daya Gaya</a>, dan + <a href="more-resources.html">Tipe Sumber Daya Lainnya</a>.</p> + </td> + </tr> + + <tr> + <td><code>xml/</code></td> + <td>File XML tak didukung yang bisa dibaca saat runtime dengan memanggil {@link +android.content.res.Resources#getXml(int) Resources.getXML()}. Berbagai file konfigurasi XML +harus disimpan di sini, seperti <a href="{@docRoot}guide/topics/search/searchable-config.html">konfigurasi yang dapat dicari</a>. +<!-- or preferences configuration. --></td> + </tr> +</table> + +<p class="caution"><strong>Perhatian:</strong> Jangan menyimpan file sumber daya secara langsung dalam +direktori {@code res/}— karena akan menyebabkan kesalahan compiler.</p> + +<p>Untuk informasi selengkapnya tentang tipe sumber daya tertentu, lihat dokumentasi <a href="available-resources.html">Tipe Sumber Daya</a>.</p> + +<p>Sumber daya yang disimpan dalam subdirektori yang didefinisikan dalam tabel 1 adalah sumber daya +"default" Anda. Berarti sumber daya ini mendefinisikan desain default dan konten untuk aplikasi Anda. +Akan tetapi, beberapa tipe perangkat berbasis Android mungkin memanggil tipe sumber daya yang berbeda. +Misalnya, jika perangkat memiliki layar yang lebih besar daripada layar normal, maka Anda harus +menyediakan sumber daya layout berbeda yang memanfaatkan ruang layar yang lebih besar. Atau, jika perangkat +memiliki pengaturan bahasa berbeda, maka Anda harus menyediakan sumber daya string berbeda yang menerjemahkan teks dalam +antarmuka pengguna Anda. Untuk menyediakan sumber daya berbeda ini bagi +konfigurasi perangkat yang berbeda, Anda harus menyediakan sumber daya alternatif, selain sumber +daya default.</p> + + +<h2 id="AlternativeResources">Menyediakan Sumber Daya Alternatif</h2> + + +<div class="figure" style="width:429px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> +<p class="img-caption"> +<strong>Gambar 1.</strong> Dua perangkat berbeda, masing-masing menggunakan sumber daya layout berbeda.</p> +</div> + +<p>Hampir setiap aplikasi harus menyediakan sumber daya alternatif untuk mendukung konfigurasi +perangkat tertentu. Misalnya, Anda harus menyertakan sumber daya drawable alternatif untuk densitas layar +berbeda dan sumber daya string alternatif untuk bahasa yang berbeda. Saat runtime, Android +akan mendeteksi konfigurasi perangkat aktif dan memuat +sumber daya yang sesuai untuk aplikasi Anda.</p> + +<p>Untuk menyebutkan alternatif konfigurasi tertentu untuk satu set sumber daya:</p> +<ol> + <li>Buat direktori baru dalam {@code res/} yang dinamai dalam bentuk {@code +<em><resources_name></em>-<em><config_qualifier></em>}. + <ul> + <li><em>{@code <resources_name>}</em> adalah nama direktori dari sumber daya default +terkait (didefinisikan dalam tabel 1).</li> + <li><em>{@code <qualifier>}</em> adalah nama yang menetapkan konfigurasi individu +yang akan digunakan sumber daya ini (didefinisikan dalam tabel 2).</li> + </ul> + <p>Anda bisa menambahkan lebih dari satu <em>{@code <qualifier>}</em>. Pisahkan masing-masing +dengan tanda hubung.</p> + <p class="caution"><strong>Perhatian:</strong> Saat menambahkan beberapa qualifier, Anda +harus menempatkannya dalam urutan yang sama dengan yang tercantum dalam tabel 2. Jika urutan qualifier +salah, sumber daya akan diabaikan.</p> + </li> + <li>Simpan masing-masing sumber daya alternatif dalam direktori baru ini. File sumber daya harus dinamai +sama persis dengan file sumber daya default.</li> +</ol> + +<p>Misalnya, berikut ini beberapa sumber daya default dan sumber daya alternatif:</p> + +<pre class="classic no-pretty-print"> +res/ + drawable/ <span style="color:black"> + icon.png + background.png </span> + drawable-hdpi/ <span style="color:black"> + icon.png + background.png </span> +</pre> + +<p>Qualifier {@code hdpi} menunjukkan bahwa sumber daya dalam direktori itu diperuntukkan bagi perangkat dengan +layar densitas tinggi. Gambar di masing-masing direktori drawable memiliki ukuran untuk densitas layar +tertentu, namun nama filenya persis +sama. Dengan demikian, ID sumber daya yang Anda gunakan untuk mengacu gambar {@code icon.png} atau @code +background.png} selalu sama, namun Android memilih +versi masing-masing sumber daya yang paling cocok dengan perangkat saat ini, dengan membandingkan informasi konfigurasi +perangkat dengan qualifier dalam nama direktori sumber daya.</p> + +<p>Android mendukung beberapa qualifier konfigurasi dan Anda dapat +menambahkan beberapa qualifier ke satu nama direktori, dengan memisahkan setiap qualifier dengan tanda hubung. Tabel 2 +berisi daftar qualifier konfigurasi yang valid, dalam urutan prioritas—jika Anda menggunakan beberapa +qualifier sebagai direktori sumber daya, Anda harus menambahkannya ke nama direktori sesuai urutan +yang tercantum dalam tabel.</p> + + +<p class="table-caption" id="table2"><strong>Tabel 2.</strong> Nama-nama +qualifier konfigurasi.</p> +<table> + <tr> + <th>Konfigurasi</th> + <th>Nilai-nilai Qualifier</th> + <th>Keterangan</th> + </tr> + <tr id="MccQualifier"> + <td>MCC dan MNC</td> + <td>Contoh:<br/> + <code>mcc310</code><br/> + <code><nobr>mcc310-mnc004</nobr></code><br/> + <code>mcc208-mnc00</code><br/> + dll. + </td> + <td> + <p>Kode negara seluler (MCC), bisa diikuti dengan kode jaringan seluler (MNC) + dari kartu SIM dalam perangkat. Misalnya, <code>mcc310</code> adalah AS untuk operator mana saja, + <code>mcc310-mnc004</code> adalah AS untuk Verizon, dan <code>mcc208-mnc00</code> Prancis untuk +Orange.</p> + <p>Jika perangkat menggunakan koneksi radio (ponsel GSM), nilai-nilai MCC dan MNC berasal +dari kartu SIM.</p> + <p>Anda juga dapat menggunakan MNC saja (misalnya, untuk menyertakan sumber daya legal +spesifik untuk negara itu di aplikasi Anda). Jika Anda perlu menetapkan hanya berdasarkan bahasa, maka gunakan qualifier +<em>bahasa dan wilayah</em> sebagai gantinya (akan dibahas nanti). Jika Anda memutuskan untuk menggunakan qualifier MCC dan +MNC, Anda harus melakukannya dengan hati-hati dan menguji apakah qualifier itu berjalan sesuai harapan.</p> + <p>Lihat juga bidang konfigurasi {@link +android.content.res.Configuration#mcc}, dan {@link +android.content.res.Configuration#mnc}, yang masing-masing menunjukkan kode negara seluler saat ini +dan kode jaringan seluler.</p> + </td> + </tr> + <tr id="LocaleQualifier"> + <td>Bahasa dan wilayah</td> + <td>Contoh:<br/> + <code>en</code><br/> + <code>fr</code><br/> + <code>en-rUS</code><br/> + <code>fr-rFR</code><br/> + <code>fr-rCA</code><br/> + dll. + </td> + <td><p>Bahasa didefinisikan oleh kode bahasa dua huruf <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO +639-1</a>, bisa juga diikuti dengan kode wilayah +dua huruf <a href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO +3166-1-alpha-2</a> (diawali dengan huruf kecil "{@code r}"). + </p><p> + Kode <em>tidak</em> membedakan huruf besar atau kecil; awalan {@code r} akan digunakan untuk +membedakan bagian wilayah. + Anda tidak bisa menetapkan wilayah saja.</p> + <p>Ini bisa berubah selama masa pakai +aplikasi Anda jika pengguna mengubah bahasanya dalam pengaturan sistem. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk informasi tentang +bagaimana hal ini dapat memengaruhi aplikasi Anda selama runtime.</p> + <p>Lihat <a href="localization.html">Pelokalan</a> untuk panduan lengkap melokalkan +aplikasi Anda ke bahasa lain.</p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#locale} yang menunjukkan +bahasa setempat yang digunakan saat ini.</p> + </td> + </tr> + <tr id="LayoutDirectionQualifier"> + <td>Arah Layout</td> + <td><code>ldrtl</code><br/> + <code>ldltr</code><br/> + </td> + <td><p>Arah layout aplikasi Anda. {@code ldrtl} berarti "arah layout dari kanan ke kiri". + {@code ldltr} berarti "arah layout dari kiri ke kanan" dan merupakan nilai implisit default. + </p> + <p>Ini bisa berlaku untuk sumber daya mana pun seperti layout, drawable, atau nilai-nilai. + </p> + <p>Misalnya, jika Anda ingin memberikan beberapa layout khusus untuk bahasa Arab dan beberapa +layout umum untuk setiap bahasa lainnya yang menggunakan "kanan-ke-kiri" lainnya (seperti bahasa Persia atau Ibrani) maka Anda akan memiliki: + </p> +<pre class="classic no-pretty-print"> +res/ + layout/ <span style="color:black"> + main.xml </span>(Default layout) + layout-ar/ <span style="color:black"> + main.xml </span>(Specific layout for Arabic) + layout-ldrtl/ <span style="color:black"> + main.xml </span>(Any "right-to-left" language, except + for Arabic, because the "ar" language qualifier + has a higher precedence.) +</pre> + <p class="note"><strong>Catatan:</strong> Untuk mengaktifkan fitur +layout kanan-ke-kiri untuk aplikasi, Anda harus mengatur <a href="{@docRoot}guide/topics/manifest/application-element.html#supportsrtl">{@code + supportsRtl}</a> ke {@code "true"} dan mengatur <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> ke 17 atau yang lebih tinggi.</p> + <p><em>Ditambahkan dalam API level 17.</em></p> + </td> + </tr> + <tr id="SmallestScreenWidthQualifier"> + <td>smallestWidth</td> + <td><code>sw<N>dp</code><br/><br/> + Contoh:<br/> + <code>sw320dp</code><br/> + <code>sw600dp</code><br/> + <code>sw720dp</code><br/> + dll. + </td> + <td> + <p>Ukuran dasar layar, sebagaimana yang ditunjukkan oleh dimensi terpendek dari area layar +yang tersedia. Secara spesifik, smallestWidth perangkat adalah yang terpendek dari +tinggi dan lebar layar yang tersedia (Anda dapat menganggapnya sebagai "lebar terkecil yang memungkinkan" untuk layar). Anda bisa +menggunakan qualifier ini untuk memastikan bahwa, apa pun orientasi layar saat ini, aplikasi +Anda memiliki paling tidak {@code <N>} dps dari lebar yang tersedia untuk UI-nya.</p> + <p>Misalnya, jika layout mengharuskan dimensi layar terkecilnya setiap saat paling tidak +600 dp, maka Anda dapat menggunakan qualifer ini untuk membuat sumber daya layout, {@code +res/layout-sw600dp/}. Sistem akan menggunakan sumber daya ini hanya bila dimensi layar terkecil yang +tersedia paling tidak 600 dp, tanpa mempertimbangkan apakah sisi 600 dp adalah tinggi atau +lebar yang dipersepsikan pengguna. SmallestWidth adalah karakteristik ukuran layar tetap dari perangkat; <strong>smallestWidth +perangkat tidak berubah saat orientasi layar berubah</strong>.</p> + <p>SmallestWidth perangkat memperhitungkan dekorasi layar dan UI sistem. Misalnya +, jika perangkat memiliki beberapa elemen UI persisten pada layar yang menghitung ruang di sepanjang +sumbu smallestWidth, sistem akan mendeklarasikan smallestWidth lebih kecil daripada ukuran layar sebenarnya, +karena itu adalah piksel layar yang tidak tersedia untuk UI Anda. Sehingga nilai yang Anda +gunakan haruslah merupakan dimensi terkecil sebenarnya yang <em>dibutuhkan oleh layout Anda</em> (biasanya, nilai ini adalah +"lebar terkecil" yang didukung layout Anda, apa pun orientasi layar saat ini).</p> + <p>Sebagian nilai yang mungkin Anda gunakan untuk ukuran layar umum:</p> + <ul> + <li>320, untuk perangkat berkonfigurasi layar seperti: + <ul> + <li>240x320 ldpi (handset QVGA)</li> + <li>320x480 mdpi (handset)</li> + <li>480x800 hdpi (handset densitas tinggi)</li> + </ul> + </li> + <li>480, untuk layar seperti 480x800 mdpi (tablet/handset).</li> + <li>600, untuk layar seperti 600x1024 mdpi (tablet 7").</li> + <li>720, untuk layar seperti 720x1280 mdpi (tablet 10").</li> + </ul> + <p>Bila aplikasi Anda menyediakan beberapa direktori sumber daya dengan nilai yang berbeda untuk +qualifier smallestWidth terkecil, sistem akan menggunakan nilai terdekat dengan (tanpa melebihi) +smallestWidth perangkat. </p> + <p><em>Ditambahkan dalam API level 13.</em></p> + <p>Lihat juga atribut <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code +android:requiresSmallestWidthDp}</a>, yang mendeklarasikan smallestWidth minimum yang +kompatibel dengan aplikasi Anda, dan bidang konfigurasi {@link +android.content.res.Configuration#smallestScreenWidthDp}, yang menyimpan nilai +smallestWidth perangkat.</p> + <p>Untuk informasi selengkapnya tentang mendesain untuk layar berbeda dan menggunakan +qualifier ini, lihat panduan pengembang <a href="{@docRoot}guide/practices/screens_support.html">Mendukung +Multi Layar</a>.</p> + </td> + </tr> + <tr id="ScreenWidthQualifier"> + <td>Lebar yang tersedia</td> + <td><code>w<N>dp</code><br/><br/> + Contoh:<br/> + <code>w720dp</code><br/> + <code>w1024dp</code><br/> + dll. + </td> + <td> + <p>Menetapkan lebar layar minimum yang tersedia, di unit {@code dp} yang +menggunakan sumber daya—yang didefinisikan oleh nilai <code><N></code>. Nilai konfigurasi ini + akan berubah bila orientasi +berubah antara lanskap dan potret agar cocok dengan lebar sebenarnya saat ini.</p> + <p>Bila aplikasi Anda menyediakan beberapa direktori sumber daya dengan nilai yang berbeda + untuk konfigurasi ini, sistem akan menggunakan nilai terdekat dengan (tanpa melebihi) + lebar layar perangkat saat ini. Nilai +di sini memperhitungkan dekorasi layar akun, jadi jika perangkat memiliki beberapa +elemen UI persisten di tepi kiri atau kanan, layar +menggunakan nilai lebar yang lebih kecil daripada ukuran layar sebenarnya, yang memperhitungkan +elemen UI ini dan mengurangi ruang aplikasi yang tersedia.</p> + <p><em>Ditambahkan dalam API level 13.</em></p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#screenWidthDp} + yang menyimpan lebar layar saat ini.</p> + <p>Untuk informasi selengkapnya tentang mendesain untuk layar berbeda dan menggunakan +qualifier ini, lihat panduan pengembang <a href="{@docRoot}guide/practices/screens_support.html">Mendukung +Multi Layar</a>.</p> + </td> + </tr> + <tr id="ScreenHeightQualifier"> + <td>Tinggi yang tersedia</td> + <td><code>h<N>dp</code><br/><br/> + Contoh:<br/> + <code>h720dp</code><br/> + <code>h1024dp</code><br/> + dll. + </td> + <td> + <p>Menetapkan tinggi layar minimum yang tersedia, dalam satuan "dp" yang harus digunakan +sumber daya —bersama nilai yang didefinisikan oleh <code><N></code>. Nilai konfigurasi ini + akan berubah saat orientasi +berubah antara lanskap dan potret agar cocok dengan tinggi sebenarnya saat ini.</p> + <p>Bila aplikasi menyediakan beberapa direktori sumber daya dengan nilai yang berbeda + untuk konfigurasi ini, sistem akan menggunakan nilai yang terdekat dengan (tanpa melebihi) + tinggi layar perangkat saat ini. Nilai +di sini memperhitungkan dekorasi layar akun, jadi jika perangkat memiliki beberapa +elemen UI persisten di tepi atas atau bawah, layar akan +menggunakan nilai tinggi yang lebih kecil daripada ukuran layar sebenarnya, memperhitungkan +elemen UI ini dan mengurangi ruang aplikasi yang tersedia. Dekorasi +layar yang tidak tetap (misalnya baris status (status-bar) telepon yang bisa +disembunyikan saat layar penuh) di sini <em>tidak</em> diperhitungkan, demikian pula +dekorasi jendela seperti baris judul (title-bar)atau baris tindakan (action-bar), jadi aplikasi harus disiapkan +untuk menangani ruang yang agak lebih kecil daripada yang ditetapkan. + <p><em>Ditambahkan dalam API level 13.</em></p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#screenHeightDp} + yang menyimpan lebar layar saat ini.</p> + <p>Untuk informasi selengkapnya tentang mendesain untuk layar berbeda dan menggunakan +qualifier ini, lihat panduan pengembang <a href="{@docRoot}guide/practices/screens_support.html">Mendukung +Multi Layar</a>.</p> + </td> + </tr> + <tr id="ScreenSizeQualifier"> + <td>Ukuran layar</td> + <td> + <code>small</code><br/> + <code>normal</code><br/> + <code>large</code><br/> + <code>xlarge</code> + </td> + <td> + <ul class="nolist"> + <li>{@code small}: Layar yang berukuran serupa dengan +layar QVGA densitas rendah. Ukuran layout minimum untuk layar kecil +adalah sekitar 320x426 satuan dp. Misalnya QVGA densitas rendah +dan VGA densitas tinggi.</li> + <li>{@code normal}: Layar yang berukuran serupa dengan +layar HVGA densitas sedang. Ukuran layout minimum untuk +layar normal adalah sekitar 320x470 satuan dp. Contoh layar seperti itu adalah +WQVGA densitas rendah, HVGA densitas sedang, WVGA + densitas tinggi.</li> + <li>{@code large}: Layar yang berukuran serupa dengan +layar VGA densitas sedang. + Ukuran layout minimum untuk layar besar adalah sekitar 480x640 satuan dp. + Misalnya layar VGA dan WVGA densitas sedang.</li> + <li>{@code xlarge}: Layar yang jauh lebih besar dari layar HVGA +densitas sedang tradisional. Ukuran layout minimum untuk +layar ekstra besar adalah sekitar 720x960 satuan dp. Perangkat dengan layar ekstra besar +seringkali terlalu besar untuk dibawa dalam saku dan kemungkinan besar + berupa perangkat bergaya tablet. <em>Ditambahkan dalam API level 9.</em></li> + </ul> + <p class="note"><strong>Catatan:</strong> Menggunakan qualifier ukuran tidak berarti bahwa +sumber daya <em>hanya</em> untuk layar ukuran itu saja. Jika Anda tidak menyediakan sumber +daya alternatif dengan qualifier yang lebih cocok dengan konfigurasi perangkat saat ini, sistem dapat menggunakan sumber daya +mana saja yang <a href="#BestMatch">paling cocok</a>.</p> + <p class="caution"><strong>Perhatian:</strong> Jika semua sumber daya Anda menggunakan +qualifier yang berukuran <em>lebih besar</em> daripada layar saat ini, sistem <strong>tidak</strong> akan menggunakannya dan aplikasi +Anda akan crash saat runtime (misalnya, jika semua sumber daya layout ditandai dengan qualifier {@code +xlarge}, namun perangkat memiliki ukuran layar normal).</p> + <p><em>Ditambahkan dalam API level 4.</em></p> + + <p>Lihat <a href="{@docRoot}guide/practices/screens_support.html">Mendukung Beberapa +Layar</a> untuk informasi selengkapnya.</p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#screenLayout}, + yang menunjukkan apakah layar berukuran kecil, normal, atau +besar.</p> + </td> + </tr> + <tr id="ScreenAspectQualifier"> + <td>Aspek layar</td> + <td> + <code>long</code><br/> + <code>notlong</code> + </td> + <td> + <ul class="nolist"> + <li>{@code long}: Layar panjang, seperti WQVGA, WVGA, FWVGA</li> + <li>{@code notlong}: Layar tidak panjang, seperti QVGA, HVGA, dan VGA</li> + </ul> + <p><em>Ditambahkan dalam API level 4.</em></p> + <p>Ini berdasarkan sepenuhnya pada rasio aspek layar (layar "panjang" lebih lebar). Ini +tidak ada kaitannya dengan orientasi layar.</p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#screenLayout}, + yang menunjukkan apakah layar panjang.</p> + </td> + </tr> + <tr id="OrientationQualifier"> + <td>Orientasi layar</td> + <td> + <code>port</code><br/> + <code>land</code> <!-- <br/> + <code>square</code> --> + </td> + <td> + <ul class="nolist"> + <li>{@code port}: Perangkat dalam orientasi potret (vertikal)</li> + <li>{@code land}: Perangkat dalam orientasi lanskap (horizontal)</li> + <!-- Square mode is currently not used. --> + </ul> + <p>Ini bisa berubah selama masa pakai aplikasi Anda jika pengguna memutar +layar. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk + informasi tentang bagaimana hal ini memengaruhi aplikasi Anda selama runtime.</p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#orientation}, +yang menunjukkan orientasi perangkat saat ini.</p> + </td> + </tr> + <tr id="UiModeQualifier"> + <td>Mode UI</td> + <td> + <code>car</code><br/> + <code>desk</code><br/> + <code>television</code><br/> + <code>appliance</code> + <code>watch</code> + </td> + <td> + <ul class="nolist"> + <li>{@code car}: Perangkat sedang menampilkan di dudukan perangkat di mobil</li> + <li>{@code desk}: Perangkat sedang menampilkan di dudukan perangkat di meja</li> + <li>{@code television}: Perangkat sedang menampilkan di televisi, yang menyediakan +pengalaman "sepuluh kaki" dengan UI-nya pada layar besar yang berada jauh dari pengguna, +terutama diorientasikan seputar DPAD atau +interaksi non-pointer lainnya</li> + <li>{@code appliance}: Perangkat berlaku sebagai +alat, tanpa tampilan</li> + <li>{@code watch}: Perangkat memiliki tampilan dan dikenakan di pergelangan tangan</li> + </ul> + <p><em>Ditambahkan dalam API level 8, televisi ditambahkan dalam API 13, jam ditambahkan dalam API 20.</em></p> + <p>Untuk informasi tentang cara aplikasi merespons saat perangkat dimasukkan +ke dalam atau dilepaskan dari dudukannya, bacalah <a href="{@docRoot}training/monitoring-device-state/docking-monitoring.html">Menentukan +dan Memantau Kondisi dan Tipe Dudukan</a>.</p> + <p>Ini bisa berubah selama masa pakai aplikasi jika pengguna menempatkan perangkat di +dudukannya. Anda dapat mengaktifkan atau menonaktifkan sebagian mode ini menggunakan {@link +android.app.UiModeManager}. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk +informasi tentang bagaimana hal ini memengaruhi aplikasi Anda selama runtime.</p> + </td> + </tr> + <tr id="NightQualifier"> + <td>Mode malam</td> + <td> + <code>night</code><br/> + <code>notnight</code> + </td> + <td> + <ul class="nolist"> + <li>{@code night}: Waktu malam</li> + <li>{@code notnight}: Waktu siang</li> + </ul> + <p><em>Ditambahkan dalam API level 8.</em></p> + <p>Ini bisa berubah selama masa pakai aplikasi jika mode malam dibiarkan dalam +mode otomatis (default), dalam hal ini perubahan mode berdasarkan pada waktu hari. Anda dapat mengaktifkan +atau menonaktifkan mode ini menggunakan {@link android.app.UiModeManager}. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk informasi tentang bagaimana hal ini memengaruhi +aplikasi Anda selama runtime.</p> + </td> + </tr> + <tr id="DensityQualifier"> + <td>Densitas piksel layar (dpi)</td> + <td> + <code>ldpi</code><br/> + <code>mdpi</code><br/> + <code>hdpi</code><br/> + <code>xhdpi</code><br/> + <code>xxhdpi</code><br/> + <code>xxxhdpi</code><br/> + <code>nodpi</code><br/> + <code>tvdpi</code> + </td> + <td> + <ul class="nolist"> + <li>{@code ldpi}: Layar densitas rendah; sekitar 120 dpi.</li> + <li>{@code mdpi}: Layar densitas sedang (pada HVGA tradisional); sekitar 160 dpi. +</li> + <li>{@code hdpi}: Layar densitas tinggi; sekitar 240 dpi.</li> + <li>{@code xhdpi}: Layar densitas ekstra tinggi; sekitar 320 dpi. <em>Ditambahkan dalam API +Level 8.</em></li> + <li>{@code xxhdpi}: Layar densitas ekstra-ekstra-tinggi; sekitar 480 dpi. <em>Ditambahkan dalam API +Level 16.</em></li> + <li>{@code xxxhdpi}: Densitas ekstra-ekstra-ekstra-tinggi (hanya ikon launcher, +lihat <a href="{@docRoot}guide/practices/screens_support.html#xxxhdpi-note">catatan</a> + dalam <em>Mendukung Beberapa Layar</em>); sekitar 640 dpi. <em>Ditambahkan dalam API +Level 18.</em></li> + <li>{@code nodpi}: Ini bisa digunakan untuk sumber daya bitmap yang tidak ingin Anda +skalakan agar sama dengan densitas perangkat.</li> + <li>{@code tvdpi}: Layar antara mdpi dan hdpi; sekitar 213 dpi. Ini +tidak dianggap sebagai kelompok densitas "utama". Sebagian besar ditujukan untuk televisi dan kebanyakan +aplikasi tidak memerlukannya —asalkan sumber daya mdpi dan hdpi cukup untuk sebagian besar aplikasi dan +sistem akan menskalakan sebagaimana mestinya. Qualifier ini diperkenalkan pada API level 13.</li> + </ul> + <p>Terdapat rasio skala 3:4:6:8:12:16 antara enam densitas utama (dengan mengabaikan densitas +tvdpi). Jadi bitmap 9x9 di ldpi adalah 12x12 di mdpi, 18x18 di hdpi, 24x24 di xhdpi dan seterusnya. +</p> + <p>Jika Anda memutuskan bahwa sumber daya gambar tidak terlihat cukup baik di televisi +atau perangkat tertentu lainnya dan ingin mencoba sumber daya tvdpi, faktor skalanya adalah 1,33*mdpi. Misalnya, +gambar 100px x 100px untuk layar mdpi harus 133px x 133px untuk tvdpi.</p> + <p class="note"><strong>Catatan:</strong> Menggunakan qualifier densitas tidak berarti bahwa +sumber daya <em>hanya</em> untuk layar dengan ukuran itu saja. Jika Anda tidak menyediakan sumber +daya alternatif dengan qualifier yang lebih cocok dengan konfigurasi perangkat saat ini, sistem dapat menggunakan sumber daya +mana saja yang <a href="#BestMatch">paling cocok</a>.</p> + <p>Lihat <a href="{@docRoot}guide/practices/screens_support.html">Mendukung Beberapa +Layar</a> untuk informasi selengkapnya tentang cara menangani densitas layar yang berbeda dan cara Android +menurunkan skala bitmap Anda agar sesuai dengan densitas saat ini.</p> + </td> + </tr> + <tr id="TouchscreenQualifier"> + <td>Tipe layar sentuh</td> + <td> + <code>notouch</code><br/> + <code>finger</code> + </td> + <td> + <ul class="nolist"> + <li>{@code notouch}: Perangkat tidak memiliki layar sentuh.</li> + <li>{@code finger}: Perangkat memiliki layar sentuh yang dimaksudkan untuk +digunakan melalui interaksi dengan jari pengguna.</li> + </ul> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#touchscreen}, yang +menunjukkan tipe layar sentuh pada perangkat.</p> + </td> + </tr> + <tr id="KeyboardAvailQualifier"> + <td>Ketersediaan keyboard</td> + <td> + <code>keysexposed</code><br/> + <code>keyshidden</code><br/> + <code>keyssoft</code> + </td> + <td> + <ul class="nolist"> + <li>{@code keysexposed}: Perangkat menyediakan keyboard. Jika perangkat mengaktifkan +keyboard perangkat lunak (kemungkinan), ini dapat digunakan bahkan saat keyboard fisik +<em>tidak</em> diekspos kepada pengguna, meskipun perangkat tidak memiliki keyboard fisik. Jika keyboard +perangkat lunak tidak disediakan atau dinonaktifkan, maka ini hanya digunakan bila +keyboard fisik diekspos.</li> + <li>{@code keyshidden}: Perangkat memiliki keyboard fisik yang tersedia +tetapi tersembunyi <em>dan</em> perangkat <em>tidak</em> mengaktifkan keyboard perangkat lunak.</li> + <li>{@code keyssoft}: Perangkat mengaktifkan keyboard perangkat lunak, +baik itu terlihat maupun tidak.</li> + </ul> + <p>Jika Anda menyediakan sumber daya <code>keysexposed</code>, namun bukan sumber daya <code>keyssoft</code> +, sistem akan menggunakan sumber daya <code>keysexposed</code> baik keyboard +terlihat atau tidak, asalkan sistem telah mengaktifkan keyboard perangkat lunak.</p> + <p>Ini bisa berubah selama masa pakai aplikasi jika pengguna membuka keyboard +fisik. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk informasi tentang bagaimana +hal ini memengaruhi aplikasi Anda selama runtime.</p> + <p>Lihat juga bidang konfigurasi {@link +android.content.res.Configuration#hardKeyboardHidden} dan {@link +android.content.res.Configuration#keyboardHidden}, yang menunjukkan visibilitas +keyboard fisik dan visibilitas segala jenis keyboard (termasuk keyboard perangkat lunak), masing-masing.</p> + </td> + </tr> + <tr id="ImeQualifier"> + <td>Metode input teks utama</td> + <td> + <code>nokeys</code><br/> + <code>qwerty</code><br/> + <code>12key</code> + </td> + <td> + <ul class="nolist"> + <li>{@code nokeys}: Perangkat tidak memiliki tombol fisik untuk input teks.</li> + <li>{@code qwerty}: Perangkat memiliki keyboard fisik qwerty, baik terlihat maupun tidak pada +pengguna +.</li> + <li>{@code 12key}: Perangkat memiliki keyboard fisik 12 tombol, baik terlihat maupun tidak +pada pengguna.</li> + </ul> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#keyboard}, +yang menunjukkan metode utama input teks yang tersedia.</p> + </td> + </tr> + <tr id="NavAvailQualifier"> + <td>Ketersediaan tombol navigasi</td> + <td> + <code>navexposed</code><br/> + <code>navhidden</code> + </td> + <td> + <ul class="nolist"> + <li>{@code navexposed}: Tombol navigasi tersedia bagi pengguna.</li> + <li>{@code navhidden}: Tombol navigasi tidak tersedia (misalnya di balik penutup yang +ditutup).</li> + </ul> + <p>Ini bisa berubah selama masa pakai aplikasi jika pengguna menyingkap tombol +navigasi. Lihat <a href="runtime-changes.html">Menangani Perubahan Runtime</a> untuk +informasi tentang bagaimana hal ini memengaruhi aplikasi Anda selama runtime.</p> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#navigationHidden}, yang menunjukkan +apakah tombol navigasi disembunyikan.</p> + </td> + </tr> + <tr id="NavigationQualifier"> + <td>Metode navigasi non-sentuh utama</td> + <td> + <code>nonav</code><br/> + <code>dpad</code><br/> + <code>trackball</code><br/> + <code>wheel</code> + </td> + <td> + <ul class="nolist"> + <li>{@code nonav}: Perangkat tidak memiliki fasilitas navigasi selain menggunakan +layar sentuh.</li> + <li>{@code dpad}: Perangkat memiliki pad pengarah (directional pad / d-pad) untuk navigasi.</li> + <li>{@code trackball}: Perangkat memiliki trackball untuk navigasi.</li> + <li>{@code wheel}: Perangkat memiliki roda pengarah (directional wheel) untuk navigasi (tidak umum).</li> + </ul> + <p>Lihat juga bidang konfigurasi {@link android.content.res.Configuration#navigation}, +yang menunjukkan tipe metode navigasi yang tersedia.</p> + </td> + </tr> +<!-- DEPRECATED + <tr> + <td>Screen dimensions</td> + <td>Examples:<br/> + <code>320x240</code><br/> + <code>640x480</code><br/> + etc. + </td> + <td> + <p>The larger dimension must be specified first. <strong>This configuration is deprecated +and should not be used</strong>. Instead use "screen size," "wider/taller screens," and "screen +orientation" described above.</p> + </td> + </tr> +--> + <tr id="VersionQualifier"> + <td>Versi Platform (level API)</td> + <td>Contoh:<br/> + <code>v3</code><br/> + <code>v4</code><br/> + <code>v7</code><br/> + dll.</td> + <td> + <p>Level API yang didukung perangkat. Misalnya, <code>v1</code> untuk API level +1 (perangkat dengan Android 1.0 atau yang lebih tinggi) dan <code>v4</code> untuk API level 4 (perangkat dengan Android +1.6 atau yang lebih tinggi). Lihat dokumen <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">Level API Android</a> untuk informasi selengkapnya +tentang nilai-nilai ini.</p> + </td> + </tr> +</table> + + +<p class="note"><strong>Catatan:</strong> Sebagian qualifier konfigurasi telah ditambahkan sejak Android +1.0, jadi tidak semua versi Android mendukung semua qualifier. Menggunakan qualifier baru secara implisit +akan menambahkan qualifier versi platform sehingga perangkat yang lebih lama pasti mengabaikannya. Misalnya, menggunakan qualifier +<code>w600dp</code> secara otomatis akan menyertakan qualifier <code>v13</code>, karena +qualifier lebar yang tersedia baru di API level 13. Untuk menghindari masalah, selalu sertakan satu set +sumber daya default (satu set sumber daya <em>tanpa qualifier</em>). Untuk informasi selengkapnya, lihat +bagian tentang <a href="#Compatibility">Menyediakan Kompatibilitas Perangkat Terbaik dengan +Sumber Daya</a>.</p> + + + +<h3 id="QualifierRules">Aturan penamaan qualifier</h3> + +<p>Inilah beberapa aturan tentang penggunaan nama qualifier konfigurasi:</p> + +<ul> + <li>Anda bisa menetapkan beberapa qualifier untuk satu set sumber daya, yang dipisahkan dengan tanda hubung. Misalnya, +<code>drawable-en-rUS-land</code> berlaku untuk perangkat bahasa Inggris-AS dalam orientasi +lanskap.</li> + <li>Qualifier harus dalam urutan seperti yang tercantum dalam <a href="#table2">tabel 2</a>. +Misalnya: + <ul> + <li>Salah: <code>drawable-hdpi-port/</code></li> + <li>Benar: <code>drawable-port-hdpi/</code></li> + </ul> + </li> + <li>Direktori sumber daya alternatif tidak bisa digunakan. Misalnya, Anda tidak bisa memiliki +<code>res/drawable/drawable-en/</code>.</li> + <li>Nilai tidak membedakan huruf besar maupun kecil. Compiler sumber daya mengubah nama direktori +menjadi huruf kecil sebelum pemrosesan untuk menghindari masalah pada sistem file yang membedakan +huruf kecil dan besar. Setiap penggunaan huruf besar dalam nama hanyalah demi keterbacaan.</li> + <li>Hanya didukung satu nilai untuk setiap tipe qualifier. Misalnya, jika Anda ingin menggunakan +file drawable yang sama untuk Spanyol dan Prancis, Anda <em>tidak bisa</em> memiliki direktori bernama +<code>drawable-rES-rFR/</code>. Sebagai gantinya, Anda perlu dua direktori sumber daya, seperti +<code>drawable-rES/</code> dan <code>drawable-rFR/</code>, berisi file yang sesuai. +Akan tetapi, Anda tidak harus benar-benar menggandakan file yang sama di kedua lokasi. Sebagai gantinya, Anda +bisa membuat alias ke satu sumber daya. Lihat <a href="#AliasResources">Membuat +sumber daya alias</a> di bawah ini.</li> +</ul> + +<p>Setelah Anda menyimpan sumber daya alternatif ke dalam direktori yang diberi nama dengan +qualifier ini, Android secara otomatis menerapkan sumber daya dalam +aplikasi Anda berdasarkan pada konfigurasi perangkat saat ini. Setiap kali sumber daya diminta, Android akan memeriksa direktori sumber daya +alternatif berisi file sumber daya yang diminta, lalu <a href="#BestMatch">mencari sumber daya yang +paling cocok</a>(dibahas di bawah). Jika tidak ada sumber daya alternatif yang cocok +dengan konfigurasi perangkat tertentu, Android akan menggunakan sumber daya default terkait (set +sumber daya untuk tipe sumber daya tertentu yang tidak termasuk qualifier +konfigurasi).</p> + + + +<h3 id="AliasResources">Membuat sumber daya alias</h3> + +<p>Bila memiliki sumber daya yang ingin Anda gunakan untuk lebih dari satu konfigurasi +perangkat (namun tidak ingin menyediakannya sebagai sumber daya default), Anda tidak perlu menempatkan sumber daya +yang sama di lebih dari satu direktori sumber daya alternatif. Sebagai gantinya, (dalam beberapa kasus) Anda bisa membuat +sumber daya alternatif +yang berfungsi sebagai alias untuk sumber daya yang disimpan dalam direktori sumber daya default.</p> + +<p class="note"><strong>Catatan:</strong> Tidak semua sumber daya menawarkan mekanisme yang memungkinkan Anda +membuat alias ke sumber daya lain. Khususnya, animasi, menu, raw, dan +sumber daya lain yang tidak ditetapkan dalam direktori {@code xml/} tidak menawarkan fitur ini.</p> + +<p>Misalnya, bayangkan Anda memiliki ikon aplikasi {@code icon.png}, dan membutuhkan versi uniknya +untuk lokal berbeda. Akan tetapi, dua lokal, bahasa Inggris-Kanada dan bahasa Prancis-Kanada, harus menggunakan +versi yang sama. Anda mungkin berasumsi bahwa Anda perlu menyalin gambar +yang sama ke dalam direktori sumber daya baik untuk bahasa Inggris-Kanada maupun bahasa Prancis-Kanada, namun +bukan demikian. Sebagai gantinya, Anda bisa menyimpan gambar yang sama-sama digunakan sebagai {@code icon_ca.png} (nama +apa saja selain {@code icon.png}) dan memasukkannya +dalam direktori default {@code res/drawable/}. Lalu buat file {@code icon.xml} dalam {@code +res/drawable-en-rCA/} dan {@code res/drawable-fr-rCA/} yang mengacu ke sumber daya {@code icon_ca.png} +yang menggunakan elemen {@code <bitmap>}. Hal ini memungkinkan Anda menyimpan satu versi saja dari +file PNG dan dua file XML kecil yang menunjuk ke sana. (Contoh file XML ditampilkan di bawah.)</p> + + +<h4>Drawable</h4> + +<p>Untuk membuat alias ke drawable yang ada, gunakan elemen {@code <bitmap>}. +Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<bitmap xmlns:android="http://schemas.android.com/apk/res/android" + android:src="@drawable/icon_ca" /> +</pre> + +<p>Jika Anda menyimpan file ini sebagai {@code icon.xml} (dalam direktori sumber daya alternatif, seperti +{@code res/drawable-en-rCA/}), maka file akan dikompilasi menjadi sumber daya yang dapat Anda acu +sebagai {@code R.drawable.icon}, namun sebenarnya merupakan alias untuk sumber daya {@code +R.drawable.icon_ca} (yang disimpan dalam {@code res/drawable/}).</p> + + +<h4>Layout</h4> + +<p>Untuk membuat alias ke layout yang ada, gunakan elemen {@code <include>}, +yang dibungkus dalam {@code <merge>}. Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<merge> + <include layout="@layout/main_ltr"/> +</merge> +</pre> + +<p>Jika Anda menyimpan file ini sebagai {@code main.xml}, file akan dikompilasi menjadi sumber daya yang dapat Anda acu +sebagai {@code R.layout.main}, namun sebenarnya merupakan alias untuk sumber daya {@code R.layout.main_ltr} +.</p> + + +<h4>String dan nilai-nilai sederhana lainnya</h4> + +<p>Untuk membuat alias ke string yang ada, cukup gunakan ID sumber daya +dari string yang diinginkan sebagai nilai untuk string baru. Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string name="hello">Hello</string> + <string name="hi">@string/hello</string> +</resources> +</pre> + +<p>Sumber daya {@code R.string.hi} sekarang merupakan alias untuk {@code R.string.hello}.</p> + +<p> <a href="{@docRoot}guide/topics/resources/more-resources.html">Nilai sederhana lainnya</a> sama +cara kerjanya. Misalnya, sebuah warna:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <color name="yellow">#f00</color> + <color name="highlight">@color/red</color> +</resources> +</pre> + + + + +<h2 id="Compatibility">Menyediakan Kompatibilitas Perangkat Terbaik dengan Sumber Daya</h2> + +<p>Agar aplikasi Anda mendukung beberapa konfigurasi perangkat, +Anda harus selalu menyediakan sumber daya default untuk setiap tipe sumber daya yang menggunakan aplikasi Anda.</p> + +<p>Misalnya, jika aplikasi Anda mendukung beberapa bahasa, sertakan selalu direktori {@code +values/} (tempat string Anda disimpan) <em>tanpa</em> <a href="#LocaleQualifier">qualifier bahasa dan wilayah</a>. Jika sebaliknya Anda menempatkan semua file +string dalam direktori yang memiliki qualifier bahasa dan wilayah, maka aplikasi Anda akan crash saat berjalan +pada perangkat yang telah diatur ke bahasa yang tidak didukung string Anda. Namun asalkan Anda menyediakan sumber daya default +{@code values/}, aplikasi akan berjalan lancar (meskipun pengguna +tidak memahami bahasa itu—, ini lebih baik daripada crash).</p> + +<p>Demikian pula, jika Anda menyediakan sumber daya layout berbeda berdasarkan orientasi layar, Anda harus +memilih satu orientasi sebagai default. Misalnya, sebagai ganti menyediakan sumber daya dalam {@code +layout-land/} untuk lanskap dan {@code layout-port/} untuk potret, biarkan salah satu sebagai default, seperti +{@code layout/} untuk lanskap dan {@code layout-port/} untuk potret.</p> + +<p>Sumber daya default perlu disediakan bukan hanya karena aplikasi mungkin berjalan pada +konfigurasi yang belum Anda antisipasi, namun juga karena versi baru Android terkadang menambahkan +qualifier konfigurasi yang tidak didukung oleh versi lama. Jika Anda menggunakan qualifier sumber daya baru, +namun mempertahankan kompatibilitas kode dengan versi Android yang lebih lama, maka saat versi lama +Android menjalankan aplikasi, aplikasi itu akan crash jika Anda tidak menyediakan sumber daya default, aplikasi +tidak bisa menggunakan sumber daya yang dinamai dengan qualifier baru. Misalnya, jika <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +minSdkVersion}</a> Anda diatur ke 4, dan Anda memenuhi syarat semua sumber daya drawable dengan menggunakan <a href="#NightQualifier">mode malam</a> ({@code night} atau {@code notnight}, yang ditambahkan di API +Level 8), maka perangkat API level 4 tidak bisa mengakses sumber daya drawable dan akan crash. Dalam hal +ini, Anda mungkin ingin {@code notnight} menjadi sumber daya default, jadi Anda harus mengecualikan +qualifier itu agar sumber daya drawable Anda ada dalam {@code drawable/} atau {@code drawable-night/}.</p> + +<p>Jadi, agar bisa menyediakan kompatibilitas perangkat terbaik, sediakan selalu sumber daya +default untuk sumber daya yang diperlukan aplikasi Anda untuk berjalan dengan benar. Selanjutnya buatlah sumber daya +alternatif untuk konfigurasi perangkat tertentu dengan menggunakan qualifier konfigurasi.</p> + +<p>Ada satu eksepsi untuk aturan ini: Jika <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> aplikasi Anda adalah 4 atau +lebih, Anda <em>tidak</em> memerlukan sumber daya drawable default saat menyediakan sumber daya +drawable alternatif dengan qualifier <a href="#DensityQualifier">densitas layar</a>. Tanpa sumber daya +drawable default sekali pun, Android bisa menemukan yang paling cocok di antara densitas layar alternatif dan menskalakan +bitmap sesuai kebutuhan. Akan tetapi, demi pengalaman terbaik pada semua jenis perangkat, Anda harus +menyediakan drawable alternatif untuk ketiga tipe densitas.</p> + + + +<h2 id="BestMatch">Cara Android Menemukan Sumber Daya yang Paling Cocok</h2> + +<p>Saat Anda meminta sumber daya yang Anda berikan alternatifnya, Android akan memilih +sumber daya alternatif yang akan digunakan saat runtime, bergantung pada konfigurasi perangkat saat ini. Untuk +mendemonstrasikan cara Android memilih sumber daya alternatif, anggaplah direktori drawable berikut +masing-masing berisi versi berbeda dari gambar yang sama:</p> + +<pre class="classic no-pretty-print"> +drawable/ +drawable-en/ +drawable-fr-rCA/ +drawable-en-port/ +drawable-en-notouch-12key/ +drawable-port-ldpi/ +drawable-port-notouch-12key/ +</pre> + +<p>Dan anggaplah yang berikut ini merupakan konfigurasi perangkatnya:</p> + +<p style="margin-left:1em;"> +Lokal = <code>en-GB</code> <br/> +Orientasi layar = <code>port</code> <br/> +Densitas piksel layar = <code>hdpi</code> <br/> +Tipe layar sentuh = <code>notouch</code> <br/> +Metode input teks utama = <code>12key</code> +</p> + +<p>Dengan membandingkan konfigurasi perangkat dengan sumber daya alternatif yang tersedia, Android akan memilih +drawable dari {@code drawable-en-port}.</p> + +<p>Sistem akan menentukan keputusannya mengenai sumber daya yang akan digunakan dengan logika +berikut:</p> + + +<div class="figure" style="width:371px"> +<img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="471" /> +<p class="img-caption"><strong>Gambar 2.</strong> Bagan alur cara Android menemukan +sumber daya yang paling cocok.</p> +</div> + + +<ol> + <li>Menghapus file sumber daya yang bertentangan dengan konfigurasi perangkat. + <p>Direktori <code>drawable-fr-rCA/</code> dihapus karena bertentangan +dengan lokal <code>en-GB</code>.</p> +<pre class="classic no-pretty-print"> +drawable/ +drawable-en/ +<strike>drawable-fr-rCA/</strike> +drawable-en-port/ +drawable-en-notouch-12key/ +drawable-port-ldpi/ +drawable-port-notouch-12key/ +</pre> +<p class="note"><strong>Eksepsi:</strong> Densitas piksel layar adalah satu qualifier yang +tidak dihapus karena bertentangan. Meskipun densitas layar perangkat adalah hdpi, +<code>drawable-port-ldpi/</code> tidak dihapus karena setiap densitas layar +dianggap cocok untuk saat ini. Informasi selengkapnya tersedia dalam dokumen <a href="{@docRoot}guide/practices/screens_support.html">Mendukung Beberapa +Layar</a>.</p></li> + + <li>Pilih qualifier berkedudukan tertinggi (berikutnya) dalam daftar (<a href="#table2">tabel 2</a>). +(Mulai dengan MCC, lalu pindah ke bawah.) </li> + <li>Apakah salah satu direktori sumber daya menyertakan qualifier ini? </li> + <ul> + <li>Jika Tidak, kembali ke langkah 2 dan lihat qualifier berikutnya. (Dalam contoh, +jawabannya adalah "tidak" hingga qualifier bahasa tercapai.)</li> + <li>Jika Ya, lanjutkan ke langkah 4.</li> + </ul> + </li> + + <li>Hapus direktori sumber daya yang tidak menyertakan qualifier ini. Dalam contoh, sistem +menghapus semua direktori yang tidak menyertakan qualifier bahasa:</li> +<pre class="classic no-pretty-print"> +<strike>drawable/</strike> +drawable-en/ +drawable-en-port/ +drawable-en-notouch-12key/ +<strike>drawable-port-ldpi/</strike> +<strike>drawable-port-notouch-12key/</strike> +</pre> +<p class="note"><strong>Eksepsi:</strong> Jika qualifier yang dimaksud adalah densitas piksel layar, +Android akan memilih opsi yang paling cocok dengan densitas layar perangkat. +Secara umum, Android lebih suka menurunkan skala gambar asli yang lebih besar daripada menaikkan skala +atas gambar asli yang lebih kecil. Lihat <a href="{@docRoot}guide/practices/screens_support.html">Mendukung Beberapa +Layar</a>.</p> + </li> + + <li>Kembali dan ulangi langkah 2, 3, dan 4 hingga tersisa satu direktori. Dalam contoh ini, orientasi +layar adalah qualifier berikutnya yang memiliki kecocokan. +Jadi, sumber daya yang tidak menetapkan orientasi layar akan dihapus: +<pre class="classic no-pretty-print"> +<strike>drawable-en/</strike> +drawable-en-port/ +<strike>drawable-en-notouch-12key/</strike> +</pre> +<p>Direktori yang tersisa adalah {@code drawable-en-port}.</p> + </li> +</ol> + +<p>Meskipun prosedur dijalankan untuk setiap sumber daya yang diminta, sistem akan mengoptimalkan beberapa aspek +lebih lanjut. Satu optimalisasi tersebut adalah bahwa setelah konfigurasi perangkat diketahui, sistem mungkin +akan menghapus sumber daya alternatif yang sama sekali tidak cocok. Misalnya, jika bahasa konfigurasi +adalah bahasa Inggris ("en"), maka setiap direktori sumber daya yang memiliki qualifier bahasa akan diatur ke +selain bahasa Inggris tidak akan pernah disertakan dalam pool sumber daya yang diperiksa (meskipun +direktori sumber daya <em>tanpa</em> qualifier bahasa masih disertakan).</p> + +<p>Saat memilih sumber daya berdasarkan qualifier ukuran layar, sistem akan menggunakan +sumber daya yang didesain untuk layar yang lebih kecil daripada layar saat ini jika tidak ada sumber daya yang lebih cocok +(misalnya, layar ukuran besar akan menggunakan sumber daya layar ukuran normal jika diperlukan). Akan tetapi, +jika satu-satunya sumber daya yang tersedia <em>lebih besar</em> daripada layar saat ini, sistem +<strong>tidak</strong> akan menggunakannya dan aplikasi Anda akan crash jika tidak ada sumber daya lain yang cocok dengan konfigurasi +perangkat (misalnya, jika semua sumber daya layout ditandai dengan qualifier {@code xlarge}, +namun perangkat memiliki ukuran layar normal).</p> + +<p class="note"><strong>Catatan:</strong> <em>Kedudukan</em> qualifier (dalam <a href="#table2">tabel 2</a>) lebih penting +daripada jumlah qualifier yang benar-benar pas dengan perangkat. Misalnya, dalam langkah 4 di atas, pilihan +terakhir pada daftar berisi tiga qualifier yang bebar-benar cocok dengan perangkat (orientasi, tipe +layar sentuh, dan metode input), sementara <code>drawable-en</code> hanya memiliki satu parameter yang cocok +(bahasa). Akan tetapi, bahasa memiliki kedudukan lebih tinggi dari pada qualifier lainnya, sehingga +<code>drawable-port-notouch-12key</code> tidak masuk.</p> + +<p>Untuk mengetahui selengkapnya tentang cara menggunakan sumber daya dalam aplikasi, lanjutkan ke <a href="accessing-resources.html">Mengakses Sumber Daya</a>.</p> diff --git a/docs/html-intl/intl/in/guide/topics/resources/runtime-changes.jd b/docs/html-intl/intl/in/guide/topics/resources/runtime-changes.jd new file mode 100644 index 000000000000..c9a5ead63c77 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/resources/runtime-changes.jd @@ -0,0 +1,281 @@ +page.title=Menangani Perubahan Runtime +page.tags=aktivitas,daur hidup +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#RetainingAnObject">Mempertahankan Objek Selama Perubahan Konfigurasi</a></li> + <li><a href="#HandlingTheChange">Menangani Sendiri Perubahan Konfigurasi</a> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="providing-resources.html">Menyediakan Sumber Daya</a></li> + <li><a href="accessing-resources.html">Mengakses Sumber Daya</a></li> + <li><a href="http://android-developers.blogspot.com/2009/02/faster-screen-orientation-change.html">Perubahan + Orientasi Layar yang Lebih Cepat</a></li> + </ol> +</div> +</div> + +<p>Sebagian konfigurasi perangkat bisa berubah selama runtime +(seperti orientasi layar, ketersediaan keyboard, dan bahasa). Saat perubahan demikian terjadi, +Android akan me-restart +{@link android.app.Activity} yang berjalan ({@link android.app.Activity#onDestroy()} dipanggil, diikuti oleh {@link +android.app.Activity#onCreate(Bundle) onCreate()}). Perilaku restart didesain untuk membantu +aplikasi Anda beradaptasi dengan konfigurasi baru melalui pemuatan kembali aplikasi Anda secara otomatis dengan +sumber daya alternatif sumber yang sesuai dengan konfigurasi perangkat baru.</p> + +<p>Untuk menangani restart dengan benar, aktivitas Anda harus mengembalikan +statusnya seperti semula melalui <a href="{@docRoot}guide/components/activities.html#Lifecycle">Daur hidup +aktivitas</a> normal, dalam hal ini Android akan memanggil +{@link android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()} sebelum menghentikan +aktivitas Anda sehingga Anda dapat menyimpan data mengenai status aplikasi. Selanjutnya Anda bisa mengembalikan status +selama {@link android.app.Activity#onCreate(Bundle) onCreate()} atau {@link +android.app.Activity#onRestoreInstanceState(Bundle) onRestoreInstanceState()}.</p> + +<p>Untuk menguji bahwa aplikasi me-restart sendiri dengan status tak berubah, Anda harus +memanggil perubahan konfigurasi (seperti mengubah orientasi layar) saat melakukan berbagai +tugas dalam aplikasi. Aplikasi Anda harus dapat me-restart setiap saat tanpa kehilangan +data pengguna atau status untuk menangani kejadian seperti perubahan konfigurasi atau bila pengguna menerima panggilan telepon +masuk lalu kembali ke aplikasi setelah proses +aplikasi Anda dimusnahkan. Untuk mengetahui cara mengembalikan status aktivitas, bacalah tentang <a href="{@docRoot}guide/components/activities.html#Lifecycle">Daur hidup aktivitas</a>.</p> + +<p>Akan tetapi, Anda mungkin menemui situasi ketika me-restart aplikasi dan +mengembalikan data dalam jumlah besar malah menjadi mahal dan menghasilkan pengalaman pengguna yang buruk. Dalam situasi +demikian, Anda memiliki dua opsi lain:</p> + +<ol type="a"> + <li><a href="#RetainingAnObject">Mempertahankan objek selama perubahan konfigurasi</a> + <p>Izinkan aktivitas Anda me-restart saat konfigurasi berubah, namun bawa objek +berstatus (stateful) ke instance baru aktivitas Anda.</p> + + </li> + <li><a href="#HandlingTheChange">Menangani sendiri perubahan konfigurasi</a> + <p>Cegah sistem me-restart aktivitas selama perubahan konfigurasi +tertentu, namun terima callback saat konfigurasi benar-benar berubah, agar Anda bisa memperbarui +aktivitas secara manual bila diperlukan.</p> + </li> +</ol> + + +<h2 id="RetainingAnObject">Mempertahankan Objek Selama Perubahan Konfigurasi</h2> + +<p>Jika me-restart aktivitas mengharuskan pemulihan seperangkat data dalam jumlah besar, menghubungkan kembali koneksi +jaringan, atau melakukan operasi intensif lainnya, maka restart penuh karena perubahan konfigurasi mungkin +menjadi pengalaman pengguna yang lambat. Selain itu, Anda mungkin tidak bisa sepenuhnya mengembalikan status +aktivitas dengan {@link android.os.Bundle} yang disimpan sistem untuk Anda dengan callback {@link +android.app.Activity#onSaveInstanceState(Bundle) onSaveInstanceState()}—itu tidaklah +didesain untuk membawa objek besar (seperti bitmap) dan data di dalamnya harus diserialkan kemudian +dinon-serialkan, yang bisa menghabiskan banyak memori dan membuat perubahan konfigurasi menjadi lambat. Dalam situasi +demikian, Anda bisa meringankan beban memulai kembali aktivitas Anda dengan mempertahankan {@link +android.app.Fragment} saat aktivitas Anda di-restart karena perubahan konfigurasi. Fragmen ini +bisa berisi acuan ke objek stateful yang ingin Anda pertahankan.</p> + +<p>Bila sistem Android menghentikan aktivitas Anda karena perubahan konfigurasi, fragmen +aktivitas yang telah ditandai untuk dipertahankan tidak akan dimusnahkan. Anda dapat menambahkan fragmen tersebut ke +aktivitas untuk mempertahankan objek stateful.</p> + +<p>Untuk mempertahankan objek stateful dalam fragmen selama perubahan konfigurasi runtime:</p> + +<ol> + <li>Perluas kelas {@link android.app.Fragment} dan deklarasikan referensi ke objek stateful +Anda.</li> + <li>Panggil {@link android.app.Fragment#setRetainInstance(boolean)} saat fragmen dibuat. + </li> + <li>Tambahkan fragmen ke aktivitas.</li> + <li>Gunakan {@link android.app.FragmentManager} untuk mengambil fragmen saat aktivitas +di-restart.</li> +</ol> + +<p>Misalnya, definisikan fragmen sebagai berikut:</p> + +<pre> +public class RetainedFragment extends Fragment { + + // data object we want to retain + private MyDataObject data; + + // this method is only called once for this fragment + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + // retain this fragment + setRetainInstance(true); + } + + public void setData(MyDataObject data) { + this.data = data; + } + + public MyDataObject getData() { + return data; + } +} +</pre> + +<p class="caution"><strong>Perhatian:</strong> Meskipun bisa menyimpan objek apa saja, Anda +sama sekali tidak boleh meneruskan objek yang terkait dengan {@link android.app.Activity}, seperti {@link +android.graphics.drawable.Drawable}, {@link android.widget.Adapter}, {@link android.view.View} +atau objek lainnya mana pun yang terkait dengan {@link android.content.Context}. Jika Anda melakukannya, hal tersebut akan +membocorkan semua tampilan dan sumber daya instance aktivitas semula. (Sumber daya yang bocor +berarti bahwa aplikasi Anda tetap menyimpannya dan tidak bisa dijadikan kumpulan sampah, sehingga bisa banyak +memori yang hilang.)</p> + +<p>Selanjutnya gunakan {@link android.app.FragmentManager} untuk menambahkan fragmen ke aktivitas. +Anda bisa memperoleh objek data dari fragmen saat aktivitas memulai kembali selama perubahan +konfigurasi runtime. Misalnya, definisikan aktivitas Anda sebagai berikut:</p> + +<pre> +public class MyActivity extends Activity { + + private RetainedFragment dataFragment; + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // find the retained fragment on activity restarts + FragmentManager fm = getFragmentManager(); + dataFragment = (DataFragment) fm.findFragmentByTag(“data”); + + // create the fragment and data the first time + if (dataFragment == null) { + // add the fragment + dataFragment = new DataFragment(); + fm.beginTransaction().add(dataFragment, “data”).commit(); + // load the data from the web + dataFragment.setData(loadMyData()); + } + + // the data is available in dataFragment.getData() + ... + } + + @Override + public void onDestroy() { + super.onDestroy(); + // store the data in the fragment + dataFragment.setData(collectMyLoadedData()); + } +} +</pre> + +<p>Dalam contoh ini, {@link android.app.Activity#onCreate(Bundle) onCreate()} menambahkan fragmen +atau mengembalikan referensinya. {@link android.app.Activity#onCreate(Bundle) onCreate()} juga +menyimpan objek stateful dalam instance fragmen. +{@link android.app.Activity#onDestroy() onDestroy()} akan memperbarui objek stateful dalam +instance fragmen yang dipertahankan.</p> + + + + + +<h2 id="HandlingTheChange">Menangani Sendiri Perubahan Konfigurasi</h2> + +<p>Jika aplikasi Anda tidak memerlukan pembaruan sumber daya selama perubahan konfigurasi +tertentu <em>dan</em> Anda memiliki keterbatasan kinerja yang mengharuskan Anda untuk +menghindari restart aktivitas, maka Anda bisa mendeklarasikan agar aktivitas Anda menangani sendiri perubahan +konfigurasinya, sehingga mencegah sistem me-restart aktivitas.</p> + +<p class="note"><strong>Catatan:</strong> Menangani sendiri perubahan konfigurasi bisa jauh lebih +mempersulit penggunaan sumber daya alternatif, karena sistem tidak menerapkannya secara otomatis +untuk Anda. Teknik ini harus dianggap sebagai usaha terakhir bila Anda harus menghindari restart +karena perubahan konfigurasi dan tidak disarankan untuk sebagian besar aplikasi.</p> + +<p>Untuk mendeklarasikan agar aktivitas Anda menangani perubahan konfigurasi, edit elemen <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> yang sesuai +dalam file manifes Anda agar menyertakan atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code +android:configChanges}</a> dengan nilai yang mewakili konfigurasi yang ingin +ditangani. Nilai yang memungkinkan tercantum dalam dokumentasi untuk atribut <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code +android:configChanges}</a> (nilai paling sering digunakan adalah {@code "orientation"} untuk +mencegah restart saat orientasi layar berubah dan {@code "keyboardHidden"} untuk mencegah +restart saat ketersediaan keyboard berubah). Anda dapat mendeklarasikan beberapa nilai konfigurasi +dalam atribut dengan memisahkannya menggunakan karakter pipa {@code |}.</p> + +<p>Misalnya, kode manifes berikut menyatakan aktivitas yang menangani +perubahan orientasi layar maupun perubahan ketersediaan keyboard:</p> + +<pre> +<activity android:name=".MyActivity" + android:configChanges="orientation|keyboardHidden" + android:label="@string/app_name"> +</pre> + +<p>Sekarang, bila salah satu konfigurasi ini berubah, {@code MyActivity} tidak akan me-restart. +Sebagai gantinya, {@code MyActivity} akan menerima panggilan ke {@link +android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. Metode ini +meneruskan objek {@link android.content.res.Configuration} yang menetapkan +konfigurasi perangkat baru. Dengan membaca bidang-bidang dalam {@link android.content.res.Configuration}, +Anda dapat menentukan konfigurasi baru dan membuat perubahan yang sesuai dengan memperbarui +sumber daya yang digunakan dalam antarmuka. Pada saat +metode ini dipanggil, objek {@link android.content.res.Resources} aktivitas Anda akan diperbarui untuk +mengembalikan sumber daya berdasarkan konfigurasi baru, jadi Anda bisa dengan mudah +me-reset elemen UI tanpa membuat sistem me-restart aktivitas Anda.</p> + +<p class="caution"><strong>Perhatian:</strong> Mulai Android 3.2 (API level 13), <strong> +"ukuran layar" juga berubah</strong> bila perangkat beralih orientasi antara potret +dan lanskap. Jadi jika Anda tidak ingin runtime di-restart karena perubahan orientasi saat mengembangkan +API level 13 atau yang lebih tinggi (sebagaimana dideklarasikan oleh atribut <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> dan <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> +), Anda harus menyertakan nilai {@code "screenSize"} selain nilai {@code +"orientation"}. Yaitu Anda harus mendeklarasikan {@code +android:configChanges="orientation|screenSize"}. Akan tetapi, jika aplikasi Anda menargetkan API level +12 atau yang lebih rendah, maka aktivitas Anda akan selalu menangani sendiri perubahan konfigurasi ini (perubahan +konfigurasi ini tidak me-restart aktivitas Anda, bahkan saat berjalan pada perangkat Android 3.2 atau yang lebih tinggi).</p> + +<p>Misalnya, implementasi {@link +android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()} berikut akan +memeriksa orientasi perangkat saat ini:</p> + +<pre> +@Override +public void onConfigurationChanged(Configuration newConfig) { + super.onConfigurationChanged(newConfig); + + // Checks the orientation of the screen + if (newConfig.orientation == Configuration.ORIENTATION_LANDSCAPE) { + Toast.makeText(this, "landscape", Toast.LENGTH_SHORT).show(); + } else if (newConfig.orientation == Configuration.ORIENTATION_PORTRAIT){ + Toast.makeText(this, "portrait", Toast.LENGTH_SHORT).show(); + } +} +</pre> + +<p>Objek {@link android.content.res.Configuration} mewakili semua konfigurasi +saat ini, tidak hanya konfigurasi yang telah berubah. Seringkali Anda tidak perlu memperhatikan dengan persis bagaimana +konfigurasi berubah dan cukup menetapkan kembali semua sumber daya yang memberikan alternatif untuk +konfigurasi sedang ditangani. Misalnya, karena objek {@link +android.content.res.Resources} sekarang diperbarui, Anda dapat me-reset +setiap {@link android.widget.ImageView} dengan {@link android.widget.ImageView#setImageResource(int) +setImageResource()} +dan sumber daya yang sesuai untuk konfigurasi baru yang digunakan (seperti dijelaskan dalam <a href="providing-resources.html#AlternateResources">Menyediakan Sumber Daya</a>).</p> + +<p>Perhatikan bahwa nilai-nilai dari bidang {@link +android.content.res.Configuration} adalah integer yang sesuai dengan konstanta spesifik +dari kelas {@link android.content.res.Configuration}. Untuk dokumentasi tentang konstanta +yang harus digunakan di setiap bidang, lihat bidang yang sesuai dalam referensi {@link +android.content.res.Configuration}.</p> + +<p class="note"><strong>Ingatlah:</strong> Saat mendeklarasikan aktivitas untuk menangani perubahan +konfigurasi, Anda bertanggung jawab untuk me-reset setiap elemen yang alternatifnya Anda berikan. Jika Anda +mendeklarasikan aktivitas untuk menangani perubahan orientasi dan memiliki gambar yang harus berubah +antara lanskap dan potret, Anda harus menetapkan kembali setiap sumber daya elemen selama {@link +android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}.</p> + +<p>Jika Anda tidak perlu memperbarui aplikasi berdasarkan perubahan +konfigurasi ini, sebagai gantinya Anda bisa saja <em>tidak</em> mengimplementasikan {@link +android.app.Activity#onConfigurationChanged(Configuration) onConfigurationChanged()}. Dalam +hal ini, semua sumber daya yang digunakan sebelum perubahan konfigurasi akan tetap digunakan +dan Anda hanya menghindari restart aktivitas. Akan tetapi, aplikasi Anda harus selalu +bisa dimatikan dan di-restart dengan status sebelumnya tetap utuh, sehingga Anda jangan menganggap teknik +ini sebagai jalan keluar untuk mempertahankan status selama daur hidup aktivitas normal. Tidak hanya +karena ada perubahan konfigurasi lainnya yang tidak bisa Anda cegah untuk me-restart aplikasi, namun +juga karena Anda harus menangani kejadian seperti saat pengguna meninggalkan aplikasi dan +dimusnahkan sebelum pengguna kembali ke aplikasi.</p> + +<p>Untuk informasi selengkapnya tentang perubahan konfigurasi yang bisa Anda tangani dalam aktivitas, lihat dokumentasi <a href="{@docRoot}guide/topics/manifest/activity-element.html#config">{@code +android:configChanges}</a> dan kelas {@link android.content.res.Configuration} +.</p> diff --git a/docs/html-intl/intl/in/guide/topics/ui/controls.jd b/docs/html-intl/intl/in/guide/topics/ui/controls.jd new file mode 100644 index 000000000000..7ee2957980a8 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/controls.jd @@ -0,0 +1,90 @@ +page.title=Kontrol Input +parent.title=Antarmuka Pengguna +parent.link=index.html +@jd:body + +<div class="figure" style="margin:0"> + <img src="{@docRoot}images/ui/ui-controls.png" alt="" style="margin:0" /> +</div> + +<p>Kontrol input adalah komponen interaktif dalam antarmuka pengguna aplikasi Anda. Android menyediakan +aneka ragam kontrol yang bisa Anda gunakan dalam UI, seperti tombol, bidang teks, bilah pencarian, +kotak cek, tombol zoom, tombol toggle, dan masih banyak lagi.</p> + +<p>Menambahkan sebuah kontrol input ke UI adalah semudah menambahkan satu elemen XML ke <a href="{@docRoot}guide/topics/ui/declaring-layout.html">layout XML</a>. Misalnya, inilah sebuah +layout dengan satu bidang teks dan satu tombol:</p> + +<pre style="clear:right"> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="horizontal"> + <EditText android:id="@+id/edit_message" + android:layout_weight="1" + android:layout_width="0dp" + android:layout_height="wrap_content" + android:hint="@string/edit_message" /> + <Button android:id="@+id/button_send" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/button_send" + android:onClick="sendMessage" /> +</LinearLayout> +</pre> + +<p>Tiap kontrol input mendukung satu set kejadian input sehingga Anda bisa menangani berbagai kejadian seperti saat +pengguna memasukkan teks atau menyentuh tombol.</p> + + +<h2 id="CommonControls">Kontrol Umum</h2> +<p>Berikut adalah daftar beberapa kontrol umum yang bisa Anda gunakan dalam aplikasi. Ikuti tautan ini untuk mengetahui +selengkapnya tentang penggunaannya masing-masing.</p> + +<p class="note"><strong>Catatan:</strong> Android menyediakan beberapa kontrol lain yang tidak tercantum +di sini. Telusuri paket {@link android.widget} untuk mengetahui selengkapnya. Jika aplikasi Anda memerlukan +semacam kontrol input tertentu, Anda bisa membangun <a href="{@docRoot}guide/topics/ui/custom-components.html">komponen custom</a> sendiri.</p> + +<table> + <tr> + <th scope="col">Tipe Kontrol</th> + <th scope="col">Keterangan</th> + <th scope="col">Kelas Terkait</th> + </tr> + <tr> + <td><a href="controls/button.html">Tombol</a></td> + <td>Tombol tekan yang bisa ditekan, atau diklik, oleh pengguna untuk melakukan suatu tindakan.</td> + <td>{@link android.widget.Button Button} </td> + </tr> + <tr> + <td><a href="controls/text.html">Bidang teks</a></td> + <td>Bidang teks yang bisa diedit. Anda bisa menggunakan widget <code>AutoCompleteTextView</code> untuk membuat widget entri teks yang menyediakan saran pelengkapan otomatis</td> + <td>{@link android.widget.EditText EditText}, {@link android.widget.AutoCompleteTextView}</td> + </tr> + <tr> + <td><a href="controls/checkbox.html">Kotak cek</a></td> + <td>Switch aktif/nonaktif yang bisa diubah oleh pengguna. Anda harus menggunakan kotak cek saat menampilkan sekumpulan opsi yang bisa dipilih pengguna dan bila keduanya mungkin terjadi bersamaan.</td> + <td>{@link android.widget.CheckBox CheckBox} </td> + </tr> + <tr> + <td><a href="controls/radiobutton.html">Tombol radio</a></td> + <td>Mirip dengan kotak cek, hanya saja cuma satu opsi yang bisa dipilih dalam kumpulan tersebut.</td> + <td>{@link android.widget.RadioGroup RadioGroup} + <br>{@link android.widget.RadioButton RadioButton} </td> + </tr> + <tr> + <td><a href="controls/togglebutton.html" style="white-space:nowrap">Tombol toggle</a></td> + <td>Tombol aktif/nonaktif dengan indikator cahaya.</td> + <td>{@link android.widget.ToggleButton ToggleButton} </td> + </tr> + <tr> + <td><a href="controls/spinner.html">Spinner</a></td> + <td>Daftar tarik-turun yang memungkinkan pengguna memilih salah satu dari serangkaian nilai.</td> + <td>{@link android.widget.Spinner Spinner} </td> + </tr> + <tr> + <td><a href="controls/pickers.html">Picker</a></td> + <td>Dialog bagi pengguna untuk memilih satu nilai dari satu kumpulan dengan menggunakan tombol naik/turun atau dengan gerakan mengusap. Gunakan widget <code>DatePicker</code>code> untuk memasukkan nilai tanggal (bulan, hari, tahun) atau widget <code>TimePicker</code> untuk memasukkan nilai waktu (jam, menit, AM/PM), yang akan diformat secara otomatis untuk lokasi pengguna tersebut.</td> + <td>{@link android.widget.DatePicker}, {@link android.widget.TimePicker}</td> + </tr> +</table> diff --git a/docs/html-intl/intl/in/guide/topics/ui/declaring-layout.jd b/docs/html-intl/intl/in/guide/topics/ui/declaring-layout.jd new file mode 100644 index 000000000000..83ff7461e7ac --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/declaring-layout.jd @@ -0,0 +1,492 @@ +page.title=Layout +page.tags=view,viewgroup +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#write">Tulis XML</a></li> + <li><a href="#load">Muat Sumber Daya XML</a></li> + <li><a href="#attributes">Atribut</a> + <ol> + <li><a href="#id">ID</a></li> + <li><a href="#layout-params">Parameter Layout</a></li> + </ol> + </li> + <li><a href="#Position">Posisi Layout</a></li> + <li><a href="#SizePaddingMargins">Ukuran, Pengisi, dan Margin</a></li> + <li><a href="#CommonLayouts">Layout Umum</a></li> + <li><a href="#AdapterViews">Membangun Layout dengan Adaptor</a> + <ol> + <li><a href="#FillingTheLayout">Mengisi tampilan adaptor dengan data</a></li> + <li><a href="#HandlingUserSelections">Menangani kejadian klik</a></li> + </ol> + </li> +</ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.view.View}</li> + <li>{@link android.view.ViewGroup}</li> + <li>{@link android.view.ViewGroup.LayoutParams}</li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="{@docRoot}training/basics/firstapp/building-ui.html">Membangun Antarmuka Pengguna +Sederhana</a></li> </div> +</div> + +<p>Layout mendefinisikan struktur visual untuk antarmuka pengguna, seperti UI sebuah <a href="{@docRoot}guide/components/activities.html">aktivitas</a> atau <a href="{@docRoot}guide/topics/appwidgets/index.html">widget aplikasi</a>. +Anda dapat mendeklarasikan layout dengan dua cara:</p> +<ul> +<li><strong>Deklarasikan elemen UI dalam XML</strong>. Android menyediakan sebuah kosakata XML +sederhana yang sesuai dengan kelas dan subkelas View, seperti halnya untuk widget dan layout.</li> +<li><strong>Buat instance elemen layout saat runtime</strong>. Aplikasi Anda +bisa membuat objek View dan ViewGroup (dan memanipulasi propertinya) lewat program. </li> +</ul> + +<p>Kerangka kerja Android memberi Anda fleksibilitas untuk menggunakan salah satu atau kedua metode ini guna mendeklarasikan dan mengelola UI aplikasi Anda. Misalnya, Anda bisa mendeklarasikan layout default aplikasi Anda dalam XML, termasuk elemen-elemen layar yang akan muncul di dalamnya dan di propertinya. Anda nanti bisa menambahkan kode dalam aplikasi yang akan memodifikasi status objek layar, termasuk yang dideklarasikan dalam XML, saat runtime. </p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <ul> + <li><a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT + Plugin for Eclipse</a> menawarkan preview layout XML — + Anda dengan file XML yang dibuka, pilih tab <strong>Layout</strong>.</li> + <li>Anda juga harus mencoba alat + <a href="{@docRoot}tools/debugging/debugging-ui.html#hierarchyViewer">Hierarchy Viewer</a>, + untuk merunut layout — alat ini akan menampilkan nilai-nilai properti layout, + menggambar bentuk kerangka dengan indikator pengisi/margin, dan tampilan yang dirender penuh selagi + Anda merunut pada emulator atau perangkat.</li> + <li>Alat <a href="{@docRoot}tools/debugging/debugging-ui.html#layoutopt">layoutopt</a> memungkinkan + Anda menganalisis layout dan hierarki dengan untuk mengetahui ketidakefisienan atau masalah lainnya.</li> +</div> +</div> + +<p>Keuntungan mendeklarasikan UI dalam XML adalah karena hal ini memungkinkan Anda memisahkan penampilan aplikasi dari kode yang mengontrol perilakunya dengan lebih baik. Keterangan UI Anda bersifat eksternal bagi kode aplikasi Anda, yang berarti bahwa Anda bisa memodifikasi atau menyesuaikannya tanpa harus memodifikasi dan mengompilasi ulang kode sumber. Misalnya, Anda bisa membuat layout XML untuk berbagai orientasi layar, berbagai ukuran layar perangkat, dan berbagai bahasa. Selain itu, mendeklarasikan layout dalam XML akan mempermudah Anda memvisualisasikan struktur UI, sehingga lebih mudah merunut masalahnya. Karena itu, dokumen ini berfokus pada upaya mengajari Anda cara mendeklarasikan layout dalam XML. Jika Anda +tertarik dalam membuat instance objek View saat runtime, lihat referensi kelas {@link android.view.ViewGroup} dan +{@link android.view.View}.</p> + +<p>Secara umum, kosakata XML untuk mendeklarasikan elemen UI mengikuti dengan sangat mirip struktur serta penamaan kelas dan metode, dengan nama elemen dipadankan dengan nama kelas dan nama atribut dipadankan dengan metode. Sebenarnya, pemadanan ini kerap kali begitu jelas sehingga Anda bisa menebak atribut XML yang berpadanan dengan sebuah metode kelas, atau menebak kelas yang berpadanan dengan sebuah elemen XML. Akan tetapi, perhatikan bahwa tidak semua kosakata identik. Dalam beberapa kasus, ada sedikit perbedaan penamaan. Misalnya +, elemen EditText memiliki atribut <code>text</code> yang berpadanan dengan +<code>EditText.setText()</code>. </p> + +<p class="note"><strong>Tip:</strong> Ketahui selengkapnya berbagai tipe layout dalam <a href="{@docRoot}guide/topics/ui/layout-objects.html">Objek +Layout Umum</a>. Ada juga sekumpulan tutorial tentang cara membangun berbagai layout dalam panduan tutorial +<a href="{@docRoot}resources/tutorials/views/index.html">Hello Views</a>.</p> + +<h2 id="write">Tulis XML</h2> + +<p>Dengan menggunakan kosakata XML Android, Anda bisa mendesain secara cepat layout UI dan elemen layar yang dimuatnya, sama dengan cara membuat halaman web dalam HTML — dengan serangkaian elemen tersarang. </p> + +<p>Tiap file layout harus berisi persis satu elemen akar, yang harus berupa sebuah objek View atau ViewGroup. Setelah mendefinisikan elemen akar, Anda bisa menambahkan objek atau widget layout tambahan sebagai elemen anak untuk membangun hierarki View yang mendefinisikan layout Anda secara bertahap. Misalnya, inilah layout XML yang menggunakan {@link android.widget.LinearLayout} +vertikal untuk menyimpan {@link android.widget.TextView} dan {@link android.widget.Button}:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="match_parent" + android:layout_height="match_parent" + android:orientation="vertical" > + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a TextView" /> + <Button android:id="@+id/button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a Button" /> +</LinearLayout> +</pre> + +<p>Setelah Anda mendeklarasikan layout dalam XML, simpanlah file dengan ekstensi <code>.xml</code>, +dalam direktori <code>res/layout/</code> proyek Android, sehingga nanti bisa dikompilasi dengan benar. </p> + +<p>Informasi selengkapnya tentang sintaks untuk file XML layout tersedia dalam dokumen <a href="{@docRoot}guide/topics/resources/layout-resource.html">Sumber Daya Layout</a>.</p> + +<h2 id="load">Muat Sumber Daya XML</h2> + +<p>Saat mengompilasi aplikasi, masing-masing file layout XML akan dikompilasi dalam sebuah sumber daya +{@link android.view.View}. Anda harus memuat sumber daya layout dari kode aplikasi, dalam implementasi +callback {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()}. +Lakukan dengan memanggil <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, +dengan meneruskan acuan ke sumber daya layout berupa: +<code>R.layout.<em>layout_file_name</em></code>. +Misalnya, jika XML layout Anda disimpan sebagai <code>main_layout.xml</code>, Anda akan memuatnya +untuk Activity seperti ini:</p> +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main_layout); +} +</pre> + +<p>Metode callback <code>onCreate()</code> dalam Activity dipanggil oleh kerangka kerja Android saat +Activity Anda dijalankan (lihat diskusi tentang daur hidup, dalam dokumen +<a href="{@docRoot}guide/components/activities.html#Lifecycle">Aktivitas</a> +).</p> + + +<h2 id="attributes">Atribut</h2> + +<p>Setiap objek View dan ViewGroup mendukung variasi atribut XML-nya sendiri. +Sebagian atribut bersifat spesifik untuk objek View (misalnya, TextView mendukung atribut <code>textSize</code> +), namun atribut ini juga diwarisi oleh sembarang objek View yang dapat memperluas kelas ini. +Sebagian atribut bersifat umum untuk semua objek View, karena diwarisi dari kelas View akar (seperti +atribut <code>id</code>). Dan, atribut lain dianggap sebagai "parameter layout" yaitu +atribut yang menjelaskan orientasi layout tertentu dari objek View, seperti yang didefinisikan oleh objek ViewGroup induk +dari objek itu.</p> + +<h3 id="id">ID</h3> + +<p>Objek View apa saja dapat memiliki ID integer yang dikaitkan dengannya, untuk mengidentifikasi secara unik View dalam pohon. +Bila aplikasi dikompilasi, ID ini akan diacu sebagai integer, namun ID biasanya +ditetapkan dalam file XML layout sebagai string, dalam atribut <code>id</code>. +Ini atribut XML yang umum untuk semua objek View +(yang didefinisikan oleh kelas {@link android.view.View}) dan Anda akan sering sekali menggunakannya. +Sintaks untuk ID dalam tag XML adalah:</p> +<pre>android:id="@+id/my_button"</pre> + +<p>Simbol "at" (@) pada awal string menunjukkan parser XML harus mengurai dan memperluas +ID string selebihnya dan mengenalinya sebagai ID sumber daya. Simbol tanda tambah (+) berarti ini nama sumber daya baru yang harus +dibuat dan ditambahkan ke sumber daya kita (dalam file <code>R.java</code>). Ada sejumlah sumber daya ID lain yang +ditawarkan oleh kerangka kerja Android. Saat mengacu sebuah ID sumber daya Android, Anda tidak memerlukan simbol tanda tambah, +namun harus menambahkan namespace paket <code>android</code>, sehingga:</p> +<pre>android:id="@android:id/empty"</pre> +<p>Dengan namespace paket <code>android</code> yang tersedia, kita sekarang mengacu ID dari kelas sumber daya <code>android.R</code> +, daripada kelas sumber daya lokal.</p> + +<p>Untuk membuat tampilan dan mengacunya dari aplikasi, pola yang umum adalah:</p> +<ol> + <li>Mendefinisikan tampilan/widget dalam file layout dan memberinya ID unik: +<pre> +<Button android:id="@+id/my_button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/my_button_text"/> +</pre> + </li> + <li>Kemudian buat instance objek tampilan dan tangkap instance itu dari layout +(biasanya dalam metode <code>{@link android.app.Activity#onCreate(Bundle) onCreate()}</code>): +<pre> +Button myButton = (Button) findViewById(R.id.my_button); +</pre> + </li> +</ol> +<p>Mendefinisikan ID untuk objek tampilan adalah penting saat membuat {@link android.widget.RelativeLayout}. +Dalam layout relatif, tampilan saudara bisa mendefinisikan layout secara relatif terhadap tampilan saudara lainnya, +yang diacu melalui ID unik.</p> +<p>ID tidak perlu unik di seluruh pohon, namun harus +unik di bagian pohon yang Anda cari (yang mungkin sering kali seluruh pohon, jadi lebih baik +benar-benar unik bila memungkinkan).</p> + + +<h3 id="layout-params">Parameter Layout</h3> + +<p>Atribut layout XML bernama <code>layout_<em>something</em></code> mendefinisikan +parameter layout View yang cocok untuk ViewGroup tempatnya berada.</p> + +<p>Setiap kelas ViewGroup mengimplementasikan kelas tersarang yang memperluas {@link +android.view.ViewGroup.LayoutParams}. Subkelas ini +berisi tipe properti yang mendefinisikan ukuran dan posisi masing-masing tampilan anak, sebagaimana +mestinya untuk grup tampilan. Seperti yang bisa Anda lihat dalam gambar 1, +grup tampilan induk mendefinisikan parameter layout untuk masing-masing tampilan anak (termasuk grup tampilan anak).</p> + +<img src="{@docRoot}images/layoutparams.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Visualisasi hierarki tampilan dengan parameter layout +yang dikaitkan dengan tiap tampilan.</p> + +<p>Perhatikan bahwa setiap subkelas LayoutParams memiliki sintaksnya sendiri untuk menetapkan +nilai-nilai. Tiap elemen anak harus mendefinisikan LayoutParams yang semestinya bagi induknya, +meskipun elemen itu bisa juga mendefinisikan LayoutParams untuk anak-anaknya sendiri. </p> + +<p>Semua grup tampilan berisi lebar dan tinggi (<code>layout_width</code> dan +<code>layout_height</code>), dan masing-masing tampilan harus mendefinisikannya. Banyak +LayoutParams yang juga menyertakan margin dan border opsional. <p> + +<p>Anda bisa menetapkan lebar dan tinggi dengan ukuran persis, meskipun Anda mungkin +tidak ingin sering-sering melakukannya. Lebih sering, Anda akan menggunakan salah satu konstanta ini untuk +mengatur lebar atau tinggi: </p> + +<ul> + <li><var>wrap_content</var> memberi tahu tampilan Anda agar menyesuaikan sendiri ukurannya dengan dimensi +yang dibutuhkan oleh isinya.</li> + <li><var>match_parent</var> (bernama <var>fill_parent</var> sebelum API Level 8) +memberi tahu tampilan Anda agar menjadi sebesar yang diperbolehkan oleh grup tampilan induknya.</li> +</ul> + +<p>Secara umum, menetapkan lebar dan tinggi layout dengan satuan mutlak seperti +piksel tidaklah disarankan. Melainkan dengan menggunakan ukuran relatif seperti +satuan piksel yang tidak bergantung pada kerapatan (<var>dp</var>), <var>wrap_content</var>, atau +<var>match_parent</var>, adalah sebuah pendekatan yang lebih baik, karena membantu memastikan bahwa +aplikasi Anda akan ditampilkan dengan benar pada berbagai ukuran layar perangkat. +Tipe ukuran yang diterima didefinisikan dalam dokumen +<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension"> +Sumber Daya yang Tersedia</a>.</p> + + +<h2 id="Position">Posisi Layout</h2> + <p> + Geometri tampilan adalah persegi panjang. Sebuah tampilan memiliki lokasi, + yang dinyatakan berupa sepasang koordinat <em>kiri</em> dan <em>atas</em>, dan + dua dimensi, yang dinyatakan berupa lebar dan tinggi. Satuan untuk lokasi + dan dimensi adalah piksel. + </p> + + <p> + Lokasi tampilan dapat diambil dengan memanggil metode + {@link android.view.View#getLeft()} dan {@link android.view.View#getTop()}. Metode terdahulu menghasilkan koordinat kiri, atau X, + persegi panjang yang mewakili tampilan. Metode selanjutnya menghasilkan koordinat + atas, atau Y, persegi panjang yang mewakili tampilan. Kedua metode ini + menghasilkan lokasi tampilan relatif terhadap induknya. Misalnya, + bila <code>getLeft()</code> menghasilkan 20, berarti tampilan berlokasi 20 piksel ke + kanan dari tepi kiri induk langsungnya. + </p> + + <p> + Selain itu, beberapa metode praktis ditawarkan untuk menghindari komputasi yang tidak perlu, + yakni {@link android.view.View#getRight()} dan {@link android.view.View#getBottom()}. + Kedua metode ini menghasilkan koordinat tepi kanan dan bawah + persegi panjang yang mewakili tampilan. Misalnya, memanggil {@link android.view.View#getRight()} + serupa dengan komputasi berikut: <code>getLeft() + getWidth()</code>. + </p> + + +<h2 id="SizePaddingMargins">Ukuran, Pengisi, dan Margin</h2> + <p> + Ukuran tampilan dinyatakan dengan lebar dan tinggi. Tampilan sebenarnya + memiliki dua pasang nilai lebar dan tinggi. + </p> + + <p> + Sepasang pertama disebut <em>lebar terukur</em> dan + <em>tinggi terukur</em>. Dimensi ini mendefinisikan seberapa besar tampilan yang diinginkan + dalam induknya. Dimensi + terukur bisa diperoleh dengan memanggil {@link android.view.View#getMeasuredWidth()} + dan {@link android.view.View#getMeasuredHeight()}. + </p> + + <p> + Sepasang kedua cukup disebut dengan <em>lebar</em> dan <em>tinggi</em>, atau + kadang-kadang <em>lebar penggambaran</em> dan <em>tinggi penggambaran</em>. Dimensi-dimensi ini + mendefinisikan ukuran tampilan sebenarnya pada layar, saat digambar dan + setelah layout. Nilai-nilai ini mungkin, namun tidak harus, berbeda dengan + lebar dan tinggi terukur. Lebar dan tinggi bisa diperoleh dengan memanggil + {@link android.view.View#getWidth()} dan {@link android.view.View#getHeight()}. + </p> + + <p> + Untuk mengukur dimensinya, tampilan akan memperhitungkan pengisinya (padding). Pengisi + dinyatakan dalam piksel untuk bagian kiri, atas, kanan, dan bawah tampilan. + Pengisi bisa digunakan untuk meng-offset isi tampilan dengan + piksel dalam jumlah tertentu. Misalnya, pengisi kiri sebesar 2 akan mendorong isi tampilan sebanyak + 2 piksel ke kanan dari tepi kiri. Pengisi bisa diatur menggunakan + metode {@link android.view.View#setPadding(int, int, int, int)} dan diketahui dengan memanggil + {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, + {@link android.view.View#getPaddingRight()}, dan {@link android.view.View#getPaddingBottom()}. + </p> + + <p> + Meskipun bisa mendefinisikan pengisi, tampilan tidak menyediakan dukungan untuk + margin. Akan tetapi, grup tampilan menyediakan dukungan tersebut. Lihat + {@link android.view.ViewGroup} dan + {@link android.view.ViewGroup.MarginLayoutParams} untuk informasi lebih jauh. + </p> + + <p>Untuk informasi selengkapnya tentang dimensi, lihat + <a href="{@docRoot}guide/topics/resources/more-resources.html#Dimension">Nilai-Nilai Dimensi</a>. + </p> + + + + + + +<style type="text/css"> +div.layout { + float:left; + width:200px; + margin:0 0 20px 20px; +} +div.layout.first { + margin-left:0; + clear:left; +} +</style> + + + + +<h2 id="CommonLayouts">Layout Umum</h2> + +<p>Tiap subkelas dari kelas {@link android.view.ViewGroup} menyediakan cara unik untuk menampilkan +tampilan yang Anda sarangkan di dalamnya. Di bawah ini adalah beberapa tipe layout lebih umum yang dibuat +ke dalam platform Android.</p> + +<p class="note"><strong>Catatan:</strong> Walaupun Anda bisa menyarangkan satu atau beberapa layout dalam +layout lain untuk mendapatkan desain UI, Anda harus berusaha menjaga hierarki layout sedangkal +mungkin. Layout Anda akan digambar lebih cepat jika memiliki layout tersarang yang lebih sedikit (hierarki tampilan yang melebar +lebih baik daripada hierarki tampilan yang dalam).</p> + +<!-- +<h2 id="framelayout">FrameLayout</h2> +<p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout +object. It's basically a blank space on your screen that you can +later fill with a single object — for example, a picture that you'll swap in and out. +All child elements of the FrameLayout are pinned to the top left corner of the screen; you cannot +specify a different location for a child view. Subsequent child views will simply be drawn over +previous ones, +partially or totally obscuring them (unless the newer object is transparent). +</p> +--> + + +<div class="layout first"> + <h4><a href="layout/linear.html">Layout Linier</a></h4> + <a href="layout/linear.html"><img src="{@docRoot}images/ui/linearlayout-small.png" alt="" /></a> + <p>Layout yang mengatur anak-anaknya menjadi satu baris horizontal atau vertikal. Layout ini + akan membuat scrollbar jika panjang jendela melebihi panjang layar.</p> +</div> + +<div class="layout"> + <h4><a href="layout/relative.html">Layout Relatif</a></h4> + <a href="layout/relative.html"><img src="{@docRoot}images/ui/relativelayout-small.png" alt="" /></a> + <p>Memungkinkan Anda menentukan lokasi objek anak relatif terhadap satu sama lain (anak A di +kiri anak B) atau terhadap induk (disejajarkan dengan atas induknya).</p> +</div> + +<div class="layout"> + <h4><a href="{@docRoot}guide/webapps/webview.html">Tampilan Web</a></h4> + <a href="{@docRoot}guide/webapps/webview.html"><img src="{@docRoot}images/ui/webview-small.png" alt="" /></a> + <p>Menampilkan halaman web.</p> +</div> + + + + +<h2 id="AdapterViews" style="clear:left">Membangun Layout dengan Adaptor</h2> + +<p>Bila isi layout bersifat dinamis atau tidak dipastikan sebelumnya, Anda bisa menggunakan layout yang menjadi +subkelas {@link android.widget.AdapterView} untuk mengisi layout dengan tampilan saat runtime. +Subkelas dari kelas {@link android.widget.AdapterView} menggunakan {@link android.widget.Adapter} untuk +mengikat data ke layoutnya. {@link android.widget.Adapter} berfungsi sebagai penghubung antara sumber data +dan layout{@link android.widget.AdapterView}—{@link android.widget.Adapter} +menarik data (dari suatu sumber seperti larik (array) atau query database) dan mengubah setiap entri +menjadi tampilan yang bisa ditambahkan ke dalam layout {@link android.widget.AdapterView}.</p> + +<p>Layout umum yang didukung oleh adaptor meliputi:</p> + +<div class="layout first"> + <h4><a href="layout/listview.html">Tampilan Daftar</a></h4> + <a href="layout/listview.html"><img src="{@docRoot}images/ui/listview-small.png" alt="" /></a> + <p>Menampilkan daftar kolom tunggal yang bergulir.</p> +</div> + +<div class="layout"> + <h4><a href="layout/gridview.html">Tampilan Petak</a></h4> + <a href="layout/gridview.html"><img src="{@docRoot}images/ui/gridview-small.png" alt="" /></a> + <p>Menampilkan petak bergulir yang terdiri atas kolom dan baris.</p> +</div> + + + +<h3 id="FillingTheLayout" style="clear:left">Mengisi tampilan adaptor dengan data</h3> + +<p>Anda bisa mengisi {@link android.widget.AdapterView} seperti {@link android.widget.ListView} atau +{@link android.widget.GridView} dengan mengikat instance {@link android.widget.AdapterView} ke +{@link android.widget.Adapter}, yang akan mengambil data dari sumber eksternal dan membuat {@link +android.view.View} yang mewakili tiap entri data.</p> + +<p>Android menyediakan beberapa subkelas {@link android.widget.Adapter} yang berguna untuk +menarik berbagai jenis data dan membangun tampilan untuk {@link android.widget.AdapterView}. Dua + adaptor yang paling umum adalah:</p> + +<dl> + <dt>{@link android.widget.ArrayAdapter}</dt> + <dd>Gunakan adaptor ini bila sumber data Anda berupa larik. Secara default, {@link +android.widget.ArrayAdapter} akan membuat tampilan untuk tiap elemen larik dengan memanggil {@link +java.lang.Object#toString()} pada tiap elemen dan menempatkan isinya dalam {@link +android.widget.TextView}. + <p>Misalnya, jika Anda memiliki satu larik string yang ingin ditampilkan dalam {@link +android.widget.ListView}, buatlah {@link android.widget.ArrayAdapter} baru dengan konstruktor +untuk menentukan layout setiap string dan larik string:</p> +<pre> +ArrayAdapter<String> adapter = new ArrayAdapter<String>(this, + android.R.layout.simple_list_item_1, myStringArray); +</pre> +<p>Argumen-argumen untuk konstruktor ini adalah:</p> +<ul> + <li>{@link android.content.Context} aplikasi Anda</li> + <li>Layout yang berisi {@link android.widget.TextView} untuk tiap string dalam larik</li> + <li>Larik string</li> +</ul> +<p>Kemudian tinggal panggil +{@link android.widget.ListView#setAdapter setAdapter()} pada {@link android.widget.ListView} Anda:</p> +<pre> +ListView listView = (ListView) findViewById(R.id.listview); +listView.setAdapter(adapter); +</pre> + + <p>Untuk menyesuaikan penampilan setiap item, Anda bisa mengesampingkan metode {@link +java.lang.Object#toString()} bagi objek dalam larik Anda. Atau, untuk membuat tampilan tiap +elemen selain {@link android.widget.TextView} (misalnya, jika Anda menginginkan +{@link android.widget.ImageView} bagi setiap item larik), perluas kelas {@link +android.widget.ArrayAdapter} dan kesampingkan {@link android.widget.ArrayAdapter#getView +getView()} agar memberikan tipe tampilan yang Anda inginkan bagi tiap item.</p> + +</dd> + + <dt>{@link android.widget.SimpleCursorAdapter}</dt> + <dd>Gunakan adaptor ini bila data Anda berasal dari {@link android.database.Cursor}. Saat +menggunakan {@link android.widget.SimpleCursorAdapter}, Anda harus menentukan layout yang akan digunakan untuk tiap +baris dalam {@link android.database.Cursor} dan di kolom mana di {@link android.database.Cursor} +harus memasukkan tampilan layout. Misalnya, jika Anda ingin untuk membuat daftar +nama orang dan nomor telepon, Anda bisa melakukan query yang menghasilkan {@link +android.database.Cursor} yang berisi satu baris untuk tiap orang dan kolom-kolom untuk nama dan +nomor. Selanjutnya Anda membuat larik string yang menentukan kolom dari {@link +android.database.Cursor} yang Anda inginkan dalam layout untuk setiap hasil dan larik integer yang menentukan +tampilan yang sesuai untuk menempatkan masing-masing kolom:</p> +<pre> +String[] fromColumns = {ContactsContract.Data.DISPLAY_NAME, + ContactsContract.CommonDataKinds.Phone.NUMBER}; +int[] toViews = {R.id.display_name, R.id.phone_number}; +</pre> +<p>Bila Anda membuat instance {@link android.widget.SimpleCursorAdapter}, teruskan layout yang akan digunakan untuk +setiap hasil, {@link android.database.Cursor} yang berisi hasil tersebut, dan dua larik ini:</p> +<pre> +SimpleCursorAdapter adapter = new SimpleCursorAdapter(this, + R.layout.person_name_and_number, cursor, fromColumns, toViews, 0); +ListView listView = getListView(); +listView.setAdapter(adapter); +</pre> +<p>{@link android.widget.SimpleCursorAdapter} kemudian membuat tampilan untuk tiap baris dalam +{@link android.database.Cursor} dengan layout yang disediakan dengan memasukkan setiap item {@code +fromColumns} ke dalam tampilan {@code toViews} yang sesuai.</p></dd> +</dl> + + +<p>Jika, selama aplikasi berjalan, Anda mengubah data sumber yang dibaca oleh +adaptor, maka Anda harus memanggil {@link android.widget.ArrayAdapter#notifyDataSetChanged()}. Hal ini akan +memberi tahu tampilan yang bersangkutan bahwa data telah berubah dan tampilan harus memperbarui dirinya sendiri.</p> + + + +<h3 id="HandlingUserSelections">Menangani kejadian klik</h3> + +<p>Anda bisa merespons kejadian klik pada setiap item dalam {@link android.widget.AdapterView} dengan +menerapkan antarmuka {@link android.widget.AdapterView.OnItemClickListener}. Misalnya:</p> + +<pre> +// Create a message handling object as an anonymous class. +private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { + public void onItemClick(AdapterView parent, View v, int position, long id) { + // Do something in response to the click + } +}; + +listView.setOnItemClickListener(mMessageClickedHandler); +</pre> + + + diff --git a/docs/html-intl/intl/in/guide/topics/ui/dialogs.jd b/docs/html-intl/intl/in/guide/topics/ui/dialogs.jd new file mode 100644 index 000000000000..65714a9e4c4d --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/dialogs.jd @@ -0,0 +1,798 @@ +page.title=Dialog +page.tags=alertdialog,dialogfragment + +@jd:body + + + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#DialogFragment">Membuat Fragmen Dialog</a></li> + <li><a href="#AlertDialog">Membuat Dialog Peringatan</a> + <ol> + <li><a href="#AddingButtons">Menambahkan tombol</a></li> + <li><a href="#AddingAList">Menambahkan daftar</a></li> + <li><a href="#CustomLayout">Membuat Layout Custom</a></li> + </ol> + </li> + <li><a href="#PassingEvents">Meneruskan Kejadian Kembali ke Host Dialog</a></li> + <li><a href="#ShowingADialog">Menampilkan Dialog</a></li> + <li><a href="#FullscreenDialog">Menampilkan Dialog sebagai Layar Penuh atau Fragmen Tertanam</a> + <ol> + <li><a href="#ActivityAsDialog">Menampilkan aktivitas sebagai dialog pada layar besar</a></li> + </ol> + </li> + <li><a href="#DismissingADialog">Menutup Dialog</a></li> +</ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.app.DialogFragment}</li> + <li>{@link android.app.AlertDialog}</li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="{@docRoot}design/building-blocks/dialogs.html">Panduan desain dialog</a></li> + <li><a href="{@docRoot}guide/topics/ui/controls/pickers.html">Picker</a> (dialog Tanggal/Waktu)</li> + </ol> + </div> +</div> + +<p>Dialog adalah jendela kecil yang meminta pengguna untuk +membuat keputusan atau memasukkan informasi tambahan. Dialog tidak mengisi layar dan +biasanya digunakan untuk kejadian modal yang mengharuskan pengguna untuk melakukan tindakan sebelum bisa melanjutkan.</p> + +<div class="note design"> +<p><strong>Desain Dialog</strong></p> + <p>Untuk informasi tentang cara mendesain dialog, termasuk saran + untuk bahasa, bacalah panduan Desain <a href="{@docRoot}design/building-blocks/dialogs.html">dialog</a>.</p> +</div> + +<img src="{@docRoot}images/ui/dialogs.png" /> + +<p>Kelas {@link android.app.Dialog} adalah kelas basis untuk dialog, namun Anda +harus menghindari pembuatan instance {@link android.app.Dialog} secara langsung. +Sebagai gantinya, gunakan salah satu subkelas berikut:</p> +<dl> + <dt>{@link android.app.AlertDialog}</dt> + <dd>Dialog yang bisa menampilkan judul, hingga tiga tombol, daftar + item yang dapat dipilih, atau layout custom.</dd> + <dt>{@link android.app.DatePickerDialog} atau {@link android.app.TimePickerDialog}</dt> + <dd>Dialog berisi UI yang sudah didefinisikan dan memungkinkan pengguna memilih tanggal atau waktu.</dd> +</dl> + +<div class="sidebox"> +<h2>Hindari ProgressDialog</h2> +<p>Android menyertakan kelas dialog lain yang disebut +{@link android.app.ProgressDialog} yang menampilkan dialog berisi progress-bar. Akan tetapi, jika Anda +perlu menunjukkan kemajuan pemuatan ataupun kemajuan yang tidak pasti, maka Anda harus mengikuti +panduan desain untuk <a href="{@docRoot}design/building-blocks/progress.html">Kemajuan & +Aktivitas</a> dan menggunakan {@link android.widget.ProgressBar} dalam layout Anda.</p> +</div> + +<p>Kelas-kelas ini mendefinisikan gaya dan struktur dialog Anda, namun Anda harus +menggunakan {@link android.support.v4.app.DialogFragment} sebagai kontainer dialog Anda. +Kelas {@link android.support.v4.app.DialogFragment} menyediakan semua kontrol yang Anda +perlukan untuk membuat dialog dan mengelola penampilannya, sebagai ganti memanggil metode +pada objek {@link android.app.Dialog}.</p> + +<p>Menggunakan {@link android.support.v4.app.DialogFragment} untuk mengelola dialog +akan memastikan bahwa kelas itu menangani kejadian daur hidup +dengan benar seperti ketika pengguna menekan tombol <em>Back</em> atau memutar layar. Kelas {@link +android.support.v4.app.DialogFragment} juga memungkinkan Anda menggunakan ulang dialog UI sebagai +komponen yang bisa ditanamkan dalam UI yang lebih besar, persis seperti {@link +android.support.v4.app.Fragment} tradisional (seperti saat Anda ingin dialog UI muncul berbeda +pada layar besar dan kecil).</p> + +<p>Bagian-bagian berikutnya dalam panduan ini akan menjelaskan cara menggunakan {@link +android.support.v4.app.DialogFragment} yang dikombinasikan dengan objek {@link android.app.AlertDialog} +. Jika Anda ingin membuat picker tanggal atau waktu, Anda harus membaca panduan +<a href="{@docRoot}guide/topics/ui/controls/pickers.html">Picker</a>.</p> + +<p class="note"><strong>Catatan:</strong> +Karena kelas {@link android.app.DialogFragment} mulanya ditambahkan pada +Android 3.0 (API level 11), dokumen ini menjelaskan cara menggunakan kelas {@link +android.support.v4.app.DialogFragment} yang disediakan bersama <a href="{@docRoot}tools/support-library/index.html">Pustaka Dukungan</a>. Dengan menambahkan pustaka ini +ke aplikasi, Anda bisa menggunakan {@link android.support.v4.app.DialogFragment} dan berbagai +API lain pada perangkat yang menjalankan Android 1.6 atau yang lebih tinggi. Jika versi minimum yang didukung aplikasi Anda +adalah API level 11 atau yang lebih tinggi, maka Anda bisa menggunakan versi kerangka kerja {@link +android.app.DialogFragment}, namun ketahuilah bahwa tautan dalam dokumen ini adalah untuk API +pustaka dukungan. Saat menggunakan pustaka dukungan, +pastikan Anda mengimpor kelas <code>android.support.v4.app.DialogFragment</code> +dan <em>bukan</em> <code>android.app.DialogFragment</code>.</p> + + +<h2 id="DialogFragment">Membuat Fragmen Dialog</h2> + +<p>Anda bisa menghasilkan beragam rancangan dialog—termasuk +layout custom dan desain yang dijelaskan dalam panduan desain <a href="{@docRoot}design/building-blocks/dialogs.html">Dialog</a> +—dengan memperluas +{@link android.support.v4.app.DialogFragment} dan membuat {@link android.app.AlertDialog} +dalam metode callback {@link android.support.v4.app.DialogFragment#onCreateDialog +onCreateDialog()}.</p> + +<p>Misalnya, berikut ini sebuah {@link android.app.AlertDialog} dasar yang dikelola dalam +{@link android.support.v4.app.DialogFragment}:</p> + +<pre> +public class FireMissilesDialogFragment extends DialogFragment { + @Override + public Dialog onCreateDialog(Bundle savedInstanceState) { + // Use the Builder class for convenient dialog construction + AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + builder.setMessage(R.string.dialog_fire_missiles) + .setPositiveButton(R.string.fire, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // FIRE ZE MISSILES! + } + }) + .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // User cancelled the dialog + } + }); + // Create the AlertDialog object and return it + return builder.create(); + } +} +</pre> + +<div class="figure" style="width:290px;margin:0 0 0 20px"> +<img src="{@docRoot}images/ui/dialog_buttons.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> +Dialog dengan satu pesan dan dua tombol tindakan.</p> +</div> + +<p>Sekarang, bila Anda membuat instance kelas ini dan memanggil {@link +android.support.v4.app.DialogFragment#show show()} pada objek itu, dialog akan muncul seperti +yang ditampilkan dalam gambar 1.</p> + +<p>Bagian berikutnya menjelaskan lebih jauh tentang penggunaan API {@link android.app.AlertDialog.Builder} +untuk membuat dialog.</p> + +<p>Bergantung pada seberapa rumit dialog tersebut, Anda bisa menerapkan berbagai metode callback lain +dalam {@link android.support.v4.app.DialogFragment}, termasuk semua +<a href="{@docRoot}guide/components/fragments.html#Lifecycle">metode daur hidup fragmen</a> dasar. + + + + + +<h2 id="AlertDialog">Membuat Dialog Peringatan</h2> + + +<p>Kelas {@link android.app.AlertDialog} memungkinkan Anda membuat berbagai desain dialog dan +seringkali satu-satunya kelas dialog yang akan Anda perlukan. +Seperti yang ditampilkan dalam gambar 2, ada tiga area pada dialog peringatan:</p> + +<div class="figure" style="width:311px;margin-top:0"> +<img src="{@docRoot}images/ui/dialogs_regions.png" alt="" style="margin-bottom:0" /> +<p class="img-caption"><strong>Gambar 2.</strong> Layout dialog.</p> +</div> + +<ol> +<li><b>Judul</b> + <p>Area ini opsional dan hanya boleh digunakan bila area konten + ditempati oleh pesan terperinci, daftar, atau layout custom. Jika Anda perlu menyatakan + pesan atau pertanyaan sederhana (seperti dialog dalam gambar 1), Anda tidak memerlukan judul.</li> +<li><b>Area konten</b> + <p>Area ini bisa menampilkan pesan, daftar, atau layout custom lainnya.</p></li> +<li><b>Tombol tindakan</b> + <p>Tidak boleh ada lebih dari tiga tombol tindakan dalam sebuah dialog.</p></li> +</ol> + +<p>Kelas {@link android.app.AlertDialog.Builder} + menyediakan API yang memungkinkan Anda membuat {@link android.app.AlertDialog} +dengan jenis konten ini, termasuk layout custom.</p> + +<p>Untuk membuat {@link android.app.AlertDialog}:</p> + +<pre> +<b>// 1. Instantiate an {@link android.app.AlertDialog.Builder} with its constructor</b> +AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + +<b>// 2. Chain together various setter methods to set the dialog characteristics</b> +builder.setMessage(R.string.dialog_message) + .setTitle(R.string.dialog_title); + +<b>// 3. Get the {@link android.app.AlertDialog} from {@link android.app.AlertDialog.Builder#create()}</b> +AlertDialog dialog = builder.create(); +</pre> + +<p>Topik-topik selanjutnya menampilkan cara mendefinisikan berbagai atribut dialog dengan menggunakan +kelas {@link android.app.AlertDialog.Builder}.</p> + + + + +<h3 id="AddingButtons">Menambahkan tombol</h3> + +<p>Untuk menambahkan tombol tindakan seperti dalam gambar 2, +panggil metode {@link android.app.AlertDialog.Builder#setPositiveButton setPositiveButton()} dan +{@link android.app.AlertDialog.Builder#setNegativeButton setNegativeButton()}:</p> + +<pre style="clear:right"> +AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); +// Add the buttons +builder.setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // User clicked OK button + } + }); +builder.setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // User cancelled the dialog + } + }); +// Set other dialog properties +... + +// Create the AlertDialog +AlertDialog dialog = builder.create(); +</pre> + +<p>Metode <code>set...Button()</code> mengharuskan adanya judul bagi tombol (disediakan +oleh suatu <a href="{@docRoot}guide/topics/resources/string-resource.html">sumber daya string</a>) dan +{@link android.content.DialogInterface.OnClickListener} yang mendefinisikan tindakan yang diambil +bila pengguna menekan tombol.</p> + +<p>Ada tiga macam tombol tindakan yang Anda bisa tambahkan:</p> +<dl> + <dt>Positif</dt> + <dd>Anda harus menggunakan tipe ini untuk menerima dan melanjutkan tindakan (tindakan "OK").</dd> + <dt>Negatif</dt> + <dd>Anda harus menggunakan tipe ini untuk membatalkan tindakan.</dd> + <dt>Netral</dt> + <dd>Anda harus menggunakan tipe ini bila pengguna mungkin tidak ingin melanjutkan tindakan, + namun tidak ingin membatalkan. Tipe ini muncul antara tombol positif dan +tombol negatif. Misalnya, tindakan bisa berupa "Ingatkan saya nanti".</dd> +</dl> + +<p>Anda hanya bisa menambahkan salah satu tipe tombol ke {@link +android.app.AlertDialog}. Artinya, Anda tidak bisa memiliki lebih dari satu tombol "positif".</p> + + + +<div class="figure" style="width:290px;margin:0 0 0 40px"> +<img src="{@docRoot}images/ui/dialog_list.png" alt="" /> +<p class="img-caption"><strong>Gambar 3.</strong> +Dialog dengan satu judul dan daftar.</p> +</div> + +<h3 id="AddingAList">Menambahkan daftar</h3> + +<p>Ada tiga macam daftar yang tersedia pada API {@link android.app.AlertDialog}:</p> +<ul> +<li>Daftar pilihan tunggal biasa</li> +<li>Daftar pilihan tunggal persisten (tombol radio)</li> +<li>Daftar pilihan ganda persisten (kotak cek)</li> +</ul> + +<p>Untuk membuat daftar pilihan tunggal seperti dalam gambar 3, +gunakan metode {@link android.app.AlertDialog.Builder#setItems setItems()}:</p> + +<pre style="clear:right"> +@Override +public Dialog onCreateDialog(Bundle savedInstanceState) { + AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + builder.setTitle(R.string.pick_color) + .setItems(R.array.colors_array, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int which) { + // The 'which' argument contains the index position + // of the selected item + } + }); + return builder.create(); +} +</pre> + +<p>Karena daftar muncul dalam area konten dialog, +dialog tidak bisa menampilkan pesan dan daftar sekaligus dan Anda harus menetapkan judul untuk +dialog dengan {@link android.app.AlertDialog.Builder#setTitle setTitle()}. +Untuk menentukan item daftar, panggil {@link +android.app.AlertDialog.Builder#setItems setItems()}, dengan meneruskan larik. +Atau, Anda bisa menetapkan daftar menggunakan {@link +android.app.AlertDialog.Builder#setAdapter setAdapter()}. Hal ini memungkinkan Anda mendukung daftar +dengan data dinamis (seperti dari database) dengan menggunakan {@link android.widget.ListAdapter}.</p> + +<p>Jika Anda memilih untuk mendukung daftar dengan {@link android.widget.ListAdapter}, +selalu gunakan sebuah {@link android.support.v4.content.Loader} agar konten dimuat +secara asinkron. Hal ini dijelaskan lebih jauh dalam panduan +<a href="{@docRoot}guide/topics/ui/declaring-layout.html#AdapterViews">Membuat Layout +dengan Adaptor</a> dan <a href="{@docRoot}guide/components/loaders.html">Loader</a> +.</p> + +<p class="note"><strong>Catatan:</strong> Secara default, menyentuh sebuah item daftar akan menutup dialog, +kecuali Anda menggunakan salah satu daftar pilihan persisten berikut ini.</p> + +<div class="figure" style="width:290px;margin:-30px 0 0 40px"> +<img src="{@docRoot}images/ui/dialog_checkboxes.png" /> +<p class="img-caption"><strong>Gambar 4.</strong> +Daftar item pilihan ganda.</p> +</div> + + +<h4 id="Checkboxes">Menambahkan daftar pilihan ganda atau pilihan tunggal persisten</h4> + +<p>Untuk menambahkan daftar item pilihan ganda (kotak cek) atau +item pilihan tunggal (tombol radio), gunakan masing-masing metode +{@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String, +DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()}, atau +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()}.</p> + +<p>Misalnya, berikut ini cara membuat daftar pilihan ganda seperti +yang ditampilkan dalam gambar 4 yang menyimpan item +yang dipilih dalam {@link java.util.ArrayList}:</p> + +<pre style="clear:right"> +@Override +public Dialog onCreateDialog(Bundle savedInstanceState) { + mSelectedItems = new ArrayList(); // Where we track the selected items + AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + // Set the dialog title + builder.setTitle(R.string.pick_toppings) + // Specify the list array, the items to be selected by default (null for none), + // and the listener through which to receive callbacks when items are selected + .setMultiChoiceItems(R.array.toppings, null, + new DialogInterface.OnMultiChoiceClickListener() { + @Override + public void onClick(DialogInterface dialog, int which, + boolean isChecked) { + if (isChecked) { + // If the user checked the item, add it to the selected items + mSelectedItems.add(which); + } else if (mSelectedItems.contains(which)) { + // Else, if the item is already in the array, remove it + mSelectedItems.remove(Integer.valueOf(which)); + } + } + }) + // Set the action buttons + .setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() { + @Override + public void onClick(DialogInterface dialog, int id) { + // User clicked OK, so save the mSelectedItems results somewhere + // or return them to the component that opened the dialog + ... + } + }) + .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { + @Override + public void onClick(DialogInterface dialog, int id) { + ... + } + }); + + return builder.create(); +} +</pre> + +<p>Walaupun daftar tradisional maupun daftar dengan tombol radio +menyediakan tindakan "pilihan tunggal", Anda harus menggunakan {@link +android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()} jika ingin mempertahankan pilihan pengguna. +Yakni, jika nanti membuka dialog lagi untuk menunjukkan pilihan pengguna, +maka Anda perlu membuat daftar dengan tombol radio.</p> + + + + + +<h3 id="CustomLayout">Membuat Layout Custom</h3> + +<div class="figure" style="width:290px;margin:-30px 0 0 40px"> +<img src="{@docRoot}images/ui/dialog_custom.png" alt="" /> +<p class="img-caption"><strong>Gambar 5.</strong> Layout dialog custom.</p> +</div> + +<p>Jika Anda menginginkan layout custom dalam dialog, buatlah layout dan tambahkan ke +{@link android.app.AlertDialog} dengan memanggil {@link +android.app.AlertDialog.Builder#setView setView()} pada objek {@link +android.app.AlertDialog.Builder} Anda.</p> + +<p>Secara default, layout custom akan mengisi jendela dialog, namun Anda masih bisa +menggunakan metode {@link android.app.AlertDialog.Builder} untuk menambahkan tombol dan judul.</p> + +<p>Misalnya, berikut ini adalah file layout untuk dialog dalam Gambar 5:</p> + +<p style="clear:right" class="code-caption">res/layout/dialog_signin.xml</p> +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="wrap_content" + android:layout_height="wrap_content"> + <ImageView + android:src="@drawable/header_logo" + android:layout_width="match_parent" + android:layout_height="64dp" + android:scaleType="center" + android:background="#FFFFBB33" + android:contentDescription="@string/app_name" /> + <EditText + android:id="@+id/username" + android:inputType="textEmailAddress" + android:layout_width="match_parent" + android:layout_height="wrap_content" + android:layout_marginTop="16dp" + android:layout_marginLeft="4dp" + android:layout_marginRight="4dp" + android:layout_marginBottom="4dp" + android:hint="@string/username" /> + <EditText + android:id="@+id/password" + android:inputType="textPassword" + android:layout_width="match_parent" + android:layout_height="wrap_content" + android:layout_marginTop="4dp" + android:layout_marginLeft="4dp" + android:layout_marginRight="4dp" + android:layout_marginBottom="16dp" + android:fontFamily="sans-serif" + android:hint="@string/password"/> +</LinearLayout> +</pre> + +<p class="note"><strong>Tip:</strong> Secara default, bila Anda telah mengatur sebuah elemen {@link android.widget.EditText} +agar menggunakan tipe input {@code "textPassword"}, keluarga font akan diatur ke spasi tunggal, sehingga +Anda harus mengubah keluarga font ke {@code "sans-serif"} sehingga kedua bidang teks menggunakan +gaya font yang cocok.</p> + +<p>Untuk memekarkan layout dalam {@link android.support.v4.app.DialogFragment} Anda, +ambillah {@link android.view.LayoutInflater} dengan +{@link android.app.Activity#getLayoutInflater()} dan panggil +{@link android.view.LayoutInflater#inflate inflate()}, dengan parameter pertama +adalah ID sumber daya layout dan parameter kedua adalah tampilan induk untuk layout. +Selanjutnya Anda bisa memanggil {@link android.app.AlertDialog#setView setView()} +untuk menempatkan layout dalam dialog.</p> + +<pre> +@Override +public Dialog onCreateDialog(Bundle savedInstanceState) { + AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + // Get the layout inflater + LayoutInflater inflater = getActivity().getLayoutInflater(); + + // Inflate and set the layout for the dialog + // Pass null as the parent view because its going in the dialog layout + builder.setView(inflater.inflate(R.layout.dialog_signin, null)) + // Add action buttons + .setPositiveButton(R.string.signin, new DialogInterface.OnClickListener() { + @Override + public void onClick(DialogInterface dialog, int id) { + // sign in the user ... + } + }) + .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + LoginDialogFragment.this.getDialog().cancel(); + } + }); + return builder.create(); +} +</pre> + +<div class="note"> +<p><strong>Tip:</strong> Jika Anda menginginkan dialog custom, +Anda bisa menampilkan {@link android.app.Activity} sebagai dialog +daripada menggunakan API {@link android.app.Dialog}. Cukup buat satu aktivitas dan mengatur temanya ke +{@link android.R.style#Theme_Holo_Dialog Theme.Holo.Dialog} +di elemen manifes <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>:</p> + +<pre> +<activity android:theme="@android:style/Theme.Holo.Dialog" > +</pre> +<p>Demikian saja. Aktivitas sekarang ditampilkan dalam jendela dialog, sebagai ganti layar penuh.</p> +</div> + + + +<h2 id="PassingEvents">Meneruskan Kejadian Kembali ke Host Dialog</h2> + +<p>Bila pengguna menyentuh salah satu tombol tindakan dialog atau memilih satu item dari daftarnya, +{@link android.support.v4.app.DialogFragment} Anda bisa melakukan sendiri tindakan yang diperlukan +, namun sering kali Anda perlu mengirim kejadian itu ke aktivitas atau fragmen yang +membuka dialog. Caranya, definisikan antarmuka dengan sebuah metode untuk masing-masing tipe kejadian klik. +Lalu implementasikan antarmuka itu dalam komponen host yang akan +menerima kejadian tindakan dari dialog.</p> + +<p>Misalnya, berikut ini adalah {@link android.support.v4.app.DialogFragment} yang mendefinisikan +antarmuka yang akan digunakan untuk mengirim kembali suatu kejadian ke aktivitas host:</p> + +<pre> +public class NoticeDialogFragment extends DialogFragment { + + /* The activity that creates an instance of this dialog fragment must + * implement this interface in order to receive event callbacks. + * Each method passes the DialogFragment in case the host needs to query it. */ + public interface NoticeDialogListener { + public void onDialogPositiveClick(DialogFragment dialog); + public void onDialogNegativeClick(DialogFragment dialog); + } + + // Use this instance of the interface to deliver action events + NoticeDialogListener mListener; + + // Override the Fragment.onAttach() method to instantiate the NoticeDialogListener + @Override + public void onAttach(Activity activity) { + super.onAttach(activity); + // Verify that the host activity implements the callback interface + try { + // Instantiate the NoticeDialogListener so we can send events to the host + mListener = (NoticeDialogListener) activity; + } catch (ClassCastException e) { + // The activity doesn't implement the interface, throw exception + throw new ClassCastException(activity.toString() + + " must implement NoticeDialogListener"); + } + } + ... +} +</pre> + +<p>Aktivitas yang menjadi host dialog tersebut akan membuat instance dialog +dengan konstruktor fragmen dialog dan menerima kejadian dialog +melalui implementasi antarmuka {@code NoticeDialogListener}:</p> + +<pre> +public class MainActivity extends FragmentActivity + implements NoticeDialogFragment.NoticeDialogListener{ + ... + + public void showNoticeDialog() { + // Create an instance of the dialog fragment and show it + DialogFragment dialog = new NoticeDialogFragment(); + dialog.show(getSupportFragmentManager(), "NoticeDialogFragment"); + } + + // The dialog fragment receives a reference to this Activity through the + // Fragment.onAttach() callback, which it uses to call the following methods + // defined by the NoticeDialogFragment.NoticeDialogListener interface + @Override + public void onDialogPositiveClick(DialogFragment dialog) { + // User touched the dialog's positive button + ... + } + + @Override + public void onDialogNegativeClick(DialogFragment dialog) { + // User touched the dialog's negative button + ... + } +} +</pre> + +<p>Karena aktivitas host mengimplementasikan {@code NoticeDialogListener}—yang +diberlakukan oleh metode callback {@link android.support.v4.app.Fragment#onAttach onAttach()} +di atas,—fragmen dialog bisa menggunakan +metode callback antarmuka untuk mengirimkan kejadian klik ke aktivitas:</p> + +<pre> +public class NoticeDialogFragment extends DialogFragment { + ... + + @Override + public Dialog onCreateDialog(Bundle savedInstanceState) { + // Build the dialog and set up the button click handlers + AlertDialog.Builder builder = new AlertDialog.Builder(getActivity()); + builder.setMessage(R.string.dialog_fire_missiles) + .setPositiveButton(R.string.fire, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // Send the positive button event back to the host activity + mListener.onDialogPositiveClick(NoticeDialogFragment.this); + } + }) + .setNegativeButton(R.string.cancel, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + // Send the negative button event back to the host activity + mListener.onDialogNegativeClick(NoticeDialogFragment.this); + } + }); + return builder.create(); + } +} +</pre> + + + +<h2 id="ShowingADialog">Menampilkan Dialog</h2> + +<p>Bila Anda ingin menampilkan dialog, buatlah instance {@link +android.support.v4.app.DialogFragment} dan panggil {@link android.support.v4.app.DialogFragment#show +show()}, dengan meneruskan {@link android.support.v4.app.FragmentManager} dan nama tag +untuk fragmen dialognya.</p> + +<p>Anda bisa mendapatkan {@link android.support.v4.app.FragmentManager} dengan memanggil +{@link android.support.v4.app.FragmentActivity#getSupportFragmentManager()} dari + {@link android.support.v4.app.FragmentActivity} atau {@link +android.support.v4.app.Fragment#getFragmentManager()} dari {@link +android.support.v4.app.Fragment}. Misalnya:</p> + +<pre> +public void confirmFireMissiles() { + DialogFragment newFragment = new FireMissilesDialogFragment(); + newFragment.show(getSupportFragmentManager(), "missiles"); +} +</pre> + +<p>Argumen kedua, {@code "missiles"}, adalah nama tag unik yang digunakan sistem untuk menyimpan +dan memulihkan status fragmen bila diperlukan. Tag ini juga memungkinkan Anda mendapatkan handle ke +fragmen dengan memanggil {@link android.support.v4.app.FragmentManager#findFragmentByTag +findFragmentByTag()}.</p> + + + + +<h2 id="FullscreenDialog">Menampilkan Dialog sebagai Layar Penuh atau Fragmen Tertanam</h2> + +<p>Anda mungkin memiliki desain UI yang di dalamnya Anda ingin UI muncul sebagai dialog dalam beberapa +situasi, namun sebagai layar penuh atau fragmen tertanam dalam situasi lain (mungkin bergantung pada apakah +perangkat memiliki layar besar atau layar kecil). Kelas {@link android.support.v4.app.DialogFragment} +menawarkan fleksibilitas ini karena masih bisa berperilaku sebagai {@link +android.support.v4.app.Fragment} yang bisa ditanamkan.</p> + +<p>Akan tetapi, dalam hal ini Anda tidak bisa menggunakan {@link android.app.AlertDialog.Builder AlertDialog.Builder} +atau objek {@link android.app.Dialog} lain untuk membangun dialog. Jika +Anda ingin {@link android.support.v4.app.DialogFragment} +bisa ditanamkan, Anda harus mendefinisikan dialog UI dalam layout, lalu memuat layout itu dalam metode callback +{@link android.support.v4.app.DialogFragment#onCreateView +onCreateView()}.</p> + +<p>Berikut ini adalah contoh {@link android.support.v4.app.DialogFragment} yang bisa muncul sebagai +dialog maupun fragmen yang bisa ditanamkan (menggunakan layout bernama <code>purchase_items.xml</code>):</p> + +<pre> +public class CustomDialogFragment extends DialogFragment { + /** The system calls this to get the DialogFragment's layout, regardless + of whether it's being displayed as a dialog or an embedded fragment. */ + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // Inflate the layout to use as dialog or embedded fragment + return inflater.inflate(R.layout.purchase_items, container, false); + } + + /** The system calls this only when creating the layout in a dialog. */ + @Override + public Dialog onCreateDialog(Bundle savedInstanceState) { + // The only reason you might override this method when using onCreateView() is + // to modify any dialog characteristics. For example, the dialog includes a + // title by default, but your custom layout might not need it. So here you can + // remove the dialog title, but you must call the superclass to get the Dialog. + Dialog dialog = super.onCreateDialog(savedInstanceState); + dialog.requestWindowFeature(Window.FEATURE_NO_TITLE); + return dialog; + } +} +</pre> + +<p>Dan berikut ini adalah beberapa kode yang memutuskan apakah akan menampilkan fragmen sebagai dialog +atau UI layar penuh, berdasarkan ukuran layar:</p> + +<pre> +public void showDialog() { + FragmentManager fragmentManager = getSupportFragmentManager(); + CustomDialogFragment newFragment = new CustomDialogFragment(); + + if (mIsLargeLayout) { + // The device is using a large layout, so show the fragment as a dialog + newFragment.show(fragmentManager, "dialog"); + } else { + // The device is smaller, so show the fragment fullscreen + FragmentTransaction transaction = fragmentManager.beginTransaction(); + // For a little polish, specify a transition animation + transaction.setTransition(FragmentTransaction.TRANSIT_FRAGMENT_OPEN); + // To make it fullscreen, use the 'content' root view as the container + // for the fragment, which is always the root view for the activity + transaction.add(android.R.id.content, newFragment) + .addToBackStack(null).commit(); + } +} +</pre> + +<p>Untuk informasi selengkapnya tentang melakukan transaksi fragmen, lihat panduan +<a href="{@docRoot}guide/components/fragments.html">Fragmen</a>.</p> + +<p>Dalam contoh ini, nilai boolean <code>mIsLargeLayout</code> menentukan apakah perangkat saat ini +harus menggunakan desain layout besar aplikasi (dan dengan demikian menampilkan fragmen ini sebagai dialog, bukan +layar penuh). Cara terbaik untuk mengatur jenis boolean ini adalah mendeklarasikan +<a href="{@docRoot}guide/topics/resources/more-resources.html#Bool">nilai sumber daya boolean</a> +dengan nilai <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">sumber daya alternatif</a> untuk berbagai ukuran layar. Misalnya, berikut ini adalah dua +versi sumber daya boolean untuk berbagai ukuran layar:</p> + +<p class="code-caption">res/values/bools.xml</p> +<pre> +<!-- Default boolean values --> +<resources> + <bool name="large_layout">false</bool> +</resources> +</pre> + +<p class="code-caption">res/values-large/bools.xml</p> +<pre> +<!-- Large screen boolean values --> +<resources> + <bool name="large_layout">true</bool> +</resources> +</pre> + +<p>Selanjutnya Anda bisa menetapkan nilai {@code mIsLargeLayout} selama +metode {@link android.app.Activity#onCreate onCreate()} aktivitas:</p> + +<pre> +boolean mIsLargeLayout; + +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + mIsLargeLayout = getResources().getBoolean(R.bool.large_layout); +} +</pre> + + + +<h3 id="ActivityAsDialog">Menampilkan aktivitas sebagai dialog pada layar besar</h3> + +<p>Sebagai ganti menampilkan dialog berupa UI layar penuh saat di layar kecil, Anda bisa memperoleh +hasil yang sama dengan menampilkan {@link android.app.Activity} sebagai dialog saat di +layar besar. Pendekatan yang Anda pilih bergantung pada desain aplikasi, namun +menampilkan aktivitas sebagai dialog sering kali berguna bila aplikasi Anda sudah didesain untuk +layar kecil dan Anda ingin meningkatkan pengalaman pada tablet dengan menampilkan aktivitas berjangka pendek +sebagai dialog.</p> + +<p>Untuk menampilkan aktivitas sebagai dialog hanya saat di layar besar, +terapkan tema {@link android.R.style#Theme_Holo_DialogWhenLarge Theme.Holo.DialogWhenLarge} + pada elemen manifes <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>:</p> + +<pre> +<activity android:theme="@android:style/Theme.Holo.DialogWhenLarge" > +</pre> + +<p>Untuk informasi selengkapnya tentang mengatur gaya aktivitas Anda dengan tema, lihat panduan <a href="{@docRoot}guide/topics/ui/themes.html">Gaya dan Tema</a>.</p> + + + +<h2 id="DismissingADialog">Menutup Dialog</h2> + +<p>Bila pengguna menyentuh salah satu tombol tindakan yang dibuat dengan +{@link android.app.AlertDialog.Builder}, sistem akan menutup dialog untuk Anda.</p> + +<p>Sistem juga menutup dialog bila pengguna menyentuh sebuah item dalam daftar dialog, kecuali +bila daftar itu menggunakan tombol radio atau kotak cek. Jika tidak, Anda bisa menutup dialog secara manual +dengan memanggil {@link android.support.v4.app.DialogFragment#dismiss()} pada {@link +android.support.v4.app.DialogFragment} Anda.</p> + +<p>Jika Anda perlu melakukan +tindakan tertentu saat dialog menghilang, Anda bisa menerapkan metode {@link +android.support.v4.app.DialogFragment#onDismiss onDismiss()} dalam {@link +android.support.v4.app.DialogFragment} Anda.</p> + +<p>Anda juga bisa <em>membatalkan</em> dialog. Ini merupakan kejadian khusus yang menunjukkan bahwa pengguna +secara eksplisit meninggalkan dialog tanpa menyelesaikan tugas. Hal ini terjadi jika pengguna menekan tombol +<em>Back</em>, menyentuh layar di luar area dialog, +atau jika Anda secara eksplisit memanggil {@link android.app.Dialog#cancel()} pada {@link +android.app.Dialog} (seperti saat merespons tombol "Cancel" dalam dialog).</p> + +<p>Seperti yang ditampilkan dalam contoh di atas, Anda bisa merespons kejadian batal dengan menerapkan +{@link android.support.v4.app.DialogFragment#onCancel onCancel()} dalam kelas {@link +android.support.v4.app.DialogFragment} Anda.</p> + +<p class="note"><strong>Catatan:</strong> Sistem akan memanggil +{@link android.support.v4.app.DialogFragment#onDismiss onDismiss()} pada tiap kejadian yang +memanggil callback {@link android.support.v4.app.DialogFragment#onCancel onCancel()}. Akan tetapi, +jika Anda memanggil {@link android.app.Dialog#dismiss Dialog.dismiss()} atau {@link +android.support.v4.app.DialogFragment#dismiss DialogFragment.dismiss()}, +sistem akan memanggil {@link android.support.v4.app.DialogFragment#onDismiss onDismiss()} <em>namun +bukan</em> {@link android.support.v4.app.DialogFragment#onCancel onCancel()}. Jadi biasanya Anda harus +memanggil {@link android.support.v4.app.DialogFragment#dismiss dismiss()} bila pengguna menekan tombol +<em>positif</em> dalam dialog untuk menghilangkan tampilan dialog.</p> + + diff --git a/docs/html-intl/intl/in/guide/topics/ui/menus.jd b/docs/html-intl/intl/in/guide/topics/ui/menus.jd new file mode 100644 index 000000000000..2cd3e6a33aa5 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/menus.jd @@ -0,0 +1,1031 @@ +page.title=Menu +parent.title=Antarmuka Pengguna +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#xml">Mendefinisikan Menu dalam XML</a></li> + <li><a href="#options-menu">Membuat Menu Opsi</a> + <ol> + <li><a href="#RespondingOptionsMenu">Menangani kejadian klik</a></li> + <li><a href="#ChangingTheMenu">Mengubah item menu saat runtime</a></li> + </ol> + </li> + <li><a href="#context-menu">Membuat Menu Kontekstual</a> + <ol> + <li><a href="#FloatingContextMenu">Membuat menu konteks mengambang</a></li> + <li><a href="#CAB">Menggunakan mode tindakan kontekstual</a></li> + </ol> + </li> + <li><a href="#PopupMenu">Membuat Menu Popup</a> + <ol> + <li><a href="#PopupEvents">Menangani kejadian klik</a></li> + </ol> + </li> + <li><a href="#groups">Membuat Grup Menu</a> + <ol> + <li><a href="#checkable">Menggunakan item menu yang bisa diberi tanda cek</a></li> + </ol> + </li> + <li><a href="#intents">Menambahkan Item Menu Berdasarkan Intent</a> + <ol> + <li><a href="#AllowingToAdd">Memungkinkan aktivitas Anda ditambahkan ke menu lain</a></li> + </ol> + </li> +</ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.view.Menu}</li> + <li>{@link android.view.MenuItem}</li> + <li>{@link android.view.ContextMenu}</li> + <li>{@link android.view.ActionMode}</li> + </ol> + + <h2>Lihat juga</h2> + <ol> + <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action-Bar</a></li> + <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Sumber Daya Menu</a></li> + <li><a href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html">Ucapkan +Selamat Tinggal pada Tombol Menu</a></li> + </ol> +</div> +</div> + +<p>Menu adalah komponen antarmuka pengguna yang lazim dalam banyak tipe aplikasi. Untuk menyediakan pengalaman pengguna yang sudah akrab +dan konsisten, Anda harus menggunakan API {@link android.view.Menu} untuk menyajikan +tindakan dan opsi lain dalam aktivitas kepada pengguna.</p> + +<p>Mulai dengan Android 3.0 (API level 11), perangkat berbasis Android tidak perlu lagi +menyediakan tombol <em>Menu</em> tersendiri. Dengan perubahan ini, aplikasi Android harus bermigrasi dari +dependensi pada panel menu 6 item biasa, dan sebagai ganti menyediakan action-bar untuk menyajikan +berbagai tindakan pengguna yang lazim.</p> + +<p>Walaupun desain dan pengalaman pengguna untuk sebagian item menu telah berubah, semantik untuk mendefinisikan +serangkaian tindakan dan opsi masih berdasarkan pada API {@link android.view.Menu}. Panduan ini +menampilkan cara membuat tiga tipe dasar penyajian menu atau tindakan pada semua +versi Android:</p> + +<dl> + <dt><strong>Menu opsi dan action-bar</strong></dt> + <dd><a href="#options-menu">Menu opsi</a> adalah kumpulan item menu utama untuk suatu +aktivitas. Inilah tempat Anda harus menempatkan tindakan yang berdampak global pada aplikasi, seperti +"Cari", "Tulis email", dan "Pengaturan". + <p>Jika Anda mengembangkan aplikasi untuk Android 2.3 atau yang lebih rendah, pengguna bisa +menampilkan panel menu opsi dengan menekan tombol <em>Menu</em>.</p> + <p>Pada Android 3.0 dan yang lebih tinggi, item menu opsi disajikan melalui <a href="{@docRoot}guide/topics/ui/actionbar.html">action-bar</a> sebagai kombinasi item tindakan +di layar dan opsi overflow. Mulai dengan Android 3.0, tombol <em>Menu</em> dihilangkan (sebagian +perangkat +tidak memilikinya), sehingga Anda harus bermigrasi ke penggunaan action-bar untuk menyediakan akses ke tindakan dan +opsi lainnya.</p> + <p>Lihat bagian tentang <a href="#options-menu">Membuat Menu Opsi</a>.</p> + </dd> + + <dt><strong>Menu konteks dan mode tindakan kontekstual</strong></dt> + + <dd>Menu konteks adalah <a href="#FloatingContextMenu">menu mengambang</a> yang muncul saat +pengguna mengklik lama pada suatu elemen. Menu ini menyediakan tindakan yang memengaruhi konten atau +bingkai konteks yang dipilih. + <p>Saat mengembangkan aplikasi untuk Android 3.0 dan yang lebih tinggi, sebagai gantinya Anda harus menggunakan <a href="#CAB">mode tindakan kontekstual</a> untuk memungkinkan tindakan pada konten yang dipilih. Mode ini menampilkan +item tindakan yang memengaruhi konten yang dipilih dalam baris di bagian atas layar dan memungkinkan pengguna +memilih beberapa item sekaligus.</p> + <p>Lihat bagian tentang <a href="#context-menu">Membuat Menu Kontekstual</a>.</p> +</dd> + + <dt><strong>Menu popup</strong></dt> + <dd>Menu popup menampilkan daftar item secara vertikal yang dipasang pada tampilan yang +memanggil menu. Ini cocok untuk menyediakan kelebihan tindakan yang terkait dengan konten tertentu atau +untuk menyediakan opsi bagi bagian kedua dari suatu perintah. Tindakan di menu popup +<strong>tidak</strong> boleh memengaruhi secara langsung konten yang bersangkutan—yang diperuntukkan bagi +tindakan kontekstual. Melainkan, menu popup adalah untuk tindakan tambahan yang terkait dengan wilayah konten dalam +aktivitas Anda. + <p>Lihat bagian tentang <a href="#PopupMenu">Membuat Menu Popup</a>.</p> +</dd> +</dl> + + + +<h2 id="xml">Mendefinisikan Menu dalam XML</h2> + +<p>Untuk semua tipe menu, Android menyediakan sebuah format XML standar untuk mendefinisikan item menu. +Sebagai ganti membuat menu dalam kode aktivitas, Anda harus mendefinisikan menu dan semua itemnya dalam +<a href="{@docRoot}guide/topics/resources/menu-resource.html">sumber daya menu</a> XML. Anda kemudian bisa +memekarkan sumber daya menu (memuatnya sebagai objek {@link android.view.Menu}) dalam aktivitas atau +fragmen.</p> + +<p>Menggunakan sumber daya menu adalah praktik yang baik karena beberapa alasan:</p> +<ul> + <li>Memvisualisasikan struktur menu dalam XML menjadi lebih mudah.</li> + <li>Cara ini memisahkan konten untuk menu dari kode perilaku aplikasi Anda.</li> + <li>Cara ini memungkinkan Anda membuat konfigurasi menu alternatif untuk berbagai versi platform, +ukuran layar, dan konfigurasi lainnya dengan memanfaatkan kerangka kerja <a href="{@docRoot}guide/topics/resources/index.html">sumber daya aplikasi</a>.</li> +</ul> + +<p>Untuk mendefinisikan menu, buatlah sebuah file XML dalam direktori <code>res/menu/</code> +proyek dan buat menu dengan elemen-elemen berikut:</p> +<dl> + <dt><code><menu></code></dt> + <dd>Mendefinisikan {@link android.view.Menu}, yang merupakan sebuah kontainer untuk item menu. Elemen +<code><menu></code> harus menjadi simpul akar untuk file dan bisa menampung salah satu atau beberapa dari elemen +<code><item></code> dan <code><group></code>.</dd> + + <dt><code><item></code></dt> + <dd>Membuat {@link android.view.MenuItem}, yang mewakili satu item menu. Elemen ini +bisa berisi elemen <code><menu></code> tersarang guna untuk membuat submenu.</dd> + + <dt><code><group></code></dt> + <dd>Kontainer opsional tak terlihat untuk elemen-elemen {@code <item>}. Kontainer ini memungkinkan Anda +mengelompokkan item menu untuk berbagi properti seperti status aktif dan visibilitas. Untuk informasi +selengkapnya, lihat bagian tentang <a href="#groups">Membuat Grup Menu</a>.</dd> +</dl> + + +<p>Berikut ini adalah contoh menu bernama <code>game_menu.xml</code>:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/new_game" + android:icon="@drawable/ic_new_game" + android:title="@string/new_game" + android:showAsAction="ifRoom"/> + <item android:id="@+id/help" + android:icon="@drawable/ic_help" + android:title="@string/help" /> +</menu> +</pre> + +<p>Elemen <code><item></code> mendukung beberapa atribut yang bisa Anda gunakan untuk mendefinisikan penampilan dan perilaku +item. Item menu di atas mencakup atribut berikut:</p> + +<dl> + <dt>{@code android:id}</dt> + <dd>ID sumber daya unik bagi item, yang memungkinkan aplikasi mengenali item +bila pengguna memilihnya.</dd> + <dt>{@code android:icon}</dt> + <dd>Acuan ke drawable untuk digunakan sebagai ikon item.</dd> + <dt>{@code android:title}</dt> + <dd>Acuan ke string untuk digunakan sebagai judul item.</dd> + <dt>{@code android:showAsAction}</dt> + <dd>Menetapkan waktu dan cara item ini muncul sebagai item tindakan di <a href="{@docRoot}guide/topics/ui/actionbar.html">action-bar</a>.</dd> +</dl> + +<p>Ini adalah atribut-atribut terpenting yang harus Anda gunakan, namun banyak lagi yang tersedia. +Untuk informasi tentang semua atribut yang didukung, lihat dokumen <a href="{@docRoot}guide/topics/resources/menu-resource.html">Sumber Daya Menu</a>.</p> + +<p>Anda bisa menambahkan submenu ke sebuah item di menu (kecuali submenu) apa saja dengan menambahkan elemen {@code <menu>} +sebagai anak {@code <item>}. Submenu berguna saat aplikasi Anda memiliki banyak +fungsi yang bisa ditata ke dalam topik-topik, seperti item dalam sebuah baris menu aplikasi PC (File, +Edit, Lihat, dsb.). Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/file" + android:title="@string/file" > + <!-- "file" submenu --> + <menu> + <item android:id="@+id/create_new" + android:title="@string/create_new" /> + <item android:id="@+id/open" + android:title="@string/open" /> + </menu> + </item> +</menu> +</pre> + +<p>Untuk menggunakan menu dalam aktivitas, Anda perlu memekarkan sumber daya menu (mengonversi sumber daya XML +menjadi objek yang bisa diprogram) dengan menggunakan {@link android.view.MenuInflater#inflate(int,Menu) +MenuInflater.inflate()}. Di bagian berikut, Anda akan melihat cara memekarkan menu untuk tiap +tipe menu.</p> + + + +<h2 id="options-menu">Membuat Menu Opsi</h2> + +<div class="figure" style="width:200px;margin:0"> + <img src="{@docRoot}images/options_menu.png" height="333" alt="" /> + <p class="img-caption"><strong>Gambar 1.</strong> Menu opsi di +Browser, pada Android 2.3.</p> +</div> + +<p>Menu opsi adalah tempat Anda harus menyertakan tindakan dan opsi lain yang relevan dengan +konteks aktivitas saat ini, seperti "Cari", "Tulis email", dan "Pengaturan".</p> + +<p>Tempat item dalam menu opsi muncul di layar bergantung pada versi aplikasi yang Anda +kembangkan:</p> + +<ul> + <li>Jika Anda mengembangkan aplikasi untuk <strong>Android 2.3.x (API level 10) atau +yang lebih rendah</strong>, konten menu opsi muncul pada bagian bawah layar bila pengguna +menekan tombol <em>Menu</em>, seperti yang ditampilkan dalam gambar 1. Bila dibuka, bagian yang terlihat pertama adalah +menu +ikon, yang menampung hingga enam item menu. Jika menu Anda menyertakan lebih dari enam item, Android akan meletakkan +item keenam dan sisanya ke dalam menu kelebihan, yang bisa dibuka pengguna dengan memilih +<em>More</em>.</li> + + <li>Jika Anda mengembangkan aplikasi untuk <strong>Android 3.0 (API level 11) dan +yang lebih tinggi</strong>, item menu opsi tersedia dalam <a href="{@docRoot}guide/topics/ui/actionbar.html">action-bar</a>. Secara default, sistem +meletakkan semua item dalam kelebihan tindakan, yang bisa ditampilkan pengguna dengan ikon kelebihan tindakan di +sisi kanan action-bar (atau dengan menekan tombol <em>Menu</em> perangkat, jika tersedia). Untuk +mengaktifkan +akses cepat ke tindakan penting, Anda bisa mempromosikan beberapa item agar muncul pada action-bar dengan menambahkan +{@code android:showAsAction="ifRoom"} ke elemen-elemen {@code <item>} yang bersangkutan (lihat gambar +2). <p>Untuk informasi selengkapnya tentang item tindakan dan perilaku action-bar lainnya, lihat panduan <a href="{@docRoot}guide/topics/ui/actionbar.html">Action-Bar</a>. </p> +<p class="note"><strong>Catatan:</strong> Sekalipun Anda <em>tidak</em> mengembangkan aplikasi untuk Android 3.0 atau +yang lebih tinggi, Anda bisa membuat layout action-bar sendiri untuk mendapatkan efek serupa. Untuk contoh cara +mendukung versi Android yang lebih lama dengan action-bar, lihat contoh <a href="{@docRoot}resources/samples/ActionBarCompat/index.html">Kompatibilitas Action-Bar</a> +.</p> +</li> +</ul> + +<img src="{@docRoot}images/ui/actionbar.png" alt="" /> +<p class="img-caption"><strong>Gambar 2.</strong> Action-bar dari aplikasi <a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>, yang menampilkan +tab-tab navigasi dan item tindakan kamera (plus tombol kelebihan tindakan).</p> + +<p>Anda bisa mendeklarasikan item untuk menu opsi dari subkelas {@link android.app.Activity} +atau subkelas {@link android.app.Fragment}. Jika aktivitas maupun fragmen Anda +mendeklarasikan item menu opsi, keduanya akan dikombinasikan dalam UI. Item aktivitas akan muncul +lebih dahulu, diikuti oleh item tiap fragmen sesuai dengan urutan penambahan fragmen ke +aktivitas. Jika perlu, Anda bisa menyusun ulang item menu dengan atribut {@code android:orderInCategory} +dalam setiap {@code <item>} yang perlu Anda pindahkan.</p> + +<p>Untuk menetapkan menu opsi suatu aktivitas, kesampingkan {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} (fragmen-fragmen menyediakan +callback {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} sendiri). Dalam metode ini +, Anda bisa memekarkan sumber daya menu (<a href="#xml">yang didefinisikan dalam XML</a>) menjadi {@link +android.view.Menu} yang disediakan dalam callback. Misalnya:</p> + +<pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + MenuInflater inflater = {@link android.app.Activity#getMenuInflater()}; + inflater.inflate(R.menu.game_menu, menu); + return true; +} +</pre> + +<p>Anda juga bisa menambahkan item menu dengan menggunakan {@link android.view.Menu#add(int,int,int,int) +add()} dan mengambil item dengan {@link android.view.Menu#findItem findItem()} untuk merevisi propertinya +dengan API {@link android.view.MenuItem}.</p> + +<p>Jika Anda mengembangkan aplikasi untuk Android 2.3.x dan yang lebih rendah, sistem akan memanggil {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} untuk membuat menu opsi +bila pengguna membuka menu untuk pertama kali. Jika Anda mengembangkan aplikasi untuk Android 3.0 dan yang lebih tinggi, +sistem akan memanggil {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} saat +memulai aktivitas, untuk menampilkan item menu pada action-bar.</p> + + + +<h3 id="RespondingOptionsMenu">Menangani kejadian klik</h3> + +<p>Bila pengguna memilih item dari menu opsi (termasuk item tindakan dalam action-bar), +sistem akan memanggil metode {@link android.app.Activity#onOptionsItemSelected(MenuItem) +onOptionsItemSelected()} aktivitas Anda. Metode ini meneruskan {@link android.view.MenuItem} yang dipilih. Anda +bisa mengidentifikasi item dengan memanggil {@link android.view.MenuItem#getItemId()}, yang menghasilkan +ID unik untuk item menu itu (yang didefinisikan oleh atribut {@code android:id} dalam sumber daya menu atau dengan +integer yang diberikan ke metode {@link android.view.Menu#add(int,int,int,int) add()}). Anda bisa mencocokkan +ID ini dengan item menu yang diketahui untuk melakukan tindakan yang sesuai. Misalnya:</p> + +<pre> +@Override +public boolean onOptionsItemSelected(MenuItem item) { + // Handle item selection + switch (item.getItemId()) { + case R.id.new_game: + newGame(); + return true; + case R.id.help: + showHelp(); + return true; + default: + return super.onOptionsItemSelected(item); + } +} +</pre> + +<p>Bila Anda berhasil menangani sebuah item menu, kembalikan {@code true}. Jika tidak menangani item menu +, Anda harus memanggil implementasi superkelas {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} (implementasi default +menghasilkan false).</p> + +<p>Jika aktivitas Anda menyertakan fragmen, sistem akan memanggil lebih dahulu {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} untuk aktivitas, kemudian +untuk setiap fragmen (sesuai dengan urutan penambahan fragmen) hingga satu fragmen mengembalikan +{@code true} atau semua fragmen telah dipanggil.</p> + +<p class="note"><strong>Tip:</strong> Android 3.0 menambahkan kemampuan mendefinisikan perilaku on-click +untuk item menu dalam XML, dengan menggunakan atribut {@code android:onClick}. Nilai atribut +harus berupa nama metode yang didefinisikan aktivitas dengan menggunakan menu. Metode +harus bersifat publik dan menerima satu parameter {@link android.view.MenuItem}—bila sistem +memanggilnya, metode ini akan meneruskan item menu yang dipilih. Untuk informasi selengkapnya dan contoh, lihat dokumen <a href="{@docRoot}guide/topics/resources/menu-resource.html">Sumber Daya Menu</a>.</p> + +<p class="note"><strong>Tip:</strong> Jika aplikasi Anda berisi banyak aktivitas dan +sebagian menyediakan menu opsi yang sama, pertimbangkan untuk membuat +aktivitas yang tidak mengimplementasikan apa-apa kecuali metode {@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()} dan {@link android.app.Activity#onOptionsItemSelected(MenuItem) +onOptionsItemSelected()}. Kemudian perluas kelas ini untuk setiap aktivitas yang harus menggunakan +menu opsi yang sama. Dengan begini, Anda bisa mengelola satu set kode untuk menangani tindakan menu +dan setiap kelas turunan mewarisi perilaku menu. +Jika ingin menambahkan item menu ke salah satu aktivitas turunan, +kesampingkan {@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()} dalam aktivitas itu. Panggil {@code super.onCreateOptionsMenu(menu)} agar +item menu asli dibuat, kemudian tambahkan item menu yang baru dengan {@link +android.view.Menu#add(int,int,int,int) menu.add()}. Anda juga bisa mengesampingkan +perilaku superkelas untuk setiap item menu.</p> + + +<h3 id="ChangingTheMenu">Mengubah item menu saat runtime</h3> + +<p>Setelah sistem memanggil {@link android.app.Activity#onCreateOptionsMenu(Menu) +onCreateOptionsMenu()}, sistem akan mempertahankan instance {@link android.view.Menu} yang Anda tempatkan dan +tidak akan memanggil {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} +lagi kecuali menu diinvalidkan karena suatu alasan. Akan tetapi, Anda harus menggunakan {@link +android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} hanya untuk membuat +status menu awal dan tidak untuk membuat perubahan selama daur hidup aktivitas.</p> + +<p>Jika Anda ingin mengubah menu opsi berdasarkan +kejadian yang terjadi selama daur hidup aktivitas, Anda bisa melakukannya dalam metode +{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}. Metode ini +meneruskan objek {@link android.view.Menu} sebagaimana adanya saat ini sehingga Anda bisa mengubahnya, +seperti menambah, menghapus, atau menonaktifkan item. (Fragmen juga menyediakan callback {@link +android.app.Fragment#onPrepareOptionsMenu onPrepareOptionsMenu()}.)</p> + +<p>Pada Android 2.3.x dan yang lebih rendah, sistem akan memanggil {@link +android.app.Activity#onPrepareOptionsMenu(Menu) +onPrepareOptionsMenu()} setiap kali pengguna membuka menu opsi (menekan tombol <em>Menu</em> +).</p> + +<p>Pada Android 3.0 dan yang lebih tinggi, menu opsi dianggap sebagai selalu terbuka saat item menu +ditampilkan pada action-bar. Bila ada kejadian dan Anda ingin melakukan pembaruan menu, Anda harus +memanggil {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} untuk meminta +sistem memanggil {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p> + +<p class="note"><strong>Catatan:</strong> +Anda tidak boleh mengubah item dalam menu opsi berdasarkan {@link android.view.View} yang saat ini +difokus. Saat dalam mode sentuh (bila pengguna tidak sedang menggunakan trackball atau d-pad), tampilan +tidak bisa mengambil fokus, sehingga Anda tidak boleh menggunakan fokus sebagai dasar untuk mengubah +item dalam menu opsi. Jika Anda ingin menyediakan item menu yang peka konteks pada {@link +android.view.View}, gunakan <a href="#context-menu">Menu Konteks</a>.</p> + + + + +<h2 id="context-menu">Membuat Menu Kontekstual</h2> + +<div class="figure" style="width:420px;margin-top:-1em"> + <img src="{@docRoot}images/ui/menu-context.png" alt="" /> + <p class="img-caption"><strong>Gambar 3.</strong> Cuplikan layar menu konteks mengambang (kiri) +dan action-bar kontekstual (kanan).</p> +</div> + +<p>Menu kontekstual menawarkan tindakan yang memengaruhi item atau bingkai konteks tertentu dalam UI. Anda +bisa menyediakan menu konteks untuk setiap tampilan, tetapi menu ini paling sering digunakan untuk item pada {@link +android.widget.ListView}, {@link android.widget.GridView}, atau kumpulan tampilan lainnya yang bisa digunakan +pengguna untuk melakukan tindakan langsung pada setiap item.</p> + +<p>Ada dua cara menyediakan tindakan kontekstual:</p> +<ul> + <li>Dalam <a href="#FloatingContextMenu">menu konteks mengambang</a>. Menu muncul sebagai +daftar item menu mengambang (serupa dengan dialog) bila pengguna mengklik lama (menekan dan +menahan) pada tampilan yang mendeklarasikan dukungan bagi menu konteks. Pengguna bisa melakukan +tindakan kontekstual pada satu item untuk setiap kalinya.</li> + + <li>Dalam <a href="#CAB">mode tindakan kontekstual</a>. Mode ini adalah implementasi sistem +{@link android.view.ActionMode} yang menampilkan <em>action-bar kontekstual</em> di bagian atas +layar dengan item tindakan yang memengaruhi item(-item) yang dipilih. Bila mode ini aktif, pengguna +bisa melakukan tindakan pada beberapa item sekaligus (jika aplikasi Anda mengizinkannya).</li> +</ul> + +<p class="note"><strong>Catatan:</strong> Mode tindakan kontekstual tersedia pada Android 3.0 (API +level 11) dan yang lebih tinggi dan merupakan teknik yang lebih disukai untuk menampilkan tindakan kontekstual bila +tersedia. Jika aplikasi Anda mendukung versi yang lebih rendah daripada 3.0, maka Anda harus mundur ke +menu konteks mengambang pada perangkat-perangkat itu.</p> + + +<h3 id="FloatingContextMenu">Membuat menu konteks mengambang</h3> + +<p>Untuk menyediakan menu konteks mengambang:</p> +<ol> + <li>Daftarkan {@link android.view.View} ke menu konteks yang harus dikaitkan dengan +memanggil {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} dan teruskan +{@link android.view.View} ke menu itu. + <p>Jika aktivitas Anda menggunakan {@link android.widget.ListView} atau {@link android.widget.GridView} dan +Anda ingin setiap item untuk menyediakan menu konteks yang sama, daftarkan semua item ke menu konteks dengan +meneruskan {@link android.widget.ListView} atau {@link android.widget.GridView} ke {@link +android.app.Activity#registerForContextMenu(View) registerForContextMenu()}.</p> +</li> + + <li>Implementasikan metode {@link +android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} +dalam {@link android.app.Activity} atau {@link android.app.Fragment} Anda. + <p>Bila tampilan yang terdaftar menerima kejadian klik-lama, sistem akan memanggil metode {@link +android.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} +Anda. Inilah tempat Anda mendefinisikan item menu, biasanya dengan memekarkan sumber daya menu. Misalnya: +</p> +<pre> +@Override +public void onCreateContextMenu(ContextMenu menu, View v, + ContextMenuInfo menuInfo) { + super.onCreateContextMenu(menu, v, menuInfo); + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.context_menu, menu); +} +</pre> + +<p>{@link android.view.MenuInflater} memungkinkan Anda untuk memekarkan menu konteks <a href="{@docRoot}guide/topics/resources/menu-resource.html">sumber daya menu</a>. Parameter metode callback +menyertakan {@link android.view.View} +yang dipilih pengguna dan objek {@link android.view.ContextMenu.ContextMenuInfo} yang menyediakan +informasi tambahan tentang item yang dipilih. Jika aktivitas Anda memiliki beberapa tampilan yang masing-masingnya menyediakan +menu konteks berbeda, Anda bisa menggunakan parameter ini untuk menentukan menu konteks yang harus +dimekarkan.</p> +</li> + +<li>Implementasikan {@link android.app.Activity#onContextItemSelected(MenuItem) +onContextItemSelected()}. + <p>Bila pengguna memilih item menu, sistem akan memanggil metode ini sehingga Anda bisa melakukan +tindakan yang sesuai. Misalnya:</p> + +<pre> +@Override +public boolean onContextItemSelected(MenuItem item) { + AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); + switch (item.getItemId()) { + case R.id.edit: + editNote(info.id); + return true; + case R.id.delete: + deleteNote(info.id); + return true; + default: + return super.onContextItemSelected(item); + } +} +</pre> + +<p>Metode {@link android.view.MenuItem#getItemId()} melakukan query ID untuk +item menu yang dipilih, yang harus Anda tetapkan ke setiap item menu dalam XML dengan menggunakan atribut {@code +android:id}, seperti yang ditampilkan di bagian tentang <a href="#xml">Mendefinisikan Menu dalam +XML</a>.</p> + +<p>Bila Anda berhasil menangani sebuah item menu, kembalikan {@code true}. Jika tidak menangani item menu, +Anda harus meneruskan item menu ke implementasi superkelas. Jika aktivitas Anda menyertakan fragmen, +aktivitas akan menerima callback ini lebih dahulu. Dengan memanggil superkelas bila tidak ditangani, sistem +meneruskan kejadian ke metode callback di setiap fragmen, satu per satu (sesuai dengan urutan +penambahan fragmen) hingga {@code true} atau {@code false} dikembalikan. (Implementasi default +untuk {@link android.app.Activity} dan {@code android.app.Fragment} mengembalikan {@code +false}, sehingga Anda harus selalu memanggil superkelas bila tidak ditangani.)</p> +</li> +</ol> + + +<h3 id="CAB">Menggunakan mode tindakan kontekstual</h3> + +<p>Mode tindakan kontekstual adalah implementasi sistem {@link android.view.ActionMode} yang +memfokuskan interaksi pengguna pada upaya melakukan tindakan kontekstual. Bila seorang +pengguna mengaktifkan mode ini dengan memilih item, <em>action-bar kontekstual</em> akan muncul di bagian atas +layar untuk menampilkan tindakan yang bisa dilakukan pengguna pada item yang dipilih saat ini. Selagi mode ini +diaktifkan, pengguna bisa memilih beberapa item (jika Anda mengizinkan), membatalkan pilihan item, dan melanjutkan +penelusuran dalam aktivitas (sebanyak yang ingin Anda izinkan). Mode tindakan dinonaktifkan +dan action-bar kontekstual menghilang bila pengguna membatalkan pilihan semua item, menekan tombol BACK, +atau memilih tindakan <em>Done</em> di sisi kiri action-bar.</p> + +<p class="note"><strong>Catatan:</strong> Action-bar kontekstual tidak harus +terkait dengan <a href="{@docRoot}guide/topics/ui/actionbar.html">action-bar</a>. Action-bar ini beroperasi +secara independen, walaupun action-bar kontekstual secara visual mengambil alih +posisi action-bar.</p> + +<p>Jika Anda mengembangkan aplikasi untuk Android 3.0 (API level 11) atau yang lebih tinggi, Anda +biasanya harus menggunakan mode tindakan kontekstual untuk menampilkan tindakan kontekstual, sebagai ganti <a href="#FloatingContextMenu">menu konteks mengambang</a>.</p> + +<p>Untuk tampilan yang menyediakan tindakan kontekstual, Anda biasanya harus memanggil mode tindakan kontekstual +pada salah satu dari dua kejadian (atau keduanya):</p> +<ul> + <li>Pengguna mengklik-lama pada tampilan.</li> + <li>Pengguna memilih kotak cek atau komponen UI yang serupa dalam tampilan.</li> +</ul> + +<p>Cara aplikasi memanggil mode tindakan kontekstual dan mendefinisikan perilaku setiap +tindakan bergantung pada desain Anda. Pada dasarnya ada dua desain:</p> +<ul> + <li>Untuk tindakan kontekstual pada tampilan individual dan tak didukung.</li> + <li>Untuk tindakan kontekstual batch pada grup item dalam {@link +android.widget.ListView} atau {@link android.widget.GridView} (memungkinkan pengguna memilih beberapa +item dan melakukan tindakan pada semua item itu).</li> +</ul> + +<p>Bagian berikut ini menjelaskan penyiapan yang diperlukan untuk setiap skenario.</p> + + +<h4 id="CABforViews">Mengaktifkan mode tindakan kontekstual untuk tampilan individual</h4> + +<p>Jika Anda ingin memanggil mode tindakan kontekstual hanya bila pengguna memilih +tampilan tertentu, Anda harus:</p> +<ol> + <li>Mengimplementasikan antarmuka {@link android.view.ActionMode.Callback}. Dalam metode callback-nya, Anda +bisa menetapkan tindakan untuk action-bar kontekstual, merespons kejadian klik pada item tindakan, dan +menangani kejadian daur hidup lainnya untuk mode tindakan itu.</li> + <li>Memanggil {@link android.app.Activity#startActionMode startActionMode()} bila Anda ingin menampilkan +action-bar (seperti saat pengguna mengklik-lama pada tampilan).</li> +</ol> + +<p>Misalnya:</p> + +<ol> + <li>Implementasikan antarmuka {@link android.view.ActionMode.Callback ActionMode.Callback}: +<pre> +private ActionMode.Callback mActionModeCallback = new ActionMode.Callback() { + + // Called when the action mode is created; startActionMode() was called + @Override + public boolean onCreateActionMode(ActionMode mode, Menu menu) { + // Inflate a menu resource providing context menu items + MenuInflater inflater = mode.getMenuInflater(); + inflater.inflate(R.menu.context_menu, menu); + return true; + } + + // Called each time the action mode is shown. Always called after onCreateActionMode, but + // may be called multiple times if the mode is invalidated. + @Override + public boolean onPrepareActionMode(ActionMode mode, Menu menu) { + return false; // Return false if nothing is done + } + + // Called when the user selects a contextual menu item + @Override + public boolean onActionItemClicked(ActionMode mode, MenuItem item) { + switch (item.getItemId()) { + case R.id.menu_share: + shareCurrentItem(); + mode.finish(); // Action picked, so close the CAB + return true; + default: + return false; + } + } + + // Called when the user exits the action mode + @Override + public void onDestroyActionMode(ActionMode mode) { + mActionMode = null; + } +}; +</pre> + +<p>Perhatikan bahwa kejadian callback ini hampir persis sama dengan callback untuk <a href="#options-menu">menu opsi</a>, hanya saja setiap callback ini juga meneruskan objek {@link +android.view.ActionMode} yang terkait dengan kejadian. Anda bisa menggunakan API {@link +android.view.ActionMode} untuk membuat berbagai perubahan pada CAB, seperti merevisi judul dan +subjudul dengan {@link android.view.ActionMode#setTitle setTitle()} dan {@link +android.view.ActionMode#setSubtitle setSubtitle()} (berguna untuk menunjukkan jumlah item +yang dipilih).</p> + +<p>Juga perhatikan bahwa contoh di atas mengatur variabel {@code mActionMode} ke nol bila +mode tindakan dimusnahkan. Dalam langkah berikutnya, Anda akan melihat cara variabel diinisialisasi dan kegunaan menyimpan +variabel anggota dalam aktivitas atau fragmen.</p> +</li> + + <li>Panggil {@link android.app.Activity#startActionMode startActionMode()} untuk mengaktifkan +mode tindakan kontekstual bila sesuai, seperti saat merespons klik-lama pada {@link +android.view.View}:</p> + +<pre> +someView.setOnLongClickListener(new View.OnLongClickListener() { + // Called when the user long-clicks on someView + public boolean onLongClick(View view) { + if (mActionMode != null) { + return false; + } + + // Start the CAB using the ActionMode.Callback defined above + mActionMode = getActivity().startActionMode(mActionModeCallback); + view.setSelected(true); + return true; + } +}); +</pre> + +<p>Bila Anda memanggil {@link android.app.Activity#startActionMode startActionMode()}, sistem akan mengembalikan +{@link android.view.ActionMode} yang dibuat. Dengan menyimpannya dalam variabel anggota, Anda bisa +membuat perubahan ke action-bar kontekstual sebagai respons terhadap kejadian lainnya. Dalam contoh di atas, +{@link android.view.ActionMode} digunakan untuk memastikan bahwa instance {@link android.view.ActionMode} +tidak dibuat kembali jika sudah aktif, dengan memeriksa apakah anggota bernilai nol sebelum memulai +mode tindakan.</p> +</li> +</ol> + + + +<h4 id="CABforListView">Mengaktifkan tindakan kontekstual batch dalam ListView atau GridView</h4> + +<p>Jika Anda memiliki sekumpulan item dalam {@link android.widget.ListView} atau {@link +android.widget.GridView} (atau ekstensi {@link android.widget.AbsListView} lainnya) dan ingin +mengizinkan pengguna melakukan tindakan batch, Anda harus:</p> + +<ul> + <li>Mengimplementasikan antarmuka {@link android.widget.AbsListView.MultiChoiceModeListener} dan mengaturnya +untuk grup tampilan dengan {@link android.widget.AbsListView#setMultiChoiceModeListener +setMultiChoiceModeListener()}. Dalam metode callback listener, Anda bisa menetapkan tindakan +untuk action-bar kontekstual, merespons kejadian klik pada item tindakan, dan menangani callback lainnya +yang diwarisi dari antarmuka {@link android.view.ActionMode.Callback}.</li> + + <li>Panggil {@link android.widget.AbsListView#setChoiceMode setChoiceMode()} dengan argumen {@link +android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL}.</li> +</ul> + +<p>Misalnya:</p> + +<pre> +ListView listView = getListView(); +listView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE_MODAL); +listView.setMultiChoiceModeListener(new MultiChoiceModeListener() { + + @Override + public void onItemCheckedStateChanged(ActionMode mode, int position, + long id, boolean checked) { + // Here you can do something when items are selected/de-selected, + // such as update the title in the CAB + } + + @Override + public boolean onActionItemClicked(ActionMode mode, MenuItem item) { + // Respond to clicks on the actions in the CAB + switch (item.getItemId()) { + case R.id.menu_delete: + deleteSelectedItems(); + mode.finish(); // Action picked, so close the CAB + return true; + default: + return false; + } + } + + @Override + public boolean onCreateActionMode(ActionMode mode, Menu menu) { + // Inflate the menu for the CAB + MenuInflater inflater = mode.getMenuInflater(); + inflater.inflate(R.menu.context, menu); + return true; + } + + @Override + public void onDestroyActionMode(ActionMode mode) { + // Here you can make any necessary updates to the activity when + // the CAB is removed. By default, selected items are deselected/unchecked. + } + + @Override + public boolean onPrepareActionMode(ActionMode mode, Menu menu) { + // Here you can perform updates to the CAB due to + // an {@link android.view.ActionMode#invalidate} request + return false; + } +}); +</pre> + +<p>Demikian saja. Kini bila pengguna memilih item dengan klik-lama, sistem akan memanggil metode {@link +android.widget.AbsListView.MultiChoiceModeListener#onCreateActionMode onCreateActionMode()} +dan menampilkan action-bar kontekstual bersama tindakan yang ditetapkan. Saat +action-bar kontekstual terlihat, pengguna bisa memilih item tambahan.</p> + +<p>Dalam beberapa kasus di mana tindakan kontekstual menyediakan item tindakan umum, Anda mungkin +ingin menambahkan kotak cek atau elemen UI serupa yang memungkinkan pengguna memilih item, karena pengguna +mungkin tidak menemukan perilaku klik-lama. Bila pengguna memilih kotak cek itu, Anda +bisa memanggil mode tindakan kontekstual dengan mengatur item daftar yang bersangkutan ke +status diberi tanda cek dengan {@link android.widget.AbsListView#setItemChecked setItemChecked()}.</p> + + + + +<h2 id="PopupMenu">Membuat Menu Popup</h2> + +<div class="figure" style="width:220px"> +<img src="{@docRoot}images/ui/popupmenu.png" alt="" /> +<p><strong>Gambar 4.</strong> Menu popup dalam aplikasi Gmail, dikaitkan pada +tombol kelebihan di sudut kanan atas.</p> +</div> + +<p>{@link android.widget.PopupMenu} adalah menu modal yang dikaitkan pada {@link android.view.View}. +Menu ini muncul di bawah tampilan jangkar jika ada ruang, atau di atas tampilan jika tidak ada. Menu ini berguna untuk:</p> +<ul> + <li>Menyediakan menu bergaya kelebihan (overflow) untuk tindakan yang <em>berkaitan dengan</em> konten tertentu (seperti +header email Gmail, yang ditampilkan dalam gambar 4). + <p class="note"><strong>Catatan:</strong> Ini tidak sama dengan menu konteks, yang umumnya +untuk tindakan yang <em>memengaruhi</em> konten yang dipilih. Untuk tindakan yang memengaruhi +konten yang dipilih, gunakan <a href="#CAB">mode tindakan kontekstual</a> atau <a href="#FloatingContextMenu">menu konteks mengambang</a>.</p></li> + <li>Menyediakan bagian kedua dari kalimat perintah (seperti tombol bertanda "Tambah" +yang menghasilkan menu popup dengan berbagai opsi "Tambah").</li> + <li>Menyediakan daftar menurun yang serupa dengan {@link android.widget.Spinner} yang tidak mempertahankan +pilihan persisten.</li> +</ul> + + +<p class="note"><strong>Catatan:</strong> {@link android.widget.PopupMenu} tersedia dengan API +level 11 dan yang lebih tinggi.</p> + +<p>Jika Anda <a href="#xml">mendefinisikan menu dalam XML</a>, berikut ini adalah cara Anda menampilkan menu popup:</p> +<ol> + <li>Buat instance {@link android.widget.PopupMenu} bersama konstruktornya, yang mengambil +aplikasi saat ini {@link android.content.Context} dan {@link android.view.View} yang akan menjadi tempat mengaitkan +menu.</li> + <li>Gunakan {@link android.view.MenuInflater} untuk memekarkan sumber daya menu Anda ke dalam objek {@link +android.view.Menu} yang dikembalikan oleh {@link +android.widget.PopupMenu#getMenu() PopupMenu.getMenu()}. Pada API level 14 ke atas, Anda bisa menggunakan +{@link android.widget.PopupMenu#inflate PopupMenu.inflate()} sebagai gantinya.</li> + <li>Panggil {@link android.widget.PopupMenu#show() PopupMenu.show()}.</li> +</ol> + +<p>Misalnya, berikut ini adalah tombol dengan atribut {@link android.R.attr#onClick android:onClick} +yang menampilkan menu popup:</p> + +<pre> +<ImageButton + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:src="@drawable/ic_overflow_holo_dark" + android:contentDescription="@string/descr_overflow_button" + android:onClick="showPopup" /> +</pre> + +<p>Aktivitas nanti bisa menampilkan menu popup seperti ini:</p> + +<pre> +public void showPopup(View v) { + PopupMenu popup = new PopupMenu(this, v); + MenuInflater inflater = popup.getMenuInflater(); + inflater.inflate(R.menu.actions, popup.getMenu()); + popup.show(); +} +</pre> + +<p>Dalam API level 14 dan yang lebih tinggi, Anda bisa menggabungkan dua baris yang memekarkan menu dengan {@link +android.widget.PopupMenu#inflate PopupMenu.inflate()}.</p> + +<p>Menu akan menghilang bila pengguna memilih item atau menyentuh di luar +area menu. Anda bisa mendengarkan kejadian menghilangkan dengan menggunakan {@link +android.widget.PopupMenu.OnDismissListener}.</p> + +<h3 id="PopupEvents">Menangani kejadian klik</h3> + +<p>Untuk melakukan suatu +tindakan bila pengguna memilih item menu, Anda harus mengimplementasikan antarmuka {@link +android.widget.PopupMenu.OnMenuItemClickListener} dan mendaftarkannya pada {@link +android.widget.PopupMenu} dengan memanggil {@link android.widget.PopupMenu#setOnMenuItemClickListener +setOnMenuItemclickListener()}. Bila pengguna memilih item, sistem akan memanggil callback {@link +android.widget.PopupMenu.OnMenuItemClickListener#onMenuItemClick onMenuItemClick()} dalam +antarmuka Anda.</p> + +<p>Misalnya:</p> + +<pre> +public void showMenu(View v) { + PopupMenu popup = new PopupMenu(this, v); + + // This activity implements OnMenuItemClickListener + popup.setOnMenuItemClickListener(this); + popup.inflate(R.menu.actions); + popup.show(); +} + +@Override +public boolean onMenuItemClick(MenuItem item) { + switch (item.getItemId()) { + case R.id.archive: + archive(item); + return true; + case R.id.delete: + delete(item); + return true; + default: + return false; + } +} +</pre> + + +<h2 id="groups">Membuat Grup Menu</h2> + +<p>Grup menu adalah sekumpulan item menu yang sama-sama memiliki ciri (trait) tertentu. Dengan grup, Anda +bisa:</p> +<ul> + <li>Menampilkan atau menyembunyikan semua item dengan {@link android.view.Menu#setGroupVisible(int,boolean) +setGroupVisible()}</li> + <li>Mengaktifkan atau mennonaktifkan semua item dengan {@link android.view.Menu#setGroupEnabled(int,boolean) +setGroupEnabled()}</li> + <li>Menetapkan apakah semua item bisa diberi tanda cek dengan {@link +android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</li> +</ul> + +<p>Anda bisa membuat grup dengan menyarangkan elemen-elemen {@code <item>} dalam elemen {@code <group>} +dalam sumber daya menu atau dengan menetapkan ID grup dengan metode {@link +android.view.Menu#add(int,int,int,int) add()}.</p> + +<p>Berikut ini adalah contoh sumber daya menu yang berisi sebuah grup:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/menu_save" + android:icon="@drawable/menu_save" + android:title="@string/menu_save" /> + <!-- menu group --> + <group android:id="@+id/group_delete"> + <item android:id="@+id/menu_archive" + android:title="@string/menu_archive" /> + <item android:id="@+id/menu_delete" + android:title="@string/menu_delete" /> + </group> +</menu> +</pre> + +<p>Item yang berada dalam grup akan muncul pada level yang sama dengan item pertama—ketiga item +dalam menu adalah bersaudara. Akan tetapi, Anda bisa memodifikasi ciri kedua +item dalam grup dengan mengacu ID grup dan menggunakan metode yang tercantum di atas. Sistem +juga tidak akan memisahkan item yang telah dikelompokkan. Misalnya, jika Anda mendeklarasikan {@code +android:showAsAction="ifRoom"} untuk tiap item, item tersebut akan muncul dalam +action-bar atau dalam kelebihan tindakan.</p> + + +<h3 id="checkable">Menggunakan item menu yang bisa diberi tanda cek</h3> + +<div class="figure" style="width:200px"> + <img src="{@docRoot}images/radio_buttons.png" height="333" alt="" /> + <p class="img-caption"><strong>Gambar 5.</strong> Cuplikan layar submenu dengan +item yang bisa diberi tanda cek.</p> +</div> + +<p>Menu bisa digunakan sebagai antarmuka untuk mengaktifkan dan menonaktifkan opsi, menggunakan kotak cek untuk +opsi mandiri, atau tombol radio untuk grup +opsi yang saling eksklusif. Gambar 5 menampilkan submenu dengan item yang bisa diberi tanda cek dengan +tombol radio.</p> + +<p class="note"><strong>Catatan:</strong> Item menu dalam Icon Menu (dari menu opsi) tidak bisa +menampilkan kotak cek atau tombol radio. Jika Anda memilih untuk membuat item dalam Icon Menu yang bisa diberi tanda cek, +Anda harus menandai status diberi tanda cek secara manual dengan menukar ikon dan/atau teks +tiap kali statusnya berubah.</p> + +<p>Anda bisa mendefinisikan perilaku yang bisa diberi tanda cek untuk tiap item menu dengan menggunakan atribut {@code +android:checkable} dalam elemen {@code <item>}, atau untuk seluruh grup dengan +atribut {@code android:checkableBehavior} dalam elemen {@code <group>}. Misalnya +, semua item dalam grup menu ini bisa diberi tanda cek dengan tombol radio:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <group android:checkableBehavior="single"> + <item android:id="@+id/red" + android:title="@string/red" /> + <item android:id="@+id/blue" + android:title="@string/blue" /> + </group> +</menu> +</pre> + +<p>Atribut {@code android:checkableBehavior} menerima: +<dl> + <dt>{@code single}</dt> + <dd>Hanya satu item dari grup ini yang bisa diberi tanda cek (tombol radio)</dd> + <dt>{@code all}</dt> + <dd>Semua item bisa diberi tanda cek (kotak cek)</dd> + <dt>{@code none}</dt> + <dd>Tidak ada item yang bisa diberi tanda cek</dd> +</dl> + +<p>Anda bisa menerapkan status diberi tanda cek default pada suatu item dengan menggunakan atribut {@code android:checked} dalam +elemen {@code <item>} dan mengubahnya dalam kode dengan metode {@link +android.view.MenuItem#setChecked(boolean) setChecked()}.</p> + +<p>Bila item yang bisa diberi tanda cek dipilih, sistem akan memanggil metode callback setiap item yang dipilih +(seperti {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}). Di sinilah +Anda harus mengatur status kotak cek itu, karena kotak cek atau tombol radio tidak +mengubah statusnya secara otomatis. Anda bisa melakukan query status saat ini suatu item (seperti sebelum +pengguna memilihnya) dengan {@link android.view.MenuItem#isChecked()} kemudian mengatur status diberi tanda cek dengan +{@link android.view.MenuItem#setChecked(boolean) setChecked()}. Misalnya:</p> + +<pre> +@Override +public boolean onOptionsItemSelected(MenuItem item) { + switch (item.getItemId()) { + case R.id.vibrate: + case R.id.dont_vibrate: + if (item.isChecked()) item.setChecked(false); + else item.setChecked(true); + return true; + default: + return super.onOptionsItemSelected(item); + } +} +</pre> + +<p>Jika Anda tidak mengatur status diberi tanda cek dengan cara ini, maka status item (kotak cek atau +tombol radio) yang terlihat tidak akan +berubah bila pengguna memilihnya. Bila Anda telah mengatur status, aktivitas akan menjaga status diberi tanda cek +suatu item sehingga bila nanti pengguna membuka menu, status diberi tanda cek yang Anda +atur akan terlihat.</p> + +<p class="note"><strong>Catatan:</strong> +Item menu yang bisa diberi tanda cek dimaksudkan untuk digunakan hanya atas dasar per sesi dan tidak disimpan setelah +aplikasi dimusnahkan. Jika Anda memiliki pengaturan aplikasi yang ingin disimpan untuk pengguna, +Anda harus menyimpan data dengan menggunakan <a href="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>.</p> + + + +<h2 id="intents">Menambahkan Item Menu Berdasarkan Intent</h2> + +<p>Kadang-kadang Anda ingin supaya item menu menjalankan aktivitas dengan menggunakan {@link android.content.Intent} +(baik aktivitas berada dalam aplikasi Anda maupun di aplikasi lain). Bila Anda mengetahui intent +yang ingin digunakan dan memiliki item menu tertentu yang harus memulai intent, Anda bisa mengeksekusi +intent dengan {@link android.app.Activity#startActivity(Intent) startActivity()} selama +metode callback bila-item-dipilih yang sesuai (seperti callback {@link +android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}).</p> + +<p>Akan tetapi, jika Anda tidak yakin apakah perangkat pengguna +berisi aplikasi yang menangani intent, maka menambahkan item menu yang memanggilnya bisa mengakibatkan +item menu tidak berfungsi, karena intent tidak bisa diterjemahkan menjadi +aktivitas. Untuk mengatasi hal ini, Android memungkinkan Anda menambahkan item menu secara dinamis ke menu +bila Android menemukan aktivitas pada perangkat yang menangani intent Anda.</p> + +<p>Untuk menambahkan item menu berdasarkan aktivitas tersedia yang menerima intent:</p> +<ol> + <li>Definisikan +intent dengan kategori {@link android.content.Intent#CATEGORY_ALTERNATIVE} dan/atau +{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, plus kebutuhan lainnya.</li> + <li>Panggil {@link +android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) +Menu.addIntentOptions()}. Android kemudian akan mencari setiap aplikasi yang bisa melakukan intent +dan menambahkannya ke menu Anda.</li> +</ol> + +<p>Jika tidak ada aplikasi terinstal +yang memenuhi intent, maka tidak ada item menu yang ditambahkan.</p> + +<p class="note"><strong>Catatan:</strong> +{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} digunakan untuk menangani +elemen yang saat ini dipilih pada layar. Jadi, metode hanya digunakan saat membuat Menu dalam {@link +android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) +onCreateContextMenu()}.</p> + +<p>Misalnya:</p> + +<pre> +@Override +public boolean onCreateOptionsMenu(Menu menu){ + super.onCreateOptionsMenu(menu); + + // Create an Intent that describes the requirements to fulfill, to be included + // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE. + Intent intent = new Intent(null, dataUri); + intent.addCategory(Intent.CATEGORY_ALTERNATIVE); + + // Search and populate the menu with acceptable offering applications. + menu.addIntentOptions( + R.id.intent_group, // Menu group to which new items will be added + 0, // Unique item ID (none) + 0, // Order for the items (none) + this.getComponentName(), // The current activity name + null, // Specific items to place first (none) + intent, // Intent created above that describes our requirements + 0, // Additional flags to control items (none) + null); // Array of MenuItems that correlate to specific items (none) + + return true; +}</pre> + +<p>Untuk setiap aktivitas yang diketahui menyediakan filter intent yang cocok dengan intent yang didefinisikan, item menu +akan ditambahkan, menggunakan nilai dalam filter intent <code>android:label</code> sebagai +judul item menu dan ikon aplikasi sebagai ikon item menu. Metode +{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) +addIntentOptions()} mengembalikan jumlah item menu yang ditambahkan.</p> + +<p class="note"><strong>Catatan:</strong> Bila Anda memanggil {@link +android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) +addIntentOptions()}, metode ini akan mengesampingkan setiap dan semua item menu menurut grup menu yang ditetapkan dalam argumen +pertama.</p> + + +<h3 id="AllowingToAdd">Memungkinkan aktivitas Anda ditambahkan ke menu lain</h3> + +<p>Anda juga bisa menawarkan layanan aktivitas Anda pada aplikasi lainnya, sehingga +aplikasi Anda bisa disertakan dalam menu aplikasi lain (membalik peran yang dijelaskan di atas).</p> + +<p>Agar bisa dimasukkan dalam menu aplikasi lain, Anda perlu mendefinisikan +filter intent seperti biasa, tetapi pastikan menyertakan nilai-nilai {@link android.content.Intent#CATEGORY_ALTERNATIVE} +dan/atau {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} untuk +kategori filter intent. Misalnya:</p> +<pre> +<intent-filter label="@string/resize_image"> + ... + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + ... +</intent-filter> +</pre> + +<p>Baca selengkapnya tentang penulisan filter intent dalam dokumen +<a href="/guide/components/intents-filters.html">Intent dan Filter Intent</a>.</p> + +<p>Untuk contoh aplikasi yang menggunakan teknik ini, lihat contoh kode +<a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Note +Pad</a>.</p> diff --git a/docs/html-intl/intl/in/guide/topics/ui/notifiers/notifications.jd b/docs/html-intl/intl/in/guide/topics/ui/notifiers/notifications.jd new file mode 100644 index 000000000000..9033b9f744f3 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/notifiers/notifications.jd @@ -0,0 +1,979 @@ +page.title=Pemberitahuan +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#Design">Pertimbangan Desain</a></li> + <li><a href="#CreateNotification">Membuat Pemberitahuan</a> + <ol> + <li><a href="#Required">Isi pemberitahuan yang diperlukan</a></li> + <li><a href="#Optional">Isi dan pengaturan pemberitahuan opsional</a></li> + <li><a href="#Actions">Tindakan pemberitahuan</a></li> + <li><a href="#Priority">Prioritas pemberitahuan</a></li> + <li><a href="#SimpleNotification">Membuat pemberitahuan sederhana</a></li> + <li><a href="#ApplyStyle">Menerapkan layout yang diperluas pada pemberitahuan</a></li> + <li><a href="#Compatibility">Menangani kompatibilitas</a></li> + </ol> + </li> + <li><a href="#Managing">Mengelola Pemberitahuan</a> + <ol> + <li><a href="#Updating">Memperbarui pemberitahuan</a></li> + <li><a href="#Removing">Menghapus pemberitahuan</a></li> + </ol> + </li> + <li><a href="#NotificationResponse">Mempertahankan Navigasi saat Memulai Aktivitas</a> + <ol> + <li><a href="#DirectEntry">Menyiapkan PendingIntent aktivitas biasa</a></li> + <li><a href="#ExtendedNotification">Menyiapkan PendingIntent aktivitas khusus</a></li> + </ol> + </li> + <li><a href="#Progress">Menampilkan Kemajuan dalam Pemberitahuan</a> + <ol> + <li><a href="#FixedProgress">Menampilkan indikator kemajuan berdurasi tetap</a></li> + <li><a href="#ActivityIndicator">Menampilkan indikator aktivitas berlanjut</a></li> + </ol> + </li> + <li><a href="#metadata">Metadata Pemberitahuan</a></li> + <li><a href="#Heads-up">Pemberitahuan Pendahuluan</a></li> + <li><a href="#lockscreenNotification">Pemberitahuan Layar Kunci</a></li> + <ol> + <li><a href="#visibility">Mengatur Visibilitas</a></li> + <li><a href="#controllingMedia">Mengontrol Pemutaran Media pada Layar Kunci</a></li> + </ol> + <li><a href="#CustomNotification">Layout Pemberitahuan Custom</a></li> +</ol> + + <h2>Kelas-kelas utama</h2> + <ol> + <li>{@link android.app.NotificationManager}</li> + <li>{@link android.support.v4.app.NotificationCompat}</li> + </ol> + <h2>Video</h2> + <ol> + <li> + <a href="http://www.youtube.com/watch?v=Yc8YrVc47TI&feature=player_detailpage#t=1672s"> + Pemberitahuan di 4.1</a> + </li> + </ol> +<h2>Lihat juga</h2> +<ol> + <li> + <a href="{@docRoot}design/patterns/notifications.html">Desain Android: Pemberitahuan</a> + </li> +</ol> +</div> +</div> +<p> + Pemberitahuan adalah pesan yang bisa Anda tampilkan kepada pengguna di luar + UI normal aplikasi. Bila Anda memberi tahu sistem untuk mengeluarkan pemberitahuan, pemberitahuan akan muncul lebih dahulu sebagai ikon dalam + <strong>area pemberitahuan</strong>. Untuk melihat detail pemberitahuan, pengguna membuka + <strong>laci pemberitahuan</strong>. Baik area pemberitahuan maupun laci pemberitahuan + adalah area-area yang dikontrol sistem yang bisa dilihat pengguna kapan saja. +</p> +<img id="figure1" src="{@docRoot}images/ui/notifications/notification_area.png" height="" alt="" /> +<p class="img-caption"> + <strong>Gambar 1.</strong> Pemberitahuan di area pemberitahuan. +</p> +<img id="figure2" src="{@docRoot}images/ui/notifications/notification_drawer.png" width="280px" alt="" /> +<p class="img-caption"> + <strong>Gambar 2.</strong> Pemberitahuan di laci pemberitahuan. +</p> + +<p class="note"><strong>Catatan:</strong> Kecuali disebutkan, panduan ini mengacu pada +kelas {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} +dalam <a href="{@docRoot}tools/support-library/index.html">Support Library</a> versi 4. +Kelas {@link android.app.Notification.Builder Notification.Builder} telah ditambahkan pada Android +3.0 (API level 11).</p> + +<h2 id="Design">Pertimbangan Desain</h2> + +<p>Pemberitahuan, sebagai bagian penting dari antarmuka pengguna Android, memiliki panduan desainnya sendiri. +Perubahan desain materi yang diperkenalkan dalam Android 5.0 (API level 21) adalah sangat +penting, dan Anda harus meninjau pelatihan <a href="{@docRoot}training/material/index.html">Desain Bahan</a> +untuk informasi selengkapnya. Untuk mengetahui cara mendesain pemberitahuan dan interaksinya, bacalah panduan desain +<a href="{@docRoot}design/patterns/notifications.html">Pemberitahuan</a>.</p> + +<h2 id="CreateNotification">Membuat Pemberitahuan</h2> + +<p>Anda menetapkan informasi dan tindakan UI bagi pemberitahuan dalam +objek {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder}. +Untuk membuat pemberitahuan itu sendiri, panggil +{@link android.support.v4.app.NotificationCompat.Builder#build NotificationCompat.Builder.build()}, +yang akan mengembalikan objek {@link android.app.Notification} berisi spesifikasi Anda. Untuk mengeluarkan +pemberitahuan, Anda meneruskan objek {@link android.app.Notification} ke sistem dengan memanggil +{@link android.app.NotificationManager#notify NotificationManager.notify()}.</p> + +<h3 id="Required">Isi pemberitahuan yang diperlukan</h3> +<p> + Objek {@link android.app.Notification} <em>harus</em> berisi yang berikut ini: +</p> +<ul> + <li> + Ikon kecil, yang diatur dengan + {@link android.support.v4.app.NotificationCompat.Builder#setSmallIcon setSmallIcon()} + </li> + <li> + Judul, yang diatur dengan + {@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()} + </li> + <li> + Teks detail, yang diatur dengan + {@link android.support.v4.app.NotificationCompat.Builder#setContentText setContentText()} + </li> +</ul> +<h3 id="Optional">Isi dan pengaturan pemberitahuan opsional</h3> +<p> + Semua isi dan pengaturan pemberitahuan lainnya bersifat opsional. Untuk mengetahui selengkapnya tentang semua itu, + lihat dokumentasi acuan untuk {@link android.support.v4.app.NotificationCompat.Builder}. +</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="Actions">Tindakan pemberitahuan</h3> +<p> + Walaupun bersifat opsional, Anda harus menambahkan setidaknya satu tindakan pada pemberitahuan. + Tindakan memungkinkan pengguna beralih langsung dari pemberitahuan ke + {@link android.app.Activity} dalam aplikasi Anda, tempat pengguna bisa melihat satu atau beberapa kejadian + atau melakukan pekerjaan lebih jauh. +</p> +<p> + Pemberitahuan bisa menyediakan beberapa tindakan sekaligus. Anda harus selalu mendefinisikan tindakan yang + akan diaktifkan bila pengguna mengklik pemberitahuan; biasanya tindakan ini akan membuka + {@link android.app.Activity} dalam aplikasi Anda. Anda juga bisa menambahkan tombol pada pemberitahuan + yang melakukan tindakan tambahan seperti mendiamkan alarm atau segera merespons + pesan teks; fitur ini tersedia mulai Android 4.1. Jika menggunakan tombol tindakan tambahan, Anda + juga harus membuat fungsionalitasnya tersedia dalam {@link android.app.Activity} di aplikasi Anda; lihat + bagian <a href="#Compatibility">Menangani kompatibilitas</a> untuk detail selengkapnya. +</p> +<p> + Dalam {@link android.app.Notification}, tindakan itu sendiri didefinisikan oleh + {@link android.app.PendingIntent} berisi + {@link android.content.Intent} yang memulai + {@link android.app.Activity} dalam aplikasi Anda. Untuk mengaitkan + {@link android.app.PendingIntent} dengan gestur, panggil metode + {@link android.support.v4.app.NotificationCompat.Builder} yang sesuai. Misalnya, jika ingin memulai + {@link android.app.Activity} bila pengguna mengklik teks pemberitahuan pada + laci pemberitahuan, tambahkan {@link android.app.PendingIntent} dengan memanggil + {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}. +</p> +<p> + Memulai {@link android.app.Activity} bila pengguna mengklik pemberitahuan adalah + skenario tindakan yang paling umum. Anda juga bisa memulai {@link android.app.Activity} bila pengguna + menghilangkan pemberitahuan. Dalam Android 4.1 dan yang lebih baru, Anda bisa memulai + {@link android.app.Activity} dari tombol tindakan. Untuk mengetahui selengkapnya, bacalah panduan acuan untuk + {@link android.support.v4.app.NotificationCompat.Builder}. +</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="Priority">Prioritas pemberitahuan</h3> +<p> + Jika diinginkan, Anda bisa mengatur prioritas pemberitahuan. Prioritas berfungsi + sebagai petunjuk bagi UI perangkat tentang cara menampilkan pemberitahuan. + Untuk mengatur prioritas pemberitahuan, panggil {@link + android.support.v4.app.NotificationCompat.Builder#setPriority(int) + NotificationCompat.Builder.setPriority()} dan teruskan salah satu konstanta prioritas {@link + android.support.v4.app.NotificationCompat}. Ada + lima level prioritas, mulai dari {@link + android.support.v4.app.NotificationCompat#PRIORITY_MIN} (-2) hingga {@link + android.support.v4.app.NotificationCompat#PRIORITY_MAX} (2); jika tidak diatur, + prioritas default akan ditetapkan {@link + android.support.v4.app.NotificationCompat#PRIORITY_DEFAULT} (0). +</p> +<p> Untuk informasi tentang mengatur level prioritas, lihat "Mengatur + dan mengelola prioritas pemberitahuan dengan benar" dalam panduan +Desain <a href="{@docRoot}design/patterns/notifications.html">Pemberitahuan</a>. +</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="SimpleNotification">Membuat pemberitahuan sederhana</h3> +<p> + Cuplikan berikut mengilustrasikan pemberitahuan sederhana yang menetapkan aktivitas untuk dibuka bila + pengguna mengklik pemberitahuan. Perhatikan bahwa kode ini membuat + objek {@link android.support.v4.app.TaskStackBuilder} dan menggunakannya untuk membuat + {@link android.app.PendingIntent} untuk tindakan. Pola ini dijelaskan secara lebih detail + di bagian <a href="#NotificationResponse"> + Mempertahankan Navigasi saat Memulai Aktivitas</a>: +</p> +<pre> +NotificationCompat.Builder mBuilder = + new NotificationCompat.Builder(this) + .setSmallIcon(R.drawable.notification_icon) + .setContentTitle("My notification") + .setContentText("Hello World!"); +// Creates an explicit intent for an Activity in your app +Intent resultIntent = new Intent(this, ResultActivity.class); + +// The stack builder object will contain an artificial back stack for the +// started Activity. +// This ensures that navigating backward from the Activity leads out of +// your application to the Home screen. +TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); +// Adds the back stack for the Intent (but not the Intent itself) +stackBuilder.addParentStack(ResultActivity.class); +// Adds the Intent that starts the Activity to the top of the stack +stackBuilder.addNextIntent(resultIntent); +PendingIntent resultPendingIntent = + stackBuilder.getPendingIntent( + 0, + PendingIntent.FLAG_UPDATE_CURRENT + ); +mBuilder.setContentIntent(resultPendingIntent); +NotificationManager mNotificationManager = + (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); +// mId allows you to update the notification later on. +mNotificationManager.notify(mId, mBuilder.build()); +</pre> +<p>Demikian saja. Pengguna Anda kini telah diberi tahu.</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="ApplyStyle">Menerapkan layout yang diperluas pada pemberitahuan</h3> +<p> + Agar pemberitahuan muncul dalam tampilan yang diperluas, buat dahulu + objek {@link android.support.v4.app.NotificationCompat.Builder} dengan opsi tampilan normal + yang Anda inginkan. Berikutnya, panggil {@link android.support.v4.app.NotificationCompat.Builder#setStyle + Builder.setStyle()} dengan objek layout yang diperluas sebagai argumennya. +</p> +<p> + Ingatlah bahwa pemberitahuan yang diperluas tidak tersedia pada platform-platform sebelum Android 4.1. Untuk + mengetahui cara menangani pemberitahuan untuk Android 4.1 dan untuk platform-platform sebelumnya, bacalah + bagian <a href="#Compatibility">Menangani kompatibilitas</a>. +</p> +<p> + Misalnya, cuplikan kode berikut memperagakan cara mengubah pemberitahuan yang dibuat + dalam cuplikan sebelumnya untuk menggunakan layout yang diperluas: +</p> +<pre> +NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this) + .setSmallIcon(R.drawable.notification_icon) + .setContentTitle("Event tracker") + .setContentText("Events received") +NotificationCompat.InboxStyle inboxStyle = + new NotificationCompat.InboxStyle(); +String[] events = new String[6]; +// Sets a title for the Inbox in expanded layout +inboxStyle.setBigContentTitle("Event tracker details:"); +... +// Moves events into the expanded layout +for (int i=0; i < events.length; i++) { + + inboxStyle.addLine(events[i]); +} +// Moves the expanded layout object into the notification object. +mBuilder.setStyle(inBoxStyle); +... +// Issue the notification here. +</pre> + +<h3 id="Compatibility">Menangani kompatibilitas</h3> + +<p> + Tidak semua fitur pemberitahuan tersedia untuk versi tertentu, walaupun + metode untuk mengaturnya ada dalam kelas pustaka dukungan + {@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder}. + Misalnya, tombol tindakan, yang bergantung pada pemberitahuan yang diperluas, hanya muncul pada Android + 4.1 dan lebih tinggi, karena pemberitahuan yang diperluas itu sendiri hanya tersedia pada + Android 4.1 dan yang lebih tinggi. +</p> +<p> + Untuk memastikan kompatibilitas terbaik, buatlah pemberitahuan dengan + {@link android.support.v4.app.NotificationCompat NotificationCompat} dan subkelasnya, + khususnya {@link android.support.v4.app.NotificationCompat.Builder + NotificationCompat.Builder}. Selain itu, ikutilah proses ini bila Anda mengimplementasikan pemberitahuan: +</p> +<ol> + <li> + Sediakan semua fungsionalitas pemberitahuan kepada semua pengguna, terlepas dari versi + yang mereka gunakan. Caranya, pastikan semua fungsionalitas tersedia dari + {@link android.app.Activity} dalam aplikasi Anda. Anda mungkin perlu menambahkan sebuah + {@link android.app.Activity} baru untuk melakukannya. + <p> + Misalnya, jika Anda ingin menggunakan + {@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()} untuk + menyediakan kontrol yang menghentikan dan memulai pemutaran media, implementasikan dahulu + kontrol ini pada {@link android.app.Activity} dalam aplikasi Anda. + </p> + </li> + <li> + Pastikan semua pengguna bisa memperoleh fungsionalitas dalam {@link android.app.Activity}, + dengan memulainya bila pengguna mengklik pemberitahuan. Caranya, + buatlah {@link android.app.PendingIntent} + untuk {@link android.app.Activity}. Panggil + {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent + setContentIntent()} untuk menambahkan {@link android.app.PendingIntent} pada pemberitahuan. + </li> + <li> + Kini tambahkan fitur pemberitahuan diperluas yang ingin Anda gunakan pada pemberitahuan. Ingatlah + bahwa setiap fungsionalitas yang Anda tambahkan juga harus tersedia dalam {@link android.app.Activity} + yang akan dimulai bila pengguna mengklik pemberitahuan. + </li> +</ol> + + +<!-- ------------------------------------------------------------------------------------------ --> +<!-- ------------------------------------------------------------------------------------------ --> +<h2 id="Managing">Mengelola Pemberitahuan</h2> +<p> + Bila perlu mengeluarkan pemberitahuan beberapa kali untuk tipe kejadian yang sama, +hindari membuat pemberitahuan yang sama sekali baru. Sebagai gantinya, Anda harus mempertimbangkan untuk memperbarui + pemberitahuan sebelumnya, baik dengan mengubah sebagian nilainya atau dengan menambahkan nilai, atau keduanya. +</p> +<p> + Misalnya, Gmail akan memberi tahu pengguna bila ada email baru dengan menambah hitungan + pesan tidak terbaca dan dengan menambahkan rangkuman tiap email ke pemberitahuan. Ini disebut dengan + "stacking" (menumpuk) pemberitahuan; hal ini dijelaskan lebih detail dalam panduan + Desain <a href="{@docRoot}design/patterns/notifications.html">Pemberitahuan</a>. +</p> +<p class="note"> + <strong>Catatan:</strong> Fitur Gmail ini mensyaratkan layout "kotak masuk" diperluas, yang merupakan + bagian dari fitur pemberitahuan diperluas yang tersedia mulai Android 4.1. +</p> +<p> + Bagian berikut menjelaskan cara memperbarui pemberitahuan dan cara menghapusnya. +</p> +<h3 id="Updating">Memperbarui pemberitahuan</h3> +<p> + Untuk menyiapkan pemberitahuan agar bisa diperbarui, keluarkan pemberitahuan bersama ID pemberitahuan dengan + memanggil {@link android.app.NotificationManager#notify(int, android.app.Notification) NotificationManager.notify()}. + Untuk memperbarui pemberitahuan ini setelah Anda + mengeluarkan, memperbarui, atau membuat objek {@link android.support.v4.app.NotificationCompat.Builder}, + buat objek {@link android.app.Notification} darinya, dan keluarkan + {@link android.app.Notification} bersama ID yang sama dengan yang Anda gunakan sebelumnya. Jika + pemberitahuan sebelumnya tetap terlihat, sistem akan memperbaruinya dari konten + objek {@link android.app.Notification}. Jika pemberitahuan sebelumnya telah dihilangkan, sebuah + pemberitahuan baru akan dibuat. +</p> +<p> + Cuplikan berikut memperagakan pemberitahuan yang diperbarui untuk mencerminkan + jumlah kejadian yang telah terjadi. Cuplikan ini menumpuk pemberitahuan, yang menampilkan rangkuman: +</p> +<pre> +mNotificationManager = + (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); +// Sets an ID for the notification, so it can be updated +int notifyID = 1; +mNotifyBuilder = new NotificationCompat.Builder(this) + .setContentTitle("New Message") + .setContentText("You've received new messages.") + .setSmallIcon(R.drawable.ic_notify_status) +numMessages = 0; +// Start of a loop that processes data and then notifies the user +... + mNotifyBuilder.setContentText(currentText) + .setNumber(++numMessages); + // Because the ID remains unchanged, the existing notification is + // updated. + mNotificationManager.notify( + notifyID, + mNotifyBuilder.build()); +... +</pre> + +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="Removing">Menghapus pemberitahuan</h3> +<p> + Pemberitahuan tetap terlihat hingga salah satu kejadian berikut terjadi: +</p> +<ul> + <li> + Pengguna menghilangkan pemberitahuan satu per satu atau dengan menggunakan "Clear All" (jika + pemberitahuan bisa dihapus). + </li> + <li> + Pengguna mengklik pemberitahuan, dan Anda memanggil + {@link android.support.v4.app.NotificationCompat.Builder#setAutoCancel setAutoCancel()} bila + Anda telah membuat pemberitahuan. + </li> + <li> + Anda memanggil {@link android.app.NotificationManager#cancel(int) cancel()} untuk + ID pemberitahuan tertentu. Metode ini juga menghapus pemberitahuan yang berjalan. + </li> + <li> + Anda memanggil {@link android.app.NotificationManager#cancelAll() cancelAll()}, yang menghapus + semua pemberitahuan yang dikeluarkan sebelumnya. + </li> +</ul> +<!-- ------------------------------------------------------------------------------------------ --> +<!-- ------------------------------------------------------------------------------------------ --> +<h2 id="NotificationResponse">Mempertahankan Navigasi saat Memulai Aktivitas</h2> +<p> + Bila memulai {@link android.app.Activity} dari pemberitahuan, Anda harus mempertahankan + pengalaman navigasi yang diharapkan pengguna. Mengklik <i>Back</i> harus membawa pengguna kembali melalui + aliran pekerjaan normal aplikasi ke layar Home, dan mengklik <i>Recents</i> harus menampilkan + {@link android.app.Activity} sebagai tugas terpisah. Untuk mempertahankan pengalaman navigasi, Anda + harus memulai {@link android.app.Activity} dalam tugas baru. Cara menyiapkan + {@link android.app.PendingIntent} untuk memberi Anda tugas baru bergantung pada sifat + {@link android.app.Activity} yang Anda mulai. Ada dua situasi umum: +</p> +<dl> + <dt> + Aktivitas rutin + </dt> + <dd> + Anda memulai {@link android.app.Activity} yang merupakan bagian dari aliran pekerjaan normal + aplikasi. Dalam situasi ini, siapkan {@link android.app.PendingIntent} untuk + memulai tugas baru, dan sediakan {@link android.app.PendingIntent} bersama back-stack + yang meniru perilaku <i>Back</i> biasa. + <p> + Pemberitahuan dari aplikasi Gmail memperagakan hal ini. Bila Anda mengklik pemberitahuan untuk + satu pesan email, Anda akan melihat pesan itu sendiri. Menyentuh <b>Back</b> akan membawa Anda + kembali melalui Gmail ke layar Home, persis seperti jika memasuki Gmail dari + layar Home bukannya memasukinya dari pemberitahuan. + </p> + <p> + Hal ini terjadi terlepas dari aplikasi tempat Anda berada saat menyentuh + pemberitahuan. Misalnya, jika Anda dalam Gmail sedang menulis pesan, dan Anda mengklik + pemberitahuan untuk satu email, Anda akan segera dibawa ke email itu. Menyentuh <i>Back</i> + akan membawa Anda ke kotak masuk kemudian layar Home, bukannya membawa Anda ke + pesan yang sedang ditulis. + </p> + </dd> + <dt> + Aktivitas khusus + </dt> + <dd> + Pengguna hanya melihat {@link android.app.Activity} ini jika dimulai dari pemberitahuan. + Dalam beberapa hal, {@link android.app.Activity} akan memperluas pemberitahuan dengan menyediakan + informasi yang akan sulit untuk ditampilkan dalam pemberitahuan itu sendiri. Untuk situasi ini, + siapkan {@link android.app.PendingIntent} untuk dimulai dalam tugas baru. Tidak perlu + membuat back-stack, karena {@link android.app.Activity} yang dimulai bukan bagian dari + aliran aktivitas aplikasi. Mengklik <i>Back</i> tetap akan membawa pengguna ke + layar Home. + </dd> +</dl> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="DirectEntry">Menyiapkan PendingIntent aktivitas biasa</h3> +<p> + Untuk menyiapkan {@link android.app.PendingIntent} yang memulai entri langsung + {@link android.app.Activity}, ikuti langkah-langkah ini: +</p> +<ol> + <li> + Definisikan hierarki {@link android.app.Activity} aplikasi Anda dalam manifes. + <ol style="list-style-type: lower-alpha;"> + <li> + Tambahkan dukungan untuk Android 4.0.3 dan yang terdahulu. Caranya, tetapkan induk + {@link android.app.Activity} yang Anda mulai dengan menambahkan elemen +<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> + sebagai anak +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>. + <p> + Untuk elemen ini, atur +<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#nm">android:name</a>="android.support.PARENT_ACTIVITY"</code>. + Atur +<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#val">android:value</a>="<parent_activity_name>"</code> + dengan <code><parent_activity_name></code> sebagai nilai +<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#nm">android:name</a></code> + untuk elemen induk +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +. Lihat XML berikut sebagai contoh. + </p> + </li> + <li> + Juga tambahkan dukungan untuk Android 4.1 dan yang lebih baru. Caranya, tambahkan atribut +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">android:parentActivityName</a></code> + pada elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + dari {@link android.app.Activity} yang Anda mulai. + </li> + </ol> + <p> + XML akhir akan terlihat seperti ini: + </p> +<pre> +<activity + android:name=".MainActivity" + android:label="@string/app_name" > + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> +</activity> +<activity + android:name=".ResultActivity" + android:parentActivityName=".MainActivity"> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value=".MainActivity"/> +</activity> +</pre> + </li> + <li> + Buat back-stack berdasarkan {@link android.content.Intent} yang memulai + {@link android.app.Activity}: + <ol style="list-style-type: lower-alpha;"> + <li> + Buat {@link android.content.Intent} untuk memulai {@link android.app.Activity}. + </li> + <li> + Buat stack-builder (pembangun tumpukan) dengan memanggil {@link android.app.TaskStackBuilder#create + TaskStackBuilder.create()}. + </li> + <li> + Tambahkan back-stack ke stack-builder dengan memanggil + {@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()}. + Untuk setiap {@link android.app.Activity} dalam hierarki yang telah Anda definisikan dalam + manifes, back-stack berisi objek {@link android.content.Intent} yang + memulai {@link android.app.Activity}. Metode ini juga menambahkan flag yang memulai + back-stack dalam tugas baru. + <p class="note"> + <strong>Catatan:</strong> Walaupun argumen untuk + {@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()} + adalah acuan ke {@link android.app.Activity} yang dimulai, panggilan metode + tidak akan menambahkan {@link android.content.Intent} yang memulai + {@link android.app.Activity}. Sebagai gantinya, hal itu ditangani dalam langkah berikutnya. + </p> + </li> + <li> + Tambahkan {@link android.content.Intent} yang memulai {@link android.app.Activity} + dari pemberitahuan, dengan memanggil + {@link android.support.v4.app.TaskStackBuilder#addNextIntent addNextIntent()}. + Teruskan {@link android.content.Intent} yang Anda buat dalam langkah pertama sebagai + argumen ke + {@link android.support.v4.app.TaskStackBuilder#addNextIntent addNextIntent()}. + </li> + <li> + Jika perlu, tambahkan argumen ke objek {@link android.content.Intent} pada + back-stack dengan memanggil {@link android.support.v4.app.TaskStackBuilder#editIntentAt + TaskStackBuilder.editIntentAt()}. Kadang-kadang perlu memastikan apakah + {@link android.app.Activity} target menampilkan data bermakna saat pengguna menelusurinya + dengan menggunakan <i>Back</i>. + </li> + <li> + Dapatkan {@link android.app.PendingIntent} untuk back-stack ini dengan memanggil + {@link android.support.v4.app.TaskStackBuilder#getPendingIntent getPendingIntent()}. + Anda nanti bisa menggunakan {@link android.app.PendingIntent} ini sebagai argumen untuk + {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent + setContentIntent()}. + </li> + </ol> + </li> +</ol> +<p> + Cuplikan kode berikut memperagakan prosesnya: +</p> +<pre> +... +Intent resultIntent = new Intent(this, ResultActivity.class); +TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); +// Adds the back stack +stackBuilder.addParentStack(ResultActivity.class); +// Adds the Intent to the top of the stack +stackBuilder.addNextIntent(resultIntent); +// Gets a PendingIntent containing the entire back stack +PendingIntent resultPendingIntent = + stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT); +... +NotificationCompat.Builder builder = new NotificationCompat.Builder(this); +builder.setContentIntent(resultPendingIntent); +NotificationManager mNotificationManager = + (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); +mNotificationManager.notify(id, builder.build()); +</pre> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="ExtendedNotification">Menyiapkan PendingIntent aktivitas khusus</h3> +<p> + Bagian berikut menjelaskan cara menyiapkan aktivitas khusus + {@link android.app.PendingIntent}. +</p> +<p> + {@link android.app.Activity} khusus tidak memerlukan back-stack, sehingga Anda tidak perlu + mendefinisikan hierarki {@link android.app.Activity}-nya dalam manifes, dan Anda tidak perlu + memanggil + {@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()} untuk membuat + back-stack. Sebagai gantinya, gunakan manifes untuk menyiapkan opsi tugas {@link android.app.Activity}, + dan buat {@link android.app.PendingIntent} dengan memanggil + {@link android.app.PendingIntent#getActivity getActivity()}: +</p> +<ol> + <li> + Dalam manifes, tambahkan atribut berikut pada elemen +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + untuk {@link android.app.Activity} + <dl> + <dt> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">android:name</a>="<i>activityclass</i>"</code> + </dt> + <dd> + Nama kelas mutlak (fully qualified) aktivitas. + </dd> + <dt> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">android:taskAffinity</a>=""</code> + </dt> + <dd> + Dikombinasikan dengan flag + {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK} + yang Anda atur dalam kode, ini memastikan bahwa {@link android.app.Activity} ini tidak + masuk ke dalam tugas default aplikasi. Setiap tugas yang ada yang memiliki + afinitas default aplikasi tidak terpengaruh. + </dd> + <dt> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude">android:excludeFromRecents</a>="true"</code> + </dt> + <dd> + Mengecualikan tugas baru dari <i>Recents</i>, sehingga pengguna tidak bisa tanpa sengaja + mengarahkan kembali. + </dd> + </dl> + <p> + Cuplikan ini menampilkan elemen: + </p> +<pre> +<activity + android:name=".ResultActivity" +... + android:launchMode="singleTask" + android:taskAffinity="" + android:excludeFromRecents="true"> +</activity> +... +</pre> + </li> + <li> + Buat dan keluarkan pemberitahuan: + <ol style="list-style-type: lower-alpha;"> + <li> + Buat {@link android.content.Intent} yang memulai + {@link android.app.Activity}. + </li> + <li> + Atur {@link android.app.Activity} untuk dimulai dalam tugas kosong yang baru dengan memanggil + {@link android.content.Intent#setFlags setFlags()} dengan flag + {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK} + dan + {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK FLAG_ACTIVITY_CLEAR_TASK}. + </li> + <li> + Atur setiap opsi lain yang Anda perlukan untuk {@link android.content.Intent}. + </li> + <li> + Buat {@link android.app.PendingIntent} dari {@link android.content.Intent} + dengan memanggil {@link android.app.PendingIntent#getActivity getActivity()}. + Anda nanti bisa menggunakan {@link android.app.PendingIntent} ini sebagai argumen untuk + {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent + setContentIntent()}. + </li> + </ol> + <p> + Cuplikan kode berikut memperagakan prosesnya: + </p> +<pre> +// Instantiate a Builder object. +NotificationCompat.Builder builder = new NotificationCompat.Builder(this); +// Creates an Intent for the Activity +Intent notifyIntent = + new Intent(this, ResultActivity.class); +// Sets the Activity to start in a new, empty task +notifyIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK + | Intent.FLAG_ACTIVITY_CLEAR_TASK); +// Creates the PendingIntent +PendingIntent notifyPendingIntent = + PendingIntent.getActivity( + this, + 0, + notifyIntent, + PendingIntent.FLAG_UPDATE_CURRENT +); + +// Puts the PendingIntent into the notification builder +builder.setContentIntent(notifyPendingIntent); +// Notifications are issued by sending them to the +// NotificationManager system service. +NotificationManager mNotificationManager = + (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); +// Builds an anonymous Notification object from the builder, and +// passes it to the NotificationManager +mNotificationManager.notify(id, builder.build()); +</pre> + </li> +</ol> +<!-- ------------------------------------------------------------------------------------------ --> +<!-- ------------------------------------------------------------------------------------------ --> +<h2 id="Progress">Menampilkan Kemajuan dalam Pemberitahuan</h2> +<p> + Pemberitahuan bisa menyertakan indikator kemajuan beranimasi yang menampilkan status +operasi yang berjalan kepada pengguna. Jika Anda bisa memperkirakan lamanya operasi berlangsung dan berapa banyak + yang sudah selesai pada suatu waktu, gunakan bentuk indikator yang "pasti" + (baris kemajuan). Jika Anda tidak bisa memperkirakan lamanya operasi, gunakan + bentuk indikator "tidak pasti" (indikator aktivitas). +</p> +<p> + Indikator kemajuan ditampilkan bersama implementasi platform + kelas {@link android.widget.ProgressBar}. +</p> +<p> + Untuk menggunakan indikator kemajuan pada platform mulai dari Android 4.0, panggil + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. Untuk + versi sebelumnya, Anda harus membuat layout pemberitahuan custom sendiri yang +menyertakan tampilan {@link android.widget.ProgressBar}. +</p> +<p> + Bagian berikut ini menjelaskan cara menampilkan kemajuan dalam pemberitahuan dengan menggunakan + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. +</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="FixedProgress">Menampilkan indikator kemajuan berdurasi tetap</h3> +<p> + Untuk menampilkan baris kemajuan pasti, tambahkan baris itu ke pemberitahuan dengan memanggil + {@link android.support.v4.app.NotificationCompat.Builder#setProgress + setProgress(max, progress, false)}, kemudian keluarkan pemberitahuan. Selagi operasi berlangsung, + tambah <code>progress</code>, dan perbarui pemberitahuan. Di akhir operasi, + <code>progress</code> harus sama dengan <code>max</code>. Satu cara umum memanggil + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()} + adalah mengatur <code>max</code> ke 100, kemudian tambah <code>progress</code> sebagai + nilai "persen selesai"untuk operasi itu. +</p> +<p> + Anda bisa membiarkan baris kemajuan ditampilkan saat operasi selesai, atau menghilangkannya. Dalam + hal apa pun, ingatlah memperbarui teks pemberitahuan untuk menampilkan bahwa operasi telah selesai. + Untuk menghapus baris kemajuan, panggil + {@link android.support.v4.app.NotificationCompat.Builder#setProgress + setProgress(0, 0, false)}. Misalnya: +</p> +<pre> +... +mNotifyManager = + (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); +mBuilder = new NotificationCompat.Builder(this); +mBuilder.setContentTitle("Picture Download") + .setContentText("Download in progress") + .setSmallIcon(R.drawable.ic_notification); +// Start a lengthy operation in a background thread +new Thread( + new Runnable() { + @Override + public void run() { + int incr; + // Do the "lengthy" operation 20 times + for (incr = 0; incr <= 100; incr+=5) { + // Sets the progress indicator to a max value, the + // current completion percentage, and "determinate" + // state + mBuilder.setProgress(100, incr, false); + // Displays the progress bar for the first time. + mNotifyManager.notify(0, mBuilder.build()); + // Sleeps the thread, simulating an operation + // that takes time + try { + // Sleep for 5 seconds + Thread.sleep(5*1000); + } catch (InterruptedException e) { + Log.d(TAG, "sleep failure"); + } + } + // When the loop is finished, updates the notification + mBuilder.setContentText("Download complete") + // Removes the progress bar + .setProgress(0,0,false); + mNotifyManager.notify(ID, mBuilder.build()); + } + } +// Starts the thread by calling the run() method in its Runnable +).start(); +</pre> + +<!-- ------------------------------------------------------------------------------------------ --> +<h3 id="ActivityIndicator">Menampilkan indikator aktivitas berlanjut</h3> +<p> + Untuk menampilkan indikator aktivitas tidak pasti, tambahkan aktivitas ke pemberitahuan dengan + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, true)} + (dua argumen pertama akan diabaikan), dan keluarkan pemberitahuan. Hasilnya adalah indikator + yang memiliki gaya yang sama dengan baris kemajuan, hanya saja animasinya terus berjalan. +</p> +<p> + Keluarkan pemberitahuan di awal operasi. Animasi akan berjalan hingga Anda + memodifikasi pemberitahuan. Bila operasi selesai, panggil + {@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, false)} + kemudian perbarui pemberitahuan untuk menghapus indikator aktivitas. + Selalu lakukan ini; jika makan animasi akan terus berjalan sekalipun operasi telah selesai. Juga + ingatlah mengubah teks pemberitahuan untuk menunjukkan bahwa operasi telah selesai. +</p> +<p> + Untuk melihat cara kerja indikator aktivitas, lihat cuplikan terdahulu. Cari lokasi baris-baris berikut: +</p> +<pre> +// Sets the progress indicator to a max value, the current completion +// percentage, and "determinate" state +mBuilder.setProgress(100, incr, false); +// Issues the notification +mNotifyManager.notify(0, mBuilder.build()); +</pre> +<p> + Ganti baris yang telah Anda temukan dengan baris berikut: +</p> +<pre> + // Sets an activity indicator for an operation of indeterminate length +mBuilder.setProgress(0, 0, true); +// Issues the notification +mNotifyManager.notify(0, mBuilder.build()); +</pre> + +<h2 id="metadata">Metadata Pemberitahuan</h2> + +<p>Pemberitahuan dapat disortir sesuai metadata yang Anda tetapkan dengan +metode {@link android.support.v4.app.NotificationCompat.Builder} berikut:</p> + +<ul> + <li>{@link android.support.v4.app.NotificationCompat.Builder#setCategory(java.lang.String) setCategory()} + memberi tahu sistem cara menangani pemberitahuan aplikasi Anda bila perangkat berada dalam mode Priority + (misalnya, jika pemberitahuan menyatakan suatu panggilan masuk, pesan instan, atau alarm).</li> + <li>{@link android.support.v4.app.NotificationCompat.Builder#setPriority(int) setPriority()} menyebabkan + pemberitahuan dengan bidang prioritas diatur ke {@code PRIORITY_MAX} atau {@code PRIORITY_HIGH} + muncul dalam jendela kecil mengambang jika pemberitahuan juga memiliki suara atau getaran.</li> + <li>{@link android.support.v4.app.NotificationCompat.Builder#addPerson(java.lang.String) addPerson()} + memungkinkan Anda menambahkan daftar orang ke pemberitahuan. Aplikasi Anda bisa menggunakannya untuk memberi isyarat pada + sistem bahwa sistem harus mengelompokkan bersama pemberitahuan dari orang-orang yang ditetapkan, atau memberi peringkat lebih penting pada pemberitahuan + untuk orang-orang ini.</li> +</ul> + +<div class="figure" style="width:230px"> + <img src="{@docRoot}images/ui/notifications/heads-up.png" alt="" width="" height="" id="figure3" /> + <p class="img-caption"> + <strong>Gambar 3.</strong> Aktivitas layar penuh yang menampilkan pemberitahuan pendahuluan + </p> +</div> + +<h2 id="Heads-up">Pemberitahuan Pendahuluan</h2> + +<p>Dengan Android 5.0 (API level 21), pemberitahuan bisa muncul dalam jendela kecil mengambang +(yang disebut juga dengan <em>pemberitahuan pendahuluan</em>) saat perangkat aktif +(yakni, perangkat dibuka kuncinya dan layarnya menyala). Pemberitahuan ini +muncul seperti bentuk ringkas pemberitahuan Anda, hanya saja +pemberitahuan pendahuluan juga menampilkan tombol tindakan. Pengguna bisa menindaklanjuti atau mengabaikan, +pemberitahuan pendahuluan tanpa meninggalkan aplikasi saat ini.</p> + +<p>Contoh-contoh kondisi yang dapat memicu pemberitahuan pendahuluan antara lain:</p> + +<ul> + <li>Aktivitas pengguna berada dalam mode layar penuh (aplikasi menggunakan +{@link android.app.Notification#fullScreenIntent}), atau</li> + <li>Pemberitahuan memiliki prioritas tinggi dan menggunakan nada dering atau + getaran</li> +</ul> + +<h2 id="lockscreenNotification">Pemberitahuan Layar Kunci</h2> + +<p>Dengan rilis Android 5.0 (API level 21), pemberitahuan kini dapat muncul pada +layar kunci. Aplikasi Anda bisa menggunakan fungsionalitas ini untuk menyediakan kontrol pemutaran media dan +tindakan umum lainnya. Pengguna bisa memilih lewat Settings apakah akan menampilkan pemberitahuan pada layar kunci, dan +Anda bisa mendesain apakah pemberitahuan aplikasi akan terlihat pada layar kunci.</p> + +<h3 id="visibility">Mengatur Visibilitas</h3> + +<p>Aplikasi Anda bisa mengatur level detail terlihat pada pemberitahuan yang ditampilkan di +layar kunci aman. Anda memanggil {@link android.support.v4.app.NotificationCompat.Builder#setVisibility(int) setVisibility()} +dan menetapkan salah satu nilai berikut:</p> + +<ul> + <li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC} menampilkan isi lengkap + pemberitahuan.</li> + <li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_SECRET} tidak menampilkan bagian apa pun dari + pemberitahuan ini pada layar kunci.</li> + <li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} menampilkan informasi dasar, + misalnya ikon dan judul isi pemberitahuan, namun menyembunyikan isi lengkap pemberitahuan.</li> +</ul> + +<p>Bila {@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} telah diatur, Anda juga bisa +menyediakan versi alternatif isi pemberitahuan yang menyembunyikan detail tertentu. Misalnya, +aplikasi SMS dapat menampilkan pemberitahuan yang menampilkan <em>Anda memiliki 3 pesan teks baru</em>, namun menyembunyikan +isi dan pengirim pesan. Untuk menyediakan pemberitahuan alternatif ini, buat dahulu pemberitahuan +pengganti menggunakan {@link android.support.v4.app.NotificationCompat.Builder}. Bila Anda membuat +objek pemberitahuan privat, lampirkan pemberitahuan pengganti melalui metode +{@link android.support.v4.app.NotificationCompat.Builder#setPublicVersion(android.app.Notification) setPublicVersion()} +.</p> + +<h3 id="controllingMedia">Mengontrol Pemutaran Media pada Layar Kunci</h3> + +<p>Dalam Android 5.0 (API level 21) layar kunci tidak lagi menampilkan kontrol media +berdasarkan {@link android.media.RemoteControlClient}, yang sekarang telah dihilangkan. Sebagai gantinya, gunakan +template {@link android.app.Notification.MediaStyle} dengan metode +{@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()} +, yang mengubah tindakan menjadi ikon yang bisa diklik.</p> + +<p class="note"><strong>Catatan:</strong> Template dan metode {@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()} +tidak disertakan dalam pustaka dukungan, sehingga fitur-fitur ini berjalan pada Android 5.0 dan yang lebih tinggi +saja.</p> + +<p>Untuk menampilkan kontrol pemutaran media di layar kunci dalam Android 5.0, atur visibilitas +ke {@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC}, seperti dijelaskan di atas. Kemudian tambahkan +tindakan dan atur template {@link android.app.Notification.MediaStyle}, seperti dijelaskan dalam contoh kode +berikut:</p> + +<pre> +Notification notification = new Notification.Builder(context) + // Show controls on lock screen even when user hides sensitive content. + .setVisibility(Notification.VISIBILITY_PUBLIC) + .setSmallIcon(R.drawable.ic_stat_player) + // Add media control buttons that invoke intents in your media service + .addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0 + .addAction(R.drawable.ic_pause, "Pause", pausePendingIntent) // #1 + .addAction(R.drawable.ic_next, "Next", nextPendingIntent) // #2 + // Apply the media style template + .setStyle(new Notification.MediaStyle() + .setShowActionsInCompactView(1 /* #1: pause button */) + .setMediaSession(mMediaSession.getSessionToken()) + .setContentTitle("Wonderful music") + .setContentText("My Awesome Band") + .setLargeIcon(albumArtBitmap) + .build(); +</pre> + +<p class="note"><strong>Catatan:</strong> Dihilangkannya {@link android.media.RemoteControlClient} +memiliki implikasi lebih jauh untuk mengontrol media. Lihat +<a href="{@docRoot}about/versions/android-5.0.html#MediaPlaybackControl">Kontrol Pemutaran Media</a> +untuk informasi selengkapnya tentang API baru untuk mengelola sesi media dan mengontrol pemutaran.</p> + + +<!-- ------------------------------------------------------------------------------------------ --> +<h2 id="CustomNotification">Layout Pemberitahuan Custom</h2> +<p> + Kerangka kerja pemberitahuan memungkinkan Anda mendefinisikan layout pemberitahuan custom, yang + mendefinisikan penampilan pemberitahuan dalam objek {@link android.widget.RemoteViews}. + Pemberitahuan dengan layout custom serupa pemberitahuan normal, namun dibuat berdasarkan + {@link android.widget.RemoteViews} yang didefinisikan dalam file layout XML. +</p> +<p> + Tinggi yang tersedia untuk layout pemberitahuan custom bergantung pada tampilan pemberitahuan. Layout + tampilan normal dibatasi hingga 64 dp, dan layout tampilan yang diperluas dibatasi hingga 256 dp. +</p> +<p> + Untuk mendefinisikan layout pemberitahuan custom, mulailah dengan membuat instance + objek {@link android.widget.RemoteViews} yang memekarkan file layout XML. Kemudian, + sebagai ganti memanggil metode seperti + {@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()}, + panggil {@link android.support.v4.app.NotificationCompat.Builder#setContent setContent()}. Untuk mengatur + detail isi pemberitahuan custom, gunakan metode dalam + {@link android.widget.RemoteViews} untuk mengatur nilai anak tampilan: +</p> +<ol> + <li> + Buat layout XML untuk pemberitahuan di file terpisah. Anda bisa menggunakan nama file +apa saja yang diinginkan, namun Anda harus menggunakan ekstensi <code>.xml</code> + </li> + <li> + Dalam aplikasi Anda, gunakan metode {@link android.widget.RemoteViews} untuk mendefinisikan + ikon dan teks pemberitahuan. Masukkan objek {@link android.widget.RemoteViews} ini ke dalam + {@link android.support.v4.app.NotificationCompat.Builder} Anda dengan memanggil + {@link android.support.v4.app.NotificationCompat.Builder#setContent setContent()}. Hindari + mengatur {@link android.graphics.drawable.Drawable} latar belakang pada + objek {@link android.widget.RemoteViews} Anda, karena warna teks bisa menjadi tidak terbaca. + </li> +</ol> +<p> + Kelas {@link android.widget.RemoteViews} juga menyertakan metode yang bisa Anda gunakan untuk + menambahkan {@link android.widget.Chronometer} atau {@link android.widget.ProgressBar} +dengan mudah ke layout pemberitahuan Anda. Untuk informasi selengkapnya tentang cara membuat layout custom + pemberitahuan Anda, lihat dokumentasi acuan {@link android.widget.RemoteViews}. +</p> +<p class="caution"> + <strong>Perhatian:</strong> Bila Anda menggunakan layout pemberitahuan custom, berhati-hatilah + untuk memastikan bahwa layout custom itu bekerja pada berbagai orientasi dan resolusi perangkat. Walaupun + berlaku bagi semua layout View, nasihat ini khususnya penting untuk pemberitahuan karena + ruang di laci pemberitahuan sangat terbatas. Jangan buat layout custom terlalu + kompleks, dan pastikan mengujinya di berbagai konfigurasi. +</p> +<!-- ------------------------------------------------------------------------------------------ --> +<h4>Menggunakan sumber daya gaya untuk teks pemberitahuan custom</h4> +<p> + Selalu gunakan sumber daya gaya untuk teks pemberitahuan custom. Warna latar belakang + pemberitahuan bisa bervariasi di berbagai perangkat dan versi, dan menggunakan sumber daya gaya + membantu Anda menangani hal ini. Mulai Android 2.3, sistem mendefinisikan sebuah gaya untuk + teks layout pemberitahuan standar. Jika Anda menggunakan gaya yang sama dalam aplikasi yang menargetkan Android + 2.3 atau yang lebih tinggi, Anda akan memastikan bahwa teks terlihat pada latar belakang tampilan. +</p> diff --git a/docs/html-intl/intl/in/guide/topics/ui/overview.jd b/docs/html-intl/intl/in/guide/topics/ui/overview.jd new file mode 100644 index 000000000000..a0b2b0645a90 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/overview.jd @@ -0,0 +1,71 @@ +page.title=Ikhtisar UI +@jd:body + + +<p>Semua elemen antarmuka pengguna dalam aplikasi Android dibangun menggunakan objek {@link android.view.View} dan +{@link android.view.ViewGroup}. {@link android.view.View} adalah objek yang menarik +sesuatu di layar dan dapat berinteraksi dengan pengguna. {@link android.view.ViewGroup} merupakan sebuah +objek yang menyimpan objek {@link android.view.View} lainnya (dan {@link android.view.ViewGroup}) untuk +mendefinisikan layout antarmuka.</p> + +<p>Android menyediakan sekumpulan subkelas {@link android.view.View} dan {@link +android.view.ViewGroup} yang menawarkan kontrol input umum (seperti tombol dan bidang +teks) serta berbagai model layout (seperti layout linear atau relatif).</p> + + +<h2 id="Layout">Layout Antarmuka Pengguna</h2> + +<p>Antarmuka pengguna untuk setiap komponen aplikasi Anda didefinisikan menggunakan hierarki objek {link +android.view.View} dan {@link android.view.ViewGroup}, seperti yang ditampilkan dalam gambar 1. Setiap kelompok tampilan +merupakan kontainer tak terlihat yang mengelola tampilan anak, sementara tampilan anak ini dapat menjadi kontrol +input atau widget lain yang +menarik sebagian dari UI. Pohon hierarki ini bisa sederhana atau bisa juga kompleks bergantung kebutuhan +(namun yang sederhana paling baik untuk kinerja).</p> + +<img src="{@docRoot}images/viewgroup.png" alt="" /> +<p class="img-caption"><strong>Gambar 1.</strong> Ilustrasi dari hierarki tampilan, yang mendefinisikan layout +UI.</p> + +<p>Untuk mendeklarasikan layout, Anda dapat menyediakan objek {@link android.view.View} dalam kode dan mulai +membangun pohon, namun cara termudah dan terefektif untuk mendefinisikan layout adalah dengan file XML. +XML menawarkan struktur layout yang dapat dibaca manusia, serupa dengan HTML.</p> + +<p>Nama elemen XML untuk tampilan sesuai dengan kelas Android yang diwakilinya. Dengan demikian elemen +<code><TextView></code> membuat widget {@link android.widget.TextView} dalam UI Anda, +dan elemen <code><LinearLayout></code> membuat kelompok tampilan {@link android.widget.LinearLayout} +. </p> + +<p>Misalnya, layout vertikal sederhana dengan tampilan teks dan tombol akan tampak seperti ini:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="vertical" > + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="I am a TextView" /> + <Button android:id="@+id/button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="I am a Button" /> +</LinearLayout> +</pre> + +<p>Saat Anda memuat sumber daya layout di aplikasi, Android akan menginisialisasi setiap simpul layout menjadi +objek runtime yang bisa Anda gunakan untuk mendefinisikan perilaku tambahan, query status objek, atau memodifikasi +layout.</p> + +<p>Untuk mendapatkan panduan lengkap mengenai pembuatan layout UI, lihat <a href="declaring-layout.html">Layout +XML</a>. + + +<h2 id="UIComponents">Komponen Antarmuka Pengguna</h2> + +<p>Anda tidak harus membuat semua UI menggunakan objek {@link android.view.View} dan {link +android.view.ViewGroup}. Android menyediakan beberapa komponen aplikasi yang menawarkan +layout UI standar yang tinggal Anda definisikan kontennya. Komponen UI ini masing-masing +memiliki set API unik yang dijelaskan dalam masing-masing dokumennya, seperti <a href="{@docRoot}guide/topics/ui/actionbar.html">Action-Bar</a>, <a href="{@docRoot}guide/topics/ui/dialogs.html">Dialog</a>, dan <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Pemberitahuan Status</a>.</p> + + diff --git a/docs/html-intl/intl/in/guide/topics/ui/settings.jd b/docs/html-intl/intl/in/guide/topics/ui/settings.jd new file mode 100644 index 000000000000..5ac61f928c19 --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/settings.jd @@ -0,0 +1,1202 @@ +page.title=Pengaturan +page.tags=preference,preferenceactivity,preferencefragment + +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Dalam dokumen ini</h2> +<ol> + <li><a href="#Overview">Ikhtisar</a> + <ol> + <li><a href="#SettingTypes">Preferensi</a></li> + </ol> + </li> + <li><a href="#DefiningPrefs">Mendefinisikan Preferensi dalam XML</a> + <ol> + <li><a href="#Groups">Membuat grup pengaturan</a></li> + <li><a href="#Intents">Menggunakan intent</a></li> + </ol> + </li> + <li><a href="#Activity">Membuat Aktivitas Preferensi</a></li> + <li><a href="#Fragment">Menggunakan Fragmen Preferensi</a></li> + <li><a href="#Defaults">Mengatur Nilai Default</a></li> + <li><a href="#PreferenceHeaders">Menggunakan Header Preferensi</a> + <ol> + <li><a href="#CreateHeaders">Membuat file header</a></li> + <li><a href="#DisplayHeaders">Menampilkan header</a></li> + <li><a href="#BackCompatHeaders">Mendukung versi yang lebih lama dengan header preferensi</a></li> + </ol> + </li> + <li><a href="#ReadingPrefs">Preferensi Membaca</a> + <ol> + <li><a href="#Listening">Mendengarkan perubahan preferensi</a></li> + </ol> + </li> + <li><a href="#NetworkUsage">Mengelola Penggunaan Jaringan</a></li> + <li><a href="#Custom">Membangun Preferensi Custom</a> + <ol> + <li><a href="#CustomSelected">Menetapkan antarmuka pengguna</a></li> + <li><a href="#CustomSave">Menyimpan nilai pengaturan</a></li> + <li><a href="#CustomInitialize">Menginisialisasi nilai saat ini</a></li> + <li><a href="#CustomDefault">Menyediakan nilai default</a></li> + <li><a href="#CustomSaveState">Menyimpan dan memulihkan status Preferensi</a></li> + </ol> + </li> +</ol> + +<h2>Kelas-kelas utama</h2> +<ol> + <li>{@link android.preference.Preference}</li> + <li>{@link android.preference.PreferenceActivity}</li> + <li>{@link android.preference.PreferenceFragment}</li> +</ol> + + +<h2>Lihat juga</h2> +<ol> + <li><a href="{@docRoot}design/patterns/settings.html">Panduan desain pengaturan</a></li> +</ol> +</div> +</div> + + + + +<p>Aplikasi sering kali menyertakan pengaturan yang memungkinkan pengguna memodifikasi fitur dan perilaku aplikasi. Misalnya, +beberapa aplikasi memungkinkan pengguna untuk menetapkan apakah pemberitahuan diaktifkan atau menetapkan seberapa sering +aplikasi menyinkronkan data dengan cloud.</p> + +<p>Jika ingin menyediakan pengaturan untuk aplikasi, Anda harus menggunakan +API Android {@link android.preference.Preference} untuk membangun antarmuka yang konsisten dengan +pengalaman pengguna di aplikasi Android yang lain (termasuk pengaturan sistem). Dokumen ini menjelaskan +cara membangun pengaturan aplikasi Anda menggunakan API {@link android.preference.Preference}.</p> + +<div class="note design"> +<p><strong>Desain Pengaturan</strong></p> + <p>Untuk informasi tentang cara mendesain pengaturan Anda, bacalah panduan desain <a href="{@docRoot}design/patterns/settings.html">Pengaturan</a>.</p> +</div> + + +<img src="{@docRoot}images/ui/settings/settings.png" alt="" width="435" /> +<p class="img-caption"><strong>Gambar 1.</strong> Cuplikan layar dari pengaturan +aplikasi Messaging Android. Memilih item yang didefinisikan oleh {@link android.preference.Preference} +akan membuka antarmuka untuk mengubah pengaturan.</p> + + + + +<h2 id="Overview">Ikhtisar</h2> + +<p>Sebagai ganti menggunakan objek {@link android.view.View} untuk membangun antarmuka pengguna, pengaturan +dibangun menggunakan berbagai subkelas dari kelas {@link android.preference.Preference} yang Anda +deklarasikan dalam file XML.</p> + +<p>Objek {@link android.preference.Preference} adalah blok pembangun untuk pengaturan +tunggal. Setiap {@link android.preference.Preference} muncul sebagai item dalam daftar dan menyediakan UI +yang sesuai bagi pengguna untuk memodifikasi pengaturan. Misalnya, {@link +android.preference.CheckBoxPreference} membuat item daftar yang menampilkan kotak cek, dan {@link +android.preference.ListPreference} membuat item yang membuka dialog berisi daftar pilihan.</p> + +<p>Setiap {@link android.preference.Preference} yang Anda tambahkan memiliki pasangan nilai-kunci yang sesuai yang +digunakan sistem untuk menyimpan pengaturan dalam file {@link android.content.SharedPreferences} +default untuk pengaturan aplikasi Anda. Bila pengguna mengubah pengaturan, sistem akan memperbarui nilai +yang bersangkutan dalam file {@link android.content.SharedPreferences} untuk Anda. Satu-satunya saat di mana Anda harus +berinteraksi langsung dengan file {@link android.content.SharedPreferences} yang terkait adalah bila Anda +perlu membaca nilai untuk menentukan perilaku aplikasi berdasarkan pengaturan pengguna.</p> + +<p>Nilai yang tersimpan di {@link android.content.SharedPreferences} untuk setiap pengaturan bisa berupa +tipe data berikut:</p> + +<ul> + <li>Boolean</li> + <li>Float</li> + <li>Int</li> + <li>Long</li> + <li>String</li> + <li>String {@link java.util.Set}</li> +</ul> + +<p>Oleh karena UI pengaturan aplikasi Anda dibangun menggunakan objek {@link android.preference.Preference} +sebagai ganti +objek {@link android.view.View}, Anda perlu menggunakan {@link android.app.Activity} khusus atau +subkelas {@link android.app.Fragment} untuk menampilkan pengaturan daftar:</p> + +<ul> + <li>Jika aplikasi Anda mendukung versi Android yang lebih lama dari 3.0 (API level 10 dan yang lebih rendah), Anda harus +membangun aktivitas sebagai ekstensi dari kelas {@link android.preference.PreferenceActivity}.</li> + <li>Pada Android 3.0 dan yang lebih baru, sebaiknya Anda menggunakan {@link android.app.Activity} biasa +yang menjadi host {@link android.preference.PreferenceFragment} yang menampilkan pengaturan aplikasi Anda. +Akan tetapi, Anda juga bisa menggunakan {@link android.preference.PreferenceActivity} untuk membuat layout dua panel +bagi layar besar bila Anda memiliki beberapa grup pengaturan.</li> +</ul> + +<p>Cara mengatur {@link android.preference.PreferenceActivity} Anda dan instance {@link +android.preference.PreferenceFragment} dibahas di bagian tentang <a href="#Activity">Membuat Aktivitas Preferensi</a> dan <a href="#Fragment">Menggunakan +Fragmen Preferensi</a>.</p> + + +<h3 id="SettingTypes">Preferensi</h3> + +<p>Setiap pengaturan untuk aplikasi Anda diwakili oleh subkelas khusus dari kelas {@link +android.preference.Preference}. Setiap subkelas menyertakan seperangkat properti utama yang memungkinkan Anda +untuk menetapkan berbagai hal seperti judul pengaturan dan nilai default. Setiap subkelas juga menyediakan +antarmuka pengguna dan properti khusus miliknya sendiri. Misalnya, gambar 1 menampilkan cuplikan layar dari + pengaturan aplikasi Messaging. Setiap item daftar dalam layar pengaturan didukung oleh objek {@link +android.preference.Preference} berbeda.</p> + +<p>Beberapa preferensi yang paling umum adalah:</p> + +<dl> + <dt>{@link android.preference.CheckBoxPreference}</dt> + <dd>Menampilkan item dengan kotak cek untuk pengaturan yang diaktifkan atau dinonaktifkan. Nilai +tersimpan adalah boolean (<code>true</code> jika diberi tanda cek).</dd> + + <dt>{@link android.preference.ListPreference}</dt> + <dd>Membuka dialog berisi daftar tombol radio. Nilai +tersimpan bisa berupa tipe nilai apa pun yang didukung (tercantum di atas).</dd> + + <dt>{@link android.preference.EditTextPreference}</dt> + <dd>Membuka dialog berisi widget {@link android.widget.EditText}. Nilai tersimpan adalah {@link +java.lang.String}.</dd> +</dl> + +<p>Lihat kelas {@link android.preference.Preference} untuk mengetahui daftar subkelas lain dan +propertinya.</p> + +<p>Tentu saja, kelas bawaan tidak mengakomodasi setiap kebutuhan dan aplikasi Anda mungkin memerlukan +sesuatu yang lebih khusus. Misalnya, platform saat ini tidak menyediakan kelas {@link +android.preference.Preference} untuk mengambil nomor atau tanggal. Anda mungkin perlu mendefinisikan +subkelas {@link android.preference.Preference} sendiri. Untuk bantuan melakukannya, lihat bagian tentang <a href="#Custom">Membangun Preferensi Custom</a>.</p> + + + +<h2 id="DefiningPrefs">Mendefinisikan Preferensi dalam XML</h2> + +<p>Meskipun bisa membuat instance objek {@link android.preference.Preference} baru saat runtime, Anda +harus mendefinisikan daftar pengaturan dalam XML dengan hierarki objek +{@link android.preference.Preference}. Menggunakan file XML untuk mendefinisikan sekumpulan pengaturan lebih disukai karena file +menyediakan struktur yang mudah dibaca dan diperbarui. Selain itu, pengaturan aplikasi Anda +umumnya telah ditetapkan sebelumnya, meskipun Anda masih bisa memodifikasi kumpulan tersebut saat runtime.</p> + +<p>Setiap subkelas {@link android.preference.Preference} bisa dideklarasikan dengan elemen XML yang +cocok dengan nama kelas, seperti {@code <CheckBoxPreference>}.</p> + +<p>Anda harus menyimpan file XML dalam direktori {@code res/xml/}. Meskipun bisa memberi nama file +sesuka Anda, biasanya file diberi nama {@code preferences.xml}. Biasanya Anda hanya memerlukan satu file, +karena cabang di hierarki (yang membuka daftar pengaturanny sendiri) dideklarasikan menggunakan instance +tersarang {@link android.preference.PreferenceScreen}.</p> + +<p class="note"><strong>Catatan:</strong> Jika ingin membuat layout multipanel untuk +pengaturan, Anda memerlukan file XML terpisah untuk setiap fragmen.</p> + +<p>Simpul akar untuk file XML harus merupakan elemen {@link android.preference.PreferenceScreen +<PreferenceScreen>}. Dalam elemen inilah tempat Anda menambahkan setiap {@link +android.preference.Preference}. Setiap anak yang Anda tambahkan dalam elemen +{@link android.preference.PreferenceScreen <PreferenceScreen>} akan tampak sebagai item +tunggal dalam daftar pengaturan.</p> + +<p>Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> + <CheckBoxPreference + android:key="pref_sync" + android:title="@string/pref_sync" + android:summary="@string/pref_sync_summ" + android:defaultValue="true" /> + <ListPreference + android:dependency="pref_sync" + android:key="pref_syncConnectionType" + android:title="@string/pref_syncConnectionType" + android:dialogTitle="@string/pref_syncConnectionType" + android:entries="@array/pref_syncConnectionTypes_entries" + android:entryValues="@array/pref_syncConnectionTypes_values" + android:defaultValue="@string/pref_syncConnectionTypes_default" /> +</PreferenceScreen> +</pre> + +<p>Dalam contoh ini, terdapat {@link android.preference.CheckBoxPreference} dan {@link +android.preference.ListPreference}. Kedua item tersebut menyertakan tiga atribut berikut:</p> + +<dl> + <dt>{@code android:key}</dt> + <dd>Atribut ini diperlukan untuk preferensi yang mempertahankan nilai data. Ini menetapkan kunci +unik (string) yang digunakan sistem saat menyimpan nilai pengaturan ini dalam {@link +android.content.SharedPreferences}. + <p>Instance satu-satunya di mana atribut ini <em>tidak diperlukan</em> adalah bila preferensi berupa +{@link android.preference.PreferenceCategory} atau {@link android.preference.PreferenceScreen}, atau +preferensi menetapkan {@link android.content.Intent} untuk dipanggil (dengan elemen <a href="#Intents">{@code <intent>}</a>) atau {@link android.app.Fragment} untuk ditampilkan (dengan atribut <a href="{@docRoot}reference/android/preference/Preference.html#attr_android:fragment">{@code +android:fragment}</a>).</p> + </dd> + <dt>{@code android:title}</dt> + <dd>Ini menyediakan nama pengaturan yang bisa dilihat oleh pengguna.</dd> + <dt>{@code android:defaultValue}</dt> + <dd>Ini menetapkan nilai awal yang harus diatur sistem dalam file {@link +android.content.SharedPreferences}. Anda harus memberikan nilai default untuk semua +pengaturan.</dd> +</dl> + +<p>Untuk informasi tentang semua atribut lain yang didukung, lihat dokumentasi {@link +android.preference.Preference} (dan subkelas masing-masing).</p> + + +<div class="figure" style="width:300px"> + <img src="{@docRoot}images/ui/settings/settings-titles.png" alt="" /> + <p class="img-caption"><strong>Gambar 2.</strong> Mengatur kategori + dengan judul. <br/><b>1.</b> Kategori ditetapkan oleh elemen {@link +android.preference.PreferenceCategory <PreferenceCategory>}. <br/><b>2.</b> Judul +ditetapkan dengan atribut {@code android:title}.</p> +</div> + + +<p>Bila daftar pengaturan Anda melebihi sekitar 10 item, Anda mungkin perlu menambahkan judul untuk +mendefinisikan grup pengaturan atau menampilkan grup tersebut di +layar terpisah. Opsi ini dijelaskan di bagian berikut.</p> + + +<h3 id="Groups">Membuat grup pengaturan</h3> + +<p>Jika Anda menampilkan daftar 10 pengaturan atau lebih, pengguna +mungkin akan kesulitan dalam memindai, memahami dan memprosesnya. Anda bisa mengatasinya dengan +membagi sebagian atau semua pengaturan ke dalam beberapa grup, yang secara efektif akan mengubah satu daftar panjang menjadi beberapa daftar +yang lebih pendek. Suatu grup pengaturan terkait bisa ditampilkan dalam salah satu dari dua cara:</p> + +<ul> + <li><a href="#Titles">Menggunakan judul</a></li> + <li><a href="#Subscreens">Menggunakan sublayar</a></li> +</ul> + +<p>Anda bisa menggunakan salah satu atau keduanya untuk mengelola pengaturan aplikasi Anda. Saat +memutuskan mana yang akan digunakan dan cara membagi pengaturan, Anda harus mengikuti pedoman dalam +Panduan <a href="{@docRoot}design/patterns/settings.html">Pengaturan</a> Desain Android.</p> + + +<h4 id="Titles">Menggunakan judul</h4> + +<p>Jika ingin menyediakan divider dengan heading di antara grup pengaturan (seperti yang ditampilkan dalam gambar 2), +tempatkan setiap grup objek {@link android.preference.Preference} di dalam {@link +android.preference.PreferenceCategory}.</p> + +<p>Misalnya:</p> + +<pre> +<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> + <PreferenceCategory + android:title="@string/pref_sms_storage_title" + android:key="pref_key_storage_settings"> + <CheckBoxPreference + android:key="pref_key_auto_delete" + android:summary="@string/pref_summary_auto_delete" + android:title="@string/pref_title_auto_delete" + android:defaultValue="false"... /> + <Preference + android:key="pref_key_sms_delete_limit" + android:dependency="pref_key_auto_delete" + android:summary="@string/pref_summary_delete_limit" + android:title="@string/pref_title_sms_delete"... /> + <Preference + android:key="pref_key_mms_delete_limit" + android:dependency="pref_key_auto_delete" + android:summary="@string/pref_summary_delete_limit" + android:title="@string/pref_title_mms_delete" ... /> + </PreferenceCategory> + ... +</PreferenceScreen> +</pre> + + +<h4 id="Subscreens">Menggunakan sublayar</h4> + +<p>Jika ingin menempatkan grup pengaturan ke dalam sublayar (seperti yang ditampilkan dalam gambar 3), tempatkan grup +objek {@link android.preference.Preference} di dalam {@link +android.preference.PreferenceScreen}.</p> + +<img src="{@docRoot}images/ui/settings/settings-subscreen.png" alt="" /> +<p class="img-caption"><strong>Gambar 3.</strong> Mengatur sublayar. Elemen {@code +<PreferenceScreen>} +membuat item yang, bila dipilih, akan membuka daftar terpisah untuk menampilkan pengaturan tersarang.</p> + +<p>Misalnya:</p> + +<pre> +<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> + <!-- opens a subscreen of settings --> + <PreferenceScreen + android:key="button_voicemail_category_key" + android:title="@string/voicemail" + android:persistent="false"> + <ListPreference + android:key="button_voicemail_provider_key" + android:title="@string/voicemail_provider" ... /> + <!-- opens another nested subscreen --> + <PreferenceScreen + android:key="button_voicemail_setting_key" + android:title="@string/voicemail_settings" + android:persistent="false"> + ... + </PreferenceScreen> + <RingtonePreference + android:key="button_voicemail_ringtone_key" + android:title="@string/voicemail_ringtone_title" + android:ringtoneType="notification" ... /> + ... + </PreferenceScreen> + ... +</PreferenceScreen> +</pre> + + +<h3 id="Intents">Menggunakan intent</h3> + +<p>Dalam beberapa kasus, Anda mungkin ingin item preferensi untuk membuka beberapa aktivitas sebagai ganti +layar pengaturan, seperti browser web untuk melihat halaman web. Untuk memanggil {@link +android.content.Intent} saat pengguna memilih item preferensi, tambahkan elemen {@code <intent>} +sebagai anak dari elemen {@code <Preference>} yang bersangkutan.</p> + +<p>Misalnya, berikut ini cara menggunakan item preferensi untuk membuka halaman web:</p> + +<pre> +<Preference android:title="@string/prefs_web_page" > + <intent android:action="android.intent.action.VIEW" + android:data="http://www.example.com" /> +</Preference> +</pre> + +<p>Anda bisa membuat intent implisit maupun eksplisit menggunakan atribut berikut:</p> + +<dl> + <dt>{@code android:action}</dt> + <dd>Tindakan yang akan ditetapkan, sesuai metode +{@link android.content.Intent#setAction setAction()}.</dd> + <dt>{@code android:data}</dt> + <dd>Data yang akan ditetapkan, sesuai metode {@link android.content.Intent#setData setData()}.</dd> + <dt>{@code android:mimeType}</dt> + <dd>Tipe MIME yang akan ditetapkan, sesuai metode +{@link android.content.Intent#setType setType()}.</dd> + <dt>{@code android:targetClass}</dt> + <dd>Bagian kelas dari nama komponen, sesuai metode {@link android.content.Intent#setComponent +setComponent()}.</dd> + <dt>{@code android:targetPackage}</dt> + <dd>Bagian paket dari nama komponen, sesuai metode {@link +android.content.Intent#setComponent setComponent()}.</dd> +</dl> + + + +<h2 id="Activity">Membuat Aktivitas Preferensi</h2> + +<p>Untuk menampilkan pengaturan Anda dalam suatu aktivitas, perluas kelas {@link +android.preference.PreferenceActivity}. Ini adalah ekstensi dari kelas {@link +android.app.Activity} biasa yang menampilkan daftar pengaturan berdasarkan hierarki objek {@link +android.preference.Preference}. {@link android.preference.PreferenceActivity} +secara otomatis mempertahankan pengaturan yang dikaitkan dengan setiap {@link +android.preference.Preference} bila pengguna membuat perubahan.</p> + +<p class="note"><strong>Catatan:</strong> Jika Anda mengembangkan aplikasi untuk Android 3.0 dan +yang lebih tinggi, sebaiknya gunakan {@link android.preference.PreferenceFragment}. Pindah ke bagian +berikutnya tentang <a href="#Fragment">Menggunakan Fragmen Preferensi</a>.</p> + +<p>Hal paling penting untuk diingat adalah jangan memuat layout tampilan selama callback {@link +android.preference.PreferenceActivity#onCreate onCreate()}. Sebagai gantinya, panggil {@link +android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} untuk +menambahkan preferensi yang telah Anda deklarasikan dalam file XML ke aktivitas. Misalnya, berikut ini adalah kode minimum +polos yang diperlukan untuk {@link android.preference.PreferenceActivity} fungsional:</p> + +<pre> +public class SettingsActivity extends PreferenceActivity { + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + addPreferencesFromResource(R.xml.preferences); + } +} +</pre> + +<p>Ini sebenarnya kode yang cukup untuk beberapa aplikasi, karena segera setelah pengguna memodifikasi preferensi, +sistem akan menyimpan perubahan tersebut ke file {@link android.content.SharedPreferences} default yang +bisa dibaca oleh komponen aplikasi Anda lainnya bila Anda perlu memeriksa pengaturan pengguna. Akan tetapi, +banyak aplikasi, yang memerlukan kode lebih sedikit untuk mendengarkan perubahan yang terjadi pada preferensi. +Untuk informasi tentang mendengarkan perubahan di file {@link android.content.SharedPreferences}, +lihat bagian tentang <a href="#ReadingPrefs">Preferensi Membaca</a>.</p> + + + + +<h2 id="Fragment">Menggunakan Fragmen Preferensi</h2> + +<p>Jika Anda mengembangkan Android 3.0 (API level 11) dan yang lebih tinggi, Anda harus menggunakan {@link +android.preference.PreferenceFragment} untuk menampilkan daftar objek {@link android.preference.Preference} +Anda. Anda bisa menambahkan {@link android.preference.PreferenceFragment} ke aktivitas apa pun,—Anda tidak +perlu menggunakan {@link android.preference.PreferenceActivity}.</p> + +<p><a href="{@docRoot}guide/components/fragments.html">Fragmen</a> menyediakan arsitektur yang lebih +fleksibel untuk aplikasi Anda, dibandingkan hanya menggunakan aktivitas, apa pun jenis +aktivitas yang Anda bangun. Dengan sendirinya, kami menyarankan Anda menggunakan {@link +android.preference.PreferenceFragment} untuk mengontrol tampilan pengaturan Anda sebagai ganti {@link +android.preference.PreferenceActivity} bila memungkinkan.</p> + +<p>Implementasi {@link android.preference.PreferenceFragment} Anda bisa semudah +mendefinisikan metode {@link android.preference.PreferenceFragment#onCreate onCreate()} untuk memuat +file preferensi dengan {@link android.preference.PreferenceFragment#addPreferencesFromResource +addPreferencesFromResource()}. Misalnya:</p> + +<pre> +public static class SettingsFragment extends PreferenceFragment { + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + // Load the preferences from an XML resource + addPreferencesFromResource(R.xml.preferences); + } + ... +} +</pre> + +<p>Anda nanti bisa menambahkan fragmen ini ke {@link android.app.Activity} seperti yang Anda lakukan untuk +{@link android.app.Fragment} lainnya. Misalnya:</p> + +<pre> +public class SettingsActivity extends Activity { + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + // Display the fragment as the main content. + getFragmentManager().beginTransaction() + .replace(android.R.id.content, new SettingsFragment()) + .commit(); + } +} +</pre> + +<p class="note"><strong>Catatan:</strong> {@link android.preference.PreferenceFragment} tidak memiliki +objek {@link android.content.Context} sendiri. Jika memerlukan objek {@link android.content.Context} +, Anda bisa memanggil {@link android.app.Fragment#getActivity()}. Akan tetapi, berhati-hatilah untuk memanggil +{@link android.app.Fragment#getActivity()} hanya bila fragmen telah dikaitkan dengan aktivitas. Bila +fragmen belum dikaitkan, atau terlepas saat akhir daur hidupnya, {@link +android.app.Fragment#getActivity()} akan mengembalikan nol.</p> + + +<h2 id="Defaults">Mengatur Nilai Default</h2> + +<p>Preferensi yang Anda buat mungkin mendefinisikan beberapa perilaku penting untuk aplikasi, jadi Anda +perlu menginisialisasi file {@link android.content.SharedPreferences} yang terkait dengan +nilai default untuk setiap {@link android.preference.Preference} bila pengguna menggunakan aplikasi +Anda untuk pertama kali.</p> + +<p>Hal pertama yang harus Anda lakukan adalah menetapkan nilai default untuk setiap objek {@link +android.preference.Preference} +di file XML Anda menggunakan atribut {@code android:defaultValue}. Nilainya bisa berupa tipe data +apa saja yang sesuai untuk objek {@link android.preference.Preference} bersangkutan. Misalnya: +</p> + +<pre> +<!-- default value is a boolean --> +<CheckBoxPreference + android:defaultValue="true" + ... /> + +<!-- default value is a string --> +<ListPreference + android:defaultValue="@string/pref_syncConnectionTypes_default" + ... /> +</pre> + +<p>Kemudian, dari metode {@link android.app.Activity#onCreate onCreate()} dalam aktivitas utama aplikasi +Anda—dan dalam aktivitas lainnya yang digunakan pengguna untuk masuk ke aplikasi Anda untuk pertama kali +—panggil {@link android.preference.PreferenceManager#setDefaultValues +setDefaultValues()}:</p> + +<pre> +PreferenceManager.setDefaultValues(this, R.xml.advanced_preferences, false); +</pre> + +<p>Memanggil ini selama {@link android.app.Activity#onCreate onCreate()} akan memastikan aplikasi +Anda diinisialisasi dengan pengaturan default, yang mungkin perlu +dibaca oleh aplikasi Anda untuk menentukan beberapa perilaku (seperti apakah akan mengunduh data pada +jaringan seluler).</p> + +<p>Metode ini membutuhkan tiga argumen:</p> +<ul> + <li>{@link android.content.Context} aplikasi Anda.</li> + <li>ID sumber daya untuk file XML preferensi yang ingin Anda atur nilai defaultnya.</li> + <li>Boolean menunjukkan apakah nilai default harus diatur lebih dari satu kali. +<p>Bila <code>false</code>, sistem akan mengatur nilai default hanya jika metode ini belum pernah +dipanggil sebelumnya (atau {@link android.preference.PreferenceManager#KEY_HAS_SET_DEFAULT_VALUES} +dalam file preferensi berbagi nilai default salah).</p></li> +</ul> + +<p>Selama Anda mengatur argumen ketiga ke <code>false</code>, Anda bisa dengan aman memanggil metode ini +setiap kali aktivitas Anda memulai tanpa mengesampingkan preferensi tersimpan pengguna dengan mengatur ulang preferensi tersebut ke +default. Akan tetapi, jika mengatur ke <code>true</code>, Anda akan mengesampingkan nilai +sebelumnya dengan default.</p> + + + +<h2 id="PreferenceHeaders">Menggunakan Header Preferensi</h2> + +<p>Dalam kasus yang jarang terjadi, Anda mungkin perlu mendesain pengaturan agar layar pertama +hanya menampilkan daftar <a href="#Subscreens">sublayar</a> (seperti dalam aplikasi Setting pada sistem, +seperti yang ditampilkan dalam gambar 4 dan 5). Bila mengembangkan desain seperti itu untuk Android 3.0 dan yang lebih tinggi, Anda +harus menggunakan fitur "header" yang baru di Android 3.0, sebagai ganti membangun sublayar dengan elemen +{@link android.preference.PreferenceScreen} tersarang.</p> + +<p>Untuk membangun pengaturan dengan header, Anda perlu:</p> +<ol> + <li>Memisahkan setiap grup pengaturan ke dalam instance {@link +android.preference.PreferenceFragment} terpisah. Ini berarti, setiap grup pengaturan memerlukan file XML +terpisah.</li> + <li>Membuat file header XML yang mencantumkan daftar setiap grup pengaturan dan mendeklarasikan fragmen mana +yang berisi daftar pengaturan yang sesuai.</li> + <li>Memperluas kelas {@link android.preference.PreferenceActivity} untuk menjadi host pengaturan Anda.</li> + <li>Mengimplementasikan callback {@link +android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} untuk menetapkan file +header.</li> +</ol> + +<p>Manfaat besar dalam menggunakan desain ini adalah karena {@link android.preference.PreferenceActivity} +secara otomatis akan menampilkan layout dua panel yang ditampilkan dalam gambar 4 bila dijalankan pada layar besar.</p> + +<p>Bahkan jika aplikasi Anda mendukung versi Android yang lebih lama dari 3.0, Anda bisa membangun +aplikasi untuk menggunakan {@link android.preference.PreferenceFragment} bagi presentasi dua panel pada perangkat +yang lebih baru sementara tetap mendukung hierarki multilayar biasa pada perangkat +yang lebih lama (lihat bagian tentang <a href="#BackCompatHeaders">Mendukung versi yang lebih lama dengan +header preferensi</a>).</p> + +<img src="{@docRoot}images/ui/settings/settings-headers-tablet.png" alt="" /> +<p class="img-caption"><strong>Gambar 4.</strong> Layout dua panel dengan header. <br/><b>1.</b> Header +didefinisikan dengan file header XML. <br/><b>2.</b> Setiap grup pengaturan didefinisikan dengan +{@link android.preference.PreferenceFragment} yang ditetapkan oleh elemen {@code <header>} dalam +file header.</p> + +<img src="{@docRoot}images/ui/settings/settings-headers-handset.png" alt="" /> +<p class="img-caption"><strong>Gambar 5.</strong> Perangkat handset dengan header pengaturan. Bila sebuah +item dipilih, {@link android.preference.PreferenceFragment} terkait akan menggantikan +header.</p> + + +<h3 id="CreateHeaders" style="clear:left">Membuat file header</h3> + +<p>Setiap grup pengaturan dalam daftar header Anda akan ditetapkan oleh elemen {@code <header>} +tunggal dalam elemen {@code <preference-headers>} akar. Misalnya:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> + <header + android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentOne" + android:title="@string/prefs_category_one" + android:summary="@string/prefs_summ_category_one" /> + <header + android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentTwo" + android:title="@string/prefs_category_two" + android:summary="@string/prefs_summ_category_two" > + <!-- key/value pairs can be included as arguments for the fragment. --> + <extra android:name="someKey" android:value="someHeaderValue" /> + </header> +</preference-headers> +</pre> + +<p>Dengan atribut {@code android:fragment}, setiap header mendeklarasikan instance {@link +android.preference.PreferenceFragment} yang harus terbuka saat pengguna memilih header.</p> + +<p>Elemen {@code <extras>} memungkinkan Anda meneruskan pasangan nilai-kunci ke fragmen di {@link +android.os.Bundle}. Fragmen bisa mengambil argumen dengan memanggil {@link +android.app.Fragment#getArguments()}. Anda bisa meneruskan argumen ke fragmen dengan berbagai +alasan, namun satu alasan yang baik adalah untuk menggunakan kembali subkelas yang sama dari {@link +android.preference.PreferenceFragment} untuk setiap grup dan menggunakan argumen untuk menetapkan file +XML preferensi mana yang harus dimuat fragmen.</p> + +<p>Misalnya, ada fragmen yang bisa digunakan ulang untuk berbagai grup pengaturan, bila setiap +header mendefinisikan argumen {@code <extra>} dengan kunci {@code "settings"}:</p> + +<pre> +public static class SettingsFragment extends PreferenceFragment { + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + String settings = getArguments().getString("settings"); + if ("notifications".equals(settings)) { + addPreferencesFromResource(R.xml.settings_wifi); + } else if ("sync".equals(settings)) { + addPreferencesFromResource(R.xml.settings_sync); + } + } +} +</pre> + + + +<h3 id="DisplayHeaders">Menampilkan header</h3> + +<p>Untuk menampilkan header preferensi, Anda harus mengimplementasikan metode callback {@link +android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} dan memanggil +{@link android.preference.PreferenceActivity#loadHeadersFromResource +loadHeadersFromResource()}. Misalnya:</p> + +<pre> +public class SettingsActivity extends PreferenceActivity { + @Override + public void onBuildHeaders(List<Header> target) { + loadHeadersFromResource(R.xml.preference_headers, target); + } +} +</pre> + +<p>Bila pengguna memilih item dari daftar header, sistem akan membuka {@link +android.preference.PreferenceFragment} terkait.</p> + +<p class="note"><strong>Catatan:</strong> Saat menggunakan header preferensi, subkelas {@link +android.preference.PreferenceActivity} Anda tidak perlu mengimplementasikan metode {@link +android.preference.PreferenceActivity#onCreate onCreate()}, karena tugas +yang diperlukan untuk aktivitas hanyalah memuat header.</p> + + +<h3 id="BackCompatHeaders">Mendukung versi yang lebih lama dengan header preferensi</h3> + +<p>Jika aplikasi Anda mendukung versi Android yang lebih lama dari 3.0, Anda tetap bisa menggunakan header untuk +menyediakan layout dua panel saat berjalan pada Android 3.0 dan yang lebih tinggi. Anda hanya perlu membuat +file XML preferensi tambahan yang menggunakan elemen {@link android.preference.Preference +<Preference>} dasar yang berperilaku seperti item header (untuk digunakan oleh Android +versi yang lebih lama).</p> + +<p>Akan tetapi, sebagai ganti membuka {@link android.preference.PreferenceScreen} baru, setiap elemen {@link +android.preference.Preference <Preference>} mengirimkan {@link android.content.Intent} ke +{@link android.preference.PreferenceActivity} yang menetapkan file XML preferensi mana yang +akan dimuat.</p> + +<p>Misalnya, ini adalah file XML untuk header preferensi yang menggunakan Android 3.0 +dan yang lebih tinggi ({@code res/xml/preference_headers.xml}):</p> + +<pre> +<preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> + <header + android:fragment="com.example.prefs.SettingsFragmentOne" + android:title="@string/prefs_category_one" + android:summary="@string/prefs_summ_category_one" /> + <header + android:fragment="com.example.prefs.SettingsFragmentTwo" + android:title="@string/prefs_category_two" + android:summary="@string/prefs_summ_category_two" /> +</preference-headers> +</pre> + +<p>Dan ini adalah file preferensi yang menyediakan header yang sama untuk versi yang lebih lama dari +Android 3.0 ({@code res/xml/preference_headers_legacy.xml}):</p> + +<pre> +<PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> + <Preference + android:title="@string/prefs_category_one" + android:summary="@string/prefs_summ_category_one" > + <intent + android:targetPackage="com.example.prefs" + android:targetClass="com.example.prefs.SettingsActivity" + android:action="com.example.prefs.PREFS_ONE" /> + </Preference> + <Preference + android:title="@string/prefs_category_two" + android:summary="@string/prefs_summ_category_two" > + <intent + android:targetPackage="com.example.prefs" + android:targetClass="com.example.prefs.SettingsActivity" + android:action="com.example.prefs.PREFS_TWO" /> + </Preference> +</PreferenceScreen> +</pre> + +<p>Karena dukungan untuk {@code <preference-headers>} telah ditambahkan di Android 3.0, sistem akan memanggil +{@link android.preference.PreferenceActivity#onBuildHeaders onBuildHeaders()} di {@link +android.preference.PreferenceActivity} hanya saat berjalan pada Android 3.0 atau yang lebih tinggi. Untuk memuat +file header "lama" ({@code preference_headers_legacy.xml}), Anda harus memeriksa versi Android +dan, jika versi tersebut lebih lama dari Android 3.0 ({@link +android.os.Build.VERSION_CODES#HONEYCOMB}), panggil {@link +android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} untuk +memuat file header lama. Misalnya:</p> + +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + ... + + if (Build.VERSION.SDK_INT < Build.VERSION_CODES.HONEYCOMB) { + // Load the legacy preferences headers + addPreferencesFromResource(R.xml.preference_headers_legacy); + } +} + +// Called only on Honeycomb and later +@Override +public void onBuildHeaders(List<Header> target) { + loadHeadersFromResource(R.xml.preference_headers, target); +} +</pre> + +<p>Satu-satunya hal yang perlu dilakukan adalah menangani {@link android.content.Intent} yang diteruskan ke +aktivitas untuk mengidentifikasi file preferensi yang akan dimuat. Jadi ambillah tindakan intent dan bandingkan dengan +string tindakan yang diketahui yang telah Anda gunakan dalam tag {@code <intent>} XML preferensi:</p> + +<pre> +final static String ACTION_PREFS_ONE = "com.example.prefs.PREFS_ONE"; +... + +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + String action = getIntent().getAction(); + if (action != null && action.equals(ACTION_PREFS_ONE)) { + addPreferencesFromResource(R.xml.preferences); + } + ... + + else if (Build.VERSION.SDK_INT < Build.VERSION_CODES.HONEYCOMB) { + // Load the legacy preferences headers + addPreferencesFromResource(R.xml.preference_headers_legacy); + } +} +</pre> + +<p>Ketahuilah bahwa panggilan berturut-turut ke {@link +android.preference.PreferenceActivity#addPreferencesFromResource addPreferencesFromResource()} akan +menumpuk semua preferensi ke dalam satu daftar, jadi pastikan bahwa ini hanya dipanggil sekali dengan mengikatkan syarat +ke pernyataan else-if.</p> + + + + + +<h2 id="ReadingPrefs">Preferensi Membaca</h2> + +<p>Secara default, semua preferensi aplikasi Anda disimpan ke file yang bisa diakses dari mana saja +di dalam aplikasi dengan memanggil metode statis {@link +android.preference.PreferenceManager#getDefaultSharedPreferences +PreferenceManager.getDefaultSharedPreferences()}. Ini akan mengembalikan objek {@link +android.content.SharedPreferences} berisi semua pasangan nilai-kunci yang terkait +dengan objek {@link android.preference.Preference} yang digunakan di {@link +android.preference.PreferenceActivity} Anda.</p> + +<p>Misalnya, inilah cara membaca salah satu nilai preferensi dari aktivitas lain dalam aplikasi +Anda:</p> + +<pre> +SharedPreferences sharedPref = PreferenceManager.getDefaultSharedPreferences(this); +String syncConnPref = sharedPref.getString(SettingsActivity.KEY_PREF_SYNC_CONN, ""); +</pre> + + + +<h3 id="Listening">Mendengarkan perubahan preferensi</h3> + +<p>Ada beberapa alasan yang membuat Anda perlu mendapatkan pemberitahuan segera setelah pengguna mengubah salah satu +preferensi. Untuk menerima callback saat perubahan terjadi pada salah satu preferensi, +implementasikan antarmuka {@link android.content.SharedPreferences.OnSharedPreferenceChangeListener +SharedPreference.OnSharedPreferenceChangeListener} dan daftarkan listener untuk objek +{@link android.content.SharedPreferences} dengan memanggil {@link +android.content.SharedPreferences#registerOnSharedPreferenceChangeListener +registerOnSharedPreferenceChangeListener()}.</p> + +<p>Antarmuka hanya memiliki satu metode callback, {@link +android.content.SharedPreferences.OnSharedPreferenceChangeListener#onSharedPreferenceChanged +onSharedPreferenceChanged()}, dan mungkin lebih mudah mengimplementasikan antarmuka sebagai bagian dari +aktivitas Anda. Misalnya:</p> + +<pre> +public class SettingsActivity extends PreferenceActivity + implements OnSharedPreferenceChangeListener { + public static final String KEY_PREF_SYNC_CONN = "pref_syncConnectionType"; + ... + + public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, + String key) { + if (key.equals(KEY_PREF_SYNC_CONN)) { + Preference connectionPref = findPreference(key); + // Set summary to be the user-description for the selected value + connectionPref.setSummary(sharedPreferences.getString(key, "")); + } + } +} +</pre> + +<p>Dalam contoh ini, metode akan memeriksa apakah pengaturan yang diubah adalah untuk kunci preferensi yang diketahui. Ini akan +memanggil {@link android.preference.PreferenceActivity#findPreference findPreference()} untuk mendapatkan objek +{@link android.preference.Preference} yang diubah agar bisa memodifikasi rangkuman item +menjadi keterangan pada pilihan pengguna. Ini berarti, bila pengaturan adalah {@link +android.preference.ListPreference} atau pengaturan multipilihan, Anda harus memanggil {@link +android.preference.Preference#setSummary setSummary()} bila pengaturan berubah ke tampilkan +status saat ini (seperti pengaturan Sleep yang ditampilkan dalam gambar 5).</p> + +<p class="note"><strong>Catatan:</strong> Seperti dijelaskan dalam dokumen Desain Android tentang <a href="{@docRoot}design/patterns/settings.html">Pengaturan</a>, kami merekomendasikan Anda untuk memperbarui +rangkuman {@link android.preference.ListPreference} setiap kali pengguna mengubah preferensi untuk +menjelaskan pengaturan saat ini.</p> + +<p>Untuk manajemen daur hidup yang baik di aktivitas, kami merekomendasikan Anda untuk mendaftarkan dan mencabut pendaftaran +{@link android.content.SharedPreferences.OnSharedPreferenceChangeListener} selama callback {@link +android.app.Activity#onResume} dan {@link android.app.Activity#onPause}:</p> + +<pre> +@Override +protected void onResume() { + super.onResume(); + getPreferenceScreen().getSharedPreferences() + .registerOnSharedPreferenceChangeListener(this); +} + +@Override +protected void onPause() { + super.onPause(); + getPreferenceScreen().getSharedPreferences() + .unregisterOnSharedPreferenceChangeListener(this); +} +</pre> + +<p class="caution"><strong>Perhatian:</strong> Bila Anda memanggil {@link +android.content.SharedPreferences#registerOnSharedPreferenceChangeListener +registerOnSharedPreferenceChangeListener()}, pengelola preferensi saat ini tidak akan +menyimpan referensi kuat ke listener. Anda harus menyimpan referensi +kuat bagi listener, atau referensi akan rentan terhadap pengumpulan sampah. Kami +merekomendasikan Anda untuk mempertahankan referensi bagi listener dalam data instance objek +yang akan ada selama Anda memerlukan listener tersebut.</p> + +<p>Misalnya, dalam kode berikut, caller tidak menyimpan referensi ke +listener. Akibatnya, listener akan dikenakan pengumpulan sampah, +dan suatu saat nanti akan gagal:</p> + +<pre> +prefs.registerOnSharedPreferenceChangeListener( + // Bad! The listener is subject to garbage collection! + new SharedPreferences.OnSharedPreferenceChangeListener() { + public void onSharedPreferenceChanged(SharedPreferences prefs, String key) { + // listener implementation + } +}); +</pre> + +<p>Sebagai gantinya, simpan referensi ke listener dalam bidang data instance +objek yang akan ada selama listener dibutuhkan:</p> + +<pre> +SharedPreferences.OnSharedPreferenceChangeListener listener = + new SharedPreferences.OnSharedPreferenceChangeListener() { + public void onSharedPreferenceChanged(SharedPreferences prefs, String key) { + // listener implementation + } +}; +prefs.registerOnSharedPreferenceChangeListener(listener); +</pre> + +<h2 id="NetworkUsage">Mengelola Penggunaan Jaringan</h2> + + +<p>Mulai Android 4.0, aplikasi Settings untuk sistem memungkinkan pengguna melihat seberapa besar +data jaringan yang digunakan aplikasi mereka saat berada di latar depan dan latar belakang. Kemudian pengguna bisa +menonaktifkan penggunaan data latar belakang untuk aplikasi individual. Agar pengguna tidak menonaktifkan akses +aplikasi ke data dari latar belakang, Anda harus menggunakan koneksi data secara efisien dan mengizinkan +pengguna untuk menyaring penggunaan data aplikasi melalui pengaturan aplikasi Anda.<p> + +<p>Misalnya, Anda bisa mengizinkan pengguna untuk mengontrol seberapa sering aplikasi menyinkronkan data, apakah aplikasi +hanya melakukan pengunggahan/pengunduhan bila ada Wi-Fi, apakah aplikasi menggunakan data saat roaming, dll. Dengan +tersedianya kontrol ini bagi pengguna, mereka kemungkinan besar tidak akan menonaktifkan akses aplikasi ke data +saat mendekati batas yang mereka tetapkan dalam Settings pada sistem, karena mereka bisa mengontrol secara tepat +seberapa besar data yang digunakan aplikasi Anda.</p> + +<p>Setelah menambahkan preferensi yang diperlukan dalam {@link android.preference.PreferenceActivity} Anda +untuk mengontrol kebiasaan data aplikasi, Anda harus menambahkan filter intent untuk {@link +android.content.Intent#ACTION_MANAGE_NETWORK_USAGE} dalam file manifes Anda. Misalnya:</p> + +<pre> +<activity android:name="SettingsActivity" ... > + <intent-filter> + <action android:name="android.intent.action.MANAGE_NETWORK_USAGE" /> + <category android:name="android.intent.category.DEFAULT" /> + </intent-filter> +</activity> +</pre> + +<p>Filter intent ini menunjukkan pada sistem bahwa ini adalah aktivitas yang mengontrol penggunaan +data aplikasi Anda. Jadi, saat pengguna memeriksa seberapa banyak data yang digunakan oleh aplikasi dari +aplikasi Settings pada sistem, tombol <em>View application settings</em> akan tersedia dan menjalankan +{@link android.preference.PreferenceActivity} sehingga pengguna bisa menyaring seberapa besar data yang digunakan +aplikasi Anda.</p> + + + + + + + +<h2 id="Custom">Membangun Preferensi Custom</h2> + +<p>Kerangka kerja Android menyertakan berbagai subkelas {@link android.preference.Preference} yang +memungkinkan Anda membangun UI untuk beberapa macam tipe pengaturan. +Akan tetapi, Anda mungkin menemukan pengaturan yang diperlukan bila tidak ada solusi bawaan, seperti +picker nomor atau picker tanggal. Dalam hal demikian, Anda akan perlu membuat preferensi custom dengan memperluas +kelas {@link android.preference.Preference} atau salah satu subkelas lainnya.</p> + +<p>Bila memperluas kelas {@link android.preference.Preference}, ada beberapa hal +penting yang perlu Anda lakukan:</p> + +<ul> + <li>Menetapkan antarmuka pengguna yang akan muncul saat pengguna memilih pengaturan.</li> + <li>Menyimpan nilai pengaturan bila perlu.</li> + <li>Menginisialisasi {@link android.preference.Preference} dengan nilai saat ini (atau default) +bila muncul di tampilan.</li> + <li>Menyediakan nilai default bila diminta oleh sistem.</li> + <li>Jika {@link android.preference.Preference} menyediakan UI sendiri (seperti dialog), simpan +dan pulihkan status untuk menangani perubahan daur hidup (seperti saat pengguna memutar layar).</li> +</ul> + +<p>Bagian berikut menjelaskan cara melakukan setiap tugas ini.</p> + + + +<h3 id="CustomSelected">Menetapkan antarmuka pengguna</h3> + + <p>Jika secara langsung memperluas kelas {@link android.preference.Preference}, Anda perlu mengimplementasikan +{@link android.preference.Preference#onClick()} untuk mendefinisikan tindakan yang terjadi bila pengguna +memilih item tersebut. Akan tetapi, sebagian besar pengaturan custom memperluas {@link android.preference.DialogPreference} untuk +menampilkan dialog, sehingga menyederhanakan prosedur. Bila memperluas {@link +android.preference.DialogPreference}, Anda harus memanggil {@link +android.preference.DialogPreference#setDialogLayoutResource setDialogLayoutResourcs()} selama di +konstruktor kelas untuk menetapkan layout dialog.</p> + + <p>Misalnya, beri ini konstruktor untuk {@link +android.preference.DialogPreference} custom yang mendeklarasikan layout dan menetapkan teks untuk tombol dialog +negatif dan positif default:</p> + +<pre> +public class NumberPickerPreference extends DialogPreference { + public NumberPickerPreference(Context context, AttributeSet attrs) { + super(context, attrs); + + setDialogLayoutResource(R.layout.numberpicker_dialog); + setPositiveButtonText(android.R.string.ok); + setNegativeButtonText(android.R.string.cancel); + + setDialogIcon(null); + } + ... +} +</pre> + + + +<h3 id="CustomSave">Menyimpan nilai pengaturan</h3> + +<p>Anda bisa menyimpan nilai pengaturan kapan saja dengan memanggil salah satu metode {@code persist*()} kelas {@link +android.preference.Preference}, seperti {@link +android.preference.Preference#persistInt persistInt()} jika nilai pengaturan adalah integer atau +{@link android.preference.Preference#persistBoolean persistBoolean()} untuk menyimpan boolean.</p> + +<p class="note"><strong>Catatan:</strong> Setiap {@link android.preference.Preference} hanya bisa menyimpan satu +tipe data, jadi Anda harus menggunakan metode {@code persist*()} yang tepat untuk tipe data yang digunakan +oleh {@link android.preference.Preference} custom Anda.</p> + +<p>Bila Anda memilih untuk mempertahankannya, pengaturan bisa bergantung pada kelas {@link +android.preference.Preference} yang Anda perluas. Jika Anda memperluas {@link +android.preference.DialogPreference}, maka Anda harus mempertahankan nilai hanya jika dialog +tertutup karena hasil positif (pengguna memilih tombol "OK").</p> + +<p>Bila {@link android.preference.DialogPreference} tertutup, sistem akan memanggil metode {@link +android.preference.DialogPreference#onDialogClosed onDialogClosed()}. Metode mencakup argumen +boolean yang menetapkan apakah hasil pengguna "positif"—jika nilainya +<code>true</code>, maka pengguna memilih tombol positif dan Anda harus menyimpan nilai baru. Misalnya: +</p> + +<pre> +@Override +protected void onDialogClosed(boolean positiveResult) { + // When the user selects "OK", persist the new value + if (positiveResult) { + persistInt(mNewValue); + } +} +</pre> + +<p>Dalam contoh ini, <code>mNewValue</code> adalah anggota kelas yang menampung nilai +pengaturan saat ini. Memanggil {@link android.preference.Preference#persistInt persistInt()} akan menyimpan nilai +ke file {@link android.content.SharedPreferences} (secara otomatis menggunakan kunci yang +ditetapkan dalam file XML untuk {@link android.preference.Preference} ini).</p> + + +<h3 id="CustomInitialize">Menginisialisasi nilai saat ini</h3> + +<p>Bila sistem menambahkan {@link android.preference.Preference} Anda ke layar, ia +akan memanggil {@link android.preference.Preference#onSetInitialValue onSetInitialValue()} untuk memberi tahu +Anda apakah pengaturan memiliki nilai yang dipertahankan. Jika tidak ada nilai yang dipertahankan, panggilan ini +akan menyediakan nilai default bagi Anda.</p> + +<p>Metode {@link android.preference.Preference#onSetInitialValue onSetInitialValue()} akan meneruskan +boolean, <code>restorePersistedValue</code>, untuk menunjukkan apakah nilai dipertahankan +untuk pengaturan. Jika <code>true</code>, maka Anda harus mengambil nilai yang dipertahankan dengan memanggil +salah satu metode {@code getPersisted*()} kelas {@link +android.preference.Preference}, seperti {@link +android.preference.Preference#getPersistedInt getPersistedInt()} untuk nilai integer. Anda biasanya +perlu mengambil nilai yang dipertahankan agar bisa memperbarui UI dengan benar untuk merefleksikan +nilai yang tersimpan sebelumnya.</p> + +<p>Jika <code>restorePersistedValue</code> adalah <code>false</code>, maka Anda +harus menggunakan nilai default yang diteruskan dalam argumen kedua.</p> + +<pre> +@Override +protected void onSetInitialValue(boolean restorePersistedValue, Object defaultValue) { + if (restorePersistedValue) { + // Restore existing state + mCurrentValue = this.getPersistedInt(DEFAULT_VALUE); + } else { + // Set default state from the XML attribute + mCurrentValue = (Integer) defaultValue; + persistInt(mCurrentValue); + } +} +</pre> + +<p>Setiap metode {@code getPersisted*()} memerlukan argumen yang menetapkan +nilai default untuk digunakan jika tidak ada nilai yang dipertahankan atau kunci tidak ada. Dalam contoh +di atas, konstanta lokal yang digunakan untuk menetapkan nilai default dalam kasus {@link +android.preference.Preference#getPersistedInt getPersistedInt()} tidak bisa mengembalikan nilai yang dipertahankan.</p> + +<p class="caution"><strong>Perhatian:</strong> Anda <strong>tidak bisa</strong> menggunakan +<code>defaultValue</code> sebagai nilai default dalam metode {@code getPersisted*()}, karena +nilainya selalu nol bila <code>restorePersistedValue</code> adalah <code>true</code>.</p> + + +<h3 id="CustomDefault">Menyediakan nilai default</h3> + +<p>Jika instance kelas {@link android.preference.Preference} Anda menetapkan nilai default +(dengan atribut {@code android:defaultValue}), maka +sistem akan memanggil {@link android.preference.Preference#onGetDefaultValue +onGetDefaultValue()} bila membuat instance objek untuk mengambil nilai. Anda harus mengimplementasikan +metode ini agar sistem bisa menyimpan nilai default dalam {@link +android.content.SharedPreferences}. Misalnya:</p> + +<pre> +@Override +protected Object onGetDefaultValue(TypedArray a, int index) { + return a.getInteger(index, DEFAULT_VALUE); +} +</pre> + +<p>Argumen metode menyediakan semua hal yang Anda perlukan: larik atribut dan posisi +indeks dari {@code android:defaultValue}, yang harus Anda ambil. Alasan Anda harus +mengimplementasikan metode ini untuk mengekstrak nilai default dari atribut adalah karena Anda harus menetapkan +nilai default lokal untuk atribut jika nilai tidak didefinisikan.</p> + + + +<h3 id="CustomSaveState">Menyimpan dan memulihkan status Preferensi</h3> + +<p>Seperti halnya {@link android.view.View} di layout, subkelas {@link android.preference.Preference} +Anda bertanggung jawab menyimpan dan memulihkan statusnya jika aktivitas atau fragmen +di-restart (seperti saat pengguna memutar layar). Untuk menyimpan +dan memulihkan status kelas {@link android.preference.Preference} dengan benar, Anda harus mengimplementasikan +metode callback daur hidup {@link android.preference.Preference#onSaveInstanceState +onSaveInstanceState()} dan {@link +android.preference.Preference#onRestoreInstanceState onRestoreInstanceState()}.</p> + +<p>Status {@link android.preference.Preference} Anda didefinisikan oleh objek yang mengimplementasikan +antarmuka {@link android.os.Parcelable}. Kerangka kerja Android menyediakan objek seperti itu untuk Anda gunakan +sebagai titik mulai untuk mendefinisikan objek status Anda: kelas {@link +android.preference.Preference.BaseSavedState}.</p> + +<p>Untuk mendefinisikan cara kelas {@link android.preference.Preference} menyimpan statusnya, Anda harus +memperluas kelas {@link android.preference.Preference.BaseSavedState}. Anda hanya perlu mengesampingkan + beberapa metode dan mendefinisikan objek {@link android.preference.Preference.BaseSavedState#CREATOR} +.</p> + +<p>Untuk sebagian besar aplikasi, Anda bisa menyalin implementasi berikut dan cukup mengubah baris yang +menangani {@code value} jika subkelas {@link android.preference.Preference} Anda menyimpan tipe +data selain integer.</p> + +<pre> +private static class SavedState extends BaseSavedState { + // Member that holds the setting's value + // Change this data type to match the type saved by your Preference + int value; + + public SavedState(Parcelable superState) { + super(superState); + } + + public SavedState(Parcel source) { + super(source); + // Get the current preference's value + value = source.readInt(); // Change this to read the appropriate data type + } + + @Override + public void writeToParcel(Parcel dest, int flags) { + super.writeToParcel(dest, flags); + // Write the preference's value + dest.writeInt(value); // Change this to write the appropriate data type + } + + // Standard creator object using an instance of this class + public static final Parcelable.Creator<SavedState> CREATOR = + new Parcelable.Creator<SavedState>() { + + public SavedState createFromParcel(Parcel in) { + return new SavedState(in); + } + + public SavedState[] newArray(int size) { + return new SavedState[size]; + } + }; +} +</pre> + +<p>Dengan implementasi {@link android.preference.Preference.BaseSavedState} di atas yang ditambahkan +ke aplikasi Anda (biasanya sebagai subkelas dari subkelas {@link android.preference.Preference}), Anda +nanti perlu mengimplementasikan metode {@link android.preference.Preference#onSaveInstanceState +onSaveInstanceState()} dan {@link +android.preference.Preference#onRestoreInstanceState onRestoreInstanceState()} untuk subkelas +{@link android.preference.Preference} Anda.</p> + +<p>Misalnya:</p> + +<pre> +@Override +protected Parcelable onSaveInstanceState() { + final Parcelable superState = super.onSaveInstanceState(); + // Check whether this Preference is persistent (continually saved) + if (isPersistent()) { + // No need to save instance state since it's persistent, + // use superclass state + return superState; + } + + // Create instance of custom BaseSavedState + final SavedState myState = new SavedState(superState); + // Set the state's value with the class member that holds current + // setting value + myState.value = mNewValue; + return myState; +} + +@Override +protected void onRestoreInstanceState(Parcelable state) { + // Check whether we saved the state in onSaveInstanceState + if (state == null || !state.getClass().equals(SavedState.class)) { + // Didn't save the state, so call superclass + super.onRestoreInstanceState(state); + return; + } + + // Cast state to custom BaseSavedState and pass to superclass + SavedState myState = (SavedState) state; + super.onRestoreInstanceState(myState.getSuperState()); + + // Set this Preference's widget to reflect the restored state + mNumberPicker.setValue(myState.value); +} +</pre> + diff --git a/docs/html-intl/intl/in/guide/topics/ui/ui-events.jd b/docs/html-intl/intl/in/guide/topics/ui/ui-events.jd new file mode 100644 index 000000000000..5068176fccae --- /dev/null +++ b/docs/html-intl/intl/in/guide/topics/ui/ui-events.jd @@ -0,0 +1,291 @@ +page.title=Kejadian Input +parent.title=Antarmuka Pengguna +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>Dalam dokumen ini</h2> + <ol> + <li><a href="#EventListeners">Event Listener</a></li> + <li><a href="#EventHandlers">Event Handler</a></li> + <li><a href="#TouchMode">Mode Sentuh</a></li> + <li><a href="#HandlingFocus">Menangani Fokus</a></li> + </ol> + +</div> +</div> + +<p>Di Android, ada lebih dari satu cara untuk mencegat kejadian dari interaksi pengguna dengan aplikasi Anda. +Saat mempertimbangkan kejadian dalam antarmuka pengguna Anda, pendekatannya adalah menangkap kejadian +dari objek View tertentu yang digunakan pengguna untuk berinteraksi. Kelas View menyediakan sarana untuk melakukannya.</p> + +<p>Dalam berbagai kelas View yang akan digunakan untuk menyusun layout, Anda mungkin melihat beberapa metode callback +publik yang tampak berguna untuk kejadian UI. Metode ini dipanggil oleh kerangka kerja Android ketika masing-masing +tindakan terjadi pada objek itu. Misalnya, bila View (seperti Button/Tombol) disentuh, +metode <code>onTouchEvent()</code> akan dipanggil pada objek itu. Akan tetapi, untuk mencegatnya, Anda harus memperluas +kelas dan mengesampingkan metode itu. Akan tetapi, memperluas setiap objek View +untuk menangani kejadian seperti itu tidaklah praktis. Karena itulah kelas View juga berisi +sekumpulan antarmuka tersarang dengan callback yang jauh lebih mudah didefinisikan. Antarmuka ini, +yang disebut <a href="#EventListeners">event listener</a>, merupakan tiket Anda untuk menangkap interaksi pengguna dengan UI.</p> + +<p>Walaupun Anda akan lebih sering menggunakan event listener ini untuk interaksi pengguna, +mungkin ada saatnya Anda ingin memperluas kelas View, untuk membuat komponen custom. +Mungkin Anda ingin memperluas kelas {@link android.widget.Button} +untuk membuat sesuatu yang lebih menarik. Dalam hal ini, Anda akan dapat mendefinisikan perilaku kejadian default untuk kelas Anda dengan menggunakan +kelas <a href="#EventHandlers">event handler</a>.</p> + + +<h2 id="EventListeners">Event Listener</h2> + +<p>Event listener merupakan antarmuka di kelas {@link android.view.View} yang berisi metode +callback tunggal. Metode ini akan dipanggil oleh kerangka kerja Android bila View yang +telah didaftarkan dengan listener dipicu oleh interaksi pengguna dengan item dalam UI.</p> + +<p>Yang juga disertakan dalam antarmuka event listener adalah metode callback berikut ini:</p> + +<dl> + <dt><code>onClick()</code></dt> + <dd>Dari {@link android.view.View.OnClickListener}. + Ini dipanggil baik saat pengguna menyentuh item + (bila dalam mode sentuh), maupun memfokuskan pada item dengan tombol navigasi atau trackball dan +menekan tombol "enter" yang sesuai atau menekan trackball.</dd> + <dt><code>onLongClick()</code></dt> + <dd>Dari {@link android.view.View.OnLongClickListener}. + Ini dipanggil baik saat pengguna menyentuh dan menahan item (bila dalam mode sentuh), +maupun memfokuskan pada item dengan tombol navigasi atau trackball dan +menekan serta menahan tombol "enter" yang sesuai atau menekan dan menahan trackball (selama satu detik).</dd> + <dt><code>onFocusChange()</code></dt> + <dd>Dari {@link android.view.View.OnFocusChangeListener}. + Ini dipanggil saat pengguna menyusuri ke atau dari item, dengan menggunakan tombol navigasi atau trackball.</dd> + <dt><code>onKey()</code></dt> + <dd>Dari {@link android.view.View.OnKeyListener}. + Ini dipanggil saat pengguna memfokuskan pada item dan menekan atau melepas tombol fisik pada perangkat.</dd> + <dt><code>onTouch()</code></dt> + <dd>Dari {@link android.view.View.OnTouchListener}. + Ini dipanggil saat pengguna melakukan tindakan yang digolongkan sebagai kejadian sentuh, termasuk penekanan, pelepasan, +atau gerak perpindahan pada layar (dalam batasan item itu).</dd> + <dt><code>onCreateContextMenu()</code></dt> + <dd>Dari {@link android.view.View.OnCreateContextMenuListener}. + Ini dipanggil saat Menu Konteks sedang dibuat (akibat "klik lama" terus-menerus). Lihat diskusi +tentang menu konteks di panduan pengembang <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a>. +</dd> +</dl> + +<p>Metode ini satu-satunya yang menempati antarmukanya masing-masing. Untuk mendefinisikan salah satu metode ini +dan menangani kejadian Anda, implementasikan antarmuka tersarang dalam Aktivitas Anda atau definisikan sebagai kelas anonim. +Kemudian, teruskan satu +instance implementasi Anda pada masing-masing metode <code>View.set...Listener()</code>. (Misalnya, panggil +<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> +dan teruskan implementasi {@link android.view.View.OnClickListener OnClickListener} Anda.)</p> + +<p>Contoh di bawah menunjukkan cara mendaftarkan on-click listener untuk Button. </p> + +<pre> +// Create an anonymous implementation of OnClickListener +private OnClickListener mCorkyListener = new OnClickListener() { + public void onClick(View v) { + // do something when the button is clicked + } +}; + +protected void onCreate(Bundle savedValues) { + ... + // Capture our button from layout + Button button = (Button)findViewById(R.id.corky); + // Register the onClick listener with the implementation above + button.setOnClickListener(mCorkyListener); + ... +} +</pre> + +<p>Anda juga akan merasa lebih praktis mengimplementasikan OnClickListener sebagai bagian dari Aktivitas. +Ini akan menghindari beban kelas ekstra dan alokasi objek. Misalnya:</p> +<pre> +public class ExampleActivity extends Activity implements OnClickListener { + protected void onCreate(Bundle savedValues) { + ... + Button button = (Button)findViewById(R.id.corky); + button.setOnClickListener(this); + } + + // Implement the OnClickListener callback + public void onClick(View v) { + // do something when the button is clicked + } + ... +} +</pre> + +<p>Perhatikan bahwa callback <code>onClick()</code> dalam contoh di atas tidak memiliki +nilai hasil, namun beberapa metode event listener lainnya harus mengembalikan boolean. Sebabnya +bergantung pada kejadian. Untuk sebagian yang mengembalikan boolean, ini sebabnya:</p> +<ul> + <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - + Ini mengembalikan boolean untuk menunjukkan apakah Anda telah menggunakan kejadian dan tidak boleh dibawa lebih jauh. + Yaitu, mengembalikan <em>benar</em> untuk menunjukkan apakah Anda telah menangani kejadian dan semestinya berhenti di sini; + mengembalikan <em>salah</em> jika Anda tidak menanganinya dan/atau kejadian semestinya berlanjut ke + on-click listener lainnya.</li> + <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - + Ini mengembalikan boolean untuk menunjukkan apakah Anda telah menggunakan kejadian dan tidak boleh dibawa lebih jauh. + Yaitu, mengembalikan <em>benar</em> untuk menunjukkan apakah Anda telah menangani kejadian dan semestinya berhenti di sini; + mengembalikan <em>salah</em> jika Anda tidak menanganinya dan/atau kejadian semestinya berlanjut ke + on-key listener lainnya.</li> + <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - + Ini mengembalikan boolean untuk menunjukkan apakah listener Anda telah menggunakan kejadian ini. Yang penting adalah +kejadian ini bisa memiliki beberapa tindakan yang saling mengikuti. Jadi, jika Anda mengembalikan <em>salah</em>saat +kejadian tindakan turun diterima, itu menunjukkan bahwa Anda belum menggunakan kejadian itu dan juga +tidak tertarik dengan tindakan berikutnya dari kejadian ini. Karena itu, Anda tidak akan diminta untuk melakukan tindakan + lainnya dalam kejadian, seperti gerakan jari, atau kejadian tindakan naik yang akan terjadi.</li> +</ul> + +<p>Ingatlah bahwa kejadian tombol fisik selalu disampaikan ke View yang sedang difokus. Kejadian ini dikirim mulai dari atas +hierarki View, kemudian turun hingga tujuan yang sesuai. Jika View Anda (atau anak View Anda) +saat ini sedang fokus, maka Anda dapat melihat kejadian berpindah melalui metode.<code>{@link android.view.View#dispatchKeyEvent(KeyEvent) +dispatchKeyEvent()}</code> Sebagai pengganti untuk menangkap kejadian penting melalui View, Anda juga dapat menerima +semua kejadian dalam Aktivitas Anda dengan <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> +dan <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p> + +<p>Selain itu, saat memikirkan tentang input teks aplikasi Anda, ingatlah bahwa banyak perangkat yang hanya memiliki +metode input perangkat lunak. Metode seperti itu tidak harus berbasis tombol; sebagian mungkin menggunakan input suara, tulisan tangan, dan seterusnya. Meskipun +metode input menyajikan antarmuka seperti keyboard, itu umumnya <strong>tidak</strong> memicu keluarga kejadian +<code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code>. Anda sama sekali tidak boleh +membangun UI yang mengharuskan penekanan tombol tertentu dikontrol kecuali jika Anda ingin membatasi aplikasi Anda pada perangkat yang memiliki +keyboard fisik. Khususnya, jangan mengandalkan metode ini untuk memvalidasi input saat pengguna menekan tombol +enter; melainkan, gunakan tindakan seperti {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} untuk menandai +metode input mengenai reaksi yang diharapkan aplikasi Anda, sehingga bisa mengubah UI-nya secara signifikan. Hindari anggapan +tentang bagaimana metode input perangkat lunak seharusnya bekerja dan percayalah bahwa metode akan menyediakan teks yang sudah diformat bagi aplikasi Anda.</p> + +<p class="note"><strong>Catatan:</strong> Android akan memanggil event handler terlebih dahulu kemudian handler +default yang sesuai dari definisi kelas. Karena itu, mengembalikan <em>benar</em> dari event listener ini akan menghentikan +penyebaran kejadian ke event listener lain dan juga akan memblokir callback ke +event handler default di View. Pastikan bahwa Anda ingin mengakhiri kejadian saat mengembalikan <em>true</em>.</p> + + +<h2 id="EventHandlers">Event Handler</h2> + +<p>Jika Anda membuat komponen custom dari View, maka Anda dapat mendefinisikan penggunaan beberapa +metode callback sebagai event handler default. +Dalam dokumen tentang <a href="{@docRoot}guide/topics/ui/custom-components.html">Komponen +Custom</a>, Anda akan melihat penggunaan beberapa callback umum untuk penanganan kejadian, +termasuk:</p> +<ul> + <li><code>{@link android.view.View#onKeyDown}</code> - Dipanggil bila terjadi kejadian tombol baru.</li> + <li><code>{@link android.view.View#onKeyUp}</code> - Dipanggil bila terjadi kejadian tombol naik.</li> + <li><code>{@link android.view.View#onTrackballEvent}</code> - Dipanggil bila terjadi kejadian gerakan trackball.</li> + <li><code>{@link android.view.View#onTouchEvent}</code> - Dipanggil bila terjadi kejadian gerakan layar sentuh.</li> + <li><code>{@link android.view.View#onFocusChanged}</code> - Dipanggil bila View memperoleh atau kehilangan fokus.</li> +</ul> +<p>Ada beberapa metode lain yang harus Anda ketahui, yang bukan bagian dari kelas View, +namun bisa berdampak langsung pada kemampuan Anda menangani kejadian. Jadi, saat mengelola kejadian yang lebih kompleks dalam +layout, pertimbangkanlah metode-metode lain ini:</p> +<ul> + <li><code>{@link android.app.Activity#dispatchTouchEvent(MotionEvent) + Activity.dispatchTouchEvent(MotionEvent)}</code> - Ini memungkinkan {@link + android.app.Activity} Anda mencegat semua kejadian sentuh sebelum dikirim ke jendela.</li> + <li><code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent) + ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - Ini memungkinkan {@link + android.view.ViewGroup} memantau kejadian saat dikirim ke View anak.</li> + <li><code>{@link android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean) + ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Panggil ini + pada View induk untuk menunjukan larangan mencegat kejadian sentuh dengan <code>{@link + android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li> +</ul> + +<h2 id="TouchMode">Mode Sentuh</h2> +<p> +Saat pengguna menyusuri antarmuka pengguna dengan tombol pengarah atau trackball, Anda +perlu memberikan fokus pada item tindakan (seperti tombol) agar pengguna bisa mengetahui apa +yang akan menerima input. Akan tetapi jika perangkat memiliki kemampuan sentuh, dan pengguna +mulai berinteraksi dengan antarmuka dengan menyentuhnya, maka Anda tidak perlu lagi +menyorot item, atau memfokuskan pada View tertentu. Karena itu, ada mode +untuk interaksi yang bernama "mode sentuh". +</p> +<p> +Untuk perangkat berkemampuan sentuh, setelah pengguna menyentuh layar, perangkat +akan masuk ke mode sentuh. Dari sini dan selanjutnya, hanya View dengan +{@link android.view.View#isFocusableInTouchMode} benar yang akan dapat difokus, seperti widget pengedit teks. +View lain yang dapat disentuh, seperti tombol, tidak akan difokus bila disentuh; View ini akan +langsung memicu on-click listener bila ditekan. +</p> +<p> +Kapan saja pengguna menekan tombol pengarah atau menggulir dengan trackball, perangkat akan +keluar dari mode sentuh, dan mencari tampilan untuk difokuskan. Kini pengguna bisa melanjutkan interaksi +dengan antarmuka pengguna tanpa menyentuh layar. +</p> +<p> +Status mode sentuh dipertahankan di seluruh sistem (semua jendela dan aktivitas). +Untuk query status saat ini, Anda bisa memanggil +{@link android.view.View#isInTouchMode} untuk mengetahui apakah perangkat saat ini sedang dalam mode sentuh. +</p> + + +<h2 id="HandlingFocus">Menangani Fokus</h2> + +<p>Kerangka kerja ini akan menangani gerakan fokus rutin sebagai respons input pengguna. +Ini termasuk mengubah fokus saat View dihapus atau disembunyikan, atau saat tersedia View +baru. View menunjukkan kesediaannya untuk mengambil fokus +melalui metode <code>{@link android.view.View#isFocusable()}</code>. Untuk mengubah apakah View bisa mengambil +fokus, panggil <code>{@link android.view.View#setFocusable(boolean) setFocusable()}</code>. Saat dalam mode sentuh, +Anda dapat me-query apakah View memungkinkan fokus dengan <code>{@link android.view.View#isFocusableInTouchMode()}</code>. +Anda bisa mengubahnya dengan <code>{@link android.view.View#setFocusableInTouchMode(boolean) setFocusableInTouchMode()}</code>. +</p> + +<p>Gerakan fokus berdasarkan pada algoritma yang mencari tetangga terdekat dalam +arah yang diberikan. Dalam kasus yang jarang terjadi, algoritma default mungkin +tidak cocok dengan perilaku yang diinginkan pengembang. Dalam situasi ini, Anda bisa memberikan +pengesampingan eksplisit dengan mengikuti atribut XML berikut dalam file layout: +<var>nextFocusDown</var>, <var>nextFocusLeft</var>, <var>nextFocusRight</var>, dan +<var>nextFocusUp</var>. Tambahkan salah satu atribut ini ke View <em>dari</em> mana fokus +meninggalkan. Definisikan nilai atribut untuk menjadi ID View +<em>ke</em> mana fokus harus diberikan. Misalnya:</p> +<pre> +<LinearLayout + android:orientation="vertical" + ... > + <Button android:id="@+id/top" + android:nextFocusUp="@+id/bottom" + ... /> + <Button android:id="@+id/bottom" + android:nextFocusDown="@+id/top" + ... /> +</LinearLayout> +</pre> + +<p>Biasanya, dalam layout vertikal ini, navigasi ke atas dari Button pertama tidak akan membawa ke +mana pun, tidak pula akan menyusuri ke bawah dari Button kedua. Karena sekarang Button atas telah +mendefinisikan Button bawah sebagai <var>nextFocusUp</var> (dan sebaliknya), fokus navigasi akan +silih berganti dari atas ke bawah dan bawah ke atas.</p> + +<p>Jika Anda ingin mendeklarasikan View sebagai dapat difokus dalam UI (bila biasanya tidak dapat difokus), +tambahkan atribut XML <code>android:focusable</code> ke View, dalam deklarasi layout Anda. +Atur nilai <var>true</var>. Anda juga bisa mendeklarasikan View +sebagai dapat difokus saat dalam Mode Sentuh dengan <code>android:focusableInTouchMode</code>.</p> +<p>Untuk meminta View tertentu difokus, panggil <code>{@link android.view.View#requestFocus()}</code>.</p> +<p>Untuk mendengarkan kejadian fokus (diberi tahu bila View menerima atau kehilangan fokus), gunakan +<code>{@link android.view.View.OnFocusChangeListener#onFocusChange(View,boolean) onFocusChange()}</code> +, seperti yang dibahas di bagian <a href="#EventListeners">Event Listener</a>, di atas.</p> + + + +<!-- +<h2 is="EventCycle">Event Cycle</h2> + <p>The basic cycle of a View is as follows:</p> + <ol> + <li>An event comes in and is dispatched to the appropriate View. The View + handles the event and notifies any listeners.</li> + <li>If, in the course of processing the event, the View's bounds may need + to be changed, the View will call {@link android.view.View#requestLayout()}.</li> + <li>Similarly, if in the course of processing the event the View's appearance + may need to be changed, the View will call {@link android.view.View#invalidate()}.</li> + <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called, + the framework will take care of measuring, laying out, and drawing the tree + as appropriate.</li> + </ol> + + <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on + the UI thread when calling any method on any View. + If you are doing work on other threads and want to update the state of a View + from that thread, you should use a {@link android.os.Handler}. + </p> +--> diff --git a/docs/html-intl/intl/in/sdk/index.jd b/docs/html-intl/intl/in/sdk/index.jd new file mode 100644 index 000000000000..f597312849e6 --- /dev/null +++ b/docs/html-intl/intl/in/sdk/index.jd @@ -0,0 +1,487 @@ +page.title=Unduh Android Studio dan SDK Tools +page.tags=sdk, android studio +page.template=sdk +header.hide=1 +page.metaDescription=Unduh Android IDE resmi dan alat pengembang untuk membuat aplikasi bagi ponsel, tablet, perangkat wearable, TV Android dan lainnya. + +studio.version=1.1.0 + +studio.linux_bundle_download=android-studio-ide-135.1740770-linux.zip +studio.linux_bundle_bytes=259336386 +studio.linux_bundle_checksum=e8d166559c50a484f83ebfec6731cc0e3f259208 + +studio.mac_bundle_download=android-studio-ide-135.1740770-mac.dmg +studio.mac_bundle_bytes=261303345 +studio.mac_bundle_checksum=f9745d0fec1eefd498f6160a2d6a1b5247d4cda3 + +studio.win_bundle_exe_download=android-studio-bundle-135.1740770-windows.exe +studio.win_bundle_exe_bytes=856233768 +studio.win_bundle_exe_checksum=7484b9989d2914e1de30995fbaa97a271a514b3f + +studio.win_notools_exe_download=android-studio-ide-135.1740770-windows.exe +studio.win_notools_exe_bytes=242135128 +studio.win_notools_exe_checksum=5ea77661cd2300cea09e8e34f4a2219a0813911f + +studio.win_bundle_download=android-studio-ide-135.1740770-windows.zip +studio.win_bundle_bytes=261667054 +studio.win_bundle_checksum=e903f17cc6a57c7e3d460c4555386e3e65c6b4eb + + + +sdk.linux_download=android-sdk_r24.1.2-linux.tgz +sdk.linux_bytes=168121693 +sdk.linux_checksum=68980e4a26cca0182abb1032abffbb72a1240c51 + +sdk.mac_download=android-sdk_r24.1.2-macosx.zip +sdk.mac_bytes=89151287 +sdk.mac_checksum=00e43ff1557e8cba7da53e4f64f3a34498048256 + +sdk.win_download=android-sdk_r24.1.2-windows.zip +sdk.win_bytes=159778618 +sdk.win_checksum=704f6c874373b98e061fe2e7eb34f9fcb907a341 + +sdk.win_installer=installer_r24.1.2-windows.exe +sdk.win_installer_bytes=111364285 +sdk.win_installer_checksum=e0ec864efa0e7449db2d7ed069c03b1f4d36f0cd + + + + + + +@jd:body + +<style type="text/css"> + .offline {display:none;} + a.download-bundle-button {display:block;} + h2.feature { + padding-top:30px; + margin-top:0; + clear:both; + } + .feature-blurb { + margin:0px; font-size:16px; font-weight:300; + padding:40px 0 0 0; + } + + .landing-button.green { + font-size:16px; + background-color:#90c653; + padding:8px 10px 10px; + margin:0; + width:206px; + text-align:center; + } + + .landing-button.green:hover { + background-color:#85b84f; + } + + .landing-button .small { + font-size: 12px; + font-weight: normal; + line-height: 12px; + display: block; + } + + h1.studio-logo { + width:226px; + height:78px; + display:block; + padding:0; + white-space: nowrap; + text-indent: -10000px; + font-size:0px; + background: url(../images/tools/studio-logo.png); + background-image: -webkit-image-set(url(../images/tools/studio-logo.png) 1x, url(../images/tools/studio-logo_2x.png) 2x); + background-size: 226px 78px; + } + +</style> + + + + + +<div style="position:relative;"> + + +<div class="wrap" id="tos" style="display:none;width:inherit;height:650px"> +<div class="col-13" style="margin:0;"> </div><!-- provides top margin for content --> + +<h1 id="tos-header" style="margin-top:0">Unduh</h1> + +<p class="sdk-terms-intro">Sebelum menginstal Android Studio atau alat SDK mandiri, +Anda harus menyetujui ketentuan dan persyaratan berikut.</p> + +<div class="sdk-terms" onfocus="this.blur()"> +<h2 class="norule">Ketentuan dan Persyaratan</h2> +Ini adalah Perjanjian Lisensi Kit Pengembangan Perangkat Lunak Android + +<h3>1. Pengantar</h3> +1.1 Kit Pengembangan Perangkat Lunak Android (dalam Perjanjian Lisensi ini disebut "SDK" dan secara spesifik termasuk file sistem Android, API paket, dan add-on API Google) diberikan lisensinya kepada Anda sesuai dengan ketentuan Perjanjian Lisensi ini. Perjanjian Lisensi ini merupakan kontrak yang mengikat secara hukum antara Anda dan Google dalam kaitannya dengan penggunaan SDK oleh Anda. + +1.2 "Android" berarti sekumpulan perangkat lunak Android untuk perangkat, seperti yang tersedia di Android Open Source Project, yang ada di URL berikut: http://source.android.com/, yang selalu diperbarui. + +1.3 "Google" berarti Google Inc., perusahaan asal Delaware dengan kantor bisnis utama di 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States. + + +<h3>2. Menerima Perjanjian Lisensi ini</h3> +2.1 Agar bisa menggunakan SDK, Anda terlebih dahulu harus menyetujui Perjanjian Lisensi ini. Anda tidak boleh menggunakan SDK jika tidak menerima Perjanjian Lisensi ini. + +2.2 Dengan mengklik untuk menerima, berarti Anda menyetujui ketentuan Perjanjian Lisensi ini. + +2.3 Anda tidak boleh menggunakan SDK dan tidak boleh menerima Perjanjian Lisensi jika Anda adalah orang yang dilarang menerima SDK berdasarkan hukum Amerika Serikat atau negara lainnya termasuk negara di mana Anda tinggal atau dari mana Anda menggunakan SDK. + +2.4 Jika Anda setuju untuk terikat dengan Perjanjian Lisensi ini atas nama perusahaan Anda atau entitas lainnya, berarti Anda mewakili dan menjamin bahwa Anda memiliki kewenangan hukum penuh untuk mengikat perusahaan Anda atau entitas tesebut pada Perjanjian Lisensi ini. Jika Anda tidak memiliki kewenangan yang disyaratkan, Anda tidak boleh menerima Perjanjian Lisensi atau menggunakan SDK atas nama perusahaan Anda atau entitas lainnya. + + +<h3>3. Lisensi SDK dari Google</h3> +3.1 Sesuai dengan ketentuan Perjanjian Lisensi ini, Google memberi Anda lisensi non-eksklusif yang tidak bisa dialihkan, bebas royalti, bersifat global dan terbatas dalam menggunakan SDK hanya untuk keperluan pengembangan aplikasi yang berjalan di platform Android. + +3.2 Anda setuju bahwa Google atau pihak ketiga lainnya memiliki semua hak, kuasa dan kepentingan hukum dalam dan pada SDK, termasuk Hak Kekayaan Intelektual yang terdapat dalam SDK. "Hak Kekayaan Intelektual" berarti setiap dan semua hak yang berdasarkan pada hukum paten, hukum hak cipta, hukum rahasia dagang, hukum merek dagang, dan setiap dan semua hak kepemilikan lainnya. Google memiliki semua hak yang tidak secara tersurat diberikan kepada Anda. + +3.3 Anda tidak boleh menggunakan SDK untuk tujuan apa pun yang tidak secara tersurat diizinkan dalam Perjanjian Lisensi ini. Kecuali sejauh yang diperlukan oleh lisensi pihak ketiga yang berlaku, Anda tidak boleh: (a) menyalin (kecuali untuk keperluan pencadangan), memodifikasi, mengadaptasi, mendistribusikan kembali, mendekompilasi, merekayasa balik, membongkar atau membuat karya turunan dari SDK atau bagian apa pun dari SDK; atau (b) memuat bagian apa pun dari SDK ke sebuah handset ponsel atau perangkat keras selain komputer pribadi, menggabungkan suatu bagian dari SDK dengan perangkat lunak lain, atau mendistribusikan perangkat lunak atau perangkat yang menggabungkan suatu bagian dari SDK. + +3.4 Anda setuju tidak akan mengambil tindakan apa pun yang dapat menyebabkan atau mengakibatkan fragmentasi Android, termasuk namun tidak terbatas pada distribusi, berpartisipasi dalam pembuatan, atau mempromosikan dengan cara apa pun alat bantu pengembangan perangkat lunak yang berasal dari SDK. + +3.5 Penggunaan, reproduksi dan distribusi komponen SDK yang berlisensi perangkat lunak sumber terbuka diatur semata-mata oleh ketentuan lisensi perangkat lunak sumber terbuka tersebut dan bukan Perjanjian Lisensi ini. + +3.6 Anda setuju bahwa bentuk dan sifat SDK yang disediakan oleh Google dapat berubah tanpa pemberitahuan sebelumnya kepada Anda dan bahwa versi SDK mendatang mungkin tidak kompatibel dengan aplikasi yang dikembangkan di versi SDK sebelumnya. Anda setuju bahwa Google boleh menghentikan (secara permanen atau sementara) penyediaan SDK (atau fitur apa pun dalam SDK) kepada Anda atau pengguna pada umumnya atas kebijakan Google, tanpa pemberitahuan sebelumnya kepada Anda. + +3.7 Perjanjian Lisensi ini tidak memberi Anda hak untuk menggunakan nama dagang, merek dagang, merek layanan, logo, nama domain, atau fitur merek khas Google lainnya. + +3.8 Anda setuju bahwa Anda tidak akan menghapus, mengaburkan, atau mengubah pernyataan hak kepemilikan apa pun (termasuk pemberitahuan hak cipta dan merek dagang) yang terlampir atau termuat dalam SDK. + + +<h3>4. Penggunaan SDK oleh Anda</h3> +4.1 Google setuju bahwa ia tidak memiliki hak, kuasa atau kepentingan dari Anda (atau pemberi lisensi Anda) berdasarkan Perjanjian Lisensi ini dalam atau pada aplikasi perangkat lunak apa pun yang Anda kembangkan menggunakan SDK, termasuk hak kekayaan intelektual yang terdapat dalam aplikasi tersebut. + +4.2 Anda setuju untuk menggunakan SDK dan mengembangkan aplikasi hanya untuk tujuan yang diizinkan oleh (a) Perjanjian Lisensi ini dan (b) hukum yang berlaku, peraturan atau praktik atau panduan yang diterima secara umum di yurisdiksi yang terkait (termasuk hukum mengenai ekspor data atau perangkat lunak ke dan dari Amerika Serikat atau negara lain yang relevan). + +4.3 Anda setuju jika Anda menggunakan SDK untuk mengembangkan aplikasi untuk pengguna umum, Anda akan melindungi privasi dan hak hukum pengguna tersebut. Jika pengguna memberikan nama, kata sandi, atau informasi login atau informasi pribadinya, Anda harus membuat pengguna tersebut menyadari bahwa informasi yang diberikannya akan bisa digunakan oleh aplikasi Anda, dan Anda harus memberikan perlindungan dan pemberitahuan privasi yang memadai secara hukum bagi pengguna tersebut. Jika aplikasi Anda menyimpan informasi pribadi atau sensitif yang diberikan oleh pengguna, aplikasi Anda harus melakukannya dengan aman. Jika pengguna menggunakan aplikasi Anda dengan memberikan informasi Akun Google, aplikasi Anda hanya boleh menggunakan informasi tersebut untuk mengakses Akun Google pengguna saat, dan untuk tujuan terbatas di mana, pengguna tersebut telah memberikan izin kepada Anda untuk melakukannya. + +4.4 Anda setuju bahwa Anda tidak akan terlibat dalam aktivitas apa pun dengan SDK, termasuk pengembangan atau distribusi aplikasi yang mengganggu, mengacaukan, merusak, atau mengakses secara tidak sah server, jaringan atau properti atau layanan pihak ketiga lainnya, termasuk namun tidak terbatas pada, Google atau operator komunikasi seluler lainnya. + +4.5 Anda setuju bertanggung jawab penuh untuk (dan bahwa Google tidak bertanggung jawab tehadap Anda atau pihak ketiga lainnya untuk) data, konten, atau sumber daya apa pun yang Anda buat, kirimkan atau tampilkan melalui Android dan/atau aplikasi untuk Android, dan terhadap konsekuensi tindakan Anda (termasuk kerugian atau kerusakan apa pun yang mungkin dialami Google). + +4.6 Anda setuju bertanggung jawab penuh terhadap (dan bahwa Google tidak bertanggung jawab terhadap Anda atau pihak ketiga lainnya untuk) pelanggaran kewajiban Anda berdasarkan Perjanjian Lisensi ini, kontrak pihak ketiga yang berlaku atau Ketentuan Layanan, atau hukum atau peraturan yang berlaku, dan terhadap konsekuensi (termasuk kerugian atau kerusakan yang mungkin dialami Google atau pihak ketiga lainnya) akibat pelanggaran tersebut. + + +<h3>5. Kredensial Pengembang Anda</h3> +5.1 Anda setuju bertanggung jawab untuk menjaga kerahasiaan semua kredensial pengembang yang mungkin diberikan Google kepada Anda atau yang mungkin Anda pilih sendiri dan bahwa Anda akan bertanggung jawab penuh terhadap semua aplikasi yang dikembangkan dengan kredensial pengembang Anda. + + +<h3>6. Privasi dan Informasi</h3> +6.1 Untuk terus berinovasi dan meningkatkan SDK, Google boleh mengumpulkan statistik penggunaan tertentu dari perangkat lunak termasuk namun tidak terbatas pada identifier unik, alamat IP terkait, nomor versi perangkat lunak, dan informasi yang menjadi tempat penggunaan alat dan/atau layanan dalam SDK dan cara penggunaannya. Sebelum informasi ini dikumpulkan, SDK akan memberi tahu dan meminta persetujuan Anda. Jika Anda tidak memberikan persetujuan, informasi tersebut tidak akan dikumpulkan. + +6.2 Data yang dikumpulkan akan diperiksa secara agregat untuk meningkatkan SDK dan dikelola sesuai dengan Kebijakan Privasi Google. + + +<h3>7. Aplikasi Pihak Ketiga</h3> +7.1 Jika Anda menggunakan SDK untuk menjalankan aplikasi yang dikembangkan oleh pihak ketiga atau yang mengakses data, konten atau sumber daya yang disediakan oleh pihak ketiga, Anda setuju bahwa Google tidak bertanggung jawab terhadap aplikasi, data, konten atau sumber daya tersebut. Anda memahami bahwa semua data, konten atau sumber daya yang mungkin Anda akses melalui aplikasi pihak ketiga merupakan tanggung jawab penuh dari pihak yang menjadi asal data tersebut dan Google tidak bertanggung jawab terhadap kerugian atau kerusakan apa pun yang mungkin Anda alami sebagai akibat menggunakan atau mengakses aplikasi, data, konten, atau sumber daya pihak ketiga tersebut. + +7.2 Anda harus menyadari bahwa data, konten dan sumber daya yang diberikan kepada Anda melalui aplikasi pihak ketiga mungkin dilindungi oleh hak kekayaan intelektual yang dimiliki oleh penyedia (atau oleh orang lain atau perusahaan atas nama mereka). Anda tidak boleh memodifikasi, menyewakan, menyewabelikan, meminjamkan, menjual, mendistribusikan atau membuat karya turunan berdasarkan data, konten, atau sumber daya ini (baik secara keseluruhan atau sebagian) kecuali Anda secara khusus diberikan izin untuk melakukannya oleh pemilik yang bersangkutan. + +7.3 Anda mengakui bahwa penggunaan Anda atas aplikasi, data, konten, atau sumber daya pihak ketiga semacam itu tunduk pada ketentuan terpisah antara Anda dan pihak ketiga yang bersangkutan. Dalam hal ini, Perjanjian Lisensi ini tidak memengaruhi hubungan hukum dengan pihak ketiga tersebut. + + +<h3>8. Menggunakan API Android</h3> +8.1 API Data Google + +8.1.1 Jika Anda menggunakan API (Antarmuka Pemrograman Aplikasi) untuk mengambil data dari Google, Anda mengakui bahwa data tersebut dilindungi hak kekayaan intelektual yang dimiliki Google atau pihak-pihak yang menyediakan data (atau oleh orang lain atau perusahaan atas nama mereka). Penggunaan API oleh Anda tunduk pada Ketentuan Layanan tambahan. Anda tidak boleh memodifikasi, menyewakan, menyewabelikan, meminjamkan, menjual, mendistribusikan atau membuat karya turunan berdasarkan data ini (baik secara keseluruhan atau sebagian) kecuali diizinkan oleh Ketentuan Layanan yang bersangkutan. + +8.1.2 Jika Anda menggunakan API dalam bentuk apa pun untuk mengambil data pengguna dari Google, Anda mengakui dan menyetujui bahwa Anda akan mengambil data hanya dengan persetujuan yang jelas dari pengguna dan hanya bila, dan sebatas keperluan yang diizinkan oleh pengguna tersebut untuk Anda lakukan. + + +<h3>9. Pengakhiran Perjanjian Lisensi ini</h3> +9.1 Perjanjian Lisensi ini akan terus berlaku hingga diakhiri oleh Anda atau Google sebagaimana diatur di bawah ini. + +9.2 Jika Anda ingin mengakhiri Perjanjian Lisensi ini, Anda boleh melakukannya dengan menghentikan penggunaan SDK dan kredensial pengembang yang bersangkutan. + +9.3 Google boleh mengakhiri Perjanjian Lisensi ini dengan Anda kapan saja jika: +(A) Anda telah melanggar suatu ketetapan Perjanjian Lisensi ini; atau +(B) Google diharuskan melakukannya oleh hukum; atau +(C) mitra Google dalam menawarkan bagian SDK (seperti API) tertentu kepada Anda telah mengakhiri hubungannya dengan Google atau tidak lagi menawarkan bagian SDK tertentu kepada Anda; atau +(D) Google memutuskan untuk tidak lagi menyediakan SDK atau bagian SDK tertentu kepada pengguna di negara tempat Anda tinggal atau negara tempat asal Anda menggunakan layanan, atau ketetapan SDK atau layanan SDK tertentu kepada Anda oleh Google yang, menurut kebijakan Google, tidak lagi layak secara komersial. + +9.4 Saat Perjanjian Lisensi ini berakhir, semua hak, kewajiban dan tanggung jawab hukum di mana Anda dan Google telah memperoleh manfaat, tunduk pada (atau yang terkumpul selama berlakunya Perjanjian Lisensi ini) atau yang dinyatakan terus berlaku tanpa batas, tidak akan dipengaruhi oleh penghentian ini, dan ketetapan ayat 14.7 akan terus berlaku terhadap hak, kewajiban dan tanggung jawab tanpa batas. + + +<h3>10. SANGGAHAN JAMINAN</h3> +10.1 ANDA SEPENUHNYA MEMAHAMI DAN MENYETUJUI BAHWA PENGGUNAAN SDK OLEH ANDA MERUPAKAN RISIKO ANDA SENDIRI DAN BAHWA SDK INI DISEDIAKAN "APA ADANYA" DAN "SEBAGAIMANA TERSEDIA" TANPA JAMINAN DALAM BENTUK APA PUN DARI GOOGLE. + +10.2 PENGGUNAAN SDK DAN MATERI APA PUN YANG DIUNDUH ATAU DIPEROLEH MELALUI PENGGUNAAN SDK OLEH ANDA ADALAH ATAS KEHENDAK DAN RISIKO ANDA SENDIRI DAN ANDA BERTANGGUNG JAWAB PENUH TERHADAP KERUSAKAN PADA SISTEM KOMPUTER ATAU PERANGKAT LAIN ATAU HILANGNYA DATA AKIBAT PENGGUNAAN SDK OLEH ANDA. + +10.3 GOOGLE LEBIH LANJUT MENYANGGAH SEMUA JAMINAN DAN PERSYARATAN APA PUN, BAIK TERSURAT MAUPUN TERSIRAT, TERMASUK NAMUN TIDAK TERBATAS PADA JAMINAN TERSIRAT DAN PERSYARATAN MENGENAI DAYA JUAL, KESESUAIAN DENGAN TUJUAN TERTENTU, DAN NON-PELANGGARAN. + + +<h3>11. PEMBATASAN KEWAJIBAN</h3> +11.1 ANDA SEPENUHNYA MEMAHAMI DAN MENYETUJUI BAHWA GOOGLE, ANAK PERUSAHAAN DAN AFILIASINYA, DAN PEMBERI LISENSINYA TIDAK AKAN BERTANGGUNG JAWAB KEPADA ANDA BERDASARKAN TEORI KEWAJIBAN TERHADAP SEGALA KERUGIAN LANGSUNG, TIDAK LANGSUNG, INSIDENTAL, KHUSUS, JANGKA PANJANG ATAU GANTI RUGI YANG DIAKIBATKAN OLEH ANDA, TERMASUK HILANGNYA DATA, WALAUPUN GOOGLE ATAU PERWAKILANNYA TELAH DIBERI TAHU ATAU SEHARUSNYA MENGETAHUI KEMUNGKINAN TIMBULNYA KEHILANGAN TERSEBUT. + + +<h3>12. Penggantian Kerugian</h3> +12.1 Sejauh maksimal yang diizinkan oleh hukum, Anda setuju untuk membela, mengganti kerugian dan melepaskan tanggung jawab Google, afiliasinya beserta direksi, petugas, karyawan dan agennya dari dan terhadap setiap dan semua klaim, tindakan, gugatan, proses hukum, serta setiap dan semua kehilangan, kewajiban, kerusakan, biaya dan pengeluaran (termasuk biaya pengacara yang sewajarnya) yang timbul atau diakibatkan dari (a) penggunaan SDK oleh Anda, (b) aplikasi apa pun yang Anda kembangkan dari SDK yang melanggar hak cipta, merek dagang, rahasia dagang, desain produk, paten atau hak kekayaan intelektual lainnya dari seseorang atau mencemarkan nama baik seseorang atau melanggar hak mereka berkaitan dengan publisitas atau privasi, dan (c) ketidakpatuhan Anda terhadap Perjanjian Lisensi ini. + + +<h3>13. Perubahan Perjanjian Lisensi</h3> +13.1 Google boleh membuat perubahan pada Perjanjian Lisensi saat mendistribusikan versi baru SDK. Saat perubahan tersebut dibuat, Google akan menyediakan versi baru Perjanjian Lisensi di situs web penyediaan SDK. + + +<h3>14. Ketentuan Hukum Umum</h3> +14.1 Perjanjian Lisensi ini merupakan perjanjian hukum antara Anda dan Google dan mengatur penggunaan SDK oleh Anda (tidak termasuk layanan apa pun yang mungkin disediakan Google untuk Anda dalam perjanjian tertulis terpisah), dan sepenuhnya menggantikan perjanjian sebelumnya antara Anda dan Google dalam kaitannya dengan SDK. + +14.2 Anda setuju bahwa jika Google tidak menjalankan atau menerapkan hak atau upaya hukum yang terkandung dalam Perjanjian Lisensi ini (atau bila Google memiliki kewenangan berdasarkan hukum yang berlaku), tindakan ini tidak akan dianggap sebagai pelepasan hak secara resmi oleh Google dan bahwa hak atau upaya hukum tesebut akan tetap bisa digunakan oleh Google. + +14.3 Jika persidangan hukum yang berwenang untuk memutuskan perkara ini menetapkan bahwa ada ketetapan Perjanjian Lisensi ini yang tidak berlaku, maka ketetapan tersebut akan dihapus dari Perjanjian Lisensi tanpa memengaruhi bagian selebihnya dari Perjanjian Lisensi ini. Ketetapan selebihnya dari Perjanjian Lisensi ini akan tetap sah dan berlaku. + +14.4 Anda mengakui dan menyetujui bahwa setiap anggota dari kelompok perusahaan yang diinduki oleh Google akan menjadi pihak ketiga penerima manfaat dari Perjanjian Lisensi ini dan bahwa perusahaan tersebut berhak untuk secara langsung memberlakukan, dan bergantung pada, ketetapan yang dimuat dalam Perjanjian Lisensi ini yang memberikan manfaat (atau hak yang mendukung) kepada mereka. Selain yang telah disebutkan di atas, tidak ada orang atau perusahaan lain yang akan menjadi pihak ketiga penerima manfaat dari Perjanjian Lisensi ini + +14.5 PEMBATASAN EKSPOR. SDK TUNDUK PADA HUKUM DAN PERATURAN EKSPOR AMERIKA SERIKAT. ANDA HARUS MEMATUHI SEMUA HUKUM DAN PERATURAN NASIONAL DAN INTERNASIONAL YANG BERLAKU PADA SDK. HUKUM INI MENYERTAKAN PEMBATASAN ATAS TUJUAN, PENGGUNA AKHIR DAN PENGGUNAAN AKHIR. + +14.6 Hak yang diberikan dalam Perjanjian Lisensi ini tidak boleh diberikan atau dialihkan baik oleh Anda maupun Google tanpa persetujuan tertulis sebelumnya dari pihak lain. Baik Anda maupun Google tidak diizinkan untuk mendelegasikan tanggung jawab atau kewajiban berdasarkan Perjanjian Lisensi ini tanpa persetujuan tertulis sebelumnya dari pihak lain. + +14.7 Perjanjian Lisensi ini, dan hubungan Anda dengan Google berdasarkan Perjanjian Lisensi ini, akan diatur oleh hukum Negara Bagian California tanpa mengindahkan pertentangan ketetapan hukumnya. Anda dan Google setuju untuk tunduk pada yurisdiksi eksklusif pengadilan yang berlokasi di county Santa Clara, California untuk menyelesaikan segala masalah hukum yang timbul dari Perjanjian Lisensi ini. Meski demikian, Anda setuju bahwa Google akan tetap diizinkan untuk mengajukan upaya hukum (atau tipe keringanan hukum setara yang mendesak) dalam yurisdiksi apa pun. + + +<em>13 November 2012</em> +</div> + + + + + +<div id="next-steps" style="display:none;position:absolute;width:inherit"> + <p>Beberapa saat lagi Anda akan dapat membuat aplikasi untuk Android!</p> + <p>Sebentar lagi, Anda akan dialihkan ke + <a id="next-link" href="{@docRoot}sdk/installing/index.html">Menginstal Android SDK</a>.</p> + +</div><!-- end next-steps --> + + + +<div id="sdk-terms-form"> +<p> +<input id="agree" type="checkbox" name="agree" value="1" onclick="onAgreeChecked()" /> +<label id="agreeLabel" for="agree">Saya telah membaca dan menyetujui ketentuan dan persyaratan di atas</label> +</p> +<p><a href="" class="button disabled" id="downloadForRealz" onclick="return onDownloadForRealz(this);"></a></p> +</div> + + +</div><!-- end TOS --> + + + + + + +<div id="landing"> + +<div class="col-13"> </div><!-- provides top margin for content --> + +<img src="{@docRoot}images/tools/studio-hero.png" srcset="{@docRoot}images/tools/studio-hero_2x.png 2x, {@docRoot}images/tools/studio-hero.png 1x" width="760" height="400" alt="" style="margin-bottom:80px" /> + +<div style="color: #fff; width:226px; height:0; overflow:visible; position:absolute; top:40px; left:25px"> + +<h1 class="studio-logo" style="margin:0 0 35px !important">Android Studio</h1> + +<p style="font-size: 16px; color:#bbb; position: absolute;left: 297px; top: 5px; display: block; +width: 400px;text-align: center;">Android IDE resmi</p> + +<ul style="font-size:12px"> +<li>Android Studio IDE</li> +<li>Android SDK Tools</li> +<li>Platform Android 5.0 (Lollipop)</li> +<li>Citra sistem emulator Android 5.0 dengan Google API</li> +</ul> + + +<a class="online landing-button green download-bundle-button" style="margin-top:30px;" href="#Other">Unduh Android Studio</a> + +<!-- this appears when viewing the offline docs --> +<p class="offline"> +Untuk mendapatkan Android Studio atau alat SDK mandiri, kunjungi <a href="http://developer.android.com/sdk/index.html">developer.android.com/sdk/</a> +</p> + +<ul style="margin-top:50px;color:#444"> + <li><a href="#Requirements">Kebutuhan Sistem</a></li> + <li><a href="#Other">Opsi Unduhan Lain</a></li> + <li><a href="{@docRoot}sdk/installing/migrate.html">Beralih ke Android Studio</a></li> + <li><a href="https://docs.google.com/a/google.com/forms/d/1mjsyfzv3HAnDY-_Kfj-3QJKdpuksyMFs9e73CRwmT6Q/viewform" target="_blank">Ikuti Survei</a></li> +</ul> + +</div> + + + + +<h2 class="feature norule" >Editor kode cerdas</h2> + +<div class="col-9" style="margin:0 20px 0 0"> + <img src="{@docRoot}images/tools/studio-hero-code.png" srcset="{@docRoot}images/tools/studio-hero-code_2x.png 2x, {@docRoot}images/tools/studio-hero-code.png 1x" width="520" /> +</div><!-- end col-9 (left column) --> + +<div class="col-4 feature-blurb"> + <p>Yang menjadi inti Android Studio adalah editor kode cerdas dengan kemampuan + penyelesaian kode, optimalisasi, dan analisis kode yang canggih.</p> + <p>Editor kode yang andal ini membantu Anda menjadi pengembang aplikasi Android yang lebih produktif.</p> +</div> + + + + + +<h2 class="feature norule">Template kode dan integrasi GitHub</h2> + +<div class="col-9" style="margin:0 20px 0 0"> + <img src="{@docRoot}images/tools/studio-hero-import.png" srcset="{@docRoot}images/tools/studio-hero-import_2x.png 2x, {@docRoot}images/tools/studio-hero-import.png 1x" width="520" /> +</div><!-- end col-9 (left column) --> + +<div class="col-4 feature-blurb"> + <p>Pemandu proyek yang baru membuat proses memulai proyek baru menjadi jauh lebih mudah.</p> + + <p>Mulai proyek dengan menggunakan kode template untuk pola seperti navigation-drawer dan view-pager, + dan bahkan impor contoh kode Google dari GitHub.</p> +</div> + + + + +<h2 class="feature norule">Pengembangan aplikasi multilayar</h2> + +<div class="col-9" style="margin:0 20px 0 0"> + <img src="{@docRoot}images/tools/studio-hero-screens.png" srcset="{@docRoot}images/tools/studio-hero-screens_2x.png 2x, {@docRoot}images/tools/studio-hero-screens.png 1x" width="520" /> +</div><!-- end col-9 (left column) --> + +<div class="col-4 feature-blurb"> + <p>Buat aplikasi untuk ponsel dan tablet Android, Android Wear, + Android TV, Android Auto dan Google Glass.</p> + <p>Dengan Android Project View yang baru dan dukungan modul di Android Studio, jadi semakin mudah + mengelola proyek dan sumber daya aplikasi. +</div> + + + + +<h2 class="feature norule">Perangkat virtual untuk semua ukuran dan bentuk</h2> + +<div class="col-9" style="margin:0 20px 0 0"> + <img src="{@docRoot}images/tools/studio-hero-avds.png" srcset="{@docRoot}images/tools/studio-hero-avds_2x.png 2x, {@docRoot}images/tools/studio-hero-avds.png 1x" width="520" /> +</div><!-- end col-9 (left column) --> + +<div class="col-4 feature-blurb"> + <p>Android Studio sudah dikonfigurasi dengan citra emulator yang dioptimalkan.</p> + <p>Virtual Device Manager yang telah diperbarui dan dibuat lebih efisien menyediakan + profil perangkat yang sudah didefinisikan untuk perangkat Android umum.</p> +</div> + + + + +<h2 class="feature norule"> +Pembuatan Android berkembang dengan Gradle</h2> + +<div class="col-9" style="margin:0 20px 0 0"> + <img src="{@docRoot}images/tools/studio-hero-gradle.png" srcset="{@docRoot}images/tools/studio-hero-gradle_2x.png 2x, {@docRoot}images/tools/studio-hero-gradle.png 1x" width="520" /> +</div><!-- end col-9 (left column) --> + +<div class="col-4 feature-blurb"> + <p>Buatlah berbagai APK untuk aplikasi Android Anda dengan aneka fitur menggunakan proyek yang sama.</p> + <p>Kelola dependensi aplikasi dengan Maven.</p> + <p>Buat APK dari Android Studio atau baris perintah.</p> +</div> + + + + +<h2 class="feature norule">Selengkapnya tentang Android Studio</h2> +<div style="background:#424242;padding:30px; color:#fff;margin:0 0 15px;"> + +<a class="online landing-button green download-bundle-button" style="margin:0 0 40px 60px;float:right" href="">Unduh Android Studio</a> + + <ul> + <li>Dibuat dengan IntelliJ IDEA Community Edition, JAVA IDE populer karya JetBrains.</li> + <li>Sistem pembuatan berbasis Gradle yang fleksibel.</li> + <li>Buat berbagai generasi APK dan variannya.</li> + <li>Dukungan template bertambah untuk Google Services dan aneka tipe perangkat.</li> + <li>Editor layout yang lengkap dengan dukungan untuk pengeditan tema.</li> + <li>Alat penambal untuk solusi kinerja, kegunaan, kompatibilitas versi, dan masalah lain.</li> + <li>ProGuard dan kemampuan penandatanganan aplikasi.</li> + <li>Dukungan bawaan untuk Google Cloud Platform, mempermudah integrasi Google Cloud + Messaging dan App Engine.</li> + </ul> + +<p style="margin:0"> +Untuk detail selengkapnya tentang fitur-fitur yang tersedia di Android Studio, +bacalah panduan <a href="{@docRoot}tools/studio/index.html">Dasar-Dasar Android Studio</a>.</p> +</div> + + +<p>Jika Anda menggunakan Eclipse dengan ADT, ingatlah bahwa Android Studio sekarang merupakan IDE resmi +untuk Android, jadi Anda harus beralih ke Android Studio untuk menerima semua +pembaruan terakhir IDE. Untuk bantuan dalam memindahkan proyek, +lihat <a href="{@docRoot}sdk/installing/migrate.html">Beralih ke Android +Studio</a>.</p> + + + + + + + +<h2 id="Requirements">Kebutuhan Sistem</h2> + +<h3>Windows</h3> + +<ul> +<li>Microsoft® Windows® 8/7/Vista/2003 (32 atau 64-bit)</li> +<li>RAM minimum 2 GB, RAM yang direkomendasikan 4 GB</li> +<li>Ruang hard-disk 400 MB</li> +<li>Setidaknya 1 GB untuk Android SDK, citra sistem emulator, dan cache</li> +<li>Resolusi layar minimum 1280 x 800</li> +<li>Java Development Kit (JDK) 7 </li> +<li>Opsional untuk emulator akselerasi: Prosesor Intel® dengan dukungan untuk Intel® VT-x, Intel® EM64T +(Intel® 64), dan fungsionalitas Execute Disable (XD) Bit</li> +</ul> + + +<h3>Mac OS X</h3> + +<ul> +<li>Mac® OS X® 10.8.5 atau yang lebih tinggi, hingga 10.9 (Mavericks)</li> +<li>RAM minimum 2 GB, RAM yang direkomendasikan 4 GB</li> +<li>Ruang hard-disk 400 MB</li> +<li>Setidaknya 1 GB untuk Android SDK, citra sistem emulator, dan cache</li> +<li>Resolusi layar minimum 1280 x 800</li> +<li>Java Runtime Environment (JRE) 6</li> +<li>Java Development Kit (JDK) 7</li> +<li>Opsional untuk emulator akselerasi: Prosesor Intel® dengan dukungan untuk Intel® VT-x, Intel® EM64T +(Intel® 64), dan fungsionalitas Execute Disable (XD) Bit</li> +</ul> + +<p>Pada Mac OS, jalankan Android Studio dengan Java Runtime Environment (JRE) 6 untuk rendering +font yang dioptimalkan. Kemudian Anda bisa mengonfigurasi proyek untuk menggunakan Java Development Kit (JDK) 6 atau JDK 7.</p> + + + +<h3>Linux</h3> + +<ul> +<li>Desktop GNOME atau KDE</li> +<li>GNU C Library (glibc) 2.15 atau yang lebih baru</li> +<li>RAM minimum 2 GB, RAM yang direkomendasikan 4 GB</li> +<li>Ruang hard-disk 400 MB</li> +<li>Setidaknya 1 GB untuk Android SDK, citra sistem emulator, dan cache</li> +<li>Resolusi layar minimum 1280 x 800</li> +<li>Oracle® Java Development Kit (JDK) 7 </li> +</ul> +<p>Telah diuji pada Ubuntu® 14.04, Trusty Tahr (distribusi 64-bit yang mampu menjalankan +aplikasi 32-bit).</p> + + + + +<h2 id="Other" style="clear:left">Opsi Unduhan Lain</h2> + +<!-- alternative SDK options follows --> diff --git a/docs/html-intl/intl/in/sdk/installing/adding-packages.jd b/docs/html-intl/intl/in/sdk/installing/adding-packages.jd new file mode 100644 index 000000000000..b98e27b0a34a --- /dev/null +++ b/docs/html-intl/intl/in/sdk/installing/adding-packages.jd @@ -0,0 +1,227 @@ +page.title=Menambahkan Paket SDK + +page.tags=sdk manager +helpoutsWidget=true + +@jd:body + +<style> +ol.large { + margin-left:0; +} +ol.large > li { + list-style-position: inside; + list-style-type:none; + margin:30px 0 0 0; + padding:30px 20px; + background:#eee; +} +ol.large > li:nth-child(odd) { +} +ol.large > li:before { + display:inline; + left:-40px; + float:left; + width:20px; + font-size:20px; + line-height:20px; +} +ol.large > li > h2 { + font-size:20px; + line-height:20px; + padding:0 0 0 20px; + margin:0 0 20px 0; + display:inline-block; + font-weight:normal; +} +ol.large > li:nth-child(1):before { + content:"1. "; +} +ol.large > li:nth-child(2):before { + content:"2. "; +} +ol.large > li:nth-child(3):before { + content:"3. "; +} +ol.large > li:nth-child(4):before { + content:"4. "; +} +ol.large > li:nth-child(5):before { + content:"5. "; +} +ol.large > li:nth-child(6):before { + content:"6. "; +} +</style> + + +<p> +Secara default, Android SDK tidak mencakup segala sesuatu yang Anda perlukan untuk memulai pengembangan. +SDK memisahkan alat, platform, dan komponen lain ke dalam paket yang bisa Anda +unduh bila diperlukan dengan menggunakan +<a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>. +Jadi, sebelum Anda bisa memulai, ada beberapa paket yang harus Anda tambahkan ke Android SDK Anda.</p> + +<p>Untuk mulai menambahkan paket, jalankan Android SDK Manager dengan salah satu cara berikut:</p> +<ul> + <li>Di Android Studio, klik <strong>SDK Manager</strong> +<img src="{@docRoot}images/tools/sdk-manager-studio.png" style="vertical-align:bottom;margin:0;height:17px" /> di toolbar.</li> + <li>Jika Anda tidak menggunakan Android Studio: + <ul> + <li>Windows: Klik ganda file <code>SDK Manager.exe</code> pada akar direktori Android +SDK.</li> + <li>Mac/Linux: Buka sebuah terminal dan arahkan ke direktori <code>tools/</code> di +lokasi instalasi Android SDK, lalu jalankan <code>android sdk</code>.</li> + </ul> + </li> +</ul> + +<p>Bila Anda membuka SDK Manager untuk pertama kali, beberapa paket akan dipilih secara +default. Biarkan dipilih, namun pastikan bahwa Anda mempunyai semua yang Anda perlukan +untuk persiapan dengan mengikuti langkah-langkah ini:</p> + + +<ol class="large"> +<li> + <h2 id="GetTools" class="norule">Dapatkan alat-alat SDK terbaru</h2> + +<img src="/images/sdk_manager_packages.png" alt="" width="350" style="float:right;margin-left:20px" /> + + <p>Setidaknya saat menyiapkan Android SDK, + Anda harus mengunduh platform Android dan alat-alat terbaru:</p> + <ol> + <li>Buka direktori Tools dan pilih: + <ul> + <li><strong>Android SDK Tools</strong></li> + <li><strong>Android SDK Platform-tools</strong></li> + <li><strong>Android SDK Build-tools</strong> (versi tertinggi)</li> + </ul> + </li> + <li>Buka folder Android X.X (versi terbaru) yang pertama dan pilih: + <ul> + <li><strong>SDK Platform</strong></li> + <li>Sebuah citra sistem untuk emulator, seperti <br> + <strong>ARM EABI v7a System Image</strong></li> + </ul> + </li> + </ol> +</li> + +<li> + <h2 id="GetSupportLib" class="norule">Dapatkan pustaka dukungan untuk API tambahan</h2> + + <div class="sidebox"> + <p>Pustaka dukungan diperlukan untuk:</p> + <ul> + <li><a href="{@docRoot}wear/index.html">Android Wear</a></li> + <li><a href="{@docRoot}tv/index.html">Android TV</a></li> + <li><a href="{@docRoot}google/play-services/cast.html">Google Cast</a></li> + </ul> + + <p>Pustaka ini juga menyediakan API populer:</p> + <ul> + <li><a href="{@docRoot}reference/android/support/v4/widget/DrawerLayout.html">Drawer + navigasi</a></li> + <li><a href="{@docRoot}reference/android/support/v4/view/ViewPager.html">Tampilan usap</a></li> + <li><a href="{@docRoot}reference/android/support/v7/app/ActionBar.html">Action-bar + yang kompatibel dengan versi lama</a></li> + </ul> + </div> + + <p><a href="{@docRoot}tools/support-library/features.html">Android Support Library</a> +menyediakan set API tambahan yang kompatibel dengan sebagian besar versi Android.</p> + + <p>Buka direktori <strong>Extras</strong> dan pilih:</p> + <ul> + <li><strong>Android Support Repository</strong></li> + <li><strong>Android Support Library</strong></li> + </ul> + + <p> </p> + <p> </p> + +</li> + + +<li> + <h2 id="GetGoogle" class="norule">Dapatkan Google Play services untuk API yang lebih banyak lagi</h2> + + <div class="sidebox"> + + <p>API Google Play services menyediakan beragam fitur dan layanan untuk aplikasi Android +Anda, misalnya:</p> + <ul> + <li><a href="{@docRoot}google/play-services/plus.html">Autentikasi pengguna</a></li> + <li><a href="{@docRoot}google/play-services/maps.html">Google Maps</a></li> + <li><a href="{@docRoot}google/play-services/cast.html">Google Cast</a></li> + <li><a href="{@docRoot}google/play-services/games.html">Skor dan + papan peringkat permainan</a></li> + <li><a href="{@docRoot}google/play-services/index.html">Dan masih banyak lagi</a></li> + </ul> + </div> + + <p>Untuk mengembangkan aplikasi dengan Google API, Anda memerlukan paket Google Play services:</p> + <p>Buka direktori <strong>Extras</strong> dan pilih:</p> + <ul> + <li><strong>Google Repository</strong></li> + <li><strong>Google Play services</strong></li> + </ul> + + <p class="note"><strong>Catatan:</strong> API Google Play services tidak tersedia pada semua +perangkat berbasis Android, namun tersedia pada semua perangkat dengan Google Play Store. Untuk menggunakan API ini + dalam emulator Android, Anda juga harus menginstal citra sistem <strong>Google API</strong> + dari direktori Android X.X terbaru di SDK Manager.</p> +</li> + + +<li> + <h2 id="Install" class="norule">Instal paket tersebut</h2> + <p>Setelah Anda memilih semua paket yang diinginkan, teruskan untuk menginstal:</p> + <ol> + <li>Klik <strong>Install X packages</strong>.</li> + <li>Di jendela berikutnya, klik ganda masing-masing nama paket di sebelah kiri + untuk menyetujui perjanjian lisensinya masing-masing.</li> + <li>Klik <strong>Install</strong>.</li> + </ol> + <p>Kemajuan pengunduhan diperlihatkan di bagian bawah jendela SDK Manager. + <strong>Jangan keluar dari SDK Manager</strong> karena hal itu akan membatalkan pengunduhan.</p> +</li> + +<li> + <h2 id="Build" class="norule">Bangun sesuatu!</h2> + +<p>Dengan adanya semua paket di atas di Android SDK, maka Anda siap untuk membangun aplikasi +untuk Android. Dengan tersedianya berbagai alat baru dan API lainnya, maka tinggal jalankan SDK Manager +untuk mengunduh paket baru bagi SDK Anda.</p> + +<p>Inilah beberapa opsi cara Anda untuk melanjutkan:</p> + +<div class="cols" style="padding:10px 0"> +<div class="col-4"> +<h3>Persiapkan</h3> +<p>Jika Anda masih baru dengan pengembangan Android, pelajari dasar-dasar aplikasi Android dengan mengikuti +panduan untuk <strong><a href="{@docRoot}training/basics/firstapp/index.html">Membangun Aplikasi Pertama Anda</a></strong>.</p> + +</div> +<div class="col-4 box"> +<h3>Bangun untuk perangkat wearable</h3> +<p>Jika Anda siap memulai pembangunan aplikasi untuk perangkat wearable Android, lihat panduan untuk +<strong><a href="{@docRoot}wear/preview/start.html">Membangun Aplikasi untuk Android Wear</a></strong>.</p> + +</div> +<div class="col-4 box"> +<h3>Gunakan Google API</h3> +<p>Untuk mulai menggunakan Google API, seperti Maps atau +layanan Play Game, lihat panduan untuk +<strong><a href="{@docRoot}google/play-services/setup.html">Mempersiapkan Google Play +Services</a></strong>.</p> + +</div> +</div><!-- end cols --> + + +</li> + +</ol> + + |