lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

Menu

Menu adalah komponen antarmuka pengguna yang lazim dalam banyak tipe aplikasi. Untuk menyediakan pengalaman pengguna yang sudah akrab dan konsisten, Anda harus menggunakan API Menu untuk menyajikan tindakan dan opsi lain dalam aktivitas kepada pengguna.

Mulai dengan Android 3.0 (API level 11), perangkat Android tidak perlu lagi menyediakan tombol Menu tersendiri. Dengan perubahan ini, aplikasi Android harus bermigrasi dari dependensi pada panel menu 6 item biasa, dan sebagai gantinya menyediakan bilah aplikasi untuk menyajikan berbagai tindakan pengguna yang lazim.

Walaupun desain dan pengalaman pengguna untuk sebagian item menu telah berubah, semantik untuk mendefinisikan serangkaian tindakan dan opsi masih berdasarkan pada Menu API. Panduan ini menampilkan cara membuat tiga tipe dasar penyajian menu atau aksi pada semua versi Android:

Menu opsi dan bilah aplikasi
Menu opsi adalah kumpulan item menu utama untuk suatu aktivitas. Inilah tempat Anda harus menempatkan tindakan yang berdampak global pada aplikasi, seperti "Cari", "Tulis email", dan "Setelan".

Lihat bagian tentang Membuat Menu Opsi.

Menu konteks dan mode aksi kontekstual
Menu konteks adalah menu mengambang yang muncul saat pengguna mengeklik lama pada suatu elemen. Menu ini menyediakan tindakan yang memengaruhi materi atau bingkai konteks yang dipilih.

Mode aksi kontekstual menampilkan item aksi yang memengaruhi materi yang dipilih dalam bilah di bagian atas layar dan memungkinkan pengguna memilih beberapa item sekaligus.

Lihat bagian tentang Membuat Menu Kontekstual.

Menu munculan
Menu munculan menampilkan daftar item secara vertikal yang dipasang pada tampilan yang memanggil menu. Ini cocok untuk menyediakan kelebihan tindakan yang terkait dengan materi tertentu atau untuk menyediakan opsi bagi bagian kedua dari suatu perintah. Tindakan di menu munculan tidak boleh memengaruhi secara langsung materi yang bersangkutan—yang diperuntukkan bagi tindakan kontekstual. Melainkan, menu munculan adalah untuk tindakan tambahan yang terkait dengan region materi dalam aktivitas Anda.

Lihat bagian tentang Membuat Menu Munculan.

Mendefinisikan Menu dalam XML

Untuk semua tipe menu, Android menyediakan sebuah format XML standar untuk mendefinisikan item menu. Sebagai ganti membangun menu dalam kode aktivitas, Anda harus mendefinisikan menu dan semua itemnya dalam sumber daya menu XML. Anda kemudian bisa memekarkan sumber daya menu (memuatnya sebagai objek Menu) dalam aktivitas atau fragmen.

Menggunakan sumber daya menu adalah praktik yang baik karena beberapa alasan:

  • Memvisualisasikan struktur menu dalam XML menjadi lebih mudah.
  • Cara ini memisahkan materi untuk menu dari kode perilaku aplikasi Anda.
  • Cara ini memungkinkan Anda membuat konfigurasi menu alternatif untuk berbagai versi platform, ukuran layar, dan konfigurasi lainnya dengan memanfaatkan kerangka kerja sumber daya aplikasi.

Untuk mendefinisikan menu, buatlah sebuah file XML dalam direktori res/menu/ proyek dan bangun menu dengan elemen-elemen berikut:

<menu>
Mendefinisikan Menu, yang merupakan sebuah kontainer untuk item menu. Elemen <menu> harus menjadi simpul akar untuk file dan bisa menampung salah satu atau beberapa dari elemen <item> dan <group>.
<item>
Membuat MenuItem, yang mewakili satu item menu. Elemen ini bisa berisi elemen <menu> tersarang guna untuk membuat submenu.
<group>
Kontainer opsional tak terlihat untuk elemen-elemen <item>. Kontainer ini memungkinkan Anda mengelompokkan item menu untuk berbagi properti seperti status aktif dan visibilitas. Untuk informasi selengkapnya, lihat bagian tentang Membuat Grup Menu.

Berikut ini adalah contoh menu bernama game_menu.xml:

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

Elemen <item> mendukung beberapa atribut yang bisa Anda gunakan untuk mendefinisikan penampilan dan perilaku item. Item menu di atas mencakup atribut berikut:

android:id
ID sumber daya unik bagi item, yang memungkinkan aplikasi mengenali item bila pengguna memilihnya.
android:icon
Acuan ke sumber daya dapat digambar untuk digunakan sebagai ikon item.
android:title
Acuan ke string untuk digunakan sebagai judul item.
android:showAsAction
Menetapkan waktu dan cara item ini muncul sebagai item aksi di bilah aplikasi.

Ini adalah atribut-atribut terpenting yang harus Anda gunakan, namun banyak lagi yang tersedia. Untuk informasi tentang semua atribut yang didukung, lihat dokumen Sumber Daya Menu.

Anda bisa menambahkan submenu ke sebuah item di menu (kecuali submenu) apa saja dengan menambahkan elemen <menu> sebagai anak <item>. Submenu berguna saat aplikasi Anda memiliki banyak fungsi yang bisa ditata ke dalam topik-topik, seperti item dalam sebuah bilah menu aplikasi PC (File, Edit, Lihat, dsb.). Misalnya:

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

Untuk menggunakan menu dalam aktivitas, Anda perlu memekarkan sumber daya menu (mengonversi sumber daya XML menjadi objek yang bisa diprogram) dengan menggunakan MenuInflater.inflate(). Di bagian berikut, Anda akan melihat cara memekarkan menu untuk tiap tipe menu.

Membuat Menu Opsi

Gambar 1. Menu opsi di Browser, pada Android 2.3.

Menu opsi adalah tempat Anda harus menyertakan tindakan dan opsi lain yang relevan dengan konteks aktivitas saat ini, seperti "Telusur", "Tulis email", dan "Setelan".

Tempat item dalam menu opsi muncul di layar bergantung pada versi aplikasi yang Anda kembangkan:

  • Jika Anda mengembangkan aplikasi untuk Android 2.3.x (API level 10) atau yang lebih rendah, materi menu opsi akan muncul di bagian bawah layar bila pengguna menekan tombol Menu, 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 luapan, yang bisa dibuka pengguna dengan memilih More.
  • Jika Anda mengembangkan aplikasi untuk Android 3.0 (API level 11) dan yang lebih tinggi, item menu opsi tersedia dalam bilah aplikasi. Secara default, sistem meletakkan semua item dalam aksi selebihnya, yang bisa ditampilkan pengguna dengan ikon aksi selebihnya di sisi kanan bilah aplikasi (atau dengan menekan tombol Menu perangkat, jika tersedia). Untuk mengaktifkan akses cepat ke tindakan penting, Anda bisa mempromosikan beberapa item agar muncul pada bilah aplikasi dengan menambahkan android:showAsAction="ifRoom" ke elemen-elemen <item> yang bersangkutan (lihat gambar 2).

    Untuk informasi selengkapnya tentang perilaku item aksi dan perilaku bilah aplikasi lainnya, lihat kelas pelatihan Menambahkan Bilah Aplikasi.

Gambar 2. Bilah aplikasi dari aplikasi Honeycomb Gallery, yang menampilkan tab-tab navigasi dan item aksi kamera (plus tombol aksi selebihnya).

Anda bisa mendeklarasikan item untuk menu opsi dari subkelas Activity atau subkelas Fragment. Jika aktivitas maupun fragmen Anda mendeklarasikan item menu opsi, keduanya akan dikombinasikan dalam UI. Item aktivitas akan muncul lebih dahulu, diikuti oleh item setiap fragmen sesuai dengan urutan penambahan setiap fragmen ke aktivitas. Jika perlu, Anda bisa menyusun ulang item menu dengan atribut android:orderInCategory dalam setiap <item> yang perlu Anda pindahkan.

Untuk menetapkan menu opsi suatu aktivitas, ganti onCreateOptionsMenu() (fragmen-fragmen menyediakan callback onCreateOptionsMenu() sendiri). Dalam metode ini , Anda bisa memekarkan sumber daya menu (yang didefinisikan dalam XML) menjadi Menu yang disediakan dalam callback. Misalnya:

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.game_menu, menu);
    return true;
}

Anda juga bisa menambahkan item menu dengan menggunakan add() dan mengambil item dengan findItem() untuk merevisi propertinya dengan MenuItem API.

Jika Anda mengembangkan aplikasi untuk Android 2.3.x dan yang lebih rendah, sistem akan memanggil 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 onCreateOptionsMenu() saat memulai aktivitas, untuk menampilkan item menu pada bilah aplikasi.

Menangani kejadian klik

Bila pengguna memilih item dari menu opsi (termasuk item aksi dalam bilah aplikasi), sistem akan memanggil metode onOptionsItemSelected() aktivitas Anda. Metode ini meneruskan MenuItem yang dipilih. Anda bisa mengidentifikasi item dengan memanggil getItemId(), yang mengembalikan ID unik untuk item menu itu (yang didefinisikan oleh atribut android:id dalam sumber daya menu atau dengan integer yang diberikan ke metode add()). Anda bisa mencocokkan ID ini dengan item menu yang diketahui untuk melakukan aksi yang sesuai. Misalnya:

@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);
    }
}

Bila Anda berhasil menangani sebuah item menu, kembalikan true. Jika tidak menangani item menu, Anda harus memanggil implementasi superkelas onOptionsItemSelected() (implementasi default mengembalikan false).

Jika aktivitas Anda menyertakan fragmen, sistem akan memanggil lebih dahulu onOptionsItemSelected() untuk aktivitas tersebut, kemudian untuk setiap fragmen (sesuai dengan urutan penambahan fragmen) hingga satu fragmen mengembalikan true atau semua fragmen telah dipanggil.

Tip: Android 3.0 menambahkan kemampuan mendefinisikan perilaku on-click untuk item menu dalam XML, dengan menggunakan atribut android:onClick. Nilai atribut harus berupa nama metode yang didefinisikan aktivitas dengan menggunakan menu. Metode harus bersifat publik dan menerima satu parameter MenuItem—bila sistem memanggilnya, metode ini akan meneruskan item menu yang dipilih. Untuk informasi selengkapnya dan contoh, lihat dokumen Sumber Daya Menu.

Tip: Jika aplikasi Anda berisi banyak aktivitas dan sebagian menyediakan menu opsi yang sama, pertimbangkan untuk membuat aktivitas yang tidak mengimplementasikan apa-apa kecuali metode onCreateOptionsMenu() dan 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, ganti onCreateOptionsMenu() dalam aktivitas itu. Panggil super.onCreateOptionsMenu(menu) agar item menu asli dibuat, kemudian tambahkan item menu yang baru dengan menu.add(). Anda juga bisa mengganti perilaku superkelas untuk setiap item menu.

Mengubah item menu saat waktu proses

Setelah sistem memanggil onCreateOptionsMenu(), sistem akan mempertahankan instance Menu yang Anda tempatkan dan tidak akan memanggil onCreateOptionsMenu() lagi kecuali menu dinyatakan tidak valid karena suatu alasan. Akan tetapi, Anda harus menggunakan onCreateOptionsMenu() hanya untuk membuat status menu awal dan tidak untuk membuat perubahan selama daur hidup aktivitas.

Jika Anda ingin mengubah menu opsi berdasarkan kejadian yang terjadi selama daur hidup aktivitas, Anda bisa melakukannya dalam metode onPrepareOptionsMenu(). Metode ini meneruskan objek Menu sebagaimana adanya saat ini sehingga Anda bisa mengubahnya, seperti menambah, membuang, atau menonaktifkan item. (Fragmen juga menyediakan callback onPrepareOptionsMenu().)

Pada Android 2.3.x dan yang lebih rendah, sistem akan memanggil onPrepareOptionsMenu() setiap kali pengguna membuka menu opsi (menekan tombol Menu).

Pada Android 3.0 dan yang lebih tinggi, menu opsi dianggap sebagai selalu terbuka saat item menu ditampilkan pada bilah aplikasi. Bila ada kejadian dan Anda ingin melakukan pembaruan menu, Anda harus memanggil invalidateOptionsMenu() untuk meminta sistem memanggil onPrepareOptionsMenu().

Catatan: Anda tidak boleh mengubah item dalam menu opsi berdasarkan 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 sesuai konteks pada View, gunakan Menu Konteks.

Membuat Menu Kontekstual

Gambar 3. Tangkapan layar menu konteks mengambang (kiri) dan bilah aksi kontekstual (kanan).

Menu kontekstual menawarkan tindakan yang memengaruhi item atau bingkai konteks tertentu dalam UI. Anda bisa menyediakan menu konteks untuk tampilan apa saja, namun menu ini paling sering digunakan untuk item dalam ListView, GridView, atau kumpulan tampilan lainnya yang bisa digunakan pengguna untuk melakukan tindakan langsung pada setiap item.

Ada dua cara menyediakan tindakan kontekstual:

  • Dalam menu konteks mengambang. Menu muncul sebagai daftar item menu mengambang (serupa dengan dialog) bila pengguna mengeklik lama (menekan dan menahan) pada tampilan yang mendeklarasikan dukungan bagi menu konteks. Pengguna bisa melakukan aksi kontekstual pada satu item untuk setiap kalinya.
  • Dalam mode aksi kontekstual. Mode ini adalah implementasi sistem ActionMode yang menampilkan bilah aksi kontekstual di bagian atas layar dengan item aksi yang memengaruhi item(-item) yang dipilih. Bila mode ini aktif, pengguna bisa melakukan aksi pada beberapa item sekaligus (jika aplikasi Anda mengizinkannya).

Catatan: Mode aksi kontekstual tersedia pada Android 3.0 (API level 11) dan yang lebih tinggi dan merupakan teknik yang lebih disukai untuk menampilkan aksi 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.

Membuat menu konteks mengambang

Untuk menyediakan menu konteks mengambang:

  1. Daftarkan View ke menu konteks yang harus dikaitkan dengan memanggil registerForContextMenu() dan teruskan View ke menu itu.

    Jika aktivitas Anda menggunakan ListView atau GridView dan Anda ingin setiap item untuk menyediakan menu konteks yang sama, daftarkan semua item ke menu konteks dengan meneruskan ListView atau GridView ke registerForContextMenu().

  2. Implementasikan metode onCreateContextMenu() dalam Activity atau Fragment.

    Bila tampilan yang terdaftar menerima kejadian klik-lama, sistem akan memanggil metode onCreateContextMenu() Anda. Inilah tempat Anda mendefinisikan item menu, biasanya dengan memekarkan sumber daya menu. Misalnya :

    @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);
    }
    

    MenuInflater memungkinkan Anda untuk memekarkan menu konteks sumber daya menu. Parameter metode callback menyertakan View yang dipilih pengguna dan objek 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.

  3. Implementasikan onContextItemSelected().

    Bila pengguna memilih item menu, sistem akan memanggil metode ini sehingga Anda bisa melakukan aksi yang sesuai. Misalnya:

    @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);
        }
    }
    

    Metode getItemId() melakukan kueri ID untuk item menu yang dipilih, yang harus Anda tetapkan ke setiap item menu dalam XML dengan menggunakan atribut android:id, seperti yang ditampilkan di bagian tentang Mendefinisikan Menu dalam XML.

    Bila Anda berhasil menangani sebuah item menu, kembalikan 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 true atau false dikembalikan. (Implementasi default untuk Activity dan android.app.Fragment mengembalikan false, sehingga Anda harus selalu memanggil superkelas bila tidak ditangani.)

Menggunakan mode aksi kontekstual

Mode aksi kontekstual adalah implementasi sistem ActionMode yang memfokuskan interaksi pengguna pada upaya melakukan aksi kontekstual. Bila seorang pengguna mengaktifkan mode ini dengan memilih item, bilah aksi kontekstual 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 aksi dinonaktifkan dan bilah aksi kontekstual menghilang bila pengguna membatalkan pilihan semua item, menekan tombol BACK, atau memilih aksi Done di sisi kiri bilah aksi.

Catatan: Bilah aksi kontekstual tidak harus terkait dengan bilah aplikasi. Keduanya beroperasi secara independen, walaupun bilah aksi kontekstual secara visual mengambil alih posisi bilah aplikasi.

Untuk tampilan yang menyediakan tindakan kontekstual, Anda biasanya harus memanggil mode aksi kontekstual pada salah satu dari dua kejadian (atau keduanya):

  • Pengguna mengeklik-lama pada tampilan.
  • Pengguna memilih kotak centang atau komponen UI yang serupa dalam tampilan.

Cara aplikasi memanggil mode aksi kontekstual dan mendefinisikan perilaku setiap aksi bergantung pada desain Anda. Pada dasarnya ada dua desain:

  • Untuk tindakan kontekstual pada tampilan arbitrer dan tak didukung.
  • Untuk aksi kontekstual batch atas kelompok item dalam ListView atau GridView (memungkinkan pengguna memilih beberapa item dan melakukan aksi pada semua item itu).

Bagian berikut ini menjelaskan penyiapan yang diperlukan untuk setiap skenario.

Mengaktifkan mode aksi kontekstual untuk tampilan individual

Jika Anda ingin memanggil mode aksi kontekstual hanya bila pengguna memilih tampilan tertentu, Anda harus:

  1. Mengimplementasikan antarmuka ActionMode.Callback. Dalam metode callback-nya, Anda bisa menetapkan tindakan untuk bilah aksi kontekstual, merespons kejadian klik pada item aksi, dan menangani kejadian daur hidup lainnya untuk mode aksi itu.
  2. Memanggil startActionMode() bila Anda ingin menampilkan action-bar (seperti saat pengguna mengeklik-lama pada tampilan).

Misalnya:

  1. Implementasikan antarmuka ActionMode.Callback:
    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;
        }
    };
    

    Perhatikan, kejadian callback ini hampir persis sama dengan callback untuk menu opsi, hanya saja setiap callback ini juga meneruskan objek ActionMode yang terkait dengan kejadian. Anda bisa menggunakan ActionMode API untuk membuat berbagai perubahan pada CAB, seperti merevisi judul dan subjudul dengan setTitle() dan setSubtitle() (berguna untuk menunjukkan jumlah item yang dipilih).

    Juga perhatikan kumpulan contoh di atas menyetel variabel mActionMode ke nol bila mode aksi dimusnahkan. Dalam langkah berikutnya, Anda akan melihat cara variabel diinisialisasi dan kegunaan menyimpan variabel anggota dalam aktivitas atau fragmen.

  2. Panggil startActionMode() untuk mengaktifkan mode aksi kontekstual bila sesuai, seperti saat merespons klik-lama pada View:

    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;
        }
    });
    

    Bila Anda memanggil startActionMode(), sistem akan mengembalikan ActionMode yang dibuat. Dengan menyimpannya dalam variabel anggota, Anda bisa membuat perubahan ke bilah aksi kontekstual sebagai respons terhadap kejadian lainnya. Dalam contoh di atas, ActionMode digunakan untuk memastikan bahwa instance ActionMode tidak dibuat kembali jika sudah aktif, dengan memeriksa apakah anggota bernilai nol sebelum memulai mode aksi.

Mengaktifkan tindakan kontekstual batch dalam ListView atau GridView

Jika Anda memiliki sekumpulan item dalam ListView atau GridView (atau ekstensi AbsListView lainnya) dan ingin memungkinkan pengguna melakukan tindakan batch, Anda harus:

Misalnya:

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 invalidate() request
        return false;
    }
});

Demikian saja. Kini bila pengguna memilih item dengan klik-lama, sistem akan memanggil metode onCreateActionMode() dan menampilkan bilah aksi kontekstual bersama tindakan yang ditetapkan. Saat bilah aksi kontekstual terlihat, pengguna bisa memilih item tambahan.

Dalam beberapa kasus di mana tindakan kontekstual menyediakan item aksi umum, Anda mungkin ingin menambahkan kotak centang atau elemen UI serupa yang memungkinkan pengguna memilih item, karena pengguna mungkin tidak menemukan perilaku klik-lama. Bila pengguna memilih kotak centang itu, Anda bisa memanggil mode aksi kontekstual dengan menyetel item daftar yang bersangkutan ke status diberi tanda centang dengan setItemChecked().

Membuat Menu Munculan

Gambar 4. Menu munculan dalam aplikasi Gmail, dikaitkan ke tombol selebihnya di sudut kanan atas.

PopupMenu adalah menu modal yang dikaitkan pada View. Menu ini muncul di bawah tampilan jangkar jika ada ruang, atau di atas tampilan jika tidak ada. Menu ini berguna untuk:

  • Menyediakan menu bergaya kelebihan (overflow) untuk tindakan yang berkaitan dengan materi tertentu (seperti header email Gmail, yang ditampilkan dalam gambar 4).

    Catatan: Ini tidak sama dengan menu konteks, yang umumnya untuk tindakan yang memengaruhi materi yang dipilih. Untuk tindakan yang memengaruhi materi yang dipilih, gunakan mode aksi kontekstual atau menu konteks mengambang.

  • Menyediakan bagian kedua dari kalimat perintah (seperti tombol bertanda "Tambah" yang menghasilkan menu munculan dengan berbagai opsi "Tambah").
  • Menyediakan daftar tarik-turun serupa dengan Spinner yang tidak mempertahankan pilihan persisten.

Catatan: PopupMenu tersedia dengan API level 11 dan yang lebih tinggi.

Jika Anda mendefinisikan menu dalam XML, berikut ini adalah cara Anda menampilkan menu munculan:

  1. Buat instance PopupMenu bersama konstruktornya, yang mengambil Context dan View aplikasi saat ini yang akan menjadi tempat mengaitkan menu.
  2. Gunakan MenuInflater untuk memekarkan sumber daya menu Anda ke dalam objek Menu yang dikembalikan oleh PopupMenu.getMenu().
  3. Panggil PopupMenu.show().

Misalnya, berikut ini adalah tombol dengan atribut android:onClick yang menampilkan menu munculan:

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

Aktivitas nanti bisa menampilkan menu munculan seperti ini:

public void showPopup(View v) {
    PopupMenu popup = new PopupMenu(this, v);
    MenuInflater inflater = popup.getMenuInflater();
    inflater.inflate(R.menu.actions, popup.getMenu());
    popup.show();
}

Dalam API level 14 dan yang lebih tinggi, Anda bisa mengombinasikan dua baris yang memekarkan menu dengan PopupMenu.inflate().

Menu akan ditutup bila pengguna memilih item atau menyentuh di luar area menu. Anda bisa mendengarkan kejadian tutup dengan menggunakan PopupMenu.OnDismissListener.

Menangani kejadian klik

Untuk melakukan suatu aksi bila pengguna memilih item menu, Anda harus mengimplementasikan antarmuka PopupMenu.OnMenuItemClickListener dan mendaftarkannya pada PopupMenu dengan memanggil setOnMenuItemclickListener(). Bila pengguna memilih item, sistem akan memanggil callback onMenuItemClick() dalam antarmuka Anda.

Misalnya:

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

Membuat Grup Menu

Grup menu adalah sekumpulan item menu yang sama-sama memiliki ciri (trait) tertentu. Dengan grup, Anda bisa:

Anda bisa membuat kelompok dengan menyarangkan elemen-elemen <item> dalam elemen <group> di sumber daya menu atau dengan menetapkan ID kelompok bersama metode add().

Berikut ini adalah contoh sumber daya menu yang berisi sebuah grup:

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

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 android:showAsAction="ifRoom" untuk setiap item, item tersebut akan muncul dalam bilah aksi atau dalam kelebihan aksi.

Menggunakan item menu yang bisa diberi tanda cek

Gambar 5. Tangkapan layar submenu bersama item yang bisa dicentang.

Menu bisa digunakan sebagai antarmuka untuk mengaktifkan dan menonaktifkan opsi, menggunakan kotak centang 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.

Catatan: Item menu dalam Icon Menu (dari menu opsi) tidak bisa menampilkan kotak centang 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.

Anda bisa mendefinisikan perilaku yang bisa dicentang untuk setiap item menu dengan menggunakan atribut android:checkable dalam elemen <item>, atau untuk seluruh kelompok dengan atribut android:checkableBehavior dalam elemen <group>. Misalnya , semua item dalam grup menu ini bisa diberi tanda cek dengan tombol radio:

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

Atribut android:checkableBehavior menerima:

single
Hanya satu item dari grup ini yang bisa diberi tanda cek (tombol radio)
all
Semua item bisa diberi tanda cek (kotak centang)
none
Tidak ada item yang bisa diberi tanda cek

Anda bisa menerapkan status dicentang default pada suatu item dengan menggunakan atribut android:checked dalam elemen <item> dan mengubahnya dalam kode dengan metode setChecked().

Bila item yang bisa diberi tanda cek dipilih, sistem akan memanggil metode callback setiap item yang dipilih (seperti onOptionsItemSelected()). Di sinilah Anda harus mengatur status kotak centang itu, karena kotak centang atau tombol radio tidak mengubah statusnya secara otomatis. Anda bisa melakukan kueri status saat ini suatu item (seperti sebelum pengguna memilihnya) dengan isChecked() kemudian mengatur status diberi tanda cek dengan setChecked(). Misalnya:

@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);
    }
}

Jika Anda tidak mengatur status diberi tanda cek dengan cara ini, maka status item (kotak centang 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.

Catatan: Item menu yang bisa diberi tanda cek dimaksudkan untuk digunakan hanya atas dasar per sesi dan tidak disimpan setelah aplikasi dimusnahkan. Jika Anda memiliki setelan aplikasi yang ingin disimpan untuk pengguna, Anda harus menyimpan data dengan menggunakan Shared Preferences.

Menambahkan Item Menu Berdasarkan Maksud

Kadang-kadang Anda ingin supaya item menu menjalankan aktivitas dengan menggunakan Intent (baik aktivitas berada dalam aplikasi Anda maupun di aplikasi lain). Bila Anda mengetahui maksud yang ingin digunakan dan memiliki item menu tertentu yang harus memulai maksud, Anda bisa mengeksekusi maksud dengan startActivity() selama metode callback saat-item-dipilih sesuai (seperti callback onOptionsItemSelected()).

Akan tetapi, jika Anda tidak yakin apakah perangkat pengguna berisi aplikasi yang menangani maksud, maka menambahkan item menu yang memanggilnya bisa mengakibatkan item menu tidak berfungsi, karena maksud 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 maksud Anda.

Untuk menambahkan item menu berdasarkan aktivitas tersedia yang menerima maksud:

  1. Definisikan maksud dengan kategori CATEGORY_ALTERNATIVE dan/atau CATEGORY_SELECTED_ALTERNATIVE, plus kebutuhan lainnya.
  2. Panggil Menu.addIntentOptions(). Android kemudian akan menelusuri setiap aplikasi yang bisa melakukan maksud dan menambahkannya ke menu Anda.

Jika tidak ada aplikasi terpasang yang memenuhi maksud, maka tidak ada item menu yang ditambahkan.

Catatan: CATEGORY_SELECTED_ALTERNATIVE digunakan untuk menangani elemen yang saat ini dipilih pada layar. Jadi, ini hanya digunakan saat membuat Menu dalam onCreateContextMenu().

Misalnya:

@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;
}

Untuk setiap aktivitas yang diketahui menyediakan filter maksud yang cocok dengan maksud yang didefinisikan, item menu akan ditambahkan, menggunakan nilai dalam filter maksud android:label sebagai judul item menu dan ikon aplikasi sebagai ikon item menu. Metode addIntentOptions() mengembalikan jumlah item menu yang ditambahkan.

Catatan: Bila Anda memanggil addIntentOptions(), ia akan menggantikan setiap dan semua item menu menurut grup menu yang ditetapkan dalam argumen pertama.

Memungkinkan aktivitas Anda ditambahkan ke menu lain

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

Agar bisa dimasukkan dalam menu aplikasi lain, Anda perlu mendefinisikan filter maksud seperti biasa, tetapi pastikan menyertakan nilai-nilai CATEGORY_ALTERNATIVE dan/atau CATEGORY_SELECTED_ALTERNATIVE untuk kategori filter maksud. Misalnya:

<intent-filter label="@string/resize_image">
    ...
    <category android:name="android.intent.category.ALTERNATIVE" />
    <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
    ...
</intent-filter>

Baca selengkapnya tentang penulisan filter maksud dalam dokumen Maksud dan Filter Maksud.

Untuk aplikasi contoh yang menggunakan teknik ini, lihat kode contoh Note Pad.