SetForegroundWindow-Funktion (winuser.h)

Artikel
03/04/2024

Versetzt den Thread, der das angegebene Fenster erstellt hat, in den Vordergrund und aktiviert das Fenster. Die Tastatureingabe wird an das Fenster weitergeleitet, und es werden verschiedene visuelle Hinweise für den Benutzer geändert. Das System weist dem Thread, der das Vordergrundfenster erstellt hat, eine etwas höhere Priorität zu als anderen Threads.

Syntax

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Parameter

[in] hWnd

Typ: HWND

Ein Handle für das Fenster, das aktiviert und in den Vordergrund gebracht werden soll.

Rückgabewert

Typ: BOOL

Wenn das Fenster in den Vordergrund geholt wurde, ist der Rückgabewert ungleich null.

Wenn das Fenster nicht in den Vordergrund gebracht wurde, ist der Rückgabewert null.

Hinweise

Das System schränkt ein, welche Prozesse das Vordergrundfenster festlegen können. Ein Prozess kann das Vordergrundfenster durch Aufrufen von SetForegroundWindow nur dann festlegen, wenn:

Alle folgenden Bedingungen sind erfüllt:
- Der Aufrufprozess gehört zu einer Desktopanwendung, nicht zu einer UWP-App oder einer Windows Store-App, die für Windows 8 oder 8.1 entwickelt wurde.
- Der Vordergrundprozess hat Aufrufe von SetForegroundWindow durch einen vorherigen Aufruf der LockSetForegroundWindow-Funktion nicht deaktiviert.
- Das Timeout für die Vordergrundsperre ist abgelaufen (siehe SPI_GETFOREGROUNDLOCKTIMEOUT in SystemParametersInfo).
- Es sind keine Menüs aktiv.
Darüber hinaus gilt mindestens eine der folgenden Bedingungen:
- Der aufrufende Prozess ist der Vordergrundprozess.
- Der aufrufende Prozess wurde vom Vordergrundprozess gestartet.
- Es gibt derzeit kein Vordergrundfenster und somit keinen Vordergrundprozess.
- Der aufrufende Prozess hat das letzte Eingabeereignis empfangen.
- Entweder der Vordergrundprozess oder der aufrufende Prozess wird debuggt.

Es ist möglich, dass einem Prozess das Recht zum Festlegen des Vordergrundfensters verweigert wird, auch wenn er diese Bedingungen erfüllt.

Eine Anwendung kann kein Fenster im Vordergrund erzwingen, während der Benutzer mit einem anderen Fenster arbeitet. Stattdessen blinkt Windows die Taskleistenschaltfläche des Fensters, um den Benutzer zu benachrichtigen.

Ein Prozess, der das Vordergrundfenster festlegen kann, kann es einem anderen Prozess ermöglichen, das Vordergrundfenster festzulegen, indem die AllowSetForegroundWindow-Funktion aufgerufen wird . Der durch den dwProcessId-Parameter auf AllowSetForegroundWindow angegebene Prozess verliert die Fähigkeit, das Vordergrundfenster festzulegen, wenn der Benutzer das nächste Mal Eingaben generiert, es sei denn, die Eingabe wird an diesen Prozess gerichtet, oder wenn ein Prozess das nächste Mal AllowSetForegroundWindow aufruft, es sei denn, derselbe Prozess wurde wie im vorherigen Aufruf von AllowSetForegroundWindow angegeben.

Der Vordergrundprozess kann Aufrufe von SetForegroundWindow deaktivieren, indem die LockSetForegroundWindow-Funktion aufgerufen wird .

Beispiel

Im folgenden Codebeispiel wird die Verwendung von SetForegroundWindow veranschaulicht.

// 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;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-window-l1-1-0 (eingeführt in Windows 8)