SetForegroundWindow, fonction (winuser.h)

Article
03/11/2023

Place le thread qui a créé la fenêtre spécifiée au premier plan et active la fenêtre. L’entrée au clavier est dirigée vers la fenêtre, et divers signaux visuels sont modifiés pour l’utilisateur. Le système attribue une priorité légèrement plus élevée au thread qui a créé la fenêtre de premier plan qu’à d’autres threads.

Syntaxe

BOOL SetForegroundWindow(
  [in] HWND hWnd
);

Paramètres

[in] hWnd

Type : HWND

Handle de la fenêtre qui doit être activée et portée au premier plan.

Valeur retournée

Type : BOOL

Si la fenêtre a été mise au premier plan, la valeur de retour est différente de zéro.

Si la fenêtre n’a pas été portée au premier plan, la valeur de retour est zéro.

Remarques

Le système restreint les processus qui peuvent définir la fenêtre de premier plan. Un processus peut définir la fenêtre de premier plan en appelant SetForegroundWindow uniquement si :

Toutes les conditions suivantes sont remplies :
- Le processus d’appel appartient à une application de bureau, et non à une application UWP ou à une application du Windows Store conçue pour Windows 8 ou 8.1.
- Le processus de premier plan n’a pas désactivé les appels à SetForegroundWindow par un appel précédent à la fonction LockSetForegroundWindow .
- Le délai d’expiration du verrouillage de premier plan a expiré (voir SPI_GETFOREGROUNDLOCKTIMEOUT dans SystemParametersInfo).
- Aucun menu n’est actif.
En outre, au moins l’une des conditions suivantes est remplie :
- Le processus appelant est le processus de premier plan.
- Le processus d’appel a été démarré par le processus de premier plan.
- Il n’existe actuellement aucune fenêtre de premier plan et donc aucun processus de premier plan.
- Le processus appelant a reçu le dernier événement d’entrée.
- Le processus de premier plan ou le processus appelant est en cours de débogage.

Il est possible qu’un processus se voit refuser le droit de définir la fenêtre de premier plan même si elle remplit ces conditions.

Une application ne peut pas forcer une fenêtre au premier plan pendant que l’utilisateur travaille avec une autre fenêtre. Au lieu de cela, Windows clignote le bouton de la barre des tâches de la fenêtre pour avertir l’utilisateur.

Un processus qui peut définir la fenêtre de premier plan peut permettre à un autre processus de définir la fenêtre de premier plan en appelant la fonction AllowSetForegroundWindow . Le processus spécifié par le paramètre dwProcessId sur AllowSetForegroundWindow perd la possibilité de définir la fenêtre de premier plan la prochaine fois que l’utilisateur génère une entrée, sauf si l’entrée est dirigée vers ce processus, ou la prochaine fois qu’un processus appelle AllowSetForegroundWindow, sauf si le même processus est spécifié comme dans l’appel précédent à AllowSetForegroundWindow.

Le processus de premier plan peut désactiver les appels à SetForegroundWindow en appelant la fonction LockSetForegroundWindow .

Exemple

L’exemple de code suivant illustre l’utilisation 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;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll
Ensemble d’API	ext-ms-win-ntuser-window-l1-1-0 (introduit dans Windows 8)