Cookbook¶
Custom shape¶
Subclass RectangleShape and override draw for custom painting. Use the
same pen/brush conventions as the built-in shapes.
class Badge(wxdiagram.RectangleShape):
def draw(self, dc):
super().draw(dc)
dc.SetTextForeground(wx.RED)
dc.DrawText("NEW", int(self.x[0]) + 4, int(self.y[0]) + 4)
Use a spline edge¶
line = wxdiagram.LineShape()
line.MakeLineControlPoints(4)
line.SetEnds(0, 0, 200, 100)
line.SetSpline(True)
line.AddArrow(wxdiagram.ARROW_ARROW)
canvas.AddShape(line)
Zoom to fit¶
canvas.ZoomToFit(margin=40)
To leave decoration out of the calculation, override getContentBounds().
It returns (max_x, max_y) in diagram coordinates:
class UmlCanvas(wxdiagram.ShapeCanvas):
def getContentBounds(self):
# only class boxes matter for fit-to-window, not captions or edges
return self.box_bounds()
The scrollable area starts at getContentOrigin(), which by default is the
minimum x/y over all shapes (and composite children). That means content at
negative diagram coordinates is still reachable. Override it alongside
getContentBounds() if your canvas navigates a different region:
def getContentOrigin(self):
return self.box_origin() # (min_x, min_y)
Edge routing¶
line = canvas.join_shapes(a, b)
line.autoRoute = "auto" # straight, or curved around boxes (no right angles)
line.autoRoute = "curved" # always bow the edge (free bezier)
line.UpdateRoute() # "straight", "curved" or "orthogonal"
line.SetRouteMode("straight") # or "auto" / "avoid" / "curved" / "orthogonal"
line.GetRouteMode()
route_edge(p1, p2, obstacle_rects) (also wxdiagram.route_edge) is a pure
function: it returns control points plus the style used. A clear segment stays
straight; otherwise the edge bows into a spline, and if curves are blocked it
takes an orthogonal lane outside the obstacles. The router knows nothing about
layout - pass it the rectangles to avoid.
Parallel edges between the same two shapes are spread into separate lanes
(14 diagram units apart) automatically by LineShape.autoRoute; pass spread
to route_edge directly if you route yourself.
Edge labels¶
line = canvas.join_shapes(client, controller) # join_shapes returns the line
line.AddText("uses") # middle label
line.SetLabelPosition(0, 0, -12) # nudge it off the line
Region indices: 0 = middle, 1 = near the start, 2 = near the end.
SetLabelText(index, text) replaces the text (multi-line via \n). Labels
are stored with the shape's regions, so they save and load with the diagram.
Scrolling speed¶
canvas.WHEEL_SCROLL_PIXELS = 20 # Windows/Linux: pixels per notch
canvas.WHEEL_SCROLL_PIXELS_MACOS = 1.0 # macOS: multiplier on wxOSX deltas
canvas.WHEEL_MAX_STEP = 80 # clamp for one wheel event
macOS is special: wxOSX sets the wheel delta to 10 and forwards the precise trackpad deltas, so they are already close to pixels. Do not scale them by the notch size or trackpad scrolling becomes ~20× too fast.
Grid and alignment guides¶
canvas.showGrid = True # draw the background grid
canvas.snapToGrid = True # snap shape drags to it
canvas.diagram.SetGridSpacing(20) # diagram units (default 10)
canvas.alignmentGuides = True # magnetic edges/centres (default on)
canvas.ALIGN_TOLERANCE = 4 # screen pixels
Hit-testing and drawing only; nothing is stored in the document.
Export a PNG¶
canvas.ExportPng("diagram.png", scale=2, margin=10)
Only the shapes are rendered (no handles, guides or marquee). scale
multiplies diagram units and margin is an output-pixel border.
Buffered painting¶
Platforms that do not composite their windows can flicker while dragging. Opt into a buffered paint pass:
class MyCanvas(wxdiagram.ShapeCanvas):
bufferedPainting = True
It uses wx.AutoBufferedPaintDC and sets wx.BG_STYLE_PAINT (the canvas then
erases its own background).
Move by top-left coordinates¶
Move takes the shape centre. Layouts and saved positions usually use the
top-left corner, so use MoveTo. It also refreshes attached lines:
shape.MoveTo(dc, node.left, node.top) # dc may be None
Manage scrolling yourself¶
Applications that already own the scrollbars can switch off the library's automatic virtual size and mouse-wheel handling:
canvas.autoVirtualSize = False # don't resize scrollbars after shape changes
canvas.zoomInputEnabled = False # don't handle Ctrl+wheel / pinch / drag-pan
# ...and handle the events in your subclass:
class AppCanvas(wxdiagram.ShapeCanvas):
def OnMouseWheel(self, event):
if event.ShiftDown():
self.on_layout_wheel(event) # application-specific
return
super().OnMouseWheel(event) # Ctrl+wheel zoom, plain scrolling
Keep labels out of the way¶
TextShape is a non-interactive caption: it is not hit-tested and never
blocks selection of the shapes around it.
caption = wxdiagram.TextShape(20, 20, "Section heading", colour="GRAY")
canvas.AddShape(caption)
Selecting and editing¶
- Plain drag on empty canvas draws a marquee; Shift/Ctrl adds to the selection.
- Esc clears the selection.
- Arrow keys nudge selected shapes by 1px; Shift+Arrow nudges by 10px.
- Ctrl+D duplicates the selection, Ctrl+Z / Ctrl+Shift+Z undo/redo.
- Alt/Space/middle-drag pans. Set
canvas.emptyDragMode = canvas.EMPTY_DRAG_PANif you want plain drag to pan instead.
Undo/redo snapshots the shape list and geometry by default. Applications with a
separate model can override snapshot_state() and restore_state() to snapshot
their own state (pynsource snapshots its graph model this way).
Programmatic selection¶
canvas.select(shape) # add to the selection
canvas.getSelectedShapes() # list of selected shapes
canvas.deselect() # clear