Skip to content

fontlab.flSnapObject

flSnapObject

A snap target.

What is flSnapObject?

Every node, guideline, and metric line that can "attract" the cursor during editing is a snap object. The flSnapObject class provides the interface for querying snap distances — "how far is the cursor from this feature?" — and for controlling which snap roles (node snapping, metric snapping, guideline snapping) are active on a particular element.

Most designers will never use flSnapObject directly in scripts. It is relevant when writing custom editor tools that need to implement their own snapping logic.

Tutorial

flSnapObject is the low-level snap interface used when building custom snap logic. Most scripts don't need it — but if you are writing a tool that implements its own magnetic attraction to guidelines or metric lines, here is the pattern.

from PythonQt.QtCore import QPointF
import fontlab as fl

# ============================================================
# Use flSnapObject through flGuideLine (which inherits it)
# to measure how far the cursor is from each guideline.
# ============================================================

font     = fl.CurrentFont()
# Simulate a cursor position in glyph units:
cursor   = QPointF(303, 498)   # slightly off the x-height

if not font.guidelines:
    print("No font-level guidelines found.")
else:
    print(f"Snap distances from cursor ({cursor.x():.0f}, {cursor.y():.0f}):")
    for gl in font.guidelines:
        if not gl.isInUse:
            print(f"  '{gl.name}': disabled")
            continue
        # distanceTo returns perpendicular distance:
        dist   = gl.distanceTo(cursor, 0)
        offset = gl.offsetTo(cursor, 0)
        print(f"  '{gl.name or '(unnamed)'}' at y={gl.centerPoint.y():.0f}:  "
              f"dist={dist:+.1f}  offset=({offset.x():.1f}, {offset.y():.1f})")

    # ============================================================
    # Find the closest guideline to the cursor.
    # ============================================================
    active_guides = [g for g in font.guidelines if g.isInUse]
    if active_guides:
        closest = min(active_guides, key=lambda g: abs(g.distanceTo(cursor, 0)))
        snap_vec = closest.offsetTo(cursor, 0)
        snapped  = QPointF(cursor.x() + snap_vec.x(),
                              cursor.y() + snap_vec.y())
        print(f"\nSnapping to '{closest.name or '(unnamed)'}':")
        print(f"  Cursor ({cursor.x():.0f}, {cursor.y():.0f}) → "
              f"Snapped ({snapped.x():.0f}, {snapped.y():.0f})")

# ============================================================
# Temporarily disable snapping on a guideline.
# ============================================================

for gl in font.guidelines:
    if gl.name == "baseline":
        gl.isInUse = False
        print(f"\nDisabled snapping on 'baseline'.")
        gl.isInUse = True  # re-enable
        break

Common Scripting Patterns

Disable all guideline snapping

import fontlab as fl

font = fl.CurrentFont()
for gl in font.guidelines:
    gl.isInUse = False
print(f"Disabled snapping on {len(font.guidelines)} guideline(s).")
# Re-enable:
# for gl in font.guidelines:
#     gl.isInUse = True

Find the nearest snap target to a point

from PythonQt.QtCore import QPointF
import fontlab as fl

font   = fl.CurrentFont()
cursor = QPointF(300, 500)

snaps = [(abs(gl.distanceTo(cursor, 0)), gl)
         for gl in font.guidelines if gl.isInUse]
if snaps:
    dist, nearest = min(snaps, key=lambda x: x[0])
    print(f"Nearest snap target: '{nearest.name}'  dist={dist:.1f} units")

Inherited binding members: flObject.

Constructors: flSnapObject() flSnapObject(flObject) flSnapObject(flSnapObject)

Native bases: object

Captured native MRO: flSnapObject, 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 object. The captured declaration exposes distanceTo, offsetTo, getHashCode, reset, setSnapFlag, setSnapFlagValue, snapFlag, snapFlags, style, 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: flSnapObject 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)
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)
distanceTo function (self, arg0: QPointF, mode: int) -> float Returns the snap distance from the given point to this object.
flObjectFlags attribute dict (shared captured text)
flag function (self, f: int) -> Any (shared captured text)
getHashCode function (self) -> Any Returns a hash code uniquely identifying this snap object.
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)
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)
isChanged attribute Any (shared captured text)
isEqual function (self, arg0: flObject) -> Any (shared captured text)
isExluded attribute Any True if this object is excluded from snap calculations.
isGhost attribute Any Bool: actual ghost-hint flag (read-only)
isHint attribute Any True if this object represents an autohint stem.
isInUse attribute Any True if this snap object is participating in snap calculations.
isMeasurementLine attribute Any True if this is a measurement (ruler) line rather than a structural snap target.
isNull attribute Any (shared captured text)
isPassive attribute Any A passive snap object is a snap target (other things snap to it) but does not itself snap to others.
isPresent attribute Any (shared captured text)
isReleased attribute Any (shared captured text)
isValid attribute Any (shared captured text)
isZone attribute Any True if this object represents an alignment zone boundary.
name attribute Any Object name (shared captured text)
offsetTo function (self, arg0: QPointF, mode: int) -> QPointF Returns the vector from the given point to the nearest snap position on this object.
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 any cached snap data for this object.
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 all snap flags for role to snapFlags.
setSnapFlagValue function (self, role: int, bool: Any) -> Any Enables (True) or disables (False) all snap for a specific role in one call.
snapFlag function (self, role: int) -> int Returns the snap flags for the given role.
snapFlags attribute Any The combined snap flags bitmask.
style attribute Any The visual style used when drawing this snap indicator on screen.
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)