Bagikan melalui

Struktur NOTIFYICONDATAW (shellapi.h)

  • Artikel

Berisi informasi yang dibutuhkan sistem untuk menampilkan pemberitahuan di area pemberitahuan. Digunakan oleh Shell_NotifyIcon.

Sintaks

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 (hWnd plus uID) atau guidItem untuk mengidentifikasi ikon mana yang akan dioperasikan saat Shell_NotifyIcon dipanggil. Anda dapat memiliki beberapa ikon yang terkait dengan satu hWnd dengan menetapkan setiap uID yang berbeda. Jika guidItem ditentukan, uID diabaikan.

uFlags

Jenis: UINT

Bendera yang menunjukkan anggota struktur lain mana yang berisi data yang valid atau memberikan informasi tambahan ke tipsalat tentang bagaimana seharusnya ditampilkan. Anggota ini bisa menjadi kombinasi dari nilai berikut:

NIF_MESSAGE (0x00000001)

0x00000001. Anggota uCallbackMessage valid.

NIF_ICON (0x00000002)

0x00000002. Anggota hIcon valid.

NIF_TIP (0x00000004)

0x00000004. Anggota szTip valid.

NIF_STATE (0x00000008)

0x00000008. Anggota dwState dan dwStateMask valid.

NIF_INFO (0x00000010)

0x00000010. Menampilkan pemberitahuan balon. Anggota szInfo, szInfoTitle, dwInfoFlags, dan uTimeout valid. Perhatikan bahwa uTimeout hanya berlaku di Windows 2000 dan Windows XP.

  • Untuk menampilkan pemberitahuan balon, tentukan NIF_INFO dan berikan teks di 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: GuidItem valid.
  • Windows Vista dan yang lebih lama: 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 masih harus 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 pembatas ikon, ketika ikon dipilih atau diaktifkan dengan keyboard, atau ketika tindakan tersebut terjadi di pemberitahuan balon.

Ketika anggota uVersion adalah 0 atau NOTIFYICON_VERSION, parameter wParam pesan berisi pengidentifikasi ikon taskbar tempat peristiwa terjadi. Pengidentifikasi ini panjangnya bisa 32 bit. Parameter lParam menyimpan pesan mouse atau keyboard yang terkait dengan peristiwa tersebut. Misalnya, saat penunjuk bergerak di atas ikon taskbar, lParam diatur ke WM_MOUSEMOVE.

Ketika anggota uVersion NOTIFYICON_VERSION_4, aplikasi terus menerima peristiwa pemberitahuan dalam bentuk pesan yang ditentukan aplikasi melalui anggota uCallbackMessage , tetapi interpretasi parameter lParam dan wParam dari pesan tersebut diubah sebagai berikut:

  • LOWORD(lParam) berisi peristiwa pemberitahuan, seperti NIN_BALLOONSHOW, NIN_POPUPOPEN, atau WM_CONTEXTMENU.
  • HIWORD(lParam) berisi ID ikon. ID ikon dibatasi hingga 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 sebagaimana 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 LoadIconMetric untuk memastikan bahwa ikon yang benar dimuat dan diskalakan dengan tepat. Lihat Keterangan untuk contoh kode.

szTip[64]

Jenis: TCHAR[64]

String null-terminated yang menentukan teks untuk tipsalat standar. Ini dapat memiliki maksimal 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 maksimal 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 dwState mana yang diambil atau dimodifikasi. Nilai yang mungkin sama dengan nilai untuk dwState. Misalnya, mengatur anggota ini ke NIS_HIDDEN hanya menyebabkan status tersembunyi item dimodifikasi saat bit berbagi ikon diabaikan terlepas dari nilainya.

szInfo[256]

Jenis: TCHAR[256]

Windows 2000 dan yang lebih baru. String yang dihentikan null 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.

Catatan Anggota ini tidak digunakan lagi pada Windows Vista. Waktu tampilan pemberitahuan sekarang didasarkan pada pengaturan aksesibilitas sistem.
 
Union dengan uVersion. Nilai batas waktu, dalam milidetik, untuk pemberitahuan. Sistem memberlakukan nilai batas waktu minimum dan maksimum. Nilai yang ditentukan dalam uTimeout yang terlalu besar diatur ke nilai maksimum. Nilai yang terlalu kecil default ke nilai minimum. Nilai batas waktu minimum dan maksimum sistem saat ini diatur masing-masing pada 10 detik dan 30 detik. Lihat Keterangan untuk diskusi lebih lanjut tentang uTimeout.

DUMMYUNIONNAME.uVersion

Jenis: UINT

Windows 2000 dan yang lebih baru. Union dengan uTimeout (tidak digunakan lagi pada Windows Vista). Menentukan versi antarmuka ikon pemberitahuan Shell mana yang harus digunakan. Untuk informasi selengkapnya tentang perbedaan dalam versi ini, lihat Shell_NotifyIcon. Anggota ini hanya digunakan saat menggunakan Shell_NotifyIcon untuk mengirim pesan NIM_SETVERSION .

szInfoTitle[64]

Jenis: TCHAR[64]

Windows 2000 dan yang lebih baru. String yang dihentikan null 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 mengubah perilaku dan tampilan pemberitahuan balon. Ikon ditempatkan di sebelah kiri judul. Jika anggota szInfoTitle memiliki panjang nol, ikon tidak ditampilkan.

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 dalam hIcon sebagai ikon judul balon pemberitahuan.
  • Windows Vista dan yang lebih baru: Gunakan ikon yang diidentifikasi di hBalloonIcon sebagai ikon judul balon pemberitahuan.

NIIF_NOSOUND (0x00000010)

0x00000010. Windows XP dan yang lebih baru. Jangan putar 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 yang 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 dalam 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 shown. Aplikasi dapat mengirim ulang pemberitahuan nanti jika masih valid pada saat itu.

Karena aplikasi tidak dapat memprediksi kapan mungkin mengalami waktu tenang, kami menyarankan agar bendera ini selalu diatur pada semua pemberitahuan yang sesuai oleh aplikasi apa pun yang berarti menghormati waktu tenang.

Selama waktu tenang, pemberitahuan tertentu masih harus dikirim karena mereka 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. Dicadangkan.

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 aplikasi Anda dimaksudkan untuk berjalan pada Windows Vista dan Windows 7, sangat penting bagi Anda untuk memeriksa versi Windows dan hanya menentukan guidItem nonzero jika pada Windows 7 atau yang lebih baru.

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 berurusan dengan 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 non-NULL dan bendera NIIF_USER diatur dalam anggota dwInfoFlags , ikon ini digunakan sebagai ikon pemberitahuan. Jika anggota ini NULL, perilaku warisan dilakukan.

Keterangan

Lihat Pemberitahuan di Panduan Interaksi Pengalaman Pengguna Windows untuk informasi selengkapnya tentang antarmuka pengguna pemberitahuan dan praktik terbaik konten.

Jika Anda mengatur bendera NIF_INFO di anggota uFlags , pemberitahuan gaya balon digunakan. Untuk diskusi selengkapnya tentang pemberitahuan ini, lihat Tipsalat balon.

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 telah terlihat setidaknya untuk panjang batas waktu minimum sistem, terlepas dari nilai uTimeout pemberitahuan asli. Jika pengguna tampaknya tidak menggunakan komputer, sistem tidak menghitung waktu ini terhadap batas waktu.

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.dll yang lebih lama, yang mengharapkan struktur yang lebih kecil. Anda dapat menjalankan aplikasi terhadap versi Shell32.dll yang lebih lama dengan menentukan nomor versi yang sesuai (lihat Versi Shell dan Kontrol Umum). 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 NOTIFYICONDATA dengan tepat. Sebelum Anda menginisialisasi struktur, gunakan DllGetVersion untuk menentukan versi Shell32.dll mana yang diinstal pada sistem dan menginisialisasi cbSize dengan salah satu nilai ini:

Versi Shell32.dll cbSize
6.0.6 atau yang 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 cbSize memungkinkan aplikasi Anda menggunakan NOTIFYICONDATA dalam metode yang kompatibel dengan versi Shell32.dll sebelumnya.

Contoh kode berikut menunjukkan pemeriksaan versi yang dapat mengaktifkan aplikasi yang menggunakan anggota guidItem 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 TRUE, anggota guidItem harus diatur ke 0.

Catatan Kode ini khusus untuk nomor versi Windows 7. Diharapkan bahwa versi Windows dan Windows Server di masa mendatang akan mendukung anggota guidItem , dan pada saat itu kode ini harus diperbarui untuk mengidentifikasi nomor versi yang lebih baru juga valid.
 
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 untuk memuat ikon untuk digunakan dengan DPI tinggi.

// 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 guidItem untuk mengidentifikasi ikon, dan ikon tersebut tidak terlihat atau beberapa panggilan ke Shell_NotifyIcon gagal, salah satu kasus berikut adalah kemungkinan penyebabnya:
  1. Bendera NIF_GUID tidak diatur di 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 berurusan dengan ikon yang sama.
  2. 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 ditandatangani Authenticode oleh perusahaan yang sama. Dalam hal ini, pengaturan dipertahankan melalui pemindahan.
     

Catatan

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

   
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