| 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> |
| |