Fungsi SetForegroundWindow (winuser.h)

Artikel
03/09/2024

Membawa utas yang membuat jendela yang ditentukan ke latar depan dan mengaktifkan jendela. Input keyboard diarahkan ke jendela, dan berbagai isti visual diubah untuk pengguna. Sistem menetapkan prioritas yang sedikit lebih tinggi ke utas yang membuat jendela latar depan daripada utas lainnya.

Sintaks

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Parameter

[in] hWnd

Jenis: HWND

Handel ke jendela yang harus diaktifkan dan dibawa ke latar depan.

Nilai kembali

Jenis: BOOL

Jika jendela dibawa ke latar depan, nilai yang dikembalikan bukan nol.

Jika jendela tidak dibawa ke latar depan, nilai yang dikembalikan adalah nol.

Keterangan

Sistem membatasi proses mana yang dapat mengatur jendela latar depan. Proses dapat mengatur jendela latar depan dengan memanggil SetForegroundWindow hanya jika:

Semua kondisi berikut ini benar:
- Proses panggilan milik aplikasi desktop, bukan aplikasi UWP atau aplikasi Windows Store yang dirancang untuk Windows 8 atau 8.1.
- Proses latar depan belum menonaktifkan panggilan ke SetForegroundWindow dengan panggilan sebelumnya ke fungsi LockSetForegroundWindow .
- Batas waktu kunci latar depan telah kedaluwarsa (lihat SPI_GETFOREGROUNDLOCKTIMEOUT di SystemParametersInfo).
- Tidak ada menu yang aktif.
Selain itu, setidaknya salah satu kondisi berikut ini benar:
- Proses panggilan adalah proses latar depan.
- Proses panggilan dimulai oleh proses latar depan.
- Saat ini tidak ada jendela latar depan, dan dengan demikian tidak ada proses latar depan.
- Proses panggilan menerima peristiwa input terakhir.
- Baik proses latar depan atau proses panggilan sedang di-debug.

Dimungkinkan bagi proses untuk ditolak hak untuk mengatur jendela latar depan bahkan jika memenuhi kondisi ini.

Aplikasi tidak dapat memaksa jendela ke latar depan saat pengguna bekerja dengan jendela lain. Sebagai gantinya, Windows mem-flash tombol taskbar jendela untuk memberi tahu pengguna.

Proses yang dapat mengatur jendela latar depan dapat memungkinkan proses lain untuk mengatur jendela latar depan dengan memanggil fungsi AllowSetForegroundWindow . Proses yang ditentukan oleh parameter dwProcessId ke AllowSetForegroundWindow kehilangan kemampuan untuk mengatur jendela latar depan lain kali pengguna menghasilkan input, kecuali input diarahkan pada proses tersebut, atau kali berikutnya proses memanggil AllowSetForegroundWindow, kecuali proses yang sama ditentukan seperti dalam panggilan sebelumnya ke AllowSetForegroundWindow.

Proses latar depan dapat menonaktifkan panggilan ke SetForegroundWindow dengan memanggil fungsi LockSetForegroundWindow .

Contoh

Contoh kode berikut menunjukkan penggunaan 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;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-ntuser-window-l1-1-0 (diperkenalkan dalam Windows 8)