Commits

Lenard Lindstrom committed 81ca25b

freetype

Comments (0)

Files changed (2)

+# HG changeset patch
+# Parent 3299e2cc3c4c18e182eb8259b2b7620c1e4e6f5a
+Finish freetype module doc page
+
+diff -r 3299e2cc3c4c -r 247a0a153db2 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	Wed Nov 06 12:59:09 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 -r 247a0a153db2 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	Wed Nov 06 12:59:09 2013 -0800
+@@ -8,35 +8,55 @@
+ 
+ | :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.
++
++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 adjested separately
++(see :attr:`Font.size`). The :mod:`pygame.examples.freetype` example
++(:func:`pygame.examples.freetype_misc.main`) shows these features in use.
+ 
+ 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,7 +64,7 @@
+ 
+ .. 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
+@@ -56,7 +76,7 @@
+ 
+ .. 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
+@@ -74,7 +94,7 @@
+ 
+ .. 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
+@@ -85,7 +105,7 @@
+ 
+ .. 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.
+@@ -106,6 +126,16 @@
+    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.
+ 
++.. 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 this will fallback on loading the default pygame font. The font name
++   can be a comma separated list of font names to look for.
++
+ .. function:: get_default_font
+ 
+    | :sl:`Get the filename of the default font`
+@@ -124,6 +154,8 @@
+    file-like object containing the font, or None; if None, the default, built-in 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
+diff -r 3299e2cc3c4c -r 247a0a153db2 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	Wed Nov 06 12:59:09 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 -r 247a0a153db2 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	Wed Nov 06 12:59:09 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."
+@@ -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