.. _program_listing_file_libtcod_console_printing.h:

Program Listing for File console_printing.h
===========================================

|exhale_lsh| :ref:`Return to documentation for file <file_libtcod_console_printing.h>` (``libtcod/console_printing.h``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS

.. code-block:: cpp

   /* BSD 3-Clause License
    *
    * Copyright © 2008-2025, Jice and the libtcod contributors.
    * All rights reserved.
    *
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions are met:
    *
    * 1. Redistributions of source code must retain the above copyright notice,
    *    this list of conditions and the following disclaimer.
    *
    * 2. Redistributions in binary form must reproduce the above copyright notice,
    *    this list of conditions and the following disclaimer in the documentation
    *    and/or other materials provided with the distribution.
    *
    * 3. Neither the name of the copyright holder nor the names of its
    *    contributors may be used to endorse or promote products derived from
    *    this software without specific prior written permission.
    *
    * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
    * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    * POSSIBILITY OF SUCH DAMAGE.
    */
   #pragma once
   #ifndef TCOD_CONSOLE_PRINTING_H_
   #define TCOD_CONSOLE_PRINTING_H_
   
   #include <stdarg.h>
   #include <stdbool.h>
   #ifndef NO_UNICODE
   #include <wchar.h>
   #endif
   
   #include "config.h"
   #include "console_types.h"
   #include "error.h"
   
   #ifdef __cplusplus
   extern "C" {
   #endif
   
   TCOD_DEPRECATED("Use TCOD_console_printf instead.")
   TCODLIB_API void TCOD_console_print(TCOD_Console* con, int x, int y, const char* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_ex instead.")
   TCODLIB_API void TCOD_console_print_ex(
       TCOD_Console* con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const char* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_rect instead.")
   TCODLIB_API int TCOD_console_print_rect(TCOD_Console* con, int x, int y, int w, int h, const char* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_rect_ex instead.")
   TCODLIB_API int TCOD_console_print_rect_ex(
       TCOD_Console* con,
       int x,
       int y,
       int w,
       int h,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const char* fmt,
       ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_frame instead.")
   TCODLIB_API void TCOD_console_print_frame(
       TCOD_console_t con, int x, int y, int w, int h, bool empty, TCOD_bkgnd_flag_t flag, const char* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_get_height_rect_fmt instead.")
   TCODLIB_API int TCOD_console_get_height_rect(TCOD_Console* con, int x, int y, int w, int h, const char* fmt, ...);
   #ifndef NO_UNICODE
   
   TCOD_DEPRECATED("Use TCOD_console_printf instead.")
   TCODLIB_API void TCOD_console_print_utf(TCOD_Console* con, int x, int y, const wchar_t* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_ex instead.")
   TCODLIB_API void TCOD_console_print_ex_utf(
       TCOD_Console* con, int x, int y, TCOD_bkgnd_flag_t flag, TCOD_alignment_t alignment, const wchar_t* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_rect instead.")
   TCODLIB_API int TCOD_console_print_rect_utf(TCOD_Console* con, int x, int y, int w, int h, const wchar_t* fmt, ...);
   
   TCOD_DEPRECATED("Use TCOD_console_printf_rect_ex instead.")
   TCODLIB_API int TCOD_console_print_rect_ex_utf(
       TCOD_Console* con,
       int x,
       int y,
       int w,
       int h,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const wchar_t* fmt,
       ...);
   
   TCOD_DEPRECATED("Use TCOD_console_get_height_rect_fmt instead.")
   TCODLIB_API int TCOD_console_get_height_rect_utf(
       TCOD_Console* con, int x, int y, int w, int h, const wchar_t* fmt, ...);
   #endif
   
   typedef enum {
     TCOD_COLCTRL_1 = 1,
     TCOD_COLCTRL_2,
     TCOD_COLCTRL_3,
     TCOD_COLCTRL_4,
     TCOD_COLCTRL_5,
     TCOD_COLCTRL_NUMBER = 5,
     TCOD_COLCTRL_FORE_RGB,
     TCOD_COLCTRL_BACK_RGB,
     TCOD_COLCTRL_STOP
   } TCOD_colctrl_t;
   
   TCODLIB_API void TCOD_console_set_color_control(TCOD_colctrl_t con, TCOD_color_t fore, TCOD_color_t back);
   
   /* UTF-8 functions */
   #ifndef TCOD_NO_UNICODE
   TCOD_DEPRECATED("Use TCOD_printf_rgb instead.")
   TCODLIB_API TCODLIB_FORMAT(4, 5) TCOD_Error
       TCOD_console_printf(TCOD_Console* __restrict con, int x, int y, const char* __restrict fmt, ...);
   TCOD_DEPRECATED("Use TCOD_printf_rgb instead.")
   TCODLIB_API TCODLIB_FORMAT(6, 7) TCOD_Error TCOD_console_printf_ex(
       TCOD_Console* __restrict con,
       int x,
       int y,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const char* __restrict fmt,
       ...);
   TCOD_DEPRECATED("Use TCOD_printf_rgb instead.")
   TCODLIB_API TCODLIB_FORMAT(6, 7) int TCOD_console_printf_rect(
       TCOD_Console* __restrict con, int x, int y, int w, int h, const char* __restrict fmt, ...);
   TCOD_DEPRECATED("Use TCOD_printf_rgb instead.")
   TCODLIB_API TCODLIB_FORMAT(8, 9) int TCOD_console_printf_rect_ex(
       TCOD_Console* __restrict con,
       int x,
       int y,
       int w,
       int h,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const char* __restrict fmt,
       ...);
   TCOD_DEPRECATED("Print function TCOD_printf_rgb and TCOD_console_draw_frame_rgb should be called separately.")
   TCODLIB_API TCODLIB_FORMAT(8, 9) TCOD_Error TCOD_console_printf_frame(
       TCOD_Console* __restrict con,
       int x,
       int y,
       int w,
       int h,
       int empty,
       TCOD_bkgnd_flag_t flag,
       const char* __restrict fmt,
       ...);
   TCODLIB_API TCODLIB_FORMAT(6, 7) int TCOD_console_get_height_rect_fmt(
       TCOD_Console* __restrict con, int x, int y, int w, int h, const char* __restrict fmt, ...);
   TCOD_PUBLIC TCOD_Error TCOD_console_printn(
       TCOD_Console* __restrict console,
       int x,
       int y,
       size_t n,
       const char* __restrict str,
       const TCOD_ColorRGB* __restrict fg,
       const TCOD_ColorRGB* __restrict bg,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment);
   TCOD_PUBLIC int TCOD_console_printn_rect(
       TCOD_Console* __restrict console,
       int x,
       int y,
       int width,
       int height,
       size_t n,
       const char* __restrict str,
       const TCOD_ColorRGB* __restrict fg,
       const TCOD_ColorRGB* __restrict bg,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment);
   TCOD_PUBLIC int TCOD_console_get_height_rect_n(
       TCOD_Console* __restrict console, int x, int y, int width, int height, size_t n, const char* __restrict str);
   TCOD_PUBLIC int TCOD_console_get_height_rect_wn(int width, size_t n, const char* __restrict str);
   TCOD_DEPRECATED("Print function TCOD_printn_rgb and TCOD_console_draw_frame_rgb should be called separately.")
   TCOD_PUBLIC TCOD_Error TCOD_console_printn_frame(
       TCOD_Console* __restrict console,
       int x,
       int y,
       int width,
       int height,
       size_t n,
       const char* __restrict title,
       const TCOD_ColorRGB* __restrict fg,
       const TCOD_ColorRGB* __restrict bg,
       TCOD_bkgnd_flag_t flag,
       bool clear);
   
   TCOD_DEPRECATED("Use TCOD_vprintf_rgb instead.")
   TCOD_PUBLIC TCOD_Error TCOD_console_vprintf(
       TCOD_Console* __restrict console,
       int x,
       int y,
       const TCOD_color_t* __restrict fg,
       const TCOD_color_t* __restrict bg,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const char* __restrict fmt,
       va_list args);
   
   TCOD_DEPRECATED("Use TCOD_vprintf_rgb instead.")
   TCOD_PUBLIC int TCOD_console_vprintf_rect(
       TCOD_Console* __restrict console,
       int x,
       int y,
       int width,
       int height,
       const TCOD_color_t* __restrict fg,
       const TCOD_color_t* __restrict bg,
       TCOD_bkgnd_flag_t flag,
       TCOD_alignment_t alignment,
       const char* fmt,
       va_list args);
   
   typedef struct TCOD_PrintParamsRGB {
     int x;  // The starting X coordinate, the left-most position being 0.
     int y;  // The starting Y coordinate, the top-most position being 0.
     int width;  // Width of the bounding rectangle. Will be unbound if set to 0
     int height;  // Height of the bounding rectangle. Will be unbound if set to 0
     const TCOD_ColorRGB* __restrict fg;  // An optional foreground color of the string
     const TCOD_ColorRGB* __restrict bg;  // An optional background color of the string
     TCOD_bkgnd_flag_t flag;  // The background blending flag. The default of `TCOD_BKGND_NONE` implies `TCOD_BKGND_SET`.
     TCOD_alignment_t alignment;  // The text justification.  Defaults to `TCOD_LEFT`.
   } TCOD_PrintParamsRGB;
   
   TCOD_PUBLIC TCODLIB_FORMAT(3, 4) int TCOD_printf_rgb(
       TCOD_Console* __restrict console, TCOD_PrintParamsRGB params, const char* __restrict fmt, ...);
   
   TCOD_PUBLIC int TCOD_printn_rgb(
       TCOD_Console* __restrict console, TCOD_PrintParamsRGB params, int n, const char* __restrict str);
   
   TCOD_PUBLIC int TCOD_vprintf_rgb(
       TCOD_Console* __restrict console, TCOD_PrintParamsRGB params, const char* __restrict fmt, va_list args);
   #endif  // TCOD_NO_UNICODE
   #ifdef __cplusplus
   }  // extern "C"
   #endif  // __cplusplus
   #endif /* TCOD_CONSOLE_PRINTING_H_ */