1. Lenard Lindstrom
  2. pygame-patches

Commits

Lenard Lindstrom  committed d42f6cf

freetype

  • Participants
  • Parent commits 81786e8
  • Branches default

Comments (0)

Files changed (2)

File freetype

-# HG changeset patch
-# Parent 3299e2cc3c4c18e182eb8259b2b7620c1e4e6f5a
-Finish freetype module doc page
-
-diff -r 3299e2cc3c4c docs/reST/ref/examples.rst
---- a/docs/reST/ref/examples.rst	Tue Nov 05 13:29:18 2013 -0800
-+++ b/docs/reST/ref/examples.rst	Thu Nov 07 21:44:06 2013 -0800
-@@ -129,6 +129,19 @@
- 
-    .. ## pygame.examples.fonty.main ##
- 
-+.. function:: freetype_misc.main
-+
-+   | :sl:`run a freetype rendering example`
-+   | :sg:`freetype_misc.main() -> None`
-+
-+   A showcase of rendering features the :class:`pygame.freetype.Font`
-+   class provides in addition to those available with :class:`pygame.font.Font`.
-+   It is a demonstration of direct to surface rendering, with vertical text
-+   and rotated text, opaque text and semi transparent text, horizontally
-+   stretched text and vertically stretched text.
-+
-+   .. ## pygame.examples.fonty.main ##
-+
- .. function:: vgrade.main
- 
-    | :sl:`display a vertical gradient`
-diff -r 3299e2cc3c4c docs/reST/ref/freetype.rst
---- a/docs/reST/ref/freetype.rst	Tue Nov 05 13:29:18 2013 -0800
-+++ b/docs/reST/ref/freetype.rst	Thu Nov 07 21:44:06 2013 -0800
-@@ -8,35 +8,61 @@
- 
- | :sl:`Enhanced Pygame module for loading and rendering computer fonts`
- 
--The :mod:`pygame.freetype` module allows for the rendering of all font file formats
--supported by FreeType, namely ``TTF``, Type1, ``CFF``, OpenType, ``SFNT``, ``PCF``,
--``FNT``, ``BDF``, ``PFR`` and Type42 fonts. It can render any UTF-32 character in a
--font file.
-+The :mod:`pygame.freetype` module is a replacement for :mod:`pygame.font`.
-+It has all of the functionality of the original, plus many new features.
-+Yet is has absolutely no dependencies on the SDL_ttf library.
-+It is implemented directly on the FreeType 2 library.
-+The :mod:`pygame.freetype` module is not itself backward compatible with
-+:mod:`pygame.font`.
-+Instead, use the :mod:`pygame.ftfont` module as a drop-in replacement
-+for :mod:`pygame.font`.
- 
--This module is a replacement for :mod:`pygame.font`. It has all of the functionality
--of the original, plus many new features. Yet is has absolutely no dependencies
--on the SDL_ttf library. The :mod:`pygame.freetype` module is not itself backward
--compatible with :mod:`pygame.font`. Instead, a new :mod:`pygame.ftfont` provides
--a drop-in replacement for :mod:`pygame.font`.
-+All font file formats supported by FreeType can be rendered by
-+:mod:`pygame.freetype`, namely ``TTF``, Type1, ``CFF``, OpenType,
-+``SFNT``, ``PCF``, ``FNT``, ``BDF``, ``PFR`` and Type42 fonts.
-+All glyphs having UTF-32 code points are accessible (see :attr:`ucs4`).
- 
--Most of the work done with fonts is done by using the actual Font objects. The
--module by itself only has routines to initialize itself and create Font objects
--with ``pygame.freetype.Font()``.
-+Most work on fonts is done using :class:`Font` instances.
-+The module itself only has routines for initialization and creation
-+of :class:`Font` objects.
-+You can load fonts from the system using the :func:`SysFont` function.
- 
--You can load fonts from the system by using the ``pygame.freetype.SysFont()``
--function. There are a few other functions to help find system fonts.
-+Extra support of bitmap fonts is available. Available bitmap sizes can
-+be listed (see :meth:`Font.get_sizes`). For bitmap only fonts :class:`Font`
-+can set the size for you
-+(see the :ref:`Font class size argument <freetype-font-size-argument>`).
- 
--For now undefined character codes are replaced with the ``undefined character``.
-+For now undefined character codes are replaced with the ``.notdef``
-+(not defined) character.
- How undefined codes are handled may become configurable in a future release.
- 
- Pygame comes with a builtin default font. This can always be accessed by
--passing None as the font name to the Font constructor.
-+passing None as the font name to the :class:`Font` constructor.
- 
--New in Pygame 1.9.2
-+Extra rendering features available to :class:`pygame.freetype.Font`
-+are direct to surface rendering (see :meth:`Font.render_to`), character kerning
-+(see :attr:`Font.kerning`), vertical layout (see :attr:`Font.vertical`),
-+rotation of rendered text (see :attr:`rotation`), and the strong style
-+(see :attr:`Font.strong`). Some properties are configurable, such as
-+strong style strength (see :attr:`Font.strength`) and underline positioning
-+(see :attr:`underline_adjustment`). Text can be positioned by the upper
-+right corner of the text box or by the text baseline (see :attr:`Font.origin`).
-+Finally, a font's vertical and horizontal size can be adjusted separately
-+(see :attr:`Font.size`). The :mod:`pygame.examples.freetype` example
-+(:func:`pygame.examples.freetype_misc.main`) shows these features in use.
-+
-+The Pygame package does not import :mod:`freetype` automatically when
-+loaded. This module must be imported explicitly to be used. ::
-+
-+   import pygame
-+   import pygame.freetype
-+
-+The :mod:`freetype` module is new in Pygame 1.9.2
-+
- 
- .. function:: get_error
- 
--   | :sl:`Return the latest FreeType2 error`
-+   | :sl:`Return the latest FreeType error`
-    | :sg:`get_error() -> str`
- 
-    Return a description of the last error which occurred in the FreeType2
-@@ -44,40 +70,40 @@
- 
- .. function:: get_version
- 
--   | :sl:`Return the FreeType 2 version`
-+   | :sl:`Return the FreeType version`
-    | :sg:`get_version() -> (int, int, int)`
- 
--   Returns the version of the FreeType2 library which was used to build the
--   'freetype' module.
-+   Returns the version of the FreeType library in use by this module.
- 
--   Note that the freetype module depends on the FreeType 2 library. It will
--   not compile with the original FreeType 1.0. Hence, the first element of the
--   tuple will always be "2".
-+   Note that the :mod:`freetype` module depends on the FreeType 2 library.
-+   It will not compile with the original FreeType 1.0. Hence, the first element
-+   of the tuple will always be "2".
- 
- .. function:: init
- 
--   | :sl:`Initialize the underlying FreeType 2 library.`
-+   | :sl:`Initialize the underlying FreeType library.`
-    | :sg:`init(cache_size=64, resolution=72)`
- 
--   This function initializes the underlying FreeType 2 library and must be
--   called before trying to use any of the functionality of the 'freetype'
-+   This function initializes the underlying FreeType library and must be
-+   called before trying to use any of the functionality of the :mod:`freetype`
-    module.
- 
--   However, this function will be automatically called by ``pygame.init()``.
--   It is safe to call this function more than once.
-+   However, :meth:`pygame.init()` will automatically call this function
-+   if the :mod:`freetype` module is already imported. It is safe to call this
-+   function more than once.
- 
--   Optionally, you may specify a default size for the Glyph cache: this is the
-+   Optionally, you may specify a default *cache_size* for the Glyph cache: the
-    maximum number of glyphs that will be cached at any given time by the
-    module. Exceedingly small values will be automatically tuned for
--   performance. Also a default pixel resolution, in dots per inch, can
-+   performance. Also a default pixel *resolution*, in dots per inch, can
-    be given to adjust font scaling.
- 
- .. function:: quit
- 
--   | :sl:`Shut down the underlying FreeType 2 library.`
-+   | :sl:`Shut down the underlying FreeType library.`
-    | :sg:`quit()`
- 
--   This function de-initializes the ``freetype`` module. After calling this
-+   This function closes the ``freetype`` module. 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. It is safe to call this function even if the module hasn't been
-@@ -85,18 +111,18 @@
- 
- .. function:: was_init
- 
--   | :sl:`Return whether the the FreeType 2 library is initialized.`
-+   | :sl:`Return whether the the FreeType library is initialized.`
-    | :sg:`was_init() -> bool`
- 
--   Returns whether the the FreeType 2 library is initialized.
-+   Returns whether the the FreeType library is initialized.
- 
- .. function:: get_default_resolution
- 
-    | :sl:`Return the default pixel size in dots per inch`
-    | :sg:`get_default_resolution() -> long`
- 
--   Returns the default pixel size, in dots per inch for the module. If not changed
--   it will be 72.
-+   Returns the default pixel size, in dots per inch, for the module.
-+   The default is 72dpi.
- 
- .. function:: set_default_resolution
- 
-@@ -104,16 +130,26 @@
-    | :sg:`set_default_resolution([resolution])`
- 
-    Set the default pixel size, in dots per inch, for the module. If the
--   optional argument is omitted or zero the resolution is reset to 72.
-+   optional argument is omitted or zero the resolution is reset to 72dpi.
-+
-+.. function:: SysFont
-+
-+   | :sl:`create a Font object from the system fonts`
-+   | :sg:`SysFont(name, size, bold=False, italic=False) -> Font`
-+
-+   Return a new Font object that is loaded from the system fonts. The font will
-+   match the requested *bold* and *italic* flags. If a suitable system font
-+   is not found the default, Pygame, is returned instead. The font *name*
-+   can be a comma separated list of font names to search for.
- 
- .. function:: get_default_font
- 
-    | :sl:`Get the filename of the default font`
-    | :sg:`get_default_font() -> string`
- 
--   Return the filename of the system font. This is not the full path to the
--   file. This file can usually be found in the same directory as the font
--   module, but it can also be bundled in separate archives.
-+   Return the filename of the default Pygame font. This is not the full path
-+   to the file. The file is usually in the same directory as the font module,
-+   but can also be bundled in a separate archive.
- 
- .. class:: Font
- 
-@@ -121,27 +157,29 @@
-    | :sg:`Font(file, size=0, font_index=0, resolution=0, ucs4=False) -> Font`
- 
-    Argument *file* can be either a string representing the font's filename, a
--   file-like object containing the font, or None; if None, the default, built-in font
--   is used.
-+   file-like object containing the font, or None; if None, the default,
-+   Pygame, font is used.
-+
-+   .. _freetype-font-size-argument:
- 
-    Optionally, a *size* argument may be specified to set the default size in
--   points, which will be used when rendering the font. The size can also be
--   passed explicitly to 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 is bitmap and no *size* is given, the default size is set
--   to the first available size for the font, if possible.
-+   points, which determines the size of the rendered characters.
-+   The size can also be passed explicitly to 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 is bitmap and no *size*
-+   is given, the default size is set to the first available size for the font.
- 
-    If the font file has more than one font, the font to load can be chosen with
-    the *index* argument. An exception is raised for an out-of-range font index
-    value.
- 
--   The optional resolution argument sets the pixel size, in dots per inch,
-+   The optional *resolution* argument sets the pixel size, in dots per inch,
-    for use in scaling glyphs for this Font instance. If 0 then the default
-    module value, set by :meth:`freetype.init`, is used. The Font object's
--   resolution can only be changed by reinitializing the Font instance.
-+   resolution can only be changed by re-initializing the Font instance.
- 
--   The optional ucs4 argument, an integer, sets the default text translation
-+   The optional *ucs4* argument, an integer, sets the default text translation
-    mode: 0 (False) recognize UTF-16 surrogate pairs, any other value (True),
-    to treat Unicode text as UCS-4, with no surrogate pairs. See
-    :attr:`Font.ucs4`.
-@@ -192,20 +230,21 @@
-       | :sl:`Return the size and offset of rendered text`
-       | :sg:`get_rect(text, style=STYLE_DEFAULT, rotation=0, size=0) -> rect`
- 
--      Gets the final dimensions and origin, in pixels, of 'text' using the
--      current point size, style, rotation and orientation. These are either
--      taken from the arguments, if given, else from the default values set
--      for the font object.
-+      Gets the final dimensions and origin, in pixels, of *text* using the
-+      optional *size* in points, *style*, and *rotation*. For other
-+      relevant render properties, and for any optional argument not given,
-+      the default values set for the :class:`Font` instance are used.
- 
--      Returns a rect containing the width and height of the text's bounding
--      box and the position of the text's origin. The origin can be used
--      to align separately rendered pieces of text. It gives the baseline
--      position and bearing at the start of the text.
-+      Returns a :class:`Rect` instance containing the width and height
-+      of the text's bounding box and the position of the text's origin.
-+      The origin is useful in aligning separately rendered pieces of text.
-+      It gives the baseline position and bearing at the start of the text.
-+      See the :meth:`render_to` method for an example.
- 
--      If text is a char (byte) string, then its encoding is assumed to be
-+      If *text* is a char (byte) string, its encoding is assumed to be
-       ``LATIN1``.
- 
--      Optionally, text can be :const:`None`, which will return the bounding
-+      Optionally, *text* can be :const:`None`, which will return the bounding
-       rectangle for the text passed to a previous :meth:`get_rect`,
-       :meth:`render`, :meth:`render_to`, :meth:`render_raw`, or
-       :meth:`render_raw_to` call. See :meth:`render_to` for more
-@@ -216,10 +255,10 @@
-       | :sl:`Return the glyph metrics for the given text`
-       | :sg:`get_metrics(text, size=0) -> [(...), ...]`
- 
--      Returns the glyph metrics for each character in 'text'.
-+      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:
-+      The glyph metrics are returned as a list of tuples. Each tuple gives
-+      metrics of a single character glyph. The glyph metrics are:
- 
-       ::
- 
-@@ -230,7 +269,7 @@
-       float values.
- 
-       The calculations are done using the font's default size in points.
--      Optionally you may specify another point size to use.
-+      Optionally you may specify another point size with the *size* argument.
- 
-       The metrics are adjusted for the current rotation, strong, and oblique
-       settings.
-@@ -284,7 +323,7 @@
-       | :sl:`The scaled height of the font in pixels`
-       | :sg:`get_sized_height(<size>=0) -> int`
- 
--      Read only. Gets the height of the font. This is the average value of all
-+      Returns the height of the font. This is the average value of all
-       glyphs in the font. It is not adjusted for strong or rotation.
- 
-    .. method:: get_sized_glyph_height
-@@ -302,7 +341,7 @@
-       | :sg:`get_sizes() -> [(int, int, int, float, float), ...]`
-       | :sg:`get_sizes() -> []`
- 
--      This returns a list of tuple records, one for each point size
-+      Returns a list of tuple records, one for each point size
-       supported. Each tuple containing the point size, the height in pixels,
-       width in pixels, horizontal ppem (nominal width) in fractional pixels,
-       and vertical ppem (nominal height) in fractional pixels.
-@@ -312,60 +351,51 @@
-       | :sl:`Return rendered text as a surface`
-       | :sg:`render(text, fgcolor=None, bgcolor=None, style=STYLE_DEFAULT, rotation=0, size=0) -> (Surface, Rect)`
- 
--      Returns a new :mod:`pygame.Surface`, with the text rendered to it
-+      Returns a new :mod:`Surface`, with the text rendered to it
-       in the color given by 'fgcolor'. If no foreground color is given,
-       the default foreground color, :attr:`fgcolor` is used.
-       If ``bgcolor`` is given, the surface
--      will be filled with this color. If no background color is given,
--      the surface is filled with zero alpha opacity. Normally the returned
-+      will be filled with this color. When no background color is given,
-+      the surface background is transparent, zero alpha. Normally the returned
-       surface has a 32 bit pixel size. However, if ``bgcolor`` is :const:`None`
--      and anti-aliasing is disabled a two color 8 bit surface with colorkey
--      set for the background color is returned.
-+      and anti-aliasing is disabled a monochrome 8 bit colorkey surface,
-+      with colorkey set for the background color, is returned.
- 
-       The return value is a tuple: the new surface and the bounding
-       rectangle giving the size and origin of the rendered text.
- 
-       If an empty string is passed for text then the returned Rect is zero
--      width and the height of the font. If dest is :const:`None` the returned
--      surface is the same dimensions as the boundary rect.
--      The rect will test False.
-+      width and the height of the font.
- 
--      The rendering is done using the font's default size in points and its
--      default style, without any rotation, and taking into account fonts which
--      are set to be drawn vertically via the :attr:`vertical` attribute.
--      Optionally you may specify another point size to use via the 'size'
--      argument, a text rotation via the 'rotation' argument, or a new text
--      style via the 'style' argument. See the attr :attr:`size`,
--      :attr:`rotation`, and :attr:`style` attributes.
-+      Optional *fgcolor*, *style*, *rotation*, and *size* arguments override
-+      the default values set for the :class:`Font` instance.
- 
--      If text is a char (byte) string, then its encoding is assumed to be
-+      If *text* is a char (byte) string, then its encoding is assumed to be
-       ``LATIN1``.
- 
--      Optionally, text can be None, which will return the bounding
--      rectangle for the text passed to a previous :meth:`get_rect`,
--      :meth:`render`, :meth:`render_to`, :meth:`render_raw`, or
--      :meth:`render_raw_to` call. See :meth:`render_to` for more
--      details.
-+      Optionally, *text* can be :const:`None`, which will render the text
-+      passed to a previous :meth:`get_rect`, :meth:`render`, :meth:`render_to`,
-+      :meth:`render_raw`, or :meth:`render_raw_to` call.
-+      See :meth:`render_to` for details.
- 
-    .. method:: render_to
- 
-       | :sl:`Render text onto an existing surface`
-       | :sg:`render_to(surf, dest, text, fgcolor=None, bgcolor=None, style=STYLE_DEFAULT, rotation=0, size=0) -> Rect`
- 
--      Renders the string 'text' to a :mod:`pygame.Surface` 'surf',
--      using the color 'fgcolor', if given, or the default foreground
--      color, :attr:`fgcolor`, otherwise.
-+      Renders the string *text* to the :mod:`pygame.Surface` *surf*,
-+      at position *dest*, a (x, y) surface coordinate pair.
-+      If either x or y is not an integer it is converted to one if possible.
-+      Any sequence where the first two items are x and y positional elements
-+      is accepted, including a :class:`Rect` instance.  As with :meth:`render`,
-+      optional *fgcolor*, *style*, *rotation*, and *size* argument are
-+      available.
- 
--      Argument 'dest' is an (x, y) surface coordinate pair. If either x
--      or y is not an integer it is converted to one if possible.
--      Any sequence, including :class:`Rect`, for which the first
--      two elements are positions x and y is accepted.
--
--      If a background color is given, the surface is first filled with that
--      color. The text is blitted next. Both the background fill and text
--      rendering involve full alpha blits. That is, the alpha values of
--      both the foreground and background colors, as well as those of the
--      destination surface if it has per-pixel alpha.
-+      If a background color *bgcolor* is given, the text bounding box is
-+      first filled with that color. The text is blitted next.
-+      Both the background fill and text rendering involve full alpha blits.
-+      That is, the alpha values of the foreground, background, and destination
-+      target surface all affect the blit.
- 
-       The return value is a rectangle giving the size and position of the
-       rendered text within the surface.
-@@ -373,7 +403,7 @@
-       If an empty string is passed for text then the returned :class:`Rect`
-       is zero width and the height of the font. The rect will test False.
- 
--      Optionally, text can be set :const:`None`, which will re-render text
-+      Optionally, *text* can be set :const:`None`, which will re-render text
-       passed to a previous :meth:`render_to`, :meth:`get_rect`, :meth:`render`,
-       :meth:`render_raw`, or :meth:`render_raw_to` call. Primarily, this
-       feature is an aid to using :meth:`render_to` in combination with
-@@ -407,11 +437,7 @@
-       with a text string or one of the above properties has changed
-       after the :meth:`get_rect` call.
- 
--      By default, the point size and style set for the font are used
--      if not passed as arguments. The text is unrotated unless a non-zero
--      rotation value is given.
--
--      If text is a char (byte) string, then its encoding is assumed to be
-+      If *text* is a char (byte) string, then its encoding is assumed to be
-       ``LATIN1``.
- 
-    .. method:: render_raw
-@@ -419,8 +445,8 @@
-       | :sl:`Return rendered text as a string of bytes`
-       | :sg:`render_raw(text, style=STYLE_DEFAULT, rotation=0, size=0, invert=False) -> (bytes, (int, int))`
- 
--      Like :meth:`render` but the tuple returned is an 8 bit
--      monochrome string of bytes and its size. The foreground color is 255, the
-+      Like :meth:`render` but with the pixels returned as a byte string
-+      of 8-bit grey-scale values. The foreground color is 255, the
-       background 0, useful as an alpha mask for a foreground pattern.
- 
-    .. method:: render_raw_to
-@@ -429,8 +455,10 @@
-       | :sg:`render_raw_to(array, text, dest=None, style=STYLE_DEFAULT, rotation=0, size=0, invert=False) -> (int, int)`
- 
-       Render to an array object exposing an array struct interface. The array
--      must be two dimensional with integer items. The default dest value, None,
--      is equivalent to (0, 0). See :meth:`render_to`.
-+      must be two dimensional with integer items. The default *dest* value,
-+      :const:`None`, is equivalent to position (0, 0). See :meth:`render_to`.
-+      As with the other render methods, *text* can be :const:`None` to
-+      render a text string passed previously to another method.
- 
-    .. attribute:: style
- 
-@@ -439,8 +467,9 @@
- 
-       Gets or sets the default style of the Font. This default style will be
-       used for all text rendering and size calculations unless overridden
--      specifically in the \`render()` or \`get_size()` calls. The style value
--      may be a bit-wise ``OR`` of one or more of the following constants:
-+      specifically in the :meth:`render` or :meth:`get_size` calls.
-+      The style value may be a bit-wise OR of one or more of the following
-+      constants:
- 
-       ::
- 
-@@ -454,10 +483,10 @@
-       Optionally, the default style can be modified or obtained accessing the
-       individual style attributes (underline, oblique, strong).
- 
--      The ``STYLE_OBLIQUE`` and ``STYLE_STRONG`` styles are for scalable fonts
--      only. An attempt to set either for a bitmap font raises an AttributeError.
--      An attempt to set either for an inactive font, as returned by
--      ``Font.__new__()``, raises a RuntimeError.
-+      The :const:`STYLE_OBLIQUE` and :const:`STYLE_STRONG` styles are for
-+      scalable fonts only. An attempt to set either for a bitmap font raises
-+      an AttributeError. An attempt to set either for an inactive font,
-+      as returned by :meth:`Font.__new__`, raises a RuntimeError.
- 
-    .. attribute:: underline
- 
-@@ -466,8 +495,8 @@
- 
-       Gets or sets whether the font will be underlined when drawing text. This
-       default style value will be used for all text rendering and size
--      calculations unless overridden specifically in the \`render()` or
--      \`get_size()` calls, via the 'style' parameter.
-+      calculations unless overridden specifically in the :meth:`render` or
-+      :meth:`get_size` calls, via the 'style' parameter.
- 
-    .. attribute:: strong
- 
-@@ -476,8 +505,8 @@
- 
-       Gets or sets whether the font will be bold when drawing text. This
-       default style value will be used for all text rendering and size
--      calculations unless overridden specifically in the \`render()` or
--      \`get_size()` calls, via the 'style' parameter.
-+      calculations unless overridden specifically in the :meth:`render` or
-+      :meth:`get_size` calls, via the 'style' parameter.
- 
-    .. attribute:: oblique
- 
-@@ -486,13 +515,13 @@
- 
-       Gets or sets whether the font will be rendered as oblique. This
-       default style value will be used for all text rendering and size
--      calculations unless overridden specifically in the \`render()` or
--      \`get_size()` calls, via the 'style' parameter.
-+      calculations unless overridden specifically in the :meth:`render` or
-+      :meth:`get_size` calls, via the *style* parameter.
- 
-       The oblique style is only supported for scalable (outline) fonts.
--      An attempt to set this property will raise an AttributeError.
--      If the font object is inactive, as returned by Font.__new__,
--      setting this property raises a RuntimeError.
-+      An attempt to set this style on a bitmap font will raise an
-+      AttributeError. If the font object is inactive, as returned by
-+      :meth:`Font.__new__`, setting this property raises a RuntimeError.
- 
-    .. attribute:: wide
- 
-@@ -500,8 +529,9 @@
-       | :sg:`wide -> bool`
- 
-       Gets or sets whether the font will be stretched horizontally
--      when drawing text. It produces a result similar to font.Font's
--      bold. This style is only available for unrotated text.
-+      when drawing text. It produces a result similar to
-+      :class:`pygame.font.Font`'s bold. This style not available for
-+      rotated text.
- 
-    .. attribute:: strength
- 
-@@ -512,13 +542,14 @@
-       strong or wide transformations, as a fraction of the untransformed
-       size. For the wide style only the horizontal dimension is
-       increased. For strong text both the horizontal and vertical
--      dimensions are enlarged. A wide style of strength 1/12 is
--      equivalent to the font.Font bold style. The default is 1/36.
-+      dimensions are enlarged. A wide style of strength 0.08333 ( 1/12 ) is
-+      equivalent to the :class:`pygame.font.Font` bold style.
-+      The default is 0.02778 ( 1/36 ).
- 
-       The strength style is only supported for scalable (outline) fonts.
--      An attempt to set this property will raise an AttributeError.
--      If the font object is inactive, as returned by Font.__new__,
--      setting this property raises a RuntimeError.
-+      An attempt to set this property on a bitmap font will raise an
-+      AttributeError. If the font object is inactive, as returned by
-+      :meth:`Font.__new__`, assignment to this property raises a RuntimeError.
- 
-    .. attribute:: underline_adjustment
- 
-@@ -528,46 +559,46 @@
-       Gets or sets a factor which, when positive, is multiplied with the
-       font's underline offset to adjust the underline position. A negative
-       value turns an underline into a strike-through or overline. It is
--      multiplied with the ascender. Accepted values are between -2.0 and 2.0
-+      multiplied with the ascender. Accepted values range between -2.0 and 2.0
-       inclusive. A value of 0.5 closely matches Tango underlining. A value of
--      1.0 mimics SDL_ttf.
-+      1.0 mimics :class:`pygame.font.Font` underlining.
- 
-    .. attribute:: fixed_width
- 
-       | :sl:`Gets whether the font is fixed-width`
-       | :sg:`fixed_width -> bool`
- 
--      Read only. Return True if the font contains fixed-width characters
--      (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
-+      Read only. Returns :const:`True` if the font contains fixed-width
-+      characters (for example Courier, Bitstream Vera Sans Mono, Andale Mono).
- 
-    .. attribute:: fixed_sizes
- 
--      | :sl:`the number of embedded bitmap sizes the font`
-+      | :sl:`the number of available bitmap sizes for the font`
-       | :sg:`fixed_sizes -> int`
- 
--      Read only. Return the number of point sizes for which the font contains
-+      Read only. Returns the number of point sizes for which the font contains
-       bitmap character images. If zero then the font is not a bitmap font. 
--      A scalable font may contain pre-rendered point sizes.
-+      A scalable font may contain pre-rendered point sizes as strikes.
- 
-    .. attribute:: scalable
- 
-       | :sl:`Gets whether the font is scalable`
-       | :sg:`scalable -> bool`
- 
--      Read only. Return True if the font contains outline glyphs. If so,
--      the point size is not limited to available bitmap sizes.
-+      Read only. Returns :const:`True` if the font contains outline glyphs.
-+      If so, the point size is not limited to available bitmap sizes.
- 
-    .. attribute:: use_bitmap_strikes
- 
--      | :sl:`allow the use of embeddeded bitmaps in an outline font file`
-+      | :sl:`allow the use of embedded bitmaps in an outline font file`
-       | :sg:`use_bitmap_strikes -> bool`
- 
--      Some scalable fonts contain embedded bitmaps for particular point
-+      Some scalable fonts include embedded bitmaps for particular point
-       sizes. This property controls whether or not those bitmap strikes
--      are used. Setting ``False`` disables the loading of any bitmap strike.
--      Setting ``True``, the default value, allows bitmap strikes for an
--      unrotated render when no style other than :attr:`wide` or
--      :attr:`underline` is set. This property has no effect on bitmap fonts.
-+      are used. Set it :const:`False` to disable the loading of any bitmap
-+      strike. Set it :const:`True`, the default, to permit bitmap strikes
-+      for a nonrotated render with no style other than :attr:`wide` or
-+      :attr:`underline`. This property is ignored for bitmap fonts.
- 
-       See also :attr:`fixed_sizes` and :meth:`get_sizes`.
- 
-@@ -576,10 +607,10 @@
-       | :sl:`Font anti-aliasing mode`
-       | :sg:`antialiased -> bool`
- 
--      Gets or sets the font's anti-aliasing mode. This defaults to ``True`` on
--      all fonts, which are rendered with full 8 bit blending.
-+      Gets or sets the font's anti-aliasing mode. This defaults to
-+      :const:`True` on all fonts, which are rendered with full 8 bit blending.
- 
--      Setting this to ``False`` will enable monochrome rendering. This should
-+      Set to :const:`False` to do monochrome rendering. This should
-       provide a small speed gain and reduce cache memory size.
- 
-    .. attribute:: kerning
-@@ -587,28 +618,26 @@
-       | :sl:`Character kerning mode`
-       | :sg:`kerning -> bool`
- 
--      Gets or sets the font's kerning mode. This defaults to False on all
--      fonts, which will be rendered by default without kerning.
-+      Gets or sets the font's kerning mode. This defaults to :const:`False`
-+      on all fonts, which will be rendered without kerning.
- 
--      Setting this to true will change all rendering methods to do kerning
--      between character pairs for surface size calculation and all
--      render operations.
-+      Set to :const:`True` to add kerning between character pairs, if supported
-+      by the font, when positioning glyphs.
- 
-    .. attribute:: vertical
- 
-       | :sl:`Font vertical mode`
-       | :sg:`vertical -> bool`
- 
--      Gets or sets whether the font is a vertical font such as fonts in fonts
--      representing Kanji glyphs or other styles of vertical writing.
-+      Gets or sets whether the characters are laid out vertically rather
-+      than horizontally. May be useful when rendering Kanji or some other
-+      vertical script.
- 
--      Changing this attribute will cause the font to be rendering vertically,
--      and affects all other methods which manage glyphs or text layouts to use
--      vertical metrics accordingly.
-+      Set to :const:`True` to switch to a vertical text layout. The default
-+      is :const:`False`, place horizontally.
- 
--      Note that the FreeType library doesn't automatically detect whether a
--      font contains glyphs which are always supposed to be drawn vertically, so
--      this attribute must be set manually by the user.
-+      Note that the :class:`Font` class does not automatically determine
-+      script orientation. Vertical layout must be selected explicitly.
- 
-       Also note that several font formats (especially bitmap based ones) don't
-       contain the necessary metrics to draw glyphs vertically, so drawing in
-@@ -619,25 +648,26 @@
-       | :sl:`text rotation in degrees counterclockwise`
-       | :sg:`rotation -> int`
- 
--      Get or set the baseline angle of the rendered text. The angle is
-+      Gets or sets the baseline angle of the rendered text. The angle is
-       represented as integer degrees. The default angle is 0, with horizontal
--      text rendered along the X axis, and vertical text along the Y axis.
--      A non-zero value rotates these axes counterclockwise that many degrees.
--      Degree values outside of the range 0 to 359 inclusive are reduced to the
--      corresponding angle within the range (eg. 390 -> 390 - 360 -> 30,
--      -45 -> 360 + -45 -> 315, 720 -> 720 - (2 * 360) -> 0).
-+      text rendered along the X-axis, and vertical text along the Y-axis.
-+      A positive value rotates these axes counterclockwise that many degrees.
-+      A negative angle corresponds to a clockwise rotation. The rotation
-+      value is normalized to a value within the range 0 to 359 inclusive
-+      (eg. 390 -> 390 - 360 -> 30, -45 -> 360 + -45 -> 315,
-+      720 -> 720 - (2 * 360) -> 0).
- 
--      Text rotation is only supported for scalable (outline) fonts. An attempt
--      to change the rotation of a bitmap font raises an AttributeError.
--      An attempt to change the rotation of an inactive font objects, as
--      returned by Font.__new__(), raises a RuntimeError.
-+      Only scalable (outline) fonts can be rotated. An attempt to change
-+      the rotation of a bitmap font raises an AttributeError.
-+      An attempt to change the rotation of an inactive font instance, as
-+      returned by :meth:`Font.__new__`, raises a RuntimeError.
- 
-    .. attribute:: fgcolor
- 
-       | :sl:`default foreground color`
-       | :sg:`fgcolor -> Color`
- 
--      Get or set the default glyph rendering color. It is initially opaque
-+      Gets or sets the default glyph rendering color. It is initially opaque
-       black ― (0, 0, 0, 255). Applies to :meth:`render` and :meth:`render_to`.
- 
-    .. attribute:: origin
-@@ -645,18 +675,19 @@
-       | :sl:`Font render to text origin mode`
-       | :sg:`origin -> bool`
- 
--      If set True, then when rendering to an existing surface, the position
--      is taken to be that of the text origin. Otherwise the render position is
--      the top-left corner of the text bounding box.
-+      If set :const:`True`, :meth:`render_to` and :meth:`render_to_raw` will
-+      take the *dest* position to be that of the text origin, as opposed to
-+      the top-left corner of the bounding box. See :meth:`get_rect` for
-+      details.
- 
-    .. attribute:: pad
- 
-       | :sl:`padded boundary mode`
-       | :sg:`pad -> bool`
- 
--      If set True, then the text boundary rectangle will be inflated to match
--      that of font.Font. Otherwise, the boundary rectangle is just large
--      enough for the text.
-+      If set :const:`True`, then the text boundary rectangle will be inflated
-+      to match that of :class:`font.Font`. Otherwise, the boundary rectangle
-+      is just large enough for the text.
- 
-    .. attribute:: ucs4
- 
-@@ -670,13 +701,15 @@
-       interpreters built with a UCS-2 unicode type (on Windows, for instance).
-       It also means character values within the UTF-16 surrogate area (0xD800
-       to 0xDFFF) are considered part of a surrogate pair. A malformed surrogate
--      pair will raise an UnicodeEncodeError. Setting ucs4 True turns surrogate
--      pair decoding off, letting interpreters with a UCS-4 unicode type access
--      the full UCS-4 character range.
-+      pair will raise a UnicodeEncodeError. Setting ucs4 :const:`True` turns
-+      surrogate pair decoding off, allowing access the full UCS-4 character
-+      range to a Python interpreter built with four byte unicode character
-+      support.
- 
-    .. attribute:: resolution
- 
-       | :sl:`Pixel resolution in dots per inch`
-       | :sg:`resolution -> int`
- 
--      Gets the pixel size used in scaling font glyphs for this Font instance.
-+      Read only. Gets pixel size used in scaling font glyphs for this
-+      :class:`Font` instance.
-diff -r 3299e2cc3c4c src/doc/examples_doc.h
---- a/src/doc/examples_doc.h	Tue Nov 05 13:29:18 2013 -0800
-+++ b/src/doc/examples_doc.h	Thu Nov 07 21:44:06 2013 -0800
-@@ -13,6 +13,8 @@
- 
- #define DOC_PYGAMEEXAMPLESFONTYMAIN "fonty.main() -> None\nrun a font rendering example"
- 
-+#define DOC_PYGAMEEXAMPLESFREETYPEMISCMAIN "freetype_misc.main() -> None\nrun a freetype rendering example"
-+
- #define DOC_PYGAMEEXAMPLESVGRADEMAIN "vgrade.main() -> None\ndisplay a vertical gradient"
- 
- #define DOC_PYGAMEEXAMPLESEVENTLISTMAIN "eventlist.main() -> None\ndisplay pygame events"
-@@ -90,6 +92,10 @@
-  fonty.main() -> None
- run a font rendering example
- 
-+pygame.examples.freetype_misc.main
-+ freetype_misc.main() -> None
-+run a freetype rendering example
-+
- pygame.examples.vgrade.main
-  vgrade.main() -> None
- display a vertical gradient
-diff -r 3299e2cc3c4c src/doc/freetype_doc.h
---- a/src/doc/freetype_doc.h	Tue Nov 05 13:29:18 2013 -0800
-+++ b/src/doc/freetype_doc.h	Thu Nov 07 21:44:06 2013 -0800
-@@ -1,20 +1,22 @@
- /* Auto generated file: with makeref.py .  Docs go in src/ *.doc . */
- #define DOC_PYGAMEFREETYPE "Enhanced Pygame module for loading and rendering computer fonts"
- 
--#define DOC_PYGAMEFREETYPEGETERROR "get_error() -> str\nReturn the latest FreeType2 error"
-+#define DOC_PYGAMEFREETYPEGETERROR "get_error() -> str\nReturn the latest FreeType error"
- 
--#define DOC_PYGAMEFREETYPEGETVERSION "get_version() -> (int, int, int)\nReturn the FreeType 2 version"
-+#define DOC_PYGAMEFREETYPEGETVERSION "get_version() -> (int, int, int)\nReturn the FreeType version"
- 
--#define DOC_PYGAMEFREETYPEINIT "init(cache_size=64, resolution=72)\nInitialize the underlying FreeType 2 library."
-+#define DOC_PYGAMEFREETYPEINIT "init(cache_size=64, resolution=72)\nInitialize the underlying FreeType library."
- 
--#define DOC_PYGAMEFREETYPEQUIT "quit()\nShut down the underlying FreeType 2 library."
-+#define DOC_PYGAMEFREETYPEQUIT "quit()\nShut down the underlying FreeType library."
- 
--#define DOC_PYGAMEFREETYPEWASINIT "was_init() -> bool\nReturn whether the the FreeType 2 library is initialized."
-+#define DOC_PYGAMEFREETYPEWASINIT "was_init() -> bool\nReturn whether the the FreeType library is initialized."
- 
- #define DOC_PYGAMEFREETYPEGETDEFAULTRESOLUTION "get_default_resolution() -> long\nReturn the default pixel size in dots per inch"
- 
- #define DOC_PYGAMEFREETYPESETDEFAULTRESOLUTION "set_default_resolution([resolution])\nSet the default pixel size in dots per inch for the module"
- 
-+#define DOC_PYGAMEFREETYPESYSFONT "SysFont(name, size, bold=False, italic=False) -> Font\ncreate a Font object from the system fonts"
-+
- #define DOC_PYGAMEFREETYPEGETDEFAULTFONT "get_default_font() -> string\nGet the filename of the default font"
- 
- #define DOC_PYGAMEFREETYPEFONT "Font(file, size=0, font_index=0, resolution=0, ucs4=False) -> Font\nCreate a new Font instance from a supported font file."
-@@ -69,11 +71,11 @@
- 
- #define DOC_FONTFIXEDWIDTH "fixed_width -> bool\nGets whether the font is fixed-width"
- 
--#define DOC_FONTFIXEDSIZES "fixed_sizes -> int\nthe number of embedded bitmap sizes the font"
-+#define DOC_FONTFIXEDSIZES "fixed_sizes -> int\nthe number of available bitmap sizes for the font"
- 
- #define DOC_FONTSCALABLE "scalable -> bool\nGets whether the font is scalable"
- 
--#define DOC_FONTUSEBITMAPSTRIKES "use_bitmap_strikes -> bool\nallow the use of embeddeded bitmaps in an outline font file"
-+#define DOC_FONTUSEBITMAPSTRIKES "use_bitmap_strikes -> bool\nallow the use of embedded bitmaps in an outline font file"
- 
- #define DOC_FONTANTIALIASED "antialiased -> bool\nFont anti-aliasing mode"
- 
-@@ -104,23 +106,23 @@
- 
- pygame.freetype.get_error
-  get_error() -> str
--Return the latest FreeType2 error
-+Return the latest FreeType error
- 
- pygame.freetype.get_version
-  get_version() -> (int, int, int)
--Return the FreeType 2 version
-+Return the FreeType version
- 
- pygame.freetype.init
-  init(cache_size=64, resolution=72)
--Initialize the underlying FreeType 2 library.
-+Initialize the underlying FreeType library.
- 
- pygame.freetype.quit
-  quit()
--Shut down the underlying FreeType 2 library.
-+Shut down the underlying FreeType library.
- 
- pygame.freetype.was_init
-  was_init() -> bool
--Return whether the the FreeType 2 library is initialized.
-+Return whether the the FreeType library is initialized.
- 
- pygame.freetype.get_default_resolution
-  get_default_resolution() -> long
-@@ -130,6 +132,10 @@
-  set_default_resolution([resolution])
- Set the default pixel size in dots per inch for the module
- 
-+pygame.freetype.SysFont
-+ SysFont(name, size, bold=False, italic=False) -> Font
-+create a Font object from the system fonts
-+
- pygame.freetype.get_default_font
-  get_default_font() -> string
- Get the filename of the default font
-@@ -242,7 +248,7 @@
- 
- pygame.freetype.Font.fixed_sizes
-  fixed_sizes -> int
--the number of embedded bitmap sizes the font
-+the number of available bitmap sizes for the font
- 
- pygame.freetype.Font.scalable
-  scalable -> bool
-@@ -250,7 +256,7 @@
- 
- pygame.freetype.Font.use_bitmap_strikes
-  use_bitmap_strikes -> bool
--allow the use of embeddeded bitmaps in an outline font file
-+allow the use of embedded bitmaps in an outline font file
- 
- pygame.freetype.Font.antialiased
-  antialiased -> bool

File series

View file
-freetype