Foenix A2650 OS/f Library: text.h File Reference

Searching...

No Matches

#include "general.h"
#include <stdbool.h>
#include "a2560k.h"

Macros
#define	SCREEN_FOR_TEXT_ATTR true
	param for functions with for_attr

Functions
int16_t	General_WrapAndTrimTextToFit (char orig_string, char formatted_string, int16_t max_chars_to_format, int16_t max_width, int16_t max_height, int16_t one_char_width, int16_t one_row_height, Font the_font, int16_t(measure_function)(Font , char , int16_t, int16_t, int16_t, int16_t *))
	Format a string by wrapping and trimming to fit the passed width and height. More...

bool	Text_CopyAttrMemToScreen (Screen the_screen, char the_source_buffer)
	Copy a full screen of attr from an off-screen buffer. More...

bool	Text_CopyAttrMemFromScreen (Screen the_screen, char the_target_buffer)
	Copy a full screen of text attributes to an off-screen buffer. More...

bool	Text_CopyCharMemToScreen (Screen the_screen, char the_source_buffer)
	Copy a full screen of text from an off-screen buffer. More...

bool	Text_CopyCharMemFromScreen (Screen the_screen, char the_target_buffer)
	Copy a full screen of text to an off-screen buffer. More...

bool	Text_CopyScreen (Screen the_screen, char the_buffer, bool to_screen, bool for_attr)
	Copy a full screen worth of EITHER text or attribute data to OR from an off-screen buffer. More...

bool	Text_CopyMemBox (Screen the_screen, char the_buffer, int16_t x1, int16_t y1, int16_t x2, int16_t y2, bool to_screen, bool for_attr)
	Copy a rectangular area of text or attr to or from an off-screen buffer. More...

void	Text_ClearScreen (Screen *the_screen, uint8_t fore_color, uint8_t back_color)
	Clear the text screen and reset foreground and background colors.

bool	Text_FillAttrMemForeBack (Screen *the_screen, uint8_t fore_color, uint8_t back_color)
	Fill the entire attribute memory of the passed screen with the specified fore- and back-color. More...

bool	Text_FillAttrMem (Screen *the_screen, uint8_t the_fill)
	Fill the entire attribute memory of the passed screen. More...

bool	Text_FillCharMem (Screen *the_screen, unsigned char the_fill)
	Fill the entire character memory of the passed screen. More...

bool	Text_FillBoxSlow (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Fill a box-shaped section of character and/or attribute memory This version uses char-by-char functions, so it is very slow. More...

bool	Text_FillBox (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, unsigned char the_char, uint8_t fore_color, uint8_t back_color)
	Fill character and attribute memory for a specific box area. More...

bool	Text_FillBoxCharOnly (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, unsigned char the_char)
	Fill character memory for a specific box area. More...

bool	Text_FillBoxAttrOnly (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t fore_color, uint8_t back_color)
	Fill attribute memory for a specific box area. More...

bool	Text_InvertBox (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2)
	Invert the colors of a rectangular block. More...

bool	Text_UpdateFontData (Screen the_screen, char new_font_data)
	replace the current font data with the data at the passed memory buffer More...

bool	Text_ShowFontChars (Screen *the_screen, int16_t y)
	Test function to display all 256 font characters. More...

bool	Text_SetCharAtXY (Screen *the_screen, int16_t x, int16_t y, unsigned char the_char)
	Set a char at a specified x, y coord. More...

bool	Text_SetAttrAtXY (Screen *the_screen, int16_t x, int16_t y, uint8_t the_attribute_value)
	Set the attribute value at a specified x, y coord. More...

bool	Text_SetColorAtXY (Screen *the_screen, int16_t x, int16_t y, uint8_t fore_color, uint8_t back_color)
	Set the attribute value at a specified x, y coord based on the foreground and background colors passed. More...

bool	Text_SetCharAndColorAtXY (Screen *the_screen, int16_t x, int16_t y, unsigned char the_char, uint8_t fore_color, uint8_t back_color)
	Draw a char at a specified x, y coord, also setting the color attributes. More...

unsigned char	Text_GetCharAtXY (Screen *the_screen, int16_t x, int16_t y)
	Get the char at a specified x, y coord. More...

uint8_t	Text_GetAttrAtXY (Screen *the_screen, int16_t x, int16_t y)
	Get the attribute value at a specified x, y coord. More...

uint8_t	Text_GetForeColorAtXY (Screen *the_screen, int16_t x, int16_t y)
	Get the foreground color at a specified x, y coord. More...

uint8_t	Text_GetBackColorAtXY (Screen *the_screen, int16_t x, int16_t y)
	Get the background color at a specified x, y coord. More...

bool	Text_DrawHLine (Screen *the_screen, int16_t x, int16_t y, int16_t the_line_len, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Draws a horizontal line from specified coords, for n characters, using the specified char and/or attribute. More...

bool	Text_DrawHLineSlow (Screen *the_screen, int16_t x, int16_t y, int16_t the_line_len, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Draws a horizontal line from specified coords, for n characters, using the specified char and/or attribute This version uses char-by-char functions, so it is very slow. More...

bool	Text_DrawVLine (Screen *the_screen, int16_t x, int16_t y, int16_t the_line_len, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Draws a vertical line from specified coords, for n characters, using the specified char and/or attribute. More...

bool	Text_DrawBoxCoords (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Draws a basic box based on 2 sets of coords, using the specified char and/or attribute for all cells. More...

bool	Text_DrawBoxCoordsFancy (Screen *the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t fore_color, uint8_t back_color)
	Draws a box based on 2 sets of coords, using the predetermined line and corner "graphics", and the passed colors. More...

bool	Text_DrawBox (Screen *the_screen, int16_t x, int16_t y, int16_t width, int16_t height, unsigned char the_char, uint8_t fore_color, uint8_t back_color, text_draw_choice the_draw_choice)
	Draws a basic box based on start coords and width/height, using the specified char and/or attribute for all cells. More...

bool	Text_DrawStringAtXY (Screen the_screen, int16_t x, int16_t y, char the_string, uint8_t fore_color, uint8_t back_color)
	Draw a string at a specified x, y coord, also setting the color attributes. More...

char *	Text_DrawStringInBox (Screen the_screen, int16_t x1, int16_t y1, int16_t x2, int16_t y2, char the_string, char *work_buffer, uint8_t fore_color, uint8_t back_color, bool(continue_function)(void))
	Draw a string in a rectangular block on the screen, with wrap. More...

int16_t	Text_MeasureStringWidth (Font the_font, char the_string, int16_t num_chars, int16_t available_width, int16_t fixed_char_width, int16_t *measured_width)
	Calculates how many characters of the passed string will fit into the passed pixel width. More...

char *	Text_GetMemLocForXY (Screen *the_screen, int16_t x, int16_t y, bool for_attr)
	Calculate the VRAM location of the specified coordinate. More...

uint8_t	Text_CalculateAttributeValue (uint8_t fore_color, uint8_t back_color)
	Calculate the combined text attribute value for a given foreground/background combination.

Function Documentation

◆ General_WrapAndTrimTextToFit()

int16_t General_WrapAndTrimTextToFit	(	char **	orig_string,
		char **	formatted_string,
		int16_t	max_chars_to_format,
		int16_t	max_width,
		int16_t	max_height,
		int16_t	one_char_width,
		int16_t	one_row_height,
		Font *	the_font,
		int16_t()(Font , char , int16_t, int16_t, int16_t, int16_t )	measure_function
	)

Format a string by wrapping and trimming to fit the passed width and height.

If the string cannot be displayed in the specified height and width, processing will stop, but it is not an error condition

Parameters

orig_string	- pointer to a string pointer that holds the text to be formatted. Upon return, this pointer will point to the next character after the last processed character (if the string was too long to fit). If the entire string fits, this pointer will not be adjusted.
formatted_string	- pointer to a string pointer to an empty string buffer that will be filled with the formatted version of the text.
max_chars_to_format	- the length of the string to format (in characters). If max_chars_to_format is less than the length of string, processing will stop after that many characters.
max_width	- the width into which the text must fit, in pixels.
max_height	- the height into which the text must fit, in pixels. Pass a 0 to disable the governor on vertical space.
one_char_width	- the width in pixels, of one character. NOTE - This is only used for fixed-width, text mode operations.
one_row_height	- the height in pixels, of one row of text, including any leading.
the_font	- the font object to be used in measuring width. This is optional and ignore if called for text mode operations.
measure_function	- pointer to the function responsible for measuring the graphical width of a string

Returns: Returns number of vertical pixels required. Returns -1 in any error condition.

◆ Text_CopyAttrMemFromScreen()

bool Text_CopyAttrMemFromScreen	(	Screen *	the_screen,
		char *	the_target_buffer
	)

Copy a full screen of text attributes to an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_target_buffer	- valid pointer to a block of memory big enough to hold the attribute data copied from the screen. It must be at least as large as the visible rows X visible columns of the screen.

Returns: Returns false on any error/invalid input.

◆ Text_CopyAttrMemToScreen()

bool Text_CopyAttrMemToScreen	(	Screen *	the_screen,
		char *	the_source_buffer
	)

Copy a full screen of attr from an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_source_buffer	- valid pointer to attribute value data that will be copied to the screen. It must be at least as large as the visible rows X visible columns of the screen.

Returns: Returns false on any error/invalid input.

◆ Text_CopyCharMemFromScreen()

bool Text_CopyCharMemFromScreen	(	Screen *	the_screen,
		char *	the_target_buffer
	)

Copy a full screen of text to an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_target_buffer	- valid pointer to a block of memory big enough to hold the character data copied from the screen. It must be at least as large as the visible rows X visible columns of the screen.

Returns: Returns false on any error/invalid input.

◆ Text_CopyCharMemToScreen()

bool Text_CopyCharMemToScreen	(	Screen *	the_screen,
		char *	the_source_buffer
	)

Copy a full screen of text from an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_source_buffer	- valid pointer to character data that will be copied to the screen. It must be at least as large as the visible rows X visible columns of the screen.

Returns: Returns false on any error/invalid input.

◆ Text_CopyMemBox()

bool Text_CopyMemBox	(	Screen *	the_screen,
		char *	the_buffer,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		bool	to_screen,
		bool	for_attr
	)

Copy a rectangular area of text or attr to or from an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_buffer	- valid pointer to a block of memory big enough to store (or alternatively act as the source of) the character or attribute data for the specified rectangle of screen memory.
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
to_screen	- true to copy to the screen from the buffer, false to copy from the screen to the buffer. Recommend using SCREEN_COPY_TO_SCREEN/SCREEN_COPY_FROM_SCREEN.
for_attr	- true to work with attribute data, false to work character data. Recommend using SCREEN_FOR_TEXT_ATTR/SCREEN_FOR_TEXT_CHAR.

Returns: Returns false on any error/invalid input.

◆ Text_CopyScreen()

bool Text_CopyScreen	(	Screen *	the_screen,
		char *	the_buffer,
		bool	to_screen,
		bool	for_attr
	)

Copy a full screen worth of EITHER text or attribute data to OR from an off-screen buffer.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_buffer	- valid pointer to a block of memory big enough to store (or alternatively act as the source of) the character or attribute data for the specified screen. It must be at least as large as the visible rows X visible columns of the screen.
to_screen	- true to copy to the screen from the buffer, false to copy from the screen to the buffer. Recommend using SCREEN_COPY_TO_SCREEN/SCREEN_COPY_FROM_SCREEN.
for_attr	- true to work with attribute data, false to work character data. Recommend using SCREEN_FOR_TEXT_ATTR/SCREEN_FOR_TEXT_CHAR.

Returns: Returns false on any error/invalid input.

◆ Text_DrawBox()

bool Text_DrawBox	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		int16_t	width,
		int16_t	height,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Draws a basic box based on start coords and width/height, using the specified char and/or attribute for all cells.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the starting horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the starting vertical position, between 0 and the screen's text_rows_vis_ - 1
width	- width, in character cells, of the rectangle to be drawn
height	- height, in character cells, of the rectangle to be drawn
the_char	- the character to be used when drawing the box
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_DrawBoxCoords()

bool Text_DrawBoxCoords	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Draws a basic box based on 2 sets of coords, using the specified char and/or attribute for all cells.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used when drawing the box
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_DrawBoxCoordsFancy()

bool Text_DrawBoxCoordsFancy	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Draws a box based on 2 sets of coords, using the predetermined line and corner "graphics", and the passed colors.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_DrawHLine()

bool Text_DrawHLine	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		int16_t	the_line_len,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Draws a horizontal line from specified coords, for n characters, using the specified char and/or attribute.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the starting horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the starting vertical position, between 0 and the screen's text_rows_vis_ - 1
the_line_len	- The total length of the line, in characters, including the start and end character.
the_char	- the character to be used when drawing
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_DrawHLineSlow()

bool Text_DrawHLineSlow	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		int16_t	the_line_len,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Draws a horizontal line from specified coords, for n characters, using the specified char and/or attribute This version uses char-by-char functions, so it is very slow.

It will be removed before release.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the starting horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the starting vertical position, between 0 and the screen's text_rows_vis_ - 1
the_line_len	- The total length of the line, in characters, including the start and end character.
the_char	- the character to be used when drawing
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_DrawStringAtXY()

bool Text_DrawStringAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		char *	the_string,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Draw a string at a specified x, y coord, also setting the color attributes.

If it is too long to display on the line it started, it will be truncated at the right edge of the screen. No word wrap is performed.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the starting horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the starting vertical position, between 0 and the screen's text_rows_vis_ - 1
the_string	- the null-terminated string to be drawn
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_DrawStringInBox()

char * Text_DrawStringInBox	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		char *	the_string,
		char **	work_buffer,
		uint8_t	fore_color,
		uint8_t	back_color,
		bool(*)(void)	continue_function
	)

Draw a string in a rectangular block on the screen, with wrap.

If a word can't be wrapped, it will break the word and move on to the next line. So if you pass a rect with 1 char of width, it will draw a vertical line of chars down the screen.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
the_string	- the null-terminated string to be displayed.
work_buffer	- pointer to a pointer to a char buffer that will be used for temporary work. Has to be large enough to contain the entire string passed
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
continue_function	- optional hook to a function that will be called if the provided text cannot fit into the specified box. If provided, the function will be called each time text exceeds available space. If the function returns true, another chunk of text will be displayed, replacing the first. If the function returns false, processing will stop. If no function is provided, processing will stop at the point text exceeds the available space.

Returns: Returns a pointer to the first character in the string after which it stopped processing (if string is too long to be displayed in its entirety). Returns the original string if the entire string was processed successfully. Returns NULL in the event of any error.

◆ Text_DrawVLine()

bool Text_DrawVLine	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		int16_t	the_line_len,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Draws a vertical line from specified coords, for n characters, using the specified char and/or attribute.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the starting horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the starting vertical position, between 0 and the screen's text_rows_vis_ - 1
the_line_len	- The total length of the line, in characters, including the start and end character.
the_char	- the character to be used when drawing
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_FillAttrMem()

bool Text_FillAttrMem	(	Screen *	the_screen,
		uint8_t	the_fill
	)

Fill the entire attribute memory of the passed screen.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_fill	- a 1-byte attribute code (foreground in high nibble, background in low nibble)

Returns: Returns false on any error/invalid input.

◆ Text_FillAttrMemForeBack()

bool Text_FillAttrMemForeBack	(	Screen *	the_screen,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Fill the entire attribute memory of the passed screen with the specified fore- and back-color.

Parameters

the_screen	- valid pointer to the target screen to operate on
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_FillBox()

bool Text_FillBox	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Fill character and attribute memory for a specific box area.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used for the fill operation
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_FillBoxAttrOnly()

bool Text_FillBoxAttrOnly	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Fill attribute memory for a specific box area.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_FillBoxCharOnly()

bool Text_FillBoxCharOnly	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		unsigned char	the_char
	)

Fill character memory for a specific box area.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used for the fill operation

Returns: Returns false on any error/invalid input.

◆ Text_FillBoxSlow()

bool Text_FillBoxSlow	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color,
		text_draw_choice	the_draw_choice
	)

Fill a box-shaped section of character and/or attribute memory This version uses char-by-char functions, so it is very slow.

It will be removed before release.

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used for the fill operation
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
the_draw_choice	- controls the scope of the action, and is one of CHAR_ONLY, ATTR_ONLY, or CHAR_AND_ATTR. See the text_draw_choice enum.

Returns: Returns false on any error/invalid input.

◆ Text_FillCharMem()

bool Text_FillCharMem	(	Screen *	the_screen,
		unsigned char	the_fill
	)

Fill the entire character memory of the passed screen.

Parameters

the_screen	- valid pointer to the target screen to operate on
the_fill	- a 1-byte character code

Returns: Returns false on any error/invalid input.

◆ Text_GetAttrAtXY()

uint8_t Text_GetAttrAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y
	)

Get the attribute value at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1

Returns: Returns a 1-byte attribute code (foreground in high nibble, background in low nibble)

◆ Text_GetBackColorAtXY()

uint8_t Text_GetBackColorAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y
	)

Get the background color at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1

Returns: Returns an index (0-15) to the background color LUT

◆ Text_GetCharAtXY()

unsigned char Text_GetCharAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y
	)

Get the char at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1

Returns: Returns a character code

◆ Text_GetForeColorAtXY()

uint8_t Text_GetForeColorAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y
	)

Get the foreground color at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1

Returns: Returns an index (0-15) to the foreground color LUT

◆ Text_GetMemLocForXY()

char * Text_GetMemLocForXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		bool	for_attr
	)

Calculate the VRAM location of the specified coordinate.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1
for_attr	- true to work with attribute data, false to work character data. Recommend using SCREEN_FOR_TEXT_ATTR/SCREEN_FOR_TEXT_CHAR.

◆ Text_InvertBox()

bool Text_InvertBox	(	Screen *	the_screen,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2
	)

Invert the colors of a rectangular block.

As this requires sampling each character cell, it is no faster (per cell) to do for entire screen as opposed to a subset box

Parameters

the_screen	- valid pointer to the target screen to operate on
x1	- the leftmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y1	- the uppermost vertical position, between 0 and the screen's text_rows_vis_ - 1
x2	- the rightmost horizontal position, between 0 and the screen's text_cols_vis_ - 1
y2	- the lowermost vertical position, between 0 and the screen's text_rows_vis_ - 1

Returns: Returns false on any error/invalid input.

◆ Text_MeasureStringWidth()

int16_t Text_MeasureStringWidth	(	Font *	the_font,
		char *	the_string,
		int16_t	num_chars,
		int16_t	available_width,
		int16_t	fixed_char_width,
		int16_t *	measured_width
	)

Calculates how many characters of the passed string will fit into the passed pixel width.

In Text Mode, all characters have the same fixed width, so this is measuring against the font width described in the screen object.

Parameters

the_font	- this is for consistency with the graphical font code. Pass a NULL here, the result will not be used.
the_string	- the null-terminated string to be measured.
num_chars	- either the length of the passed string, or as much of the string as should be displayed. Passing GEN_NO_STRLEN_CAP will mean it will attempt to measure the entire string.
available_width	- the width, in pixels, of the space the string is to be measured against.
fixed_char_width	- the width, in pixels, of one character.
measured_width	- the number of pixels needed to display the characters that fit into the available_width. If the entire string fit, this is the width in pixels of that string. If only X characters fit, it is the pixel width of those X characters.

Returns: Returns -1 in any error condition, or the number of characters that fit. If the entire string fits, the passed len will be returned.

◆ Text_SetAttrAtXY()

bool Text_SetAttrAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		uint8_t	the_attribute_value
	)

Set the attribute value at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1
the_attribute_value	- a 1-byte attribute code (foreground in high nibble, background in low nibble)

Returns: Returns false on any error/invalid input.

◆ Text_SetCharAndColorAtXY()

bool Text_SetCharAndColorAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		unsigned char	the_char,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Draw a char at a specified x, y coord, also setting the color attributes.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_SetCharAtXY()

bool Text_SetCharAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		unsigned char	the_char
	)

Set a char at a specified x, y coord.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1
the_char	- the character to be used

Returns: Returns false on any error/invalid input.

◆ Text_SetColorAtXY()

bool Text_SetColorAtXY	(	Screen *	the_screen,
		int16_t	x,
		int16_t	y,
		uint8_t	fore_color,
		uint8_t	back_color
	)

Set the attribute value at a specified x, y coord based on the foreground and background colors passed.

Parameters

the_screen	- valid pointer to the target screen to operate on
x	- the horizontal position, between 0 and the screen's text_cols_vis_ - 1
y	- the vertical position, between 0 and the screen's text_rows_vis_ - 1
fore_color	- Index to the desired foreground color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.
back_color	- Index to the desired background color (0-15). The predefined macro constants may be used (COLOR_DK_RED, etc.), but be aware that the colors are not fixed, and may not correspond to the names if the LUT in RAM has been modified.

Returns: Returns false on any error/invalid input.

◆ Text_ShowFontChars()

bool Text_ShowFontChars	(	Screen *	the_screen,
		int16_t	y
	)

Test function to display all 256 font characters.

Characters are rendered in 8 rows of 32 characters.

Parameters

the_screen	- valid pointer to the target screen to operate on
y	- the starting row to draw the font characters.

Returns: Returns false on any error/invalid input.

◆ Text_UpdateFontData()

bool Text_UpdateFontData	(	Screen *	the_screen,
		char *	new_font_data
	)

replace the current font data with the data at the passed memory buffer

Parameters

the_screen	- valid pointer to the target screen to operate on
new_font_data	- Pointer to 2K (256 characters x 8 lines/bytes each) of font data. Each byte represents one line of an 8x8 font glyph.

Returns: Returns false on any error/invalid input.

Macros

Functions

Function Documentation

◆ General_WrapAndTrimTextToFit()

◆ Text_CopyAttrMemFromScreen()

◆ Text_CopyAttrMemToScreen()

◆ Text_CopyCharMemFromScreen()

◆ Text_CopyCharMemToScreen()

◆ Text_CopyMemBox()

◆ Text_CopyScreen()

◆ Text_DrawBox()

◆ Text_DrawBoxCoords()

◆ Text_DrawBoxCoordsFancy()

◆ Text_DrawHLine()

◆ Text_DrawHLineSlow()

◆ Text_DrawStringAtXY()

◆ Text_DrawStringInBox()

◆ Text_DrawVLine()

◆ Text_FillAttrMem()

◆ Text_FillAttrMemForeBack()

◆ Text_FillBox()

◆ Text_FillBoxAttrOnly()

◆ Text_FillBoxCharOnly()

◆ Text_FillBoxSlow()

◆ Text_FillCharMem()

◆ Text_GetAttrAtXY()

◆ Text_GetBackColorAtXY()

◆ Text_GetCharAtXY()

◆ Text_GetForeColorAtXY()

◆ Text_GetMemLocForXY()

◆ Text_InvertBox()

◆ Text_MeasureStringWidth()

◆ Text_SetAttrAtXY()

◆ Text_SetCharAndColorAtXY()

◆ Text_SetCharAtXY()

◆ Text_SetColorAtXY()

◆ Text_ShowFontChars()

◆ Text_UpdateFontData()