Skip to content

fontlab.flVisualItem

flVisualItem

Base class for all canvas objects.

What is flVisualItem?

Every visible, interactive object on the canvas — shapes, text blocks, stickers, and the transform frame — is an flVisualItem. This class provides the common interface: visibility, selection state, transform, paint, and coordinate mapping between glyph space and canvas space.

In practice, you won't create flVisualItem objects directly. Instead you will call its methods on concrete subclasses like flShapeInfo or flTextBlock. Understanding flVisualItem helps you write tool code that works generically with any canvas object.

Tutorial

flVisualItem is the API for controlling visibility, selection, and on-screen appearance of canvas objects. Here is how to use it through concrete canvas items.

from PythonQt.QtCore import QPointF
import fontlab as fl

# ============================================================
# Access canvas items in the active glyph window.
# flShapeInfo, flTextBlock, and the TransformFrame are all
# flVisualItem subclasses — they share the same interface.
# ============================================================

ws     = fl.flWorkspace.instance()
canvas = ws.getActiveCanvas()
if canvas is None:
    print("Open a glyph window first.")
    raise SystemExit

gi = canvas.activeGlyphInfo()
if gi is None:
    print("No active glyph.")
    raise SystemExit

# Get all shape info objects (each is an flVisualItem):
all_contours = gi.getNearbyContours(QPointF(0, 0), 9999, "")
shapes = {id(ci.shapeInfo): ci.shapeInfo for ci in all_contours}

print(f"Canvas objects ({len(shapes)}):")
for si in shapes.values():
    print(f"  selectable={si.isSelectable()}  "
          f"on_canvas={si.haveCanvas()}  "
          f"zoom={si.itemScale():.2f}×  "
          f"bounds={si.boundingRectOnCanvas()}")

# ============================================================
# Select and deselect items.
# ============================================================

for si in shapes.values():
    si.select()     # select all shapes
fl.Update()
print("\nAll shapes selected.")

import time; time.sleep(0.5)

for si in shapes.values():
    si.unselect()   # deselect all
fl.Update()
print("All shapes deselected.")

# ============================================================
# Show/hide a shape temporarily (e.g. for a "before/after"
# comparison — not recommended for permanent edits).
# ============================================================

shape_list = list(shapes.values())
if shape_list:
    target = shape_list[0]
    target.hide()
    fl.Update()
    print(f"\nHid shape. Canvas = {target.haveCanvas()}")
    import time; time.sleep(0.5)
    target.show()
    fl.Update()
    print("Showed shape.")

# ============================================================
# Use itemScale() to draw decorators at a fixed screen size.
# A circle of radius 5 screen pixels regardless of zoom:
# ============================================================

if shape_list:
    si       = shape_list[0]
    zoom     = si.itemScale()
    # In a real paint() override: radius = 5.0 / zoom
    print(f"\nFor decorator: screen-radius 5px → glyph-radius {5.0 / zoom:.2f}fu")

Common Scripting Patterns

Check if an item is currently on the canvas

from PythonQt.QtCore import QPointF
import fontlab as fl

ws = fl.flWorkspace.instance()
gi = ws.getActiveCanvas().activeGlyphInfo() if ws.getActiveCanvas() else None
if gi:
    contours = gi.getNearbyContours(QPointF(0, 0), 9999, "")
    for ci in contours[:1]:
        si = ci.shapeInfo
        print(f"Shape on canvas: {si.haveCanvas()}")
        print(f"  Reference pt:  {si.referencePoint()}")
        print(f"  Canvas bounds: {si.boundingRectOnCanvas()}")

Force a repaint of a specific item without changing data

from PythonQt.QtCore import QPointF
import fontlab as fl

ws = fl.flWorkspace.instance()
gi = ws.getActiveCanvas().activeGlyphInfo() if ws.getActiveCanvas() else None
if gi:
    contours = gi.getNearbyContours(QPointF(0, 0), 9999, "")
    for ci in contours[:1]:
        ci.shapeInfo.preview()   # repaint without data change

flVisualItem.Listeners

Use the flVisualItem.Listeners dictionary with subscription.

Key Native value Description
HoverListener flVisualItem::Listeners::HoverListener Native enum value.
MoveListener flVisualItem::Listeners::MoveListener Native enum value.
DragListener flVisualItem::Listeners::DragListener Native enum value.
ClickListener flVisualItem::Listeners::ClickListener Native enum value.

Inherited binding members: flObject.

Constructors: flVisualItem() flVisualItem(flVisualItem) flVisualItem(flObject) flVisualItem(objId id)

Native bases: object

Captured native MRO: flVisualItem, 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: Visual item. The captured declaration exposes appendDecorator, clearDecorators, clearItems, contain, containsItem, hide, show, move, select, unselect, invselect, mapCanvasToItem, mapItemToCanvas, mapCanvasDistanceToItem, paint, canvas, opacity, visible, selected, locked and itemScale. 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: flVisualItem 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
Listeners attribute dict (shared captured text)
__init__ function (self, /, *args: Any, **kwargs: Any) -> None Initialize self. (shared captured text)
acceptEvents function (self) -> int Returns the bitmask of event types this specific item accepts.
activateEditor function (self, canvas_pos: QPointF) -> None Activates the inline editing mode at canvas_pos.
addedToCanvas function (self, arg0: flCanvas) -> None Called when this item is first added to a canvas.
adjustCanvasPosition function (self, arg0: QPointF) -> QPointF Snaps the given canvas position to the nearest valid position for this item.
adjustPosition function (self, double: Any) -> Any QPointF | double adjustPosition(QPointF | double)
appendDecorator function (self, arg0: flVisualItem, DecoratorOrder: Any) -> None Adds a decorator visual item (e.g. a highlight or label overlay) to this item.
boundingRectOnCanvas function (self, *args: Any, **kwargs: Any) -> Any QRectF boundingRectOnCanvas(
canvas function (self) -> flCanvas Returns the canvas this item lives on, or Nothing if it is not on a canvas.
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)
clearDecorators function (self) -> Any Removes all decorator items (highlight overlays, labels, etc.) that have been added to this item.
clearFlag function (self, f: int) -> Any (shared captured text)
clearFlags function (self) -> Any (shared captured text)
clearItems function (self) -> Any Removes all child items from this item's item list.
clone function (self, *args: Any, **kwargs: Any) -> Any Clone the object (shared captured text)
cloneObject function (*args: Any, **kwargs: Any) -> Any (shared captured text)
contain function (self, canvas_pos: QPointF) -> bool Returns True if the given canvas point is inside this item.
containsItem function (self, arg0: flVisualItem) -> bool Returns True if the given flVisualItem is a child of this item.
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)
deactivateEditor function (self) -> Any If this item has an active inline editor (e.g. text editing mode), deactivates it and returns to normal display mode.
distanceTo function (self, arg0: QPointF) -> float Returns the distance in canvas pixels from the given point to the nearest edge or feature of this item.
flObjectFlags attribute dict (shared captured text)
flag function (self, f: int) -> Any (shared captured text)
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)
haveCanvas function (self) -> bool Returns True if this item is currently attached to a canvas.
haveEditor function (self, canvas_pos: QPointF) -> bool Returns True if clicking at canvas_pos would activate an inline editor for this item.
haveObject function (*args: Any, **kwargs: Any) -> Any (shared captured text)
hide function (self) -> Any Makes this item invisible without removing it from the canvas.
historyStates function (self, accepted_state: bool) -> Any (shared captured text)
hovered attribute Any Whether the mouse cursor is currently over this item.
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)
instanceAcceptEvents function () -> int Returns the default event acceptance bitmask for all instances of this class.
instanceType function (*args: Any, **kwargs: Any) -> Any (shared captured text)
invselect function (self) -> Any Inverts the selection state: selects the item if it was unselected, deselects it if it was selected.
isChanged attribute Any (shared captured text)
isEqual function (self, arg0: flObject) -> Any (shared captured text)
isNull attribute Any (shared captured text)
isPresent attribute Any (shared captured text)
isReleased attribute Any (shared captured text)
isSelectable function (self) -> bool Returns True if this item can be selected by the user with a click.
isStableSelect function (self) -> bool Returns True if this item's selection state is stable across canvas refreshes (i.e. won't spontaneously deselect).
isValid attribute Any (shared captured text)
itemScale function (self) -> float Returns the canvas zoom scale as experienced by this item.
locked attribute Any If True, the item is not interactive — it won't respond to clicks or drags.
mapCanvasDistanceToItem function (self, arg0: QPointF) -> QPointF Converts a distance vector from canvas space into this item's local coordinate space.
mapCanvasToItem function (self, QRectF: Any) -> Any QPointF | QRectF mapCanvasToItem(QPointF | QRectF)
mapItemToCanvas function (self, QRectF: Any) -> Any QPointF | QRectF mapItemToCanvas(QPointF | QRectF)
metricStep function (self) -> float Returns the metric grid step this item uses for alignment and snapping.
move function (self, arg0: QPointF) -> None Moves this item on the canvas by the given offset vector (in canvas coordinates).
name attribute Any Object name (shared captured text)
opacity attribute Any The transparency of this item.
owner attribute Any The parent item in the visual hierarchy.
paint function (self, *args: Any, **kwargs: Any) -> Any Renders this item using the provided QPainter.
preview function (self) -> Any Forces a repaint of this item on the canvas without changing any model data.
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)
referencePoint function (self) -> QPointF Returns the reference point (origin or pivot) of this item in canvas coordinates.
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)
removeDecorator function (self, arg0: flVisualItem) -> None Removes a decorator that was previously added with appendDecorator.
removeItem function (self, arg0: flVisualItem) -> None Removes a child item.
removedFromCanvas function (self) -> Any Called by the engine when this item is removed from its canvas.
restoreHistoryState function (self, history_ix: int) -> Any (shared captured text)
select function (self) -> Any Selects this item.
selected attribute Any Whether this item is currently selected.
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)
show function (self) -> Any Makes this item visible.
tag function (self, *args: Any, **kwargs: Any) -> Any (shared captured text)
transform attribute Any The 2-D transform applied to this item's local coordinate system.
type attribute Any Object type (shared captured text)
unselect function (self) -> Any Deselects this item.
update function (self) -> Any (shared captured text)
visible attribute Any Whether this item is rendered on the canvas.