Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Berisi informasi yang diperlukan sistem untuk menampilkan pemberitahuan di area pemberitahuan. Digunakan oleh Shell_NotifyIcon.
Sintaksis
typedef struct _NOTIFYICONDATAW {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
WCHAR szTip[64];
#else
WCHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
WCHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
WCHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAW, *PNOTIFYICONDATAW;
Anggota
cbSize
Jenis: DWORD
Ukuran struktur ini, dalam byte.
hWnd
Jenis: HWND
Handel ke jendela yang menerima pemberitahuan yang terkait dengan ikon di area pemberitahuan.
uID
Jenis: UINT
Pengidentifikasi ikon taskbar yang ditentukan aplikasi. Shell menggunakan (
uFlags
Jenis: UINT
Bendera yang menunjukkan anggota struktur lain mana yang berisi data yang valid atau memberikan informasi tambahan ke tipsalat tentang cara menampilkannya. Anggota ini bisa menjadi kombinasi dari nilai berikut:
NIF_MESSAGE (0x00000001)
0x00000001. Anggota
NIF_ICON (0x00000002)
0x00000002. Anggota
NIF_TIP (0x00000004)
0x00000004. Anggota szTip
NIF_STATE (0x00000008)
0x00000008. dwState dan dwStateMask anggota valid.
NIF_INFO (0x00000010)
0x00000010. Menampilkan pemberitahuan balon.
szInfo, szInfoTitle, dwInfoFlags, dan anggota uTimeout valid. Perhatikan bahwa
- Untuk menampilkan pemberitahuan balon, tentukan NIF_INFO dan berikan teks dalam szInfo.
- Untuk menghapus pemberitahuan balon, tentukan NIF_INFO dan berikan string kosong melalui szInfo.
- Untuk menambahkan ikon area pemberitahuan tanpa menampilkan pemberitahuan, jangan atur bendera NIF_INFO.
NIF_GUID (0x00000020)
0x00000020.
Windows 7 dan yang lebih baru : guidItemvalid. - Windows Vista dansebelumnya: Dicadangkan.
NIF_REALTIME (0x00000040)
0x00000040. Windows Vista dan yang lebih baru. Jika pemberitahuan balon tidak dapat segera ditampilkan, buang. Gunakan bendera ini untuk pemberitahuan yang mewakili informasi real-time yang tidak berarti atau menyesatkan jika ditampilkan di lain waktu. Misalnya, pesan yang menyatakan "Telepon Anda berdering." NIF_REALTIME bermakna hanya jika dikombinasikan dengan bendera NIF_INFO.
NIF_SHOWTIP (0x00000080)
0x00000080. Windows Vista dan yang lebih baru. Gunakan tipsalat standar. Biasanya, ketika uVersion diatur ke NOTIFYICON_VERSION_4, tipsalat standar ditekan dan dapat digantikan oleh UI pop-up yang digambar aplikasi. Jika aplikasi ingin menampilkan tipsalat standar dengan NOTIFYICON_VERSION_4, aplikasi dapat menentukan NIF_SHOWTIP untuk menunjukkan tipsalat standar harus tetap ditampilkan.
uCallbackMessage
Jenis: UINT
Pengidentifikasi pesan yang ditentukan aplikasi. Sistem menggunakan pengidentifikasi ini untuk mengirim pesan pemberitahuan ke jendela yang diidentifikasi dalam hWnd. Pesan pemberitahuan ini dikirim ketika peristiwa mouse atau hover terjadi di persegi panjang batas ikon, ketika ikon dipilih atau diaktifkan dengan keyboard, atau ketika tindakan tersebut terjadi di pemberitahuan balon.
Ketika anggota
Ketika anggota uVersion
-
LOWORD(lParam) berisi peristiwa pemberitahuan, seperti NIN_BALLOONSHOW, NIN_POPUPOPEN, atau WM_CONTEXTMENU. - HIWORD(lParam) berisi ID ikon. ID ikon dibatasi untuk panjang 16 bit.
- GET_X_LPARAM(wParam) mengembalikan koordinat jangkar X untuk peristiwa pemberitahuan NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT, dan semua pesan mouse antara WM_MOUSEFIRST dan WM_MOUSELAST. Jika salah satu pesan tersebut dihasilkan oleh keyboard, wParam diatur ke sudut kiri atas ikon target. Untuk semua pesan lainnya, wParam tidak ditentukan.
- GET_Y_LPARAM(wParam) mengembalikan koordinat jangkar Y untuk peristiwa pemberitahuan dan pesan seperti yang didefinisikan untuk jangkar X.
hIcon
Jenis: HICON
Handel ke ikon yang akan ditambahkan, dimodifikasi, atau dihapus. Windows XP dan yang lebih baru mendukung ikon hingga 32 BPP.
Jika hanya ikon piksel 16x16 yang disediakan, ikon ini diskalakan ke ukuran yang lebih besar dalam sistem yang diatur ke nilai dpi tinggi. Ini dapat menyebabkan hasil yang tidak menarik. Disarankan agar Anda menyediakan ikon piksel 16x16 dan ikon 32x32 di file sumber daya Anda. Gunakan
szTip[64]
Jenis: TCHAR[64]
String null-terminated yang menentukan teks untuk tipsalat standar. Ini dapat memiliki maksimum 64 karakter, termasuk karakter null yang mengakhiri.
Untuk Windows 2000 dan yang lebih baru, szTip dapat memiliki maksimal 128 karakter, termasuk karakter null yang mengakhiri.
szTip[128]
Jenis: TCHAR[64]
String null-terminated yang menentukan teks untuk tipsalat standar. Ini dapat memiliki maksimum 64 karakter, termasuk karakter null yang mengakhiri.
Untuk Windows 2000 dan yang lebih baru, szTip dapat memiliki maksimal 128 karakter, termasuk karakter null yang mengakhiri.
dwState
Jenis: DWORD
Windows 2000 dan yang lebih baru. Status ikon. Salah satu atau kedua nilai berikut:
NIS_HIDDEN (0x00000001)
0x00000001. Ikon disembunyikan.
NIS_SHAREDICON (0x00000002)
0x00000002. Sumber daya ikon dibagikan di antara beberapa ikon.
dwStateMask
Jenis: DWORD
Windows 2000 dan yang lebih baru. Nilai yang menentukan bit anggota
szInfo[256]
Jenis: TCHAR[256]
Windows 2000 dan yang lebih baru. String null-terminated yang menentukan teks untuk ditampilkan dalam pemberitahuan balon. Ini dapat memiliki maksimal 256 karakter, termasuk karakter null yang mengakhiri, tetapi harus dibatasi hingga 200 karakter dalam bahasa Inggris untuk mengakomodasi pelokalan. Untuk menghapus pemberitahuan balon dari UI, hapus ikon (dengan NIM_DELETE) atau atur bendera NIF_INFO di uFlags dan atur szInfo ke string kosong.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
Jenis: UINT
Windows 2000 dan yang lebih baru.
DUMMYUNIONNAME.uVersion
Jenis: UINT
Windows 2000 dan yang lebih baru. Union dengan uTimeout
szInfoTitle[64]
Jenis: TCHAR[64]
Windows 2000 dan yang lebih baru. String null-terminated yang menentukan judul untuk pemberitahuan balon. Judul ini muncul dalam font yang lebih besar tepat di atas teks. Ini dapat memiliki maksimal 64 karakter, termasuk karakter null yang mengakhiri, tetapi harus dibatasi hingga 48 karakter dalam bahasa Inggris untuk mengakomodasi pelokalan.
dwInfoFlags
Jenis: DWORD
Windows 2000 dan yang lebih baru. Bendera yang dapat diatur untuk memodifikasi perilaku dan tampilan pemberitahuan balon. Ikon ditempatkan di sebelah kiri judul. Jika anggota szInfoTitle
NIIF_NONE (0x00000000)
0x00000000. Tidak ada ikon.
NIIF_INFO (0x00000001)
0x00000001. Ikon informasi.
NIIF_WARNING (0x00000002)
0x00000002. Ikon peringatan.
NIIF_ERROR (0x00000003)
0x00000003. Ikon kesalahan.
NIIF_USER (0x00000004)
0x00000004. Windows XP SP2 dan yang lebih baru.
- windows XP: Gunakan ikon yang diidentifikasi di hIcon sebagai ikon judul balon pemberitahuan.
Windows Vista dan yang lebih baru : Gunakan ikon yang diidentifikasi dihBalloonIcon sebagai ikon judul balon pemberitahuan.
NIIF_NOSOUND (0x00000010)
0x00000010. Windows XP dan yang lebih baru. Jangan mainkan suara terkait. Hanya berlaku untuk pemberitahuan.
NIIF_LARGE_ICON (0x00000020)
0x00000020. Windows Vista dan yang lebih baru. Versi besar ikon harus digunakan sebagai ikon pemberitahuan. Ini sesuai dengan ikon dengan dimensi SM_CXICON x SM_CYICON. Jika bendera ini tidak diatur, ikon dengan dimensi SM_CXSMICON x SM_CYSMICON digunakan.
- Bendera ini dapat digunakan dengan semua ikon stok .
- Aplikasi yang menggunakan ikon yang disesuaikan lebih lama (NIIF_USER dengan hIcon) harus menyediakan versi SM_CYICON SM_CXICON x baru di ikon baki (hIcon). Ikon ini diturunkan skalanya ketika ditampilkan di Baki Sistem atau Area Kontrol Sistem (SCA).
- Ikon baru yang disesuaikan (NIIF_USER dengan
hBalloonIcon ) harus menyediakan versi SM_CXICON x SM_CYICON di ikon yang disediakan ( hBalloonIcon ).
NIIF_RESPECT_QUIET_TIME (0x00000080)
0x00000080. Windows 7 dan yang lebih baru. Jangan tampilkan pemberitahuan balon jika pengguna saat ini berada dalam "waktu tenang", yang merupakan jam pertama setelah pengguna baru masuk ke akunnya untuk pertama kalinya. Selama waktu ini, sebagian besar pemberitahuan tidak boleh dikirim atau ditampilkan. Ini memungkinkan pengguna terbiasa dengan sistem komputer baru tanpa gangguan tersebut. Waktu tenang juga terjadi untuk setiap pengguna setelah peningkatan sistem operasi atau penginstalan bersih. Pemberitahuan yang dikirim dengan bendera ini selama waktu tenang tidak diantrekan; itu hanya diberhentikan tanpa dishown. Aplikasi dapat mengirim ulang pemberitahuan nanti jika masih valid pada saat itu.
Karena aplikasi tidak dapat memprediksi kapan aplikasi mungkin mengalami waktu tenang, kami menyarankan agar bendera ini selalu diatur pada semua pemberitahuan yang sesuai dengan aplikasi apa pun yang berarti menghormati waktu tenang.
Selama waktu tenang, pemberitahuan tertentu masih harus dikirim karena diharapkan oleh pengguna sebagai umpan balik sebagai tanggapan terhadap tindakan pengguna, misalnya ketika dia mencolokkan perangkat USB atau mencetak dokumen.
Jika pengguna saat ini tidak berada dalam waktu tenang, bendera ini tidak berpengaruh.
NIIF_ICON_MASK (0x0000000F)
0x0000000F. Windows XP dan yang lebih baru. Dipesan.
guidItem
Jenis: GUID
Windows XP dan yang lebih baru.
-
Windows 7 dan yang lebih baru: GUID terdaftar yang mengidentifikasi ikon. Nilai ini mengambil alih uID dan merupakan metode yang direkomendasikan untuk mengidentifikasi ikon. Bendera NIF_GUID harus diatur dalam anggota
uFlags. - Windows XP dan Windows Vista: Dicadangkan; harus diatur ke 0.
Jika Anda mengidentifikasi ikon pemberitahuan dengan GUID dalam satu panggilan ke Shell_NotifyIcon, Anda harus menggunakan GUID yang sama untuk mengidentifikasi ikon dalam panggilan Shell_NotifyIcon berikutnya yang menangani ikon yang sama.
Untuk menghasilkan GUID untuk digunakan dalam anggota ini, gunakan alat pembuatan GUID seperti Guidgen.exe.
hBalloonIcon
Jenis: HICON
Windows Vista dan yang lebih baru. Handel ikon pemberitahuan yang disesuaikan yang disediakan oleh aplikasi yang harus digunakan secara independen dari ikon area pemberitahuan. Jika anggota ini bukan NULL dan bendera NIIF_USER diatur dalam anggota
Komentar
Lihat Pemberitahuan di Panduan Interaksi Pengalaman Pengguna Windows untuk informasi selengkapnya tentang antarmuka pengguna pemberitahuan dan praktik terbaik konten.
Jika Anda mengatur bendera
Tidak lebih dari satu pemberitahuan balon pada satu waktu dapat ditampilkan untuk taskbar. Jika aplikasi mencoba menampilkan pemberitahuan ketika sudah ditampilkan, pemberitahuan baru diantrekan dan ditampilkan saat pemberitahuan yang lebih lama hilang. Dalam versi Windows sebelum Windows Vista, pemberitahuan baru tidak akan muncul sampai pemberitahuan yang ada terlihat setidaknya untuk panjang batas waktu minimum sistem, terlepas dari nilai
Beberapa anggota struktur ini hanya didukung untuk Windows 2000 dan yang lebih baru. Untuk mengaktifkan anggota ini, sertakan salah satu baris berikut di header Anda:
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
Perhatikan bahwa Anda harus menginisialisasi struktur dengan ukurannya. Jika Anda menggunakan ukuran struktur yang saat ini ditentukan, aplikasi mungkin tidak berjalan dengan versi Shell32.dllyang lebih lama , yang mengharapkan struktur yang lebih kecil. Anda dapat menjalankan aplikasi anda terhadap versi Shell32.dll sebelumnya dengan menentukan nomor versi yang sesuai (lihat Shell dan Common Controls Versions). Namun, ini dapat menyebabkan masalah jika aplikasi Anda juga perlu berjalan pada sistem yang lebih baru.
Anda dapat mempertahankan kompatibilitas aplikasi dengan semua versi Shell32.dll saat masih menggunakan file header saat ini dengan mengatur ukuran struktur
| Versi Shell32.dll | cbSize |
|---|---|
| 6.0.6 atau lebih tinggi (Windows Vista dan yang lebih baru) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| Versi yang lebih rendah dari 5.0 | NOTIFYICONDATA_V1_SIZE |
Menggunakan nilai ini untuk
Contoh kode berikut menunjukkan pemeriksaan versi yang dapat mengaktifkan aplikasi yang menggunakan guidItem anggota untuk dijalankan pada Windows Vista dan Windows 7. Ini menyediakan fungsi Boolean yang mengembalikan TRUE jika sistem operasi adalah Windows 7. Kecuali anggota ini mengembalikan
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
Contoh kode berikut menunjukkan penggunaan LoadIconMetric
// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");
// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;
Pemecahan Masalah
Jika Anda menggunakan anggota- Bendera NIF_GUID tidak diatur dalam setiap panggilan ke Shell_NotifyIcon. Setelah mengidentifikasi ikon pemberitahuan dengan GUID dalam satu panggilan ke Shell_NotifyIcon, Anda harus menggunakan GUID yang sama untuk mengidentifikasi ikon dalam panggilan Shell_NotifyIcon berikutnya yang menangani ikon yang sama.
-
File biner yang berisi ikon telah dipindahkan. Jalur file biner disertakan dalam pendaftaran GUID ikon dan tidak dapat diubah. Pengaturan yang terkait dengan ikon dipertahankan melalui peningkatan hanya jika jalur file dan GUID tidak berubah. Jika jalur harus diubah, aplikasi harus menghapus informasi GUID apa pun yang ditambahkan ketika ikon yang ada terdaftar. Setelah informasi tersebut dihapus, Anda dapat memindahkan file biner ke lokasi baru dan mendaftarkannya kembali dengan GUID baru. Pengaturan apa pun yang terkait dengan pendaftaran GUID asli akan hilang.
Ini juga terjadi dalam kasus penginstalan berdampingan. Saat berhadapan dengan penginstalan berdampingan, versi baru aplikasi harus memperbarui GUID file biner.
Catatan Satu-satunya pengecualian untuk file yang dipindahkan terjadi ketika file biner asli dan yang dipindahkan Authenticode-ditandatangani oleh perusahaan yang sama. Dalam hal ini, pengaturan dipertahankan melalui pemindahan.
Nota
Header shellapi.h mendefinisikan NOTIFYICONDATA sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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] |
| Header |
shellapi.h |
Lihat juga
Pemberitahuan dan Area Pemberitahuan