/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* 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
# include <stddef.h>
# ifndef __os_h
# include "os.h"
# endif
# ifndef __drawmod_h
# include "drawmod.h"
# endif
# ifndef __wimp_h
# include "wimp.h"
# endif
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 0x0001 /* justify text */
#define font_RUBOUT 0x0002 /* rub-out box required */
#define font_ABS 0x0004 /* absolute co-ordinates */
/* 8 not used */
#define font_OSCOORDS 0x0010 /* os coords supplied (otherwise 1/72000 inch) */
#define font_LENGTH 0x0080 /* length supplied */
#define font_16BIT 0x1000 /* 16-bit string supplied */
#define font_32BIT 0x2000 /* 32-bit string supplied */
/* ------------------------------- 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);
/*---------------------------------------------------------------------------*/
/*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);
/* ------------------------ font_makemenu --------------------------------
* Description: Constructs a Wimp menu of all available fonts
*
* Parameters: wimp_menustr ** menup -- on entry, *menup = result from last time, or NULL
* char * tickitem -- font identifier to tick, else NULL => none, or 1 => system font
* fontmenu_flags flags -- 0 => construct menu without 'System font' at top
* 1 => construct menu with 'System font' at top
* 2 => just delete the supplied menu structure
* Returns: possible error condition
* Other Info: *menup -> font menu (suitable for passing to Wimp_CreateMenu)
*
*/
typedef enum {
fontmenu_WithoutSystemFont = 0,
fontmenu_WithSystemFont = 1,
fontmenu_Delete = 2
} fontmenu_flags;
extern os_error *font_makemenu(wimp_menustr ** menup, char * tickitem, fontmenu_flags flags);
/* ------------------------ font_decodemenu --------------------------------
* Description: Decodes a menu click in a font menu
*
* Parameters: wimp_menustr * menu -- pointer to font menu
* int * selections -- list of menu selection indices
* char ** resultp -- pointer to pointer to contain answer
* *resultp -> previous buffer, or NULL
* Returns: possible error condition
* Other Info: *resultp -> malloc block containing font identifier
* the initial value of *resultp is realloc()ed to obtain the new buffer
* the resulting buffer should be free()ed by the caller when no longer required
*
* if menu includes system font, check for selections[0]==0 before calling this
* (font_decodemenu will return "System font", which isn't very useful)
* The format of the font identifier string is documented in the Font Manager spec.
*/
extern os_error *font_decodemenu(wimp_menustr * menu, int * selections, char ** resultp);
# endif
/* end font.h */