Skip to content

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)