テクニカルノート 6: メッセージマップ

[アーティクル]
06/16/2023

このノートでは、MFC メッセージマップ機能について説明します。

問題

Microsoft Windows では、メッセージング機能を使用するウィンドウクラス内で、仮想関数が実装されています。関連メッセージの数が多いため、Windows メッセージごとに個別の仮想関数を提供すると、作成される vtable は非常に大きなものになります。

システム定義 Windows メッセージの数は時間の経過と共に変化し、アプリケーションは独自の Windows メッセージを定義することができるため、メッセージマップには、インターフェイスの変更による既存のコードの破損を防ぐ間接参照レベルが用意されています。

概要

MFC には、ウィンドウに送信されたメッセージを処理するために、従来の Windows ベースのプログラム内で使用されていた switch ステートメントの代替手段が用意されています。ウィンドウがメッセージを受信したとき、適切なメソッドが自動的に呼び出されるように、メッセージからメソッドへのマッピングを定義することができます。この message-map 機能の設計は仮想関数と似ていますが、C++ 仮想関数では実現できない追加のメリットがあります。

メッセージマップの定義

DECLARE_MESSAGE_MAP マクロは、クラスに対して 3 つのメンバーを宣言します。

_messageEntries と呼ばれる AFX_MSGMAP_ENTRY エントリのプライベート配列。
_messageEntries 配列を指す messageMap と呼ばれる保護された AFX_MSGMAP 構造体。
messageMap のアドレスを返す GetMessageMap と呼ばれる保護された仮想関数。

このマクロは、メッセージマップを使用して、任意のクラスの宣言に挿入する必要があります。慣例に従って、これはクラスの宣言の末尾に配置されます。次に例を示します。

class CMyWnd : public CMyParentWndClass
{
    // my stuff...

protected:
    //{{AFX_MSG(CMyWnd)
    afx_msg void OnPaint();
    //}}AFX_MSG

    DECLARE_MESSAGE_MAP()
};

これは、AppWizard と ClassWizard が新しいクラスを作成するときに生成される形式です。 ClassWizard には、//{{ および //}} ブラケットが必要です。

メッセージマップのテーブルは、メッセージマップエントリに展開される一連のマクロを使用して定義されます。テーブルは BEGIN_MESSAGE_MAP マクロ呼び出しで始まります。このマクロ呼び出しにより、このメッセージマップによって処理されるクラスと、未処理のメッセージが渡される親クラスが定義されます。テーブルの末尾は END_MESSAGE_MAP マクロ呼び出しです。

この 2 つのマクロ呼び出しの間には、このメッセージマップによって処理されるメッセージごとにエントリがあります。 Windows の標準メッセージには、そのメッセージのエントリを生成するON_WM_MESSAGE_NAME という形式のマクロが含まれています。

各 Windows メッセージのパラメーターをアンパックし、タイプセーフを提供するために、標準の関数シグネチャが定義されています。これらのシグネチャは、CWnd の宣言内の Afxwin.h ファイル内で見つけることができます。それぞれにキーワード afx_msg が付いているため、簡単に特定できます。

Note

ClassWizard では、ご自身のメッセージマップハンドラー宣言内で、afx_msg キーワードを使用する必要があります。

これらの関数シグネチャは、シンプルな規則に基づいて派生したものです。関数の名前は必ず "On" で始まります。その後に "WM_" を除いた Windows メッセージの名前が続きます。名前の各単語の最初の文字は大文字です。パラメーターの順序は、wParam、LOWORD(lParam)、HIWORD(lParam) です。使用されていないパラメーターは渡されません。 MFC クラスによってラップされたハンドルは、適切な MFC オブジェクトへのポインターに変換されます。次の例は、WM_PAINT メッセージを処理し、CMyWnd::OnPaint 関数が呼び出されるようにする方法を示しています。

BEGIN_MESSAGE_MAP(CMyWnd, CMyParentWndClass)
    //{{AFX_MSG_MAP(CMyWnd)
    ON_WM_PAINT()
    //}}AFX_MSG_MAP
END_MESSAGE_MAP()

メッセージマップテーブルは、関数またはクラスの定義のスコープ外で定義する必要があります。 extern "C" ブロック内には入れないでください。

Note

ClassWizard により、コメントブラケット //{{ と //}} の間のメッセージマップエントリが修正されます。

ユーザー定義 Windows メッセージ

ユーザー定義メッセージをメッセージマップに含めるには、ON_MESSAGE マクロを使用します。このマクロは、次の形式でメッセージ番号とメソッドを受け入れます。

    // inside the class declaration
    afx_msg LRESULT OnMyMessage(WPARAM wParam, LPARAM lParam);

    #define WM_MYMESSAGE (WM_USER + 100)

BEGIN_MESSAGE_MAP(CMyWnd, CMyParentWndClass)
    ON_MESSAGE(WM_MYMESSAGE, OnMyMessage)
END_MESSAGE_MAP()

この例では、このユーザー定義メッセージの標準 WM_USER ベースから派生した、Windows メッセージ ID を持つカスタムメッセージ用のハンドラーを確立します。次の例は、このハンドラーを呼び出す方法を示しています。

CWnd* pWnd = ...;
pWnd->SendMessage(WM_MYMESSAGE);

この方法を使用するユーザー定義メッセージの範囲は、WM_USER から 0x7fff の範囲内である必要があります。

Note

ClassWizard は、ClassWizard ユーザーインターフェイスからの ON_MESSAGE ハンドラールーチンの入力をサポートしていません。これらは Visual C++ エディターから手動で入力する必要があります。 ClassWizard は、これらのエントリを解析して、他のメッセージマップエントリと同じように参照できるようにします。

登録済み Windows メッセージ

RegisterWindowMessage 関数は、システム全体で一意であることが保証されている新しいウィンドウメッセージの定義に使用されます。これらのメッセージの処理には、マクロ ON_REGISTERED_MESSAGE が使用されます。このマクロは、登録済み Winsows メッセージ ID を含む UINT NEAR 変数の名前を受け入れます。次に例を示します。

class CMyWnd : public CMyParentWndClass
{
public:
    CMyWnd();

    //{{AFX_MSG(CMyWnd)
    afx_msg LRESULT OnFind(WPARAM wParam, LPARAM lParam);
    //}}AFX_MSG

    DECLARE_MESSAGE_MAP()
};

static UINT NEAR WM_FIND = RegisterWindowMessage("COMMDLG_FIND");

BEGIN_MESSAGE_MAP(CMyWnd, CMyParentWndClass)
    //{{AFX_MSG_MAP(CMyWnd)
    ON_REGISTERED_MESSAGE(WM_FIND, OnFind)
    //}}AFX_MSG_MAP
END_MESSAGE_MAP()

登録済み Windows メッセージ ID 変数 (この例では WM_FIND) は NEAR 変数でなければなりません。これは、ON_REGISTERED_MESSAGE の実装方法によるものです。

この方法を使用するユーザー定義メッセージの範囲は、0xC000 から 0xFFFF の範囲になります。

Note

ClassWizard は、ClassWizard ユーザーインターフェイスからの ON_REGISTERED_MESSAGE ハンドラールーチンの入力をサポートしていません。これらはテキストエディターから手動で入力する必要があります。 ClassWizard は、これらのエントリを解析して、他のメッセージマップエントリと同じように参照できるようにします。

コマンドメッセージ

メニューやアクセラレータからのコマンドメッセージは、ON_COMMAND マクロを使用してメッセージマップ内で処理されます。このマクロは、コマンド ID とメソッドを受け入れます。指定されたコマンド ID に等しい wParam を持つ特定のWM_COMMAND メッセージのみが、メッセージマップエントリで指定されたメソッドによって処理されます。コマンドハンドラーのメンバー関数はパラメーターを取らず、void を返します。マクロの形式は次のとおりです。

ON_COMMAND(id, memberFxn)

コマンド更新メッセージは、同じメカニズムを使用してルーティングされますが、代わりに ON_UPDATE_COMMAND_UI マクロが使用されます。コマンド更新ハンドラーのメンバー関数は、1 つのパラメーター、CCmdUI オブジェクトへのポインターを取り、void を返します。マクロの形式は次のとおりです

ON_UPDATE_COMMAND_UI(id, memberFxn)

上級ユーザーは、コマンドメッセージハンドラーの拡張形式、ON_COMMAND_EX マクロを使用できます。このマクロは、ON_COMMAND 機能のスーパーセットを提供します。拡張コマンドハンドラーメンバー関数は、単一のパラメーター、つまりコマンド ID を含む UINT を取り、BOOL を返します。戻り値は、コマンドが処理されたことを示す TRUE である必要があります。それ以外の場合、他のコマンドターゲットオブジェクトに対するルーティングが引き続き行われます。

形式の例を次に示します。

Resource.h 内 (通常は Visual C++ で生成)

#define    ID_MYCMD      100
#define    ID_COMPLEX    101

クラス宣言内

afx_msg void OnMyCommand();
afx_msg void OnUpdateMyCommand(CCmdUI* pCmdUI);
afx_msg BOOL OnComplexCommand(UINT nID);

メッセージマップ定義内

ON_COMMAND(ID_MYCMD, OnMyCommand)
ON_UPDATE_COMMAND_UI(ID_MYCMD, OnUpdateMyCommand)
ON_COMMAND_EX(ID_MYCMD, OnComplexCommand)

実装ファイル内

void CMyClass::OnMyCommand()
{
    // handle the command
}

void CMyClass::OnUpdateMyCommand(CCmdUI* pCmdUI)
{
    // set the UI state with pCmdUI
}

BOOL CMyClass::OnComplexCommand(UINT nID)
{
    // handle the command
    return TRUE;
}

上級ユーザーは、単一コマンドハンドラー ON_COMMAND_RANGE または ON_COMMAND_RANGE_EX を使用することで、コマンドの範囲を処理できます。これらのマクロの詳細については、製品ドキュメントを参照してください。

Note

ClassWizard は、ON_COMMAND および ON_UPDATE_COMMAND_UI ハンドラーの作成をサポートしていますが、ON_COMMAND_EX およびON_COMMAND_RANGE ハンドラーの作成はサポートしていません。ただし、Class Wizard は、4 つのコマンドハンドラーバリアントをすべて解析し、閲覧できるようにします。

コントロール通知メッセージ

子コントロールからウィンドウに送信されるメッセージには、そのメッセージマップエントリ内にコントロール ID という追加情報が含まれます。メッセージマップエントリ内で指定されたメッセージハンドラーは、次の条件が満たされている場合にのみ呼び出されます。

BN_CLICKED などのコントロール通知コード (lParam の上位ワード) が、メッセージマップエントリ内で指定された通知コードと一致する。
コントロール ID (wParam) が、メッセージマップエントリ内で指定されたコントロール ID と一致する。

カスタムコントロール通知メッセージは、ON_CONTROL マクロを使用して、カスタム通知コードを含むメッセージマップエントリを定義する場合があります。このマクロの形式は次のとおりです

ON_CONTROL(wNotificationCode, id, memberFxn)

高度な使用として、ON_CONTROL_RANGE を使って、同じハンドラーを持つコントロールの範囲から特定のコントロール通知を処理することができます。

Note

ClassWizard は、ユーザーインターフェイス内での ON_CONTROL または ON_CONTROL_RANGE ハンドラーの作成をサポートしていません。これらはテキストエディターを使用して、手動で入力する必要があります。 ClassWizard は、これらのエントリを解析して、他のメッセージマップエントリと同じように参照できるようにします。

Windows コモンコントロールは、複雑なコントロール通知に対して、より強力な WM_NOTIFY を使用します。このバージョンの MFC は、ON_NOTIFY マクロと ON_NOTIFY_RANGE マクロを使って、この新しいメッセージを直接サポートしています。これらのマクロの詳細については、製品ドキュメントを参照してください。

次の方法で共有

テクニカルノート 6: メッセージマップ

問題

概要

メッセージマップの定義

ユーザー定義 Windows メッセージ

登録済み Windows メッセージ

コマンドメッセージ

コントロール通知メッセージ

関連項目

フィードバック

その他のリソース

次の方法で共有

テクニカル ノート 6: メッセージ マップ

問題

概要

メッセージ マップの定義

ユーザー定義 Windows メッセージ

登録済み Windows メッセージ

コマンド メッセージ

コントロール通知メッセージ

関連項目

フィードバック

その他のリソース

テクニカルノート 6: メッセージマップ

メッセージマップの定義

コマンドメッセージ