Funzione ScrollConsoleScreenBuffer

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.

Sposta un blocco di dati in un buffer dello schermo. Gli effetti dello spostamento possono essere limitati specificando un rettangolo di ritaglio, in modo che il contenuto del buffer dello schermo della console all'esterno del rettangolo di ritaglio rimanga invariato.

Sintassi

BOOL WINAPI ScrollConsoleScreenBuffer(
  _In_           HANDLE     hConsoleOutput,
  _In_     const SMALL_RECT *lpScrollRectangle,
  _In_opt_ const SMALL_RECT *lpClipRectangle,
  _In_           COORD      dwDestinationOrigin,
  _In_     const CHAR_INFO  *lpFill
);

Parametri

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

lpScrollRectangle [in]
Puntatore a una struttura SMALL_RECT i cui membri specificano le coordinate in alto a sinistra e in basso a destra del rettangolo del buffer dello schermo della console da spostare.

lpClipRectangle [in, facoltativo]
Puntatore a una struttura SMALL_RECT i cui membri specificano le coordinate in alto a sinistra e in basso a destra del rettangolo del buffer dello schermo della console interessate dallo scorrimento. Questo puntatore può essere NULL.

dwDestinationOrigin [in]
Struttura COORD che specifica l'angolo superiore sinistro della nuova posizione del contenuto lpScrollRectangle , in caratteri.

lpFill [in]
Puntatore a una struttura CHAR_INFO che specifica gli attributi di carattere e colore da utilizzare per riempire le celle all'interno dell'intersezione di lpScrollRectangle e lpClipRectangle che sono rimasti vuoti in seguito allo spostamento.

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:

ScrollConsoleScreenBuffer copia il contenuto di un'area rettangolare di un buffer dello schermo, specificato dal parametro lpScrollRectangle , in un'altra area del buffer dello schermo della console. Il rettangolo di destinazione ha le stesse dimensioni del rettangolo lpScrollRectangle con l'angolo superiore sinistro alle coordinate specificate dal parametro dwDestinationOrigin. Le parti di lpScrollRectangle che non si sovrappongono al rettangolo di destinazione vengono riempite con gli attributi carattere e colore specificati dal parametro lpFill .

Il rettangolo di ritaglio si applica alle modifiche apportate sia nel rettangolo lpScrollRectangle che nel rettangolo di destinazione. Ad esempio, se il rettangolo di ritaglio non include un'area che sarebbe stata riempita dal contenuto di lpFill, il contenuto originale dell'area rimane invariato.

Se le aree di scorrimento o di destinazione si estendono oltre le dimensioni del buffer dello schermo della console, vengono ritagliate. Ad esempio, se lpScrollRectangle è l'area contenuta in (0,0) e (19,19) e dwDestinationOrigin è (10,15), il rettangolo di destinazione è l'area contenuta in (10,15) e (29,34). Tuttavia, se il buffer dello schermo della console è largo 50 caratteri e 30 caratteri, il rettangolo di destinazione viene ritagliato su (10,15) e (29,29). Anche le modifiche apportate al buffer dello schermo della console vengono ritagliate in base a lpClipRectangle, se il parametro specifica una struttura SMALL_RECT. Se il rettangolo di ritaglio viene specificato come (0,0) e (49,19), vengono apportate solo le modifiche apportate in tale area del buffer dello schermo della console.

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 non è consigliata e non ha un terminale virtuale equivalente. L'uso può essere approssimativo con i margini di scorrimento per correggere un'area dello schermo, il posizionamento del cursore per impostare la posizione attiva all'esterno dell'area e le nuove righe per forzare lo spostamento del testo. Lo spazio rimanente può essere riempito spostando il cursore, impostando attributi grafici e scrivendo testo normale.

Esempi

Per un esempio, vedere Scorrimento del contenuto di un buffer dello schermo.

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	ScrollConsoleScreenBufferW (Unicode) e ScrollConsoleScreenBufferA (ANSI)