font

/* 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 */