Fonction SetConsoleWindowInfo

Article
12/15/2023

Important

Ce document décrit les fonctionnalités de la plateforme de console qui ne font plus partie de notre feuille de route de l’écosystème. Nous vous déconseillons d’utiliser ce contenu dans de nouveaux produits, mais nous continuerons prendre en charge des utilisations existantes pour l’avenir indéterminé. Notre solution moderne préférée se concentre sur les séquences de terminal virtuel pour une compatibilité maximale dans les scénarios multiplateformes. Vous trouverez plus d’informations sur cette décision de conception dans notre document console classique versus terminal virtuel.

Définit la taille et la position actuelles de la fenêtre de la mémoire tampon d’écran d’une console.

Syntaxe

BOOL WINAPI SetConsoleWindowInfo(
  _In_       HANDLE     hConsoleOutput,
  _In_       BOOL       bAbsolute,
  _In_ const SMALL_RECT *lpConsoleWindow
);

Paramètres

hConsoleOutput [entrée]
Handle vers la mémoire tampon d’écran de console. Le handle doit avoir le droit d’accès GENERIC_READ. Pour plus d’informations, consultez Sécurité de la mémoire tampon et droits d’accès d’une console.

bAbsolute [entrée]
Si ce paramètre a la valeur VRAI, les coordonnées spécifient les nouveaux angles supérieur gauche et inférieur droit de la fenêtre. Si la valeur est FAUX, les coordonnées sont relatives aux coordonnées actuelles de l’angle de la fenêtre.

lpConsoleWindow [entrée]
Un pointeur vers une structure SMALL_RECT qui spécifie les nouveaux angles supérieur gauche et inférieur droit de la fenêtre.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

La fonction échoue si le rectangle de fenêtre spécifié s’étend au-delà des limites de la mémoire tampon de l’écran de la console. Cela signifie que les membres Haut et Gauche du rectangle lpConsoleWindow (ou les coordonnées supérieure et gauche calculées, si bAbsolute est FAUX) ne peuvent pas être inférieurs à zéro. De même, les membres Bas et Droite (ou les coordonnées inférieure et droite calculées) ne peuvent pas être supérieurs à (hauteur de la mémoire tampon d’écran – 1) et (largeur de la mémoire tampon d’écran – 1), respectivement. La fonction échoue également si le membre Droite (ou la coordonnée droite calculée) est inférieur ou égal au membre Gauche (ou la coordonnée gauche calculée) ou si le membre Bas (ou la coordonnée inférieure calculée) est inférieur ou égal au membre Haut (ou la coordonnée supérieure calculée).

Pour les consoles avec plusieurs mémoires tampons d’écran, la modification de l’emplacement de la fenêtre pour une mémoire tampon d’écran n’affecte pas les emplacements de fenêtre des autres mémoires tampons d’écran.

Pour déterminer la taille et la position actuelles de la fenêtre de mémoire tampon d’écran, utilisez la fonction GetConsoleScreenBufferInfo. Cette fonction retourne également la taille maximale de la fenêtre, compte tenu de la taille actuelle de la mémoire tampon d’écran, de la taille de police actuelle et de la taille de l’écran. La fonction GetLargestConsoleWindowSize retourne la taille maximale de la fenêtre en fonction de la police et des tailles d’écran actuelles, mais elle ne tient pas compte de la taille de la mémoire tampon d’écran de la console.

SetConsoleWindowInfo peut être utilisé pour faire défiler le contenu de la mémoire tampon d’écran de la console en déplaçant la position du rectangle de fenêtre sans modifier sa taille.

Conseil

Cette API n’est pas recommandée et n’a pas d’équivalent au terminal virtuel. Cette décision aligne intentionnellement la plateforme Windows avec d’autres systèmes d’exploitation où l’utilisateur dispose d’un contrôle total sur cette option de présentation. Le remoting des applications via des utilitaires multiplateformes et des transports comme SSH peut ne pas fonctionner comme prévu si vous utilisez cette API.

Exemples

Pour obtenir un exemple, consultez Défilement de la fenêtre d’une mémoire tampon d’écran.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
En-tête	ConsoleApi2.h (via WinCon.h, inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll