Funzione SetForegroundWindow (winuser.h)

Articolo
03/13/2024

Porta in primo piano il thread che ha creato la finestra specificata e attiva la finestra. L'input della tastiera viene indirizzato alla finestra e vengono modificati vari segnali visivi per l'utente. Il sistema assegna una priorità leggermente più alta al thread che ha creato la finestra in primo piano rispetto ad altri thread.

Sintassi

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Parametri

[in] hWnd

Tipo: HWND

Handle per la finestra che deve essere attivata e portata in primo piano.

Valore restituito

Tipo: BOOL

Se la finestra è stata portata in primo piano, il valore restituito è diverso da zero.

Se la finestra non è stata portata in primo piano, il valore restituito è zero.

Commenti

Il sistema limita i processi che possono impostare la finestra in primo piano. Un processo può impostare la finestra in primo piano chiamando SetForegroundWindow solo se:

Tutte le condizioni seguenti sono vere:
- Il processo chiamante appartiene a un'applicazione desktop, non a un'app UWP o a un'app di Windows Store progettata per Windows 8 o 8.1.
- Il processo in primo piano non ha disabilitato le chiamate a SetForegroundWindow tramite una chiamata precedente alla funzione LockSetForegroundWindow .
- Il timeout del blocco in primo piano è scaduto (vedere SPI_GETFOREGROUNDLOCKTIMEOUT in SystemParametersInfo).
- Nessun menu attivo.
Inoltre, almeno una delle condizioni seguenti è vera:
- Il processo chiamante è il processo in primo piano.
- Il processo chiamante è stato avviato dal processo in primo piano.
- Attualmente non è presente alcuna finestra in primo piano e pertanto non esiste alcun processo in primo piano.
- Il processo chiamante ha ricevuto l'ultimo evento di input.
- Il processo in primo piano o il processo chiamante viene sottoposto a debug.

È possibile che un processo venga negato il diritto di impostare la finestra in primo piano anche se soddisfa queste condizioni.

Un'applicazione non può forzare una finestra in primo piano mentre l'utente utilizza un'altra finestra. Windows lampeggia invece il pulsante della barra delle applicazioni della finestra per notificare all'utente.

Un processo in grado di impostare la finestra in primo piano può consentire a un altro processo di impostare la finestra in primo piano chiamando la funzione AllowSetForegroundWindow . Il processo specificato dal parametro dwProcessId per AllowSetForegroundWindow perde la possibilità di impostare la finestra in primo piano alla successiva generazione dell'input da parte dell'utente, a meno che l'input non venga indirizzato a tale processo o alla successiva chiamata a AllowSetForegroundWindow, a meno che non venga specificato lo stesso processo della chiamata precedente a AllowSetForegroundWindow.

Il processo in primo piano può disabilitare le chiamate a SetForegroundWindow chiamando la funzione LockSetForegroundWindow .

Esempio

L'esempio di codice seguente illustra l'uso di 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll
Set di API	ext-ms-win-ntuser-window-l1-1-0 (introdotto in Windows 8)