/*
    ####             #    #     # #
    #   #            #    #       #          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 Desk_Window_ModeChange (in Window.c.ModeChange) has to go
through all loaded templates and windows looking for outline fonts, lose
them with Desk_Font_LoseFont, recreate them with Desk_Font_FindFont and substitute
the new Desk_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 (Desk_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 Desk_font2_block is finished
with.

Font2 also registers an exit-handler which calls Desk_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 (Desk_font2_block *),
ie. a (Desk_font2_block **). This is because some of the functions set the
pointer to NULL or a new value.



Use like:

Desk_font2_block	*font2;

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

Then in a redrawer:

Desk_Font_Paint3(
	font2->handle, 	|* Always correct for the current mode	*|
	"Some text...", 
	Desk_font_plot_OSCOORS | Desk_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 Desk_font_info for all fonts they use, so Font2 provides this
information automatically to a) save calls to Desk_Font_ReadInfo or b) save
memory by storing each Desk_font_handle's information just once, regardless
of how many times the applcation is using the font.

*/


#ifndef __Desk_Font2_h
#define __Desk_Font2_h

#ifdef __cplusplus
	extern "C" {
#endif


#ifndef __Desk_Font_h
	#include "Desk.Font.h"
#endif




typedef struct Desk_font2_block	{
	Desk_font_handle	handle;		/* Use for all font actions	*/
	Desk_font_info	info;		/* Always up-to-date info	*/
	}
	Desk_font2_block;


Desk_os_error	*Desk_Font2_ClaimFont(   Desk_font2_block **font2, const char *name, int sizex, int sizey);
/*
Makes (*font2) point to a suitable Desk_font2_block. Do not call this if
font2 is already set - use Desk_Font2_ReclaimFont in this case.

sizex and sizey should be 16*pointsize.

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

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

sizex and sizey should be 16*pointsize.
*/

void		Desk_Font2_ReleaseFont( Desk_font2_block **font2);
/*
Calls Desk_Font_LoseFont( (*font2)->handle) if *font2!=NULL, and then 
sets *font2 to NULL
*/

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




#ifdef Desk_DeskLib_DEBUG
	#ifdef Desk__making_Font2
		#include "Debug.h"
		#define Desk_debug_level Desk_font2_debuglevel
	#endif
	
	extern int	Desk_font2_debuglevel;
/*
In the debug version of DeskLib, this is the Font2 library's own
version of Desk_debug_level. It is initially 0; a program can set it to
different values to turn on different debug ouputs in the Font2
library.
 */
#endif


#ifdef __cplusplus
}
#endif


#endif
