Función ScrollConsoleScreenBuffer

Artículo
12/21/2023

Importante

En este documento se describe funcionalidad de la plataforma de consola que ya no forma parte de nuestro plan de desarrollo del ecosistema. No se recomienda usar este contenido en nuevos productos, pero seguiremos admitiendo los usos existentes en un futuro indefinido. Nuestra solución moderna preferida se centra en secuencias de terminal virtual para lograr la máxima compatibilidad en escenarios multiplataforma. Puede encontrar más información sobre esta decisión de diseño en nuestro documento de Comparación de consola clásica y terminal virtual.

Mueve un bloque de datos en un búfer de pantalla. Los efectos del movimiento se pueden limitar especificando un rectángulo de recorte para que no cambie el contenido del búfer de pantalla de consola que queda fuera de este rectángulo.

Sintaxis

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
);

Parámetros

hConsoleOutput [in]
Identificador del búfer de pantalla de la consola. El identificador debe tener derecho de acceso de GENERIC_READ. Para obtener más información, consulte Seguridad y derechos de acceso del búfer de la consola.

lpScrollRectangle [in]
Puntero a una estructura SMALL_RECT cuyos miembros especifican las coordenadas superior izquierda e inferior derecha del rectángulo del búfer de pantalla de consola que se va a mover.

lpClipRectangle [in, optional]
Puntero a una estructura SMALL_RECT cuyos miembros especifican las coordenadas superior izquierda e inferior derecha del rectángulo del búfer de pantalla de consola al que afecta el desplazamiento. Este puntero puede ser NULL.

dwDestinationOrigin [in]
Estructura COORD que especifica la esquina superior izquierda de la nueva ubicación del contenido de lpScrollRectangle en caracteres.

lpFill [in]
Puntero a una estructura CHAR_INFO que especifica los atributos de carácter y color con los que se van a rellenar las celdas dentro de la intersección de lpScrollRectangle con lpClipRectangle que quedaron vacías debido al movimiento.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

ScrollConsoleScreenBuffer copia el contenido de una región rectangular de un búfer de pantalla (que especifica el parámetro lpScrollRectangle) en otra área del búfer de pantalla de consola. El rectángulo de destino tiene las mismas dimensiones que el rectángulo de lpScrollRectangle. El parámetro dwDestinationOrigin especifica las coordenadas de su esquina superior izquierda. Esas partes de lpScrollRectangle que no se superponen con el rectángulo de destino se rellenan con los atributos de carácter y color que especifica el parámetro lpFill.

El rectángulo de recorte se aplica a los cambios realizados tanto en el rectángulo de lpScrollRectangle como en el de destino. Por ejemplo, si el rectángulo de recorte no incluye ninguna región rellenada con el contenido de lpFill, el contenido original de la región se mantiene sin cambios.

Si las regiones de desplazamiento o destino se extienden más allá de las dimensiones del búfer de pantalla de consola, se recortan. Por ejemplo, si lpScrollRectangle es la región contenida entre (0,0) y (19,19), y dwDestinationOrigin es (10,15), el rectángulo de destino es la región contenida entre (10,15) y (29,34). Sin embargo, si el búfer de pantalla de consola tiene 50 caracteres de ancho y 30 de alto, el rectángulo de destino se recorta a (10,15) y (29,29). Los cambios en el búfer de pantalla de consola también se recortan en función de lpClipRectangle si el parámetro especifica una estructura SMALL_RECT. Si el rectángulo de recorte se especifica como (0,0) y (49,19), solo se realizan los cambios que se producen en esa región del búfer de pantalla de consola.

Esta función usa caracteres Unicode o caracteres de 8 bits de la página de códigos actual de la consola. La página de códigos de la consola tiene como valor predeterminado la página de códigos OEM del sistema. Para cambiar la página de códigos de la consola, use las funciones SetConsoleCP o SetConsoleOutputCP. Los consumidores heredados también pueden usar los comandos chcp o mode con cp select=, pero no se recomienda si va a desarrollar algo nuevo.

Sugerencia

Esta API no se recomienda y no tiene un equivalente de terminal virtual. Su uso se puede aproximar con márgenes de desplazamiento para corregir un área de la pantalla, con el posicionamiento del cursor para establecer la posición activa fuera de la región y con nuevas líneas para forzar el movimiento del texto. Para rellenar el espacio restante, puede mover el cursor, establecer atributos gráficos y escribir texto normal.

Ejemplos

Para ver un ejemplo, consulte Desplazamiento por el contenido de un búfer de pantalla.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	ConsoleApi2.h (a través de WinCon.h, incluido Windows.h)
Biblioteca	Kernel32.lib
Archivo DLL	Kernel32.dll
Nombres Unicode y ANSI	ScrollConsoleScreenBufferW (Unicode) y ScrollConsoleScreenBufferA (ANSI)