Función SetForegroundWindow (winuser.h)

Artículo
03/13/2024

Trae el subproceso que creó la ventana especificada en primer plano y activa la ventana. La entrada del teclado se dirige a la ventana y se cambian varias indicaciones visuales para el usuario. El sistema asigna una prioridad ligeramente mayor al subproceso que creó la ventana de primer plano que a otros subprocesos.

Sintaxis

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Parámetros

[in] hWnd

Tipo: HWND

Identificador de la ventana que se debe activar y llevar al primer plano.

Valor devuelto

Tipo: BOOL

Si la ventana se trajo al primer plano, el valor devuelto es distinto de cero.

Si la ventana no se trajo al primer plano, el valor devuelto es cero.

Comentarios

El sistema restringe qué procesos pueden establecer la ventana de primer plano. Un proceso puede establecer la ventana de primer plano llamando a SetForegroundWindow solo si:

Todas las condiciones siguientes son verdaderas:
- El proceso de llamada pertenece a una aplicación de escritorio, no a una aplicación para UWP o a una aplicación de la Tienda Windows diseñada para Windows 8 o 8.1.
- El proceso de primer plano no ha deshabilitado las llamadas a SetForegroundWindow mediante una llamada anterior a la función LockSetForegroundWindow .
- El tiempo de espera de bloqueo en primer plano ha expirado (consulte SPI_GETFOREGROUNDLOCKTIMEOUT en SystemParametersInfo).
- No hay menús activos.
Además, se cumple al menos una de las siguientes condiciones:
- El proceso de llamada es el proceso en primer plano.
- El proceso de llamada se inició mediante el proceso de primer plano.
- Actualmente no hay ninguna ventana de primer plano y, por tanto, no hay ningún proceso de primer plano.
- El proceso de llamada recibió el último evento de entrada.
- Se está depurando el proceso en primer plano o el proceso de llamada.

Es posible denegar un proceso el derecho de establecer la ventana de primer plano incluso si cumple estas condiciones.

Una aplicación no puede forzar una ventana al primer plano mientras el usuario está trabajando con otra ventana. En su lugar, Windows parpadea el botón de la barra de tareas de la ventana para notificar al usuario.

Un proceso que puede establecer la ventana de primer plano puede habilitar otro proceso para establecer la ventana de primer plano llamando a la función AllowSetForegroundWindow . El proceso especificado por el parámetro dwProcessId para AllowSetForegroundWindow pierde la capacidad de establecer la ventana de primer plano la próxima vez que el usuario genera la entrada, a menos que la entrada se dirija a ese proceso o la próxima vez que un proceso llame a AllowSetForegroundWindow, a menos que se especifique el mismo proceso que en la llamada anterior a AllowSetForegroundWindow.

El proceso de primer plano puede deshabilitar las llamadas a SetForegroundWindow llamando a la función LockSetForegroundWindow .

Ejemplo

En el ejemplo de código siguiente se muestra el uso de 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;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-window-l1-1-0 (introducido en Windows 8)