Merge pull request #146 from chinapandaman/PPF-145

PPF-145: update docs with new font related features

Author: chinapandaman

docs/v2/api_reference.md

@@ -5,7 +5,7 @@ of PyPDFForm.
 
 ## PyPDFForm Object
 
-### *class* PyPDFForm.**PyPDFForm**(*template=b"", simple_mode=True, global_font_size=12, global_font_color=(0, 0, 0), global_text_x_offset=0, global_text_y_offset=0, global_text_wrap_length=100*)
+### *class* PyPDFForm.**PyPDFForm**(*template=b"", simple_mode=True, global_font="Helvetica", global_font_size=12, global_font_color=(0, 0, 0), global_text_x_offset=0, global_text_y_offset=0, global_text_wrap_length=100*)
 
 The PyPDFForm object implements a PDF form and acts as 
 the central object. It can be constructed with or without a 
@@ -22,6 +22,9 @@ by Python IO's `.read()` method.
 details like font size. Turning simple mode on also allows leaving PDF editable 
 after filling.
 
+* **global_font** - a string which sets the global font for text filled on the PDF form. The 
+font set by this parameter has to be registered first. This will only take effect if `simple_mode` is `False`. 
+  
 * **global_font_size** - an integer/float value which sets the global font size for texts 
 filled on the PDF form. This will only take effect if `simple_mode` is `False`.
 
@@ -65,7 +68,7 @@ on the specified page, coordinates with specified resolutions and rotation angle
 
 * **rotation** - integer/float, degrees the image will be rotated after drawn.
 
-### **draw_text**(*text, page_number, x, y, font_size=12, font_color=(0, 0, 0), text_x_offset=0, text_y_offset=0, text_wrap_length=100*)
+### **draw_text**(*text, page_number, x, y, font="Helvetica", font_size=12, font_color=(0, 0, 0), text_x_offset=0, text_y_offset=0, text_wrap_length=100*)
 
 The draw text method takes a text string and draws it on the specified page 
 at the specified coordinates.
@@ -80,6 +83,9 @@ at the specified coordinates.
 
 * **y** - integer/float, vertical coordinate of which the text will be drawn at.
 
+* **font** - string, sets the font for text drawn. Font set by this parameter has to be 
+registered first.
+
 * **font_size** - integer/float, font size of the text drawn.
 
 * **font_color** - RGB integer/float tuple, font color of the text drawn.
@@ -112,6 +118,18 @@ be printed and a `boolean` will check the corresponding checkboxes.
 
 * **editable** - only available if `simple_mode` is `True`, enabling this will allow the filled PDF to be still 
 editable.
+  
+### **register_font**(*font_name, ttf_stream*)
+
+This class method takes a TTF font file stream and register it with the `font_name` specified. 
+Registered fonts can then be used by any instance of object.
+
+#### Parameters:
+
+* **font_name** - a string of which the font will be registered as. Registered fonts can be referenced and 
+used via this name.
+
+* **ttf_stream** - a byte stream of the ttf font file.
 
 ### **simple_mode** = *True*
 

docs/v2/examples.md

@@ -86,6 +86,51 @@ with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
 
 Link to this example: https://github.com/chinapandaman/PyPDFForm/blob/master/examples/simple_fill_editable.py
 
+## Register font and set registered global font on filled text
+
+This example registers a [LiberationSerif-Regular](https://github.com/chinapandaman/PyPDFForm/blob/master/font_samples/LiberationSerif-Regular.ttf) 
+font and sets it as the global font on the filled PDF form.
+
+```python
+import os
+
+from PyPDFForm import PyPDFForm
+
+PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
+    os.path.expanduser("~/Downloads"), "sample_template.pdf"
+)  # Change this to where you downloaded the sample PDF form
+
+PATH_TO_SAMPLE_TTF_FONT_FILE = os.path.join(
+    os.path.expanduser("~/Downloads"), "LiberationSerif-Regular.ttf"
+)  # Change this to where you downloaded the sample font file
+
+PATH_TO_FILLED_PDF_FORM = os.path.join(
+    os.path.expanduser("~"), "output.pdf"
+)  # Change this to where you wish to put your filled PDF form
+
+with open(PATH_TO_SAMPLE_TTF_FONT_FILE, "rb+") as font:
+    PyPDFForm.register_font("LiberationSerif-Regular", font.read())
+
+with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
+    filled_pdf = PyPDFForm(
+        template.read(), simple_mode=False, global_font="LiberationSerif-Regular",
+    ).fill(
+        {
+            "test": "test_1",
+            "check": True,
+            "test_2": "test_2",
+            "check_2": False,
+            "test_3": "test_3",
+            "check_3": True,
+        },
+    )
+
+    with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
+        output.write(filled_pdf.stream)
+```
+
+Link to this example: https://github.com/chinapandaman/PyPDFForm/blob/master/examples/fill_font.py
+
 ## Set global font size and font color on filled text
 
 This example sets a global font size of 20, and a global font color of red 
@@ -354,10 +399,17 @@ PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
     os.path.expanduser("~/Downloads"), "sample_template.pdf"
 )  # Change this to where you downloaded the sample PDF form
 
+PATH_TO_SAMPLE_TTF_FONT_FILE = os.path.join(
+    os.path.expanduser("~/Downloads"), "LiberationSerif-Italic.ttf"
+)  # Change this to where you downloaded the sample font file
+
 PATH_TO_FILLED_PDF_FORM = os.path.join(
     os.path.expanduser("~"), "output.pdf"
 )  # Change this to where you wish to put your filled PDF form
 
+with open(PATH_TO_SAMPLE_TTF_FONT_FILE, "rb+") as font:
+    PyPDFForm.register_font("LiberationSerif-Italic", font.read())
+
 with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
     pdf_form = PyPDFForm(template.read(), simple_mode=False)
 
@@ -367,6 +419,7 @@ with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
     pdf_form.elements["test_2"].text_y_offset = -50
     pdf_form.elements["test_2"].text_wrap_length = 1
     pdf_form.elements["test_2"].font_color = (0, 1, 0)
+    pdf_form.elements["test_3"].font = "LiberationSerif-Italic"
     pdf_form.elements["test_3"].text_wrap_length = 2
     pdf_form.elements["test_3"].font_color = (0, 0, 1)
 

examples/fill_customized_elements.py

@@ -6,10 +6,17 @@
     os.path.expanduser("~/Downloads"), "sample_template.pdf"
 )  # Change this to where you downloaded the sample PDF form
 
+PATH_TO_SAMPLE_TTF_FONT_FILE = os.path.join(
+    os.path.expanduser("~/Downloads"), "LiberationSerif-Italic.ttf"
+)  # Change this to where you downloaded the sample font file
+
 PATH_TO_FILLED_PDF_FORM = os.path.join(
     os.path.expanduser("~"), "output.pdf"
 )  # Change this to where you wish to put your filled PDF form
 
+with open(PATH_TO_SAMPLE_TTF_FONT_FILE, "rb+") as font:
+    PyPDFForm.register_font("LiberationSerif-Italic", font.read())
+
 with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
     pdf_form = PyPDFForm(template.read(), simple_mode=False)
 
@@ -19,6 +26,7 @@
     pdf_form.elements["test_2"].text_y_offset = -50
     pdf_form.elements["test_2"].text_wrap_length = 1
     pdf_form.elements["test_2"].font_color = (0, 1, 0)
+    pdf_form.elements["test_3"].font = "LiberationSerif-Italic"
     pdf_form.elements["test_3"].text_wrap_length = 2
     pdf_form.elements["test_3"].font_color = (0, 0, 1)
 

examples/fill_font.py

@@ -0,0 +1,37 @@
+import os
+
+from PyPDFForm import PyPDFForm
+
+PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM = os.path.join(
+    os.path.expanduser("~/Downloads"), "sample_template.pdf"
+)  # Change this to where you downloaded the sample PDF form
+
+PATH_TO_SAMPLE_TTF_FONT_FILE = os.path.join(
+    os.path.expanduser("~/Downloads"), "LiberationSerif-Regular.ttf"
+)  # Change this to where you downloaded the sample font file
+
+PATH_TO_FILLED_PDF_FORM = os.path.join(
+    os.path.expanduser("~"), "output.pdf"
+)  # Change this to where you wish to put your filled PDF form
+
+with open(PATH_TO_SAMPLE_TTF_FONT_FILE, "rb+") as font:
+    PyPDFForm.register_font("LiberationSerif-Regular", font.read())
+
+with open(PATH_TO_DOWNLOADED_SAMPLE_PDF_FORM, "rb+") as template:
+    filled_pdf = PyPDFForm(
+        template.read(),
+        simple_mode=False,
+        global_font="LiberationSerif-Regular",
+    ).fill(
+        {
+            "test": "test_1",
+            "check": True,
+            "test_2": "test_2",
+            "check_2": False,
+            "test_3": "test_3",
+            "check_3": True,
+        },
+    )
+
+    with open(PATH_TO_FILLED_PDF_FORM, "wb+") as output:
+        output.write(filled_pdf.stream)

setup.py

@@ -16,7 +16,7 @@
 
 setuptools.setup(
     name="PyPDFForm",
-    version="0.2.0",
+    version="0.2.1",
     description="python library for PDF forms",
     long_description=long_description,
     long_description_content_type="text/markdown",