Source

pygame / doc / src / freetypebase.xml

Full commit
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.freetype.base">
  <alias>pygame2.freetype</alias>
  <short>Wrapping module for the FreeType 2 font library</short>
  <desc>
    This module wraps the FreeType 2 font library to add improvent font
    drawing capabilities to PyGame2, such as new font formats, etc.
  </desc>
  <func name="get_error">
    <call>get_version () -> (int, int, int)</call>
    <desc>
        Returns the description of the last error which occurred in the
        FreeType library, or None if no error have occurred.
    </desc>
  </func>

  <func name="get_version">
    <call>get_version () -> (int, int, int)</call>
    <desc>
        Gets the version of the FreeType2 library which was used to build
        the 'freetype' module.
    </desc>
  </func>
  <func name="init">
    <call>init () -> None</call>
    <desc>
      Initializes the underlying FreeType 2 library.
      
      This method must be called before trying to use any of the functionality
      of the 'freetype' module.
    </desc>
  </func>
  <func name="quit">
    <call>quit () -> None</call>
    <desc>
      Shuts down the underlying FreeType 2 library.

      After calling this function, you should not invoke any class,
      method or function related to the 'freetype' module as they are likely to
      fail or might give unpredictable results.
    </desc>
  </func>
  <func name="was_init">
    <call>was_init () -> bool</call>
    <desc>
      Returns whether the the FreeType 2 library is initialized.
    </desc>
  </func>


  <class name="Font">
    <constructor>Font (file [, ptsize, index]) -> Font</constructor>
    <desc>
        Creates a new Font from a supported font file.

        *file* can be either a string representing the font's filename or
        a file-like object containing the font.

        Optionally, a *ptsize* argument may be specified to set the
        default size in points which will be used to render the font. 
        Such size can also be specified manually on each method call.
        Because of the way the caching system works, specifying a
        default size on the constructor doesn't imply a performance
        gain over manually passing the size on each function call.

        If the font file has more than one face, the *index* argument
        may be specified to specify which face index to load. Defaults
        to 0; font loading will fail if the given index is not contained
        in the font.
    </desc>
    <attr name="name">
      <desc>Gets the name of the font face.</desc>
    </attr>
    <method name="get_size">
      <call>get_size(text [, ptsize]) -> int, int</call>
      <desc>
          Gets the size in pixels which 'text' will occupy when rendered using 
          this Font.

          Returns a tuple containing the width and height of the text's
          bounding box. 
          
          The calculations are done using the font's default size in points.
          Optionally you may specify another point size to use.
      </desc>
    </method>
    <method name="get_metrics">
      <call>get_metrics(text, [bbmode, ptsize]) -> [(...), ...]</call>
      <desc>
        Returns the glyph metrics for each character in 'text'.

        The glyph metrics are returned inside a list; each character will
        be represented as a tuple inside the list with the following values:

          (min_x, max_x, min_y, max_y, horizontal_advance)

        By default, these values are returned as grid-fitted pixel
        coordinates (ints). Optionally, one of the following constants
        (which can be found on the FreeType constants module) may be passed
        as the bbmode argument:

            BBOX_EXACT: Return accurate floating point values.

            BBOX_EXACT_GRIDFIT: Return accurate floating point values aligned
            to the drawing grid.

            BBOX_PIXEL: Return pixel coordinates (ints).

            BBOX_PIXEL_GRIDFIT (default): Return grid-aligned pixel coordinates.
        
        The calculations are done using the font's default size in points.
        Optionally you may specify another point size to use.

      </desc>
    </method>
    <attr name="height">
      <desc>Gets the height of the Font.</desc>
    </attr>
    <method name="render">
      <call>render(text, fgcolor[, bgcolor, dstsurface, xpos, ypos, ptsize]) -> (int, int, :class:`pygame2.sdl.video.Surface`)</call>
      <desc>
        Renders a text on a SDL surface.

        Renders the string *text* to a
        :class:`pygame2.sdl.video.Surface`, using the color *fgcolor*.

        If a destination surface *dstsurface*' exists and is a
        :class:`pygame2.sdl.video.Surface` (independently of its bit
        depth), the text will be rendered directly on top of it at the
        passed coordinates (*xpos*, *ypos*). The width and height of
        the rendered text as well as the surface will be returned in a
        tuple.

        If there is no destination surface, a new
        :class:`pygame2.sdl.video.Surface` will be created with the
        required size to contain the drawn text, using *bgcolor* as its
        background color. The width and height of the rendered text,
        together with the new :class:`pygame2.sdl.video.Surface`, will
        be returned in a tuple.

        The rendering is done using the font's default size in points.
        Optionally you may specify another point size to use.

        This function is only available when PyGame 2 has been compiled
        with SDL support.
      </desc>
    </method>
    <method name="render_raw">
      <call>render_raw(text [, ptsize]) -> (int, int, bytes)</call>
      <desc>
        Renders a text to a byte buffer.

        Renders the string *text* to a raw buffer of bytes, each byte
        representing the opacity of the glyph's raster image in
        grayscale.
        
        The width (pitch) and height of the rendered text, together with
        the bytes buffer, will be returned in a tuple.

        The rendering is done using the font's default size in points.
        Optionally you may specify another point size to use.
      </desc>
    </method>
    <attr name="style">
      <desc>Gets or sets the style of the Font.
      
      .. todo::
      
        TODO
      </desc>
    </attr>
    <attr name="fixed_width">
      <desc>
        Returns whether this Font is a fixed-width (bitmap) font.
        
        .. note::
        
          Note that scalable fonts whose glyphs are all the same width 
          (i.e. monospace TTF fonts used for programming) are not considered
          fixed width.
      </desc>
    </attr>
  </class>
  
</module>