Skip to content

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 id and an optional name.
  • A type tag — you can always ask .type to 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.