Rewrite and re-document the BitmapFont class (#208)

* Rewrite and redocument the BitmapFont class

* Document exception types for BitmapFont rendering

Author: a-hurst

doc/modules/ext/bitmapfont.rst

@@ -1,66 +1,8 @@
-Basic Bitmap Font Rendering
-===========================
+`sdl2.ext.bitmapfont` - Basic Bitmap Font Rendering
+===================================================
 
 This module provides the :class:`~sdl2.ext.BitmapFont` class, which allows for
 basic font rendering in PySDL2 without depending on the SDL_ttf library.
 
-
-.. class:: BitmapFont(surface : Sprite, size : iterable[, mapping=None)
-
-   A bitmap graphics to character mapping. The :class:`BitmapFont` class
-   uses an image *surface* to find and render font character glyphs for
-   text. It requires a mapping table, which denotes the characters
-   available on the image.
-
-   The mapping table is a list of strings, where each string reflects a
-   *line* of characters on the image. Each character within each line
-   has the same size as specified by the size argument.
-
-   A typical mapping table might look like ::
-
-      [ '0123456789',
-        'ABCDEFGHIJ',
-        'KLMNOPQRST',
-        'UVWXYZ    ',
-        'abcdefghij',
-        'klmnopqrst',
-        'uvwxyz    ',
-        ',;.:!?+-()' ]
-
-   .. attribute:: surface
-
-      The :class:`sdl2.SDL_Surface` containing the character bitmaps.
-
-   .. attribute:: offsets
-
-      A dict containing the character offsets on the :attr:`surface`.
-
-   .. attribute:: mapping
-
-      The character mapping table, a list of strings.
-
-   .. attribute:: size
-
-      The size of an individual glyph bitmap on the font.
-
-   .. method:: render(text : string[, bpp=None]) -> Sprite
-
-      Renders the passed text on a new :class:`Sprite` and returns it.
-      If no explicit *bpp* are provided, the bpp settings of the
-      :attr:`.surface` are used.
-
-   .. method:: render_on(surface : Sprite, text : string[, \
-                         offset=(0, 0)]) -> (int, int, int, int)
-
-      Renders a text on the passed sprite, starting at a specific
-      offset. The top-left start position of the text will be the
-      passed *offset* and a 4-value tuple with the changed area will be
-      returned.
-
-   .. method:: contains(c : string) -> bool
-
-      Checks, whether a certain character exists in the font.
-
-   .. method:: can_render(text : string) -> bool
-
-      Checks, whether all characters in the passed *text* can be rendered.
+.. automodule:: sdl2.ext.bitmapfont
+	:members:

doc/news.rst

@@ -57,6 +57,11 @@ New Features:
   when using SDL2 2.0.10 or newer (PR #207)
 * Added :meth:`sdl2.ext.Renderer.blit` as an alias for the 
   :meth:`sdl2.ext.Renderer.copy` method (PR #207)
+* Added a new method :meth:`~sdl2.ext.BitmapFont.remap` to the
+  :obj:`~sdl2.ext.BitmapFont` class to allow specifying custom character
+  widths and heights for each mapped character in a bitmap font (PR #208)
+* Added a new argument ``line_h`` to :meth:`sdl2.ext.BitmapFont.render_on` to
+  allow specifying custom line heights (PR #208)
 
 Fixed Bugs:
 
@@ -73,6 +78,14 @@ Fixed Bugs:
   try to unlock RLE surfaces once their corresponding view objects are deleted.
   This prevents a segmentation fault when a view is garbage-collected but the
   surface has already been freed (PR #204)
+* Fixed a bug where the rectangle returned by
+  :meth:`sdl2.ext.BitmapFont.render_on` would overestimate the size of the
+  rendered text by one character in both width and height (PR #208)
+* :meth:`sdl2.ext.BitmapFont.contains` no longer assumes that the font map
+  contains a space (PR #208)
+* Rendering multiline text with the :class:`sdl2.ext.BitmapFont` class now
+  always splits lines using the newline (`\n`) character. Previously on
+  Windows, it would only split on Windows-style line endings (`\r\n`) (PR #208)
 
 API Changes:
 
@@ -113,6 +126,11 @@ Deprecation Notices:
   instead (PR #205)
 * The :func:`sdl2.ext.get_image_formats` function has been deprecated, as it
   gives inaccurate results in most cases (PR #205)
+* The :meth:`sdl2.ext.BitmapFont.can_render` method has been deprecated (PR #208)
+* The :meth:`sdl2.ext.BitmapFont.render` method has been deprecated in favor of
+  :meth:`sdl2.ext.BitmapFont.render_text`, which returns an SDL surface instead
+  of a SoftwareSprite and ensures the output surface is in ARGB8888 format by
+  default (PR #208)
 
 
 0.9.9