# Tentative python object model

People seem to want a python interface. I'm not a python user myself and probably don't understand its idioms. I envision something whose top levels (the `FontForge` module and the `Font` type) will duplicate the UI of the Font window.

I anticipate supporting both old and new (python) scripts. The execute scripts dialog will allow you to chose which interpreter to apply. The command line interface will have a new argument `-script=py <filename>`

The module will be named "FontForge" and will expose the following

FontForge Module Methods
GetPrefs | Get FontForge preference items
SetPrefs | Set FontForge preference items
SavePrefs | Save FontForge preference items
LoadPrefs | Load FontForge preference items
DefaultOtherSubrs | Use FontForge's default \"othersubrs\" functions for Type1 fonts
ReadOtherSubrsFile | Read from a file, \"othersubrs\" functions for Type1 fonts
LoadEncodingFile | Load an encoding file into the list of encodings
LoadNamelist | Load a namelist into the list of namelists
LoadNamelistDir | Load a directory of namelist files into the list of namelists
LoadPlugin | Load a FontForge plugin
LoadPluginDir | Load a directory of FontForge plugin files
PreloadCidmap | Load a cidmap file
UnicodeFromName | Given a name, look it up in the namelists and find what unicode code point it maps to (returns -1 if not found)
ControlAfmLigatureOutput | Controls what ligatures get output to afm/tfm files
Version | Returns a string containing the current version of FontForge, as 20061116
Fonts | Returns a tuple of all loaded fonts

It will contain the following types:

- Font
- Glyph
- Reference
- Contour
- Point
- Spline2D
- Spline
- Hint
- HintMask
- TTInstructions
- Some method for manipulating GPOS/GSUB data which I'm not going to work out yet because I expect FontForge's implementation of these will change soon.

## FontForge Font Type

The Font object is a pointer to FontForge's font data structure. Any changes made to it will be made to those data.

Font Type Members
userdata | arbitrary user data
fontname | font name
fullname | full name
familyname | family name
weight | weight
copyright | copyright
xuid | PostScript eXtended Unique ID
fondname | Mac FOND resource name
cidregistry | CID Registry
cidordering | CID Ordering
upos | Underline Position
uwidth | Underline Width
cidversion | CID Version
strokewidth | Stroke Width
ascent | Font Ascent
descent | Font Descent
vertical_origin | Vertical Origin
uniqueid | PostScript Unique ID
cidsupplement | CID Supplement
macstyle | Mac Style Bits
design_size | Point size for which this font was designed
fontstyle_id | Font Style ID for 'size' feature
design_range_bottom | Smallest point size for which this font is acceptable
design_range_top | Largest point size for which this font is acceptable
os2_version | OS/2 table version number
os2_version | OS/2 table version number
os2_weight | OS/2 weight
os2_width | OS/2 width
os2_fstype | OS/2 fstype
hhea_linegap | hhea linegap
hhea_ascent | hhea ascent
hhea_descent | hhea descent
hhea_ascent_add | Whether the hhea_ascent field is used as is, or as an offset applied to the value FontForge thinks appropriate
hhea_descent_add | Whether the hhea_descent field is used as is, or as an offset applied to the value FontForge thinks appropriate
vhea_linegap | vhea linegap
os2_typoascent | OS/2 Typographic Ascent
os2_typodescent | OS/2 Typographic Descent
os2_typolinegap | OS/2 Typographic Linegap
os2_typoascent_add | Whether the os2_typoascent field is used as is, or as an offset applied to the value FontForge thinks appropriate
os2_typodescent_add | Whether the os2_typodescent field is used as is, or as an offset applied to the value FontForge thinks appropriate
os2_winascent | OS/2 Windows Ascent
os2_windescent | OS/2 Windows Descent
os2_winascent_add | Whether the os2_winascent field is used as is, or as an offset applied to the value FontForge thinks appropriate
os2_windescent_add | Whether the os2_windescent field is used as is, or as an offset applied to the value FontForge thinks appropriate
os2_subxsize | OS/2 Subscript XSize
os2_subxoff | OS/2 Subscript XOffset
os2_subysize | OS/2 Subscript YSize
os2_subyoff | OS/2 Subscript YOffset
os2_supxsize | OS/2 Superscript XSize
os2_supxoff | OS/2 Superscript XOffset
os2_supysize | OS/2 Superscript YSize
os2_supyoff | OS/2 Superscript YOffset
os2_strikeysize | OS/2 Strikethrough YSize
os2_strikeyoff | OS/2 Strikethrough YOffset
os2_family_class | OS/2 Family Class
os2_version | OS/2 Version Number
os2_use_typo_metrics | OS/2 Flag MS thinks is necessary to encourage people to follow the standard and use typographic metrics
os2_weight_width_slope_only | OS/2 Flag MS thinks is necessary
os2_panose | The 10 element OS/2 Panose tuple
os2_vendor | The 4 character OS/2 vendor string
changed | Flag indicating whether the font has been changed since it was loaded (read only)
new | Flag indicating whether the font is new (read only)
hasvmetrics | Flag indicating whether the font contains vertical metrics
onlybitmaps | Flag indicating whether the font contains bitmap strikes but no outlines
is_quadratic | Flag indicating whether the font contains quadratic splines (truetype) or cubic (postscript)
multilayer | Flag indicating whether the font is multilayered (type3) or not
strokedfont | Flag indicating whether the font is a stroked font or not
guide | The Contours that make up the guide layer of the font
(some mechanism to control the private dictionary)
(some mechanism to get the selection)

Font Type Methods
Pretty much all the commands in the old scripting language
FindOrMake | Passed an encoding returns the Glyph at that encoding, if there is none it will create one |
FindEncoding | Passed an encoding returns the Glyph at that encoding |
FindUnicode | Passed an unicode codepoint returns the Glyph with that code point |
FindName | Passed a glyph name returns the Glyph with that name |
... |  |

## FontForge Glyph Type

The Glyph object is a pointer to FontForge's glyph data structure. Any changes made here will be made directly to those data.

Glyph Type Members
userdata | arbitrary python user data
name | glyph name
unicode | primary unicode codepoint
width | advance width
vwidth | vertical advance width
changed | Flag indicating whether the glyph has been changed
parent | The font containing us
hhints | Horizontal PostScript Hints
vhints | Vertical PostScript Hints
color | color
tex_height | TeX Height
tex_depth | TeX Depth
tex_sub_pos | TeX Subscript position
tex_super_pos | TeX Superscript position
layer_cnt | number of layers in this glyph
instructions | TrueType instructions
counterhints | A HintMask specifying counters

Glyph Type Methods
GetLayerContours | Returns the contours in the specified layer
SetLayerContours | Sets the contours in the specified layer
GetLayerReferences | Returns the references in the specified layer
SetLayerReferences | Sets the references in the specified layer
if multilayer | methods to get/set fill/stroke color, stroke linewidth, etc.

## FontForge Contour Type

Contour objects are not pointers to FontForge's data, they are objects in their own right. If you change a contour object you will have to assign it back the glyph it came from before those changes are evident.

Contours are doubly linked lists of points. A contour may be either quadratic (for truetype fonts) or cubic (for postscript fonts). SVG supports fonts which are mixed cubic and quadratic, but FontForge does not. A point may be either on curve or off. An off-curve point is also called a control point. In a cubic contour there may be either

- Two on-curve points adjacent (in which case a line will be drawn between them)
- Two on-curve points separated by two off-curve points (in which case a cubic spline will be drawn between them)

In a quadratic contour there may be

- Two on-curve points adjacent (in which case a line will be drawn between them)
- Two on-curve points separated by one off-curve point (in which case a quadratic spline will be drawn between them)
- Two off-curve points adjacent (in which case an on-curve point will be interpolated between the two and a quadratic spline will be drawn)

This is basically the format found in truetype fonts. In is not the format used in sfd files (where interpolated points are specified directly)

Contours may be either open (a "line") or closed (a "circle"). In an open contour the first and last points are specified in the data structure (each point knows its own predecessor and successor) and more points may be added after the last. In a closed contour the first and last points will be the same; you may not add points to a closed contour, but you may cut it to make an open contour (to which you may add points).

When you create a contour it is empty.

- You may add an on-curve point to an empty contour with the Start(x,y) method.
- You may add an off-curve point to an empty quadratic contour with QuadraticAddOff(x,y).
- You may add a line to an open, non-empty contour with LineTo(x,y) (more precisely this adds an on-curve point, which usually means a line, but in a quadratic contour which currently ends in an off-curve point it could finish a quadratic spline).
- You may add a cubic spline to a cubic contour with CubicTo(cp1x,cp1y,cp2x,cp2y,x,y)
- You may add a quadratic spline to a quadratic contour with QuadraticTo(cpx,cpy,x,y)
- You may close a non-empty contour with Close()

Contour Type Members
first | First point on the contour
last | Last point on the contour (same as first for a closed contour)
is_quadratic | Whether this is an quadratic (truetype) or cubic (postscript) contour Assigning to this will change the point list as it is changed to approximate the other format
next | Next contour

Contour Type Methods
IsClosed | Returns whether a contour is closed or not
IsEmpty | Returns whether a contour contains no points
Close | Close an open contour
Cut | With no args, cut a closed contour before the first point, else cut a contour before the specified point, returns a second contour if the original was open
Start | Place an initial point on an empty contour
LineTo | Append a line to the end of an open contour
CubicTo | Append a cubic curve to the end of an open (cubic) contour
QuadraticTo | Append a quadratic curve to the end of an open (quadratic) contour
QuadraticAddOff | Append a quadratic off-curve point to the end of an open (quadratic) contour
MakeFirst | Rotate a closed contour so that the specified point is first
Merge | Removes the specified on-curve point leaving the contour otherwise intact
Simplify | Smooths a contour
Simplifies | Smooths a contour set
ReverseDirection | Reverse a closed contour so that the second point on it is the penultimate and vice versa.
IsClockwise | Determine if a contour is oriented in a clockwise direction. If the contour intersects itself the results are indeterminate.
CorrectDirections | Orient a contour set so that external contours are clockwise and internal counter clockwise.
Transform | Transform a contour by a 6 element matrix.
RemoveOverlaps | Remove overlapping areas from a contour set.
Intersects | Returns the areas where a contour set overlaps.
Exclude | Exclude the area of the argument (also a contour set) from the current contour
AddExtrema | Add Extrema to a contour
AddExtremas | Add Extrema to a contour set
Round | Round points on a contour
Rounds | Round points on a contour set
Stroke | Strokes a contour
Strokes | Strokes a contour set

## FontForge Point Type

Points are intended primarily to live in contours and not to have independent existences -- hence the next and prev fields are read only and may only be set by adding points to a contour.

Point Type Members
x | x coordinate
y | y coordinate
on_curve | whether this point lies on the curve or is a control point
index | TrueType point number
hintmask | pointer to a PostScript hint mask
next | Next point on the contour (Read only)
prev | Previous point on the contour (Read only)

Point Type Methods
Transform | Transforms the point by the transformation matrix (a 6 element tuple of reals)

## FontForge Reference Type

Reference Type Members
glyph | Glyph being refered to
matrix | A 6 element transformation matrix (at tuple of reals)
use_my_metrics | TrueType use my metrics bit
point_matching | Flag indicating whether the reference should be positioned by TrueType point mapping
match_pt_base | Match point in previous references
match_pt_ref | Match point in this reference

## FontForge Hint Type

These are objects in their own right; they are intended to be linked together to form either a horizontal or vertical hint set.

Hint Type Members
start | Location at which the hint starts This may be x or y depending on whether the hint is horizontal or vertical
width | Extent of the hint. This will be negative for ghost hints
next | Pointer to the next hint