GraphView and CellState Management

Relevant source files

• packages/core/__tests__/internal/utils.test.ts
• packages/core/src/gui/MaxLog.ts
• packages/core/src/internal/utils.ts
• packages/core/src/serialization/Codec.ts
• packages/core/src/serialization/ObjectCodec.ts
• packages/core/src/view/GraphView.ts
• packages/core/src/view/layout/hierarchical/CoordinateAssignment.ts
• packages/core/src/view/other/PrintPreview.ts

This document describes the view layer responsible for rendering the graph, managing cached visual state, and coordinating the validation lifecycle. The GraphView class acts as the rendering engine that translates the logical graph structure from GraphDataModel into visual representations on screen.

For information about the underlying data model and cell hierarchy, see GraphDataModel and Cell System. For details about geometry objects and coordinate calculations, see Geometry and Positioning. For rendering specifics, see CellRenderer and Shape Creation.

GraphView Architecture

The GraphView class extends EventSource and serves as the central rendering coordinator. It maintains a cache of CellState objects, handles coordinate transformations, and manages the validation lifecycle that synchronizes the visual representation with the data model.

Sources: packages/core/src/view/GraphView.ts98-225

Core Properties

The GraphView maintains several essential properties:

Property	Type	Purpose
graph	AbstractGraph	Reference to the enclosing graph
states	Map<Cell, CellState>	Cache mapping cells to their visual states
scale	number	Current zoom level (1.0 = 100%)
translate	Point	Current pan offset
graphBounds	Rectangle	Bounding box of all visible content
currentRoot	Cell | null	Root of the displayed hierarchy (for drill-down)

Sources: packages/core/src/view/GraphView.ts163-182

DOM Pane Structure

The GraphView organizes rendering into four layered panes:

These panes provide z-ordering control, ensuring backgrounds render behind cells, which render behind overlays, which render behind decorators.

Sources: packages/core/src/view/GraphView.ts112-353

CellState: Cached Visual State

A CellState represents the computed visual properties of a cell at a specific point in time. It caches geometry, style resolution, absolute coordinates, and shape references to avoid redundant calculations during rendering.

Sources: packages/core/src/view/GraphView.ts34

Key State Properties

Each CellState contains:

• Position and size: x, y, width, height (absolute coordinates in view space)
• Computed offsets: origin, absoluteOffset (for hierarchical positioning)
• Terminal states: References to source/target CellState for edges
• Shape references: shape (the rendered shape), text (the label)
• Style: style (resolved CellStateStyle object)
• Validity flag: invalid (marks whether recomputation is needed)

Sources: Inferred from GraphView usage patterns

Validation Lifecycle

The validation lifecycle is a three-phase process that synchronizes the visual representation with the data model:

Sources: packages/core/src/view/GraphView.ts445-869

Invalidation Phase

The invalidate() method marks cells (and their descendants and connected edges) as needing recomputation. This is typically triggered by model changes.

The method sets state.invalid = true and recursively processes:

• All child cells (if recurse is true)
• All connected edges (if includeEdges is true)
• Uses cell.invalidating flag to prevent infinite loops

Sources: packages/core/src/view/GraphView.ts490-534

Validation Phase

The validate() method walks the cell hierarchy and recomputes all invalid states. It performs these steps:

1. Reset validation tracking: Clears lastNode, lastHtmlNode, etc.
2. Validate cell hierarchy: Calls validateCell() recursively
3. Update cell states: Calls validateCellState() for each cell
4. Update bounds: Computes the overall graphBounds
5. Validate background: Updates background image and page shapes

Sources: packages/core/src/view/GraphView.ts536-563

State Update Process

For each cell state being validated, updateCellState() computes:

Sources: packages/core/src/view/GraphView.ts872-946

Revalidation

The convenience method revalidate() combines invalidation and validation:

This is commonly used after scale or translate changes to refresh the entire view.

Sources: packages/core/src/view/GraphView.ts455-461

State Management

The GraphView maintains a Map<Cell, CellState> that provides efficient lookups and lifecycle management.

State Creation and Retrieval

States are created lazily through getState():

The visibility parameter controls whether a state should exist. If visible is false and a state exists, it is removed via removeState().

Sources: packages/core/src/view/GraphView.ts789-807

State Removal

The removeState() method cleans up a cell state:

1. Removes from the states map
2. Destroys the shape (removes DOM nodes)
3. Destroys the text shape
4. Removes overlays

The clear() method removes states for an entire subtree, typically used when collapsing groups or changing the current root.

Sources: packages/core/src/view/GraphView.ts470-488

Coordinate System and Transformations

The GraphView applies two coordinate transformations: translate (pan) and scale (zoom). These convert from model coordinates to view (screen) coordinates.

Coordinate Transformation Formula

For a cell with geometry position (gx, gy):

viewX = scale * (translate.x + gx)
viewY = scale * (translate.y + gy)

The inverse transformation (view to model):

modelX = (viewX / scale) - translate.x
modelY = (viewY / scale) - translate.y

Sources: packages/core/src/view/GraphView.ts928-933

Scale and Translate Management

Each transformation method fires events and triggers revalidation to update all cell states with new coordinates.

Sources: packages/core/src/view/GraphView.ts232-443

Hierarchical Positioning

For cells within a parent, the coordinate computation accounts for:

1. Parent origin: Inherited from parent state's origin
2. Child offset: From graph.getChildOffsetForCell()
3. Relative geometry: If geo.relative is true, position is a percentage of parent size
4. Geometry offset: The geo.offset point
5. Parent rotation: For rotated parents, coordinates are transformed

Sources: packages/core/src/view/GraphView.ts876-945

Edge State Management

Edge states require special handling for terminal points and routing:

Edge validation involves:

• Fixed terminal points: Connection points constrained to perimeter
• Control points: Waypoints defined in geometry
• Floating terminal points: Endpoints computed by edge style
• Edge bounds: Bounding box encompassing all points
• Label position: Default or custom label placement

Sources: packages/core/src/view/GraphView.ts972-1008

Integration with Rendering

The GraphView delegates actual shape creation and drawing to CellRenderer, but controls the rendering flow:

The stateValidated() method ensures correct z-ordering by managing DOM node insertion order based on whether cells should be kept in foreground or background.

Sources: packages/core/src/view/GraphView.ts816-1110

Background and Page Validation

The GraphView manages special rendering for background images and page boundaries:

Background Image

If graph.backgroundImage is set, the view creates an ImageShape in the backgroundPane and updates it during validation:

Sources: packages/core/src/view/GraphView.ts631-660

Page Boundaries

If graph.pageVisible is true, the view renders a page background shape with shadow effect:

The page bounds are computed from graph.pageFormat and graph.pageScale.

Sources: packages/core/src/view/GraphView.ts662-725

Usage Patterns

Responding to Model Changes

When the model changes, the typical flow is:

Sources: Inferred from GraphView design

Print Preview Integration

The PrintPreview class uses GraphView with temporary cell states to render pages:

This allows rendering the same graph at different scales without affecting the main view.

Sources: packages/core/src/view/other/PrintPreview.ts879-887

Layout Coordinate Assignment

Layout algorithms access cell states to read current positions and write new positions:

Sources: packages/core/src/view/layout/hierarchical/CoordinateAssignment.ts1024-1058

Performance Considerations

The validation system is designed for efficiency:

1. Lazy validation: States are only computed when invalid is true
2. Incremental updates: Only affected cells are invalidated
3. Cached bounds: CellState caches bounding boxes to avoid recalculation
4. Deferred rendering: Validation can occur without rendering if rendering is false

The updateStyle property can force style recalculation on every validation (default is false), which is useful during interactive style editing but expensive for normal operation.

Sources: packages/core/src/view/GraphView.ts184-189

---

This validation and state management system forms the foundation of maxGraph's rendering pipeline, efficiently translating the logical data model into a visual representation while supporting zoom, pan, and hierarchical drill-down operations.