/**************************************************************************** * This source file was written by Acorn Computers Limited. It is part of * * the RISCOS library for writing applications in C for RISC OS. It may be * * used freely in the creation of programs for Archimedes. It should be * * used with Acorn's C Compiler Release 3 or later. * * * ***************************************************************************/ /* * Title : font.h * Purpose: access to RISC OS font facilities * */ # ifndef __font_h # define __font_h # ifndef __os_h # include "os.h" # endif # include "drawmod.h" typedef int font; /* abstract font handle */ /* ---------------------------- font_cacheaddress -------------------------- * Description: Informs caller of font cache used and font cache size. * * Parameters: int *version -- version number * int *cacheused -- amount of font cache used (in bytes) * int *cachesize -- total size of font cache (in bytes) * Returns: os_error* -- possible error condition * Other Info: Version number is *100, so v.1.07 would be returned as 107. * */ extern os_error * font_cacheaddress(int *version, int *cacheused, int *cachesize); /* ------------------------------- font_find ------------------------------- * Description: Gives caller a handle to font, given its name. * * Parameters: char *name -- the font name * int xsize, ysize -- x/y point size (in 16ths of a point) * int xres, yres -- x/y resolution in dots per inch * font* -- the returned font handle * Returns: Possible error condition. * Other Info: none. * */ extern os_error * font_find( char* name, int xsize, int ysize, /* in 16ths of a point */ int xres, int yres, /* dots per inch of resolution: 0->use default */ font*); /* result */ /* ------------------------------- font_lose ------------------------------- * Description: Informs font manager that a font is no longer needed * * Parameters: font f -- the font * Returns: possible error condition. * Other Info: none. * */ extern os_error * font_lose(font f); typedef struct font_def { char name[16]; int xsize, ysize, xres, yres; /* as above */ int usage, age; } font_def; /* ------------------------------ font_readdef ----------------------------- * Description: Get details about a font, given its handle. * * Parameters: font -- the font handle * font_def* -- pointer to buffer to hold returned details * Returns: possible error condition. * Other Info: This function fills in details re: font, into the supplied * buffer(a variable of type 'font_def'). * fields of this buffer are as follows: * name -- font name * xsize, ysize -- x/y point size * 16 * xres, yres -- x/y resolution (dots per inch) * usage -- number of times Font_FindFont has found * the font minus number of times * Font_LoseFont has been used on it * age -- number of font accesses made since this * one was last accessed. * */ extern os_error * font_readdef(font, font_def*); typedef struct font_info { int minx, miny, maxx, maxy; } font_info; /* ------------------------------- font_readinfo --------------------------- * Description: Informs caller of minimal area covering any character in * the font bounding box. * * Parameters: font -- the font handle * font_info* -- pointer to buffer to hold returned details * Returns: possible error condition. * Other Info: Fills in details re: font in supplied buffer (variable of * type 'font_info'). * fields of this buffer are as follows: * minx -- min x coord in pixels (inclusive) * maxx -- max x coord in pixels (inclusive) * miny -- min y coord in pixels (exclusive) * maxy -- max y coord in pixels (exclusive). * */ extern os_error * font_readinfo(font, font_info*); typedef struct font_string { char* s; int x; /* inout, in 1/72000 inch */ int y; /* inout, in 1/72000 inch */ int split; /* inout: space char, or -1 */ /* on exit, = count of space or printable */ int term; /* inout, index into s */ } font_string; /* -------------------------------- font_strwidth -------------------------- * Description: Determine 'width' of string. * * Parameters: font_string *fs -- the string, with fields: * s -- string itself * x -- max x offset before termination * y -- max y offset before termination * split -- string split character * term -- index of char to terminate by * Returns: possible error condition. * Other Info: On exit fs fields hold: * s -- unchanged * x -- x offset after printing string * y -- y offset after printing string * split -- no. of split chars found * no. of printable chars if split was -1 * term -- index into string at which terminated. * */ extern os_error * font_strwidth(font_string *fs); /* paint options */ #define font_JUSTIFY 0x01 /* justify text */ #define font_RUBOUT 0x02 /* rub-out box required */ #define font_ABS 0x04 /* absolute co-ordinates */ /* 8 not used */ #define font_OSCOORDS 0x10 /* os coords supplied (otherwise 1/72000 inch) */ /* ------------------------------- font_paint ----------------------------- * Description: Paint the given string at coords x,y. * * Parameters: char * -- the string * int options -- set using "paint options" defined above * int x, y -- coords (either os or 1/72000 inch) * Returns: possible error condition. * Other Info: none. * */ extern os_error * font_paint(char*, int options, int x, int y); /* ------------------------------- font_caret ----------------------------- * Description: Set colour, size and position of the caret. * * Parameters: int colour -- EORed onto screen * int height -- in OS coordinates * int flags -- bit 4 set ==> OS coords, else 1/72000 inch * int x,y -- x/y coords * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_caret(int colour, int height, int flags, int x, int y); /* ---------------------------- font_converttoos --------------------------- * Description: Converts coords in 1/72000 inch to OS units. * * Parameters: int x_inch, y_inch -- x/y coords in 1/72000 inch * int *x_os, *y_os -- x/y coords in OS units * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_converttoos(int x_inch, int y_inch, int *x_os, int *y_os); /* --------------------------- font_converttopoints ------------------------ * Description: Converts OS units to 1/72000 inch. * * Parameters: int x_os, y_os -- x/y coords in OS units * int *x_inch, *y_inch -- x/y coords in 1/72000 inch * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_converttopoints(int x_os, int y_os, int *x_inch, int *y_inch); /* ------------------------------- font_setfont ---------------------------- * Description: Sets up font used for subsequent painting or size-requests. * * Parameters: font -- the font handle * Returns: possible error condition. * Other Info: none. * */ extern os_error * font_setfont(font); typedef struct font_state { font f; int back_colour; int fore_colour; int offset; } font_state; /* --------------------------------- font_current -------------------------- * Description: Informs caller of current font state. * * Parameters: font_state *f -- pointer to buffer to hold font state * Returns: possible error condition. * Other Info: returned buffer(into variable of type 'font_state'): * font f -- handle of current font * int back_colour -- current background colour * int fore_colour -- current foreground colour * int offset -- foreground colour offset. * */ extern os_error *font_current(font_state *f); /* -------------------------------- font_future ---------------------------- * Description: Informs caller of font characteristics after a future * font_paint. * * Parameters: font_state *f -- pointer to buffer to hold font state * Returns: possible error condition. * Other Info: buffer contents: * font f -- handle of font which would be selected * int back_colour -- future background colour * int fore_colour -- future foreground colour * int offset -- foreground colour offset. * */ extern os_error *font_future(font_state *f); /* ------------------------------- font_findcaret -------------------------- * Description: Informs caller of nearest point in a string to the caret * position. * * Parameters: font_string *fs -- the string * fields: char *s -- the string itself * int x,y -- x/y coords of caret * Returns: possible error condition. * Other Info: returned fields of fs as in font_strwidth. * */ extern os_error *font_findcaret(font_string *fs); /* ----------------------------- font_charbbox ----------------------------- * Description: Informs caller of bounding box of char in given font. * * Parameters: font -- the font handle * char -- the ASCII character * int options -- only relevant option if font_OSCOORDS * font_info * -- pointer to buffer to hold font info * Returns: possible error condition. * Other Info: if OS coords are used and font has been scaled, box may * be surrounded by area of blank pixels. * */ extern os_error * font_charbbox(font, char, int options, font_info*); /* -------------------------- font_readscalefactor ------------------------- * Description: Informs caller of x and y scale factors used by font. * manager for converting between OS coords and 1/72000 inch * * Parameters: int *x, *y -- returned scale factors * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_readscalefactor(int *x, int *y); /* ---------------------------- font_setscalefactor ----------------------- * Description: Sets the scale factors used by font manager. * * Parameters: int x,y -- the new scale factors * Returns: possible error condition. * Other Info: scale factors may have been changed by another application * well-behaved applications save and restore scale factors. * */ extern os_error *font_setscalefactor(int x, int y); /* ------------------------------- font_list ------------------------------- * Description: Gives name of an available font. * * Parameters: char* -- pointer to buffer to hold font name * int* -- count of fonts found (0 on first call) * Returns: possible error condition. * Other Info: count is -1 if no more names * typically used in loop until count == -1. * */ extern os_error * font_list(char*, int*); /* ------------------------------ font_setcolour --------------------------- * Description: Sets the current font(optionally), changes foreground * and background colours, and offset for that font. * * Parameters: font -- the font handle (0 for current font) * int background, foreground -- back/foreground colours * int offset -- foreground offset colour (-14 to +14) * Returns: possible error condition. * Other Info: none. * */ extern os_error * font_setcolour(font, int background, int foreground, int offset); #define font_BlueGun 0x01000000 /* 8-bit field: phsical colour blue gun. */ #define font_GreenGun 0x00010000 /* 8-bit field: phsical colour green gun. */ #define font_RedGun 0x00000100 /* 8-bit field: phsical colour red gun. */ /* --------------------------- font_setpalette ----------------------------- * Description: Sets the anti-alias palette * * Parameters: int background -- logical background colour * int foreground -- logical foreground colour * int offset -- foreground colour offset * int physical_back -- physical background colour * int physical_fore -- physical foreground colour * Returns: possible error condition. * Other Info: physical_back and physical_fore are of the form: * 0xBBGGRR00 (see #defines above). * */ extern os_error *font_setpalette(int background, int foreground, int offset, int physical_back, int physical_fore); typedef struct font_threshold { char offset; char thresholds[15]; } font_threshold; /* ------------------------- font_readthresholds --------------------------- * Description: Reads the list of threshold values that the font manager * uses when painting characters. * * Parameters: font_theshold *th -- pointer to result buffer * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_readthresholds(font_threshold *th); /* ------------------------- font_setthresholds ---------------------------- * Description: Sets up threshold values for painting colours. * * Parameters: font_threshold *th -- pointer to a threshold table * Returns: possible error condition. * Other Info: none. * */ extern os_error *font_setthresholds(font_threshold *th); /* ------------------------- font_findcaretj ------------------------------- * Description: Finds nearest point where the caret can go (using * justification offsets). * * Parameters: font_string *fs -- the string (set up as in font_findcaret) * int offset_x, offset-y -- the justification offsets * Returns: possible error condition. * Other Info: if offsets are both zero then same as font_findcaret. * */ extern os_error *font_findcaretj(font_string *fs, int offset_x, int offset_y); /* ------------------------ font_stringbbox -------------------------------- * Description: Measures the size of a string (without printing it). * * Parameters: char *s -- the string * font_info *fi -- pointer to buffer to hold font info * Returns: possible error condition. * Other Info: fields returned in fi are: * minx, miny -- bounding box min x/y * maxx, maxy -- bounding box min x/y. * */ extern os_error *font_stringbbox(char *s, font_info *fi); /* new SWIS */ /*---------------------------------------------------------------------------*/ /*Routines to create a draw module path object from calls to font_paint*/ typedef enum {font_CONVERT, font_IGNORE, font_ERROR} font_action_on_bitmap; extern os_error *font_output_to_null ( BOOL add_hints, BOOL output_skeleton, font_action_on_bitmap action_on_bitmap ); extern os_error *font_output_size (size_t *size); extern os_error *font_output_to_buffer ( drawmod_buffer *buff_ptr, BOOL add_hints, BOOL output_skeleton, font_action_on_bitmap action_on_bitmap ); extern os_error *font_output_to_screen (void); # endif /* end font.h */