home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Font.pm < prev    next >
Text File  |  1999-04-17  |  4KB  |  102 lines
  1. NAME
  2.     RISCOS::Font -- perl interface to fonts and the font manager
  3.  
  4. SYNOPSIS
  5.          use RISCOS::Font;
  6.          $font = RISCOS::Font->new('Homerton.Medium',12);
  7.          @bbox = $font->StringBBox('Hello World');
  8.  
  9.  
  10. DESCRIPTION
  11.     `RISCOS::Font' provides an interface to the Font manager
  12.     allowing programs to use outline fonts. Currently only functions
  13.     to calculate the dimensions of strings and characters are
  14.     implemented, principally for the DrawFile Text object and the
  15.     TextArea parser. `RISCOS::Font' automatically keeps track of the
  16.     fonts in use, freeing a font handle with `XFont_LoseFont' when
  17.     the last reference goes out of scope. Functionality is provided
  18.     both as methods on `RISCOS::Font' objects and as functions that
  19.     take a text description of the font to use. This description is
  20.     passed as a reference to an array of parameters for `new'.
  21.  
  22.   Subroutines/Methods
  23.  
  24.     new <name> <xpoints> <ypoints> <xdpi> <ydpi>
  25.         `new' returns a `RISCOS::Font' object referring to the
  26.         specifed font, creating a new object if necessary. As
  27.         object's destructor calls `XFont_LoseFont' when the last
  28.         reference to it is destroyed, `RISCOS::Font' keeps track of
  29.         font handles without programmer intervention. One out of
  30.         *xpoints* and *ypoints* must be specified, and if only one
  31.         is specified both default to this value. If *xdpi* or *ydpi*
  32.         are undefined then 0 is passed to `XFont_FindFont' to use
  33.         the default dpi.
  34.  
  35.     Clone
  36.         `Clone' returns a copy of the `RISCOS::Font' object.
  37.  
  38.     PointX
  39.  
  40.     PointX
  41.         `PointX' and `PointY' return the X and Y point sizes
  42.         respectively.
  43.  
  44.     Name
  45.         In scalar context `Name' returns the font's name. In array
  46.         context returns `(*Name*, *PointX*, *PointY*)'.
  47.  
  48.     CharBBox <character>
  49.  
  50.     font_char_bbox <font> <character>
  51.         returns the bounding box of the specified character in
  52.         millipoints.
  53.  
  54.     StringBBox <text> [<flags> [<transform>]]
  55.  
  56.     font_string_bbox <font> <text> [<flags> [<transform>]]
  57.         returns the bounding box (in millipoints) of the specified
  58.         text(which may contain font control sequences). In array
  59.         context returns the bounding box, in scalar context a
  60.         reference to the bounding box array. This function is
  61.         similar to `XFont_StringBBox' except that it will return
  62.         `(0,0,0,0') for an empty string and that it will add the
  63.         width of any trailing space. *transform* if defined should
  64.         point to a transformation matrix, and *flags* are:
  65.  
  66.                     bit 0    perform kerning
  67.                     bit 1    wrting direction is right to left
  68.  
  69.  
  70.     Split <text> <split> <flags> <x> <y> <transform>
  71.  
  72.     font_split_string <font> <text> <split> <flags> <x> <y> <transform>
  73.         returns the longest substring that fits within the specified
  74.         coordinates, splitting the text at the specified character
  75.         (or any if `undef' is specified). In scalar context returns
  76.         the split string, in list context returns `(*text*, *x*,
  77.         *y*, `\@bbox')' where *x*, *y* gives the position of the
  78.         split, and *bbox* is a reference to an array containing the
  79.         bounding box of the split string (the string starts at 0,0).
  80.         *flags* and *transform* are as for `StringBBox'.
  81.  
  82.  
  83. BUGS
  84.     `StringBBox' doesn't match the behaviour of `XFont_ScanString',
  85.     because `XFont_ScanString' is illogical when it comes to spaces.
  86.     The "raw" bounding box of `"a "' is eqivalent to `"a"', while
  87.     the "raw" bounding box of `"a "' is equivalent to the total
  88.     width of `"a "' (*i.e.* the position where the next character
  89.     would start). This is presumably because spaces are stated as
  90.     having a bounding box of (0, 0, 0, 0) and the SWI naïvely
  91.     positions each space at the correct place along the string and
  92.     merges the bounding box. Hence strings like `"_ "' have a
  93.     "bounding box" that neither gives the region of printed ink, nor
  94.     the total width of the string. This is a bug on Acorn's part,
  95.     because the bounding box is defined as (inclusive, inclusive,
  96.     exclusive, exclusive), hence (0, 0, 0, 0) should be recognised
  97.     as illegal (and hence special case).
  98.  
  99. AUTHOR
  100.     Nicholas Clark <nick@unfortu.net>
  101.  
  102.