release 0.4a1

Author: hx2A

py5/__init__.py

@@ -111,7 +111,7 @@ def create_font_file(
     set the ``pause`` parameter to ``False``.
 
     Get a list of font names available on your computer with Py5Font's
-    :doc:`py5font_list` method. If you request an unavailable font, it will create
+    ``Py5Font.list()`` method. If you request an unavailable font, it will create
     the data file anyway but using a default font."""
     vlw_creator = CreateFontTool(font_name, font_size,
                                  filename=filename, characters=characters,

py5/create_font_tool.py

@@ -24,6 +24,7 @@
 from jpype import JException, JArray, JString  # noqa
 
 from .shape import Py5Shape, _return_py5shape  # noqa
+from .type_decorators import _ret_str  # noqa
 
 
 def _return_py5font(f):
@@ -68,16 +69,16 @@ class Py5Font:
     -----
 
     Py5Font is the font class for py5. To create a font to use with py5, use
-    :doc:`create_font_file`. This will create a font in the format py5 requires. Py5
+    ``create_font_file()``. This will create a font in the format py5 requires. Py5
     displays fonts using the .vlw font format, which uses images for each letter,
-    rather than defining them through vector data. The :doc:`load_font` function
-    constructs a new font and :doc:`text_font` makes a font active. The
-    :doc:`py5font_list` method creates a list of the fonts installed on the
-    computer, which is useful information to use with the :doc:`create_font`
-    function for dynamically converting fonts into a format to use with py5.
-
-    To create a new font dynamically, use the :doc:`create_font` function. Do not
-    use the syntax ``Py5Font()``.
+    rather than defining them through vector data. The ``load_font()`` function
+    constructs a new font and ``text_font()`` makes a font active. The
+    ``Py5Font.list()`` method creates a list of the fonts installed on the computer,
+    which is useful information to use with the ``create_font()`` function for
+    dynamically converting fonts into a format to use with py5.
+
+    To create a new font dynamically, use the ``create_font()`` function. Do not use
+    the syntax ``Py5Font()``.
     """
 
     _cls = jpype.JClass('processing.core.PFont')
@@ -87,92 +88,90 @@ def __init__(self, pfont):
         self._instance = pfont
 
     def ascent(self) -> float:
-        """The documentation for this field or method has not yet been written.
+        """Get the ascent of this font from the baseline.
 
         Underlying Java method: PFont.ascent
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the ascent of this font from the baseline. The value is based on a font of
+        size 1. Multiply it by the font size to get the offset from the baseline.
         """
         return self._instance.ascent()
 
     def descent(self) -> float:
-        """The documentation for this field or method has not yet been written.
+        """Get the descent of this font from the baseline.
 
         Underlying Java method: PFont.descent
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the descent of this font from the baseline. The value is based on a font of
+        size 1. Multiply it by the font size to get the offset from the baseline.
         """
         return self._instance.descent()
 
     def get_default_size(self) -> int:
-        """The documentation for this field or method has not yet been written.
+        """Get the font's size that will be used when ``text_font()`` is called.
 
         Underlying Java method: PFont.getDefaultSize
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the font's size that will be used when ``text_font()`` is called. When
+        drawing with 2x pixel density, bitmap fonts in OpenGL need to be created at
+        double the requested size. This ensures that they're shown at half on displays
+        (so folks don't have to change their sketch code).
         """
         return self._instance.getDefaultSize()
 
     def get_glyph_count(self) -> int:
-        """The documentation for this field or method has not yet been written.
+        """Get the number of glyphs contained in the font.
 
         Underlying Java method: PFont.getGlyphCount
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the number of glyphs contained in the font. This will be 0 if the font is a
+        "lazy font" that creates glyphs as they are needed by the Sketch. This will be
+        the case if the font was created with ``create_font()`` without using the
+        ``charset`` parameter.
         """
         return self._instance.getGlyphCount()
 
+    @_ret_str
     def get_name(self) -> str:
-        """The documentation for this field or method has not yet been written.
+        """Get the font's name.
 
         Underlying Java method: PFont.getName
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the font's name.
         """
         return self._instance.getName()
 
+    @_ret_str
     def get_post_script_name(self) -> str:
-        """The documentation for this field or method has not yet been written.
+        """Get the font's postscript name.
 
         Underlying Java method: PFont.getPostScriptName
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the font's postscript name.
         """
         return self._instance.getPostScriptName()
 
     @overload
     def get_shape(self, ch: chr, /) -> Py5Shape:
-        """The documentation for this field or method has not yet been written.
+        """Get a single character as a ``Py5Shape`` object.
 
         Underlying Java method: PFont.getShape
 
@@ -188,23 +187,27 @@ def get_shape(self, ch: chr, /) -> Py5Shape:
         ----------
 
         ch: chr
-            missing variable description
+            single character
 
         detail: float
-            missing variable description
+            level of shape detail
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get a single character as a ``Py5Shape`` object. Use the ``detail`` parameter to
+        draw the shape with only straight line segments.
+
+        Calling ``Py5Shape.disable_style()`` on the returned ``Py5Shape`` object seems
+        to be necessary for these to be drawable.
+
+        This method only works on fonts loaded with ``create_font()``.
         """
         pass
 
     @overload
     def get_shape(self, ch: chr, detail: float, /) -> Py5Shape:
-        """The documentation for this field or method has not yet been written.
+        """Get a single character as a ``Py5Shape`` object.
 
         Underlying Java method: PFont.getShape
 
@@ -220,23 +223,27 @@ def get_shape(self, ch: chr, detail: float, /) -> Py5Shape:
         ----------
 
         ch: chr
-            missing variable description
+            single character
 
         detail: float
-            missing variable description
+            level of shape detail
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get a single character as a ``Py5Shape`` object. Use the ``detail`` parameter to
+        draw the shape with only straight line segments.
+
+        Calling ``Py5Shape.disable_style()`` on the returned ``Py5Shape`` object seems
+        to be necessary for these to be drawable.
+
+        This method only works on fonts loaded with ``create_font()``.
         """
         pass
 
     @_return_py5shape
     def get_shape(self, *args):
-        """The documentation for this field or method has not yet been written.
+        """Get a single character as a ``Py5Shape`` object.
 
         Underlying Java method: PFont.getShape
 
@@ -252,62 +259,50 @@ def get_shape(self, *args):
         ----------
 
         ch: chr
-            missing variable description
+            single character
 
         detail: float
-            missing variable description
+            level of shape detail
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get a single character as a ``Py5Shape`` object. Use the ``detail`` parameter to
+        draw the shape with only straight line segments.
+
+        Calling ``Py5Shape.disable_style()`` on the returned ``Py5Shape`` object seems
+        to be necessary for these to be drawable.
+
+        This method only works on fonts loaded with ``create_font()``.
         """
         return self._instance.getShape(*args)
 
     def get_size(self) -> int:
-        """The documentation for this field or method has not yet been written.
+        """Get the font's size.
 
         Underlying Java method: PFont.getSize
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the font's size.
         """
         return self._instance.getSize()
 
     def is_smooth(self) -> bool:
-        """The documentation for this field or method has not yet been written.
+        """Boolean value reflecting if smoothing (anti-aliasing) was used when the font was
+        created.
 
         Underlying Java method: PFont.isSmooth
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Boolean value reflecting if smoothing (anti-aliasing) was used when the font was
+        created. By default, ``create_font()`` will use smoothing.
         """
         return self._instance.isSmooth()
 
-    def is_stream(self) -> bool:
-        """The documentation for this field or method has not yet been written.
-
-        Underlying Java method: PFont.isStream
-
-        Notes
-        -----
-
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
-        """
-        return self._instance.isStream()
-
     @classmethod
     @_return_list_str
     def list(cls) -> List[str]:
@@ -320,42 +315,29 @@ def list(cls) -> List[str]:
 
         Gets a list of the fonts installed on the system. The data is returned as a list
         of strings. This list provides the names of each font for input into
-        :doc:`create_font`, which allows py5 to dynamically format fonts.
+        ``create_font()``, which allows py5 to dynamically format fonts.
 
         This works outside of a running Sketch.
         """
         return cls._cls.list()
 
-    def set_subsetting(self) -> None:
-        """The documentation for this field or method has not yet been written.
-
-        Underlying Java method: PFont.setSubsetting
-
-        Notes
-        -----
-
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
-        """
-        return self._instance.setSubsetting()
-
     def width(self, c: chr, /) -> float:
-        """The documentation for this field or method has not yet been written.
+        """Get the width of a character in this font.
 
         Underlying Java method: PFont.width
 
         Parameters
         ----------
 
         c: chr
-            missing variable description
+            single character
 
         Notes
         -----
 
-        The documentation for this field or method has not yet been written. If you know
-        what it does, please help out with a pull request to the relevant file in
-        https://github.com/hx2A/py5generator/tree/master/py5_docs/Reference/api_en/.
+        Get the width of a character in this font. The value is based on a font of size
+        1. Multiply it by the font size to get the horizontal space of the character.
+
+        This will return 0 if the character is not in the font's character set.
         """
         return self._instance.width(c)