fontlab.flObject
flObject
What is flObject?
Everything you touch in FontLab — a node, a contour, a shape, a guideline, an anchor, a glyph, a layer, even the font itself — is an flObject under the hood. It is the common base class that every FontLab model object inherits from. Think of it as the "thing" that every object in the font universe is built on top of.
Because everything shares this base, there are a handful of universal superpowers that every object has, no matter what it is:
- An identity — every object has a unique integer
idand an optionalname. - A type tag — you can always ask
.typeto find out what kind of object you're holding. - Arbitrary metadata — you can attach your own key-value data to any object using properties.
- Boolean markers — you can tag objects with flags, perfect for "mark as processed" logic in loops.
- Validity checks — you can always ask whether an object is still alive, or has been deleted.
- History access — every object participates in FontLab's undo/redo system.
You will rarely create an flObject directly. Instead, you will always be working with its subclasses — flGlyph, flLayer, flShape, flNode, etc. But understanding flObject means you understand the shared foundation all of those build on.
The ID System
Every object in FontLab has a unique integer ID assigned when it is created. This ID is available via the .id property. IDs are stable for the lifetime of a session — if you store an object's ID at the start of a script, you can use haveObject() and createObject() to check if it still exists later, even after operations that might have shuffled things around.
IDs are particularly useful when you need to track a set of objects across multiple passes of a loop — for example, collecting node IDs in one pass and then acting on them in a second pass without worrying about the list becoming stale.
node_id = some_node.id
# ... do work that might reorganize things ...
if fl.flObject.haveObject(node_id):
print("Node still exists")
Properties: Attaching Your Own Metadata
FontLab lets you attach arbitrary key-value metadata to any object using the setProperty / getProperty family of methods. This is a lightweight way to annotate font data with information that FontLab itself doesn't track — things like the name of the designer who created a shape, a version counter, or a flag indicating that a glyph has been reviewed.
Dynamic properties hold QVariant values, including strings and numbers. They may also contain internal object links or temporary editor state. Cloning and file persistence depend on the object type and property; arbitrary properties are not guaranteed to be copied or saved. Use propertyNames() and getProperty() to inspect a snapshot before an operation.
glyph.setProperty("reviewed_by", "Maria")
glyph.setPropertyInt("revision", 3)
print(glyph.getProperty("reviewed_by")) # "Maria"
print(glyph.getPropertyInt("revision")) # 3
Flags: Quick Boolean Markers
Every object has a set of bit flags — numbered boolean markers you can set, clear, and test. These are designed for use in processing loops where you want to mark objects as "done" or "needs attention" without adding external bookkeeping.
Flags are just bits in an integer, so flag(1), flag(2), flag(4) etc. are all independent. There is no defined meaning for any particular flag number — you choose whatever convention works for your script.
for node in contour.nodes():
if needs_processing(node):
node.setFlag(1)
for node in contour.nodes():
if node.flag(1):
process(node)
node.clearFlag(1)
Tutorial
import fontlab as fl
# Obtain objects at various levels — all of them are flObject subclasses
font = fl.CurrentFont()
glyph = font['A']
layer = glyph.layers[0]
shape = layer.shapes[0]
# ── Type inspection ────────────────────────────────────────────────────────
# If you're ever unsure what you're holding, check .type
print(fl.flModel.typeToStr(shape.type)) # "Shape"
print(fl.flModel.typeToStr(layer.type)) # "Layer"
print(fl.flModel.typeToStr(glyph.type)) # "Glyph"
# ── ID system ──────────────────────────────────────────────────────────────
print(shape.id) # e.g. 4823 — unique per session
# Save the ID and verify the object still exists later
saved_id = shape.id
# ... run an operation that might delete shapes ...
if fl.flObject.haveObject(saved_id):
print("Shape survived the operation")
else:
print("Shape was removed")
# ── Naming objects ─────────────────────────────────────────────────────────
shape.name = "stem_left"
print(shape.name) # "stem_left"
# ── Properties: attach your own metadata to any object ────────────────────
# Great for scripts that need to leave notes on objects between passes
glyph.setProperty("reviewed_by", "Maria")
glyph.setPropertyInt("revision", 3)
glyph.setPropertyFloat("stem_weight", 92.5)
print(glyph.getProperty("reviewed_by")) # "Maria"
print(glyph.getPropertyInt("revision")) # 3
print(glyph.getPropertyFloat("stem_weight")) # 92.5
# List all properties currently set on an object
for key in glyph.propertyNames():
print(f" {key}: {glyph.getProperty(key)}")
# ── Flags: mark objects during processing ─────────────────────────────────
# Flag bit 1 = "needs review", flag bit 2 = "processed"
for contour in layer.getContours():
for node in contour.nodes():
if node.x < 0:
node.setFlag(1) # mark nodes left of origin
# Second pass: act on flagged nodes
for contour in layer.getContours():
for node in contour.nodes():
if node.flag(1):
node.x = 0
node.clearFlag(1) # unmark after fixing
# ── Clone: make an independent copy ───────────────────────────────────────
clone = shape.clone()
# The clone has a new unique ID; changes to it don't affect the original
clone.name = "stem_left_copy"
layer.addShape(clone)
# ── Validity checks ────────────────────────────────────────────────────────
# Always guard before using objects you didn't just create
if shape.isValid:
print("Safe to use")
if shape.isPresent:
print("Shape is still attached to its layer")
# ── Undo history ──────────────────────────────────────────────────────────
if shape.hasHistoryStates:
states = shape.historyStates(True) # committed states only
cur = shape.currentHistoryState()
init = shape.initialHistoryState()
print(f"History: {len(states)} states, current={cur}, oldest={init}")
# Undo one step programmatically (if there's a previous state)
if cur > init:
shape.restoreHistoryState(cur - 1)
# ── Mark changed and refresh UI ───────────────────────────────────────────
shape.changed()
fl.Update()
Common Patterns
Check before you use
# Whenever you store an object reference and use it later, guard with isValid
obj = get_some_object()
if obj and obj.isValid and obj.isPresent:
do_something(obj)
Tagging objects for multi-pass scripts
# Pass 1: flag objects that match your criteria
for shape in layer.shapes:
if shape.boundingBox.width() > 500:
shape.setFlag(1)
# Pass 2: operate on flagged objects
for shape in layer.shapes:
if shape.flag(1):
shape.setProperty("status", "wide")
shape.clearFlag(1)
Finding objects by ID across operations
important_ids = [s.id for s in layer.shapes if s.name.startswith("counter")]
run_some_destructive_operation()
survivors = [s for s in layer.shapes if s.id in set(important_ids)]
print(f"{len(survivors)} counter shapes survived")
Constructors: flObject() flObject(flObject) flObject(uint id)
Native bases: object
Captured native MRO: flObject, 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:
Base editing object. The captured declaration exposes identity and state attributes id, name, type, refCnt, isValid, isNull, isPresent, isReleased, isChanged and hasChanges. Captured methods cover properties (getProperty, setProperty, getProperties), flags (flag, setFlag, clearFlag), history states (historyStates, restoreHistoryState, hasHistoryState) and object lifetime (clone, release, remove, update, changed).
Source: FontLab Proteus API documentation
Source: generated/fontlab.py: flObject 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 |
Marks this object as "dirty" — it has unsaved changes. |
checkInitHistoryState |
function | (self, history_ix: int) -> Any |
Checks whether the given state index is the initial (oldest) history state. |
clearAboveHistory |
function | (self, history_ix: int) -> Any |
Removes all history states above the given index, discarding any redo states beyond that point. |
clearFlag |
function | (self, f: int) -> Any |
Clears (turns off) flag bit f. |
clearFlags |
function | (self) -> Any |
Clears all flag bits on this object at once, regardless of which ones were set. |
clone |
function | (self, *args: Any, **kwargs: Any) -> Any |
Clone the object |
cloneObject |
function | (*args: Any, **kwargs: Any) -> Any |
Creates a deep copy of the given object and returns it. |
createObject |
function | (*args: Any, **kwargs: Any) -> Any |
FlObject/Nothing createObject(int); |
currentHistoryState |
function | (self, *args: Any, **kwargs: Any) -> Any |
Returns the index of the current history state. |
flObjectFlags |
attribute | dict |
(shared captured text) |
flag |
function | (self, f: int) -> Any |
Returns True if bit flag f is currently set on this object, False otherwise. |
getProperties |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get object's properties list |
getProperty |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get object property by 'key' or number |
getPropertyFloat |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get float object property by 'key' |
getPropertyInt |
function | (self, *args: Any, **kwargs: Any) -> Any |
Get int object property by 'key' |
hasChanges |
attribute | Any |
True if this object has unsaved changes that have not yet been written to disk. |
hasHistoryState |
function | (self, history_ix: int) -> Any |
Returns True if a history state at the given index exists for this object. |
hasHistoryStates |
attribute | Any |
True if this object has at least one recorded history state. |
haveObject |
function | (*args: Any, **kwargs: Any) -> Any |
Given an object ID (an integer), returns True if an object with that ID currently exists in the font model. |
historyStates |
function | (self, accepted_state: bool) -> Any |
Returns a list of history state indices for this object. |
id |
attribute | Any |
Object id |
independedAll |
function | (self) -> Any |
Breaks all dependency links that make this object react to changes in other objects. |
initialHistoryState |
function | (self, *args: Any, **kwargs: Any) -> Any |
Returns the index of the oldest available history state — in other words, how far back you can undo. |
instanceType |
function | (*args: Any, **kwargs: Any) -> Any |
Returns the integer type identifier for this class. |
isChanged |
attribute | Any |
True if this object has been modified since the last explicit changed() call was processed. |
isEqual |
function | (self, arg0: flObject) -> Any |
Compares this object to another for deep equality. |
isNull |
attribute | Any |
True if this object handle points to nothing — the C++ pointer is null. |
isPresent |
attribute | Any |
True if this object is currently part of its parent's collection — for example, a shape that is attached to a layer. |
isReleased |
attribute | Any |
True if this object has been released and its underlying C++ resources have been freed. |
isValid |
attribute | Any |
The safest single validity check. |
name |
attribute | Any |
Object name |
propertyNames |
function | (self, *args: Any, **kwargs: Any) -> Any |
PropertyNames(): sorted snapshot of dynamic property keys |
refCnt |
attribute | Any |
Object references count |
release |
function | (self) -> Any |
Releases the internal reference this Python handle holds on the underlying C++ object. |
remove |
function | (self, *args: Any, **kwargs: Any) -> Any |
Removes this object from its parent container, or removes the given child object from this object. |
removeChild |
function | (self, arg0: flObject) -> Any |
Removes a specific child object from this object's children list. |
restoreHistoryState |
function | (self, history_ix: int) -> Any |
Rolls the object back to the history state at the given index. |
setFlag |
function | (self, *args: Any, **kwargs: Any) -> Any |
Sets flag f to True (or to the given boolean value if provided). |
setProperty |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set object property by 'key' or number |
setPropertyFloat |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set float object property by 'key' |
setPropertyInt |
function | (self, *args: Any, **kwargs: Any) -> Any |
Set int object property by 'key' |
tag |
function | (self, *args: Any, **kwargs: Any) -> Any |
Gets or sets a short string tag on the object. |
type |
attribute | Any |
Object type |
update |
function | (self) -> Any |
Signals to FontLab that this object's data has changed and the UI should reflect the latest state. |