From dfed1424d1b3d1e30f6080d80ab9dcd86a14233c Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sun, 7 Jul 2019 20:52:30 +1000 Subject: [PATCH] Improved ImageFont documentation --- docs/reference/ImageFont.rst | 89 ++---------------------------------- src/PIL/ImageFont.py | 24 ++++++++++ 2 files changed, 29 insertions(+), 84 deletions(-) diff --git a/docs/reference/ImageFont.rst b/docs/reference/ImageFont.rst index e1b7b6261a9..bb7538096b0 100644 --- a/docs/reference/ImageFont.rst +++ b/docs/reference/ImageFont.rst @@ -47,90 +47,11 @@ Functions Methods ------- -.. py:method:: PIL.ImageFont.ImageFont.getsize(text, direction=None, features=[], language=None) - - Returns width and height (in pixels) of given text if rendered in font with - provided direction, features, and language. - - :param text: Text to measure. - - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). - Requires libraqm. - - .. versionadded:: 4.2.0 - - :param features: A list of OpenType font features to be used during text - layout. This is usually used to turn on optional - font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' - to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist - Requires libraqm. - - .. versionadded:: 4.2.0 - - :param language: Language of the text. Different languages may use - different glyph shapes or ligatures. This parameter tells - the font which language the text is in, and to apply the - correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` - Requires libraqm. - - .. versionadded:: 6.0.0 - - :return: (width, height) - -.. py:method:: PIL.ImageFont.ImageFont.getmask(text, mode='', direction=None, features=[], language=None) - - Create a bitmap for the text. - - If the font uses antialiasing, the bitmap should have mode “L” and use a - maximum value of 255. Otherwise, it should have mode “1”. - - :param text: Text to render. - :param mode: Used by some graphics drivers to indicate what mode the - driver prefers; if empty, the renderer may return either - mode. Note that the mode is always a string, to simplify - C-level implementations. - - .. versionadded:: 1.1.5 - - :param direction: Direction of the text. It can be 'rtl' (right to - left), 'ltr' (left to right) or 'ttb' (top to bottom). - Requires libraqm. - - .. versionadded:: 4.2.0 - - :param features: A list of OpenType font features to be used during text - layout. This is usually used to turn on optional - font features that are not enabled by default, - for example 'dlig' or 'ss01', but can be also - used to turn off default font features for - example '-liga' to disable ligatures or '-kern' - to disable kerning. To get all supported - features, see - https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist - Requires libraqm. - - .. versionadded:: 4.2.0 - - :param language: Language of the text. Different languages may use - different glyph shapes or ligatures. This parameter tells - the font which language the text is in, and to apply the - correct substitutions as appropriate, if available. - It should be a `BCP 47 language code - ` - Requires libraqm. - - .. versionadded:: 6.0.0 - - :return: An internal PIL storage memory instance as defined by the - :py:mod:`PIL.Image.core` interface module. +.. autoclass:: PIL.ImageFont.ImageFont + :members: .. autoclass:: PIL.ImageFont.FreeTypeFont :members: + +.. autoclass:: PIL.ImageFont.TransposedFont + :members: diff --git a/src/PIL/ImageFont.py b/src/PIL/ImageFont.py index 9012eafe54a..e2e6af33254 100644 --- a/src/PIL/ImageFont.py +++ b/src/PIL/ImageFont.py @@ -110,9 +110,33 @@ def _load_pilfont_data(self, file, image): self.font = Image.core.font(image.im, data) def getsize(self, text, *args, **kwargs): + """ + Returns width and height (in pixels) of given text. + + :param text: Text to measure. + + :return: (width, height) + """ return self.font.getsize(text) def getmask(self, text, mode="", *args, **kwargs): + """ + Create a bitmap for the text. + + If the font uses antialiasing, the bitmap should have mode ``L`` and use a + maximum value of 255. Otherwise, it should have mode ``1``. + + :param text: Text to render. + :param mode: Used by some graphics drivers to indicate what mode the + driver prefers; if empty, the renderer may return either + mode. Note that the mode is always a string, to simplify + C-level implementations. + + .. versionadded:: 1.1.5 + + :return: An internal PIL storage memory instance as defined by the + :py:mod:`PIL.Image.core` interface module. + """ return self.font.getmask(text, mode)