font.h File Reference

#include <stdbool.h>
#include <mcp/syscalls.h>
#include "a2560k.h"

Go to the source code of this file.

Data Structures
struct	Font
	This Font object is essentially the Mac "fontRecord" struct, with added pointers for the data tables. More...

Macros
#define	FONT_RECORD_SIZE   26
	size, in bytes, of the font record (minus tables) as stored in Mac FONT resources
#define	FONT_CHAR_FOENIX_OUTLINE   0x11
	the outlined Foenix character
#define	FONT_CHAR_CHECKMARK   0x12
	the checkmark character
#define	FONT_CHAR_DIAMOND   0x13
	the diamond character
#define	FONT_CHAR_FOENIX_REG   0x14
	the non-outlined Foenix character
#define	FONT_CHAR_MENU_RIGHT   0x15
	the '>' style character for use in showing submenus
#define	FONT_CHAR_MENU_RIGHT_WIDTH   7
	the width, in pixels, of the standard '>' for menu sub-menus. Every font is to use the same width, regardless of style or size.

Functions
Font *	Font_New (uint8_t *the_data, uint16_t data_size)
	Create a Font object, and populate it from the passed buffer. More...
bool	Font_Destroy (Font **the_font)
char *	Font_DrawStringInBox (Bitmap *the_bitmap, int16_t width, int16_t height, char *the_string, int16_t num_chars, char **wrap_buffer, bool(*continue_function)(void))
	Draw a string in a rectangular block on the screen, with wrap. More...
int16_t	Font_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...
int16_t	Font_DrawChar (Bitmap *the_bitmap, uint8_t the_char, Font *the_font)
	Draw one character on the bitmap, at the current bitmap pen coordinates NOTE: if the draw action is successful, the bitmap's current pen position will be updated in preparation for the next character draw. More...

Function Documentation

Font_Destroy()

bool Font_Destroy

(

Font **

the_font

)

Parameters

the_font

– pointer to the pointer for the Font object to be destroyed

Returns

Returns false if the pointer to the passed Font was NULL

Font_DrawChar()

int16_t Font_DrawChar	(	Bitmap *	the_bitmap,
		uint8_t	the_char,
		Font *	the_font
	)

Draw one character on the bitmap, at the current bitmap pen coordinates NOTE: if the draw action is successful, the bitmap's current pen position will be updated in preparation for the next character draw.

TODO: stop passing Font, and have the concept of a current font for a given bitmap. and maybe a default system font.

Parameters

the_bitmap	– reference to a valid Bitmap object.
the_font	– reference to a complete, loaded Font object. If the passed Font object is NULL, the font associated with the Bitmap object passed will be used instead. If the Bitmap does not have a font, the function will return an error.
the_char	– the character to be drawn. If the character does not exist in the font, the font's "missing glyph" character will be used instead.

Returns

Returns number of horizontal pixels used, including left/right offsets, or -1 on any error condition.

Font_DrawStringInBox()

char * Font_DrawStringInBox	(	Bitmap *	the_bitmap,
		int16_t	width,
		int16_t	height,
		char *	the_string,
		int16_t	num_chars,
		char **	wrap_buffer,
		bool(*)(void)	continue_function
	)

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

The current font, pen location, and pen color of the bitmap will be used 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_bitmap	– a valid Bitmap object, with a valid font_ property
width	– the horizontal size of the text wrap box, in pixels. The total of 'width' and the current X coord of the bitmap must not be greater than width of the bitmap.
height	– the vertical size of the text wrap box, in pixels. The total of 'height' and the current Y coord of the bitmap must not be greater than height of the bitmap.
the_string	– the null-terminated string to be displayed.
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 display the entire string if it fits.
wrap_buffer	– pointer to a pointer to a temporary text buffer that can be used to hold the wrapped ('formatted') characters. The buffer must be large enough to hold num_chars of incoming text, plus additional line break characters where necessary.
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.

Font_MeasureStringWidth()

int16_t Font_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.

The current font of the bitmap will be used as the basis for calculating fit.

Parameters

the_font	– reference to a complete, loaded Font object.
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. This value will be ignored. It exists to keep text-mode text-wrapping compatible with bitmap-font text-wrapping.
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.

Font_New()

Font * Font_New	(	uint8_t *	the_data,
		uint16_t	data_size
	)

Create a Font object, and populate it from the passed buffer.

NOTE: it is not possible to create a Font object without having a valid 'FONT' data chunk already in memory. NOTE: this allocates new memory for the font, and copies the font data to it from the passed buffer. It is not dependent on the data in the buffer after returning.

Parameters

the_data	– Must contain a valid Mac 'FONT' resource data hunk.
data_size	– Count of all bytes in the data buffer, including the font record and following font tables.

Returns

Returns a new Font object. Returns NULL on any error condition.