1 /****************************************************************************
2 * This source file was written by Acorn Computers Limited. It is part of *
3 * the RISCOS library for writing applications in C for RISC OS. It may be *
4 * used freely in the creation of programs for Archimedes. It should be *
5 * used with Acorn's C Compiler Release 3 or later. *
7 ***************************************************************************/
11 * Purpose: access to RISC OS font facilities
24 typedef int font; /* abstract font handle */
27 /* ---------------------------- font_cacheaddress --------------------------
28 * Description: Informs caller of font cache used and font cache size.
30 * Parameters: int *version -- version number
31 * int *cacheused -- amount of font cache used (in bytes)
32 * int *cachesize -- total size of font cache (in bytes)
33 * Returns: os_error* -- possible error condition
34 * Other Info: Version number is *100, so v.1.07 would be returned as 107.
38 extern os_error * font_cacheaddress(int *version, int *cacheused, int *cachesize);
41 /* ------------------------------- font_find -------------------------------
42 * Description: Gives caller a handle to font, given its name.
44 * Parameters: char *name -- the font name
45 * int xsize, ysize -- x/y point size (in 16ths of a point)
46 * int xres, yres -- x/y resolution in dots per inch
47 * font* -- the returned font handle
48 * Returns: Possible error condition.
53 extern os_error * font_find(
55 int xsize, int ysize, /* in 16ths of a point */
56 int xres, int yres, /* dots per inch of resolution: 0->use default */
60 /* ------------------------------- font_lose -------------------------------
61 * Description: Informs font manager that a font is no longer needed
63 * Parameters: font f -- the font
64 * Returns: possible error condition.
69 extern os_error * font_lose(font f);
71 typedef struct font_def {
73 int xsize, ysize, xres, yres; /* as above */
78 /* ------------------------------ font_readdef -----------------------------
79 * Description: Get details about a font, given its handle.
81 * Parameters: font -- the font handle
82 * font_def* -- pointer to buffer to hold returned details
83 * Returns: possible error condition.
84 * Other Info: This function fills in details re: font, into the supplied
85 * buffer(a variable of type 'font_def').
86 * fields of this buffer are as follows:
88 * xsize, ysize -- x/y point size * 16
89 * xres, yres -- x/y resolution (dots per inch)
90 * usage -- number of times Font_FindFont has found
91 * the font minus number of times
92 * Font_LoseFont has been used on it
93 * age -- number of font accesses made since this
94 * one was last accessed.
98 extern os_error * font_readdef(font, font_def*);
100 typedef struct font_info {
101 int minx, miny, maxx, maxy;
105 /* ------------------------------- font_readinfo ---------------------------
106 * Description: Informs caller of minimal area covering any character in
107 * the font bounding box.
109 * Parameters: font -- the font handle
110 * font_info* -- pointer to buffer to hold returned details
111 * Returns: possible error condition.
112 * Other Info: Fills in details re: font in supplied buffer (variable of
114 * fields of this buffer are as follows:
115 * minx -- min x coord in pixels (inclusive)
116 * maxx -- max x coord in pixels (inclusive)
117 * miny -- min y coord in pixels (exclusive)
118 * maxy -- max y coord in pixels (exclusive).
122 extern os_error * font_readinfo(font, font_info*);
125 typedef struct font_string {
128 int x; /* inout, in 1/72000 inch */
129 int y; /* inout, in 1/72000 inch */
130 int split; /* inout: space char, or -1 */
131 /* on exit, = count of space or printable */
132 int term; /* inout, index into s */
137 /* -------------------------------- font_strwidth --------------------------
138 * Description: Determine 'width' of string.
140 * Parameters: font_string *fs -- the string, with fields:
142 * x -- max x offset before termination
143 * y -- max y offset before termination
144 * split -- string split character
145 * term -- index of char to terminate by
146 * Returns: possible error condition.
147 * Other Info: On exit fs fields hold:
149 * x -- x offset after printing string
150 * y -- y offset after printing string
151 * split -- no. of split chars found
152 * no. of printable chars if split was -1
153 * term -- index into string at which terminated.
157 extern os_error * font_strwidth(font_string *fs);
161 #define font_JUSTIFY 0x01 /* justify text */
162 #define font_RUBOUT 0x02 /* rub-out box required */
163 #define font_ABS 0x04 /* absolute co-ordinates */
165 #define font_OSCOORDS 0x10 /* os coords supplied (otherwise 1/72000 inch) */
168 /* ------------------------------- font_paint -----------------------------
169 * Description: Paint the given string at coords x,y.
171 * Parameters: char * -- the string
172 * int options -- set using "paint options" defined above
173 * int x, y -- coords (either os or 1/72000 inch)
174 * Returns: possible error condition.
179 extern os_error * font_paint(char*, int options, int x, int y);
182 /* ------------------------------- font_caret -----------------------------
183 * Description: Set colour, size and position of the caret.
185 * Parameters: int colour -- EORed onto screen
186 * int height -- in OS coordinates
187 * int flags -- bit 4 set ==> OS coords, else 1/72000 inch
188 * int x,y -- x/y coords
189 * Returns: possible error condition.
194 extern os_error *font_caret(int colour, int height, int flags, int x, int y);
197 /* ---------------------------- font_converttoos ---------------------------
198 * Description: Converts coords in 1/72000 inch to OS units.
200 * Parameters: int x_inch, y_inch -- x/y coords in 1/72000 inch
201 * int *x_os, *y_os -- x/y coords in OS units
202 * Returns: possible error condition.
207 extern os_error *font_converttoos(int x_inch, int y_inch, int *x_os, int *y_os);
210 /* --------------------------- font_converttopoints ------------------------
211 * Description: Converts OS units to 1/72000 inch.
213 * Parameters: int x_os, y_os -- x/y coords in OS units
214 * int *x_inch, *y_inch -- x/y coords in 1/72000 inch
215 * Returns: possible error condition.
220 extern os_error *font_converttopoints(int x_os, int y_os, int *x_inch, int *y_inch);
223 /* ------------------------------- font_setfont ----------------------------
224 * Description: Sets up font used for subsequent painting or size-requests.
226 * Parameters: font -- the font handle
227 * Returns: possible error condition.
232 extern os_error * font_setfont(font);
235 typedef struct font_state {
245 /* --------------------------------- font_current --------------------------
246 * Description: Informs caller of current font state.
248 * Parameters: font_state *f -- pointer to buffer to hold font state
249 * Returns: possible error condition.
250 * Other Info: returned buffer(into variable of type 'font_state'):
251 * font f -- handle of current font
252 * int back_colour -- current background colour
253 * int fore_colour -- current foreground colour
254 * int offset -- foreground colour offset.
258 extern os_error *font_current(font_state *f);
261 /* -------------------------------- font_future ----------------------------
262 * Description: Informs caller of font characteristics after a future
265 * Parameters: font_state *f -- pointer to buffer to hold font state
266 * Returns: possible error condition.
267 * Other Info: buffer contents:
268 * font f -- handle of font which would be selected
269 * int back_colour -- future background colour
270 * int fore_colour -- future foreground colour
271 * int offset -- foreground colour offset.
275 extern os_error *font_future(font_state *f);
278 /* ------------------------------- font_findcaret --------------------------
279 * Description: Informs caller of nearest point in a string to the caret
282 * Parameters: font_string *fs -- the string
283 * fields: char *s -- the string itself
284 * int x,y -- x/y coords of caret
285 * Returns: possible error condition.
286 * Other Info: returned fields of fs as in font_strwidth.
290 extern os_error *font_findcaret(font_string *fs);
293 /* ----------------------------- font_charbbox -----------------------------
294 * Description: Informs caller of bounding box of char in given font.
296 * Parameters: font -- the font handle
297 * char -- the ASCII character
298 * int options -- only relevant option if font_OSCOORDS
299 * font_info * -- pointer to buffer to hold font info
300 * Returns: possible error condition.
301 * Other Info: if OS coords are used and font has been scaled, box may
302 * be surrounded by area of blank pixels.
306 extern os_error * font_charbbox(font, char, int options, font_info*);
309 /* -------------------------- font_readscalefactor -------------------------
310 * Description: Informs caller of x and y scale factors used by font.
311 * manager for converting between OS coords and 1/72000 inch
313 * Parameters: int *x, *y -- returned scale factors
314 * Returns: possible error condition.
319 extern os_error *font_readscalefactor(int *x, int *y);
322 /* ---------------------------- font_setscalefactor -----------------------
323 * Description: Sets the scale factors used by font manager.
325 * Parameters: int x,y -- the new scale factors
326 * Returns: possible error condition.
327 * Other Info: scale factors may have been changed by another application
328 * well-behaved applications save and restore scale factors.
332 extern os_error *font_setscalefactor(int x, int y);
335 /* ------------------------------- font_list -------------------------------
336 * Description: Gives name of an available font.
338 * Parameters: char* -- pointer to buffer to hold font name
339 * int* -- count of fonts found (0 on first call)
340 * Returns: possible error condition.
341 * Other Info: count is -1 if no more names
342 * typically used in loop until count == -1.
346 extern os_error * font_list(char*, int*);
349 /* ------------------------------ font_setcolour ---------------------------
350 * Description: Sets the current font(optionally), changes foreground
351 * and background colours, and offset for that font.
353 * Parameters: font -- the font handle (0 for current font)
354 * int background, foreground -- back/foreground colours
355 * int offset -- foreground offset colour (-14 to +14)
356 * Returns: possible error condition.
361 extern os_error * font_setcolour(font, int background, int foreground, int offset);
364 #define font_BlueGun 0x01000000 /* 8-bit field: phsical colour blue gun. */
365 #define font_GreenGun 0x00010000 /* 8-bit field: phsical colour green gun. */
366 #define font_RedGun 0x00000100 /* 8-bit field: phsical colour red gun. */
369 /* --------------------------- font_setpalette -----------------------------
370 * Description: Sets the anti-alias palette
372 * Parameters: int background -- logical background colour
373 * int foreground -- logical foreground colour
374 * int offset -- foreground colour offset
375 * int physical_back -- physical background colour
376 * int physical_fore -- physical foreground colour
377 * Returns: possible error condition.
378 * Other Info: physical_back and physical_fore are of the form:
379 * 0xBBGGRR00 (see #defines above).
383 extern os_error *font_setpalette(int background, int foreground, int offset,
384 int physical_back, int physical_fore);
386 typedef struct font_threshold {
394 /* ------------------------- font_readthresholds ---------------------------
395 * Description: Reads the list of threshold values that the font manager
396 * uses when painting characters.
398 * Parameters: font_theshold *th -- pointer to result buffer
399 * Returns: possible error condition.
404 extern os_error *font_readthresholds(font_threshold *th);
407 /* ------------------------- font_setthresholds ----------------------------
408 * Description: Sets up threshold values for painting colours.
410 * Parameters: font_threshold *th -- pointer to a threshold table
411 * Returns: possible error condition.
416 extern os_error *font_setthresholds(font_threshold *th);
419 /* ------------------------- font_findcaretj -------------------------------
420 * Description: Finds nearest point where the caret can go (using
421 * justification offsets).
423 * Parameters: font_string *fs -- the string (set up as in font_findcaret)
424 * int offset_x, offset-y -- the justification offsets
425 * Returns: possible error condition.
426 * Other Info: if offsets are both zero then same as font_findcaret.
430 extern os_error *font_findcaretj(font_string *fs, int offset_x, int offset_y);
433 /* ------------------------ font_stringbbox --------------------------------
434 * Description: Measures the size of a string (without printing it).
436 * Parameters: char *s -- the string
437 * font_info *fi -- pointer to buffer to hold font info
438 * Returns: possible error condition.
439 * Other Info: fields returned in fi are:
440 * minx, miny -- bounding box min x/y
441 * maxx, maxy -- bounding box min x/y.
445 extern os_error *font_stringbbox(char *s, font_info *fi);
449 /*---------------------------------------------------------------------------*/
450 /*Routines to create a draw module path object from calls to font_paint*/
452 typedef enum {font_CONVERT, font_IGNORE, font_ERROR} font_action_on_bitmap;
457 BOOL output_skeleton,
458 font_action_on_bitmap action_on_bitmap
461 extern os_error *font_output_size (size_t *size);
464 *font_output_to_buffer
465 ( drawmod_buffer *buff_ptr,
467 BOOL output_skeleton,
468 font_action_on_bitmap action_on_bitmap
471 extern os_error *font_output_to_screen (void);