Share via

Metode ICustomDestinationList::AppendCategory (shobjidl_core.h)

  • Artikel

Menentukan kategori kustom dan tujuan yang dikandungnya, untuk dimasukkan dalam Jump List kustom.

Sintaks

HRESULT AppendCategory(
  [in] LPCWSTR      pszCategory,
  [in] IObjectArray *poa
);

Parameter

[in] pszCategory

Jenis: LPCWSTR

Penunjuk ke string yang berisi nama tampilan kategori kustom. String ini ditampilkan di header kategori di Jump List. String dapat langsung menahan nama tampilan atau dapat menjadi representasi string tidak langsung, seperti "@shell32.dll,-1324", untuk menggunakan string yang disimpan. String tidak langsung memungkinkan header kategori ditampilkan dalam bahasa yang dipilih pengguna.

Catatan Setiap kategori kustom harus memiliki nama yang unik. Nama kategori duplikat akan menyebabkan masalah presentasi di Jump List.
 

[in] poa

Jenis: IObjectArray*

Penunjuk ke IObjectArray yang mewakili satu atau beberapa objek IShellItem yang mewakili tujuan dalam kategori. Beberapa tujuan dalam daftar mungkin juga diwakili oleh objek IShellLink , meskipun lebih jarang.

Catatan Setiap IShellLink yang digunakan di sini harus mendeklarasikan daftar argumen melalui SetArguments. Menambahkan objek IShellLink tanpa argumen ke kategori kustom tidak didukung karena pengguna tidak dapat menyematkan atau melepaskan semat tipe item ini dari Jump List, juga tidak dapat ditambahkan atau dihapus.
 

Menampilkan nilai

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan sebaliknya.

Jika panggilan ke AppendCategory mencoba menambahkan item yang ada di daftar tujuan yang dihapus yang diambil oleh panggilan ke BeginList yang memulai sesi, panggilan ke AppendCategory gagal.

Jika AppendCategory mencoba menambahkan IShellItem yang tidak didaftarkan aplikasi untuk ditangani, panggilan gagal.

AppendCategory dapat gagal jika ada pengaturan privasi Kebijakan Grup atau privasi pengguna yang diaktifkan. Kategori kustom berisi item khusus pengguna berdasarkan penggunaan individual, yang tidak diizinkan di bawah pengaturan privasi tersebut.

Pengaturan privasi Kebijakan Grup atau privasi pengguna tidak akan menyebabkan kegagalan dalam metode ICustomDestinationList lainnya. Tugas tidak spesifik untuk pengguna. AppendKnownCategory tidak akan menghasilkan tampilan kategori Terbaru atau Sering karena tidak akan memiliki data, tetapi panggilan metode tidak akan mengembalikan kode kegagalan.

Dalam kasus kode kegagalan di AppendCategory yang disebabkan oleh pengaturan privasi Kebijakan Grup atau privasi pengguna (E_ACCESSDENIED), aplikasi harus terus memperbarui tugas dan memanggil CommitList.

Jika tidak ada pendaftaran jenis file yang ditemukan untuk aplikasi terkait, AppendCategory mengembalikan 0x80040F03 HRESULT. Ini dapat disebabkan oleh aplikasi yang tidak mendaftarkan jenis file yang coba ditambahkan ke Jump List atau dari masalah dalam pendaftaran, seperti tidak menyediakan AppUserModelID saat aplikasi menggunakan AppUserModelID eksplisit.

Keterangan

Anda harus memanggil BeginList sebelum memanggil metode ini.

Jika aplikasi menyediakan kategori kustom, aplikasi tersebut bertanggung jawab untuk mengisinya. Konten kategori masih harus spesifik pengguna dan berdasarkan riwayat dan tindakan pengguna, tetapi dengan menggunakan kategori kustom, aplikasi dapat menentukan apa yang ingin dilacak dan apa yang ingin diabaikannya. Misalnya, skenario yang berbeda dapat terlibat ketika opsi aplikasi yang berbeda dipilih. Misalnya, program audio mungkin memilih untuk menyertakan hanya album yang baru diputar dan mengabaikan trek individual yang baru diputar. Aplikasi mungkin juga hanya memiliki algoritma pelacakan penggunaan yang disesuaikan dengan penggunaan spesifiknya yang memberikan hasil yang lebih baik daripada algoritma default sistem.

Aplikasi dapat memanggil AppendCategory lebih dari sekali dalam sesi pembuatan daftar untuk menambahkan beberapa kategori kustom. Dalam hal ini, kategori harus dirancang sehingga kontennya saling eksklusif. Setiap kategori kustom harus dibangun di sekitar skenario tertentu sehingga item tidak diduplikasi di antaranya.

Kategori dalam Daftar Lompat kustom, termasuk kategori Terbaru atau Sering yang diketahui, diperlihatkan dalam urutan penambahannya, dengan item terbaru ditambahkan ke akhir daftar. Jika ruang tidak cukup untuk menampilkan semua entri, entri terakhir dalam daftar menghilang dari layar terlebih dahulu. Oleh karena itu, kategori terpenting harus ditambahkan terlebih dahulu untuk memastikan peluang terbaik mereka untuk selalu ditampilkan. Tujuan dalam kategori ditampilkan dalam urutan penyimpanannya di objek IObjectArray yang ditunjukkan oleh poa.

Pengguna mungkin memutuskan untuk menyematkan satu atau beberapa tujuan yang disediakan dalam kategori kustom ke Jump List. Daftar tujuan yang disematkan tidak tersedia untuk aplikasi, tetapi duplikasi dicegah oleh UI sehingga tidak ada tindakan tambahan yang diperlukan dari aplikasi. Secara visual, item yang disematkan berpindah ke bagian Disematkan dari Jump List dan menghilang dari lokasi aslinya.

Panggilan yang berhasil ke AppendCategory tidak menjamin bahwa item tersebut akan ditampilkan. Sejumlah tujuan yang ditambahkan di atas nilai yang ditunjukkan oleh parameter pcMinItems di ICustomDestinationList::BeginList tidak ditampilkan. Kategori Disematkan lebih diprioritaskan daripada semua daftar tujuan lainnya. Daftar Disematkan ditampilkan, lalu ruang yang tersisa dialokasikan ke daftar tujuan lainnya. Dimungkinkan bagi pengguna untuk menyematkan tujuan yang cukup ke Jump List untuk menjaga tujuan lain agar tidak ditampilkan. Faktor lain, seperti resolusi layar yang dikurangi atau ukuran font yang meningkat, juga dapat menyebabkan tujuan yang disediakan aplikasi terpotong dari daftar. Aplikasi tidak memiliki cara untuk memprediksi situasi ini dan tidak diberi tahu ketika terjadi. Aplikasi hanya harus menyadari bahwa kemungkinan ada. Karena pemotongan daftar tujuan atau daftar terjadi dari bawah ke atas, aplikasi harus menempatkan kategori dan tujuan yang paling penting di bagian atas daftar sehingga mereka memiliki peluang terbaik untuk ditampilkan.

Selama sesi yang dimulai dengan BeginList dan berakhir dengan CommitList, Anda dapat memanggil AppendCategory lebih dari sekali. Jika salah satu panggilan tersebut gagal karena upaya untuk menambahkan kategori yang berisi item dalam daftar item yang dihapus, panggilan ke CommitList tidak menghapus daftar item yang dihapus. Agar daftar item yang dihapus dihapus, semua panggilan ke AppendCategory dalam sesi harus berhasil dikembalikan.

Instans IShellLink yang disediakan melalui IObjectArray yang diarahkan oleh poa harus memberikan hal berikut:

Nama tampilan harus diatur melalui properti System.Title (PKEY_Title) item. Properti dapat langsung menahan nama tampilan atau dapat menjadi representasi string tidak langsung, seperti "@shell32.dll,-1324", untuk menggunakan string yang disimpan. String tidak langsung memungkinkan nama item ditampilkan dalam bahasa yang dipilih pengguna.

Secara opsional, bidang deskripsi (SetDescription) dapat diatur untuk menyediakan tipsalat kustom untuk item di Jump List.

Persyaratan

   
Klien minimum yang didukung Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform Windows
Header shobjidl_core.h (termasuk Shobjidl.h)
Pustaka Shell32.lib
DLL Shell32.dll (versi 6.1 atau yang lebih baru)

Lihat juga

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

Ekstensi Bilah Tugas