Skip to content

fontlab.flSnapLine

flSnapLine

Guideline snap geometry engine.

What is flSnapLine?

flSnapLine is the technical base class that powers all guideline snapping in FontLab. It holds the two geometric nodes (center and vector) that define a line's position and angle, and provides the distance and offset math that the snapping system uses to "pull" nodes toward a guide as the designer drags them.

You almost never interact with flSnapLine directly — flGuideLine inherits everything from it, so you get all of these methods and properties through your flGuideLine objects. Understanding flSnapLine is most useful when writing custom snap tools or reading the snap distance from a guideline programmatically.

Tutorial

The distanceTo and offsetTo methods are the practical core of flSnapLine for scripting. Here is how to use them to measure how far nodes are from a guideline.

from PythonQt.QtCore import QPointF
import fontlab as fl

# ============================================================
# Measure how far each node in a glyph is from a specific
# horizontal guideline. This is useful for checking whether
# your nodes are properly aligned to a metric line.
# ============================================================

font  = fl.CurrentFont()
glyph = font['H']
layer = glyph.layers[0]

# Find the cap-height guideline (if it exists):
cap_guide = next(
    (g for g in font.guidelines if 'cap' in (g.name or '').lower()
     or g.expression == '=capHeight'),
    None
)

if cap_guide is None:
    # Fall back to any horizontal guide near y=700
    cap_guide = next(
        (g for g in font.guidelines if g.isHorizontal()
         and abs(g.centerPoint.y() - 700) < 50),
        None
    )

if cap_guide is None:
    print("No cap-height guideline found.")
else:
    print(f"Cap-height guide at y={cap_guide.centerPoint.y():.0f}")
    print()
    for shape in layer.shapes:
        for contour in shape.contours:
            for node in contour.nodes():
                pt   = QPointF(node.x, node.y)
                dist = cap_guide.distanceTo(pt, 0)  # 0 = perpendicular
                if abs(dist) < 10:
                    print(f"  Node ({node.x:.0f}, {node.y:.0f}) "
                          f"is {dist:+.1f} units from cap-height guide")

# ============================================================
# Get the snap offset — the vector that moves a point exactly
# onto the guideline. Useful for implementing a snap-to-guide
# operation in a custom tool.
# ============================================================

if cap_guide:
    test_pt = QPointF(300, 695)   # slightly below cap height
    offset  = cap_guide.offsetTo(test_pt, 0)
    snapped = QPointF(test_pt.x() + offset.x(),
                         test_pt.y() + offset.y())
    print(f"\nPoint ({test_pt.x():.0f}, {test_pt.y():.0f}) "
          f"→ snapped to ({snapped.x():.0f}, {snapped.y():.0f})")

Common Scripting Patterns

Check whether an object is a snap line

import fontlab as fl
from fontlab import flSnapLine

font = fl.CurrentFont()
for gl in font.guidelines:
    print(f"'{gl.name}' is snap line: {flSnapLine.isSnapLine(gl)}")

Read snap flags from a guideline

import fontlab as fl
from fontlab import flSnaps

font = fl.CurrentFont()
for gl in font.guidelines:
    flag = gl.snapFlag(0)   # role 0 = general
    is_vert = bool(flag & flSnaps.SnapLineFlags.get("Vertical", 0))
    is_horz = bool(flag & flSnaps.SnapLineFlags.get("Horizontal", 0))
    print(f"'{gl.name}': horiz={is_horz} vert={is_vert}")

isGhost is inherited from flSnapObject and reports the actual native flag. hasExtLine describes geometry; an ordinary stem can have an independent extension node, so it does not establish a contour link. After checking for None, use extension.id, flVectorNode.isVectorNode(extension), and the concrete node's contour to inspect the existing model and owner. The getters create no replacement node or geometry and do not make contour replacement or history operations safe by themselves.

Constructors: flSnapLine() flSnapLine(flObject) flSnapLine(flSnapLine)

Native bases: object

Captured native MRO: flSnapLine, 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: Snap line. The captured declaration exposes distanceTo, offsetTo, getHashCode, isSnapLine, reset, setSnapFlag, setSnapFlagValue, snapFlag, angle, angleMode, center, centerPoint, color, constraints, expression, extLinef, extPosition, length, hasColor, hasExtLine, isHint, isZone, isPassive and isMeasurementLine. 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: flSnapLine 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)
angle attribute Any The line angle in degrees.
angleMode attribute Any Controls how the angle is constrained during interactive editing
center attribute Any The node defining the line's origin/center point
centerPoint attribute Any Center position as a plain QPointF
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)
color attribute Any Custom display color for this line
constraints attribute Any Rectangle limiting interactive movement; empty = no constraint
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)
distanceTo function (self, arg0: QPointF, mode: int) -> float Returns the signed perpendicular distance from a point to this line.
expression attribute Any Formula that drives the line's position (e.g.
extLinef attribute Any The extended line segment, if any
extPosition attribute Any An extended position value along the line's axis, used for non-H/V guides
extension attribute Any FlNode: existing extension node, or None if absent (read-only)
flObjectFlags attribute dict (shared captured text)
flag function (self, f: int) -> Any (shared captured text)
getHashCode function (self) -> Any Returns the snap hash for this specific line instance.
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)
hasChanges attribute Any (shared captured text)
hasColor attribute Any True if a custom color has been set
hasExpression attribute Any True if this line's position is driven by an expression
hasExtLine attribute Any True if an extended line segment is attached
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)
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)
initialHistoryState function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
instanceType function (*args: Any, **kwargs: Any) -> Any (shared captured text)
isAbsoluteMarkerPos attribute Any When True, measurement markers on this line use absolute coordinates
isChanged attribute Any (shared captured text)
isEqual function (self, arg0: flObject) -> Any (shared captured text)
isExluded attribute Any (shared captured text)
isGhost attribute Any Bool: actual ghost-hint flag (read-only) (shared captured text)
isHint attribute Any (shared captured text)
isInUse attribute Any (shared captured text)
isMeasurementLine attribute Any (shared captured text)
isNull attribute Any (shared captured text)
isPassive attribute Any (shared captured text)
isPresent attribute Any (shared captured text)
isReleased attribute Any (shared captured text)
isShortGuideline attribute Any True if this is a finite-length guide rather than infinite
isSnapLine function (arg0: flObject) -> bool Returns True if the given object is any kind of snap line (including guidelines).
isValid attribute Any (shared captured text)
isZone attribute Any (shared captured text)
length attribute Any Visible length in font units.
linef attribute Any The line as a Qt QLineF segment
markers attribute Any Measurement markers attached to this line
markersStructVersion attribute Any Increments when the markers list changes — use for cache invalidation
name attribute Any Object name (shared captured text)
offsetTo function (self, arg0: QPointF, mode: int) -> QPointF Returns the snap offset vector — the shortest path from the given point to the nearest position on this line.
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)
reset function (self) -> Any Clears the snap state, removing any cached snap geometry.
restoreHistoryState function (self, history_ix: int) -> Any (shared captured text)
setFlag function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
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)
setSnapFlag function (self, role: int, snapFlags: int) -> Any Sets the snap flags for a given role, replacing the current value.
setSnapFlagValue function (self, role: int, bool: Any) -> Any Enables or disables all snapping for a specific role in one call without changing individual bits.
snapFlag function (self, role: int) -> int Returns the snap flags for a given snap role.
snapFlags attribute Any (shared captured text)
style attribute Any
tag function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
type attribute Any Object type (shared captured text)
update function (self) -> Any (shared captured text)
vector attribute Any The node defining the line's direction
vectorPoint attribute Any Vector endpoint as a plain QPointF