Функция SetForegroundWindow (winuser.h)

Статья
03/11/2023

Переносит поток, создавший указанное окно, на передний план и активирует окно. Ввод с помощью клавиатуры направляется в окно, и для пользователя изменяются различные визуальные подсказки. Система назначает потоку, создавщему окно переднего плана, немного более высокий приоритет, чем другим потокам.

Синтаксис

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Параметры

[in] hWnd

Тип: HWND

Дескриптор окна, которое должно быть активировано и выведено на передний план.

Возвращаемое значение

Тип: BOOL

Если окно было выведено на передний план, возвращаемое значение не равно нулю.

Если окно не было выведено на передний план, возвращаемое значение равно нулю.

Выполняются все следующие условия:
- Процесс вызова принадлежит классическому приложению, а не приложению UWP или приложению Магазина Windows, предназначенному для Windows 8 или 8.1.
- Процесс переднего плана не отключал вызовы SetForegroundWindow предыдущим вызовом функции LockSetForegroundWindow .
- Истекло время ожидания блокировки переднего плана (см . SPI_GETFOREGROUNDLOCKTIMEOUT в SystemParametersInfo).
- Меню не активны.
Кроме того, выполняется по крайней мере одно из следующих условий:
- Вызывающий процесс является процессом переднего плана.
- Вызывающий процесс был запущен процессом переднего плана.
- В настоящее время отсутствует окно переднего плана и, следовательно, процесс переднего плана.
- Вызывающий процесс получил последнее входное событие.
- Выполняется отладка процесса переднего плана или вызывающего процесса.

Процесс может быть лишен права на настройку окна переднего плана, даже если он соответствует этим условиям.

Приложение не может принудительно вывести окно на передний план, пока пользователь работает с другим окном. Вместо этого Windows мигает кнопку панели задач окна, чтобы уведомить пользователя.

Процесс, который может задать окно переднего плана, может позволить другому процессу задать окно переднего плана путем вызова функции AllowSetForegroundWindow . Процесс, заданный параметром dwProcessId для AllowSetForegroundWindow , теряет возможность задать окно переднего плана в следующий раз, когда пользователь создает входные данные, если только входные данные не направлены на этот процесс, или в следующий раз, когда процесс вызывает AllowSetForegroundWindow, если не указан тот же процесс, что и в предыдущем вызове AllowSetForegroundWindow.

Процесс переднего плана может отключить вызовы SetForegroundWindow , вызвав функцию LockSetForegroundWindow .

Пример

В следующем примере кода показано использование 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
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-window-l1-1-0 (представлено в Windows 8)