Bagikan melalui

fungsi Shell_NotifyIconW (shellapi.h)

Mengirim pesan ke area status taskbar.

Sintaksis

BOOL Shell_NotifyIconW(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAW lpData
);

Parameter

[in] dwMessage

Jenis: DWORD

Nilai yang menentukan tindakan yang akan diambil oleh fungsi ini. Ini dapat memiliki salah satu nilai berikut:

NIM_ADD (0x00000000)

0x00000000. Menambahkan ikon ke area status. Ikon diberikan pengidentifikasi dalam struktur NOTIFYICONDATA yang ditujukkan olehlpdata —baik melalui uID atau anggota guidItem. Pengidentifikasi ini digunakan dalam panggilan berikutnya ke Shell_NotifyIcon untuk melakukan tindakan selanjutnya pada ikon.

NIM_MODIFY (0x00000001)

0x00000001. Memodifikasi ikon di area status. NOTIFYICONDATA struktur yang ditunjukkan oleh lpdata menggunakan ID yang awalnya ditetapkan ke ikon ketika ditambahkan ke area pemberitahuan (NIM_ADD) untuk mengidentifikasi ikon yang akan dimodifikasi.

NIM_DELETE (0x00000002)

0x00000002. Menghapus ikon dari area status. NOTIFYICONDATA struktur yang ditujukkan oleh lpdata menggunakan ID yang awalnya ditetapkan ke ikon saat ditambahkan ke area pemberitahuan (NIM_ADD) untuk mengidentifikasi ikon yang akan dihapus.

NIM_SETFOCUS (0x00000003)

0x00000003. Shell32.dll versi 5.0 dan yang lebih baru hanya. Mengembalikan fokus ke area pemberitahuan taskbar. Ikon area pemberitahuan harus menggunakan pesan ini ketika mereka telah menyelesaikan operasi UI mereka. Misalnya, jika ikon menampilkan menu pintasan, tetapi pengguna menekan ESC untuk membatalkannya, gunakan NIM_SETFOCUS untuk mengembalikan fokus ke area pemberitahuan.

NIM_SETVERSION (0x00000004)

0x00000004. Shell32.dll versi 5.0 dan yang lebih baru hanya. Menginstruksikan area pemberitahuan untuk berpura-pura sesuai dengan nomor versi yang ditentukan dalam uVersion anggota struktur yang diarahkan oleh lpdata. Nomor versi menentukan anggota mana yang dikenali.

NIM_SETVERSION harus dipanggil setiap kali ikon area pemberitahuan ditambahkan (NIM_ADD). Ini tidak perlu dipanggil dengan NIM_MODIFY. Pengaturan versi tidak bertahan setelah pengguna keluar.

Untuk detailnya, lihat bagian Keterangan.

[in] lpData

Jenis: PNOTIFYICONDATA

Penunjuk ke struktur NOTIFYICONDATA . Konten struktur tergantung pada nilai dwMessage. Ini dapat menentukan ikon untuk ditambahkan ke area pemberitahuan, menyebabkan ikon tersebut menampilkan pemberitahuan, atau mengidentifikasi ikon untuk memodifikasi atau menghapus.

Mengembalikan nilai

Jenis: BOOL

Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Jika dwMessage diatur ke NIM_SETVERSION, fungsi mengembalikan TRUE jika versi berhasil diubah, atau FALSE jika versi yang diminta tidak didukung.

Komentar

Pada Windows 2000 (Shell32.dll versi 5.0), jika Anda mengatur uVersion anggota struktur NOTIFYICONDATA yang diarahkan oleh lpdata ke NOTIFYICON_VERSION_4 atau lebih tinggi, Shell_NotifyIcon peristiwa mouse dan keyboard ditangani secara berbeda dari pada versi Windows sebelumnya. Perbedaannya termasuk yang berikut ini:

  • Jika pengguna memilih menu pintasan ikon pemberitahuan dengan keyboard, Shell sekarang mengirim pesan WM_CONTEXTMENU kepada aplikasi terkait. Versi sebelumnya mengirim pesan WM_RBUTTONDOWN dan WM_RBUTTONUP.
  • Jika pengguna memilih ikon beri tahu dengan keyboard dan mengaktifkannya dengan tombol SPACEBAR atau ENTER, Shell versi 5.0 mengirimkan aplikasi terkait pemberitahuan NIN_KEYSELECT. Versi sebelumnya mengirim pesan WM_RBUTTONDOWN dan WM_RBUTTONUP.
  • Jika pengguna memilih ikon beri tahu dengan mouse dan mengaktifkannya dengan tombol ENTER, Shell sekarang mengirim aplikasi terkait pemberitahuan NIN_SELECT. Versi sebelumnya mengirim pesan WM_RBUTTONDOWN dan WM_RBUTTONUP.
Pada Windows XP (Shell32.dll versi 6.0), jika pengguna melewati penunjuk mouse di atas ikon tempat pemberitahuan balon dikaitkan, Shell mengirim pesan berikut:
  • NIN_BALLOONSHOW. Dikirim ketika balon ditampilkan (balon diantrekan).
  • NIN_BALLOONHIDE. Dikirim ketika balon menghilang. Misalnya, saat ikon dihapus. Pesan ini tidak dikirim jika balon diberhentikan karena waktu habis atau jika pengguna mengklik mouse.

    Pada Windows 7, NIN_BALLOONHIDE juga dikirim ketika pemberitahuan dengan set bendera NIIF_RESPECT_QUIET_TIME mencoba ditampilkan selama waktu tenang (jam pertama pengguna di komputer baru). Dalam hal ini, balon tidak pernah ditampilkan sama sekali.

  • NIN_BALLOONTIMEOUT. Dikirim ketika balon diberhentikan karena waktu habis.
  • NIN_BALLOONUSERCLICK. Dikirim ketika balon diberhentikan karena pengguna mengklik mouse.
Selain pesan tersebut, pada Windows Vista (Shell32.dll versi 6.0.6), jika pengguna meneruskan penunjuk mouse ke ikon tempat pemberitahuan balon dikaitkan, Windows Vista Shell juga menambahkan pesan berikut:
  • NIN_POPUPOPEN. Dikirim saat pengguna mengarahkan kursor ke ikon untuk menunjukkan bahwa UI pop-up yang lebih kaya harus digunakan sebagai pengganti tipsalat tekstual standar.
  • NIN_POPUPCLOSE. Dikirim saat kursor tidak lagi mengarahkan kursor ke ikon untuk menunjukkan bahwa UI pop-up kaya harus ditutup.
Terlepas dari versi sistem operasi, Anda dapat memilih cara shell harus berperilaku dengan memanggil Shell_NotifyIcon dengan dwMessage diatur ke NIM_SETVERSION. Atur uVersion anggota struktur NOTIFYICONDATA yang ditunjukkan oleh lpdata untuk menunjukkan apakah Anda menginginkan perilaku Windows 2000, Windows Vista, atau pra-versi 5.0 (Windows 95).
Catatan Pesan yang dibahas di atas bukan pesan Windows konvensional. Mereka dikirim sebagai nilai lParam pesan yang ditentukan aplikasi yang ditentukan dalam uCallbackMessage anggota NOTIFYI Struktur CONDATA yang diarahkan olehlpdata , ketika Shell_NotifyIcon dipanggil dengan bendera NIM_ADD diatur dalam dwMessage.
 
Pada Windows XP Service Pack 2 (SP2), ikon kustom dapat ditampilkan di balon pemberitahuan. Ini memungkinkan proses panggilan untuk menyesuaikan pemberitahuan di luar opsi info, peringatan, dan kesalahan yang tersedia sebelumnya, dan membedakannya dari jenis pemberitahuan lain untuk pengguna.
 
Pada Windows 10, pesan balon ditampilkan sebagai pemberitahuan banner, yang kemudian tetap berada di Pusat Pemberitahuan hingga diberhentikan. Pada Windows 11, perilaku pemberitahuan banner lebih dekat mengikuti perilaku warisan dalam membuatnya sementara. Ketika waktu pemberitahuan bannner habis atau dihentikan, pemberitahuan tersebut tidak akan ditampilkan di Pusat Pemberitahuan.
 

Nota

Header shellapi.h mendefinisikan Shell_NotifyIcon sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosektor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows XP [hanya aplikasi desktop]
server minimum yang didukung Windows 2000 Server [hanya aplikasi desktop]
Platform Target Windows
Header shellapi.h
Pustaka Shell32.lib
DLL Shell32.dll (versi 4.0 atau yang lebih baru)
set API ext-ms-win-shell-shell32-l1-2-1 (diperkenalkan di Windows 10, versi 10.0.10240)

Lihat juga

Pemberitahuan dan Area Pemberitahuan

  • Last updated on