Metode ITaskbarList3::SetOverlayIcon (shobjidl_core.h)

Menerapkan overlay ke tombol taskbar untuk menunjukkan status aplikasi atau pemberitahuan kepada pengguna.

Sintaks

HRESULT SetOverlayIcon(
  [in] HWND    hwnd,
  [in] HICON   hIcon,
  [in] LPCWSTR pszDescription
);

Parameter

[in] hwnd

Jenis: HWND

Handel jendela yang tombol taskbar terkait menerima overlay. Handel ini harus termasuk dalam proses panggilan yang terkait dengan aplikasi tombol dan harus HWND yang valid atau panggilan diabaikan.

[in] hIcon

Jenis: HICON

Handel ikon yang akan digunakan sebagai overlay. Ini harus menjadi ikon kecil, berukuran 16x16 piksel pada 96 dpi. Jika ikon overlay sudah diterapkan ke tombol taskbar, overlay yang ada akan diganti.

Nilai ini bisa NULL. Bagaimana nilai NULL ditangani bergantung pada apakah tombol taskbar mewakili satu jendela atau sekelompok jendela.

• Jika tombol taskbar mewakili satu jendela, ikon overlay dihapus dari tampilan.
• Jika tombol taskbar mewakili sekelompok jendela dan overlay sebelumnya masih tersedia (diterima lebih awal dari overlay saat ini, tetapi belum dibebaskan oleh nilai NULL ), maka overlay sebelumnya ditampilkan sebagai pengganti overlay saat ini.

Ini adalah tanggung jawab aplikasi panggilan untuk membebaskan hIcon ketika tidak lagi diperlukan. Ini umumnya dapat dilakukan setelah Anda memanggil SetOverlayIcon karena taskbar membuat dan menggunakan salinan ikonnya sendiri.

[in] pszDescription

Jenis: LPCWSTR

Penunjuk ke string yang menyediakan versi teks alt dari informasi yang disampaikan oleh overlay, untuk tujuan aksesibilitas.

Nilai kembali

Jenis: HRESULT

Jika metode ini berhasil, metode ini mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Dalam versi Windows yang lebih lama dari Windows 7, aplikasi sering menggunakan ikon di area pemberitahuan taskbar untuk menampilkan status aplikasi dan pemberitahuan kepada pengguna. Taskbar Windows 7 memungkinkan aplikasi untuk memberikan umpan balik pengguna semacam itu melalui tombol taskbar-nya, memusatkan lebih banyak informasi aplikasi di satu tempat. Overlay ini mirip dengan overlay yang ada yang digunakan untuk ikon pintasan atau pemberitahuan keamanan, ditampilkan di sudut kanan bawah tombol.

Ilustrasi berikut menunjukkan overlay (kotak kecil berwarna hijau yang menunjukkan status pengguna sebagai "Tersedia") yang diterapkan ke tombol taskbar paling kanan.

Overlay ikon berfungsi sebagai pemberitahuan kontekstual status, dan dimaksudkan untuk meniadakan kebutuhan ikon status area pemberitahuan terpisah untuk mengomunikasikan informasi tersebut kepada pengguna. Perancang aplikasi harus memutuskan selama siklus pengembangan metode mana—ikon overlay atau ikon status area pemberitahuan—paling baik melayani aplikasi tersebut. Ikon overlay dimaksudkan untuk menyediakan status atau pemberitahuan penting yang sudah lama ada seperti status jaringan, status messenger, atau email baru. Mereka tidak boleh sering diubah, juga tidak boleh dianimasikan.

Untuk menampilkan ikon overlay, taskbar harus dalam mode ikon besar default. Jika taskbar dikonfigurasi melalui Taskbar dan Start Menu Properties untuk menampilkan ikon kecil, overlay tidak dapat diterapkan dan panggilan ke metode ini diabaikan.

Karena satu overlay diterapkan ke tombol taskbar alih-alih ke gambar mini jendela individual, ini adalah fitur per grup daripada per jendela. Permintaan ikon overlay dapat diterima dari jendela individual dalam grup taskbar, tetapi tidak mengantre. Overlay terakhir yang diterima adalah overlay yang ditampilkan. Jika overlay terakhir yang diterima dihapus, overlay yang diganti dipulihkan selama masih aktif. Sebagai contoh, windows 1, 2, dan 3 diatur, secara berurutan, melapisi A, B, dan C. Karena overlay C diterima terakhir, itu ditampilkan pada tombol taskbar. Jendela 2 memanggil SetOverlayIcon dengan nilai NULL untuk menghapus overlay B. Jendela 3 kemudian melakukan hal yang sama untuk menghapus overlay C. Karena overlay A jendela 1 masih aktif, overlay tersebut kemudian ditampilkan pada tombol taskbar.

Jika Windows Explorer dimatikan secara tak terduga, overlay tidak dipulihkan ketika Windows Explorer dipulihkan. Aplikasi harus menunggu untuk menerima pesan TaskbarButtonCreated yang menunjukkan bahwa Windows Explorer telah dimulai ulang dan tombol taskbar telah dibuat ulang, lalu panggil SetOverlayIcon lagi untuk menerapkan kembali overlay.

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	Explorerframe.lib
DLL	Explorerframe.dll

Lihat juga

ITaskbarList

ITaskbarList2

ITaskbarList3

Ekstensi Taskbar