MessageBox 函式 (winuser.h)

顯示模式對話框，其中包含系統圖示、一組按鈕，以及簡短的應用程式特定訊息，例如狀態或錯誤資訊。 消息框會傳回整數值，指出使用者按下的按鈕。

語法

int MessageBox(
  [in, optional] HWND    hWnd,
  [in, optional] LPCTSTR lpText,
  [in, optional] LPCTSTR lpCaption,
  [in]           UINT    uType
);

參數

[in, optional] hWnd

類型： HWND

要建立之消息框之擁有者視窗的句柄。 如果此參數為 NULL，消息框沒有擁有者視窗。

[in, optional] lpText

類型： LPCTSTR

要顯示的訊息。 如果字串包含一行以上，您可以使用每一行之間的歸位字元和/或換行字元分隔行。

[in, optional] lpCaption

類型： LPCTSTR

對話框標題。 如果此參數為 NULL，則預設標題為 Error。

[in] uType

類型： UINT

對話框的內容和行為。 這個參數可以是下列旗標群組中的旗標組合。

若要指出消息框中顯示的按鈕，請指定下列其中一個值。

值	意義
MB_ABORTRETRYIGNORE 0x00000002L	消息框包含三個按鈕： 中止、 重試和 忽略。
MB_CANCELTRYCONTINUE 0x00000006L	消息框包含三個按鈕： [取消]、[ 再試一次]、 [繼續]。 使用此消息框類型，而不是MB_ABORTRETRYIGNORE。
MB_HELP 0x00004000L	將 [說明 ] 按鈕新增至消息框。 當使用者按 鍵按一 次按 F1 時，系統會傳送 WM_HELP 訊息給擁有者。
MB_OK 0x00000000L	消息框包含一個按鈕： [確定]。 此為預設值。
MB_OKCANCEL 0x00000001L	消息框包含兩個按鈕： [確定 ] 和 [ 取消]。
MB_RETRYCANCEL 0x00000005L	消息框包含兩個按鈕： 重試 和 取消。
MB_YESNO 0x00000004L	消息框包含兩個按鈕： [是 ] 和 [ 否]。
MB_YESNOCANCEL 0x00000003L	消息框包含三個按鈕： [是]、 [否] 和 [取消]。

 

若要在消息框中顯示圖示，請指定下列其中一個值。

值	意義
MB_ICONEXCLAMATION 0x00000030L	消息框中會出現驚嘆號圖示。
MB_ICONWARNING 0x00000030L	消息框中會出現驚嘆號圖示。
MB_ICONINFORMATION 0x00000040L	由圓形中的小寫字母 i 所組成的圖示會出現在消息框中。
MB_ICONASTERISK 0x00000040L	由圓形中的小寫字母 i 所組成的圖示會出現在消息框中。
MB_ICONQUESTION 0x00000020L	消息框中會出現問號圖示。 我們不再建議使用問號的訊息圖示，因為它並未清楚表示特定類型的訊息，且問題訊息的措辭適用於各種訊息。 此外，使用者可能會將訊息符號的問號與「說明」資訊搞混。 因此，請勿在您的訊息方塊中使用這個問號訊息符號。 系統繼續支援將其納入，只為回溯相容性之用。
MB_ICONSTOP 0x00000010L	消息框中會出現停止簽署圖示。
MB_ICONERROR 0x00000010L	消息框中會出現停止簽署圖示。
MB_ICONHAND 0x00000010L	消息框中會出現停止簽署圖示。

 

若要指出預設按鈕，請指定下列其中一個值。

值	意義
MB_DEFBUTTON1 0x00000000L	第一個按鈕是預設按鈕。 除非指定MB_DEFBUTTON2、MB_DEFBUTTON3或MB_DEFBUTTON4，否則MB_DEFBUTTON1是預設值。
MB_DEFBUTTON2 0x00000100L	第二個按鈕是預設按鈕。
MB_DEFBUTTON3 0x00000200L	第三個按鈕是預設按鈕。
MB_DEFBUTTON4 0x00000300L	第四個按鈕是預設按鈕。

 

若要指出對話方塊的形式，請指定下列其中一個值。

值	意義
MB_APPLMODAL 0x00000000L	用戶必須先回應消息框，才能繼續在 hWnd 參數所識別的視窗中工作。 不過，使用者可以移至其他線程的視窗，並在這些視窗中運作。 視應用程式中的視窗階層而定，使用者可能能夠移至線程內的其他視窗。 消息框父系的所有子視窗都會自動停用，但彈出視窗不是。 如果未指定MB_SYSTEMMODAL或MB_TASKMODAL，則MB_APPLMODAL為預設值。
MB_SYSTEMMODAL 0x00001000L	與MB_APPLMODAL相同，不同之處在於消息框具有 WS_EX_TOPMOST 樣式。 使用系統強制回應消息框來通知用戶發生嚴重、潛在的損害錯誤，例如立即注意 (，例如記憶體不足) 。 此旗標不會影響使用者與 與 hWnd 相關聯視窗以外的窗口互動。
MB_TASKMODAL 0x00002000L	與 MB_APPLMODAL相同， 不同之處在於 如果 hWnd 參數為 NULL，則會停用屬於目前線程的所有最上層視窗。 當呼叫的應用程式或連結庫沒有可用的視窗句柄，但仍需要防止呼叫線程中的其他視窗輸入，而不暫停其他線程時，請使用此旗標。

 

若要指定其他選項，請使用下列一或多個值。

值	意義
MB_DEFAULT_DESKTOP_ONLY 0x00020000L	與互動式視窗月臺的桌面相同。 如需詳細資訊，請參閱 視窗月臺。 如果目前的輸入桌面不是預設桌面， 則 MessageBox 不會在使用者切換至預設桌面之前傳回。
MB_RIGHT 0x00080000L	文字靠右對齊。
MB_RTLREADING 0x00100000L	在希伯來文和阿拉伯文系統上，使用由右至左閱讀順序顯示訊息和 標題 文字。
MB_SETFOREGROUND 0x00010000L	消息框會變成前景視窗。 在內部，系統會呼叫消息框的 SetForegroundWindow 函式。
MB_TOPMOST 0x00040000L	消息框是以 窗口樣式WS_EX_TOPMOST 建立。
MB_SERVICE_NOTIFICATION 0x00200000L	呼叫者是一個會通知使用者發生事件的服務。 函式會顯示目前使用中桌面上的消息框，即使沒有使用者登入計算機也一樣。 終端機服務： 如果呼叫線程具有模擬令牌，函式會將消息框導向至模擬令牌中指定的會話。 如果設定此旗標， hWnd 參數必須是 NULL。 這可讓消息框出現在桌面上，而不是對應至 hWnd 的桌面。 如需有關使用此旗標之安全性考慮的資訊，請參閱 互動式服務。 特別是請注意，此旗標可以在鎖定的桌面上產生互動式內容，因此應該只用於一組非常有限的案例，例如資源耗盡。

傳回值

類型： int

如果消息框有 [取消] 按鈕，則函式會在按下 ESC 鍵或選取 [取消] 按鈕時傳回 IDCANCEL 值。 如果消息框沒有 [取消] 按鈕，除非有MB_OK按鈕，否則按下 ESC 不會有任何作用。 如果顯示MB_OK按鈕，且使用者按下 ESC 鍵，則傳回值會是 IDOK。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果函式成功，傳回值就是下列其中一個功能表項值。

傳回碼/值	Description
IDABORT 3	已選取 [中止] 按鈕。
IDCANCEL 2	已選取 [取消] 按鈕。
IDCONTINUE 11	已選取 [ 繼續 ] 按鈕。
IDIGNORE 5	已選取 [忽略] 按鈕。
IDNO 7	已選取 [否] 按鈕。
IDOK 1	已選取 [ 確定 ] 按鈕。
IDRETRY 4	已選取 [重試] 按鈕。
IDTRYAGAIN 10	已選取 [重試] 按鈕。
IDYES 6	已選取 [ 是 ] 按鈕。

備註

將 uType 參數設定為對應的旗標值，即可在消息框中使用下列系統圖示。

圖示	旗標值
	MB_ICONHAND、 MB_ICONSTOP或 MB_ICONERROR
	MB_ICONQUESTION
	MB_ICONEXCLAMATION 或 MB_ICONWARNING
	MB_ICONASTERISK 或 MB_ICONINFORMATION

 

在 MessageBox 顯示字串開頭的 Unicode 格式化字元 U+200F 所表示，將兩個由右至左標記新增 (RL) M，由 MessageBox 轉譯引擎解譯，以便讓 MessageBox 的讀取順序轉譯為由右至左 (RTL) 。

當您使用系統強制回應消息框來指出系統記憶體不足時， lpText 和 lpCaption 參數所指向的字串不應該從資源檔取得，因為嘗試載入資源可能會失敗。

如果您在對話方塊存在時建立訊息框，請使用對話框的句柄做為 hWnd 參數。 hWnd 參數不應該識別子視窗，例如對話框中的控件。

範例

在下列範例中，應用程式會顯示消息框，在發生錯誤狀況之後提示使用者輸入動作。 消息框會顯示描述錯誤狀況以及如何解決的訊息。 MB_CANCELTRYCONTINUE樣式會指示 MessageBox 提供三個按鈕，讓使用者可以選擇如何繼續。 MB_DEFBUTTON2樣式會將預設焦點設定為消息框的第二個按鈕，在此案例中為 [再試] 按鈕。

int DisplayResourceNAMessageBox()
{
    int msgboxID = MessageBox(
        NULL,
        (LPCWSTR)L"Resource not available\nDo you want to try again?",
        (LPCWSTR)L"Account Details",
        MB_ICONWARNING | MB_CANCELTRYCONTINUE | MB_DEFBUTTON2
    );

    switch (msgboxID)
    {
    case IDCANCEL:
        // TODO: add code
        break;
    case IDTRYAGAIN:
        // TODO: add code
        break;
    case IDCONTINUE:
        // TODO: add code
        break;
    }

    return msgboxID;
}

下圖顯示此程式代碼範例的輸出：

如需另一個消息框範例，請參閱 顯示消息框。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	winuser.h (包含 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-dialogbox-l1-1-0 (於 Windows 8)

另請參閱

概念

對話框

FlashWindow

MessageBeep

MessageBoxEx

MessageBoxIndirect

其他資源

參考

SetForegroundWindow