fontlab.flShapeBuilder
flShapeBuilder
Parametric Element Constructor.
What Is flShapeBuilder?
Most shapes in FontLab are plain: they hold a list of contours you drew with the pen. But FontLab also has parametric elements — shapes whose contours are generated by an algorithm rather than drawn by hand. Examples include:
- Stroke elements — a centreline path that FontLab expands into two parallel outlines
- Engraving elements — the sharp-nibbed calligraphic strokes used in engraved type
- Smart-corner shapes — corners replaced by algorithmic components (ink traps, rounded corners, serifs)
- Inline / Outline effects — automatic outlines derived from the glyph shape
Each of these lives inside an flShape, but instead of just storing fixed contours, the shape has an flShapeBuilder attached to it. The builder holds the recipe — the parameters and algorithm — and regenerates the output contours whenever those parameters change.
When Do You Encounter flShapeBuilder in Scripts?
When you iterate layer.shapes in a glyph that uses parametric elements, some of those shapes will have a non-None shapeBuilder property (on flShape) or builder property (on flShapeData). You cannot edit the contours of these shapes the same way you edit plain drawn contours — they are re-generated by the builder every time. To understand or interact with a parametric element programmatically, you go through its flShapeBuilder.
Builders also appear temporarily during interactive drawing: when you are in the middle of drawing a contour with the Pen tool, FontLab uses a builder internally to manage the in-progress state. Scripts rarely need to interact with this transient builder state, but it's good to know it exists.
Reading vs Modifying
Most scripts that encounter builders just need to detect them (check if a shape has one, read its title to know the type) and then decide to skip or decompose the shape. Directly manipulating a builder's parameters from Python is an advanced operation and depends on the specific builder type. The API documented here covers the common methods available on all builder types.
Understanding Builder Feature Flags
The BuilderFeatures enum is passed as an integer to hasFeature(). Here are the commonly used values:
| Value | Name | Meaning |
|---|---|---|
1 |
CanAddNodes |
The builder accepts additional nodes (e.g., you can extend the skeleton path) |
2 |
CanClose |
The skeleton path can be closed into a loop |
4 |
CanBoolean |
The builder supports boolean combine operations |
8 |
CanUngroup |
The builder result can be ungrouped into sub-shapes |
16 |
CanMerge |
The builder can merge with adjacent shapes |
Note: these flags may be combined (bitwise OR). Check availability with the FontLab version you are targeting.
Tutorial
This tutorial walks through detecting parametric elements in a glyph, reading builder information, working with smart nodes, and understanding when to skip builder shapes in scripts.
import fontlab as fl
from fontlab import flShape
font = fl.CurrentFont()
# ----------------------------------------------------------------
# Part 1: Detecting parametric (builder) shapes
# ----------------------------------------------------------------
# When scripting any glyph, always check whether a shape has a builder
# before assuming you can edit its contours directly.
glyph = font['A']
layer = glyph.layers[0]
for shape in layer.shapes:
b = shape.shapeBuilder # None for plain drawn shapes
if b is None:
print(f"Plain contour shape — {shape.contoursCount} contours, editable directly")
else:
# This is a parametric element. Its contours are generated.
print(f"Parametric shape — builder type: '{b.title}'")
print(f" canUngroup={b.canUngroup}")
print(f" haveResult={b.haveResult}")
# ----------------------------------------------------------------
# Part 2: Identifying builder types by title
# ----------------------------------------------------------------
# The builder's 'title' property is the most reliable way to identify
# what kind of parametric element you are looking at.
for gname in font.glyphsNames[:20]: # check first 20 glyphs
g = font[gname]
for lyr in g.layers:
for sh in lyr.shapes:
b = sh.shapeBuilder
if b is not None:
print(f"{gname}/{lyr.name}: '{b.title}' element")
# ----------------------------------------------------------------
# Part 3: Checking builder capabilities before operating
# ----------------------------------------------------------------
# Before calling operations that depend on specific features, always
# check hasFeature() to avoid errors on builder types that don't support them.
shape = layer.shapes[0]
b = shape.shapeBuilder
if b is not None:
# Feature flag constants (pass as integers):
CAN_ADD_NODES = 1
CAN_CLOSE = 2
CAN_BOOLEAN = 4
print("Can add nodes:", b.hasFeature(CAN_ADD_NODES))
print("Can close path:", b.hasFeature(CAN_CLOSE))
print("Supports boolean:", b.hasFeature(CAN_BOOLEAN))
# ----------------------------------------------------------------
# Part 4: Working with smart nodes
# ----------------------------------------------------------------
# Smart nodes are special control points managed by the builder.
# They appear as diamond or square handles in the FontLab UI and
# control parameters like corner size or serif thickness.
for shape in layer.shapes:
b = shape.shapeBuilder
if b is None:
continue
smart_nodes = b.getSmartNodes()
if smart_nodes:
print(f"Builder '{b.title}' has {len(smart_nodes)} smart nodes:")
for n in smart_nodes:
print(f" smart node at ({n.x:.1f}, {n.y:.1f})")
else:
print(f"Builder '{b.title}' has no smart nodes")
# ----------------------------------------------------------------
# Part 5: Applying a transform to a builder shape
# ----------------------------------------------------------------
# Parametric shapes need the transform cache prepared before any
# geometric operation, just like plain shapes.
from PythonQt.QtGui import QTransform
for shape in layer.shapes:
b = shape.shapeBuilder
if b is not None:
# Prepare, transform, reset — always in this order.
b.prepareTransformationData()
# (Apply your transform here — e.g. via shape.applyTransform())
b.resetTransformationData()
# ----------------------------------------------------------------
# Part 6: Deactivating a builder when done
# ----------------------------------------------------------------
# If you have activated a builder (e.g. by calling shape.activateBuilder()),
# deactivate it when you are finished to commit the result.
shape = layer.shapes[0]
b = shape.shapeBuilder
if b is not None and b.haveResult:
print(f"Builder '{b.title}' has a result ready.")
b.deactivate()
print("Builder deactivated — result committed to shape.")
# ----------------------------------------------------------------
# Part 7: Skipping builder shapes in a contour-editing script
# ----------------------------------------------------------------
# Most contour-editing scripts should skip parametric shapes entirely.
# Editing the output contours of a builder directly will be overwritten
# the next time the builder recomputes. Always skip or decompose first.
for shape in layer.shapes:
if shape.shapeBuilder is not None:
print(f"Skipping parametric shape: '{shape.shapeBuilder.title}'")
continue
# Safe to edit contours here — this is a plain drawn shape.
for contour in shape.getContours():
for node in contour.nodes():
pass # your per-node processing here
fl.Update()
Common Scripting Patterns
Checking whether any shape in a glyph is parametric
def has_parametric_shapes(glyph):
for layer in glyph.layers:
for shape in layer.shapes:
if shape.shapeBuilder is not None:
return True
return False
for gname in font.glyphsNames:
if has_parametric_shapes(font[gname]):
print(f"{gname} has parametric elements")
Listing all builder types used across the entire font
from collections import Counter
builder_types = Counter()
for gname in font.glyphsNames:
g = font[gname]
for layer in g.layers:
for shape in layer.shapes:
b = shape.shapeBuilder
if b is not None:
builder_types[b.title] += 1
print("Builder types in font:")
for btype, count in builder_types.most_common():
print(f" {btype}: {count} shapes")
Skipping parametric shapes when collecting all nodes
all_nodes = []
for shape in layer.shapes:
if shape.shapeBuilder is not None:
continue # don't collect nodes from parametric shapes
for contour in shape.getContours():
all_nodes.extend(contour.nodes())
print(f"Collected {len(all_nodes)} editable nodes")
Finding all shapes with smart nodes
smart_shapes = []
for shape in layer.shapes:
b = shape.shapeBuilder
if b is not None and b.getSmartNodes():
smart_shapes.append(shape)
print(f"Shapes with smart nodes: {len(smart_shapes)}")
Checking if a specific builder supports boolean operations
CAN_BOOLEAN = 4
for shape in layer.shapes:
b = shape.shapeBuilder
if b is not None and b.hasFeature(CAN_BOOLEAN):
print(f"Shape with '{b.title}' supports boolean operations")
Safely applying a transform to all shapes (plain and parametric alike)
tx = QTransform().translate(0, 10) # move up 10 units
for shape in layer.shapes:
b = shape.shapeBuilder
# Use the builder's cache if it has one, otherwise use the shape's.
if b is not None:
b.prepareTransformationData()
shape.applyTransform(tx)
b.resetTransformationData()
else:
shape.prepareTransformationData()
shape.applyTransform(tx)
shape.resetTransformationData()
fl.Update()
Getting the builder title to display in a UI label
shape = layer.shapes[0]
b = shape.shapeBuilder
label = b.title if b is not None else "Plain Contour"
print(f"Selected element type: {label}")
Notes for Advanced Usage
Modifying builder parameters. The flShapeBuilder class provides the common interface shared by all builder types. Each specific builder type (Stroke, Engraving, SmartCorner, etc.) exposes additional properties and methods through its own subclass. To access those, you need to cast or obtain the builder in its specific type. The title property is the safest way to determine the subclass before casting.
Builder activation and the UI. When you call shape.activateBuilder(), FontLab enters the parametric editing mode for that element, as if you had double-clicked it in the UI. This changes the active tool and the edit state. If you activate a builder from a script running in the background, you may see unexpected UI changes. In batch scripts, prefer reading builder data (title, getSmartNodes, etc.) without activating.
Decomposing parametric elements. If you need editable flat contours from a parametric shape, call shape.decomposite(). This bakes the current builder output into static contours and removes the builder. The operation is destructive and cannot be undone programmatically — the shape will no longer update parametrically after decomposition.
Constructors: flShapeBuilder() flShapeBuilder(flShapeBuilder) flShapeBuilder(flObject)
Native bases: object
Captured native MRO: flShapeBuilder, object
Native new allocation evidence (not an init overload): (args, *kwargs) Create and return a new object. See help(type) for accurate signature.
Supplemental documentation:
Shape builder. The captured declaration exposes deactivate, getSmartNodes, hasFeature, init, prepareTransformationData, resetTransformationData, setDestShape, setDestShapeData, setOwnerLayer, setOwnerShapeData, canUngroup, haveResult and title. It is created with no captured constructor overloads. It also carries the shared object members changed, clone, cloneObject, getProperty, setProperty, release, remove and update and the shared attributes id, name, type, isValid and isNull.
Source: FontLab Proteus API documentation
Source: generated/fontlab.py: flShapeBuilder captured declaration
Complete member index
Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.
| Member | Kind | Signature | Summary |
|---|---|---|---|
__init__ |
function | (self, /, *args: Any, **kwargs: Any) -> None |
Initialize self. (shared captured text) |
canUngroup |
attribute | Any |
True if this builder's result can be ungrouped — dissolved into its individual constituent shapes. |
changed |
function | (self) -> Any |
(shared captured text) |
checkInitHistoryState |
function | (self, history_ix: int) -> Any |
(shared captured text) |
clearAboveHistory |
function | (self, history_ix: int) -> Any |
(shared captured text) |
clearFlag |
function | (self, f: int) -> Any |
(shared captured text) |
clearFlags |
function | (self) -> Any |
(shared captured text) |
clone |
function | (self, *args: Any, **kwargs: Any) -> Any |
Clone the object (shared captured text) |
cloneObject |
function | (*args: Any, **kwargs: Any) -> Any |
(shared captured text) |
createObject |
function | (*args: Any, **kwargs: Any) -> Any |
FlObject/Nothing createObject(int); (shared captured text) |
currentHistoryState |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
deactivate |
function | (self) -> Any |
Signals that the current build operation is complete and cleans up the in-progress state. |
flObjectFlags |
attribute | dict |
(shared captured text) |
flag |
function | (self, f: int) -> Any |
(shared captured text) |
getProperties |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get object's properties list (shared captured text) |
getProperty |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get object property by 'key' or number (shared captured text) |
getPropertyFloat |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get float object property by 'key' (shared captured text) |
getPropertyInt |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get int object property by 'key' (shared captured text) |
getSmartNodes |
function | (self) -> Any |
|
hasChanges |
attribute | Any |
(shared captured text) |
hasFeature |
function | (self, BuilderFeatures: Any) -> bool |
Tests whether this builder supports a specific capability. |
hasHistoryState |
function | (self, history_ix: int) -> Any |
(shared captured text) |
hasHistoryStates |
attribute | Any |
(shared captured text) |
haveObject |
function | (*args: Any, **kwargs: Any) -> Any |
(shared captured text) |
haveResult |
attribute | Any |
True if the builder has finished computing and has a result shape ready to commit to the glyph. |
historyStates |
function | (self, accepted_state: bool) -> Any |
(shared captured text) |
id |
attribute | Any |
Object id (shared captured text) |
independedAll |
function | (self) -> Any |
(shared captured text) |
init |
function | (self) -> Any |
Resets the builder to a fresh, empty state, discarding any partially built result. |
initialHistoryState |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
instanceType |
function | (*args: Any, **kwargs: Any) -> Any |
(shared captured text) |
isChanged |
attribute | Any |
(shared captured text) |
isEqual |
function | (self, arg0: flObject) -> Any |
(shared captured text) |
isNull |
attribute | Any |
(shared captured text) |
isPresent |
attribute | Any |
(shared captured text) |
isReleased |
attribute | Any |
(shared captured text) |
isValid |
attribute | Any |
(shared captured text) |
name |
attribute | Any |
Object name (shared captured text) |
prepareTransformationData |
function | (self) -> Any |
Caches the current geometry so that interactive transformations (rotate, scale) work correctly on the builder's result shape. |
propertyNames |
function | (self, *args: Any, **kwargs: Any) -> Any |
PropertyNames(): sorted snapshot of dynamic property keys (shared captured text) |
refCnt |
attribute | Any |
Object references count (shared captured text) |
release |
function | (self) -> Any |
(shared captured text) |
remove |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
removeChild |
function | (self, arg0: flObject) -> Any |
(shared captured text) |
resetTransformationData |
function | (self) -> Any |
Discards the transform cache created by prepareTransformationData(). |
restoreHistoryState |
function | (self, history_ix: int) -> Any |
(shared captured text) |
setDestShape |
function | (self, arg0: flShape) -> Any |
Designates which flShape the builder should write its generated contours into. |
setDestShapeData |
function | (self, arg0: flShapeData) -> Any |
Like setDestShape, but targets the inner flShapeData directly rather than the full shape wrapper. |
setFlag |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
setOwnerLayer |
function | (self, arg0: flObject) -> Any |
Sets the layer that "owns" this builder — the layer in which new shapes or glyphs created by the build operation will appear. |
setOwnerShapeData |
function | (self, arg0: flObject) -> Any |
Sets the owning shape data context. |
setProperty |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set object property by 'key' or number (shared captured text) |
setPropertyFloat |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set float object property by 'key' (shared captured text) |
setPropertyInt |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set int object property by 'key' (shared captured text) |
tag |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
title |
attribute | Any |
A short human-readable label for this builder type, such as "Pen", "Stroke", "Engraving", "SmartCorner", or "Group". |
type |
attribute | Any |
Object type (shared captured text) |
update |
function | (self) -> Any |
(shared captured text) |