NOTIFYICONDATAW 構造体 (shellapi.h)
システムが通知領域に通知を表示するために必要な情報を格納します。 Shell_NotifyIconで使用されます。
構文
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;
メンバーズ
cbSize
型: DWORD
この構造体のサイズ (バイト単位)。
hWnd
型: HWND
通知領域のアイコンに関連付けられた通知を受信するウィンドウのハンドル。
uID
型: UINT
タスク バー アイコンのアプリケーション定義識別子。 シェルでは、(hWnd と uID
uFlags
型: UINT
構造体の他のどのメンバーに有効なデータが含まれているかを示すか、表示方法に関する追加情報をツールヒントに提供するフラグ。 このメンバーには、次の値を組み合わせて使用できます。
NIF_MESSAGE (0x00000001)
0x00000001。 uCallbackMessage メンバーは有効です。
NIF_ICON (0x00000002)
0x00000002。 hIcon メンバーは有効です。
NIF_TIP (0x00000004)
0x00000004。 szTip メンバーが有効です。
NIF_STATE (0x00000008)
0x00000008。 dwState メンバーと dwStateMask メンバーが有効です。
NIF_INFO (0x00000010)
0x00000010。 バルーン通知を表示します。
szInfo、szInfoTitle、dwInfoFlags、および uTimeout メンバーが有効です。 uTimeout
- バルーン通知を表示するには、NIF_INFOを指定し、szInfoでテキストを指定します。
- バルーン通知を削除するには、NIF_INFOを指定し、szInfoを使用して空の文字列を指定します。
- 通知を表示せずに通知領域アイコンを追加するには、NIF_INFO フラグを設定しないでください。
NIF_GUID (0x00000020)
0x00000020。
- Windows 7 以降の: guidItem が有効です。
- Windows Vista 以前の: 予約済み。
NIF_REALTIME (0x00000040)
0x00000040。 Windows Vista 以降のを
NIF_SHOWTIP (0x00000080)
0x00000080。 Windows Vista 以降のを
uCallbackMessage
型: UINT
アプリケーション定義のメッセージ識別子。 システムは、この識別子を使用して、hWndで識別されたウィンドウ
uVersion メンバーが 0 またはNOTIFYICON_VERSIONの場合、メッセージの wParam パラメーターには、イベントが発生したタスク バー アイコンの識別子が含まれます。 この識別子の長さは 32 ビットです。 lParam パラメーターは、イベントに関連付けられているマウスまたはキーボード メッセージを保持します。 たとえば、ポインターがタスク バー アイコンの上に移動すると、lParam が WM_MOUSEMOVEに設定されます。
uVersion メンバーがNOTIFYICON_VERSION_4されると、アプリケーションは引き続き uCallbackMessage メンバーを介してアプリケーション定義メッセージの形式で通知イベントを受信しますが、そのメッセージの lParam および wParam パラメーターの解釈は次のように変更されます。
- LOWORD(lParam) には、NIN_BALLOONSHOW、NIN_POPUPOPEN、WM_CONTEXTMENUなどの通知イベントが含まれます。
-
HIWORD(lParam)
アイコン ID が含まれています。 アイコン ID は 16 ビットの長さに制限されます。 -
GET_X_LPARAM(wParam) は、通知イベントのNIN_POPUPOPEN、NIN_SELECT、NIN_KEYSELECT、およびWM_MOUSEFIRSTとWM_MOUSELAST間のすべてのマウス メッセージの X アンカー座標を返します。 これらのメッセージのいずれかがキーボードによって生成された場合、wParam はターゲット アイコンの左上隅に設定されます。 その他のすべてのメッセージの場合、wParam
は未定義です。 - GET_Y_LPARAM(wParam) は、X アンカーに対して定義されている通知イベントとメッセージの Y アンカー座標を返します。
hIcon
型: HICON
追加、変更、または削除するアイコンのハンドル。 Windows XP 以降では、最大 32 BPP のアイコンがサポートされています。
16 x 16 ピクセルのアイコンのみが指定されている場合、システムでは大きいサイズにスケーリングされ、高 dpi 値に設定されます。 これにより、魅力的でない結果が発生する可能性があります。 リソース ファイルには、16 x 16 ピクセル アイコンと 32 x 32 アイコンの両方を指定することをお勧めします。 LoadIconMetric を使用して、正しいアイコンが読み込まれ、適切にスケーリングされていることを確認します。 コード例については、「解説」を参照してください。
szTip[64]
型: TCHAR[64]
標準のヒントのテキストを指定する null で終わる文字列。 終端の null 文字を含め、最大 64 文字を指定できます。
Windows 2000 以降の場合、szTip は、終端の null 文字を含め、最大 128 文字にすることができます。
szTip[128]
型: TCHAR[64]
標準のヒントのテキストを指定する null で終わる文字列。 終端の null 文字を含め、最大 64 文字を指定できます。
Windows 2000 以降の場合、szTip は、終端の null 文字を含め、最大 128 文字にすることができます。
dwState
型: DWORD
Windows 2000 以降のを
NIS_HIDDEN (0x00000001)
0x00000001。 アイコンは非表示になっています。
NIS_SHAREDICON (0x00000002)
0x00000002。 アイコン リソースは、複数のアイコン間で共有されます。
dwStateMask
型: DWORD
Windows 2000 以降のを
szInfo[256]
型: TCHAR[256]
Windows 2000 以降のを
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
型: UINT
Windows 2000 以降のを
DUMMYUNIONNAME.uVersion
型: UINT
Windows 2000 以降のを
szInfoTitle[64]
型: TCHAR[64]
Windows 2000 以降のを
dwInfoFlags
型: DWORD
Windows 2000 以降のを
NIIF_NONE (0x00000000)
0x00000000。 [いいえ] アイコン。
NIIF_INFO (0x00000001)
0x00000001。 情報アイコン。
NIIF_WARNING (0x00000002)
0x00000002。 警告アイコン。
NIIF_ERROR (0x00000003)
0x00000003。 エラー アイコン。
NIIF_USER (0x00000004)
0x00000004。 Windows XP SP2 以降のを
Windows XP : 通知バルーンのタイトル アイコンとして、hIconで識別されるアイコンを使用します。 Windows Vista 以降の : 通知バルーンのタイトル アイコンとして hBalloonIconで識別されるアイコンを使用します。
NIIF_NOSOUND (0x00000010)
0x00000010。 Windows XP 以降のを
NIIF_LARGE_ICON (0x00000020)
0x00000020。 Windows Vista 以降のを
- このフラグは、すべての ストックアイコンで使用できます。
- 以前のカスタマイズされたアイコン (hIconでNIIF_USER) を使用するアプリケーションは、トレイ アイコン (hIcon) に新しい SM_CXICON x SM_CYICON バージョンを提供する必要があります。 これらのアイコンは、システム・トレイまたはシステム制御域 (SCA) に表示されるときにスケールダウンされます。
- 新しいカスタマイズされたアイコン (hBalloonIconを含むNIIF_USER) は、指定されたアイコン (hBalloonIcon) にSM_CXICON x SM_CYICON バージョンを指定する必要があります。
NIIF_RESPECT_QUIET_TIME (0x00000080)
0x00000080。 Windows 7 以降のを
アプリケーションでは、いつ静かな時間が発生する可能性があるかを予測できないため、このフラグは、静かな時間を優先することを意味するすべてのアプリケーションによって、すべての適切な通知に常に設定することをお勧めします。
一部の通知は、USB デバイスに接続したり、ドキュメントを印刷したりする場合など、ユーザーの操作に対するフィードバックとしてユーザーが期待するため、静かな時間の間に送信する必要があります。
現在のユーザーが静かな時間でない場合、このフラグは無効です。
NIIF_ICON_MASK (0x0000000F)
0x0000000F。 Windows XP 以降のを
guidItem
型: GUID
Windows XP 以降のを
-
Windows 7 以降の: アイコンを識別する登録済みの GUID。 この値は uID
オーバーライドし、アイコンを識別するための推奨される方法です。 NIF_GUID フラグは、uFlags メンバーで設定する必要があります。 - Windows XP と Windows Vista: 予約済み。は 0 に設定する必要があります。
Shell_NotifyIconへの 1 回の呼び出しで GUID を持つ通知アイコンを識別する場合は、同じ GUID を使用して、その同じアイコンを処理する後続の Shell_NotifyIcon 呼び出しでアイコンを識別する必要があります。
このメンバーで使用する GUID を生成するには、Guidgen.exeなどの GUID 生成ツールを使用します。
hBalloonIcon
型: HICON
Windows Vista 以降のを
備考
通知 UI とコンテンツのベスト プラクティスの詳細については、「Windows ユーザー エクスペリエンスの対話ガイドライン」の「通知の」を参照してください。
uFlags メンバーで NIF_INFO フラグを設定すると、バルーン スタイルの通知が使用されます。 これらの通知の詳細については、「バルーンのヒント」を参照してください。
タスク バーに対して一度に 1 つ以上のバルーン通知を表示することはできません。 アプリケーションが既に表示されているときに通知を表示しようとすると、古い通知が消えたときに新しい通知がキューに登録され、表示されます。 Windows Vista より前のバージョンの Windows では、元の通知の uTimeout 値に関係なく、少なくともシステムの最小タイムアウト長で既存の
この構造体のいくつかのメンバーは、Windows 2000 以降でのみサポートされています。 これらのメンバーを有効にするには、ヘッダーに次のいずれかの行を含めます。
// 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
構造体のサイズを初期化する必要があることに注意してください。 現在定義されている構造体のサイズを使用する場合、アプリケーションが以前のバージョンの Shell32.dllで実行されない可能性があります。この場合、構造体が小さいことが予想されます。 適切なバージョン番号を定義することで、以前のバージョンの Shell32.dll に対してアプリケーションを実行できます (シェルと共通コントロールのバージョンを参照)。 ただし、より新しいシステムでもアプリケーションを実行する必要がある場合は、問題が発生する可能性があります。
NOTIFYICONDATA 構造体のサイズを適切に設定することで、現在のヘッダー ファイルを使用しながら、すべての Shell32.dll バージョンとのアプリケーションの互換性を維持できます。 構造体を初期化する前に、DllGetVersion
| Shell32.dll バージョン | cbSize |
|---|---|
| 6.0.6 以降 (Windows Vista 以降) | sizeof(NOTIFYICONDATA) |
| 6.0 (Windows XP) | NOTIFYICONDATA_V3_SIZE |
| 5.0 (Windows 2000) | NOTIFYICONDATA_V2_SIZE |
| 5.0 より前のバージョン | NOTIFYICONDATA_V1_SIZE |
cbSize にこの値を使用すると、アプリケーションは以前のバージョンの Shell32.dll バージョンと互換性のあるメソッドで NOTIFYICONDATA を使用できます。
次のコード例は、guidItem メンバーを使用するアプリケーションを Windows Vista と Windows 7 の両方で実行できるようにするバージョン チェックを示しています。 オペレーティング システムが Windows 7 の場合 TRUE を返すブール関数を提供します。 このメンバーが TRUE
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);
}
次のコード例は、LoadIconMetric を使用して、高 DPI で使用するアイコンを読み込む方法を示しています。
// 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;
のトラブルシューティング
guidItem メンバーを使用してアイコンを識別していて、そのアイコンが表示されない場合や、Shell_NotifyIcon の呼び出しが失敗した場合は、次のいずれかの原因が考えられます。- NIF_GUID フラグは、Shell_NotifyIconのすべての呼び出しで設定されていませんでした。 Shell_NotifyIconへの 1 回の呼び出しで GUID を持つ通知アイコンを識別したら、その同じ GUID を使用して、その同じアイコンを処理する後続の Shell_NotifyIcon 呼び出しでアイコンを識別する必要があります。
-
アイコンを含むバイナリ ファイルが移動されました。 バイナリ ファイルのパスはアイコンの GUID の登録に含まれており、変更することはできません。 アイコンに関連付けられている設定は、ファイル パスと GUID が変更されていない場合にのみ、アップグレードによって保持されます。 パスを変更する必要がある場合、アプリケーションは、既存のアイコンが登録されたときに追加されたすべての GUID 情報を削除する必要があります。 その情報が削除されたら、バイナリ ファイルを新しい場所に移動し、新しい GUID で再登録できます。 元の GUID 登録に関連付けられている設定はすべて失われます。
これは、サイド バイ サイド インストールの場合にも発生します。 サイド バイ サイド インストールを処理する場合は、新しいバージョンのアプリケーションでバイナリ ファイルの GUID を更新する必要があります。
メモ 移動されたファイルに対する唯一の例外は、元のバイナリ ファイルと移動されたバイナリ ファイルの両方が、同じ会社によって署名された Authenticode場合に発生します。 その場合、設定は移動中も保持されます。
手記
shellapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして NOTIFYICONDATA を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| ヘッダー | shellapi.h |