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

    File:    Font.h
    Author:  Copyright  1993 Shaun Blackmore, Julian Smith
    Version: 1.02 (08 Jul 1995)
    Purpose: Assembler SWI veneers for the Font Manager
             NOTE that some names are not strictly 'DeskLib' style, to keep
             them consistent with the SWIs they represent ("Converttopoints",
             etc). However, macros with 'DeskLib' naming are provided to allow
             either naming style to be used.
    Mods:    08 Jul 1995 - Julian Smith - Added Font_Paint3 for use with RISC
                                          OS 3. Also various macros for the
                                          'plottype' argument of Font_Paint3.
*/

#ifndef __dl_font_h
#define __dl_font_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_core_h
#include "Core.h"
#endif

#ifndef __dl_wimp_h
#include "Wimp.h"
#endif

                                   
typedef int font_handle;

typedef struct
{
  char name[128];   /* NOTE: Font_ReadDefn returns this string CR terminated */
  int xsize, ysize, xres, yres;
  int age, usage;
} font_defn;


typedef struct
{
    int minx, miny, maxx, maxy;
} font_info;
/*
Used with Font_ReadInfo
*/

typedef struct
{
  char *s;              /* string */
  int x;                /* in/out, in 1/72000s of an inch */
  int y;                /* in/out, in 1/72000s of an inch */
  int split;            /* in/out: space char, or -1      */
                        /*         on exit, = count of space or printable */
  int term;             /* in/out: index into s */
} font_string;
/*
Used with Font_FindCaret, Font_StringWidth.
*/

typedef struct
{
  int background, foreground;
} font_colours;


typedef struct
{
  font_handle  font;
  font_colours colour;
  int          offset;
} font_state;
/*
Used with Font_CurrentFont and Font_FutureFont.
*/

typedef struct
{
  char offset;
  char thresholds[15];
} font_thresholds;
/*
Used with Font_ReadThresholds
*/

   /*  Font usage array  (font_array)
    *  This array is indexed by the font handle - each entry contains a
    *  count of how many times we have FindFont'd this font. This is used
    *  mainly by the template system (Wimp_LoadTemplate).
    *  See Font_LoseAllFonts
    *  For convenience, this is defined in Wimp.h (it is mainly used for
    *  template loading)
    *
    *  typedef struct
    *  {
    *    char fonts[256];
    *  } font_array;
    */

extern os_error *Font_CacheAddr(int *version, int *cacheused, int *cachesize);	/* PRMS 3-418 */
extern os_error *Font_ListFonts(char *name, int *count);			/* PRMS 3-450 */

extern os_error *Font_ReadDefn(font_handle font, font_defn *defn);		/* PRMS 3-424 */
extern os_error *Font_ReadInfo(font_handle font, font_info *info);		/* PRMs 3-426 */

extern os_error *Font_ConverttoOS(int x, int y, int *xout, int *yout);		/* PRMs 3-438 */
#define Font_ConvertToOS Font_ConverttoOS					/* PRMs 3-438 */
/*
Converts x and y from millipoints to OS coors.
(normally 400millipoints = 1 OS unit).
Both xout and yout must be valid addresses, even if you are only
interested in (say) xout.
*/

extern os_error *Font_Converttopoints(int x, int y, int *xout, int *yout);	/* PRMs 3-439 */
#define Font_ConvertToPoints Font_Converttopoints				/* PRMs 3-439 */

extern os_error *Font_FindFont(font_handle *font, char *name,
                               int xsize, int ysize, int xres, int yres);	/* PRMs 3-419 */

extern os_error *Font_LoseFont(font_handle font);				/* PRMs 3-423 */

extern void Font_LoseAllFonts(font_array *fonts);
/*  Font_LoseAllFonts
 *  Given a font usage array, this function calls Font_Lose for all fonts
 *  used, and sets the font usage array to zeros. See above for info on
 *  how a font usage array is organised...
 */

extern os_error *Font_SetFont(font_handle font);		/* PRMs 3-440 */
extern os_error *Font_CurrentFont(font_state *state);		/* PRMs 3-441 */
extern os_error *Font_FutureFont(font_state *state);		/* PRMs 3-443 */

extern os_error *Font_Paint(char *, int options, int x, int y);	/* PRMs 3-429 */
/*
Use Font_Paint3 to use RISC OS 3 features.
*/

extern os_error *Font_Caret(int colour, int height, int flags, int x, int y);	/* PRMs 3-436 */
extern os_error *Font_FindCaret(font_string *string);				/* PRMs 3-444 */
extern os_error *Font_FindCaretJ(font_string *s, int xoffset, int yoffset);	/* PRMs 3-461 */

extern os_error *Font_StringWidth(font_string *string);		/* PRMs 3-427 */
extern os_error *Font_CharBBox(font_handle font, char c,
                               int flags, font_info *info);	/* PRMs 3-446 */
extern os_error *Font_StringBBox(char *string, font_info *info);/* PRMs 3-463 */

extern os_error *Font_ReadScaleFactor(int *xscale, int *yscale);/* PRMs 3-448 */

extern os_error *Font_SetFontColours(font_handle font,
                                     int back_colour, int fore_colour,
                                     int offset);
extern os_error *Font_SetPalette(int back_log,  int fore_log,
                                 int offset,
                                 int back_phys, int fore_phys);

extern os_error *Font_ReadThresholds(font_thresholds *t);
extern os_error *Font_SetThresholds(font_thresholds *t);





#define font_justify_NONE	(0)
/*
No justification
*/

#define font_justify_CURSOR	(1<<0)
/* 
Justify between startpos and last graphics position.
Not to be used with font_justify_COORBLOCK or 
font_justify_NONE.
*/

#define font_justify_COORBLOCK	(1<<5)
/*
Justify according to 8-word coordinate pointed to by r5
Not to be used with font_justify_CURSOR, 
font_justify_NONE or font_plot_OSCOORS.
*/


#define font_rubout_NONE	(0)
/*
Don't do a rubout.
*/

#define font_rubout_CURSOR	(1<<1)
/*
Use the last two graphics cursor positions to define
the rubout box.
*/

#define font_rubout_COORBLOCK	(1<<1 + 1<<5)
/*
Rubout box is defined by the font_coorblock pointed to by r5.
Not RISC OS 2.
Not to be used with font_plot_OSCOORS.
*/

#define font_plot_OSCOORS	(1<<4)
/*
Coors are in OS coors.
Not to be used with font_justify_COORBLOCK or
font_rubout_COORBLOCK.
*/

#define font_plot_TRANSMATRIX	(1<<6)
/*
Use transformation matrix pointed to by r6
Not RISC OS 2.
Not to be used with font_plot_OSCOORS.
*/

#define font_STRLEN	(1<<7)
/*
r7 is length of string
Not RISC OS 2
*/

#define font_plot_CURRENTHANDLE	(1<<8)
/*
Use current handle iff r0=0
Not RISC OS 2
*/

#define font_plot_KERN		(1<<9)
/*
Kern the string.
Not RISC OS 2.
*/


typedef struct	{
	struct	{
		wimp_point	space;
		wimp_point	letter;
		}
		offsets;
		
	wimp_rect	rubout;
	}
	font_coorblock;
/*
Used with Font_Paint3
*/
	

typedef struct	{
	struct	{
		int	xx;	/* These names may not be right...	*/
		int	xy;
		int	yx;
		int	yy;
		}
		scale;
		
	wimp_point	translate;
	}
	font_transformation;
/*
Used with Font_Paint3
*/



os_error	*Font_Paint3( 
			font_handle		font, 
			const char		*string, 
			unsigned int		plottype,
			int			x,
			int			y,
			font_coorblock		*coorblock,
			font_transformation	*transformation,
			int			length
			);
/*

Veneer for the RISC OS 3 Font_Paint SWI.  Note that Font_Paint doesn't 
support any of the RISC OS 3 features.

See PRM 3-429

'plottype' should be a combination (using '|' rather than '+', because
some bits are set in more than one macro) of font_justify_NONE,
font_justify_CURSOR, font_justify_COORBLOCK, font_rubout_NONE,
font_rubout_CURSOR, font_rubout_COORBLOCK, font_plot_OSCOORS,
font_plot_TRANSMATRIX, font_STRLEN, font_plot_CURRENTHANDLE,
font_plot_KERN.


There are rather complicated rules for which of these are allowed at the
same time. The following is what I think is the situation.

You can use:
 
Only one of: font_justify_NONE, font_justify_CURSOR,
font_justify_COORBLOCK

Only one of: font_rubout_NONE, font_rubout_CURSOR, font_rubout_COORBLOCK

In addition, you may not use font_plot_OSCOORS  with any of
font_justify_COORBLOCK, font_rubout_COORBLOCK, font_plot_TRANSMATRIX


Another way of looking at this, is:

You can use just one font_justify_*

You can use just one font_rubout_*

You can only use font_plot_OSCOORS if you don't use any of:
font_justify_COORBLOCK, font_rubout_COORBLOCK, font_plot_TRANSMATRIX


Note that both font_justify_COORBLOCK and font_rubout_COORBLOCK use
wimp_rect 'coorblock'. If you use either of these, 'coorblock' mustn't
be NULL.


Just for fun, here's a run-down of the justification and rubout bits  in
Font_Paint's r2:

Bit
5 0 | Justification
----+--------------
0 0 | None
0 1 | Cursor
1 0 | Coor block r5
1 1 | Illegal

Bit
5 1 | Rubout
----+--------------
0 0 | None
0 1 | Cursor
1 0 | Illegal
1 1 | Coor block r5


These are rather unsymetrical...

*/







#ifdef __cplusplus
}
#endif


#endif
