# dlangui.graphics.fonts

DLANGUI library.
This module contains base fonts access interface and common implementation.
Font - base class for fonts.
FontManager - base class for font managers - provides access to available fonts.
Actual implementation is:
dlangui.graphics.ftfonts - FreeType based font manager.
dlangui.platforms.windows.w32fonts - Win32 API based font manager.
To enable OpenGL support, build with version(USE_OPENGL);
See Also:
dlangui.graphics.drawbuf, DrawBuf, drawbuf, drawbuf.html
Synopsis:

    import dlangui.graphics.fonts;

    // find suitable font of size 25, normal, preferrable Arial, or, if not available, any SansSerif font
    FontRef font = FontManager.instance.getFont(25, FontWeight.Normal, false, FontFamily.SansSerif, "Arial");

    dstring sampleText = "Sample text to draw"d;
    // measure text string width and height (one line)
    Point sz = font.textSize(sampleText);
    // draw red text at center of DrawBuf buf
    font.drawText(buf, buf.width / 2 - sz.x/2, buf.height / 2 - sz.y / 2, sampleText, 0xFF0000);

License:
Boost License 1.0
Authors:
Vadim Lopatin, coolreader.org@gmail.com

enum FontFamily: ubyte;
  font families enum
  Unspecified
    Unknown / not set / does not matter
  SansSerif
    Sans Serif font, e.g. Arial
  Serif
    Serif font, e.g. Times New Roman
  Fantasy
    Fantasy font
  Cursive
    Cursive font
  MonoSpace
    Monospace font (fixed pitch font), e.g. Courier New
enum FontWeight: int;
  font weight constants (0..1000)
  Normal
    normal font weight
  Bold
    bold font
@property void function(uint id) glyphDestroyCallback();
  get glyph destroy callback (to cleanup OpenGL caches)
  Used for resource management. Usually you don't have to call it manually.
@property void glyphDestroyCallback(void function(uint id) callback);
  Set glyph destroy callback (to cleanup OpenGL caches) This callback is used to tell OpenGL glyph cache that glyph is not more used - to let OpenGL glyph cache delete texture if all glyphs in it are no longer used.
  Used for resource management. Usually you don't have to call it manually.
uint nextGlyphId();
  ID generator for glyphs
  Generates next glyph ID. Unique IDs are being used to control OpenGL glyph cache items lifetime.
  Used for resource management. Usually you don't have to call it manually.
immutable int MAX_WIDTH_UNSPECIFIED;
  constant for measureText maxWidth paramenter - to tell that all characters of text string should be measured.
abstract class Font: dlangui.core.types.RefCountedObject;
  Instance of font with specific size, weight, face, etc.
  Allows to measure text string and draw it on DrawBuf
  Use FontManager.instance.getFont() to retrieve font instance.
  abstract @property int size();
    returns font size (as requested from font engine)
  abstract @property int height();
    returns actual font height including interline space
  abstract @property int weight();
    returns font weight
  abstract @property int baseline();
    returns baseline offset
  abstract @property bool italic();
    returns true if font is italic
  abstract @property string face();
    returns font face name
  abstract @property FontFamily family();
    returns font family
  abstract @property bool isNull();
    returns true if font object is not yet initialized / loaded
  @property bool isFixed();
    returns true if font has fixed pitch (all characters have equal width)
  @property int spaceWidth();
    returns true if font is fixed
  int charWidth(dchar ch);
    returns character width
  int measureText(const dchar[] text, ref int[] widths, int maxWidth = MAX_WIDTH_UNSPECIFIED, int tabSize = 4, int tabOffset = 0, uint textFlags = 0);
    Measure text string, return accumulated widths[] (distance to end of n-th character), returns number of measured chars.
    Supports Tab character processing and processing of menu item labels like '&File'.
    Params:

    dchar[] text | text string to measure
    int[] widths | output buffer to put measured widths (widths[i] will be set to cumulative widths text[0..i])
    int maxWidth | maximum width to measure - measure is stopping if max width is reached (pass MAX_WIDTH_UNSPECIFIED to measure all characters)
    int tabSize | tabulation size, in number of spaces
    int tabOffset | when string is drawn not from left position, use to move tab stops left/right
    uint textFlags | TextFlag bit set - to control underline, hotkey label processing, etc...

    Returns:
    number of characters measured (may be less than text.length if maxWidth is reached)
  Point textSize(const dchar[] text, int maxWidth = MAX_WIDTH_UNSPECIFIED, int tabSize = 4, int tabOffset = 0, uint textFlags = 0);
    Measure text string as single line, returns width and height
    Params:

    dchar[] text | text string to measure
    int maxWidth | maximum width - measure is stopping if max width is reached
    int tabSize | tabulation size, in number of spaces
    int tabOffset | when string is drawn not from left position, use to move tab stops left/right
    uint textFlags | TextFlag bit set - to control underline, hotkey label processing, etc...

  void drawText(DrawBuf buf, int x, int y, const dchar[] text, uint color, int tabSize = 4, int tabOffset = 0, uint textFlags = 0);
    Draw text string to buffer.
    Params:

    DrawBuf buf | graphics buffer to draw text to
    int x | x coordinate to draw first character at
    int y | y coordinate to draw first character at
    dchar[] text | text string to draw
    uint color | color for drawing of glyphs
    int tabSize | tabulation size, in number of spaces
    int tabOffset | when string is drawn not from left position, use to move tab stops left/right
    uint textFlags | set of TextFlag bit fields

  abstract Glyph* getCharGlyph(dchar ch, bool withImage = true);
    get character glyph information
  abstract void checkpoint();
    clear usage flags for all entries
  abstract void cleanup();
    removes entries not used after last call of checkpoint() or cleanup()
struct FontList;
  font instance collection - utility class, for font manager implementations
abstract class FontManager;
  Access points to fonts.
  static @property void instance(FontManager manager);
    sets new font manager singleton instance
  static @property FontManager instance();
    returns font manager singleton instance
  abstract ref FontRef getFont(int size, int weight, bool italic, FontFamily family, string face);
    get font instance best matched specified parameters
  abstract void checkpoint();
    clear usage flags for all entries -- for cleanup of unused fonts
  abstract void cleanup();
    removes entries not used after last call of checkpoint() or cleanup()
struct GlyphCache;
  Glyph image cache
  Recently used glyphs are marked with glyph.lastUsage = 1
  checkpoint() call clears usage marks
  cleanup() removes all items not accessed since last checkpoint()
  Glyph* find(dchar ch);
    try to find glyph for character in cache, returns null if not found
  Glyph* put(dchar ch, Glyph* glyph);
    put character glyph to cache
  void cleanup();
    removes entries not used after last call of checkpoint() or cleanup()
  void checkpoint();
    clear usage flags for all entries
  void clear();
    removes all entries (when built with USE_OPENGL version, notify OpenGL cache about removed glyphs)

Page generated by Ddoc. Vadim Lopatin, 2014