Metode ICustomDestinationList::AppendKnownCategory (shobjidl_core.h)

Artikel
03/04/2024

Menentukan bahwa kategori Sering atau Terbaru harus disertakan dalam Jump List kustom.

Sintaks

HRESULT AppendKnownCategory(
  [in] KNOWNDESTCATEGORY category
);

Parameter

[in] category

Jenis: KNOWNDESTCATEGORY

Salah satu nilai berikut yang menunjukkan kategori mana yang diketahui untuk ditambahkan ke daftar:

KDC_FREQUENT (1)

0x1. Tambahkan kategori Sering .

KDC_RECENT (2)

0x2. Tambahkan kategori Terbaru .

Nilai kembali

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan sebaliknya.

Jika ada pengaturan privasi Kebijakan Grup atau privasi pengguna, itu dapat memengaruhi hasil metode ini. Kategori yang berisi item khusus pengguna berdasarkan penggunaan individual tidak diizinkan di bawah pengaturan privasi tersebut. Karena hal ini, kategori Terbaru atau Sering ditambahkan melalui metode ini tidak akan memiliki data, dan kategori tanpa data tidak ditampilkan. Namun, dalam situasi itu, panggilan metode ini tidak akan menghasilkan kode kegagalan.

Keterangan

Anda harus memanggil ICustomDestinationList::BeginList sebelum Anda memanggil metode ini.

Kategori Terbaru ditampilkan dalam Daftar Lompat default, tetapi untuk menampilkannya dalam Daftar Lompat kustom bersama dengan kategori kustom, Anda harus secara eksplisit memintanya melalui metode ini.

Dengan AppendCategory dan AppendKnownCategory, Jump List kustom harus dirancang untuk menghindari item apa pun yang muncul di lebih dari satu kategori. Jika dua kategori hanyalah tampilan yang berbeda pada data yang sama, salah satu kategori tersebut harus dihapus karena menggunakan ruang Jump List tanpa berkontribusi pada kenyamanan pengguna. Duplikat tidak disembunyikan oleh sistem kecuali dalam kasus tujuan yang disematkan, dalam hal ini tujuan ditampilkan dalam kategori Disematkan dan tersembunyi di semua yang lain.

Kategori Sering dan Terbaru kemungkinan berisi tingkat tumpang tindih dan oleh karena itu Anda tidak boleh menambahkan kedua kategori ke satu Jump List. Manakah dari keduanya yang terbaik untuk aplikasi Anda tergantung pada sifatnya. Aplikasi yang menghasilkan file, seperti Microsoft Word atau Microsoft Paint, harus menggunakan kategori Terbaru karena pengguna kemungkinan besar ingin kembali ke file yang baru saja mereka kerjakan. Aplikasi yang lebih banyak digunakan untuk menjelajah atau memutar data yang dibuat di tempat lain harus menggunakan kategori Sering karena pengguna lebih cenderung mengakses jumlah item yang lebih besar, banyak dari mereka hanya sekali. Dengan kata lain, jika aplikasi Anda kemungkinan besar akan mengakses sejumlah besar item hanya beberapa kali masing-masing, yang berkontribusi kebisingan pada set item yang lebih kecil yang ingin diakses pengguna berkali-kali, maka Frequent adalah pilihan terbaik. Jika aplikasi Anda lebih cenderung mengakses sejumlah kecil item yang lebih baru sebagian besar waktu, maka Anda harus memilih Terbaru.

Kategori dalam Daftar Lompat kustom, termasuk kategori Terbaru atau Sering yang diketahui, diperlihatkan dalam urutan ditambahkan, dengan kategori yang terakhir ditambahkan di bagian bawah daftar.

Sejumlah tujuan yang ditambahkan di atas nilai yang ditunjukkan oleh parameter pcMinItems di ICustomDestinationList::BeginList tidak ditampilkan.

Kategori kosong tidak ditampilkan.

Konten kategori Sering dan Terbaru dihitung untuk setiap aplikasi yang menggunakan SHAddToRecentDocs secara langsung. Dalam beberapa kasus tindakan pengguna, seperti membuka file melalui Windows Explorer atau menggunakan kotak dialog file umum untuk membuka, menyimpan, atau membuat file, Shell memanggil SHAddToRecentDocs atas nama aplikasi dan panggilan tersebut juga dipertimbangkan dalam statistik penggunaan. Shell juga memanggil SHAddToRecentDocs atas nama aplikasi ketika tujuan diluncurkan dari Jump List-nya. Namun, adalah praktik yang baik bagi aplikasi untuk secara eksplisit memanggil SHAddToRecentDocs itu sendiri bahkan jika diharapkan bahwa Shell akan melakukan panggilan. Ini menjamin bahwa penggunaan dicatat, dan algoritma untuk melacak penggunaan terbaru atau yang sering akan benar untuk setiap panggilan duplikat.

Persyaratan

Persyaratan	Nilai
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)