Console Screen

Introduction

A class to draw a console screen.

The object can be used in a similar fashion to console programming. e.g. moving a cursor around, changing foreground and background colours, "printing" and "reading" strings, "stretching" cells to allow double-height cells, scrolling, and accessing colours and cell values (the 'character' at that position) separately, as well as inverting, flipping and darkening cells using simple cell attributes.

This class is now at version 2.4. For an overview of the changes to the object, read its change log.

Usage

Alias

The class name is ConsoleScreen and exists in the selbaward namespace thus: selbaward::ConsoleScreen.

The selbaward namespace has an alias that allows it to be specified using just "sw". For Console Screen, that would be: sw::ConsoleScreen.

However, Console Screen also includes an alias for itself. "Cs" is the alias for selbaward::ConsoleScreen so bypasses the selbaward namespace and the need for the full class name. As with the selbaward namespace alias, this shortcut alias can be disabled. To disable the "Cs" alias, just use #define SELBAWARD_CONSOLESCREEN_NO_CLASSNAME_SHORTCUT, which must be defined before the inclusion of Console Screen.

Any use of Console Screen in this documentation will use the shortcut alias, Cs. The Console Screen object will also be a short version: cs.

Declaration

Cs cs;
creates a Console Screen with the default mode (see below)

Cs cs(sf::Vector2u);
creates a Console Screen with a mode determined by the given sf::Vector2u. A mode is the number of cells used to fit the screen

Drawing

This class inherits from sf::Drawable so it is drawn in the same way as all SFML drawables:
window.draw(cs);
where window is an sf::RenderWindow.

Transformations

This class inherits from sf::Transformable so it has all the usual SFML transformations available.

Manipulation

Description

Console Screen works similarly to a basic tile map in that it holds values for each cell (tile) and displays a specific part of a texture based on that value, modified by a colour. Console Screen is a specialised version that allows strings to update multiple cells at once. Console Screen also uses a similar "tile map" that draws each cells as individual solid colours beneath the texture cells. This acts as a background colour for the cells and background drawing can be switched off.

"Printing" is the act of changing the cells based on a string. This is the main way to manipulate cells. You can think of it as writing/drawing text in the same way to a console/terminal/shell.

"Print Properties" are the current state of printing. This includes things like current colours and the current position as well as some other attributes that manipulate the way cells are modified when printing. There are, in fact, two sets of print properties: the main one (cursor printing) and a temporary one (direct printing). Both work mostly indentically except direct printing doesn't move the visible cursor and also has a temporary lifetime.

Each cell has:

• a value that represents which tile to display in that cell. The value can be set using characters of a string,
• a foreground colour that determines the colour of the tile. If normal shaders are used, this colour is multiplied with the tile,
• a background colour that determines the background of the cell. This is a solid rectangle drawn directly behind the foreground tile,
• a stretch value that determines which part of the tile to draw. This can be the entire tile or just the top or bottom half of the tile,
• an inverse attribute that determines whether the foreground and background colours should be swapped when drawn,
• a dark attribute that determines if both colours should be drawn at full intensity or darker. It defaults to false. If it is true, darkened versions of both colours are used when drawing the cell,
• a flip x attribute that determines if the tile should be flipped horizontally,
• and a flip y attribute that determines if the tile should be flipped vertically.

Which of these values and attributes are overwritten (affected) during printing can be changed and is stored in the print properties.

"Location" or "cell index" are ways of identifying the cells of the screen. Cell index ranges from zero to the number of cells minus 1 whereas the location is a two-dimensional type that stores the x (column) and y (row) of the cell. Both the column and the row start at zero (left-most column is zero and top-most row is zero)

"Character mapping" is the ability to assign - or map - a different cell value to a character so that it doesn't print its default tile value. For example, mapping "p" to the value of the tile that has an "e" in it would result in the "e" being shown whenever "p" is printed.

Colours are stored in a palette, which can be manipulated manually although a number of default palettes are provided that can be loaded easily. A colour in a palette is created using an sf::Color. Once stored in the palette, it is used by specifying its palette ID/index. All colours used in Console Screen use Palette IDs rather than direct colours, even in RGB mode. This means that a colour stored in a cell refers to a colour in the palette. If this colour in the palette is then changed to a different colour, the cell will still use this palette colour and therefore the updated colour. This results in the ability to change multiple cells' colours by manipulating the palette.

RGB mode allows the entire 24-bit colour RGB palette to be used. Since the almost 17 million colours of that palette are not stored in Console Screen, the palette manipulation ability is disabled; the palette is fixed and can not be changed or even re-ordered. The palette ID for colour in RGB mode correspond to their hexadecimal representation in the RRGGBB order. This means that a fully green and half red colour would have the palette ID of 0x80ff00. Note that RGB is not activated by default. Standard palette mode is set by default, which allows the many provided palettes or even your own custom palette to be used.

The entire screen (all of the cell contents) - or a rectangular selection of cells - can be scrolled in any of the four directions by any amount. Scrolling is the effect of moving the cells' contents into neighbouring cells so that it appears to have moved the entire screen - or rectangular region - in a specific direction. When the cells are scrolled off the edge of the screen (or selection rectangle), the cells can be lost and the opposite side has new, clear cells, or the cells can be wrapped where, instead of losing them, they move onto the opposite side instead of new cells.

The colours in the palette can be "cycled". That is, shifted - or 'scrolled' in one direction in the palette. A range of colours in the palette can be specified to cycle or else the entire palette is cycled. The colours that are shifted/scrolled off the edge of the palette/range wrap onto the opposite side, similarly to the way scroll wrapping works.

"Stack printing" allows you to stack a cell. That is, have multiple characters/tiles displayed on the same cell, layered on top of each other. Stack cells are not used in the same way as the main screen; they are "free" cells that have their own location stored. They can be printed using some special methods which add stack cells to a "pile". There are two piles: under and over. Over allows you to stack cells on top of the main cells. Under allows you to stack cells below the main cells. Note that the under cells are still drawn above (in front of) the background rectangle. Note also that the backgrounds of stack cells are completely ignored. Since they have their own location, scrolling does not affect stack cells. Entire piles can be removed at once but piles are not removed when clearing the screen. Stack cells can be given a grid offset when added. That is, a stack cell's position can be moved from its index's position and this position can be "off-grid".

"Clearing the screen" is resetting every cell in the screen. This most importantly includes resetting the cell values but also sets its colours to the colours in the current print properties although you can specify specific colours to override the print properties. The default value to which a cell is reset is zero but this value can be modified to any cell value; it can also be set by using a char, which is mapped using Console Screen character mapping (see above).

"Filling the screen" is very similar to clearing the screen except that it sets every cell in the screen to match the cell that you provide. This allows you to fill the screen with any cell value as well as with any cell attributes.

Parts (or all) of the screen's contents can be copied into a buffer. Multiple buffers can be stored at once. These buffers can then be "pasted" back onto the screen, replacing the cells that they cover. They are pasted starting at the top-left corner of the screen (0, 0) by default but can be pasted elsewhere by providing an offset (which can even be negative). Buffers can even be pasted into stack piles; this creates a number of stack cells in the chosen pile that match the buffer and the locations they should be. Buffers can be added/created and without copying from the screen. The cells of the buffers can also be manipulated directly.

"Reading" is the ability to retrieve information from the cell values. This can be used to get strings from text displayed on the screen. Reading is done very similarly to printing and also uses the two print properties (cursor printing and direct printing).

"Colour commands" are ways of specifying colours based on some other information. They can be stored instead of almost any colour as a colour ID can also hold colour commands. Colour commands can be "opposite" that will just use the colour specified by the opposite colour (foreground is opposite of background), "invert" that will invert the opposite colour (e.g. FFA020 inverted is 005FDF), "contrast" that will choose fully black or fully white to be in contrast to the opposite colour. Once a 'target' colour has been chosen, the closest match to that colour in the palette will be used.

"Cursor commands" are ways of specifying tasks for the cursor. Tasks include moving left, right, up or down; moving to the beginning of the row below; moving to the next or previous tab space and moving to the beginning or end of the row or entire screen. Cursor commands can also be mapped to a character so that certain characters inside a string can trigger cursor tasks.

Types

All types are a part of the class (Cs when using the default alias).

Enum Classes

• Direction
  Possible values: Left, Right, Up, Down.
  Used to specify the direction of MovementControl (see below in Classes/Structs). Used internally by Structs "Left", "Right", "Up" and "Down" so is probably not much use elsewhere.

• Palette
  Possible values: Default, Colors2BlackWhite, Colors2WhiteBlack, Colors16Greenscale, Colors16Grayscale, Colors16Sepia, Colors16Cga, Colors16CgaNonIbm, Colors16Windows, Colors16Mac, Colors16ZxSpectrum, Colors16Html, Colors216Web, Colors256Greenscale, Colors256Grayscale, Colors256Sepia or ColorsRgb.
  Used to specify which palette to load (see loadPalette).

• StretchType
  Possible values: None, Top, Bottom or Both.
  Used to specify the stretch value of the cell or the current stretch type value in print properties. If added to a print stream, the current print properties stretch type value is changed to match. A stretch type of "Both" also alters the way some cursor commands function and affects automatic scrolling as well as how the cursor is displayed.

• CursorCommand
  Possible values: None, Newline, Tab, TabReverse, Backspace, Delete, Left, Right, Up, Down, Home, End, HomeLine or EndLine.
  Used to specify a task to be performed that modifies the print properties location and sometimes the cell contents at that location. If added to a print or read stream, the current properties location is mostly modified based on the specified task. If Backspace or Delete are added to that stream, the cell contents are also affected. These commands can be mapped to a character when printing.

• PrintType
  Possible values: Cursor, Direct or Current.
  Used to specify a set of print properties. Cursor specifies the cursor printing properties, Direct specifies the direct printing properties and Current specified the currently active print properties.

Enums

Enums are most commonly used in Console Screen to allow a name to be used instead of a value while the value is what is being used underneath. Values shown in brackets are the values given to those names.

• ColorCommand
  Possible values: Unused (-1), Opposite (-2), Invert (-3) or Contrast (-4).
  Used to specify which colour to use based on information at time of update. "Opposite colour" is the opposite of foreground or background. Opposite takes the opposite colour directly, Invert uses the opposite colour, inverts its RGB values and then finds the closest matching Color in the palette, Contrast set to either fully black or fully white (or the closest matching Color in the palette) to contrast the opposite colour. Unused should not be used for cells. It is only ever used to specify a failure; it is returned from getColorAt and getBackgroundColorAt if the location is out of range and exceptions have been disabled.

• Direct
  Possible values: Begin or End.
  Used to specify the beginning or the end of a session of direct printing. This can only be used in a print or read stream where it sets the print properties to the direct set if in a session or to the cursor set if not in a session. Note that direct print properties are reset to the default print properties for each session. This is an enum instead of an enum class so that it is possible to use the value without the need for its enum name e.g. just Cs::Begin instead of Cs::Direct::Begin

• Affect
  Provided values: None (0 / 0x00), Value (1 / 0x01), FgColor (2 / 0x02), BgColor (4 / 0x04), Stretch (8 / 0x08), Inverse (16 / 0x10), Dark (32 / 0x20), FlipX (64 / 0x40), FlipY (128 / 0x80), Print (Value + FgColor + Stretch), Default (Print + BgColor), Attribs (Inverse + Dark + FlipX + FlipY), Paint (FgColor + BgColor), All (255 / 0xFF).
  Used to indicate specific parts of a cell. If modifying the cell, only the parts indicated here will be affected. If getting information (getAttributeAt), only one part should be specified as specifying multiple parts will result in only one being used and the others ignored. Which part used cannot be relied upon as the precedence may change at any time. If added to the print stream, the current print properties' affect mask is modified to match.
  To specify multiple parts, you can simply "or" the parts together. e.g. to affect value, stretch and inverse: (Affect::Value | Affect::Stretch | Affect::Inverse). The actual value can be anything from 0 (None, 0x00) to 255 (All, 0xFF).

• ColorType
  Possible values: Foreground, Background.
  Used to indicate which colour is currently active in print properties. This means that setting print properties' ColorType to Background will mean that any colour changes will modify the background colour (unless the colour change is explicit about which colour type). If added to the print stream, the currently active colour in print properties is modified to match.

Classes/Structs

A "quick class" is a simple class/struct that is designed to be created on-the-fly from its parameter(s) with the main intention of being able to specify the task to perform by its type.

• Location
  alias for sf::Vector2u used for specifying a specific cell by column and row. If added to a print or read stream, the current print properties' location is changed to match.

• Offset
  alias for sf::Vector2i used for specifying an offset by column and row. If added to a print or read stream, the current print properties' location is offset by this amount.

• Char
  A quick class to allow a single character to be passed to the stream without requiring a string.

• Number
  A quick class to allow a number to be automatically converted to a string when passed to the stream.

• Fg
  A quick class to allow the foreground colour to be changed explicitly in the stream. e.g. << Fg(10) changes the foreground colour of the current print properties to palette ID 10. Its constructor takes a Color.

• Bg
  A quick class to allow the background colour to be changed explicitly in the stream. e.g. << Bg(1) changes the background colour of the current print properties to palette ID 10. Its constructor takes a Color.

• MovementControl
  A quick class that is used a base quick class for the directional tasks: Left, Right, Up and Down. Its constructor takes a distance but the direction must be set manually. The directional tasks do this automatically.

• Left

• Right

• Up

• Down
  Quick classes that inherit from the MovementControl quick class and allow movement of the print properties' location by the specified direction. Its constructor takes a distance.

• Wipe
  A quick class that creates a string of spaces of a specified length that is printed. Its constructor takes the length of that string.

• Color
  Stores a "colour ID" which can represent either a palette ID (positive value) or a ColorCommand (negative value). Its constructor takes any number (it's implicitly converted to a long int). The constructor can also take a ColorCommand directly. If no parameters are provided, the colour is set to a palette ID of zero. If added to a print stream, the colour specified by the current print properties ColorType is modified to match.

• ColorPair
  Stores a foreground Color and a background Color. Its constructor can take a foreground Color and a background Color. If parameters are omitted, the background colour is set to a palette ID of zero and the foreground colour is set to a palette ID of one. If added to a print stream, the colours in the current print properties are modified to match.

• CellAttributes
  Stores the attribute flags for a cell. It has a bool for each: inverse, dark, flipX and flipY. Its constructor takes all four bools in order or an attribute mask (built from Affect - see above). If parameters are omitted, the attributes are set to their default values (all false).

• Cell
  Stores the information required for a single cell of the screen. Each cell stores a value (an unsigned int that represents the texture tile that is displayed in that cell), a ColorPair (foreground and background colours), a StretchType (the type of stretching that should be applied to this cell) and CellAttributes (the four attribute flags). This is how the information for each cell is stored in Console Screen. Using cell() gives you direct access to the actual Cell stored whereas using peek() returns a copy of that cell. An entire Cell can be "set" (see setCellAt), poked (see poke) or a copy retrieved using getCellAt() or peek(). A Cell is required as a parameter for fill() as this method fills every cell with the cell parameter. A stack cell can be created by passing a Location and a Cell (see addOverAt and addUnderAt).

Stream

The main method of printing and reading with Console Screen is to use the stream design, using the insertion and extraction operators (<< and >>) directly on the Console Screen object itself.

Note: cs is the Console Screen object and Cs is the Console Screen class name.

Printing

Multiple prints can be linked/streamed together like so:

cs << Cs::Location(8, 5) << Cs::ColorPair(9, 0) << "Some" << Cs::Down(2) << Cs::Fg(10) << "text.";

This moves the current print position to (8, 5), changes the foreground colour to palette colour 9 and the background colour to palette colour 0, prints "Some", moves the print position down two rows, changes the foreground colour to palette colour 10 and then finally prints "text.".

• << "STR";
  prints the string, STR, taking into account all character mapping, including mapped cursor commands. This allows cursor control inside the string. For example, "This row has ended.\n" could move the print position to a new line if '\n' is mapped to Cs::CursorCommand::Newline.

• << Cs::Char('C');
  prints the character, C, taking into account all character mapping, including mapped cursor commands. This allows cursor control to be passed as a character. For example, '\n' could move the print position to a new line if '\n' is mapped to Cs::CursorCommand::Newline.

• << Cs::Number(35);
  prints the number, 35, by first automatically converting it to a string (using std::to_string).

• << Cs::Location(x, y)
  moves the current print location to the specified Location.

• << Cs::Offset(x, y) moves the current print location by the specified Offset. Note that x and/or y can be positive or negative.

• << Cs::Direct::Begin

• << Cs::Begin
  begins a session of direct printing. This creates a temporary set of print properties for use during direct printing and remain the current print properties until the session ends.

• << Cs::Direct::End

• << Cs::End
  ends a session of direct printing. The print properties return to their previous state before direct printing began.

• << Cs::ColorType::Foreground

• << Cs::ColorType::Background

• << Cs::Foreground

• << Cs::Background
  sets which colour will be altered by any following colour changes (see Cs::Color() below).

• << Cs::Color(10)
  changes the colour of the current ColorType (see Cs::ColorType:: above). For example, Cs::Foreground followed by cs::Color(10) will set the foreground colour of the current print properties to palette ID 10.

• << Cs::Fg(11)
  changes the foreground colour of the current print properties to palette ID 11 regardless of the current ColorType.

• << Cs::Bg(2)
  changes the background color of the current print properties to palette ID 2 regardless of the current ColorType.

• << Cs::ColorPair(10, 1)
  changes both foreground and background colours of the current print properties at once.

• << Cs::Wipe(5)
  prints a string of 5 spaces. Can be used to clear a specific part of text or for manipulating many cells' attributes without provided a string of that length.

• << Cs::Left(3)

• << Cs::Right(3)

• << Cs::Up(3)

• << Cs::Down(3)
  moves the current print properties location 3 cells to the left, right, upwards or downwards.

• << sf::Color::Red changes the current ColorType colour to either the closest matching palette colour or to the palette colour after it is added. The effect of this is determined by the action flag, AddNewColorToPalette.

• << Cs::StretchType::None

• << Cs::StretchType::Top

• << Cs::StretchType::Bottom

• << Cs::StretchType::Both
  changes the stretch value of the current print properties to match. "None" means no stretching, "Top" means stretch the top half to fill the cell and "Bottom" means stretch the bottom half to fill the cell. "Both" is special and cause printing to print as if "Top" was chosen but also print the same string on the row below (if there is one) as if "Bottom" was chosen. For this reason, a cell should never be set to "Both"; it should only be used for printing. A stretch type of "Both" for the cursor print properties can affect cursor commands, automatic scrolling and how the cursor appears.

• << Cs::Affect::None

• << (Cs::Affect::Value | Cs::Affect::FgColor)

• << Cs::Affect::Print

• << Cs::Affect::All
  alters which parts of the cell are affected by any printing that follows. Multiple values can be "orred" together. Possible values for the parts are: Value (cell value), FgColor (foreground Color), BgColor (background Color), Stretch (StretchType - see above), Inverse (inverse attribute flag), Dark (dark attribute flag), FlipX (flip horizontally attribute flag) and FlipY (flip vertically attribute flag). Other values are predefined combinations of these parts: None (no parts), All (all parts), Print (Value, FgColor and Stretch), Default (Print and BgColor), Attribs (Inverse, Dark, FlipX and FlipY - the attribute flags), Paint (FgColor and BgColor - for colouring cells without affecting anything else including their values).

• << Cs::CellAttributes(Cs::Affect::Inverse | Cs::Affect::FlipX)

• << Cs::CellAttributes()

• << Cs::CellAttributes(false, false, false, false)
  changes all of the cell attribute flags in the current print properties (the ones that will be used when printing) to match the cell attributes you pass as a parameter. The parameter can be a single value representing which attributes are set, which can be found by "orring" Cs::Affect values together (see above), can be omitted to use default attribute flags (all off/false) or all flags can be specified directly using multiple bool parameters. The order is: inverse, dark, flip x and flip y. Note that this overwrites all of the attribute flags in the current print properties.

• << Cs::CursorCommand::Newline

• << Cs::CursorCommand::Backspace

• << Cs::CursorCommand::Tab
  performs the specified cursor command task. Possible values are: None (does nothing); Newline (moves the print location to the beginning of the row below the current location - note that only cursor printing can cause automatic scrolling); Tab (moves print location to next tab space); TabReverse (move print location to previous tab space); Left, Right, Up and Down (moves print location in that direction by one cell); HomeLine (moves to beginning of current row), EndLine (moves to end of current row), Home (moves to top-left cell), End (moves to bottom-right cell), Delete (clears the cell value at current print location), Backspace (moves the print location left by one cell and clears the cell value at that the new location). Delete and Backspace affect cell contents; Delete only affects cell contents (it doesn't change the print location). If the current stretch value of the current print properties is Cs::StretchType::Both, Delete and Backspace both also clear the cell below the usual cleared cell (if possible) whereas Newline moves down two rows instead of just one. Note that the cursor command affects the current print properties, which is not necessarily the cursor print properties; it can be the direct print properties. Note that if the current stretch type is "Both", the effect of these commands may be altered (mostly uses two rows at a time).

Reading

Only one read can be performed per "stream" but multiple settings can be linked/streamed together like so:

std::string readText;
cs >> Cs::Location(8, 5) >> Cs::Right(4) >> Cs::Down(2) >> 5 >> readText;

This moves the current print position to (8, 5), moves the print position right by four columns, moves the print position down two rows, sets the length of the string to read to 5 and then finally reads those five characters. If this is performed immediately after the printing streaming example above, the result of this read would be "text.". Note that reading can affect some of the print properties used by printing, such as location.

• >> 8
  sets the length of the string to read. Can be any unsigned integer.

• >> stringVariable
  reads the string of length previously set (see above) into stringVariable, replacing any string already there.

• >> Cs::Location(x, y)
  moves the current read location to the specified Location. Print location is used for reading so moving the read location is identical to moving the print location.

• >> Cs::Offset(x, y) moves the current read location by the specified Offset. Note that x and/or y can be positive or negative. Moving the read location is identical to moving the print location.

• >> Cs::Direct::Begin

• >> Cs::Begin
  begins a session of direct reading. Note that direct reading is identical to direct printing so this creates a temporary set of print properties in the same way that beginning a session of direct printing does. These remain the current print properties until the (print or read) session ends.

• >> Cs::Direct::End

• >> Cs::End
  ends a session of direct reading. The print properties return to their previous state before direct printing or reading began.

• >> Cs::Left(3)

• >> Cs::Right(3)

• >> Cs::Up(3)

• >> Cs::Down(3)
  moves the current read location 3 cells to the left, right, upwards or downwards. Note that this also affects the print location.

• >> Cs::CursorCommand::Newline

• >> Cs::CursorCommand::Backspace

• >> Cs::CursorCommand::Tab
  performs the specified cursor command task. Possible values are: None (does nothing); Newline (moves the read location to the beginning of the row below the current location - note that only cursor printing can cause automatic scrolling); Tab (moves read location to next tab space); TabReverse (move read location to previous tab space); Left, Right, Up and Down (moves read location in that direction by one cell); HomeLine (moves to beginning of current row), EndLine (moves to end of current row), Home (moves to top-left cell), End (moves to bottom-right cell), Delete (clears the cell value at current read location), Backspace (moves the read location left by one cell and clears the cell value at that the new location). Delete and Backspace affect cell contents, even though it may be considered reading; Delete only affects cell contents (it doesn't change the read location). Read location is a synonym for print location. Note that the cursor command affects the current print properties, which is not necessarily the cursor print properties; it can be direct print properties.

Setup

• setMode(sf::Vector2u)
  takes an sf::Vector2u that represents the mode, which is the number of cells used to fit the screen. The mode can be provided in the constructor (see above in declaration) but can also be used here to change the mode at any time. Changing the mode clears the screen and clears the entire stack. However, buffers persist over mode changes so can be used to copy content before changing the mode and pasting the content after a mode change.

• setClearValue(unsigned int)
  takes an unsigned int that represents the value that a cell will have when 'clearing' a cell. If parameter is omitted, this value defaults to zero.

• setClearChar(char)
  takes a char that represents the character that a cell will have when 'clearing' a cell. Note that this char is mapped using Console Screen's character mapping and then that resulting value is the value that is stored and used.

• setDarkAttributeMultiplier(float)
  takes a float that represents the value to which a cell's colours are multiplied when its dark attribute is used. If parameter is omitted, this value defaults to 0.5f.

Texture Setup

• setTexture(sf::Texture)
  takes an sf::Texture and stores a pointer to it. This means that the texture should exist (at its current memory position) as long as Console Screen requires it. This texture can be changed whenever you like and should be reset if the current texture is moved in memory. You can also use this method to nullify the texture by omitting the parameter.

• setTextureTileSize(sf::Vector2u)
  takes an sf::Vector2u that specifies the size of each tile (the section of texture to be shown in each cell). If parameter is omitted, this defaults to 8x8

• setTextureOffset(sf::Vector2u)
  takes an sf::Vector2u that specifies the offset to use inside the texture for the actual texture rectangles. If parameter is omitted, this defaults to (0, 0).

• setNumberOfTextureTilesPerRow(unsigned int)
  takes an unsigned int that informs Console Screen how many texture tiles there are per row in the texture. If parameter is omitted, this default to 16.

• setTexture(texture, numberOfTilesPerRow, tileSize, offset)
  sets all texture values at once. texture is the sf::Texture to be used, numberOfTilesPerRow is an unsigned int representing how many tiles there are per row in the texture, tileSize is an sf::Vector2u representing the size of each tile and offset is an sf::Vector2u representing the offset position of the tileset within the actual texture. See above for information.

Switches

These methods enable or disable the switch depending on the value of the bool. The descriptions here are for when the switches are enabled.

• setThrowExceptions(bool)
  throws exceptions on errors/mis-use.

• setUpdateAutomatically(bool)
  updates automatically (and dynamically) whenever anything changes otherwise a manual update() call is required. Note that updates cannot be performed automatically if the cell is manipulated directly.

• setShowCursor(bool)
  shows the cursor.

• setShowBackground(bool)
  shows the cells' backgrounds.

• setScrollAutomatically(bool)
  scrolls the screen upwards once if the cursor runs out of cells while printing or when moving the cursor using a cursor command methods.

• setWrapOnManualScroll(bool)
  wraps the contents to the opposite side when scrolling manually.

• setInvertCursor(bool)
  instructs the cell in which the cursor resides to swap its main and background colours.

• setUseCursorColor(bool)
  displays the cursor using its own colour otherwise it uses the colour from the cell in which it resides.

• setAddNewColorToPalette(bool)
  adds an sf::Color to the palette when it is added to print stream, which also sets the current ColorType Color to the palette colour just added. If this is set to false, the palette colour is the closest matching colour.

Visual Representation

• update()
  updates the visual representation of the Console Screen from its current state. Usually not required if Update Automatically switch is enabled (see above).

• setSize(sf::Vector2f)
  sets the size of the Console Screen.

Global

• clear(Color backgroundColor)
  clears all the cells (sets their values to zero) with the background colour specified. If no parameter is provided, the current background colour stored in the main/cursor print properties is used.

• clear(ColorCommand)
  clears all the cells with the background colour determined by a colour command.

• clear(ColorPair)
  clears all the cells with the ColorPair specified.

• fill(Cell)
  fills all the cells with cell provided).

• crash()
  randomises all values and colours of all cells to create a crash-like screen.

Print Properties

• resetPrintProperties(PrintType)
  resets to the default properties one of the two sets of print properties. The PrintType is an enum class that can be Cursor (to reset the properties for cursor printing), Direct (to reset the properties for direct printing) or Current (the default, which resets the properties of whichever print properties are currently in use).

Print methods

These methods print to the screen in the same way the streaming a string does (in fact, streaming a string uses the Print(string) method itself).
Note that the other methods work slightly different.
Using these methods can allow a single character to be printed whereas streaming doesn't allow characters unless they're first converted to a string.
All characters are mapped accordingly.

• print(char) prints the character at the current print properties location, using the current print properties' "affect" setup, and moves the print location to the right by one (it will move to the next line if it passes the last column).

• print(std::string)
  prints the string at the current print properties location, using the current print properties' "affect" setup, and moves the print location to the cell after the final character. Each character is printed to the right of the previous one, continuing on the next line if the last column has been used. Note that this is identical to << std::string.

• print(Location, char)
  prints the character at the specified location, using the current print properties' "affect" setup. The print properties - including the location - are not affected. This is not the most effecient method as it copies entire sets of print properties multiple times.

• print(Location, std::string)
  prints the string at the specified location, using the current print properties' "affect" setup. The print properties - including the location - are not affected. This is not the most effecient method as it copies entire sets of print properties multiple times.

Read methods

These methods print to the screen in the same way the streaming a string does. As opposed to the print methods, which are called by the stream printing, the read methods are provided for simplicity and internally call the stream reading.

• read() returns an std::string by reading the string starting at the current read/print properties location, using the current read length, following the same newline-when-end-of-column-is-reached method as printing and moves the read/print location to the cell to the right of the final character.

• read(unsigned int length)
  returns an std::string by reading the string starting at the current read/print properties location, using the specified length, following the same newline-when-end-of-column-is-reached method as printing and moves the read/print location to the cell to the right of the final character.

• read(Location)
  returns an std::string by reading the string starting at the specified location, using the current read length, following the same newline-when-end-of-column-is-reached method as printing and moves the read/print location to the cell to the right of the final character.

• read(Location, unsigned int length)
  returns an std::string by reading the string starting at the specified location, using the specified length, following the same newline-when-end-of-column-is-reached method as printing and moves the read/print location to the cell to the right of the final character.

Cursor

• setCursor(int cellValue)
  sets the cell value to use for the visual representation of the cursor.

• setCursor(char, bool)
  sets the cell value for the cursor from the char specified, mapping the character if the bool is true, which it is by default.

• setCursorColor(Color)
  sets the Color (palette ID) to use for the cursor.

• setCursorTab(unsigned int)
  sets the tab size to the specified unsigned int.

Cells

• clearCellAt(sf::Vector2u location)
  clears the cell (sets its value to zero, sets its colours to the current colours) at the given cell location.

• setCellAt(sf::Vector2u location, Cell)
  sets the cell at the location to the provided cell (of type Cs::Cell). This cell contains all of the information for a single cell.

• setValueAt(sf::Vector2u location, unsigned int)
  sets the cell's value at the location to the provided unsigned int.

• setForegroundColorAt(sf::Vector2u location, Color)
  sets the cell's foreground colour at the location.

• setBackgroundColorAt(sf::Vector2u location, Color)
  sets the cell's background colour at the location.

• setColorsAt(sf::Vector2u location, Color color, Color backgroundColor)
  sets both of the cell's colours at the location.

• setStretchAt(sf::Vector2u location, StretchType)
  sets the cell's StretchType value at the location.

• setAttributesAt(sf::Vector2u location, CellAttributes)
  sets the cell's attributes at the location.

• setAttributesAt(sf::Vector2u location, Affect)
  sets the cell's attributes at the location to match the affect "mask".

• setAttributesToAt(sf::Vector2u location, bool attributeValue, Affect)
  sets the cell's attributes at the location to the attributeValue provided. The attributes that are affected are selected with Affect.

Stack Printing

"Over" cells are drawn over (or in front of) the main cells.
"Under" cells are drawn under (or behind) the main cells (but in front of the cells' background rectangles).
Note that the background of all stack cells are ignored completely

• addOverAt(Location, Cell, offset)
  adds the specified cell at the specified location to the "over pile". The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• addOverAt(Location, char, offset)
  adds a cell at the specified location to the "over pile" with the value based of the specified char, using the current print properties. The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• addOverAt(Location, string, offset)
  adds cells starting from the specified location to the "over pile" with value based on each char in the string, using the current print properties. The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• addUnderAt(Location, Cell, offset)
  adds the specified cell at the specified location to the "under pile". The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• addUnderAt(Location, char, offset)
  adds a cell at the specified location to the "under pile" with the value based of the specified char, using the current print properties. The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• addUnderAt(Location, string, offset)
  adds cells starting from the specified location to the "under pile" with value based on each char in the string, using the current print properties. The offset (sf::Vector2f) specifies how many grid positions to move the cell. The cell can be positioned off-grid by using fractional values. If offset is omitted, offset is zero.

• clearOversAt(Location)
  removes all cells from the "over pile" that are located at the specified location.

• clearUndersAt(Location)
  removes all cells from the "under pile" that are located at the specified location.

• clearStackAt(Location)
  removes all stack cells that are located at the specified location (both under cells and over cells).

• clearOvers()
  removes the entire "over pile".

• clearUnders()
  removes the entire "under pile".

• clearStack()
  removes all stack cells (both the over pile and the under pile and cleared).

Buffers

Buffers (or "clipboards") store rectangular regions of cells - up to the entire screen size (mode), which is the default if the rectangular region is not specified. They can be used to copy small parts of text or even capture a screenshot!

• copy(selectionRectangle)
  copies the cells in the selection (sf::IntRect) to a new buffer. If selectionRectangle is omitted, the entire screen is copied. The index of the new buffer is returned.

• paste(offset)
  pastes the buffer onto the screen offset by the specified offset (sf::Vector2i), which can have negative values. If offset is omitted, offset becomes (0, 0), which means that the top-left of the buffer is pasted at the top-left of the screen. The index of the new buffer is returned.

• removeBuffer()
  removes the most recently added buffer. See copy() above.

• copy(index, selectionRectangle)
  as copy() above but instead of creating a new buffer, it copies into (replaces) an already existing buffer specifed by the buffer index. The selectionRectangle can also be omitted here.

• paste(index, offset)
  as paste() above but instead of pasting the most recently added buffer, it pastes from the buffer specified by the buffer index. The offset can also be omitted here.

• removeBuffer(index)
  removes the buffer specified by the buffer index.

• removeAllBuffers()
  removes all stored buffers.

• addBuffer(size)
  adds a buffer of the given size (sf::Vector2u). If size is omitted, size becomes 1 x 1. The index of the new buffer is returned.

• resizeBuffer(index, size)
  changes the size of the buffer specified by index to the new size (sf::Vector2u) given.

• pasteOver(offset)
  pastes the buffer offset by the specified offset (sf::Vector2i) onto the "over pile" by creating "over cells" for each of the cells in the buffer. If offset is omitted, offset becomes (0, 0).

• pasteUnder(offset)
  pastes the buffer offset by the specified offset (sf::Vector2i) onto the "under pile" by creating "under cells" for each of the cells in the buffer. If offset is omitted, offset becomes (0, 0).

• pasteOver(index, offset)
  as pasteOver() above but instead of pasting the most recently added buffer, it pastes from the buffer specified by the buffer index. The offset can also be omitted here.

• pasteUnder(index, offset)
  as pasteUnder() above but instead of pasting the most recently added buffer, it pastes from the buffer specified by the buffer index. The offset can also be omitted here.

Manual Scrolling

If amount is provided, the screen is scrolled that many times, otherwise it is only scrolled once. If the Wrap On Manual Scroll switch is enabled, the cells "pushed off the edge" appear on the opposite side, otherwise the new cells are cleared.

• scrollUp(unsigned int amount)
  scrolls the screen up (all cells are moved upwards) by amount. If amount is omitted, it is scrolled once.

• scrollDown(unsigned int amount)
  scrolls the screen down (all cells are moved downwards) by amount. If amount is omitted, it is scrolled once.

• scrollRight(unsigned int amount)
  scrolls the screen right (all cells are moved to the right) by amount. If amount is omitted, it is scrolled once.

• scrollLeft(unsigned int amount)
  scrolls the screen left (all cells are moved to the left) by amount. If amount is omitted, it is scrolled once.

• scrollUp(unsigned int amount, sf::IntRect selectionRectangle)
  scrolls the cells within the specified selection rectangle (sf::IntRect) up by the amount specified.

• scrollDown(unsigned int amount, sf::IntRect selectionRectangle)
  scrolls the cells within the specified selection rectangle (sf::IntRect) down by the amount specified.

• scrollRight(unsigned int amount, sf::IntRect selectionRectangle)
  scrolls the cells within the specified selection rectangle (sf::IntRect) right the amount specified.

• scrollLeft(unsigned int amount, sf::IntRect selectionRectangle)
  scrolls the cells within the specified selection rectangle (sf::IntRect) left by the amount specified.

Character Mapping

Mapping to cell values

• setMappedCharacter(char character, unsigned int value)
  adds the specified character to the character map and maps it to the value specified.

• setMappedCharacters(string characters, unsigned int initialValue)
  adds the specified characters provided in the string to the character map and maps them to the values beginning from initialValue.

• removeMappedCharacter(char character)
  removes the specified character from the character map.

• removeMappedCharacters(string characters)
  removes the specified characters provided in the string from the character map.

Mapping to cursor commands

• setMappedCursorCommandCharacter(char character, CursorCommand cursorCommand)
  adds the specified character to the character map that maps to cursor commands and maps it to the cursor command specified.

• setMappedCursorCommandCharacters(characters, cursorCommands)
  adds the specified characters provided in characters (a string) to the character map that maps to cursor commands and maps them to the cursor commands specified in cursorCommands. Note that cursorCommands is of type const std::vectorCs::CursorCommand&, a vector of cursor commands.

• removeMappedCursorCommandCharacter(char character)`
  removes the specified character from the character map that maps to cursor commands.

• removeMappedCursorCommandCharacters(string characters)`
  removes the specified characters provided in the string from the character map that maps to cursor commands.

Colour Palette

Standard palette mode allows specific and customisable palettes. Loading the RGB palette changes to the RGB palette mode. The palette becomes fixed and no longer manipulatable but allows complete and free access to all 24-bit RGB colours. Palette manipulation methods may throw exceptions due to being in RGB mode. To leave RGB mode, you can load different palette.

• loadPalette(palette)
  loads a supplied palette. Replaces any current palette. Sets the palette mode to standard or rgb depending on the palette chosen. The parameter is a strongly-typed enum that allows a choice of available palettes. The list of enum values is below.

• addColorToPalette(sf::Color)
  adds an sf::Color to the end of the palette.

• setPaletteColor(Color, sf::Color color)
  sets the palette colour specified by Color (colour commands are not allowed here), to the specified sf::Color.

• setPaletteSize(size)
  sets the palette to contain "size" number of colours. If the size is greater than the current size, the new colours are created in their default state. i.e. SFML colours default to sf::Color::Black.

• removePaletteColor(Color)
  removes the palette colour specified by Color (colour commands are not allowed here).

• cyclePaletteUp(Color firstColor, Color lastColor, amount)
  cycles the colours in the palette between the specified colours (inclusive) by shifting the colours to higher colour IDs. Colours that would be shifted past lastColor are wrapped to the range, starting from firstColor. If the colours are omitted, the entire palette is cycled. amount specified how many steps of cycle are performed. If amount is omitted, amount defaults to 1.

• cyclePaletteDown(Color firstColor, Color lastColor, amount)
  cycles the colours in the palette between the specified colours (inclusive) by shifting the colours to lower colour IDs. Colours that would be shifted past firstColor are wrapped to the range, starting from lastColor. If the colours are omitted, the entire palette is cycled. amount specified how many steps of cycle are performed. If amount is omitted, amount defaults to 1.

Available Palette Enum Values

• Cs::Palette::Default
  A basic 16-colour palette.

• Cs::Palette::Colors2BlackWhite
  A 2-colour palette: first colour is black; second colour is white.

• Cs::Palette::Colors2WhiteBlack
  A 2-colour palette: first colour is white; second colour is black.

• Cs::Palette::Colors8Rgb
  An 8-colour palette: all combinations of the three components (RGB) at fully on and fully off.

• Cs::Palette::Colors16Greenscale
  A 16-colour palette: 16 shades of green from full black (0, 0, 0) to full green (0, 255, 0).

• Cs::Palette::Colors16Grayscale
  A 16-colour palette: 16 shades of grey from full black (0, 0, 0) to full white (255, 255, 255).

• Cs::Palette::Colors16Sepia
  A 16-colour palette: 16 shades of sepia starting from full black (0, 0, 0), passing through sepia tones to almost white.

• Cs::Palette::Colors16Cga
  A 16-colour palette based on the CGA display palette.

• Cs::Palette::Colors16CgaNonIbm
  A 16-colour palette based on the earlier, non-IBM compatible CGA display palette (identical to Colors16ZxSpectrum below).

• Cs::Palette::Colors16Windows
  A 16-colour palette based on Windows' default 16-colour palette.

• Cs::Palette::Colors16Mac
  A 16-colour palette based on Mac's default 16-colour palette.

• Cs::Palette::Colors16ZxSpectrum
  A 16-colour palette based on the ZX Spectrum's palette.

• Cs::Palette::Colors16Html
  A 16-colour palette based on the palette defined here.

• Cs::Palette::Colors216Web
  A 216-colour palette of so-called "web-safe" colours.

• Cs::Palette::Colors256Greenscale
  A 256-colour palette: 256 shades of green from full black (0, 0, 0) to full green (0, 255, 0).

• Cs::Palette::Colors256Grayscale
  A 256-colour palette: 256 shades of grey from full black (0, 0, 0) to full white (255, 255, 255).

• Cs::Palette::Colors256Sepia
  A 256-colour palette: 256 shades of sepia starting from full black (0, 0, 0), passing through sepia tones to almost white.

• Cs::Palette::ColorsRgb
  A 24-bit/16,777,216-colour palette: combination of each colour component having 256 steps. Sets RGB palette mode. Colours in the palette are ordered so that the palette ID can be specified like this: RRGGBB in hex e.g. 0x00FF00 for green.

Direct manipulation

Similar to cell manipulation above, but takes a cell index rather than a cell location.

• poke(unsigned int index, Cell cell)
  changes the cell at index to the new cell

• poke(unsigned int index, unsigned int value)
  changes the value of the cell at index

• poke(unsigned int index, Color color)
  changes the colour (palette ID) of the cell at index

• poke(unsigned int index, Color color, Color backgroundColor)
  changes both (foreground and background) the colours (palette IDs) of the cell at index

• poke(unsigned int index, StretchType stretch)
  changes the stretch type of the cell at index

• poke(unsigned int index, CellAttributes attributes)
  changes the attributes of the cell at index

• poke(unsigned int index, bool attributeValue, Affect attributeMask)
  changes multiple attributes of the cell at index to the value specified by attributeValue. The attributes are selected using attributeMask, an "affect mask" (see Affect above). Any non-attributes present in the affect mask will be ignored.

• cell(unsigned int index)
  returns a reference to the actual cell stored in the class at the index specified. Note that modifying directly cannot cause the screen to be updated automatically.

• bufferCell(unsigned int bufferIndex, unsigned int cellIndex)
  returns a reference to the actual cell specified by cellIndex that is stored in the buffer specifed by bufferIndex. Note that modifying directly cannot cause the screen to be updated automatically.

Information

Setup

• getMode()
  returns an sf::Vector2u of the current mode (number of cells in each dimension).

• getNumberOfCells()
  returns an unsigned int of the total number of cells. This is equivalent to getMode().x * getMode().y

• getClearValue()
  returns an unsigned int representing the value to which a cell is set when it is cleared.

• getClearChar()
  returns a char representing the value to which a cell is set when it is cleared after 'unmapping' (if possible) the value to a char.

• getDarkAttributeMultiplier()
  returns a float representing the value that is multiplied to the colours in a cell when its dark attribute is true.

Texture Setup

• getNumberOfTilesInTexture2d()
  returns an sf::Vector2u of the number of tiles that are usable in the texture (within the specified "numberOfTextureTilesPerRow" and within the height of the texture).

• getNumberOfTilesInTexture()
  returns an unsigned int of the total number of usable tiles in the texture. This is equivalent to getNumberOfTilesInTexture2d().x * getNumberOfTilesInTexture2d().y

Switches

A bool is returned representing if that switch is set to true.

• getThrowExceptions()
• getUpdateAutomatically()
• getShowCursor()
• getShowBackground()
• getScrollAutomatically()
• getWrapOnManualScroll()
• getInvertCursor()
• getUseCursorColor()
• getAddNewColorToPalette()

Visual Representation

• getSize()
  returns an sf::Vector2f of the size of the Console Screen (see setSize above).

• getPerfectSize()
  returns an sf::Vector2f of the size that would display each pixel of the texture per one unit of the current view. The actual value is the texture tile size multiplied by the mode.

• getLocalBounds()
  returns an sf::FloatRect that contains the Console Screen before any SFML transformations.

• getGlobalBounds()
  returns an sf::FloatRect that contains the Console Screen after any SFML transformations.

• getLocationAtCoord(coord)
  returns an sf::Vector2f that represents the cell's location that is at the co-ordinate passed by coord (sf::Vector2f). This return value is not an sf::Vector2u as this also shows which part of the cell is at the co-ordinate.

• getCoordAtLocation(location)
  returns an sf::Vector2f that represents the co-ordinate of the the passed cell location (sf::Vector2f). This parameter is not an sf::Vector2u as this allows any part of the cell to be specified.

Print Properties

The PrintType parameter, which can be omitted, for each of the print properties method specifies from which set of print properties the information is retrieved.
Possible PrintType values are:

• Cursor for cursor printing properties

• Direct for direct printing properties

• Current for the print properties which are currently active. This is the default value if the parameter is omitted.

• getLocation(PrintType)
  returns a Cs::Location (an alias for sf::Vector2u) of the specified print properties' location.

• getIndex(PrintType)
  returns an unsigned int of the specified print properties' location as a cell index.

• getColorPair(PrintType)
  returns a Cs::ColorPair (contains Cs::Color foreground and Cs::Color background) of the specified print properties' colours.

• getStretchType(PrintType)
  returns a Cs::StretchType indicating the current stretch type value in the specified print properties.

• getCellAttributes(PrintType)
  returns a Cs::CellAttributes that contains all cell attribute flags in the specified print properties.

• getCellAttributesBitmask(PrintType)
  returns an unsigned int representing the "affect (bit)mask" of all the CellAttributes in the specified print properties. As all attributes in the Affect enum are of values within the first nibble of the byte, this return value will always be either zero or be between 0x10 (16) and 0xF0 (240), with the second nibble always being zero.

• getAffectBitmask(PrintType)
  returns an unsigned int representing the "affect (bit)mask" in the specified print properties.

• getColorType(PrintType)
  returns a Cs::ColorType representing the current ColorType value (which colour is currently active) in the specified print properties.

Cursor

• getCursorValue()
  returns an integer representing the cell value used to display the cursor. A negative value (-1) is used to display no tile for the cursor.

• getCursorChar(bool)
  returns a char representing the character that is used to display the cursor. If the bool is true, the character is mapped otherwise it's almost identical to getCursorValue() above. If the bool is omitted, it defaults to true.

• getCursorColor()
  returns a Cs::Color representing the Color (palette ID) used for the cursor.

• getCursorTab()
  returns an unsigned int representing the current tab size.

Cells

• getCellAt(Location)
  returns a (copy of) the Cs::Cell at the specified location.

• getValueAt(Location)
  returns an unsigned int representing the value of the cell at the specified location.

• getColorAt(Location)
  returns a Cs::Color (palette ID) of the cell's colour at the specified location.

• getBackgroundColorAt(Location)
  returns a Cs::Color (palette ID) of the cell's background colour at the specified location.

• getStretchAt(Location)
  returns a Cs::StretchType representing the stretch value of the cell at the specified location.

• getAttributesAt(Location)
  returns the entire cell's attributes (of type Cs::CellAttributes - see setAttributes()) from the specified location.

• getAttributeAt(Location, Affect attributeMask)
  returns a bool of the cell's selected attribute - selected with attributeMask value - that is at the specified location. attributeMask should only be a single Affect attribute value; if contains multiple attributes, it will use only one and ignore the rest. Note that the order of precedence may be changed at any time.

Character Mapping

• getIsMappedCharacter(character)
  returns a bool representing if the specified character currently has a mapping associated with it.

• getMappedCharacter(character)
  returns an unsigned int representing the cell value to which the specified character is mapped.

• getIsMappedCursorCommandCharacter(character)
  returns a bool representing if the specified character currently has a mapping associated with it that maps it to a cursor command.

• getMappedCursorCommandCharacter(character)
  returns a Cs::CursorCommand representing the cursor command to which the specified character is mapped.

Palette

• getPaletteColor(Color)
  returns an sf::Color of the Color (palette ID) provided. Colour commands are not usable here.

• getPaletteSize()
  returns an unsigned int of the number of colours in the palette. There must always be at least one colour in the palette so this value can never be zero.

Buffers

• getNumberOfBuffers()
  returns an unsigned int of the number of buffers that are currently stored.

• getSizeOfBuffer(index)
  returns an sf::Vector2u of the size of the specified buffer.

Direct Manipulation

• peek(unsigned int index)
  returns a type Cs::Cell (a copy of the entire cell) from the cell at index

• cell(unsigned int index)
  returns a reference to the actual Cs::Cell stored in the class at index. Note that this allows direct manipulation and updates cannot be performed automatically. This is also listed above with the "pokes".

Simple Example

#include <SFML/Graphics.hpp>
#include <SelbaWard/ConsoleScreen.hpp>
#include <SelbaWard/PaletteEnums.hpp>
int main()
{
    sf::RenderWindow window(sf::VideoMode({ 320u, 300u }), "Console Screen simple example", sf::Style::Default);
    sf::Texture csTexture{};
    if (!csTexture.loadFromFile("resources/Windows Console ASCII.png"))
        return EXIT_FAILURE;
    Cs cs({ 16u, 9u });
    cs.setTexture(csTexture, 16u, { 8u, 12u }); // texture, number of tiles per row, tile size
    cs.setSize({ 256.f, 216.f }); // scaled x2
    cs.setOrigin(cs.getLocalBounds().size / 2.f);
    cs.setPosition(sf::Vector2f(window.getSize() / 2u));
    cs.setRotation(sf::degrees(20.f));
    cs.crash(); // randomise cells' values and colours
    cs << Cs::Direct::Begin << Cs::Bg(sw::Palette::Default::Blue) <<
        Cs::Fg(sw::Palette::Default::Cyan) << Cs::Location(5, 2) << "Selba" <<
        Cs::Fg(sw::Palette::Default::White) << Cs::Location(6, 3) << "Ward!" <<
        Cs::Direct::End;
    cs << Cs::ColorPair(sw::Palette::Default::Green, sw::Palette::Default::Black);
    cs << Cs::Location(3, 5) << "Console" << Cs::Location(7, 6) << "Screen";
    while (window.isOpen())
    {
        while (const auto event{ window.pollEvent() }) if (event->is<sf::Event::Closed>()) window.close();
        window.clear();
        window.draw(cs);
        window.display();
    }
}

The code above displays:

(this will display differently every time as the majority of its cells are randomly generated)

Note: the texture for this example is available, along with more examples, in the examples folder, although you can use your own images.

_{(ConsoleScreen v2.4)}