Função SetForegroundWindow (winuser.h)

Artigo
03/13/2024

Traz o thread que criou a janela especificada para o primeiro plano e ativa a janela. A entrada do teclado é direcionada para a janela e várias indicações visuais são alteradas para o usuário. O sistema atribui uma prioridade um pouco maior ao thread que criou a janela em primeiro plano do que a outros threads.

Sintaxe

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Parâmetros

[in] hWnd

Digite: HWND

Um identificador para a janela que deve ser ativado e levado para o primeiro plano.

Retornar valor

Tipo: BOOL

Se a janela foi trazida para o primeiro plano, o valor retornado é diferente de zero.

Se a janela não tiver sido trazida para o primeiro plano, o valor retornado será zero.

Comentários

O sistema restringe quais processos podem definir a janela em primeiro plano. Um processo pode definir a janela em primeiro plano chamando SetForegroundWindow somente se:

Todas as seguintes condições são verdadeiras:
- O processo de chamada pertence a um aplicativo da área de trabalho, não a um aplicativo UWP ou a um aplicativo da Windows Store projetado para Windows 8 ou 8.1.
- O processo em primeiro plano não desabilitou as chamadas para SetForegroundWindow por uma chamada anterior para a função LockSetForegroundWindow .
- O tempo limite de bloqueio em primeiro plano expirou (consulte SPI_GETFOREGROUNDLOCKTIMEOUT em SystemParametersInfo).
- Nenhum menu está ativo.
Além disso, pelo menos uma das seguintes condições é verdadeira:
- O processo de chamada é o processo em primeiro plano.
- O processo de chamada foi iniciado pelo processo em primeiro plano.
- Atualmente, não há nenhuma janela em primeiro plano e, portanto, nenhum processo em primeiro plano.
- O processo de chamada recebeu o último evento de entrada.
- O processo em primeiro plano ou o processo de chamada está sendo depurado.

É possível que um processo seja negado o direito de definir a janela em primeiro plano, mesmo que ela atenda a essas condições.

Um aplicativo não pode forçar uma janela para o primeiro plano enquanto o usuário está trabalhando com outra janela. Em vez disso, o Windows exibe o botão da barra de tarefas da janela para notificar o usuário.

Um processo que pode definir a janela em primeiro plano pode habilitar outro processo para definir a janela em primeiro plano chamando a função AllowSetForegroundWindow . O processo especificado pelo parâmetro dwProcessId para AllowSetForegroundWindow perde a capacidade de definir a janela em primeiro plano na próxima vez que o usuário gerar entrada, a menos que a entrada seja direcionada para esse processo, ou na próxima vez que um processo chamar AllowSetForegroundWindow, a menos que o mesmo processo seja especificado como na chamada anterior para AllowSetForegroundWindow.

O processo em primeiro plano pode desabilitar chamadas para SetForegroundWindow chamando a função LockSetForegroundWindow .

Exemplo

O exemplo de código a seguir demonstra o 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	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-window-l1-1-0 (introduzido no Windows 8)