Funzione WriteConsoleOutput

Articolo
12/13/2023

Importante

Questo documento descrive le funzionalità della piattaforma della console che non fanno più parte della roadmap dell'ecosistema. Non è consigliabile usare questo contenuto nei nuovi prodotti, ma continueremo a supportare gli utilizzi esistenti per il futuro indefinito. La soluzione moderna preferita è incentrata sulle sequenze di terminale virtuale per garantire la massima compatibilità negli scenari multipiattaforma. Per altre informazioni su questa decisione di progettazione, vedere il documento relativo alla console classica e al terminale virtuale.

Scrive i dati degli attributi carattere e colore in un blocco rettangolare specificato di celle di caratteri in un buffer dello schermo della console. I dati da scrivere provengono da un blocco rettangolare di dimensioni corrispondenti in una posizione specificata nel buffer di origine.

Sintassi

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

Parametri

hConsoleOutput [in]
Handle per il buffer dello schermo della console. L'handle deve avere il diritto di accesso GENERIC_WRITE . Per altre informazioni, vedere Sicurezza dei buffer della console e diritti di accesso.

lpBuffer [in]
Dati da scrivere nel buffer dello schermo della console. Questo puntatore viene considerato come origine di una matrice bidimensionale di strutture CHAR_INFO le cui dimensioni sono specificate dal parametro dwBufferSize.

dwBufferSize [in]
Dimensioni del buffer a cui punta il parametro lpBuffer , nelle celle di caratteri. Il membro X della struttura COORD è il numero di colonne. Il membro Y è il numero di righe.

dwBufferCoord [in]
Coordinate della cella superiore sinistra nel buffer a cui punta il parametro lpBuffer . Il membro X della struttura COORD è la colonna e il membro Y è la riga.

lpWriteRegion [in, out]
Puntatore a una struttura SMALL_RECT. All'input, i membri della struttura specificano le coordinate in alto a sinistra e in basso a destra del rettangolo del buffer dello schermo della console in cui scrivere. Nell'output, i membri della struttura specificano il rettangolo effettivo utilizzato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Osservazioni:

WriteConsoleOutput considera il buffer di origine e il buffer dello schermo di destinazione come matrici bidimensionali (colonne e righe di celle di caratteri). Il rettangolo a cui punta il parametro lpWriteRegion specifica le dimensioni e la posizione del blocco in cui scrivere nel buffer dello schermo della console. Un rettangolo della stessa dimensione si trova con la cella superiore sinistra in corrispondenza delle coordinate del parametro dwBufferCoord nella matrice lpBuffer . I dati delle celle che si trovano nell'intersezione di questo rettangolo e del rettangolo del buffer di origine (le cui dimensioni sono specificate dal parametro dwBufferSize ) vengono scritti nel rettangolo di destinazione.

Le celle nel rettangolo di destinazione la cui posizione di origine corrispondente si trovano all'esterno dei limiti del rettangolo del buffer di origine non sono interessate dall'operazione di scrittura. In altre parole, si tratta delle celle per le quali non è disponibile alcun dato da scrivere.

Prima che WriteConsoleOutput restituisca, imposta i membri di lpWriteRegion sul rettangolo effettivo del buffer dello schermo interessato dall'operazione di scrittura. Questo rettangolo riflette le celle nel rettangolo di destinazione per cui esiste una cella corrispondente nel buffer di origine, perché WriteConsoleOutput ritaglia le dimensioni del rettangolo di destinazione fino ai limiti del buffer dello schermo della console.

Se il rettangolo specificato da lpWriteRegion si trova completamente al di fuori dei limiti del buffer dello schermo della console o se il rettangolo corrispondente è posizionato completamente al di fuori dei limiti del buffer di origine, non vengono scritti dati. In questo caso, la funzione restituisce con i membri della struttura a cui punta il parametro lpWriteRegion impostato in modo che il membro Right sia minore di Left o che il membro Bottom sia minore di Top. Per determinare le dimensioni del buffer dello schermo della console, usare la funzione GetConsoleScreenBufferInfo.

WriteConsoleOutput non ha alcun effetto sulla posizione del cursore.

Questa funzione usa i caratteri Unicode o i caratteri a 8 bit dalla tabella codici corrente della console. Inizialmente il valore predefinito della tabella codici della console è la tabella codici OEM del sistema. Per modificare la tabella codici della console usare le funzioni SetConsoleCP o SetConsoleOutputCP. I consumer legacy possono anche usare i comandichcp o mode con cp select= ma non è consigliabile per il nuovo sviluppo.

Suggerimento

Questa API ha un terminale virtuale equivalente nella formattazione del testo e nelle sequenze di posizionamento del cursore. Spostare il cursore nella posizione in cui inserire, applicare la formattazione desiderata e scrivere il testo. Le sequenze di terminale virtuale sono consigliate per tutti gli sviluppi nuovi e in corso.

Esempi

Per un esempio, vedere Lettura e scrittura di blocchi di caratteri e attributi.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ConsoleApi2.h (tramite WinCon.h, includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll
Nomi Unicode e ANSI	WriteConsoleOutputW (Unicode) e WriteConsoleOutputA (ANSI)