fontlab.flGuideLine
flGuideLine
What is a guideline?
Guidelines are the non-printing reference lines you draw across your canvas to help align things. They are the blue (or custom-colored) lines that mark cap height, x-height, descender, optical margins, stem axes, and any other alignment target you care about.
FontLab has two scopes of guidelines:
-
Font-level guidelines live in
flPackage.guidelines. They appear in every glyph you open — they are global to the whole font. These are perfect for metrics references like ascender, cap height, x-height, descender, and baseline, because those values are relevant to every glyph. -
Glyph-level guidelines live in
flLayer.guidelines. They only appear when that specific glyph (and layer) is open in the editor. Use these for glyph-specific construction lines, like the exact center of a capital O, or the shoulder angle on a lowercase n.
Beyond simple horizontal and vertical lines, guidelines can be:
- Angled — any angle in degrees. Useful for italic slant guides or diagonal construction lines.
- Expression-based — a guideline whose position is tied to a font metric by a formula, like
"=xHeight". If you change xHeight, the guideline moves with it automatically. - Power guides — guidelines that FontLab auto-generates from the extremes of your outlines. They snap to the tops, bottoms, and sides of your contours, making it easy to align multiple glyphs to common optical heights.
What is flSnapLine?
flSnapLine is the technical base class that handles all the snap and measurement geometry — the center node, the vector node, the snap flags, and the distance/offset math. You rarely need to interact with flSnapLine directly; flGuideLine inherits everything from it and adds the extra features (color, tags, style, expressions) that you'll actually use. Think of flSnapLine as the engine and flGuideLine as the car.
Tutorial
from PythonQt.QtCore import QPointF
from PythonQt.QtGui import QColor
import fontlab as fl
from fontlab import flGuideLine
font = fl.CurrentFont()
glyph = font['H']
layer = glyph.layers[0]
# ============================================================
# 1. Font-level (global) guidelines
# ============================================================
# Font-level guidelines appear in every glyph. They're ideal for
# shared metrics references like cap height, ascender, x-height,
# and descender. Add them once and they show up everywhere.
# Create a horizontal guideline at y = 700 (cap height reference).
# angle=0 means horizontal; the QPointF gives the position.
h_guide = flGuideLine(0.0, QPointF(0, 700))
font.addGuideline(h_guide)
print("Font-level guidelines:", len(font.guidelines))
# Create a vertical guideline at x = 300 (a stem axis reference).
# angle=90 means vertical.
v_guide = flGuideLine(90.0, QPointF(300, 0))
font.addGuideline(v_guide)
# ============================================================
# 2. Glyph-level guidelines
# ============================================================
# Glyph-level guidelines only appear in the one glyph where you
# add them. Great for construction lines specific to that letter —
# like the shoulder angle on a lowercase 'n', or the center of a
# round letter's bowl.
# A 45° diagonal guideline through the point (100, 100):
a_guide = flGuideLine(45.0, QPointF(100, 100))
layer.appendGuidelines([a_guide])
print("Glyph-level guidelines in this layer:", len(layer.guidelines))
# ============================================================
# 3. Inspecting guidelines
# ============================================================
# Loop through all font-level guides and print their properties.
for gl in font.guidelines:
print(f" angle={gl.angle:.1f}° "
f"pos={gl.centerPoint} "
f"vertical={gl.isVertical()} "
f"horizontal={gl.isHorizontal()}")
# ============================================================
# 4. Moving a guideline with a transform
# ============================================================
# The guideline doesn't have a simple ".y = 720" setter, so you
# move it with applyTransform(). QTransform().translate(dx, dy)
# shifts it by (dx, dy) in font units.
gl = font.guidelines[0]
print("Before move:", gl.centerPoint)
from PythonQt.QtGui import QTransform
gl.applyTransform(QTransform().translate(0, 20)) # move up 20 units
print("After move:", gl.centerPoint)
# ============================================================
# 5. Coloring guidelines
# ============================================================
# You can assign any color to a guideline to help distinguish it.
# Red for construction guides, blue for metrics, green for
# opticals — whatever helps your visual system.
gl.color = QColor(220, 60, 60) # a warm red
print("Has custom color:", gl.hasColor) # True
# ============================================================
# 6. Expression-based guidelines
# ============================================================
# An expression ties the guideline's position to a font metric.
# When you update the metric (e.g. change xHeight in Font Info),
# the guideline follows automatically. The expression string starts
# with "=" followed by a metric name or arithmetic formula.
gl.expression = "=xHeight"
print("Expression:", gl.expression)
print("Position controlled by expression:", gl.hasExpression)
# You can also use arithmetic:
h_guide.expression = "=capHeight * 0.5" # midpoint of cap height
# ============================================================
# 7. Tagging guidelines for filtering
# ============================================================
# Tags let you group guides by purpose so your scripts can
# work on just a subset without touching everything.
h_guide.tags = {"metrics", "horizontal"}
v_guide.tags = {"construction"}
# Find all guides tagged "metrics":
metric_guides = [g for g in font.guidelines if "metrics" in g.tags]
print("Metric guides:", len(metric_guides))
# ============================================================
# 8. Snap geometry (distanceTo, offsetTo)
# ============================================================
# You can query how far a point is from a guideline, or get the
# snap vector that would move a point onto the guide.
# This is useful if you want to measure how far a node is
# from an alignment target.
pt = QPointF(100, 680)
dist = gl.distanceTo(pt, 0) # perpendicular distance, signed
offset = gl.offsetTo(pt, 0) # vector to snap onto the guide
print(f"Distance from point to guide: {dist:.1f} units")
print(f"Snap offset: ({offset.x():.1f}, {offset.y():.1f})")
# ============================================================
# 9. Markers on a guideline
# ============================================================
# Some guidelines carry measurement markers — tick marks that
# label distances or stem widths. If you're scripting metrics
# or stem analysis, you can read them here.
for m in gl.markers:
print(f" Marker at position={m.position}")
# ============================================================
# 10. Power guides (auto-generated from outlines)
# ============================================================
# Power guides are automatically created from the extreme points
# of your contours. They snap to the optical tops, bottoms, and
# sides of your shapes — useful for aligning multiple glyphs
# to a shared optical height.
#
# flGuideLine.createPowerGuides(font, layer,
# horizontal=True, ← capture top/bottom extremes
# vertical=True, ← capture left/right extremes
# diagonal=False) ← skip diagonal tangent points
ok = flGuideLine.createPowerGuides(font, layer,
True, True, False,
use_glyph_guides=True,
use_font_guides=True)
print("Power guides created:", ok)
print("Layer guides after power-guide generation:", len(layer.guidelines))
# ============================================================
# 11. Sorting guidelines
# ============================================================
# Sort font guidelines from bottom to top (ascending y position):
sorted_guides = flGuideLine.sortGuideLines(list(font.guidelines), True)
for g in sorted_guides:
print(f" y={g.centerPoint.y():.0f} angle={g.angle:.0f}°")
# ============================================================
# 12. Removing a guideline
# ============================================================
font.removeGuideline(v_guide)
print("Font guidelines remaining:", len(font.guidelines))
fl.Update()
Common Scripting Patterns
Set font metrics as expression guidelines
from PythonQt.QtCore import QPointF
# Create guides for the four main font metrics, tied to expressions
# so they stay correct even if you later change the values.
import fontlab as fl
from fontlab import flGuideLine
font = fl.CurrentFont()
metrics = [
("=ascender", "metrics"),
("=capHeight", "metrics"),
("=xHeight", "metrics"),
("=descender", "metrics"),
]
for expr, tag in metrics:
g = flGuideLine(0.0, QPointF(0, 0)) # position is set by expression
g.expression = expr
g.tags = {tag}
font.addGuideline(g)
fl.Update()
Remove all guidelines from a layer
# Clear every glyph-level guide from a specific layer.
# Font-level guides are untouched.
layer = fl.CurrentFont()['n'].layers[0]
layer.removeGuides(True, True) # True, True = remove all guidelines (both orientations)
fl.Update()
Color-code guidelines by type
from PythonQt.QtGui import QColor
# Walk through all font guidelines and assign colors
# based on whether they're horizontal, vertical, or diagonal.
font = fl.CurrentFont()
for g in font.guidelines:
if g.isHorizontal():
g.color = QColor(50, 100, 200) # blue for horizontal
elif g.isVertical():
g.color = QColor(200, 100, 50) # orange for vertical
else:
g.color = QColor(100, 180, 100) # green for diagonal
fl.Update()
Measure how far nodes are from a guide
from PythonQt.QtCore import QPointF
# Find all nodes that are within 5 units of the cap-height guide.
font = fl.CurrentFont()
cap_guide = next(
(g for g in font.guidelines if g.expression == "=capHeight"), None
)
if cap_guide:
glyph = font['H']
layer = glyph.layers[0]
for contour in layer.getContours():
for node in contour.nodes():
pt = QPointF(node.x, node.y)
if abs(cap_guide.distanceTo(pt, 0)) < 5:
print(f"Node at ({node.x}, {node.y}) is near cap height")
Generate power guides for every glyph in the font
# Build power guides for every glyph's first layer.
# Useful for identifying optical height variation across glyphs.
font = fl.CurrentFont()
for glyph in font.glyphs:
layer = glyph.layers[0]
flGuideLine.createPowerGuides(font, layer, True, True, False)
fl.Update()
Constructors: flGuideLine() flGuideLine(flObject) flGuideLine(flGuideLine) flGuideLine(double angle, QPointF canvas_point, uint=flSnaps::Vector, SnapObjectsStyle=gsPageGuideline) flGuideLine(QLineF line, uint=flSnaps::Vector, SnapObjectsStyle=gsPageGuideline) flGuideLine(QPointF center, QPointF vector_point, uint =flSnaps::Vector, SnapObjectsStyle=gsPageGuideline)
Native bases: object
Captured native MRO: flGuideLine, 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:
An editing guideline with angle, centerPoint and vectorPoint attributes. The captured declaration identifies centerPoint and vectorPoint as QPointF values, and linef as a QLineF. name identifies the object; color is a QColor value. Consult the retained constructors for supported line and point forms.
Source: FontLab Proteus API documentation
Source: generated/fontlab.py: flGuideLine 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 angle of the guideline in degrees. |
angleMode |
attribute | Any |
Controls how the angle snaps or is constrained during interactive editing |
applyTransform |
function | (self, arg0: QTransform) -> None |
Move, rotate, or scale the guideline using a transform matrix. |
center |
attribute | Any |
The node that defines the guideline's origin/center point. |
centerPoint |
attribute | Any |
The 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 |
A custom color for this guideline. |
constraints |
attribute | Any |
A rectangle that limits how far the guideline can be moved interactively. |
counterPaper |
function | () -> int |
Return the number of paper (font-level) guidelines currently in the font |
createInstance |
function | () -> flGuideLine |
Allocate a new guideline instance |
createObject |
function | (*args: Any, **kwargs: Any) -> Any |
FlObject/Nothing createObject(int); (shared captured text) |
createPowerGuides |
function | (arg0: fgFont, arg1: flLayer, horizontal: bool, vertical: bool, use_glyph_guides: Any=...) -> bool |
Auto-generate power guides from the extreme points of existing contours in this layer. |
currentHistoryState |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
disconnectFromContour |
function | (self) -> Any |
If this guideline was "locked" to a specific node on a contour, this breaks that connection, making the guideline free-floating again |
distanceTo |
function | (self, arg0: QPointF, mode: int) -> float |
|
expression |
attribute | Any |
An arithmetic expression that determines this guideline's position. |
extLinef |
attribute | Any |
The extended line segment, if present |
extPosition |
attribute | Any |
An extended position value. |
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 | (arg0: QPointF, angle: float) -> int |
Compute a unique hash for a given position + angle combination. |
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 guideline's position is controlled by an expression string |
hasExtLine |
attribute | Any |
True if there is an extended line segment attached (a secondary segment that extends past the main guide) |
hasHistoryState |
function | (self, history_ix: int) -> Any |
(shared captured text) |
hasHistoryStates |
attribute | Any |
(shared captured text) |
hasTags |
attribute | Any |
True if at least one tag has been assigned to this guideline |
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, any measurement markers on this guideline are positioned using absolute coordinates. |
isChanged |
attribute | Any |
(shared captured text) |
isEqual |
function | (self, arg0: flObject) -> Any |
(shared captured text) |
isExluded |
attribute | Any |
|
isGhost |
attribute | Any |
Bool: actual ghost-hint flag (read-only) |
isGuideLine |
function | (arg0: flObject) -> bool |
Check whether a generic object is actually a guideline |
isHint |
attribute | Any |
|
isHorizontal |
function | (self, a: Any=...) -> bool |
Returns True if the guideline's angle is within a degrees of horizontal (0°). |
isInUse |
attribute | Any |
|
isMeasurementLine |
attribute | Any |
|
isNull |
attribute | Any |
(shared captured text) |
isPassive |
attribute | Any |
|
isPresent |
attribute | Any |
(shared captured text) |
isReleased |
attribute | Any |
(shared captured text) |
isShortGuideline |
attribute | Any |
True if this is a bounded (short, finite-length) guideline rather than an infinite one |
isSnapLine |
function | (arg0: flObject) -> bool |
|
isValid |
attribute | Any |
(shared captured text) |
isVertical |
function | (self, a: Any=...) -> bool |
Returns True if the guideline's angle is within a degrees of vertical (90°). |
isVerticalQuarter |
attribute | Any |
True if the angle is exactly 90° or 270° — a perfectly vertical guideline. |
isZone |
attribute | Any |
|
length |
attribute | Any |
The visible length of the guideline segment in font units. |
linef |
attribute | Any |
The guideline as a Qt QLineF segment. |
markers |
attribute | Any |
A list of measurement markers attached to this guideline. |
markersStructVersion |
attribute | Any |
An integer that increments every time the markers list changes. |
name |
attribute | Any |
Object name (shared captured text) |
offsetTo |
function | (self, arg0: QPointF, mode: int) -> QPointF |
|
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 |
|
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 |
|
setSnapFlagValue |
function | (self, role: int, bool: Any) -> Any |
|
snapFlag |
function | (self, role: int) -> int |
|
snapFlags |
attribute | Any |
|
sortGuideLines |
function | (ascending: Any=...) -> Any |
Sort a list of guidelines by their position value (lowest to highest by default) |
style |
attribute | Any |
The visual style of this guideline — controls whether it draws as a standard guide, a zone boundary, a page edge, etc. |
tag |
function | (self, *args: Any, **kwargs: Any) -> Any |
(shared captured text) |
tags |
attribute | Any |
A set of string tags you can attach to this guideline for filtering. |
type |
attribute | Any |
Object type (shared captured text) |
update |
function | (self) -> Any |
(shared captured text) |
vector |
attribute | Any |
The node that defines the direction the guideline points. |
vectorPoint |
attribute | Any |
The vector endpoint as a plain QPointF |