Función WriteConsoleOutput

Artículo
12/15/2023

Importante

En este documento se describe funcionalidad de la plataforma de consola que ya no forma parte de nuestra hoja de ruta 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.

Escribe datos de atributos de color y caracteres en un bloque rectangular especificado de celdas de caracteres en un búfer de pantalla de consola. Los datos que se van a escribir se toman de un bloque rectangular de tamaño correspondiente en una ubicación especificada en el búfer de origen.

Sintaxis

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

Parámetros

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

lpBuffer [in]
Los datos que se escribirán en el búfer de pantalla de la consola. Este puntero se trata como el origen de una matriz bidimensional de estructuras CHAR_INFO cuyo tamaño especifica el parámetro dwBufferSize.

dwBufferSize [in]
Tamaño del búfer al que apunta el parámetro lpBuffer, en celdas de caracteres. El miembro X de la estructura COORD es el número de columnas; el miembro Y es el número de filas.

dwBufferCoord [in]
Coordenadas de la celda superior izquierda del búfer al que apunta el parámetro lpBuffer. El miembro X de la estructura COORD es la columna y el miembro Y es la fila.

lpWriteRegion [in, out]
Un puntero a una estructura SMALL_RECT. En la entrada, los miembros de la estructura especifican las coordenadas superior izquierda e inferior derecha del rectángulo del búfer de pantalla de la consola en el que se va a escribir. En la salida, los miembros de la estructura especifican el rectángulo real que se usó.

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

WriteConsoleOutput trata el búfer de origen y el búfer de pantalla de destino como matrices bidimensionales (columnas y filas de celdas de caracteres). El rectángulo al que apunta el parámetro lpWriteRegion especifica el tamaño y la ubicación del bloque en el búfer de pantalla de la consola. Un rectángulo del mismo tamaño se encuentra con su celda superior izquierda en las coordenadas del parámetro dwBufferCoord en la matriz lpBuffer. Los datos de las celdas que están en la intersección de este rectángulo y el rectángulo del búfer de origen (cuyas dimensiones especifica el parámetro dwBufferSize) se escriben en el rectángulo de destino.

Las celdas del rectángulo de destino cuya ubicación de origen correspondiente están fuera de los límites del rectángulo del búfer de origen no se ven afectadas por la operación de escritura. En otras palabras, estas son las celdas para las que no hay datos disponibles para escribir.

Antes de que vuelva WriteConsoleOutput, establece los miembros de lpWriteRegion en el rectángulo real del búfer de pantalla afectado por la operación de escritura. Este rectángulo refleja las celdas del rectángulo de destino para las que existía una celda correspondiente en el búfer de origen, ya que WriteConsoleOutput recorta las dimensiones del rectángulo de destino a los límites del búfer de pantalla de la consola.

Si el rectángulo especificado por lpWriteRegion se encuentra completamente fuera de los límites del búfer de pantalla de la consola, o si el rectángulo correspondiente está completamente fuera de los límites del búfer de origen, no se escribe ningún dato. En este caso, la función vuelve con los miembros de la estructura a los que apunta el parámetro lpWriteRegion establecido de forma que el miembro Right es menor que el miembro Left, o el miembro Bottom es menor que Top. Para determinar el tamaño del búfer de pantalla de la consola, utilice la función GetConsoleScreenBufferInfo.

WriteConsoleOutput no tiene ningún efecto en la posición del cursor.

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 tiene un terminal virtual equivalente en las secuencias de formato de texto y posicionamiento del cursor. Mueva el cursor a la ubicación para insertar, aplique el formato deseado y escriba el texto. Se recomiendan secuencias de terminal virtual para todo el desarrollo nuevo y continuo.

Ejemplos

Para ver un ejemplo, consulte Lectura y escritura de bloques de caracteres y atributos.

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	WriteConsoleOutputW (Unicode) y WriteConsoleOutputA (ANSI)