Blocks

getBlocks returns a lightweight block list for table, sidebar, and selection UI.

When a user selects a block from that list, request index-based details or attributes without reloading the drawing.

• getBlocks returns blocksSnapshot with index, name, visible, selected, and hasAttribute.
• getBlockDetails returns blockDetailsSnapshot with details, insert data, bounds, dimensions, area, and attributes.
• getBlockAttributes returns blockAttributesSnapshot with only the selected block attributes.
• Send setBlockVisibility using all, index, indexes, name, or names.

Use getBlocks as the initial data source for a fast block list. The response intentionally does not include details.

Use the returned index when the operator clicks a row, opens a details panel, or needs attributes for one or more blocks.

• requestId is optional but recommended for matching responses to requests.
• getBlockDetails and getBlockAttributes support index and indexes only.
• If no block matches, the canvas returns an empty payload.blocks array.

Keep list and detail requests separate. This keeps block panels responsive on large drawings and avoids moving heavy geometry data until the user asks for it.

• getBlocks returns blocksSnapshot as a lightweight list only, with no details.
• getBlockDetails returns blockDetailsSnapshot with index-based details plus attributes.
• getBlockAttributes returns blockAttributesSnapshot with index-based attributes only.
• setBlockVisibility is the visibility command for all blocks or selected block indexes/names.

These examples show the intended request order: load the list first, then request detail or attributes for the selected block index.

parent.postMessage({
  type: 'getBlocks',
  payload: { requestId: 'blocks-1' }
}, '*');

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'blocksSnapshot') return;

  const payload = event.data.payload;
  console.log('Blocks list:', payload.blocks);
  renderBlockPanel(payload.blocks);
});

parent.postMessage({
  type: 'getBlockDetails',
  payload: { requestId: 'details-1', index: 12 }
}, '*');

parent.postMessage({
  type: 'getBlockDetails',
  payload: { requestId: 'details-2', indexes: [3, 4, 5] }
}, '*');

parent.postMessage({
  type: 'getBlockAttributes',
  payload: { requestId: 'attrs-1', index: 3 }
}, '*');

parent.postMessage({
  type: 'setBlockVisibility',
  payload: {
    requestId: 'blocks-hide-1',
    indexes: [4, 7],
    visible: false
  }
}, '*');

parent.postMessage({
  type: 'setBlockVisibility',
  payload: {
    requestId: 'blocks-show-all',
    all: true,
    visible: true
  }
}, '*');

The host requests the lightweight block collection, renders it in its own UI, and requests details only for selected blocks.

viewerWindow.postMessage({
  type: 'getBlocks',
  payload: { requestId: 'blocks-open' }
}, '*');

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'blocksSnapshot') return;

  console.log(event.data.payload.blocks);
});

viewerWindow.postMessage({
  type: 'getBlockDetails',
  payload: { requestId: 'details-1', index: 3 }
}, '*');

window.addEventListener('message', (event) => {
  const { type, payload } = event.data || {};

  if (type === 'blockDetailsSnapshot') {
    const block = payload.blocks[0];
    if (!block) return;

    console.log(block.details?.insert);
    console.log(block.details?.bounds?.width);
    console.log(block.details?.bounds?.height);
    console.log(block.details?.bounds?.area);
    console.log(block.attributes ?? []);
  }

  if (type === 'blockAttributesSnapshot') {
    console.log(payload.blocks[0]?.attributes);
  }
});

viewerWindow.postMessage({
  type: 'setBlockVisibility',
  payload: { requestId: 'block-toggle', name: 'DOOR_TAG', visible: false }
}, '*');

This pattern gives you a standalone block panel with lazy detail requests for selected rows.

let blocks = [];
let selectedBlockDetails = null;

window.addEventListener('message', (event) => {
  const { type, payload } = event.data || {};

  if (type === 'blocksSnapshot') {
    blocks = payload.blocks;
    renderBlocks(blocks);
  }

  if (type === 'blockDetailsSnapshot') {
    selectedBlockDetails = payload.blocks[0] || null;
    renderSelectedBlock(selectedBlockDetails);
  }

  if (type === 'blockAttributesSnapshot') {
    renderAttributes(payload.blocks[0]?.attributes || []);
  }
});

function loadBlocks() {
  viewerWindow.postMessage({
    type: 'getBlocks',
    payload: { requestId: 'blocks-init' }
  }, '*');
}

function toggleBlock(index, visible) {
  viewerWindow.postMessage({
    type: 'setBlockVisibility',
    payload: { requestId: 'block-' + index, index, visible }
  }, '*');
}

function loadBlockDetails(index) {
  if (typeof index !== 'number') return;

  viewerWindow.postMessage({
    type: 'getBlockDetails',
    payload: { requestId: 'details-' + index, index }
  }, '*');
}

function loadBlockAttributes(index) {
  if (typeof index !== 'number') return;

  viewerWindow.postMessage({
    type: 'getBlockAttributes',
    payload: { requestId: 'attrs-' + index, index }
  }, '*');
}

blocksSnapshot is intentionally small. Detail and attribute payloads are returned separately so list UIs stay fast.

blockDetailsSnapshot includes the block state, styling, insert transform, computed bounds, and attributes returned by the CAD canvas. If a request matches no blocks, payload.blocks is an empty array.

type BlocksSnapshot = {
  type: 'blocksSnapshot';
  payload: {
    requestId?: string;
    fileId?: string;
    fileIndex?: number;
    fileName?: string;
    blocks: Array<{
      index: number;
      name: string;
      visible: boolean;
      selected: boolean;
      hasAttribute: boolean;
    }>;
  };
};

type BlockDetailsSnapshot = {
  type: 'blockDetailsSnapshot';
  payload: {
    requestId?: string;
    fileId?: string;
    fileIndex?: number;
    fileName?: string;
    blocks: Array<{
      index: number;
      name: string;
      details: {
        index: number;
        name: string;
        state: number;
        defaultstate: number;
        defaultcolor: string | null;
        color: string | null;
        fillstyle: string | null;
        defaultfillstyle: string | null;
        overridecolor: boolean;
        overridefill: boolean;
        hatchstyle: string | null;
        selected: boolean;
        listed: boolean;
        insert?: {
          blockhandleLow?: number;
          blockhandleHigh?: number;
          insertX?: number;
          insertY?: number;
          insertZ?: number;
          insertRot?: number;
          insertscaleX?: number;
          insertscaleY?: number;
          insertscaleZ?: number;
          blockref?: number;
          MinX?: number;
          MinY?: number;
          MaxX?: number;
          MaxY?: number;
          type?: string;
        };
        drawn: boolean;
        mouseon: boolean;
        hasAttribute: boolean;
        fold: number;
        bounds: {
          minX: number;
          minY: number;
          maxX: number;
          maxY: number;
          width: number;
          height: number;
          area: number;
        };
      };
      attributes: Array<{
        name: string;
        value: unknown;
        blockref?: number;
      }>;
    }>;
  };
};

A blockDetailsSnapshot response wraps the requested blocks with request and active-file metadata.

• type: Always blockDetailsSnapshot for a getBlockDetails response.
• payload.requestId: Echoes the requestId supplied by the host, when provided.
• payload.fileId, payload.fileIndex, payload.fileName: Identify the active file that produced the response.
• payload.blocks: Array of matching blocks. It can be empty when no requested index exists.
• block.index, block.name: The block identifier and display name used by the viewer.
• block.details.state, defaultstate: Current and default visibility/state values from the CAD block record.
• block.details.color, defaultcolor: Current and default block colors, usually as hex strings when available.
• block.details.fillstyle, defaultfillstyle, hatchstyle: Fill and hatch styling values when the source drawing exposes them.
• block.details.overridecolor, overridefill: Whether color or fill is overridden from its default style.
• block.details.selected, listed, drawn, mouseon: Viewer/runtime flags for selection, list inclusion, draw state, and hover state.
• block.details.hasAttribute: True when the block has attribute rows.
• block.details.fold: Fold/grouping value returned by the CAD canvas.
• block.details.insert: Insert reference data, including handle values, insertion position, rotation, scale, blockref, raw extents, and value type.
• block.details.bounds: Computed block bounds in canvas coordinates, including min/max coordinates, width, height, and area.
• block.attributes: Attribute rows for the block. Each row includes name, value, and blockref when available.

Use the related pages below when you need the matching layer workflow or the full payload reference.

• Layers: Layers
• Technical Reference: API References
• CAD Overview: Overview