/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Font2.Font2.c
    Author:  Copyright  1994 Julian Smith
    Version: 1.00 (08 Jul 1995)
    Purpose: Fonts with automatic handling of mode-changing
*/


/*
The RISC OS font manager seems to work in terms of pixels rather than OS
coordinates, and so it doesn't adjust fonts when the user changes to a
screen mode with a different pixel-OS ratio. This results in fonts
changing size over mode changes, unless they are re-calculated.

This causes all sorts of complexity in DeskLib's Template and Window
libraries, because icons with outline fonts contain a font handle in the
icon data, so Window_ModeChange (in Window.c.ModeChange) has to go
through all loaded templates and windows looking for outline fonts, lose
them with Font_LoseFont, recreate them with Font_FindFont and substitute
the new font_handle values into the icon blocks.

For other uses of fonts, a simpler method is to make applications work
with a *pointer* to a font handle rather than a straight font handle,
and have a central agency take care of the actual font handles.

This is what Font2 does. The Font2 library can thus easily keep the list
of font handles (which the application gets pointers into) and change
the handles on mode changes without having to store the location of
every font handle the application uses, and change them when the mode is
changed. Hopefully this should make outline fonts much easier to use.

Note that if the application has many (font2_block *)'s, some will point
to the *same* place if they are the same font. Font2 keeps a count of
how many pointer there are so it knows when a font2_block is finished
with.

Font2 also registers an exit-handler which calls Font_LoseFont for all
fonts registered with Font2 when the application finished (the
font-handling in Window/Template has always done this).

All calls to Font2 functions require the address of the (font2_block *),
ie. a (font2_block **). This is because some of the functions set the
pointer to NULL or a new value.



Use like:

font2_block	*font2;

main()
{
Font2_ClaimFont( &font2, "Trinity.Medium", 16*12, 16*12);
}

Then in a redrawer:

Font_Paint3(
	font2->handle,	|* Always correct for the current mode	*|
	"Some text...", 
	font_plot_OSCOORS | font_plot_CURRENTHANDLE, 
	x, 
	y - font2->info.miny, 
	NULL, NULL, 0
	);

Note the use of font2->info. I expect most programs will need to know
about the font_info for all fonts they use, so Font2 provides this
information automatically to a) save calls to Font_ReadInfo or b) save
memory by storing each font_handle's information just once, regardless
of how many times the applcation is using the font.

*/


#ifndef __dl_font2_h
#define __dl_font2_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_font_h
#include "Font.h"
#endif




typedef struct font2_block	{
	font_handle	handle;		/* Use for all font actions	*/
	font_info	info;		/* Always up-to-date info	*/
	}
	font2_block;


os_error	*Font2_ClaimFont(   font2_block **font2, char *name, int sizex, int sizey);
/*
Makes (*font2) point to a suitable font2_block. Do not call this if
font2 is already set - use Font2_ReclaimFont in this case.

sizex and sizey should be 16*pointsize.

(*font2)->info will be set with Font_ReadInfo.
*/

os_error	*Font2_ReclaimFont( font2_block **font2, char *name, int xsize, int ysize);
/*
Releases existing font (if *font2!=NULL) and then makes *font2 point to a
new font2_block for the specified font.

sizex and sizey should be 16*pointsize.
*/

void		Font2_ReleaseFont( font2_block **font2);
/*
Calls Font_LoseFont( (*font2)->handle) if *font2!=NULL, and then 
sets *font2 to NULL
*/

void		Font2_Initialise( void);
/*
This is called automatically if necessary by Font2_(Re)Claim. It
registers an event handler for message_MODECHANGE message_type, which
re-finds all the font2 font handles.
*/






#ifdef __cplusplus
}
#endif


#endif
