doc/sphinx/techref/pyextend.rst
FontForge includes an extensive :doc:Python API </scripting/python> which is
most often used in scripts to alter and generate font files. However, this API
also provides ways of extending the functionality of the FontForge program,
including the user interface. Most of these are documented in the :ref:User Interface Module Functions <fontforge.ui_functions> section of the Python
documentation.
Given that points and contours are basis of vector font data many extensions will want to modify them. There is one misleading aspect of the "layer" API that must be clarified in order to do so. It is also important to be aware of layers and how they relate to the FontForge user interface.
The Basics ^^^^^^^^^^
A point is (typically) an element of a contour and a contour is
(typically) an element of a layer. Confusingly, however, there are really
two meanings of the term "layer" in the FontForge Python API. One is the
fontforge.layer object, which is the object that can contain
fontforge.contour objects. The other is a layer internal to a font
object.
The confusion arises when a developer attempts to modify a point in this way: ::
f = fontforge.open('foo.otf')
g = f['a']
l = g.foreground
for c in l:
for p in c:
p.x += 15
f.generate('foo_new.otf')
After this script executes the points of the glyph "a" in foo_new.otf will
be the same as those in foo.otf. And this is true even though the points in
the fontforge.layer object l have been changed. This is because l
is not a reference to g.foreground (which represents the internal state
of the layer) but a copy of it. Any changes to the layer must therefore be
"copied back" to have an effect on the font. This can be done with an
assignment but we now recommend using the glyph.setLayer() method instead,
as this gives you more control over how point types are preserved or converted
as they are copied back.::
f = fontforge.open('foo.otf')
g = f['a']
l = g.foreground
for c in l:
for p in c:
p.x += 15
g.setLayer(l, 'Fore')
f.generate('foo_new.otf')
Layer Awareness and Undo Preservation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The author of a "top-down" script for modifying a font will typically know what
layer to modify—most often glyph.foreground (which is also identified as
"0" or "Fore"). A script that extends the FontForge UI with a new menu option
should not make such assumptions. At a given time the user may be editing the
foreground or background layer or even one of a few layers in a multi-layer
font. Such a function should therefore typically not reference specific layers
at all and use glyph.activeLayer instead, as in: ::
def shiftBy15(u, glyph):
l = glyph.layers[glyph.activeLayer]
for c in l:
for p in c:
p.x += 15
glyph.preserveLayerAsUndo(glyph.activeLayer)
g.setLayer(l, glyph.activeLayer)
This function also demonstrates an appropriate use of the
preserveLayerAsUndo() method. Setting an "internal" layer (either through
assignment for with the glyph.setLayer() method) does not automatically add
the previous layer to the Undo/Redo state. By calling
glyph.preserveLayerAsUndo() you give the user the option of reversing your
change with "Edit -> Undo".
References ^^^^^^^^^^
The reference API is similar to the layer API, with the same caveats. You can
get the list of references for the current UI layer with rl = g.layerrefs[g.activeLayer] (where g is a fontforge.glyph object). To
effect changes in the references you need to assign back to
g.layerrefs[g.activeLayer]. Each reference is represented by a tuple of
glyph name, transformation matrix tuple (that is, a sub-tuple of six floating
point numbers representing the transformation) and a boolean selected status.
This script accordingly shifts the references in the current layer by 15 points: ::
def shiftRefsBy15(u, glyph):
rl = glyph.layerrefs[glyph.activeLayer]
nl = []
tr = psMat.translate(15,0)
for r in rl:
nl.append((r[0], psMat.compose(r[1], tr), r[2]))
glyph.preserveLayerAsUndo(glyph.activeLayer)
glyph.layerrefs[glyph.activeLayer] = nl
(One could also have used a transformation matrix to move the points in the earlier
fragments by passing it to p.transform().)
As noted in the API documentation, when assigning to the reference list the
transformation matrix and selection status tuple elements are optional (with
respective defaults of the identity matrix and False).
Anchor Points ^^^^^^^^^^^^^
In contrast with points and references, all anchor points are considered part
of the foreground layer. They can be accessed and edited through the
glyph.anchorPointsWithSel property. When editing the list care must be
taken to construct the tuples so that the name, type, position, selection and
(when relevant) ligature information are preserved or changed as desired.
.. _fontforge.plugin_menu:
The functions shiftBy15() and shiftRefsBy15() above were written to
be added as menu items using :py:meth:fontforge.registerMenuItem. This is
the most common form of FontForge UI extension and we recommend familiarizing
(or re-familiarizing) yourself with the documentation as the API has recently
been enhanced.
Selection State ^^^^^^^^^^^^^^^
In the case of many menu items, probably most of them, the user should have some "input" into how one applies in a given situation. Sometimes this is a reason to raise a dialog asking the user for input, but in the majority of cases a menu callback will "interact" with a user by way of selection state.
Each point, both on-curve and control, has a boolean selection state. The selection state of on-curve points is generally more important or "primary". The "Transform ..." dialog, for example, transforms selected on-curve points (and references) and their associated off-curve points regardless of the latter's selection status. (This is true unless no points are selected, in which case all points are transformed.) Other contour-level facilities, such as "Correct Direction", consider a contour to be selected if at least one of its on-curve points is selected, and changes those contours accordingly.
Still, in some cases you may want to attend to the selection state of control points.
Each reference and anchor point also has a selection state. The Python reference API has recently been enhanced to make the state available.
As an example, consider the shiftRefsBy15 function above. We could
enhance it to shift only selected references unless there are none,
in all references are shifted: ::
def shiftRefsBy15(u, glyph):
rl = glyph.layerrefs[glyph.activeLayer]
has_selected = False
for r in rl:
if r[2]:
has_selected = True
nl = []
tr = psMat.translate(15,0)
for r in rl:
if not has_selected or r[2]:
nl.append((r[0], psMat.compose(r[1], tr), r[2]))
else:
nl.append(r)
glyph.preserveLayerAsUndo(glyph.activeLayer)
glyph.layerrefs[glyph.activeLayer] = nl
At the font level each font has its own selection state accessible via the
:py:attr:fontforge.font.selection property. Many useful font-level tools will
be selection-agnostic but some should only apply to selected glyphs. When
these are added as menu items they should include enable_functions analogous to
those of a glyph-level tool, so that a user learns whey they do and do not
apply.
Enable Functions ^^^^^^^^^^^^^^^^
Some menu items, such as one that adds a new point in a CharView, may always be
"applicable". Others can only do something sensible if the character (or font)
has certain features, such as at least one point or reference, or if certain
combinations of points, anchor points, and references are selected. When adding
a new option you should help the user understand when it is and is not
applicable by writing and registering an enable function. This will allow
FontForge to display the item as enabled in the menu when it applies and as
disabled when it does not apply.
The enhanced version of shiftRefsBy15() only applies if there is at least
one reference, so it's enable function could be: ::
def SRB15Enable(u, glyph):
return len(glyph.layerrefs[glyph.activeLayer])>0
See the next section for an example of how to register this function.
Hotkeys and Mnemonics ^^^^^^^^^^^^^^^^^^^^^
A menu item can have both a Hotkey and a Mnemonic. These are two different means of picking a menu item using the keyboard.
A Hotkey is a single key combination, usually including modifiers like Control,
Alt, and Shift, that directly invokes a menu item or other action. Because
hotkeys are a "limited resource", unless you are confident that a menu item you
register should have one it may be better to let the user add their own if they
find your addition particularly useful. As the
:py:meth:fontforge.registerMenuItem documentation notes, even if you do
include a hotkey string when registering that key combination may already
be taken, in which case no hotkey will be assigned.
Mnemonics provide a per-menu key accelerator, usually activated by pressing Alt and then the mnemonic key displayed with an underline. Using sequences of mnemonic key combinations a user can navigate from the menu bar down through sub-menus and choose a menu action entirely with the keyboard. Mnemonics are also a "limited resource" but less limited, and we encourage all plugin developers to specify them.
You specify a mnemonic key by preceding it with an underscore in the name, as in: ::
fontforge.registerMenuItem(callback=shiftRefsBy15, enable=SRB15Enable,
context=("Glyph"), name=("_Shift References by 15", "MyExt.shiftRefsBy15"),
submenu=("_MyExt", "MyExt.submenu"))
which specifes "M" as the mnemonic for the "MyExt" submenu and "S" as the mnemonic for the action.
Note, however, that the specified mnemonic for the top level is only taken as a suggestion, and if it is not available another will be assigned. This is because different users will have different combinations of plugins and init scripts installed in different orders, so any given mnemonic may already be in use. Because lower menu levels will typically have entries for one plugin or script you can count on getting the mnemonic you specify.
Best Practices ^^^^^^^^^^^^^^
In addition to the advice above, we recommend that a plugin put all of its added menu items into or under a single sub-menu of "Tools". A user may have many plugins installed or have their own init scripts so a single plugin should avoid taking up a lot of space.
The FontForge SFD file format and python API includes
:py:attr:fontforge.font.persistent for storing per-font information and
:py:attr:fontforge.glyph.persistent for storing per-glyph information.
These are fragile interfaces, however, and should only be used when strictly
necessary.
The FontForge program does not enforce any pattern of use on these attributes. We suggest the following conventions:
persistent attribute.fontforge.ask dialog that allows them to opt-out of overwriting
the value. If they give permission you can create a dictionary as in step
1 and overwrite the existing data... _fontforge.plugin_api:
Even when you eventually plan on writing a FontForge Python plugin it will
generally be easiest to start by writing an "Init Script". This is a script
that, when placed in one of the directories listed by the
:py:meth:fontforge.scriptPath() <fontforge.scriptPath> function, is
automatically run when FontForge is started.
As a simple example, here is a script that adds an "Add Midpoint Contour" entry to the Char View Tools menu. When any two on-curve points of a glyph are selected this adds a new contour containing a single point that is located midway between the two selected points.::
import fontforge
def getSelectedPoints(l):
pl = []
for c in l:
pl.extend( [ p for p in c if p.on_curve and p.selected ] )
return pl
def midContourEnable(u, glyph):
return len(getSelectedPoints(glyph.layers[glyph.activeLayer]))==2
def addMidContour(u, glyph):
layer_id = glyph.activeLayer
l = glyph.layers[layer_id]
pl = getSelectedPoints(l)
if len(pl) != 2:
fontforge.postError("Bad selection", "You must select "
"exactly two on-curve points to add a midpoint contour.")
return
nc = fontforge.contour()
nc.insertPoint(((pl[0].x+pl[1].x)/2, (pl[0].y+pl[1].y)/2, True,
fontforge.splineCorner, True))
l += nc
glyph.preserveLayerAsUndo(layer_id)
glyph.layers[layer_id] = l
fontforge.registerMenuItem(callback=addMidContour, enable=midContourEnable,
context=("Glyph"), name="_Add Midpoint Contour")
This script is typical in that it starts with some imports, defines some
functions, and ends by invoking :py:meth:fontforge.registerMenuItem. Other
scripts may import other modules, define more elaborate functions or classes,
or register more menu items or other callbacks. Still, this is a common
general pattern.
The first step in converting the script to a plugin is to wrap the last
section in a function called fontforge_plugin_init(). Once the file
is packaged appropriately this function will be called after FontForge
discovers and loads the plugin (if the user has Enabled it).::
def fontforge_plugin_init(**kw):
fontforge.registerMenuItem(callback=addMidContour,
enable=midContourEnable, context=("Glyph"),
name="_Add Midpoint Contour")
The **kw function argument will capture any keyword arguments passed
to the function. There is currently one, discussed below, but more may
be added in the future. (Note that while the function can be located
in other places (see the section on Entry-points below) it must be a
function, not a method.
The remaining steps have to do with python "packaging", which is too
large a topic to discuss extensively in this guide. A good starting
point is Packaging Python Projects <https://packaging.python.org/tutorials/packaging-projects/>_ from the
Python documentation. The following are the very basics.
First we create a new directory for our project with the following files:
fontforge_midpoint.py (The script itself as a single module file.)LICENSE (Containing the license text.)README.md (A file containing basic documentation for the plugin, in this
case written in Python-Mark-down format <https://pypi.org/project/Markdown/>_.pyproject.tomlsetup.cfg or setup.pypyproject.toml is a short helper file for the setuptools package
builder. It will typically have these contents: ::
[build-system]
requires = [
"setuptools>=42",
"wheel"
]
build-backend = "setuptools.build_meta"
Finally there is the setup.cfg file (or, less typically these days, the
setup.py file). It should have contents analogous to these: ::
[metadata]
name = fontforge-midcontour
version = 1.0.0
author = Example Author
author_email = [email protected]
description = A FontForge_plugin to add a single-point contour between points
long_description = file: README.md
long_description_content_type = text/markdown
url = https::/github.com/author/MidContour
classifiers =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
Topic :: Text Processing :: Fonts
[options]
py_modules = fontforge_midcontour
python_requires = >=3.6
[options.entry_points]
fontforge_plugin =
MidContour = fontforge_midcontour
The name field is the name of the package. Recent Python documentation
encourages developers to add their PyPI username to the package name but
this practice has not been widely adopted. For now we recommend that you
include "fontforge" in the package name along with a string that either
specifically identifies what your plugin does or is just a distinctive
project name. Therefore ambiguous names like "Point" or "Contour" should
be avoided as these are more likely to also be used by someone else. Please
search the PyPI database for a candidate name to help ensure it is not already
in use. Package names should be all lower case but can contain dashes and
underscores.
The url should point to your project page or a GitHub (or other such
service) repository for the plugin code.
Obviously the description field should contain a one-line description of
the plugin. However, it is important that this description (or, if that is not
possible, the README file) contain the exact string "FontForge_plugin".
FontForge does not maintain its own database of plugins; it instead links to
the PyPI database query system passing that string.
classifiers help users people searching on PyPI to find
relevant packages (although the list of classifiers is, unfortunately, fixed).
This is a reasonable selection.
py_modules should be the list of modules provided by the package without
any .py extensions. (More complicated packages with sub-directories
could benefit from using packages = find: instead.
The last directives specify the Python package "Entry-points", which are
the basis of FontForge's discovery system. The Entry-point identifier
must be fontforge_plugin.
The token on the left of the indented line is the plugin name. This will appear in the "Configure Plugins..." dialog and other contexts. It will normally be the name of your package except without "fontforge" and with optional capitalization. It can contain the usual alphanumerics-plus-underscores and also spaces (although spaces are not recommended).
The token on the right of the equals sign identifies the location of the
fontforge_plugin_init function. In this case it is just at the top
level of the module so the identifier is just the module name. If it were
instead a property of object "MC" in that module the string would be
fontforge_midcontour.MC.
In some cases you may want to use a setup.py file instead. The file
equivalent to the setup.cfg above is: ::
import setuptools
with open("README.md", "r", encoding="utf-8") as fh: long_description = fh.read()
setuptools.setup( name="fontforge_midcontour-author", version="1.0.0", author="Example Author", author_email="[email protected]", description="A FontForge_plugin to add a single-point contour between points", long_description = long_description, long_description_content_type = "text/markdown", url="https::/github.com/author/MidContour", py_modules=["fontforge_midcontour"], classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Topic :: Text Processing :: Fonts", ], python_requires=">=3.6", entry_points={ 'fontforge_plugin': [ 'MidContour = fontforge_midcontour' ],}, )
Once the directory has the five files with the appropriate contents you can
build the package by entering the directory and running python -m build .
If there are no errors the package archive will be added to the dist
subdirectory (which will be created if necessary). This package can be
installed directly with pip install [name] or published on PyPI <https://realpython.com/pypi-publish-python-package/#publishing-to-pypi>_.
Marking Dependencies ^^^^^^^^^^^^^^^^^^^^
A simple plugin may have no dependencies beyond FontForge itself, and because
only FontForge will attempt to discover and load plugins it is not necessary
to mark that dependency. Other plugins may import numerical processing modules
or use tkinter to raise dialogs.
"Hard" dependencies—those that a plugin cannot operate without—should be marked
in the [options] section of setup.cfg with an install_requires
directive. If any version of the package will suffice just use its name. If
your code requires a minimum version add >= and then that version. For
example, these directives specify that tkinter and numpy must be
installed, with a minimum numpy version of 1.19.3: ::
[options]
...
install_requires
tkinter
numpy>=1.19.3
Use of the more complex requirements.txt Python dependency mechanism is not
recommended, as it implies more control over the Python environment than makes
sense for a FontForge plugin.
When possible you should avoid dependencies on Python packages that require compilation, either because they are written in another language or because they rely on "external" libraries. The Windows version of FontForge has an embedded Python environment that is not capable of compiling packages, so (at least for now) Windows users will not be able to use your plugin if it has such dependencies.
The Configuration System ^^^^^^^^^^^^^^^^^^^^^^^^
The plugin API offers an optional convention for setting and storing plugin- specific parameters. It has two parts:
The initializing call to fontforge_plugin_init is passed a keyword
parameter preferences_path. This is a filesystem path that points to
an appropriate location for storing plugin data. It is recommended that
plugins either add an appropriate extension to the path (if they only
need a single file) or to create a directory of that name and store
files within it. The content should point to the same directory on every
initialization unless the name of the plugin is changed.
The parameter can be extracted from the **kw dictionary (see above)
or caught explicitly by changing the definition to
def fontforge_plugin_init(preferences_path=None, **kw):
Plugin configuration is triggered by a call to fontforge_plugin_config,
which is a function defined on the same module or object as
fontforge_plugin_init. If a plugin defines that function it will be
called when a user presses the "Configure" button in the Plugin dialog.
If fontforge_plugin_init is not defined the button will be disabled.
Beyond this API it is entirely up to the plugin to store, retrieve, and offer
configuration choices to the user. Until FontForge provides more dialog choices
the latter may be difficult without resorting to tkinter. It is also possible
to support file-based configuration and use an :py:meth:fontforge.openFilename()
dialog to ask for the file so that it can be copied into the appropriate location.