Skip to content

fontlab.fgSymbol

fgSymbol

A single character identity record.

What is fgSymbol?

Every slot in a text string that FontLab renders in the metrics view is represented by an fgSymbol. Think of it as a small ticket that says "show me the glyph for the letter 'A' (Unicode 0x0041)." It also carries a glyph ID (the slot index in the font), a layer name (which master to use), and can hold arbitrary custom data.

You will encounter fgSymbol objects mainly when working with fgSymbolList (a complete string of characters) or through flGlyphInfo.symbol (the symbol for a rendered glyph slot in the metrics view).

Tutorial

import fontlab as fl
from fontlab import fgSymbol

# ============================================================
# Create a symbol for the letter 'A' and inspect it.
# You normally get symbols from an fgSymbolList rather than
# creating them manually, but this shows the structure.
# ============================================================

sym = fgSymbol()
sym.id = 0x0041   # set to Unicode code point for 'A'

print(f"Unicode: {hex(sym.unicode)}")   # 0x41
print(f"Name:    '{sym.name}'")
print(f"Empty:   {sym.empty}")
print(f"Has unicode: {sym.hasUnicode}")

# ============================================================
# Attach custom data to a symbol.
# DataCode is just an integer key you choose — use any number.
# This is useful for tagging symbols during batch processing.
# ============================================================

sym.setData(1, "needs-review")
print(f"Has data at code 1: {sym.containsData(1)}")
print(f"Data: {sym.data(1)}")

# Clear the data when done:
sym.clearData(1)
print(f"After clear: {sym.containsData(1)}")

# ============================================================
# Resolve a symbol within a specific font.
# Call computeID() to find out which glyph slot 'A' occupies
# in the currently open font.
# ============================================================

font = fl.CurrentFont()
sym2 = fgSymbol()
sym2.id = 0x0041   # 'A'
found = sym2.computeID(font)
if found:
    print(f"'A' is at glyph index {sym2.glyphIndex} in font '{font.info.familyName}'")
else:
    print("Glyph 'A' not found in current font")

# ============================================================
# Check if two symbols refer to the same character.
# Useful when searching a symbol list.
# ============================================================

sym3 = fgSymbol()
sym3.id = 0x0042   # 'B'

print(f"sym2 == sym2: {sym2.compare(sym2)}")  # True
print(f"sym2 == sym3: {sym2.compare(sym3)}")  # False

Common Scripting Patterns

Choose a master or location for each symbol

Master selection uses the master/layer name; fgSymbol has no master property. Repeated occurrences of the same glyph can carry different overrides.

import fontlab as fl

light = fl.fgSymbol("a")
light.setLayerOverride("Light")
instance = fl.fgSymbol("a")
instance.setLocation(fl.flLocation({"wt": 450}))
symbols = fl.fgSymbolList([light, instance])

print(symbols[0].layerName)       # Light
print(symbols[1].hasLocation)     # True
print(symbols[1].location["wt"])  # 450

# List access returns a copy: assign the edited symbol back.
symbol = symbols[0]
symbol.setLayerOverride("Bold")
symbols.set(0, symbol)

symbol = symbols[1]
symbol.clearPresentationOverride()
symbols.set(1, symbol)

location also returns a copy. To change coordinates, construct a new flLocation from a dictionary and pass it to symbol.setLocation(). Coordinates use the font's design space; axis short names such as "wt" are supported.

flGlyphInfo.symbol is a copy as well. To change a displayed occurrence, use flGlyphInfo.setActiveLayer(layer), setLocation(location), or clearPresentationOverride() on the flGlyphInfo itself.

Check if a symbol is a line break

from fontlab import fgSymbol
sym = fgSymbol()
sym.id = 0x000D   # carriage return
print("Is CR:", sym.cr)

Transfer a symbol between fonts (clear old IDs, resolve in new font)

from fontlab import fgSymbol
sym = fgSymbol()
sym.id = 0x0041

font_a = fl.CurrentFont()
sym.computeID(font_a)   # resolve in font A

# Now move to font B:
sym.clearID()           # discard font-A-specific IDs
font_b = ...            # another open font
sym.computeID(font_b)   # resolve in font B

fgSymbol.DataCode

Use the fgSymbol.DataCode dictionary with subscription.

Key Native value Description
GlyphIndex fgSymbol::GlyphIndex Native enum value.
LigatureIndex fgSymbol::LigatureIndex Native enum value.
Locked fgSymbol::Locked Native enum value.
FontSize fgSymbol::FontSize Native enum value.
PackageID fgSymbol::PackageID Native enum value.
DoLayout fgSymbol::DoLayout Native enum value.
DoFeatures fgSymbol::DoFeatures Native enum value.
Features fgSymbol::Features Native enum value.
ProteusData fgSymbol::ProteusData Native enum value.
Active fgSymbol::Active Native enum value.
ColorMark fgSymbol::ColorMark Native enum value.
UserAreaBegin fgSymbol::UserAreaBegin Native enum value.

Constructors: fgSymbol() - default fgSymbol(fgSymbol) - copy fgSymbol(unicode) fgSymbol('name') fgSymbol(id, fgFont) fgSymbol(glyph_id, package_id) fgSymbol(unicode, 'name', id)

Native bases: object

Captured native MRO: fgSymbol, 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: A glyph reference identified by unicode, name, id and pid, with the flags hasName, hasUnicode and empty. The captured declaration exposes glyph (returning a glyph for a font), computeID, compare, clear, and data, setData, containsData and clearData keyed by the DataCode attribute. Consult the retained constructor documentation for the supported creation forms. Caution: FontLab 9.0.9809 terminates when fgSymbol() is called with no arguments (Fontlab/fl#8632, open).

Source: FontLab Proteus API documentation

Source: generated/fontlab.py: fgSymbol 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
DataCode attribute dict
__init__ function (self, /, *args: Any, **kwargs: Any) -> None Initialize self. (shared captured text)
clear function (self) -> Any Resets all fields to their unset state — no Unicode, no name, no ID.
clearData function (self, DataCode: Any) -> Any Removes the custom data entry for DataCode from this symbol.
clearID function (self) -> Any Clears only the font-specific ID fields (id, pid, glyphIndex), while keeping any attached custom data.
clearPresentationOverride function (self) -> Any Clears both the named master/layer and explicit location, restoring inheritance from the current context.
compare function (self, arg0: fgSymbol) -> bool Returns True if this symbol and the given symbol identify the same character — same Unicode value or same glyph ID, depending on what is set.
computeID function (self, arg0: fgFont) -> bool Looks up this symbol's glyph name or Unicode in the given font and fills in the id, pid, and glyphIndex fields.
containsData function (self, DataCode: Any) -> bool Returns True if custom data has been stored under DataCode.
cr attribute Any True if this symbol is a carriage-return/line-break character.
data function (self, DataCode: Any) -> Any Returns the custom data stored under the given DataCode key.
empty attribute Any True if no glyph has been assigned — both unicode is zero and name is empty.
glyph function (self, arg0: fgFont, setId: bool) -> fgGlyph Returns the fgGlyph (fontgate glyph) from fgFont that this symbol identifies.
glyphIndex attribute Any The zero-based index of the glyph in the font's glyph array.
hasLocation attribute Any Whether this occurrence has an explicit location.
hasName attribute Any True if a glyph name has been explicitly assigned.
hasUnicode attribute Any True if a Unicode code point has been explicitly assigned.
id attribute Any Unsigned long
init function (self) -> Any Initialises all fields to their default values.
layerName attribute Any Requested master/layer name, e.g.
ligatureIndex attribute Any For ligature components, the index of this symbol within its ligature cluster (0-based).
location attribute Any Copy of the explicit design coordinates for this occurrence.
name attribute Any The glyph name for this symbol (e.g.
pid attribute Any Unsigned long
setData function (self, DataCode: Any, d: Any) -> Any Stores the value d under DataCode.
setLayerOverride function (self, string: Any) -> Any Selects a named master/layer for this occurrence and clears any explicit location.
setLocation function (self, arg0: flLocation) -> Any Sets explicit design coordinates for this occurrence and clears the named master/layer override.
setSterile function (self) -> Any Marks this symbol as sterile — it will be included in the text string but will not generate a visible glyph when rendered.
space attribute Any True if this symbol is a space character (Unicode space, non-breaking space, etc.).
unicode attribute Any The Unicode code point directly assigned to this symbol, or 0 if none.
unicodeEnsure attribute Any Returns the Unicode code point, computing it from the glyph name if not already stored.