chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/font

   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.                         *
   6  *                                                                          *
   7  ***************************************************************************/
   8
   9 /*
  10  * Title  : font.h
  11  * Purpose: access to RISC OS font facilities
  12  *
  13  */
  14
  15 # ifndef __font_h
  16 # define __font_h
  17
  18 # ifndef __os_h
  19 # include "os.h"
  20 # endif
  21
  22 # include "drawmod.h"
  23
  24 typedef int font; /* abstract font handle */
  25
  26
  27 /* ---------------------------- font_cacheaddress --------------------------
  28  * Description:   Informs caller of font cache used and font cache size.
  29  *
  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.
  35  *
  36  */
  37
  38 extern os_error * font_cacheaddress(int *version, int *cacheused, int *cachesize);
  39
  40
  41 /* ------------------------------- font_find -------------------------------
  42  * Description:   Gives caller a handle to font, given its name.
  43  *
  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.
  49  * Other Info:    none.
  50  *
  51  */
  52
  53 extern os_error * font_find(
  54   char* name,
  55   int xsize, int ysize,    /* in 16ths of a point */
  56   int xres, int yres,      /* dots per inch of resolution: 0->use default */
  57   font*);                  /* result */
  58
  59
  60 /* ------------------------------- font_lose -------------------------------
  61  * Description:   Informs font manager that a font is no longer needed
  62  *
  63  * Parameters:    font f -- the font
  64  * Returns:       possible error condition.
  65  * Other Info:    none.
  66  *
  67  */
  68
  69 extern os_error * font_lose(font f);
  70
  71 typedef struct font_def {
  72     char name[16];
  73     int xsize, ysize, xres, yres; /* as above */
  74     int usage, age;
  75 } font_def;
  76
  77
  78 /* ------------------------------ font_readdef -----------------------------
  79  * Description:   Get details about a font, given its handle.
  80  *
  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:
  87  *                          name -- font name
  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.
  95  *
  96  */
  97
  98 extern os_error * font_readdef(font, font_def*);
  99
 100 typedef struct font_info {
 101     int minx, miny, maxx, maxy;
 102 } font_info;
 103
 104
 105 /* ------------------------------- font_readinfo ---------------------------
 106  * Description:   Informs caller of minimal area covering any character in
 107  *                the font bounding box.
 108  *
 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
 113  *                type 'font_info').
 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).
 119  *
 120  */
 121
 122 extern os_error * font_readinfo(font, font_info*);
 123
 124
 125 typedef struct font_string {
 126
 127     char* s;
 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 */
 133
 134     } font_string;
 135
 136
 137 /* -------------------------------- font_strwidth --------------------------
 138  * Description:   Determine 'width' of string.
 139  *
 140  * Parameters:    font_string *fs -- the string, with fields:
 141  *                              s -- string itself
 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:
 148  *                              s -- unchanged
 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.
 154  *
 155  */
 156
 157 extern os_error * font_strwidth(font_string *fs);
 158
 159
 160 /* paint options */
 161 #define font_JUSTIFY 0x01   /* justify text */
 162 #define font_RUBOUT  0x02   /* rub-out box required */
 163 #define font_ABS     0x04   /* absolute co-ordinates */
 164         /* 8 not used */
 165 #define font_OSCOORDS 0x10  /* os coords supplied (otherwise 1/72000 inch) */
 166
 167
 168 /* ------------------------------- font_paint -----------------------------
 169  * Description:   Paint the given string at coords x,y.
 170  *
 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.
 175  * Other Info:    none.
 176  *
 177  */
 178
 179 extern os_error * font_paint(char*, int options, int x, int y);
 180
 181
 182 /* ------------------------------- font_caret -----------------------------
 183  * Description:   Set colour, size and position of the caret.
 184  *
 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.
 190  * Other Info:    none.
 191  *
 192  */
 193
 194 extern os_error *font_caret(int colour, int height, int flags, int x, int y);
 195
 196
 197 /* ---------------------------- font_converttoos ---------------------------
 198  * Description:   Converts coords in 1/72000 inch to OS units.
 199  *
 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.
 203  * Other Info:    none.
 204  *
 205  */
 206
 207 extern os_error *font_converttoos(int x_inch, int y_inch, int *x_os, int *y_os);
 208
 209
 210 /* --------------------------- font_converttopoints ------------------------
 211  * Description:   Converts OS units to 1/72000 inch.
 212  *
 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.
 216  * Other Info:    none.
 217  *
 218  */
 219
 220 extern os_error *font_converttopoints(int x_os, int y_os, int *x_inch, int *y_inch);
 221
 222
 223 /* ------------------------------- font_setfont ----------------------------
 224  * Description:   Sets up font used for subsequent painting or size-requests.
 225  *
 226  * Parameters:    font -- the font handle
 227  * Returns:       possible error condition.
 228  * Other Info:    none.
 229  *
 230  */
 231
 232 extern os_error * font_setfont(font);
 233
 234
 235 typedef struct font_state {
 236
 237        font f;
 238        int back_colour;
 239        int fore_colour;
 240        int offset;
 241
 242        } font_state;
 243
 244
 245 /* --------------------------------- font_current --------------------------
 246  * Description:   Informs caller of current font state.
 247  *
 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.
 255  *
 256  */
 257
 258 extern os_error *font_current(font_state *f);
 259
 260
 261 /* -------------------------------- font_future ----------------------------
 262  * Description:   Informs caller of font characteristics after a future
 263  *                font_paint.
 264  *
 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.
 272  *
 273  */
 274
 275 extern os_error *font_future(font_state *f);
 276
 277
 278 /* ------------------------------- font_findcaret --------------------------
 279  * Description:   Informs caller of nearest point in a string to the caret
 280  *                position.
 281  *
 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.
 287  *
 288  */
 289
 290 extern os_error *font_findcaret(font_string *fs);
 291
 292
 293 /* ----------------------------- font_charbbox -----------------------------
 294  * Description:   Informs caller of bounding box of char in given font.
 295  *
 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.
 303  *
 304  */
 305
 306 extern os_error * font_charbbox(font, char, int options, font_info*);
 307
 308
 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
 312  *
 313  * Parameters:    int *x, *y -- returned scale factors
 314  * Returns:       possible error condition.
 315  * Other Info:    none.
 316  *
 317  */
 318
 319 extern os_error *font_readscalefactor(int *x, int *y);
 320
 321
 322 /* ---------------------------- font_setscalefactor -----------------------
 323  * Description:   Sets the scale factors used by font manager.
 324  *
 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.
 329  *
 330  */
 331
 332 extern os_error *font_setscalefactor(int x, int y);
 333
 334
 335 /* ------------------------------- font_list -------------------------------
 336  * Description:   Gives name of an available font.
 337  *
 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.
 343  *
 344  */
 345
 346 extern os_error * font_list(char*, int*);
 347
 348
 349 /* ------------------------------ font_setcolour ---------------------------
 350  * Description:   Sets the current font(optionally), changes foreground
 351  *                and background colours, and offset for that font.
 352  *
 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.
 357  * Other Info:    none.
 358  *
 359  */
 360
 361 extern os_error * font_setcolour(font, int background, int foreground, int offset);
 362
 363
 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.   */
 367
 368
 369 /* --------------------------- font_setpalette -----------------------------
 370  * Description:   Sets the anti-alias palette
 371  *
 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).
 380  *
 381  */
 382
 383 extern os_error *font_setpalette(int background, int foreground, int offset,
 384                           int physical_back, int physical_fore);
 385
 386 typedef struct font_threshold {
 387
 388      char offset;
 389      char thresholds[15];
 390
 391      } font_threshold;
 392
 393
 394 /* ------------------------- font_readthresholds ---------------------------
 395  * Description:   Reads the list of threshold values that the font manager
 396  *                uses when painting characters.
 397  *
 398  * Parameters:    font_theshold *th -- pointer to result buffer
 399  * Returns:       possible error condition.
 400  * Other Info:    none.
 401  *
 402  */
 403
 404 extern os_error *font_readthresholds(font_threshold *th);
 405
 406
 407 /* ------------------------- font_setthresholds ----------------------------
 408  * Description:   Sets up threshold values for painting colours.
 409  *
 410  * Parameters:    font_threshold *th -- pointer to a threshold table
 411  * Returns:       possible error condition.
 412  * Other Info:    none.
 413  *
 414  */
 415
 416 extern os_error *font_setthresholds(font_threshold *th);
 417
 418
 419 /* ------------------------- font_findcaretj -------------------------------
 420  * Description:   Finds nearest point where the caret can go (using
 421  *                justification offsets).
 422  *
 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.
 427  *
 428  */
 429
 430 extern os_error *font_findcaretj(font_string *fs, int offset_x, int offset_y);
 431
 432
 433 /* ------------------------ font_stringbbox --------------------------------
 434  * Description:   Measures the size of a string (without printing it).
 435  *
 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.
 442  *
 443  */
 444
 445 extern os_error *font_stringbbox(char *s, font_info *fi);
 446
 447 /* new SWIS */
 448
 449 /*---------------------------------------------------------------------------*/
 450 /*Routines to create a draw module path object from calls to font_paint*/
 451
 452 typedef enum {font_CONVERT, font_IGNORE, font_ERROR} font_action_on_bitmap;
 453
 454 extern os_error
 455    *font_output_to_null
 456    (  BOOL add_hints,
 457       BOOL output_skeleton,
 458       font_action_on_bitmap action_on_bitmap
 459    );
 460
 461 extern os_error *font_output_size (size_t *size);
 462
 463 extern os_error
 464    *font_output_to_buffer
 465    (  drawmod_buffer *buff_ptr,
 466       BOOL add_hints,
 467       BOOL output_skeleton,
 468       font_action_on_bitmap action_on_bitmap
 469    );
 470
 471 extern os_error *font_output_to_screen (void);
 472
 473 # endif
 474
 475 /* end font.h */