Block Definition (BlockDefinition)

About 2 min

Block Definition (BlockDefinition)

A block definition is a collection of entities that can be reused throughout the drawing.

Overview

Blocks are an important organizational mechanism in CAD, combining multiple entities into a reusable unit. Modifying a block definition affects all insert instances that reference that block.

Creating a Block Definition

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

const doc = Engine.currentDoc;

// Create block definition (recommended: pass block name to blocks.add)
const blockDef = doc.blocks.add('StandardBolt');
blockDef.basePoint = [0, 0];  // Block base point (supports array form)

// Create entities within the block (supports [x, y] array form)
const circle = new CircleEnt([0, 0], 10);
circle.setDefaults();

const line1 = new LineEnt([-10, 0], [10, 0]);
line1.setDefaults();

const line2 = new LineEnt([0, -10], [0, 10]);
line2.setDefaults();

// Add entities to block
blockDef.addEntity(circle);
blockDef.addEntity(line1);
blockDef.addEntity(line2);

Properties

Property	Type	Description
`name`	string	Block name (unique)
`basePoint`	Point2D	Block base point (insertion reference point)
`blockId`	string	Block ID (8-char GUID string)
`items`	EntityBase[]	Entity collection within the block
`isLayout`	boolean	Whether it is a layout block
`isXref`	boolean	Whether it is an external reference

Methods

addEntity() / add() - Add Entity

const blockDef = doc.blocks.add('NewBlock');

const line = new LineEnt([0, 0], [100, 0]);  // Supports array form
line.setDefaults();

blockDef.addEntity(line);  // Recommended
// or
blockDef.add(line);        // Equivalent

remove() - Remove Entity

blockDef.remove(line);

count - Get Entity Count

console.log(`Entity count: ${blockDef.count}`);

Block Collection Management (Blocks)

import { Engine } from 'vjcad';

const doc = Engine.currentDoc;
const blocks = doc.blocks;

// Create new block (pass string name)
const blockDef = blocks.add('MyBlock');

// Check if block exists
if (blocks.has('StandardPart')) {
  console.log('Block exists');
}

// Find block by name
const myBlock = blocks.itemByName('MyBlock');

// Find block by ID
const blockById = blocks.itemById('abcdefgh');

// Get block count
console.log(`Block count: ${blocks.count}`);

// Iterate all blocks
for (const block of blocks.items) {
  console.log(`Block: ${block.name}, Entities: ${block.count}`);
}

// Get named blocks (excluding anonymous and layout blocks)
const namedBlocks = blocks.getNamedItems();

// Delete block definition
blocks.remove(blockDef);

Complete Examples

Create a Reusable Title Block

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

function createTitleBlock() {
  const doc = Engine.currentDoc;
  
  // Create block definition
  const blockDef = doc.blocks.add('A4TitleBlock');
  blockDef.basePoint = [0, 0];
  
  // Outer frame (A4: 297 x 210) - using simplified interface
  const outerFrame = new PolylineEnt();
  outerFrame.setPoints([
      [0, 0],
      [297, 0],
      [297, 210],
      [0, 210]
  ]);
  outerFrame.isClosed = true;
  outerFrame.setDefaults();
  blockDef.addEntity(outerFrame);
  
  // Inner frame (with margins)
  const innerFrame = new PolylineEnt();
  innerFrame.setPoints([
      [25, 5],
      [292, 5],
      [292, 205],
      [25, 205]
  ]);
  innerFrame.isClosed = true;
  innerFrame.setDefaults();
  blockDef.addEntity(innerFrame);
  
  // Title bar separator line
  const titleLine = new LineEnt([200, 5], [200, 45]);
  titleLine.setDefaults();
  blockDef.addEntity(titleLine);
  
  // Title text
  const titleText = new TextEnt();
  titleText.insertionPoint = [246, 25];
  titleText.text = 'Drawing Title';
  titleText.height = 5;
  titleText.textAlignment = TextAlignmentEnum.Center;
  titleText.setDefaults();
  blockDef.addEntity(titleText);
  
  return blockDef;
}

// Use the title block
const titleBlock = createTitleBlock();

const insert = new InsertEnt();
insert.blockId = titleBlock.blockId;
insert.insertionPoint = [0, 0];  // Supports array form
insert.setDefaults();

Engine.addEntities(insert);

Create Block from Selection

import { 
  Engine, 
  InsertEnt,
  Point2D,
  SelectionInputOptions,
  PointInputOptions,
  InputStatusEnum
} from 'vjcad';

async function createBlockFromSelection() {
  const doc = Engine.currentDoc;
  
  // Select entities
  const selOpt = new SelectionInputOptions('Select entities to create block:');
  const selResult = await Engine.getSelections(selOpt);
  
  if (selResult.status !== InputStatusEnum.OK || !selResult.selections?.length) {
    Engine.writeMessage('No entities selected');
    return;
  }
  
  // Get base point
  const ptOpt = new PointInputOptions('Specify base point for block:');
  const ptResult = await Engine.getPoint(ptOpt);
  
  if (ptResult.status !== InputStatusEnum.OK) {
    return;
  }
  
  const basePoint = ptResult.value as Point2D;
  
  // Create block definition
  const blockName = `Block_${Date.now()}`;
  const blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = basePoint;
  
  // Copy selected entities to block (relative to base point)
  for (const ent of selResult.selections) {
    const cloned = ent.clone();
    // Move to position relative to base point
    cloned.move(basePoint, [0, 0]);  // Supports array form
    blockDef.addEntity(cloned);
  }
  
  // Delete original entities, replace with block insert
  Engine.eraseEntities(selResult.selections);
  
  const insert = new InsertEnt();
  insert.blockId = blockDef.blockId;
  insert.insertionPoint = basePoint;  // Point2D or [x, y]
  insert.setDefaults();
  
  Engine.addEntities(insert);
  
  Engine.writeMessage(`Block created: ${blockName}`);
}

Notes

Block name uniqueness: Each block definition must have a unique name. blocks.add() with an existing name returns the existing block.
Base point selection: Choose the block's basePoint wisely to facilitate subsequent insert positioning.
Nested blocks: Blocks can contain insert instances of other blocks.
Modification propagation: Modifying a block definition affects all insert instances.