SetConsoleWindowInfo Funktion

Artikel
12/15/2023

Wichtig

In diesem Dokument werden Konsolenplattformfunktionen beschrieben, die nicht mehr Teil unserer Ökosystem-Roadmap sind. Wir empfehlen nicht, diesen Inhalt in neuen Produkten zu verwenden, aber wir werden weiterhin vorhandene Nutzungen für die unbegrenzte Zukunft unterstützen. Unsere bevorzugte moderne Lösung konzentriert sich auf virtuelle Terminalsequenzen für maximale Kompatibilität in plattformübergreifenden Szenarien. Weitere Informationen zu dieser Designentscheidung finden Sie in unserem Dokument klassische Konsole im Vergleich zum virtuellen Terminal.

Legt die aktuelle Größe und Position des Fensters eines Konsolenbildschirmpuffers fest.

Syntax

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

Parameter

hConsoleOutput [in]
Ein Handle für den Konsolenbildschirm-Puffer. Das Handle muss über das Zugriffsrecht GENERIC_READ verfügen. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Konsolenpuffer.

bAbsolute [in]
Wenn dieser Parameter TRUEist, geben die Koordinaten die neuen oberen linken und unteren rechten Ecken des Fensters an. Wenn dies FALSE ist, sind die Koordinaten relativ zu den aktuellen Fenstereckekoordinaten.

lpConsoleWindow [in]
Ein Zeiger auf eine SMALL_RECT Struktur, die die neuen oberen linken und unteren rechten Ecken des Fensters angibt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die Funktion schlägt fehl, wenn das angegebene Fensterrechteck über die Grenzen des Konsolenbildschirmpuffers hinausgeht. Dies bedeutet, dass die Oberen und Linken Mitglieder des Rechtecks lpConsoleWindow (oder die berechneten oberen und linken Koordinaten, wenn bAbsolute FALSE ist) nicht kleiner als null sein können. Entsprechend können die Unteren und Rechten Mitglieder (oder die berechneten unteren und rechten Koordinaten) nicht größer als (Bildschirmpufferhöhe – 1) bzw. (Bildschirmpufferbreite – 1) sein. Die Funktion schlägt auch fehl, wenn das Rechte Mitglied (oder die berechnete rechte Koordinate) kleiner oder gleich dem Linken Mitglied (oder berechneten linken Koordinate) ist oder das Untere Mitglied (oder die berechnete untere Koordinate) kleiner oder gleich dem Oberen Mitglied (oder berechneten oberen Koordinate) ist.

Bei Konsolen mit mehr als einem Bildschirmpuffer wirkt sich das Ändern der Fensterposition für einen Bildschirmpuffer nicht auf die Fensterpositionen der anderen Bildschirmpuffer aus.

Um die aktuelle Größe und Position des Fensters eines Bildschirmpuffers zu bestimmen, verwenden Sie die Funktion GetConsoleScreenBufferInfo. Diese Funktion gibt auch die maximale Größe des Fensters zurück, je nach aktueller Bildschirmpuffergröße, dem aktuellen Schriftgrad und dem Bildschirmformat. Die GetLargestConsoleWindowSize-Funktion gibt die maximale Fenstergröße für die aktuelle Schriftart und die Bildschirmgrößen zurück, berücksichtigt jedoch nicht die Größe des Konsolenbildschirmpuffers.

SetConsoleWindowInfo kann verwendet werden, um den Inhalt des Konsolenbildschirmpuffers zu scrollen, indem die Position des Fensterrechtecks verschoben wird, ohne seine Größe zu ändern.

Tipp

Diese API wird nicht empfohlen und verfügt nicht über eine virtuelle Terminal-Entsprechung. Diese Entscheidung richtet die Windows-Plattform absichtlich mit anderen Betriebssystemen aus, auf denen dem Benutzer die volle Kontrolle über diese Präsentationsoption gewährt wird. Anwendungen, die über plattformübergreifende Dienstprogramme und Transporte wie SSH remoten, funktionieren möglicherweise nicht wie erwartet, wenn Sie diese API verwenden.

Beispiele

Ein Beispiel finden Sie unter Scrollen des Fensters eines Bildschirmpuffers.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Header	ConsoleApi2.h (über WinCon.h, Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll