Shell_NotifyIconA関数 (shellapi.h)

[アーティクル]
11/20/2024

タスクバーの状態領域にメッセージを送信します。

構文

BOOL Shell_NotifyIconA(
  [in] DWORD            dwMessage,
  [in] PNOTIFYICONDATAA lpData
);

パラメーター

[in] dwMessage

型: DWORD

この関数によって実行されるアクションを指定する値。次のいずれかの値を指定できます。

NIM_ADD (0x00000000)

0x00000000。ステータス領域にアイコンを追加します。アイコンには、uID または guidItem メンバーを介して lpdata指す NOTIFYICONDATA 構造体識別子が与えられます。この識別子は、後続の Shell_NotifyIcon 呼び出しで使用され、アイコンに対して後でアクションを実行します。

NIM_MODIFY (0x00000001)

0x00000001。ステータス領域のアイコンを変更します。 lpdata 指す NOTIFYICONDATA 構造体は、アイコンが通知領域 (NIM_ADD) に追加されたときに最初に割り当てられた ID を使用して、変更するアイコンを識別します。

NIM_DELETE (0x00000002)

0x00000002。ステータス領域からアイコンを削除します。 NOTIFYICONDATAlpdata が指す構造体は、アイコンが通知領域 (NIM_ADD) に追加されたときに最初に割り当てられた ID を使用して、削除するアイコンを識別します。

NIM_SETFOCUS (0x00000003)

0x00000003。バージョン 5.0 以降 Shell32.dllだけです。タスクバーの通知領域にフォーカスを戻します。通知領域アイコンは、UI 操作が完了したときにこのメッセージを使用する必要があります。たとえば、アイコンにショートカットメニューが表示されていても、ユーザーが Esc キーを押してキャンセルする場合は、NIM_SETFOCUS を使用して通知領域にフォーカスを戻します。

NIM_SETVERSION (0x00000004)

0x00000004。バージョン 5.0 以降 Shell32.dllだけです。 lpdataが指す構造体の uVersion メンバーで指定されたバージョン番号に従って動作するように通知領域指示します。バージョン番号は、認識されるメンバーを指定します。

NIM_SETVERSIONは、通知領域アイコンが追加されるたびに呼び出す必要があります (NIM_ADD)。 NIM_MODIFYで呼び出す必要はありません。ユーザーがログオフすると、バージョン設定は保持されません。

詳細については、「解説」セクションを参照してください。

[in] lpData

型: PNOTIFYICONDATA

NOTIFYICONDATA 構造体へのポインター。構造体の内容は、dwMessageの値依存します。通知領域に追加するアイコンを定義したり、そのアイコンに通知を表示させたり、変更または削除するアイコンを識別することができます。

戻り値

型: BOOL

成功した場合 TRUE を返し、それ以外の場合は FALSE 返します。 dwMessage NIM_SETVERSIONに設定されている場合、バージョンが正常に変更された場合は true を返し、要求されたバージョンがサポートされていない場合は FALSE をします。

備考

Windows 2000 (Shell32.dll バージョン 5.0) の時点で、lpdata が指す NOTIFYICONDATA 構造体の uVersion メンバーを NOTIFYICON_VERSION_4 以上に設定すると、Shell_NotifyIcon マウスイベントとキーボードイベントは以前のバージョンの Windows とは異なる方法で処理されます。違いは次のとおりです。

ユーザーがキーボードで通知アイコンのショートカットメニューを選択した場合、シェルは関連付けられているアプリケーションに WM_CONTEXTMENU メッセージを送信するようになりました。以前のバージョンでは、WM_RBUTTONDOWN および WM_RBUTTONUP メッセージが送信されます。
ユーザーがキーボードで通知アイコンを選択し、SPACEBAR キーまたは ENTER キーを使用してアクティブ化すると、バージョン 5.0 シェルは関連付けられたアプリケーションにNIN_KEYSELECT通知を送信します。以前のバージョンでは、WM_RBUTTONDOWN および WM_RBUTTONUP メッセージが送信されます。
ユーザーがマウスで通知アイコンを選択し、Enter キーを使用してアクティブ化すると、シェルは関連付けられたアプリケーションにNIN_SELECT通知を送信するようになりました。以前のバージョンでは、WM_RBUTTONDOWN および WM_RBUTTONUP メッセージが送信されます。

Windows XP (Shell32.dll バージョン 6.0) の時点で、ユーザーがバルーン通知が関連付けられているアイコンの上にマウスポインターを渡すと、シェルは次のメッセージを送信します。

NIN_BALLOONSHOW。バルーンが表示されたときに送信されます (バルーンはキューに入れられます)。
NIN_BALLOONHIDE。バルーンが消えたときに送信されます。たとえば、アイコンが削除されたときなどです。このメッセージは、タイムアウトが原因でバルーンが閉じられた場合、またはユーザーがマウスをクリックした場合は送信されません。
Windows 7 の時点で、NIN_BALLOONHIDEは、NIIF_RESPECT_QUIET_TIME フラグが設定された通知が、静かな時間帯 (新しいコンピューターでのユーザーの最初の 1 時間) に表示しようとしたときにも送信されます。その場合、バルーンは一切表示されません。
NIN_BALLOONTIMEOUT。タイムアウトが原因でバルーンが閉じられたときに送信されます。
NIN_BALLOONUSERCLICK。ユーザーがマウスをクリックしたために吹き出しが閉じられたときに送信されます。

これらのメッセージに加えて、Windows Vista (Shell32.dll バージョン 6.0.6) の時点で、ユーザーがバルーン通知が関連付けられているアイコンの上にマウスポインターを渡すと、Windows Vista シェルも次のメッセージを追加します。

NIN_POPUPOPEN。ユーザーがアイコンの上にカーソルを置くと、標準的なテキストヒントの代わりに、より豊富なポップアップ UI を使用する必要があることを示すために送信されます。
NIN_POPUPCLOSE。アイコンの上にカーソルが置かなくなったときに送信され、リッチポップアップ UI を閉じる必要があることを示します。

オペレーティングシステムのバージョンに関係なく、dwMessage を NIM_SETVERSIONに設定して Shell_NotifyIcon を呼び出すことによって、シェルの動作方法を選択できます。 lpdata が指す NOTIFYICONDATA 構造体の uVersion メンバーを設定して、Windows 2000、Windows Vista、またはバージョン 5.0 (Windows 95) 以前の動作を指定します。

注上記で説明したメッセージは、従来の Windows メッセージではありません。これらは、dwMessageで設定された NIM_ADD フラグで Shell_NotifyIcon が呼び出されると、lpdataが指す NOTIFYICONDATA 構造体の uCallbackMessage メンバーで指定されたアプリケーション定義メッセージの lParam 値として送信されます。

Windows XP Service Pack 2 (SP2) の時点で、通知バルーンにカスタムアイコンを表示できます。これにより、呼び出し元プロセスは、情報、警告、およびエラーの以前に使用可能なオプションを超えて通知をカスタマイズし、ユーザーの他の種類の通知と区別することができます。

手記

shellapi.h ヘッダーは、unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとしてShell_NotifyIconを定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	shellapi.h
ライブラリ	Shell32.lib
DLL	Shell32.dll (バージョン 4.0 以降)
API セットの	ext-ms-win-shell-shell32-l1-2-1 (Windows 10 バージョン 10.0.10240 で導入)

次の方法で共有