Migrating from wx.lib.ogl¶
wxdiagram descends from the wx.lib.ogl that ships with wxPython. It began
as ogl2, a fork of that library created to fix OGL's drag rendering on
modern macOS, and was later renamed and packaged as a standalone canvas.
That shared lineage matters when porting: most of the working API is the same. This page separates four things:
- why pynsource could run the same code against both libraries;
- the calls that behave identically in both;
- the small set of differences that need editing;
- the wx.lib.ogl subsystems
wxdiagramdeliberately does not have.
Status (0.2.7): the compatibility gaps that mattered to pynsource — canvas attachment,
AddShape(..., addAfter),Diagram.Clear,ShowAll, stable ids, spline/arrow/constraint accessors,CircleShape, grid/snap, line labels and buffered painting — are implemented. What is still missing is listed in section 6.
1. Why pynsource could use both libraries¶
One codebase, two backends¶
For seven years pynsource ran the same GUI modules against wx.lib.ogl and
ogl2, choosing at import time:
# pynsource, 2019-2026
if PRO_EDITION:
import ogl2 as ogl
else:
import wx.lib.ogl as ogl
Everything else was written against the ogl alias: UmlCanvas, the
DividedShape subclasses, LineShapeUml, UmlShapeHandler, the region
formatting, the arrow constants and the diagrams themselves. Switching to
wxdiagram was then a one-line change:
import wxdiagram as ogl
The reason this worked is not that the libraries are identical. It is that
the classes, method names, constants and data helpers were carried over from
wx.lib.ogl on purpose, and pynsource used the part of the API that was
stable.
How much is actually shared?¶
An automated census of dir() output makes wxdiagram look like a quarter of
OGL. That number measures the size of the old library's entire surface, not
the cost of a port.
A more useful measurement is the API a real application actually calls. At
0.2.7, pynsource's canvas code calls 53 names that OGL defines and that are
present and working in both libraries — including every shape, line, region,
arrow, canvas, diagram and event-handler call it makes. Only three names it
touched are wx-only (the buffered Draw(), the arrow metafile's Rotate(),
and one OnSizingEndDragLeft base implementation). The eight wxdiagram-only
names it uses (move_to, MoveTo, route modes, OnLeftUp, …) are either new
features or replacements that remove the old workarounds.
Across the compared classes, the OGL-defined API measures (names each module
defines itself, so inherited wx.Window members are excluded):
| Measure | Value |
|---|---|
OGL-defined names in wx.lib.ogl |
304 |
OGL-defined names in wxdiagram |
223 |
| Shared | 166 |
| Shared as a share of wx | 55% |
| Shared as a share of wxdiagram | 74% |
dir() still undercounts the practical overlap, because it mixes in inherited
wx.Window machinery on one side and counts new convenience methods on the
other. ShapeCanvas, for example, is 97% shared because most of it is
wx.ScrolledWindow.
The seven real seams¶
The actual porting work in pynsource was this list, not a rewrite:
| Seam | wx.lib.ogl |
wxdiagram |
What pynsource did |
|---|---|---|---|
| Startup | OGLInitialize() |
initialize() |
renamed the call |
| Constructors | RectangleShape(w, h) |
RectangleShape(x1, y1, x2, y2) |
adjusted the few shapes it constructs directly |
| Position | centre SetX/SetY plus a Move2 monkeypatch |
move_to(left, top) and MoveTo(dc, left, top) |
kept one setpos/getpos helper |
| Fonts | setting the shape font also formatted the region | shape and regions hold fonts separately | added GetRegions()[0].SetFont(font) |
| Event handler | UmlShapeHandler |
UmlShapeHandlerOglTwo adapter |
swapped the base class and method names |
| Painting | required canvas.Draw() to blit its back buffer |
paints directly in EVT_PAINT |
deleted those calls |
| Zoom/pan | application code | built into the canvas | removed the PRO_EDITION guards |
There was also a one-off: on modern macOS, wx.lib.ogl needed pynsource's
162-line repair_ogl.py monkeypatch to draw shapes while dragging.
wxdiagram needs no equivalent.
Why the old library's surface is so much bigger¶
The missing third is not mostly everyday drawing calls. It is large legacy subsystems and accessor pairs:
DrawnShape/PseudoMetaFile/DrawOp— recording drawing operations into metafiles, with import and orientation handling;DivisionShape/DivisionControlPoint/PopupDivisionMenu— recursive subdividable containers;- the full attachment/branching model (
Attach,Detach, branching styles); - rotation;
- the old double-buffered canvas (
Draw,GetBuffer); - many
GetX/SetXpairs for state thatwxdiagrameither exposes directly or no longer stores.
A normal diagram application does not use most of that, which is why the same pynsource modules could ignore it on both backends.
2. Where the calls are the same¶
The calls in this section use the same name, arguments and return values in
wx.lib.ogl and wxdiagram 0.2.7. Where a behaviour detail differs, the note
says so. If your application is built from these, porting is mostly the
import line.
Canvas and diagram¶
| Call | Notes |
|---|---|
ShapeCanvas(parent) |
same |
canvas.SetDiagram(diagram) |
same; it now also attaches shapes and calls diagram.SetCanvas |
canvas.GetDiagram() |
same |
diagram.AddShape(shape, addAfter) |
same; see section 4 for the no-addAfter default |
diagram.GetShapeList() |
same |
diagram.FindShape(id) |
same |
diagram.DeleteAllShapes() |
same |
diagram.Clear(dc) |
same: clears the device context |
diagram.ShowAll(show) |
same |
canvas.PrepareDC(dc) |
same |
Shapes and appearance¶
| Call | Notes |
|---|---|
shape.SetPen(pen) / SetBrush(brush) |
same |
shape.SetFont(font) |
same one-argument call; wx's optional regionId is not supported |
shape.SetCanvas(canvas) / GetCanvas() |
same |
shape.SetDraggable(flag) / SetCentreResize(flag) |
same |
shape.Show(show) / IsShown() |
same |
shape.GetX() / GetY() |
same: both return the centre |
shape.GetBoundingBoxMin() / GetBoundingBoxMax() |
same |
shape.Move(dc, x, y, display=True) |
same |
shape.Delete() |
same |
RectangleShape.AddText(string) |
same |
RectangleShape.AddRegion(region) / GetRegions() |
same |
RectangleShape.FormatText(dc, text, index) |
same |
DividedShape.SetRegionSizes() |
same |
Regions and divided shapes¶
shape = ogl.DividedShape(220, 140)
header = ogl.ShapeRegion()
header.SetText("UserController")
header.SetProportions(0.0, 0.25)
header.SetFormatMode(ogl.FORMAT_CENTRE_HORIZ)
shape.AddRegion(header)
body = ogl.ShapeRegion()
body.SetText("+ get(name)\n+ post(req)")
body.SetProportions(0.0, 0.75)
body.SetFormatMode(ogl.FORMAT_NONE)
shape.AddRegion(body)
shape.SetRegionSizes()
shape.FormatText(dc, body.GetText(), 1)
ShapeRegion, ShapeTextLine, the FORMAT_* constants and the region
proportion model are shared, so UML-style class boxes port without changes.
Lines and arrows¶
line = ogl.LineShape()
line.SetCanvas(canvas)
line.SetEnds(x1, y1, x2, y2)
line.MakeLineControlPoints(2)
line.SetSpline(True)
line.AddArrow(ogl.ARROW_ARROW, ogl.ARROW_POSITION_END)
line.AddText("uses")
| Call | Notes |
|---|---|
LineShape.SetEnds(x1, y1, x2, y2) / GetEnds() |
same |
MakeLineControlPoints(n) |
same |
SetSpline(True) / IsSpline() |
same |
AddArrow(type, end, size, ...) |
same signature |
GetArrows(), AddArrowOrdered(), ClearArrow() |
same |
FindArrowHead(id), DeleteArrowHead(id), SetIgnoreOffsets() |
same |
LineShape.AddText(string) |
same; labels are drawn in wxdiagram |
ArrowHead, Constraint, ConstraintType |
API-identical |
Event handlers¶
The base class name and the drawing hooks survive, but handlers in
wxdiagram are mixin-style: the shape is the handler, so GetShape()
returns self.
class MyShape(ogl.DividedShape):
def OnDraw(self, dc):
super().OnDraw(dc)
# custom painting, identical in wx.lib.ogl and wxdiagram
| Call | Notes |
|---|---|
subclass ShapeEvtHandler |
same base class name; see the mixin note above |
shape.OnDraw(dc) / OnDrawContents(dc) |
same override points |
OnSizingEndDragLeft(pt, x, y, keys, attch) |
same signature as the call control points make |
GetShape() |
wx returns the associated shape; wxdiagram returns self because the shape is the handler |
Constants¶
FORMAT_NONE, FORMAT_CENTRE_HORIZ, FORMAT_CENTRE_VERT, the ARROW_*
family, the CONSTRAINT_* family and the CONTROL_POINT_* constants use the
same names and values.
3. Equivalent calls that did change¶
These are the calls where the name or argument list differs. This is the useful table to keep open while porting.
wx.lib.ogl |
wxdiagram |
Notes |
|---|---|---|
OGLInitialize() |
initialize() |
call once before creating shapes |
RectangleShape(w, h) |
RectangleShape(x1, y1, x2, y2) |
Block / ResizableRectangleShape for handles |
EllipseShape(w, h) |
EllipseShape(x1, y1, x2, y2) |
ConnectableEllipseShape() for resizing and ports |
CircleShape(diameter) |
CircleShape(x, y, diameter=...) |
|
TextShape(width, height) |
TextShape(x, y, text, colour, font) |
a caption, not a text box |
Shape(canvas) |
Shape(x=[], y=[]) |
|
shape.SetX(cx) / SetY(cy) |
shape.move_to(left, top) / MoveTo(dc, left, top) |
geometry is stored as x/y point lists |
shape.SetSize(w, h) on a composite |
SetSize(x, y, recursive=False) |
|
canvas.InsertShape(shape) |
canvas.InsertShape(shape, index=0) |
the old call still works |
OnLeftClick(x, y, keys, attachment) |
OnLeftUp(event) |
|
OnLeftDoubleClick(x, y, keys, att) |
OnLeftDClick(event) |
|
OnRightClick(x, y, keys, att) |
OnRightDown(event) / OnRightUp(event) |
|
OnBeginDragLeft / OnDragLeft |
no per-shape equivalent | the canvas moves the shape |
OnEndDragLeft(x, y, keys, att) |
OnEndDragLeft(event) |
no attachment argument |
handler.SetShape(shape) / GetShape() |
handler is the shape | the shape subclasses ShapeEvtHandler |
shape.Draw(dc) |
shape.draw(dc) |
lowercase |
ShapeCanvas.FindShape(x, y) |
canvas.getCurrentShape(event) |
|
canvas.Draw() |
— | paints directly in EVT_PAINT |
repairOGL() |
— | no longer needed |
ShapeCanvas(... style=wx.BORDER) |
ShapeCanvas(... style=0) |
pass wx.BORDER explicitly if wanted |
4. Same name, different behaviour¶
A few calls exist in both but do not mean quite the same thing:
Diagram.AddShape(shape)with noaddAfter.wx.lib.oglappends to the end of the shape list;wxdiagraminserts at the front. Both insert afteraddAfterwhen one is given. The same applies tocanvas.AddShape, which delegates to the diagram. If you rely on insertion order for z-order, passaddAfteror calldiagram.ChangeShapeOrder(shape, pos)afterwards.Shape.SetFont(font). In wx, setting the shape font also drives the default region's formatting. Inwxdiagramthe shape and its regions hold fonts separately, so set the region font too:shape.GetRegions()[0].SetFont(font).RectangleShapeandEllipseShapeinteractivity. In wx everyShapeis selectable and resizable. Inwxdiagramthe plain primitives are not; useBlock,ResizableRectangleShape,ConnectableEllipseShape, or add theSelectable/Resizeablemixins.TextShape. wx'sTextShape(width, height)is a text box.wxdiagram.TextShape(x, y, text, …)is a non-interactive caption.- Geometry storage.
GetX()/GetY()still return the centre, but the underlying state isshape.x/shape.ylists of extent points, not_xpos/_yposplus_width/_height. Code that pokes those internals needs rewriting. ShapeCanvasdefault style. wx useswx.BORDER;wxdiagramuses0. Pass the style explicitly if your layout depends on it.- Event handlers are mixins. In wx a
ShapeEvtHandleris a separate object associated with a shape. Inwxdiagramthe shape itself inheritsShapeEvtHandler;SetShape()andSetEventHandler()are accepted but do nothing. Put the handler methods on the shape subclass, and useGetShape()(which returnsself) if you want code that reads the same in both libraries. - Event granularity. wx distinguishes click from drag with a tolerance
and passes an
attachmentargument.wxdiagramdistinguishes down/up, ignores motion belowShapeCanvas.DRAG_TOLERANCE(3 px, the same value wx uses), and has no attachment argument.
5. What wxdiagram adds¶
These are additions, not things inherited from wx:
| Area | wxdiagram |
|---|---|
| Zoom / pan / fit | ZoomIn, ZoomOut, ZoomTo, ZoomReset, ZoomToFit, CenterOn, update_virtual_size; Ctrl+wheel, macOS pinch, drag-empty-canvas pan |
| Persistence | Diagram.Save(path) / Diagram.Load(path); versioned JSON with shapes, composites, colours, fonts, arrows and constraints |
| Connection UX | hover ports, drag-port-to-shape, join_shapes, perimeter-clipped attached edges that re-route when shapes move |
| Selection / keyboard | marquee and multi-select, Delete, Tab cycle, Ctrl+A/C/V, undo/redo, nudge, z-order |
| Grid and guides | optional grid, snap-to-grid, magnetic alignment guides |
| Edge labels | LineShape.AddText, SetLabelPosition, hit-tested label rectangles |
| Export | ShapeCanvas.ExportPng at any scale |
| Layout / routing | ApplyLayout("spring"), crossing reduction, per-edge SetRouteMode (straight, auto, avoid, curved, orthogonal) |
| Packaging | explicit imports, __all__, uv packaging, tests, CI, demos |
6. What wxdiagram still lacks¶
Small parity gaps¶
| Missing | Why it matters |
|---|---|
Text regions on the base Shape |
AddText, AddRegion, GetRegions, FormatText exist on RectangleShape, DividedShape, CompositeShape and LineShape, but not on every shape |
ShapeCanvas.FindShape(x, y) returning (shape, attachment) |
use getCurrentShape(event) instead |
GetFont, GetTextColour/SetTextColour |
font is write-only on some shapes; no text-colour accessor |
SetHighlight / IsHighlighted / Flash |
useful for search results |
SetFixedSize, SetFixedWidth/Height, SetMaintainAspectRatio |
proportional resizing must be done by the application |
SetMouseTolerance |
DRAG_TOLERANCE is a class attribute; no per-diagram setter |
WhollyContains, OGLCleanUp |
small helpers |
InsertLineControlPoint, SetCornerRadius |
line/bend and rounded-rectangle conveniences |
SHADOW_*, BRANCHING_*, OP_*, LINE_ALIGNMENT_* |
exported for name compatibility, but shadow and branching behaviour is not implemented |
Large subsystems¶
These are deliberate omissions, not accidents:
DrawnShape/PseudoMetaFile/DrawOp— record-and-replay drawing and metafile import.DivisionShape/DivisionControlPoint/PopupDivisionMenu— recursive subdividable containers with split/edit menus.- Full attachment/branching model —
Attach/Detach, branching styles, attachment ordering, attachment-aware hit-testing.wxdiagramuses ports and attached lines instead. - Rotation —
SetRotation,Rotate,GetRotation. - Shadow drawing — constants exist, no renderer.
If you need one of these, keep the corresponding wx code or open a roadmap discussion; they are not hiding behind a renamed method.
7. Per-class coverage¶
Public members from dir() (including inherited members), at 0.2.7:
| Class | wx members | wxdiagram members | shared | wx coverage |
|---|---|---|---|---|
Shape |
160 | 73 | 43 | 27% |
ShapeEvtHandler |
34 | 18 | 5 | 15% |
RectangleShape |
166 | 91 | 59 | 36% |
EllipseShape |
164 | 77 | 46 | 28% |
PolygonShape |
173 | 78 | 46 | 27% |
TextShape |
166 | 75 | 44 | 27% |
BitmapShape |
170 | 98 | 65 | 38% |
DividedShape |
168 | 101 | 63 | 38% |
LineShape |
210 | 125 | 79 | 38% |
CompositeShape |
182 | 111 | 74 | 41% |
Diagram |
24 | 22 | 15 | 62% |
ArrowHead |
15 | 15 | 15 | 100% |
Constraint |
3 | 3 | 3 | 100% |
ShapeCanvas |
464 | 535 | 449 | 97% |
Read this table as surface area, not porting effort. The data and constraint helpers are identical; the shape hierarchy is smaller because the metafile, division and attachment subsystems are gone. The calls a typical application makes are overwhelmingly in the shared 166.
8. Porting checklist¶
- Alias the import and keep the rest of the module:
import wxdiagram as ogl - Call
initialize()once at startup instead ofOGLInitialize(). - Fix constructors — rectangles, ellipses, circles and text shapes take
coordinates rather than width/height:
# before shape = ogl.RectangleShape(120, 60) # after shape = ogl.RectangleShape(0, 0, 120, 60) - Replace centre-based positioning with
move_to(left, top)(diagram coordinates) orMoveTo(dc, left, top)(inside a paint/refresh pass). Keep a singlesetpos/getposhelper rather than editing every call site. - Rename the event hooks you override:
OnLeftClick→OnLeftUp,OnLeftDoubleClick→OnLeftDClick,OnRightClick→OnRightDown/Up. Drop theattachmentargument; keepOnEndDragLeft(event). - Set region fonts explicitly after
SetFont. - Delete
canvas.Draw()andrepairOGL()calls. Painting is automatic. - Decide about interaction — if your shapes were plain
RectangleShape/EllipseShapeand relied on wx's built-in handles, switch toBlockor add theSelectable/Resizeablemixins. - Run a contract test. pynsource
keeps one at
src/tests/test_wxdiagram_contract.pythat asserts every name its canvas needs still exists. A twenty-line version of that test will catch most upgrade breaks. - Check the omissions list in section 6 before porting code that uses metafiles, divisions, rotation or the attachment model.
The intended positioning is "inspired by wx.lib.ogl, with a modernised
API" — but the API it kept is the API most applications actually use.