SetForegroundWindow 函式 (winuser.h)

發行項
03/09/2024

將建立指定視窗的線程帶入前景，並啟動視窗。鍵盤輸入會導向至視窗，而用戶會變更各種視覺提示。系統會將稍微較高的優先順序指派給建立前景窗口的線程，而不是其他線程。

語法

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

參數

[in] hWnd

類型： HWND

視窗的句柄，應啟動並帶至前景。

傳回值

類型： BOOL

如果視窗被帶至前景，則傳回值為非零值。

如果視窗未帶入前景，則傳回值為零。

備註

系統會限制哪些進程可以設定前景視窗。只有在下列狀況時，進程才能呼叫 SetForegroundWindow 來設定前景視窗：

下列所有條件都成立：
- 呼叫程式屬於傳統型應用程式，而不是針對 Windows 8 或 8.1 設計的 UWP 應用程式或 Windows 市集應用程式。
- 前景進程尚未停用對 SetForegroundWindow 的呼叫，前一次呼叫 LockSetForegroundWindow 函式。
- 前景鎖定逾時已過期， (請參閱 SystemParametersInfo) 中的SPI_GETFOREGROUNDLOCKTIMEOUT。
- 沒有作用中的功能表。
此外，至少下列其中一個條件成立：
- 呼叫進程是前景進程。
- 呼叫進程是由前景進程啟動。
- 目前沒有前景視窗，因此沒有前景進程。
- 呼叫行程收到最後一個輸入事件。
- 正在偵錯前景進程或呼叫進程。

即使程式符合這些條件，還是可能會拒絕設定前景窗口的許可權。

當使用者使用另一個視窗時，應用程式無法強制將窗口強制至前景。相反地，Windows 會閃爍視窗的任務欄按鈕來通知使用者。

可以設定前景窗口的進程可以讓另一個進程藉由呼叫 AllowSetForegroundWindow 函式來設定前景視窗。 由 dwProcessId 參數指定給 AllowSetForegroundWindow 的進程會失去下次使用者產生輸入時設定前景視窗的能力，除非該進程導向該進程，或下一次進程呼叫 AllowSetForegroundWindow 時，除非在前一次對 AllowSetForegroundWindow 的呼叫中指定相同的進程。

前景進程可以藉由呼叫 LockSetForegroundWindow 函式來停用對 SetForegroundWindow 的呼叫。

範例

下列程式代碼範例示範 如何使用 SetForegroundWindow

// If the window is invisible we will show it and make it topmost without the
// foreground focus. If the window is visible it will also be made the
// topmost window without the foreground focus. If wParam is TRUE then
// for both cases the window will be forced into the foreground focus
if (uMsg == m_ShowStageMessage) {
    BOOL bVisible = IsWindowVisible(hwnd);
    SetWindowPos(hwnd, HWND_TOP, 0, 0, 0, 0,
                    SWP_NOMOVE | SWP_NOSIZE | SWP_SHOWWINDOW |
                    (bVisible ? SWP_NOACTIVATE : 0));
    // Should we bring the window to the foreground
    if (wParam == TRUE) {
        SetForegroundWindow(hwnd);
    }
    return (LRESULT) 1;
}

規格需求

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