Input and Event System

About 3 min

Input and Event System

User input interaction and event listening.

Input Functions

getPoint - Get Point

const { PointInputOptions, InputStatusEnum, getPoint, Point2D } = vjcad;

// Basic usage
const options = new PointInputOptions("Specify point position:");
const result = await getPoint(options);

if (result.status === InputStatusEnum.OK) {
    const point = result.value;  // Point2D {x, y}
    console.log(`Point: (${point.x}, ${point.y})`);
}

With rubber band line:

const opt = new PointInputOptions("Specify end point:");
opt.useBasePoint = true;      // Enable rubber band line
opt.basePoint = startPoint;   // Set base point
const result = await getPoint(opt);

Hide default rubber band line and use custom preview:

const opt = new PointInputOptions("Specify end point:");
opt.useBasePoint = true;
opt.basePoint = startPoint;
opt.hideRubberBand = true;    // Hide default rubber band line

opt.callback = (canvasPt) => {
    const worldPt = Engine.CanvasToWcs(canvasPt);
    // Create custom preview
    const preview = new LineEnt([startPoint.x, startPoint.y], [worldPt.x, worldPt.y]);
    preview.setDefaults();
    preview.color = 1;
    Engine.clearPreview();
    Engine.drawPreviewEntities([preview]);
};

const result = await getPoint(opt);
Engine.clearPreview();

With keyword options:

const opt = new PointInputOptions("Specify point [Line(L)/Circle(C)/Exit(E)]:");
opt.keywords = ["L", "C", "E"];

const result = await getPoint(opt);

switch (result.status) {
    case InputStatusEnum.OK:
        // User clicked a coordinate point
        const point = result.value;
        break;
    case InputStatusEnum.Keyword:
        // User entered a keyword
        const keyword = result.stringResult.toUpperCase();
        if (keyword === "L") { /* Handle line */ }
        else if (keyword === "C") { /* Handle circle */ }
        else if (keyword === "E") { /* Exit */ }
        break;
    case InputStatusEnum.Cancel:
        // User cancelled (ESC)
        break;
}

getSelections - Get Selection Set

const { SelectionInputOptions, InputStatusEnum, getSelections } = vjcad;

const options = new SelectionInputOptions("Select objects:");
const result = await getSelections(options);

if (result.status === InputStatusEnum.OK) {
    const entities = result.value;  // Entity array
    console.log(`Selected ${entities.length} entities`);
    
    entities.forEach((ent, i) => {
        console.log(`${i + 1}. ${ent.type} (ID: ${ent.id}, Color: ${ent.color})`);
    });
}

Features:

Supports window selection and point selection
User confirms selection by pressing Enter
Returns an entity array

getReal - Get Real Number

const { RealInputOptions, InputStatusEnum, getReal } = vjcad;

const options = new RealInputOptions("Enter circle radius:");
options.defaultValue = 30;  // Default value

const result = await getReal(options);

if (result.status === InputStatusEnum.OK) {
    const radius = result.value;
} else if (result.status === InputStatusEnum.EnterOrSpace) {
    // User pressed Enter, use default value
    const radius = options.defaultValue;
}

getInteger - Get Integer

const { IntegerInputOptions, InputStatusEnum, getInteger } = vjcad;

const options = new IntegerInputOptions("Enter polygon sides:");
options.defaultValue = 6;

const result = await getInteger(options);

if (result.status === InputStatusEnum.OK) {
    const sides = result.value;
} else if (result.status === InputStatusEnum.EnterOrSpace) {
    const sides = options.defaultValue;
}

getString - Get String

const { StringInputOptions, InputStatusEnum, getString } = vjcad;

const options = new StringInputOptions("Enter layer name:");
options.defaultValue = "NewLayer";

const result = await getString(options);

if (result.status === InputStatusEnum.OK) {
    const layerName = result.value;
}

InputStatusEnum Status

Status	Description	Common Scenario
`OK`	Input obtained successfully	User clicked/entered a valid value
`Cancel`	User cancelled	Pressed ESC
`EnterOrSpace`	User pressed Enter/Space	Use default value
`Keyword`	User entered a keyword	When `keywords` option is used

Event System

Basic Usage of CadEventManager

const { CadEventManager, CadEvents, Engine } = vjcad;

// Get event manager
const events = Engine.eventManager;
// Or: const events = CadEventManager.getInstance();

// Register listener
events.on(CadEvents.EntityAdded, (args) => {
    console.log('Entity added:', args.entity.type);
});

// Chained calls
events
    .on(CadEvents.EntityAdded, handler1)
    .on(CadEvents.EntityModified, handler2);

// One-time listener
events.once(CadEvents.DocumentOpened, (args) => {
    console.log('Document opened:', args.document.name);
});

Unsubscribe

// Method 1: save handler reference
const handler = (args) => { console.log(args); };
events.on(CadEvents.EntityAdded, handler);
events.off(CadEvents.EntityAdded, handler);

// Method 2: remove all listeners for a specific event
events.offAll(CadEvents.EntityAdded);

// Method 3: remove all listeners for all events
events.offAll();

Event Manager Methods

Method	Description
`on(event, handler)`	Register listener
`once(event, handler)`	Register one-time listener
`off(event, handler)`	Remove specific listener
`offAll(event?)`	Remove all listeners
`hasListeners(event)`	Check if listeners exist
`listenerCount(event)`	Get listener count
`suspendEvents()`	Suspend event triggering
`resumeEvents()`	Resume event triggering

Common Event Types

Entity Events

// Entity added
events.on(CadEvents.EntityAdded, (args) => {
    console.log('Entity:', args.entity);
    console.log('Document:', args.document);
});

// Batch add
events.on(CadEvents.EntitiesAdded, (args) => {
    console.log('Added count:', args.entities.length);
});

// Entity modified
events.on(CadEvents.EntityModified, (args) => {
    console.log('Modified entity:', args.entity);
});

// Entity erased
events.on(CadEvents.EntitiesErased, (args) => {
    args.entities.forEach(ent => {
        console.log('Erased:', ent.type);
    });
});

Selection Events

events.on(CadEvents.SelectionChanged, (args) => {
    const selected = Engine.ssGetFirst();
    console.log('Current selected count:', selected.length);
});

Command Events

events.on(CadEvents.CommandStarted, (args) => {
    console.log('Command started:', args.commandName);
});

events.on(CadEvents.CommandEnded, (args) => {
    console.log('Command ended:', args.commandName);
});

events.on(CadEvents.CommandCancelled, (args) => {
    console.log('Command cancelled:', args.commandName);
});

Document Events

events.on(CadEvents.DocumentOpened, (args) => {
    console.log('Document name:', args.document.name);
    console.log('File path:', args.filePath);
});

events.on(CadEvents.DocumentSaved, (args) => {
    console.log('Document saved:', args.document.name);
});

events.on(CadEvents.DocumentModified, (args) => {
    console.log('Document modified');
});

Layer Events

events.on(CadEvents.LayerAdded, (args) => {
    console.log('New layer:', args.layer.name);
});

events.on(CadEvents.CurrentLayerChanged, (args) => {
    console.log('Current layer:', args.layer.name);
});

Cancellable Events

Events ending with -ing can be cancelled.

// Prevent entity deletion
events.on(CadEvents.EntityErasing, (args) => {
    if (args.entity.layer === "ProtectedLayer") {
        args.cancel = true;
        args.cancelReason = "Entities on the protected layer cannot be deleted";
        message.info("Deletion cancelled");
    }
});

// Prevent document closing
events.on(CadEvents.DocumentClosing, (args) => {
    if (hasUnsavedChanges()) {
        args.cancel = true;
        args.cancelReason = "Please save changes first";
    }
});

// Prevent command execution
events.on(CadEvents.CommandStarting, (args) => {
    if (args.commandName === 'ERASE' && !hasPermission()) {
        args.cancel = true;
        args.cancelReason = "No permission to delete";
    }
});

List of cancellable events:

DocumentCreating / DocumentOpening / DocumentClosing / DocumentSaving
EntityAdding / EntitiesAdding / EntityErasing / EntitiesErasing
CommandStarting
LayerAdding / LayerDeleting
BlockAdding / BlockDeleting

Complete Event Type List

Document Events

Event	Description
`DocumentCreating` / `DocumentCreated`	Create document
`DocumentOpening` / `DocumentOpened`	Open document
`DocumentClosing` / `DocumentClosed`	Close document
`DocumentSaving` / `DocumentSaved`	Save document
`DocumentModified`	Document modified
`DocumentSwitched`	Switch document

Entity Events

Event	Description
`EntityAdding` / `EntityAdded`	Add entity
`EntitiesAdding` / `EntitiesAdded`	Batch add
`EntityModified`	Modify entity
`EntityErasing` / `EntityErased`	Erase entity
`EntitiesErasing` / `EntitiesErased`	Batch erase

Command Events

Event	Description
`CommandStarting` / `CommandStarted`	Command start
`CommandEnded`	Command end
`CommandCancelled`	Command cancelled

Selection Events

Event	Description
`SelectionChanged`	Selection set changed
`SelectionCleared`	Selection set cleared

Layer Events

Event	Description
`LayerAdding` / `LayerAdded`	Add layer
`LayerDeleting` / `LayerDeleted`	Delete layer
`LayerModified`	Modify layer
`CurrentLayerChanged`	Current layer changed

View Events

Event	Description
`ViewZoomed`	View zoomed
`ViewPanned`	View panned
`ViewRegenerated`	View regenerated

Block Events

Event	Description
`BlockAdding` / `BlockAdded`	Add block definition
`BlockDeleting` / `BlockDeleted`	Delete block definition
`BlockModified`	Modify block definition