Block Insert Entity (InsertEnt)

InsertEnt represents an instance of a block definition, inserting a block definition into the drawing.

Overview

A block insert is a reference to a block definition (BlockDefinition) that can be reused in the drawing with different positions, rotations, and scales.

Constructor

import { InsertEnt, Engine, Point2D } from 'vjcad';

const doc = Engine.currentDoc;
const blockDef = doc.blocks.itemByName('MyBlock');

// Recommended: set properties step by step
const insert1 = new InsertEnt();
insert1.blockId = blockDef.blockId;    // Block ID (8-char GUID string, must be obtained via blockDef.blockId)
insert1.insertionPoint = [100, 100];   // Insertion point (supports array)
insert1.scaleFactor = 1;               // Scale factor
insert1.rotation = 0;                  // Rotation angle (radians)
insert1.setDefaults();

// Constructor parameter syntax
const insert2 = new InsertEnt(blockDef.blockId, [100, 100], 1, 0);
insert2.setDefaults();

Note

The blockId parameter must be the 8-char GUID string obtained from blockDef.blockId. You cannot pass a block name string directly.

Shorthand Syntax

The insertionPoint property supports [x, y] array-form coordinates.

Properties

Property	Type	Description
blockId	string	Block ID (8-char GUID string, obtained via blockDef.blockId)
insertionPoint	Point2D	Insertion point position
scaleFactor	number	Scale factor
rotation	number	Rotation angle (radians)
isReversedX	boolean	Whether X-axis is mirrored
isReversedY	boolean	Whether Y-axis is mirrored
name	string	Block name (read-only, obtained from document by blockId)

Attribute Text (Attributes)

Block inserts support attribute text, allowing different text content for each instance of the block.

addAttribute Method

insert.addAttribute({
  tag: string,           // Attribute tag (must match the attribute definition in the block definition)
  textString?: string,   // Attribute text content
  height?: number,       // Text height (important: must be explicitly specified)
  position?: Point2D,    // Position offset
  rotation?: number,     // Rotation angle
  invisible?: boolean,   // Whether hidden
  color?: number,        // Color
});

height Parameter

The height parameter of addAttribute is optional:

• Without height: Automatically uses the original height of the attribute text in the block definition (multiplied by scale factor)
• With height: Uses the specified height value

// Recommended: omit height, auto-use height from block definition
insert.addAttribute({ tag: "NAME", textString: "Part A" });

// Also valid: explicitly specify height (overrides block definition height)
insert.addAttribute({ tag: "NAME", textString: "Part A", height: 30 });

Examples

Insert a Block

import { Engine, InsertEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;

// Assume a block definition named "StandardPart" already exists
const blockDef = doc.blocks.itemByName('StandardPart');

const insert = new InsertEnt();
insert.blockId = blockDef.blockId;
insert.insertionPoint = new Point2D(100, 100);
insert.setDefaults();

Engine.addEntities(insert);

Create a Block and Insert It

import { Engine, InsertEnt, LineEnt, CircleEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;

// 1. Create block definition
const blockName = 'CrossMark';

let blockDef = doc.blocks.itemByName(blockName);
if (!blockDef) {
  blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = new Point2D(0, 0);

  // Add entities to block
  const hLine = new LineEnt(new Point2D(-10, 0), new Point2D(10, 0));
  const vLine = new LineEnt(new Point2D(0, -10), new Point2D(0, 10));
  const circle = new CircleEnt(new Point2D(0, 0), 5);
  
  hLine.setDefaults();
  vLine.setDefaults();
  circle.setDefaults();

  blockDef.addEntity(hLine);
  blockDef.addEntity(vLine);
  blockDef.addEntity(circle);
}

// 2. Insert multiple instances of the block
const positions = [
  new Point2D(50, 50),
  new Point2D(150, 50),
  new Point2D(100, 150)
];

for (const pos of positions) {
  const insert = new InsertEnt();
  insert.blockId = blockDef.blockId;
  insert.insertionPoint = pos;
  insert.setDefaults();
  Engine.addEntities(insert);
}

Insert with Different Scales and Rotations

import { Engine, InsertEnt, Point2D } from 'vjcad';

const doc = Engine.currentDoc;
const blockDef = doc.blocks.itemByName('PartA');

// Original size
const insert1 = new InsertEnt();
insert1.blockId = blockDef.blockId;
insert1.insertionPoint = new Point2D(0, 0);
insert1.setDefaults();

// Scale up 2x
const insert2 = new InsertEnt();
insert2.blockId = blockDef.blockId;
insert2.insertionPoint = new Point2D(200, 0);
insert2.scaleFactor = 2;
insert2.setDefaults();

// Rotate 45 degrees
const insert3 = new InsertEnt();
insert3.blockId = blockDef.blockId;
insert3.insertionPoint = new Point2D(0, 200);
insert3.rotation = Math.PI / 4;
insert3.setDefaults();

// Mirror on X-axis
const insert4 = new InsertEnt();
insert4.blockId = blockDef.blockId;
insert4.insertionPoint = new Point2D(200, 200);
insert4.isReversedX = true;
insert4.setDefaults();

Engine.addEntities([insert1, insert2, insert3, insert4]);

Block with Attribute Text

import { Engine, InsertEnt, LineEnt, TextEnt, TextAlignmentEnum } from 'vjcad';

const doc = Engine.currentDoc;
const blockName = 'TitleBlock';

// 1. Create a block with attribute definitions
let blockDef = doc.blocks.itemByName(blockName);
if (!blockDef) {
  blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = [0, 0];

  // Rectangular border
  const line1 = new LineEnt([0, 0], [60, 0]);
  const line2 = new LineEnt([60, 0], [60, 20]);
  const line3 = new LineEnt([60, 20], [0, 20]);
  const line4 = new LineEnt([0, 20], [0, 0]);
  [line1, line2, line3, line4].forEach(l => l.setDefaults());

  // Attribute definitions: set tag and prompt
  const attrName = new TextEnt([5, 12], "Name", 4, 0, TextAlignmentEnum.Left);
  attrName.tag = "NAME";           // Attribute tag
  attrName.prompt = "Enter name";  // Insert prompt
  attrName.setDefaults();

  const attrCode = new TextEnt([5, 4], "Code", 4, 0, TextAlignmentEnum.Left);
  attrCode.tag = "CODE";
  attrCode.prompt = "Enter code";
  attrCode.setDefaults();

  blockDef.addEntity(line1);
  blockDef.addEntity(line2);
  blockDef.addEntity(line3);
  blockDef.addEntity(line4);
  blockDef.addEntity(attrName);
  blockDef.addEntity(attrCode);
}

// 2. Insert block and set attribute values
const insert = new InsertEnt();
insert.blockId = blockDef.blockId;
insert.insertionPoint = [10, 50];
insert.setDefaults();

// Omit height, auto-use original height from block definition
insert.addAttribute({ tag: "NAME", textString: "Part A" });
insert.addAttribute({ tag: "CODE", textString: "P-001" });

Engine.addEntities(insert);

Next Steps

• Block Definition (BlockDefinition)
• Image Reference (ImageRefEnt)