python-pillow/Pillow
1
1
Fork 0
mirror of https://github.com/python-pillow/Pillow.git synced 2025-10-30 23:47:27 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3804 from radarhere/imagefont_docs

Browse Source 
Improved ImageFont documentation
This commit is contained in:
Hugo 2019-04-24 10:20:34 +03:00 committed by GitHub
commit 764a027e28
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 224 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/reference/ImageDraw.rst
View File

@ -287,11 +287,11 @@ Methods
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
@ -326,11 +326,11 @@ Methods
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
@ -362,11 +362,11 @@ Methods
Requires libraqm.
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
@ -398,11 +398,11 @@ Methods
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.

19
docs/reference/ImageFilter.rst
View File

@ -38,12 +38,31 @@ image enhancement filters:
* **SMOOTH_MORE**
.. autoclass:: PIL.ImageFilter.Color3DLUT
:members:
.. autoclass:: PIL.ImageFilter.BoxBlur
:members:
.. autoclass:: PIL.ImageFilter.GaussianBlur
:members:
.. autoclass:: PIL.ImageFilter.UnsharpMask
:members:
.. autoclass:: PIL.ImageFilter.Kernel
:members:
.. autoclass:: PIL.ImageFilter.RankFilter
:members:
.. autoclass:: PIL.ImageFilter.MedianFilter
:members:
.. autoclass:: PIL.ImageFilter.MinFilter
:members:
.. autoclass:: PIL.ImageFilter.MaxFilter
:members:
.. autoclass:: PIL.ImageFilter.ModeFilter
:members:

15
docs/reference/ImageFont.rst
View File

@ -51,9 +51,9 @@ Methods
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.
@ -73,11 +73,11 @@ Methods
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
@ -119,11 +119,11 @@ Methods
.. versionadded:: 4.2.0
:param language: Language of the text. Different languages may use
: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 `BCP47 language code
It should be a `BCP 47 language code
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
@ -131,3 +131,6 @@ Methods
:return: An internal PIL storage memory instance as defined by the
:py:mod:`PIL.Image.core` interface module.
.. autoclass:: PIL.ImageFont.FreeTypeFont
:members:

1
docs/reference/ImageSequence.rst
View File

@ -25,3 +25,4 @@ The :py:class:`~PIL.ImageSequence.Iterator` class
-------------------------------------------------
.. autoclass:: PIL.ImageSequence.Iterator
:members:

4
docs/reference/ImageWin.rst
View File

@ -24,6 +24,8 @@ Tkinter makes the window handle available via the winfo_id method:
.. autoclass:: PIL.ImageWin.Dib
:members:
.. autoclass:: PIL.ImageWin.HDC
:members:
.. autoclass:: PIL.ImageWin.HWND
:members:

184
src/PIL/ImageFont.py
View File

@ -153,17 +153,99 @@ class FreeTypeFont(object):
return text.split(split_character)
def getname(self):
"""
:return: A tuple of the font family (e.g. Helvetica) and the font style
(e.g. Bold)
"""
return self.font.family, self.font.style
def getmetrics(self):
"""
:return: A tuple of the font ascent (the distance from the baseline to
the highest outline point) and descent (the distance from the
baseline to the lowest outline point, a negative value)
"""
return self.font.ascent, self.font.descent
def getsize(self, text, direction=None, features=None, 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
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
.. versionadded:: 6.0.0
:return: (width, height)
"""
size, offset = self.font.getsize(text, direction, features, language)
return (size[0] + offset[0], size[1] + offset[1])
def getsize_multiline(self, text, direction=None, spacing=4,
features=None, language=None):
"""
Returns width and height (in pixels) of given text if rendered in font
with provided direction, features, and language, while respecting
newline characters.
: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.
:param spacing: The vertical gap between lines, defaulting to 4 pixels.
: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.
: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
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
.. versionadded:: 6.0.0
:return: (width, height)
"""
max_width = 0
lines = self._multiline_split(text)
line_spacing = self.getsize('A')[1] + spacing
@ -174,14 +256,116 @@ class FreeTypeFont(object):
return max_width, len(lines)*line_spacing - spacing
def getoffset(self, text):
"""
Returns the offset of given text. This is the gap between the
starting coordinate and the first marking. Note that this gap is
included in the result of :py:func:`~PIL.ImageFont.FreeTypeFont.getsize`.
:param text: Text to measure.
:return: A tuple of the x and y offset
"""
return self.font.getsize(text)[1]
def getmask(self, text, mode="", direction=None, features=None, 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
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
.. versionadded:: 6.0.0
:return: An internal PIL storage memory instance as defined by the
:py:mod:`PIL.Image.core` interface module.
"""
return self.getmask2(text, mode, direction=direction, features=features,
language=language)[0]
def getmask2(self, text, mode="", fill=Image.core.fill, direction=None,
features=None, language=None, *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
: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
<https://www.w3.org/International/articles/language-tags/>`
Requires libraqm.
.. versionadded:: 6.0.0
:return: A tuple of an internal PIL storage memory instance as defined by the
:py:mod:`PIL.Image.core` interface module, and the text offset, the
gap between the starting coordinate and the first marking
"""
size, offset = self.font.getsize(text, direction, features, language)
im = fill("L", size, 0)
self.font.render(text, im.id, mode == "1", direction, features, language)