Skip to main content

Tutorial

About 3 min

Tutorial

WebCAD development library, providing core APIs for CAD drawing functionality.

Quick Start (5 Minutes)

1. Initialize the Engine

const { MainView, initCadContainer, Engine, LineEnt, message } = vjcad;

// Create MainView instance with full configuration options:
const cadView = new MainView({
    // Basic configuration
    appname: "My CAD App",              // Application name
    version: "v1.0.0",                  // Version number
    
    // Service configuration
    serviceUrl: env.serviceUrl,          // Backend service URL
    accessToken: env.accessToken,        // Access token
    accessKey: "",                       // Access key (for encrypted drawings)
    
    // UI configuration
    sidebarStyle: "none",                // "none" | "left" | "right" | "both"
    
});

// Mount to DOM container
initCadContainer("map", cadView);

// Wait for initialization to complete
await cadView.onLoad();

message.info("WebCAD initialized");

2. Create Your First Shape

// Create a line: from (0,0) to (100,100)
const line = new LineEnt([0, 0], [100, 100]);
line.setDefaults();  // Apply system default properties (must call)
Engine.addEntities(line);

// Zoom to fit all content
Engine.zoomExtents();

3. Create a Custom Command

const { CommandDefinition, CommandRegistry, PointInputOptions, 
        InputStatusEnum, getPoint, writeMessage } = vjcad;

class MyLineCommand {
    async main() {
        // Get start point
        const opt1 = new PointInputOptions("Specify start point:");
        const result1 = await getPoint(opt1);
        if (result1.status !== InputStatusEnum.OK) return;
        
        // Get end point (with rubber band line)
        const opt2 = new PointInputOptions("Specify end point:");
        opt2.useBasePoint = true;
        opt2.basePoint = result1.value;
        const result2 = await getPoint(opt2);
        if (result2.status !== InputStatusEnum.OK) return;
        
        // Create line
        const line = new LineEnt(result1.value, result2.value);
        line.setDefaults();
        Engine.addEntities(line);
        
        writeMessage("<br/>Line created");
    }
}

// Register and execute command
const cmdDef = new CommandDefinition("MYLINE", "Draw Line", MyLineCommand);
CommandRegistry.regist(cmdDef);
await Engine.editor.executerWithOp("MYLINE");

Core API Quick Reference

Common Entities

EntityCreationDescription
LineEntnew LineEnt([x1,y1], [x2,y2])Line
CircleEntnew CircleEnt([cx,cy], radius)Circle
ArcEntnew ArcEnt([cx,cy], r, startAng, endAng)Arc
PolylineEntnew PolylineEnt() + setPoints()Polyline
TextEntnew TextEnt()Single-line text
MTextEntnew MTextEnt()Multi-line text

Important: After creating an entity, you must call setDefaults() first, then set properties like color.

Input Functions

// Get point
const result = await getPoint(new PointInputOptions("Specify point:"));
if (result.status === InputStatusEnum.OK) {
    const point = result.value;  // {x, y}
}

// Get selection set
const result = await getSelections(new SelectionInputOptions("Select objects:"));
if (result.status === InputStatusEnum.OK) {
    const entities = result.value;  // Entity array
}

// Get numeric value
const result = await getReal(new RealInputOptions("Enter radius:"));
const result = await getInteger(new IntegerInputOptions("Enter number of sides:"));

Engine Core Methods

// Entity operations
Engine.addEntities(entity);           // Add entity
Engine.addEntities([ent1, ent2]);     // Add multiple
Engine.eraseEntities(entity);         // Delete entity

// View operations
Engine.zoomExtents();                 // Zoom to fit
Engine.zoomToEntities(entities);      // Zoom to specific entities
Engine.regen();                       // Refresh display
Engine.regen(true);                   // Full redraw

// Selection set
Engine.ssSetFirst([entity]);          // Set selection
Engine.ssGetFirst();                  // Get selection

// Query
Engine.getEntities();                 // Get all entities
Engine.getEntities(ent => ent.layer === "LayerA");  // Filter by condition
Engine.getEntitiesByType('LINE');     // Get by type
Engine.getLayers();                   // Get all layers

Property Settings

const line = new LineEnt([0, 0], [100, 0]);
line.setDefaults();           // Must call first

// Set properties (after setDefaults)
line.color = 1;               // Color (1=Red 2=Yellow 3=Green 4=Cyan 5=Blue 6=Magenta 7=White)
line.layer = "LayerName";     // Layer
line.lineType = "HIDDEN";     // Linetype (CONTINUOUS, HIDDEN, CENTER)
line.lineTypeScale = 1.0;     // Linetype scale

Engine.addEntities(line);

Layer Operations

// Create layer
Engine.createLayer("NewLayer", {
    color: 1,
    lineType: "CONTINUOUS",
    layerOn: true,
    isFrozen: false,
    isLocked: false
});

// Switch current layer
Engine.setCurrentLayer("LayerName");

// Layer visibility
const layer = Engine.getLayerByName("LayerName");
layer.layerOn = false;   // Turn off
layer.isFrozen = true;   // Freeze
layer.isLocked = true;   // Lock
Engine.regen(true);

Undo Operations

const undoMgr = Engine.undoManager;

// Undo/Redo
undoMgr.undo();
undoMgr.redo();

// Undo grouping (merge multiple operations into one undo step)
undoMgr.start_undoMark();
try {
    // Multiple operations...
} finally {
    undoMgr.end_undoMark();
}

Advanced Feature Index

Entity System

Commands & Interaction

Data Management

Edit Operations

Extension Development

Common Patterns

Standard Entity Creation Flow

const entity = new XxxEnt(...);  // 1. Create entity
entity.setDefaults();            // 2. Apply default properties (required)
entity.color = 1;                // 3. Set custom properties (optional)
Engine.addEntities(entity);      // 4. Add to canvas

Standard Command Class Structure

class MyCommand {
    async main() {
        Engine.undoManager.start_undoMark();
        try {
            // Command logic
        } finally {
            Engine.undoManager.end_undoMark();
            Engine.clearPreview();
        }
    }
}

Event Listening

Engine.eventManager.on(CadEvents.EntityAdded, (args) => {
    console.log('Entity added:', args.entity.type);
});

// Cancellable event
Engine.eventManager.on(CadEvents.EntityErasing, (args) => {
    if (args.entity.layer === "ProtectedLayer") {
        args.cancel = true;  // Prevent deletion
    }
});