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. |