Shell_NotifyIconA関数 (shellapi.h)

[アーティクル]
08/26/2023

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

構文

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

パラメーター

[in] dwMessage

型: DWORD

この関数によって実行されるアクションを示す値。次のいずれかの値になります。

NIM_ADD (0x00000000)

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

NIM_MODIFY (0x00000001)

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

NIM_DELETE (0x00000002)

0x00000002。ステータス領域からアイコンを削除します。 lpdata が指す NOTIFYICONDATA 構造体は、アイコンが通知領域 (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 ( バージョン 6.0Shell32.dll) 以降、ユーザーがバルーン通知が関連付けられているアイコンの上にマウスポインターを渡すと、シェルは次のメッセージを送信します。

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

これらのメッセージに加えて、Windows Vista (バージョン 6.0.6 Shell32.dll) の時点で、ユーザーがバルーン通知が関連付けられているアイコンの上にマウスポインターを渡すと、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 ヘッダーは、Shell_NotifyIconをエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

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

こちらもご覧ください

通知と通知領域